@caido/sdk-frontend

This is the reference for the frontend SDK used by frontend plugins. Caido is the main interface that provides access to various services and functionalities.

SDK

Caido<T, E>

Caido<T, E>: object

Utilities for frontend plugins.

Type Parameters

Type Parameter	Default type
`T` extends `BackendEndpoints`	`Record`<`string`, `never`>
`E` extends `BackendEvents`	`Record`<`string`, `never`>

Type declaration

backend

backend: BackendSDK<T, E>

Utilities to interact with the backend plugin.

commandPalette

commandPalette: CommandPaletteSDK

Utilities to interact with the command palette.

commands

commands: CommandsSDK

Utilities to interact with commands

findings

findings: FindingsSDK

Utilities to interact with findings

graphql

graphql: GraphqlSDK

Utilities to interact with the GraphQL API.

httpHistory

httpHistory: HTTPHistorySDK

Utilities to interact with the HTTP History page.

menu: MenuSDK

Utilities to insert menu items and context-menus throughout the UI.

navigation: NavigationSDK

Utilities to interact with navigation.

replay

replay: ReplaySDK

Utilities to interact with the Replay page.

scopes

scopes: ScopesSDK

Utilities to interact with scopes

search

search: SearchSDK

Utilities to interact with the Search page.

shortcuts

shortcuts: ShortcutsSDK

Utilities to interact with shortcuts.

sidebar: SidebarSDK

Utilities to interact with the sidebar.

storage

storage: StorageSDK

Utilities to interact with frontend-plugin storage.

ui

ui: UISDK

Utilities to create UI components.

window

window: WindowSDK

Utilities to interact with the active page.

Backend

BackendEndpoints

BackendEndpoints: object

Endpoints provided by the backend plugin.

Index Signature

[key: string]: (...args: any[]) => any

BackendEvents

BackendEvents: object

Events emitted by the backend plugin.

Index Signature

[key: string]: (...args: any[]) => void

BackendSDK<T, E>

BackendSDK<T, E>: { [K in keyof T]: Function } & object

Utilities to interact with the backend plugin.

Type declaration

onEvent()

onEvent: <K>(event: K, callback: E[K]) => object

Subscribe to a backend event.

Type Parameters

Type Parameter
`K` extends keyof `E`

Parameters

Parameter	Type	Description
`event`	`K`	The event to subscribe to.
`callback`	`E`[`K`]	The callback to call when the event is emitted.

Returns

object

An object with a stop method that can be called to stop listening to the event.

stop()

stop: () => void

Returns

void

Type Parameters

Type Parameter
`T` extends `BackendEndpoints`
`E` extends `BackendEvents`

UI

UISDK

UISDK: object

Utilities to create UI components.

Type declaration

button()

button: (options?: object) => HTMLElement

Create a button.

Parameters

Parameter	Type	Description
`options`?	`object`	Options for the button.
`options.label`?	`string`	The label of the button.
`options.leadingIcon`?	`Icon`	The leading icon of the button.
`options.size`?	`"small"` \| `"medium"` \| `"large"`	The size of the button.
`options.trailingIcon`?	`Icon`	The trailing icon of the button.
`options.variant`?	`"primary"` \| `"secondary"` \| `"tertiary"`	The variant of the button.

Returns

HTMLElement

The button element.

Example

const deleteButton = sdk.ui.button({
  variant: "primary",
  label: "Delete",
  trailingIcon: "fas fa-trash-can",
  size: "small",
});

card()

card: (options?: object) => HTMLElement

Create a card.

Parameters

Parameter	Type	Description
`options`?	`object`	Options for the card.
`options.body`?	`HTMLElement`	The body of the card.
`options.footer`?	`HTMLElement`	The footer of the card.
`options.header`?	`HTMLElement`	The header of the card.

Returns

HTMLElement

The card element.

httpRequestEditor()

httpRequestEditor: () => HTTPRequestEditor

Create an HTTP request editor

Returns

HTTPRequestEditor

The HTTP request editor.

httpResponseEditor()

httpResponseEditor: () => HTTPResponseEditor

Create an HTTP response editor

Returns

HTTPResponseEditor

The HTTP response editor.

well()

well: (options?: object) => HTMLElement

Create a well.

Parameters

Parameter	Type	Description
`options`?	`object`	Options for the well.
`options.body`?	`HTMLElement`	The body of the well.
`options.footer`?	`HTMLElement`	The footer of the well.
`options.header`?	`HTMLElement`	The header of the well.

Returns

HTMLElement

The well element.

Scopes

