From 08bb3df836d974e00b54074607cfe7b6ff290ffa Mon Sep 17 00:00:00 2001 From: Caido Bot Date: Fri, 15 May 2026 18:41:48 +0000 Subject: [PATCH] Update SDK Documentation --- src/reference/sdks/backend/api.md | 28 +++-- src/reference/sdks/backend/index.md | 2 +- src/reference/sdks/backend/other.md | 149 +++++++++++++++++++++++++++ src/reference/sdks/backend/shared.md | 58 ++++++++--- 4 files changed, 213 insertions(+), 24 deletions(-) diff --git a/src/reference/sdks/backend/api.md b/src/reference/sdks/backend/api.md index ed6d9f9..fd5d526 100644 --- a/src/reference/sdks/backend/api.md +++ b/src/reference/sdks/backend/api.md @@ -2,7 +2,7 @@ ### APISDK -> **APISDK**\<`API`, `Events`\> = `object` +> **APISDK**\<`SpecOrAPI`, `Events`\> = `object` The SDK for the API RPC service. @@ -10,23 +10,29 @@ The SDK for the API RPC service. | Type Parameter | Default type | | ------ | ------ | -| `API` | `object` | +| `SpecOrAPI` | `object` | | `Events` | `object` | #### Methods ##### register() -> **register**(`name`: keyof `API`, `callback`: (`sdk`: [`SDK`](index.md#sdk), ...`args`: `any`[]) => `any`): `void` +> **register**\<`K`\>(`name`: `K`, `callback`: [`APICallback`](other.md#apicallback)\<[`ResolvedAPI`](other.md#resolvedapi)\<`SpecOrAPI`\>\[`K`\]\>): `void` Registers a new backend function for the RPC. +###### Type Parameters + +| Type Parameter | +| ------ | +| `K` *extends* `string` \| `number` \| `symbol` | + ###### Parameters | Parameter | Type | | ------ | ------ | -| `name` | keyof `API` | -| `callback` | (`sdk`: [`SDK`](index.md#sdk), ...`args`: `any`[]) => `any` | +| `name` | `K` | +| `callback` | [`APICallback`](other.md#apicallback)\<[`ResolvedAPI`](other.md#resolvedapi)\<`SpecOrAPI`\>\[`K`\]\> | ###### Returns @@ -42,16 +48,22 @@ sdk.api.register("multiply", (sdk: SDK, a: number, b: number) => { ##### send() -> **send**(`event`: keyof `Events`, ...`args`: `any`[]): `void` +> **send**\<`K`\>(`event`: `K`, ...`args`: [`EventParameters`](other.md#eventparameters)\<[`ResolvedEvents`](other.md#resolvedevents)\<`SpecOrAPI`, `Events`\>\[`K`\]\>): `void` Sends an event to the frontend plugin. +###### Type Parameters + +| Type Parameter | +| ------ | +| `K` *extends* `string` \| `number` \| `symbol` | + ###### Parameters | Parameter | Type | | ------ | ------ | -| `event` | keyof `Events` | -| ...`args` | `any`[] | +| `event` | `K` | +| ...`args` | [`EventParameters`](other.md#eventparameters)\<[`ResolvedEvents`](other.md#resolvedevents)\<`SpecOrAPI`, `Events`\>\[`K`\]\> | ###### Returns diff --git a/src/reference/sdks/backend/index.md b/src/reference/sdks/backend/index.md index aa58f0c..468e973 100644 --- a/src/reference/sdks/backend/index.md +++ b/src/reference/sdks/backend/index.md @@ -1,7 +1,7 @@ # @caido/sdk-backend This is the reference for the backend SDK used by backend plugins. -[SDK](#events) is the main interface that provides access to various services and functionalities. +[SDK](other.md#events) is the main interface that provides access to various services and functionalities. ## SDK diff --git a/src/reference/sdks/backend/other.md b/src/reference/sdks/backend/other.md index a0e47b6..a1e856c 100644 --- a/src/reference/sdks/backend/other.md +++ b/src/reference/sdks/backend/other.md @@ -145,6 +145,50 @@ The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_ *** +### AnyFn() + +> **AnyFn** = (...`args`: `any`[]) => [`MaybePromise`](shared.md#maybepromise)\<`any`\> + +#### Parameters + +| Parameter | Type | +| ------ | ------ | +| ...`args` | `any`[] | + +#### Returns + +[`MaybePromise`](shared.md#maybepromise)\<`any`\> + +*** + +### AnyVoidFn() + +> **AnyVoidFn** = (...`args`: `any`[]) => [`MaybePromise`](shared.md#maybepromise)\<`void`\> + +#### Parameters + +| Parameter | Type | +| ------ | ------ | +| ...`args` | `any`[] | + +#### Returns + +[`MaybePromise`](shared.md#maybepromise)\<`void`\> + +*** + +### APICallback + +> **APICallback**\<`T`\> = `T` *extends* [`AnyFn`](#anyfn) ? (`sdk`: [`SDK`](index.md#sdk), ...`args`: `Parameters`\<`T`\>) => `ReturnType`\<`T`\> : [`InvalidCallbackMessage`](#invalidcallbackmessage) + +#### Type Parameters + +| Type Parameter | +| ------ | +| `T` | + +*** + ### Console > **Console** = `object` @@ -276,6 +320,54 @@ The value of the environment variable. *** +### EventParameters + +> **EventParameters**\<`T`\> = `T` *extends* [`AnyVoidFn`](#anyvoidfn) ? `A` : [`InvalidEventParametersMessage`](#invalideventparametersmessage) + +#### Type Parameters + +| Type Parameter | +| ------ | +| `T` | + +*** + +### ExactPluginPackageKeys + +> **ExactPluginPackageKeys**\<`T`\> = keyof `T` *extends* [`PluginPackageSpecKey`](#pluginpackagespeckey) ? [`PluginPackageSpecKey`](#pluginpackagespeckey) *extends* keyof `T` ? `unknown` : [`PluginPackageSpecKeyError`](#pluginpackagespeckeyerror) : [`PluginPackageSpecKeyError`](#pluginpackagespeckeyerror) + +#### Type Parameters + +| Type Parameter | +| ------ | +| `T` | + +*** + +### InvalidCallbackMessage + +> **InvalidCallbackMessage** = `"Your callback must respect the format (sdk: SDK, ...args: unknown[]) => MaybePromise"` + +*** + +### InvalidEventParametersMessage + +> **InvalidEventParametersMessage** = `"Invalid event parameters"` + +*** + +### MaybePromise + +> **MaybePromise**\<`T`\> = `T` \| `Promise`\<`T`\> + +#### Type Parameters + +| Type Parameter | +| ------ | +| `T` | + +*** + ### PageInfo > **PageInfo** = `object` @@ -308,6 +400,63 @@ Information on the current page of paginated data. *** +### PluginPackageSpec + +> **PluginPackageSpec** = `object` + +#### Properties + +##### api + +> **api**: `Record`\<`string`, [`AnyFn`](#anyfn)\> + +##### events + +> **events**: `Record`\<`string`, [`AnyVoidFn`](#anyvoidfn)\> + +##### manifestId + +> **manifestId**: `string` + +*** + +### PluginPackageSpecKey + +> **PluginPackageSpecKey** = keyof [`PluginPackageSpec`](#pluginpackagespec) + +*** + +### PluginPackageSpecKeyError + +> **PluginPackageSpecKeyError** = `"Only manifestId, api and events keys are allowed"` + +*** + +### ResolvedAPI + +> **ResolvedAPI**\<`T`\> = `T` *extends* `object` ? `A` : `T` + +#### Type Parameters + +| Type Parameter | +| ------ | +| `T` | + +*** + +### ResolvedEvents + +> **ResolvedEvents**\<`T`, `Events`\> = `T` *extends* `object` ? `A` : `Events` + +#### Type Parameters + +| Type Parameter | +| ------ | +| `T` | +| `Events` | + +*** + ### Result > **Result** = `object` diff --git a/src/reference/sdks/backend/shared.md b/src/reference/sdks/backend/shared.md index 3efce17..703480f 100644 --- a/src/reference/sdks/backend/shared.md +++ b/src/reference/sdks/backend/shared.md @@ -22,7 +22,7 @@ A cursor for pagination. *** -### DefineAPI +### ~~DefineAPI~~ > **DefineAPI**\<`API`\> = `{ [K in keyof API]: DefineAPICallback }` @@ -50,6 +50,10 @@ export function init(sdk: SDK) { } ``` +#### Deprecated + +Use DefinePluginPackageSpec instead. + *** ### DefineAPICallback @@ -80,7 +84,7 @@ Parser for Plugin backend events callbacks. *** -### DefineEvents +### ~~DefineEvents~~ > **DefineEvents**\<`Events`\> = `{ [K in keyof Events]: DefineEventCallback }` @@ -106,33 +110,57 @@ export function init(sdk: SDK<{}, BackendEvents>) { } ``` +#### Deprecated + +Use DefinePluginPackageSpec instead. + *** -### ID +### DefinePluginPackageSpec -> **ID** = `string` & `object` +> **DefinePluginPackageSpec**\<`TSpec`\> = `TSpec` -A unique identifier. +Define the specification of a Plugin Package. This includes: -#### Type Declaration +- Manifest ID: the unique identifier of the plugin package. +- API: the backend functions that are callable from the frontend plugin. +- Events: the events that the frontend can receive from the backend plugin. -##### \_\_id? +#### Type Parameters -> `optional` **\_\_id**: `never` +| Type Parameter | +| ------ | +| `TSpec` *extends* [`PluginPackageSpec`](other.md#pluginpackagespec) & [`ExactPluginPackageKeys`](other.md#exactpluginpackagekeys)\<`TSpec`\> | + +#### Example + +```typescript +type MyEventData = { id: string; name: string }; + +export type Spec = DefinePluginPackageSpec<{ + manifestId: "myplugin", + api: { + myFunction: (min: number, max: number) => Promise; + }, + events: { + "my-event": (data: MyEventData) => void; + } +}>; +``` *** -### MaybePromise +### ID -> **MaybePromise**\<`T`\> = `T` \| `Promise`\<`T`\> +> **ID** = `string` & `object` -Promise or value. +A unique identifier. -#### Type Parameters +#### Type Declaration -| Type Parameter | -| ------ | -| `T` | +##### \_\_id? + +> `optional` **\_\_id**: `never` ***