Skip to content

Commit 1a5cb04

Browse files
caidobotcaidobot
committed
Update SDK Documentation
1 parent 0a81019 commit 1a5cb04

12 files changed

Lines changed: 469 additions & 102 deletions

File tree

‎src/reference/sdks/backend/api.md‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,37 @@
22

33
### APISDK
44

5-
> **APISDK**\<`API`, `Events`\> = `object`
5+
> **APISDK**\<`SpecOrAPI`, `Events`\> = `object`
66
77
The SDK for the API RPC service.
88

99
#### Type Parameters
1010

1111
| Type Parameter | Default type |
1212
| ------ | ------ |
13-
| `API` | `object` |
13+
| `SpecOrAPI` | `object` |
1414
| `Events` | `object` |
1515

1616
#### Methods
1717

1818
##### register()
1919

20-
> **register**(`name`: keyof `API`, `callback`: (`sdk`: [`SDK`](index.md#sdk), ...`args`: `any`[]) => `any`): `void`
20+
> **register**\<`K`\>(`name`: `K`, `callback`: [`APICallback`](other.md#apicallback)\<[`ResolvedAPI`](other.md#resolvedapi)\<`SpecOrAPI`\>\[`K`\]\>): `void`
2121
2222
Registers a new backend function for the RPC.
2323

24+
###### Type Parameters
25+
26+
| Type Parameter |
27+
| ------ |
28+
| `K` *extends* `string` \| `number` \| `symbol` |
29+
2430
###### Parameters
2531

2632
| Parameter | Type |
2733
| ------ | ------ |
28-
| `name` | keyof `API` |
29-
| `callback` | (`sdk`: [`SDK`](index.md#sdk), ...`args`: `any`[]) => `any` |
34+
| `name` | `K` |
35+
| `callback` | [`APICallback`](other.md#apicallback)\<[`ResolvedAPI`](other.md#resolvedapi)\<`SpecOrAPI`\>\[`K`\]\> |
3036

3137
###### Returns
3238

@@ -42,16 +48,22 @@ sdk.api.register("multiply", (sdk: SDK, a: number, b: number) => {
4248

4349
##### send()
4450

45-
> **send**(`event`: keyof `Events`, ...`args`: `any`[]): `void`
51+
> **send**\<`K`\>(`event`: `K`, ...`args`: [`EventParameters`](other.md#eventparameters)\<[`ResolvedEvents`](other.md#resolvedevents)\<`SpecOrAPI`, `Events`\>\[`K`\]\>): `void`
4652
4753
Sends an event to the frontend plugin.
4854

55+
###### Type Parameters
56+
57+
| Type Parameter |
58+
| ------ |
59+
| `K` *extends* `string` \| `number` \| `symbol` |
60+
4961
###### Parameters
5062

5163
| Parameter | Type |
5264
| ------ | ------ |
53-
| `event` | keyof `Events` |
54-
| ...`args` | `any`[] |
65+
| `event` | `K` |
66+
| ...`args` | [`EventParameters`](other.md#eventparameters)\<[`ResolvedEvents`](other.md#resolvedevents)\<`SpecOrAPI`, `Events`\>\[`K`\]\> |
5567

5668
###### Returns
5769

‎src/reference/sdks/backend/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# @caido/sdk-backend
22

33
This is the reference for the backend SDK used by backend plugins.
4-
[SDK](#events) is the main interface that provides access to various services and functionalities.
4+
[SDK](other.md#events) is the main interface that provides access to various services and functionalities.
55

66
## SDK
77

‎src/reference/sdks/backend/other.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,50 @@ The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_
145145

146146
***
147147

148+
### AnyFn()
149+
150+
> **AnyFn** = (...`args`: `any`[]) => [`MaybePromise`](shared.md#maybepromise)\<`any`\>
151+
152+
#### Parameters
153+
154+
| Parameter | Type |
155+
| ------ | ------ |
156+
| ...`args` | `any`[] |
157+
158+
#### Returns
159+
160+
[`MaybePromise`](shared.md#maybepromise)\<`any`\>
161+
162+
***
163+
164+
### AnyVoidFn()
165+
166+
> **AnyVoidFn** = (...`args`: `any`[]) => [`MaybePromise`](shared.md#maybepromise)\<`void`\>
167+
168+
#### Parameters
169+
170+
| Parameter | Type |
171+
| ------ | ------ |
172+
| ...`args` | `any`[] |
173+
174+
#### Returns
175+
176+
[`MaybePromise`](shared.md#maybepromise)\<`void`\>
177+
178+
***
179+
180+
### APICallback
181+
182+
> **APICallback**\<`T`\> = `T` *extends* [`AnyFn`](#anyfn) ? (`sdk`: [`SDK`](index.md#sdk), ...`args`: `Parameters`\<`T`\>) => `ReturnType`\<`T`\> : [`InvalidCallbackMessage`](#invalidcallbackmessage)
183+
184+
#### Type Parameters
185+
186+
| Type Parameter |
187+
| ------ |
188+
| `T` |
189+
190+
***
191+
148192
### Console
149193

150194
> **Console** = `object`
@@ -276,6 +320,54 @@ The value of the environment variable.
276320

277321
***
278322

323+
### EventParameters
324+
325+
> **EventParameters**\<`T`\> = `T` *extends* [`AnyVoidFn`](#anyvoidfn) ? `A` : [`InvalidEventParametersMessage`](#invalideventparametersmessage)
326+
327+
#### Type Parameters
328+
329+
| Type Parameter |
330+
| ------ |
331+
| `T` |
332+
333+
***
334+
335+
### ExactPluginPackageKeys
336+
337+
> **ExactPluginPackageKeys**\<`T`\> = keyof `T` *extends* [`PluginPackageSpecKey`](#pluginpackagespeckey) ? [`PluginPackageSpecKey`](#pluginpackagespeckey) *extends* keyof `T` ? `unknown` : [`PluginPackageSpecKeyError`](#pluginpackagespeckeyerror) : [`PluginPackageSpecKeyError`](#pluginpackagespeckeyerror)
338+
339+
#### Type Parameters
340+
341+
| Type Parameter |
342+
| ------ |
343+
| `T` |
344+
345+
***
346+
347+
### InvalidCallbackMessage
348+
349+
> **InvalidCallbackMessage** = `"Your callback must respect the format (sdk: SDK, ...args: unknown[]) => MaybePromise<unknown>"`
350+
351+
***
352+
353+
### InvalidEventParametersMessage
354+
355+
> **InvalidEventParametersMessage** = `"Invalid event parameters"`
356+
357+
***
358+
359+
### MaybePromise
360+
361+
> **MaybePromise**\<`T`\> = `T` \| `Promise`\<`T`\>
362+
363+
#### Type Parameters
364+
365+
| Type Parameter |
366+
| ------ |
367+
| `T` |
368+
369+
***
370+
279371
### PageInfo
280372

281373
> **PageInfo** = `object`
@@ -308,6 +400,63 @@ Information on the current page of paginated data.
308400
309401
***
310402

403+
### PluginPackageSpec
404+
405+
> **PluginPackageSpec** = `object`
406+
407+
#### Properties
408+
409+
##### api
410+
411+
> **api**: `Record`\<`string`, [`AnyFn`](#anyfn)\>
412+
413+
##### events
414+
415+
> **events**: `Record`\<`string`, [`AnyVoidFn`](#anyvoidfn)\>
416+
417+
##### manifestId
418+
419+
> **manifestId**: `string`
420+
421+
***
422+
423+
### PluginPackageSpecKey
424+
425+
> **PluginPackageSpecKey** = keyof [`PluginPackageSpec`](#pluginpackagespec)
426+
427+
***
428+
429+
### PluginPackageSpecKeyError
430+
431+
> **PluginPackageSpecKeyError** = `"Only manifestId, api and events keys are allowed"`
432+
433+
***
434+
435+
### ResolvedAPI
436+
437+
> **ResolvedAPI**\<`T`\> = `T` *extends* `object` ? `A` : `T`
438+
439+
#### Type Parameters
440+
441+
| Type Parameter |
442+
| ------ |
443+
| `T` |
444+
445+
***
446+
447+
### ResolvedEvents
448+
449+
> **ResolvedEvents**\<`T`, `Events`\> = `T` *extends* `object` ? `A` : `Events`
450+
451+
#### Type Parameters
452+
453+
| Type Parameter |
454+
| ------ |
455+
| `T` |
456+
| `Events` |
457+
458+
***
459+
311460
### Result
312461

313462
> **Result** = `object`

‎src/reference/sdks/backend/shared.md‎

Lines changed: 43 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ A cursor for pagination.
2222
2323
***
2424

25-
### DefineAPI
25+
### ~~DefineAPI~~
2626

2727
> **DefineAPI**\<`API`\> = `{ [K in keyof API]: DefineAPICallback<API[K]> }`
2828
@@ -50,6 +50,10 @@ export function init(sdk: SDK<API>) {
5050
}
5151
```
5252

53+
#### Deprecated
54+
55+
Use DefinePluginPackageSpec instead.
56+
5357
***
5458

5559
### DefineAPICallback
@@ -80,7 +84,7 @@ Parser for Plugin backend events callbacks.
8084

8185
***
8286

83-
### DefineEvents
87+
### ~~DefineEvents~~
8488

8589
> **DefineEvents**\<`Events`\> = `{ [K in keyof Events]: DefineEventCallback<Events[K]> }`
8690
@@ -106,33 +110,57 @@ export function init(sdk: SDK<{}, BackendEvents>) {
106110
}
107111
```
108112

113+
#### Deprecated
114+
115+
Use DefinePluginPackageSpec instead.
116+
109117
***
110118

111-
### ID
119+
### DefinePluginPackageSpec
112120

113-
> **ID** = `string` & `object`
121+
> **DefinePluginPackageSpec**\<`TSpec`\> = `TSpec`
114122
115-
A unique identifier.
123+
Define the specification of a Plugin Package. This includes:
116124

117-
#### Type Declaration
125+
- Manifest ID: the unique identifier of the plugin package.
126+
- API: the backend functions that are callable from the frontend plugin.
127+
- Events: the events that the frontend can receive from the backend plugin.
118128

119-
##### \_\_id?
129+
#### Type Parameters
120130

121-
> `optional` **\_\_id**: `never`
131+
| Type Parameter |
132+
| ------ |
133+
| `TSpec` *extends* [`PluginPackageSpec`](other.md#pluginpackagespec) & [`ExactPluginPackageKeys`](other.md#exactpluginpackagekeys)\<`TSpec`\> |
134+
135+
#### Example
136+
137+
```typescript
138+
type MyEventData = { id: string; name: string };
139+
140+
export type Spec = DefinePluginPackageSpec<{
141+
manifestId: "myplugin",
142+
api: {
143+
myFunction: (min: number, max: number) => Promise<string>;
144+
},
145+
events: {
146+
"my-event": (data: MyEventData) => void;
147+
}
148+
}>;
149+
```
122150

123151
***
124152

125-
### MaybePromise
153+
### ID
126154

127-
> **MaybePromise**\<`T`\> = `T` \| `Promise`\<`T`\>
155+
> **ID** = `string` & `object`
128156
129-
Promise or value.
157+
A unique identifier.
130158

131-
#### Type Parameters
159+
#### Type Declaration
132160

133-
| Type Parameter |
134-
| ------ |
135-
| `T` |
161+
##### \_\_id?
162+
163+
> `optional` **\_\_id**: `never`
136164
137165
***
138166

‎src/reference/sdks/frontend/backend.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,30 +26,30 @@ Events emitted by the backend plugin.
2626

2727
### BackendSDK
2828

29-
> **BackendSDK**\<`T`, `E`\> = `{ [K in keyof T]: (args: Parameters<T[K]>) => PromisifiedReturnType<T[K]> }` & `object`
29+
> **BackendSDK**\<`T`, `E`\> = `{ [K in keyof ResolvedAPI<T>]: (args: Parameters<ResolvedAPI<T>[K]>) => PromisifiedReturnType<ResolvedAPI<T>[K]> }` & `object`
3030
3131
Utilities to interact with the backend plugin.
3232

3333
#### Type Declaration
3434

3535
##### onEvent()
3636

37-
> **onEvent**: \<`K`\>(`event`: `K`, `callback`: `E`\[`K`\]) => `object`
37+
> **onEvent**: \<`K`\>(`event`: `K`, `callback`: [`ResolvedEvents`](other.md#resolvedevents)\<`T`, `E`\>\[`K`\]) => `object`
3838
3939
Subscribe to a backend event.
4040

4141
###### Type Parameters
4242

4343
| Type Parameter |
4444
| ------ |
45-
| `K` *extends* keyof `E` |
45+
| `K` *extends* keyof [`ResolvedEvents`](other.md#resolvedevents)\<`T`, `E`\> |
4646

4747
###### Parameters
4848

4949
| Parameter | Type | Description |
5050
| ------ | ------ | ------ |
5151
| `event` | `K` | The event to subscribe to. |
52-
| `callback` | `E`\[`K`\] | The callback to call when the event is emitted. |
52+
| `callback` | [`ResolvedEvents`](other.md#resolvedevents)\<`T`, `E`\>\[`K`\] | The callback to call when the event is emitted. |
5353

5454
###### Returns
5555

@@ -69,5 +69,5 @@ An object with a `stop` method that can be called to stop listening to the event
6969

7070
| Type Parameter |
7171
| ------ |
72-
| `T` *extends* [`BackendEndpoints`](#backendendpoints) |
72+
| `T` *extends* [`ResolvedAPI`](other.md#resolvedapi)\<[`BackendEndpoints`](#backendendpoints)\> |
7373
| `E` *extends* [`BackendEvents`](#backendevents) |

‎src/reference/sdks/frontend/findings.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
> **Finding** = `object`
66
7-
Represents a [https://docs.caido.io/reference/features/logging/findings\|Finding](https://docs.caido.io/reference/features/logging/findings|Finding).
7+
Represents a [https://docs.caido.io/app/quickstart/findings.html\|Finding](https://docs.caido.io/app/quickstart/findings.html|Finding).
88

99
#### Properties
1010

0 commit comments

Comments
 (0)