Scope

Scope: object

Represents a scope.

Type declaration

allowlist

allowlist: string[]

The list of included items.

denylist

denylist: string[]

The list of excluded items.

id

id: ID

The unique ID of the scope.

name

name: string

The name of the scope.

ScopesSDK

ScopesSDK: object

Utilities to interact with scopes

Type declaration

createScope()

createScope: (options: object) => Promise<Scope | undefined>

Create a scope.

Parameters

Parameter	Type	Description
`options`	`object`	Options for the scope.
`options.allowlist`	`string`[]	The list of included items in the scope.
`options.denylist`	`string`[]	The list of excluded items in the scope.
`options.name`	`string`	The name of the scope.

Returns

Promise<Scope | undefined>

The created scope.

Example

const newScope = await sdk.scopes.createScope({
  name: "Example",
  allowlist: ["*example.com", "*github.com"],
  denylist: ["*caido.io"],
});

deleteScope()

deleteScope: (id: ID) => Promise<boolean>

Delete a scope.

Parameters

Parameter	Type	Description
`id`	`ID`	The id of the scope to delete.

Returns

Promise<boolean>

Whether the scope was deleted.

getScopes()

getScopes: () => Scope[]

Get all scopes.

Returns

Scope[]

A list of scopes.

updateScope()

updateScope: (id: ID, options: object) => Promise<Scope | undefined>

Update a scope.

Parameters

Parameter	Type	Description
`id`	`ID`	The id of the scope to update.
`options`	`object`	Options for the scope.
`options.allowlist`?	`string`[]	The list of included items in the scope.
`options.denylist`?	`string`[]	The list of excluded items in the scope.
`options.name`?	`string`	The name of the scope.

Returns

Promise<Scope | undefined>

The updated scope.

Findings

Finding

Finding: object

Represents a https://docs.caido.io/reference/features/logging/findings|Finding.

Type declaration

description?

optional description: string

The description of the finding.

host

host: string

The host of the request attached to this finding

id

id: ID

The ID of the finding.

path

path: string

The path of the request attached to this finding

reporter

reporter: string

The reporter of the finding.

title

title: string

The title of the finding.

FindingsSDK

FindingsSDK: object

Utilities to interact with findings

Type declaration

createFinding()

createFinding: (requestId: ID, options: object) => Promise<Finding | undefined>

Create a Finding.

Parameters

Parameter	Type	Description
`requestId`	`ID`	The id of the request the finding is associated with.
`options`	`object`	Options for the finding.
`options.dedupeKey`?	`string`	If a finding with the same deduplication key already exists, it will not create a new finding.
`options.description`?	`string`	The description of the finding.
`options.reporter`	`string`	The reporter of the finding.
`options.title`	`string`	The title of the finding.

Returns

Promise<Finding | undefined>

The created finding.

Commands

CommandContext

CommandContext: CommandContextBase | CommandContextRequestRow | CommandContextRequest | CommandContextResponse

Represents the context in which a command is executed.

CommandContextBase

CommandContextBase: object

The base context for a command. This context is used for commands that are not executed in a specific context, such as via shortcuts and the command palette.

Type declaration

type

type: "BaseContext"

CommandContextRequest

CommandContextRequest: object

The context for a command that is executed on a request pane.

Type declaration

request

request: object

The request that is currently open in the request pane.

request.host

host: string

request.isTls

isTls: boolean

request.path

path: string

request.port

port: number

request.query

query: string

request.raw

raw: string

selection

selection: string

The currently selected text in the request pane.

type

type: "RequestContext"

CommandContextRequestRow

CommandContextRequestRow: object

The context for a command that is executed on a row in the request table.

Type declaration

requests

requests: object[]

The requests that are selected in the request table.

type

type: "RequestRowContext"

CommandContextResponse

CommandContextResponse: object

The context for a command that is executed on a response pane.

Type declaration

request

request: object

The request that is associated with the response.

request.host

host: string

request.id

id: ID

request.isTls

isTls: boolean

request.path

path: string

request.port

port: number

request.query

query: string

response

response: object

The response that is currently open in the response pane.

response.id

id: ID

response.raw

raw: string

response.roundtripTime

roundtripTime: number

response.statusCode

statusCode: number

selection

selection: string

The currently selected text in the response pane.

type

type: "ResponseContext"

CommandsSDK

CommandsSDK: object

Utilities to interact with commands

Type declaration

register()

register: (id: CommandID, options: object) => void

Parameters

Parameter	Type	Description
`id`	`CommandID`	The id of the command.
`options`	`object`	Options for the command.
`options.group`?	`string`	The group this command belongs to.
`options.name`	`string`	The name of the command.
`options.run`	(`context`: `CommandContext`) => `void`	The function to run when the command is executed.
`options.when`?	(`context`: `CommandContext`) => `boolean`	A function to determine if the command is available.

Returns

void

Example

sdk.commands.register("hello", {
  name: "Print to console.",
  run: () => console.log("Hello world!"),
  group: "Custom Commands",
});

MenuItem

MenuItem: RequestRowMenuItem | SettingsMenuItem | RequestMenuItem | ResponseMenuItem

A content-menu item.

MenuSDK

MenuSDK: object

Utilities to insert menu items and context-menus throughout the UI.

Type declaration

registerItem()

registerItem: (item: MenuItem) => void

Parameters

Parameter	Type	Description
`item`	`MenuItem`	The menu item to register.

Returns

void

Example

sdk.menu.registerItem({
  type: "Request",
  commandId: "hello",
  leadingIcon: "fas fa-hand",
});

RequestMenuItem

RequestMenuItem: object

A context-menu item that appears when right-clicking a request pane.

Type declaration

commandId

commandId: CommandID

The command ID to execute when the menu item is clicked.

leadingIcon?

optional leadingIcon: string

The icon to display to the left of the menu item.

type

type: "Request"

RequestRowMenuItem

RequestRowMenuItem: object

A context-menu item that appears when right-clicking a request row.

Type declaration

commandId

commandId: CommandID

The command ID to execute when the menu item is clicked.

leadingIcon?

optional leadingIcon: string

The icon to display to the left of the menu item.

type

type: "RequestRow"

ResponseMenuItem

ResponseMenuItem: object

A context-menu item that appears when right-clicking a response pane.

Type declaration

commandId

commandId: CommandID

The command ID to execute when the menu item is

leadingIcon?

optional leadingIcon: string

The icon to display to the left of the menu item.

type

type: "Response"

SettingsMenuItem

SettingsMenuItem: object

A menu item that appears in the settings menu.

Type declaration

label

label: string

The label of the menu item.

leadingIcon?

optional leadingIcon: Icon

The Icon to display to the left of the menu item.

path

path: string

The path that the user will be navigated to when the menu item is clicked The path must start with "/settings/".

type

type: "Settings"

NavigationSDK

NavigationSDK: object

Utilities to interact with navigation.

Type declaration

addPage()

addPage: (path: string, options: object) => void

Add a page to the navigation.

Parameters

Parameter	Type	Description
`path`	`string`	The path of the page.
`options`	`object`	Options for the page.
`options.body`	`HTMLElement`	The body of the page.
`options.topbar`?	`HTMLElement`	The topbar of the page.

Returns

void

goTo()

goTo: (path: string) => void

Navigate to a path.

Parameters

Parameter	Type	Description
`path`	`string`	The path to navigate to.

Returns

void

Example

sdk.navigation.goTo("/my-plugin-page");

Window

WindowSDK

WindowSDK: object

Utilities to interact with the active page.

Type declaration

getActiveEditor()

getActiveEditor: () => Editor | undefined

Get the active editor.

Returns

Editor | undefined

The active editor.

showToast()

showToast: (message: string, options?: object) => void

Show a toast message.

Parameters

Parameter	Type	Description
`message`	`string`	The message to show.
`options`?	`object`	Options for the toast message.
`options.duration`?	`number`	The duration of the toast message in milliseconds.
`options.variant`?	`"success"` \| `"error"` \| `"warning"` \| `"info"`	The variant of the toast message.

Returns

void

Storage

StorageSDK

StorageSDK: object

Utilities to interact with frontend-plugin storage.

Type declaration

get()

get: () => JSONValue

Get the storage.

Returns

JSONValue

The storage.

onChange()

onChange: (callback: (value: JSONValue) => void) => void

Subscribe to storage changes.

Parameters

Parameter	Type	Description
`callback`	(`value`: `JSONValue`) => `void`	The callback to call when the storage changes.

Returns

void

set()

set: <T>(value: JSONCompatible<T>) => Promise<void>

Set the storage.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`value`	`JSONCompatible`<`T`>	The value to set the storage to

Returns

Promise<void>

A promise that resolves when the storage has been set.

Shortcuts

ShortcutsSDK

ShortcutsSDK: object

Utilities to interact with shortcuts.

Type declaration

register()

register: (commandId: CommandID, keys: string[]) => void

Parameters

Parameter	Type	Description
`commandId`	`CommandID`	The id of the command to run when the shortcut is triggered.
`keys`	`string`[]	The keys of the shortcut. Check out hotkeys-js for the list of supported keys.

Returns

void

Command Palette

CommandPaletteSDK

CommandPaletteSDK: object

Utilities to interact with the command palette.

Type declaration

register()

register: (commandId: string) => void

Parameters

Parameter	Type	Description
`commandId`	`string`	The id of the command to register.

Returns

void

SidebarItem

SidebarItem: object

Represents a sidebar item.

Type declaration

setCount()

setCount: (count: number) => void

Set the value of a notification badge next to the sidebar item.

Parameters

Parameter	Type	Description
`count`	`number`	The number to display in the badge. A value of 0 will hide the badge.

Returns

void

SidebarSDK

SidebarSDK: object

Utilities to interact with the sidebar.

Type declaration

registerItem()

registerItem: (name: string, path: string, options?: object) => SidebarItem

Parameters

Parameter	Type	Description
`name`	`string`	The name of the sidebar item.
`path`	`string`	The path that the user will be navigated to when the sidebar item is clicked.
`options`?	`object`	Options for the sidebar item.
`options.group`?	`string`	The group the sidebar item belongs to.
`options.icon`?	`Icon`	The Icon of the sidebar item.
`options.isExternal`?	`boolean`	Whether the path points to an external URL.

Returns

SidebarItem

The created sidebar item.

Example

sdk.sidebar.registerItem("My Plugin", "/my-plugin-page", {
  icon: "fas fa-rocket",
});

Replay

ReplayCollection

ReplayCollection: object

A collection in Replay.

Type declaration

id

id: string

The ID of the collection.

name

name: string

The name of the collection.

sessionIds

sessionIds: string[]

The sessions in the collection.

ReplaySDK

ReplaySDK: object

Utilities to interact with Replay.

Type declaration

closeTab()

closeTab: (sessionId: string) => void

Close a replay tab for the given session.

Parameters

Parameter	Type	Description
`sessionId`	`string`	The ID of the session to close.

Returns

void

getCollections()

getCollections: () => ReplayCollection[]

Get the list of all replay collections.

Returns

ReplayCollection[]

The list of all replay collections.

getSessions()

getSessions: () => ReplaySession[]

Get the list of all replay sessions.

Returns

ReplaySession[]

The list of all replay sessions.

getTabs()

getTabs: () => ReplayTab[]

Get the list of all open replay tabs.

Returns

ReplayTab[]

The list of all open replay tabs.

openTab()

openTab: (sessionId: string) => void

Open a replay tab for the given session.

Parameters

Parameter	Type	Description
`sessionId`	`string`	The ID of the session to open.

Returns

void

renameSession()

renameSession: (id: string, name: string) => Promise<ReplaySession>

Rename a session.

Parameters

Parameter	Type	Description
`id`	`string`	The ID of the session to rename.
`name`	`string`	The new name of the session.

Returns

Promise<ReplaySession>

The updated session.

ReplaySession

ReplaySession: object

A session in Replay.

Type declaration

collectionId

collectionId: string

The ID of the collection the session belongs to.

id

id: string

The ID of the session.

name

name: string

The name of the session.

ReplayTab

ReplayTab: object

A replay tab.

Type declaration

sessionId

sessionId: string

The ID of the session associated with this tab.

HTTP History

HTTPHistorySDK

HTTPHistorySDK: object

Utilities to interact with the HTTP History page.

Type declaration

getQuery()

getQuery: () => string

Get the current HTTPQL query.

Returns

string

The current HTTPQL query.

setQuery()

setQuery: (query: string) => void

Set the HTTPQL query that will be applied on the HTTP History table results.

Parameters

Parameter	Type	Description
`query`	`string`	The HTTPQL query.

Returns

void

Search

SearchSDK

SearchSDK: object

Utilities to interact with the Search page.

Type declaration

getQuery()

getQuery: () => string

Get the current HTTPQL query.

Returns

string

The current HTTPQL query.

setQuery()

setQuery: (query: string) => void

Set the HTTPQL query that will be applied on the search table results.

Parameters

Parameter	Type	Description
`query`	`string`	The HTTPQL query.

Returns

void

Other

CommandID

CommandID: string & object

A unique command identifier.

Type declaration

__commandId?

optional __commandId: never

Example

"my-super-command"

Editor

Editor: object

Generic editor interface.

Type declaration

focus()

focus: () => void

Focus the editor.

Returns

void

getEditorView()

getEditorView: () => EditorView

Get the editor view.

Returns

EditorView

The CodeMirror EditorView.

getSelectedText()

getSelectedText: () => string

Get the currently selected text of the editor.

Returns

string

isReadOnly()

isReadOnly: () => boolean

Check whether the editor is read-only.

Returns

boolean

Whether the editor is read-only.

replaceSelectedText()

replaceSelectedText: (text: string) => void

Replace the currently selected text of the editor.

Parameters

Parameter	Type	Description
`text`	`string`	The text to replace the selection with.

Returns

void

HTTPRequestEditor

HTTPRequestEditor: object

Type declaration

getEditorView()

getEditorView: () => EditorView

Get the editor view.

Returns

EditorView

The CodeMirror EditorView.

getElement()

getElement: () => HTMLElement

Get the editor element. Append this to your DOM to display the editor.

Returns

HTMLElement

The editor element.

HTTPResponseEditor

HTTPResponseEditor: object

Type declaration

getEditorView()

getEditorView: () => EditorView

Get the editor view.

Returns

EditorView

The CodeMirror EditorView.

getElement()

getElement: () => HTMLElement

Get the editor element. Append this to your DOM to display the editor.

Returns

HTMLElement

The editor element.

Icon

Icon: string & object

A https://fontawesome.com/icons|FontAwesome icon class.

Type declaration

__icon?

optional __icon: never

Example

"fas fa-rocket"

ID

ID: string & object

A unique Caido identifier per type.

Type declaration

__id?

optional __id: never

JSONCompatible<T>

JSONCompatible<T>: unknown extends T ? never : { [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible<T[P]> }

Type Parameters

Type Parameter
`T`

JSONPrimitive

JSONPrimitive: string | number | boolean | null | undefined

JSONValue

JSONValue: JSONPrimitive | JSONValue[] | object

NotAssignableToJson

NotAssignableToJson: bigint | symbol | Function

PromisifiedReturnType<T>

PromisifiedReturnType<T>: ReturnType<T> extends Promise<infer U> ? Promise<U> : Promise<ReturnType<T>>

Type Parameters

Type Parameter
`T` extends (...`args`: `unknown`[]) => `unknown`

@caido/sdk-frontend ​

SDK ​

Caido<T, E> ​

Type Parameters ​

Type declaration ​

backend ​

commandPalette ​

commands ​

findings ​

graphql ​

httpHistory ​

menu ​

navigation ​

replay ​

scopes ​

search ​

shortcuts ​

sidebar ​

storage ​

ui ​

window ​

Backend ​

BackendEndpoints ​

Index Signature ​

BackendEvents ​

Index Signature ​

BackendSDK<T, E> ​

Type declaration ​

onEvent() ​

Type Parameters ​

Parameters ​

Returns ​

stop() ​

Returns ​

Type Parameters ​

UI ​

UISDK ​

Type declaration ​

button() ​

Parameters ​

Returns ​

Example ​

card() ​

Parameters ​

Returns ​

httpRequestEditor() ​

Returns ​

httpResponseEditor() ​

Returns ​

well() ​

Parameters ​

Returns ​

Scopes ​

Scope ​

Type declaration ​

allowlist ​

denylist ​

id ​

name ​

ScopesSDK ​

Type declaration ​

createScope() ​

Parameters ​

Returns ​

Example ​

deleteScope() ​

Parameters ​

Returns ​

getScopes() ​

Returns ​

updateScope() ​

Parameters ​

Returns ​

Findings ​

Finding ​

Type declaration ​

description? ​

host ​

id ​

path ​

@caido/sdk-frontend

SDK

Caido<T, E>

Type Parameters

Type declaration

backend

commandPalette

commands

findings

graphql

httpHistory

menu

navigation

replay

scopes

search

shortcuts

sidebar

storage

ui

window

Backend

BackendEndpoints

Index Signature

BackendEvents

Index Signature

BackendSDK<T, E>

Type declaration

onEvent()

Type Parameters

Parameters

Returns

stop()

Returns

Type Parameters

UI

UISDK

Type declaration

button()

Parameters

Returns

Example

card()

Parameters

Returns

httpRequestEditor()

Returns

httpResponseEditor()

Returns

well()

Parameters

Returns

Scopes

Scope

Type declaration

allowlist

denylist

id

name

ScopesSDK

Type declaration

createScope()

Parameters

Returns

Example

deleteScope()

Parameters

Returns

getScopes()

Returns

updateScope()

Parameters

Returns

Findings

Finding

Type declaration

description?

host

id

path