@caido/sdk-frontend 0.41.1-beta.3 → 0.41.1-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caido/sdk-frontend",
-  "version": "0.41.1-beta.3",
+  "version": "0.41.1-beta.5",
   "description": "Typing for the Caido Frontend SDK",
   "author": "Caido Labs Inc. <dev@caido.io>",
   "license": "MIT",

package/src/types/backend.d.ts

@@ -1,11 +1,23 @@
 import type { PromisifiedReturnType } from "./utils";
+/**
+ * Endpoints provided by the backend plugin.
+ * @category Backend
+ */
 export type BackendEndpoints = {
     [key: string]: (...args: any[]) => any;
 };
+/**
+ * Events emitted by the backend plugin.
+ * @category Backend
+ */
 export type BackendEvents = {
     [key: string]: (...args: any[]) => void;
 };
-export type ToBackendRPC<T extends BackendEndpoints, E extends BackendEvents> = {
+/**
+ * Utilities to interact with the backend plugin.
+ * @category Backend
+ */
+export type BackendSDK<T extends BackendEndpoints, E extends BackendEvents> = {
     [K in keyof T]: (...args: Parameters<T[K]>) => PromisifiedReturnType<T[K]>;
 } & {
     /**

package/src/types/command_palette.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Utilities to interact with the command palette.
+ * @category Command Palette
+ */
+export type CommandPaletteSDK = {
+    /**
+     * Register a command.
+     * @param commandId The id of the command to register.
+     */
+    register: (commandId: string) => void;
+};

package/src/types/commands.d.ts

@@ -1,13 +1,50 @@
+import type { CommandID, ID } from "./utils";
+/**
+ * Utilities to interact with commands
+ * @category Commands
+ */
+export type CommandsSDK = {
+    /**
+     * Register a command.
+     * @param id The id of the command.
+     * @param options Options for the command.
+     * @param options.name The name of the command.
+     * @param options.run The function to run when the command is executed.
+     * @param options.group The group this command belongs to.
+     * @param options.when A function to determine if the command is available.
+     *
+     * @example
+     * ```ts
+     * sdk.commands.register("hello", {
+     *   name: "Print to console.",
+     *   run: () => console.log("Hello world!"),
+     *   group: "Custom Commands",
+     * });
+     * ```
+     */
+    register: (id: CommandID, options: {
+        name: string;
+        run: (context: CommandContext) => void;
+        group?: string;
+        when?: (context: CommandContext) => boolean;
+    }) => void;
+};
+/**
+ * Represents the context in which a command is executed.
+ * @category Commands
+ */
 export type CommandContext = CommandContextBase | CommandContextRequestRow | CommandContextRequest | CommandContextResponse;
 /**
  * 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.
+ * @category Commands
  */
 type CommandContextBase = {
     type: "BaseContext";
 };
 /**
  * The context for a command that is executed on a row in the request table.
+ * @category Commands
  */
 type CommandContextRequestRow = {
     type: "RequestRowContext";
@@ -15,7 +52,7 @@ type CommandContextRequestRow = {
      * The requests that are selected in the request table.
      */
     requests: {
-        id: string;
+        id: ID;
         host: string;
         port: number;
         path: string;
@@ -25,6 +62,7 @@ type CommandContextRequestRow = {
 };
 /**
  * The context for a command that is executed on a request pane.
+ * @category Commands
  */
 type CommandContextRequest = {
     type: "RequestContext";
@@ -46,6 +84,7 @@ type CommandContextRequest = {
 };
 /**
  * The context for a command that is executed on a response pane.
+ * @category Commands
  */
 type CommandContextResponse = {
     type: "ResponseContext";
@@ -53,7 +92,7 @@ type CommandContextResponse = {
      * The request that is associated with the response.
      */
     request: {
-        id: string;
+        id: ID;
         host: string;
         port: number;
         path: string;
@@ -64,7 +103,7 @@ type CommandContextResponse = {
      * The response that is currently open in the response pane.
      */
     response: {
-        id: string;
+        id: ID;
         raw: string;
         statusCode: number;
         roundtripTime: number;

package/src/types/editor.d.ts

@@ -21,12 +21,35 @@ export type Editor = {
      * Focus the editor.
      */
     focus: () => void;
+    /**
+     * Get the editor view.
+     * @returns The CodeMirror {@link https://codemirror.net/docs/ref/#view.EditorView EditorView}.
+     */
+    getEditorView: () => EditorView;
 };
 export type HTTPRequestEditor = {
+    /**
+     * Get the editor element.
+     * Append this to your DOM to display the editor.
+     * @returns The editor element.
+     */
     getElement: () => HTMLElement;
+    /**
+     * Get the editor view.
+     * @returns The CodeMirror {@link https://codemirror.net/docs/ref/#view.EditorView EditorView}.
+     */
     getEditorView: () => EditorView;
 };
 export type HTTPResponseEditor = {
+    /**
+     * Get the editor element.
+     * Append this to your DOM to display the editor.
+     * @returns The editor element.
+     */
     getElement: () => HTMLElement;
+    /**
+     * Get the editor view.
+     * @returns The CodeMirror {@link https://codemirror.net/docs/ref/#view.EditorView EditorView}.
+     */
     getEditorView: () => EditorView;
 };

package/src/types/findings.d.ts

@@ -1,11 +1,35 @@
+import type { ID } from "./utils";
 /**
- * Represents a finding.
+ * Utilities to interact with findings
+ * @category Findings
  */
-export type Finding = {
+export type FindingsSDK = {
+    /**
+     * Create a {@link Finding}.
+     * @param requestId The id of the request the finding is associated with.
+     * @param options Options for the finding.
+     * @param options.title The title of the finding.
+     * @param options.description The description of the finding.
+     * @param options.reporter The reporter of the finding.
+     * @param options.dedupeKey If a finding with the same deduplication key already exists, it will not create a new finding.
+     * @returns The created finding.
+     */
+    createFinding: (requestId: ID, options: {
+        title: string;
+        description?: string;
+        reporter: string;
+        dedupeKey?: string;
+    }) => Promise<Finding | undefined>;
+};
+/**
+ * Represents a {@link https://docs.caido.io/reference/features/logging/findings|Finding}.
+ * @category Findings
+ */
+type Finding = {
     /**
      * The ID of the finding.
      */
-    id: string;
+    id: ID;
     /**
      * The title of the finding.
      */
@@ -27,3 +51,4 @@ export type Finding = {
      */
     path: string;
 };
+export {};

package/src/types/index.d.ts

@@ -1,271 +1,73 @@
-import type { Sdk } from "./__generated__/graphql-sdk";
-import type { BackendEndpoints, BackendEvents, ToBackendRPC } from "./backend";
-import type { CommandContext } from "./commands";
-import type { Editor, HTTPRequestEditor, HTTPResponseEditor } from "./editor";
-import type { Finding } from "./findings";
-import type { MenuItem } from "./menu";
-import type { Scope } from "./scopes";
-import type { SidebarItem } from "./sidebar";
-import type { JSONCompatible, JSONValue } from "./utils";
+import type { Sdk as GraphqlSDK } from "./__generated__/graphql-sdk";
+import type { BackendEndpoints, BackendEvents, BackendSDK } from "./backend";
+import type { CommandPaletteSDK } from "./command_palette";
+import type { CommandsSDK } from "./commands";
+import type { FindingsSDK } from "./findings";
+import type { MenuSDK } from "./menu";
+import type { NavigationSDK } from "./navigation";
+import type { ScopesSDK } from "./scopes";
+import type { ShortcutsSDK } from "./shortcuts";
+import type { SidebarSDK } from "./sidebar";
+import type { StorageSDK } from "./storage";
+import type { UISDK } from "./ui";
+import type { WindowSDK } from "./window";
 export type { CommandContext } from "./commands";
 export type { MenuItem } from "./menu";
+/**
+ * Utilities for frontend plugins.
+ * @category SDK
+ */
 export type API<T extends BackendEndpoints = Record<string, never>, E extends BackendEvents = Record<string, never>> = {
-    graphql: Sdk;
-    backend: ToBackendRPC<T, E>;
+    /**
+     * Utilities to interact with the GraphQL API.
+     */
+    graphql: GraphqlSDK;
+    /**
+     * Utilities to interact with the backend plugin.
+     */
+    backend: BackendSDK<T, E>;
     /**
      * Utilities to create UI components.
      */
-    ui: {
-        /**
-         * Create a button.
-         * @param options Options for the button.
-         * @param options.variant The variant of the button.
-         * @param options.label The label of the button.
-         * @param options.leadingIcon The leading icon of the button.
-         * @param options.trailingIcon The trailing icon of the button.
-         * @param options.size The size of the button.
-         * @returns The button element.
-         */
-        button: (options?: {
-            variant?: "primary" | "secondary" | "tertiary";
-            label?: string;
-            leadingIcon?: string;
-            trailingIcon?: string;
-            size?: "small" | "medium" | "large";
-        }) => HTMLElement;
-        /**
-         * Create a card.
-         * @param options Options for the card.
-         * @param options.header The header of the card.
-         * @param options.body The body of the card.
-         * @param options.footer The footer of the card.
-         * @returns The card element.
-         */
-        card: (options?: {
-            header?: HTMLElement;
-            body?: HTMLElement;
-            footer?: HTMLElement;
-        }) => HTMLElement;
-        /**
-         * Create a well.
-         * @param options Options for the well.
-         * @param options.header The header of the well.
-         * @param options.body The body of the well.
-         * @param options.footer The footer of the well.
-         * @returns The well element.
-         */
-        well: (options?: {
-            header?: HTMLElement;
-            body?: HTMLElement;
-            footer?: HTMLElement;
-        }) => HTMLElement;
-        /**
-         * Create an HTTP request editor
-         * @returns The HTTP request editor.
-         */
-        httpRequestEditor: () => HTTPRequestEditor;
-        /**
-         * Create an HTTP response editor
-         * @returns The HTTP response editor.
-         */
-        httpResponseEditor: () => HTTPResponseEditor;
-    };
+    ui: UISDK;
     /**
      * Utilities to interact with scopes
      */
-    scopes: {
-        /**
-         * Get all scopes.
-         * @returns A list of scopes.
-         */
-        getScopes: () => Scope[];
-        /**
-         * Create a scope.
-         * @param options Options for the scope.
-         * @param options.name The name of the scope.
-         * @param options.allowlist The list of included items in the scope.
-         * @param options.denylist The list of excluded items in the scope.
-         * @returns The created scope.
-         */
-        createScope: (options: {
-            name: string;
-            allowlist: string[];
-            denylist: string[];
-        }) => Promise<Scope | undefined>;
-        /**
-         * Update a scope.
-         * @param id The id of the scope to update.
-         * @param options Options for the scope.
-         * @param options.name The name of the scope.
-         * @param options.allowlist The list of included items in the scope.
-         * @param options.denylist The list of excluded items in the scope.
-         * @returns The updated scope.
-         */
-        updateScope: (id: string, options: {
-            name?: string;
-            allowlist?: string[];
-            denylist?: string[];
-        }) => Promise<Scope | undefined>;
-        /**
-         * Delete a scope.
-         * @param id The id of the scope to delete.
-         * @returns Whether the scope was deleted.
-         */
-        deleteScope: (id: string) => Promise<boolean>;
-    };
+    scopes: ScopesSDK;
     /**
      * Utilities to interact with findings
      */
-    findings: {
-        /**
-         * Create a finding.
-         * @param requestId The id of the request the finding is associated with.
-         * @param options Options for the finding.
-         * @param options.title The title of the finding.
-         * @param options.description The description of the finding.
-         * @param options.reporter The reporter of the finding.
-         * @param options.dedupeKey The dedupe key of the finding.
-         * @returns The created finding.
-         */
-        createFinding: (requestId: string, options: {
-            title: string;
-            description?: string;
-            reporter: string;
-            dedupeKey?: string;
-        }) => Promise<Finding | undefined>;
-    };
+    findings: FindingsSDK;
     /**
      * Utilities to interact with commands
      */
-    commands: {
-        /**
-         * Register a command.
-         * @param id The id of the command.
-         * @param options Options for the command.
-         * @param options.name The name of the command.
-         * @param options.run The function to run when the command is executed.
-         * @param options.group The group this command belongs to.
-         * @param options.when A function to determine if the command is available.
-         */
-        register: (id: string, options: {
-            name: string;
-            run: (context: CommandContext) => void;
-            group?: string;
-            when?: (context: CommandContext) => boolean;
-        }) => void;
-    };
+    commands: CommandsSDK;
     /**
      * Utilities to insert menu items and context-menus throughout the UI.
      */
-    menu: {
-        /**
-         * Register a menu item.
-         * @param item The menu item to register.
-         */
-        registerItem: (item: MenuItem) => void;
-    };
+    menu: MenuSDK;
     /**
      * Utilities to interact with navigation.
      */
-    navigation: {
-        /**
-         * Navigate to a path.
-         * @param path The path to navigate to.
-         */
-        goTo: (path: string) => void;
-        /**
-         * Add a page to the navigation.
-         * @param path The path of the page.
-         * @param options Options for the page.
-         * @param options.body The body of the page.
-         * @param options.topbar The topbar of the page.
-         */
-        addPage: (path: string, options: {
-            body: HTMLElement;
-            topbar?: HTMLElement;
-        }) => void;
-    };
+    navigation: NavigationSDK;
     /**
      * Utilities to interact with the active page.
      */
-    window: {
-        /**
-         * Get the active editor.
-         * @returns The active editor.
-         */
-        getActiveEditor: () => Editor | undefined;
-        /**
-         * Show a toast message.
-         * @param message The message to show.
-         * @param options Options for the toast message.
-         * @param options.variant The variant of the toast message.
-         * @param options.duration The duration of the toast message in milliseconds.
-         */
-        showToast: (message: string, options?: {
-            variant?: "success" | "error" | "warning" | "info";
-            duration?: number;
-        }) => void;
-    };
+    window: WindowSDK;
     /**
      * Utilities to interact with frontend-plugin storage.
      */
-    storage: {
-        /**
-         * Get the storage.
-         * @returns The storage.
-         */
-        get: () => JSONValue;
-        /**
-         * Set the storage.
-         * @param value The value to set the storage to
-         * @returns A promise that resolves when the storage has been set.
-         */
-        set: <T>(value: JSONCompatible<T>) => Promise<void>;
-        /**
-         * Subscribe to storage changes.
-         * @param callback The callback to call when the storage changes.
-         */
-        onChange: (callback: (value: JSONValue) => void) => void;
-    };
+    storage: StorageSDK;
     /**
      * Utilities to interact with shortcuts.
      */
-    shortcuts: {
-        /**
-         * Register a shortcut.
-         * @param commandId The id of the command to run when the shortcut is triggered.
-         * @param keys The keys of the shortcut.
-         */
-        register: (commandId: string, keys: string[]) => void;
-    };
+    shortcuts: ShortcutsSDK;
     /**
      * Utilities to interact with the command palette.
      */
-    commandPalette: {
-        /**
-         * Register a command.
-         * @param commandId The id of the command to register.
-         */
-        register: (commandId: string) => void;
-    };
+    commandPalette: CommandPaletteSDK;
     /**
      * Utilities to interact with the sidebar.
      */
-    sidebar: {
-        /**
-         * Register a sidebar item.
-         * @param name The name of the sidebar item.
-         * @param path The path that the user will be navigated to when the sidebar item is clicked.
-         * @param options Options for the sidebar item.
-         * @param options.icon The icon of the sidebar item.
-         * @param options.group The group the sidebar item belongs to.
-         * @param options.isExternal Whether the path points to an external URL.
-         * @returns The created sidebar item.
-         */
-        registerItem: (name: string, path: string, options?: {
-            icon?: string;
-            group?: string;
-            isExternal?: boolean;
-        }) => SidebarItem;
-    };
+    sidebar: SidebarSDK;
 };

package/src/types/menu.d.ts

@@ -1,13 +1,39 @@
+import type { CommandID, Icon } from "./utils";
+/**
+ * Utilities to insert menu items and context-menus throughout the UI.
+ * @category Menu
+ */
+export type MenuSDK = {
+    /**
+     * Register a menu item.
+     * @param item The menu item to register.
+     *
+     * @example
+     * ```ts
+     * sdk.menu.registerItem({
+     *   type: "Request",
+     *   commandId: "hello",
+     *   leadingIcon: "fas fa-hand",
+     * });
+     * ```
+     */
+    registerItem: (item: MenuItem) => void;
+};
+/**
+ * A content-menu item.
+ * @category Menu
+ */
 export type MenuItem = RequestRowMenuItem | SettingsMenuItem | RequestMenuItem | ResponseMenuItem;
 /**
  * A context-menu item that appears when right-clicking a request row.
+ * @category Menu
  */
 type RequestRowMenuItem = {
     type: "RequestRow";
     /**
      * The command ID to execute when the menu item is clicked.
      */
-    commandId: string;
+    commandId: CommandID;
     /**
      * The icon to display to the left of the menu item.
      */
@@ -15,13 +41,14 @@ type RequestRowMenuItem = {
 };
 /**
  * A context-menu item that appears when right-clicking a request pane.
+ * @category Menu
  */
 type RequestMenuItem = {
     type: "Request";
     /**
      * The command ID to execute when the menu item is clicked.
      */
-    commandId: string;
+    commandId: CommandID;
     /**
      * The icon to display to the left of the menu item.
      */
@@ -29,13 +56,14 @@ type RequestMenuItem = {
 };
 /**
  * A context-menu item that appears when right-clicking a response pane.
+ * @category Menu
  */
 type ResponseMenuItem = {
     type: "Response";
     /**
      * The command ID to execute when the menu item is
      */
-    commandId: string;
+    commandId: CommandID;
     /**
      * The icon to display to the left of the menu item.
      */
@@ -43,6 +71,7 @@ type ResponseMenuItem = {
 };
 /**
  * A menu item that appears in the settings menu.
+ * @category Menu
  */
 type SettingsMenuItem = {
     type: "Settings";
@@ -52,11 +81,12 @@ type SettingsMenuItem = {
     label: string;
     /**
      * The path that the user will be navigated to when the menu item is clicked
+     * The path must start with "/settings/".
      */
     path: string;
     /**
-     * The icon to display to the left of the menu item.
+     * The {@link Icon} to display to the left of the menu item.
      */
-    leadingIcon?: string;
+    leadingIcon?: Icon;
 };
 export {};

package/src/types/navigation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Utilities to interact with navigation.
+ * @category Navigation
+ */
+export type NavigationSDK = {
+    /**
+     * Navigate to a path.
+     * @param path The path to navigate to.
+     *
+     * @example
+     * ```ts
+     * sdk.navigation.goTo("/my-plugin-page");
+     * ```
+     */
+    goTo: (path: string) => void;
+    /**
+     * Add a page to the navigation.
+     * @param path The path of the page.
+     * @param options Options for the page.
+     * @param options.body The body of the page.
+     * @param options.topbar The topbar of the page.
+     */
+    addPage: (path: string, options: {
+        body: HTMLElement;
+        topbar?: HTMLElement;
+    }) => void;
+};

package/src/types/scopes.d.ts

@@ -1,11 +1,66 @@
+import type { ID } from "./utils";
+/**
+ * Utilities to interact with scopes
+ * @category Scopes
+ */
+export type ScopesSDK = {
+    /**
+     * Get all scopes.
+     * @returns A list of scopes.
+     */
+    getScopes: () => Scope[];
+    /**
+     * Create a scope.
+     * @param options Options for the scope.
+     * @param options.name The name of the scope.
+     * @param options.allowlist The list of included items in the scope.
+     * @param options.denylist The list of excluded items in the scope.
+     * @returns The created scope.
+     *
+     * @example
+     * ```ts
+     * const newScope = await sdk.scopes.createScope({
+     *   name: "Example",
+     *   allowlist: ["*example.com", "*github.com"],
+     *   denylist: ["*caido.io"],
+     * });
+     * ```
+     */
+    createScope: (options: {
+        name: string;
+        allowlist: string[];
+        denylist: string[];
+    }) => Promise<Scope | undefined>;
+    /**
+     * Update a scope.
+     * @param id The id of the scope to update.
+     * @param options Options for the scope.
+     * @param options.name The name of the scope.
+     * @param options.allowlist The list of included items in the scope.
+     * @param options.denylist The list of excluded items in the scope.
+     * @returns The updated scope.
+     */
+    updateScope: (id: ID, options: {
+        name?: string;
+        allowlist?: string[];
+        denylist?: string[];
+    }) => Promise<Scope | undefined>;
+    /**
+     * Delete a scope.
+     * @param id The id of the scope to delete.
+     * @returns Whether the scope was deleted.
+     */
+    deleteScope: (id: ID) => Promise<boolean>;
+};
 /**
  * Represents a scope.
+ * @category Scopes
  */
-export type Scope = {
+type Scope = {
     /**
      * The unique ID of the scope.
      */
-    id: string;
+    id: ID;
     /**
      * The name of the scope.
      */
@@ -19,3 +74,4 @@ export type Scope = {
      */
     denylist: string[];
 };
+export {};

package/src/types/shortcuts.d.ts

@@ -0,0 +1,13 @@
+import type { CommandID } from "./utils";
+/**
+ * Utilities to interact with shortcuts.
+ * @category Shortcuts
+ */
+export type ShortcutsSDK = {
+    /**
+     * Register a shortcut.
+     * @param commandId The id of the command to run when the shortcut is triggered.
+     * @param keys The keys of the shortcut.
+     */
+    register: (commandId: CommandID, keys: string[]) => void;
+};

package/src/types/sidebar.d.ts

@@ -1,10 +1,41 @@
+import type { Icon } from "./utils";
+/**
+ * Utilities to interact with the sidebar.
+ * @category Sidebar
+ */
+export type SidebarSDK = {
+    /**
+     * Register a sidebar item.
+     * @param name The name of the sidebar item.
+     * @param path The path that the user will be navigated to when the sidebar item is clicked.
+     * @param options Options for the sidebar item.
+     * @param options.icon The {@link Icon} of the sidebar item.
+     * @param options.group The group the sidebar item belongs to.
+     * @param options.isExternal Whether the path points to an external URL.
+     * @returns The created sidebar item.
+     *
+     * @example
+     * ```ts
+     * sdk.sidebar.registerItem("My Plugin", "/my-plugin-page", {
+     *   icon: "fas fa-rocket",
+     * });
+     * ```
+     */
+    registerItem: (name: string, path: string, options?: {
+        icon?: Icon;
+        group?: string;
+        isExternal?: boolean;
+    }) => SidebarItem;
+};
 /**
  * Represents a sidebar item.
+ * @category Sidebar
  */
-export type SidebarItem = {
+type SidebarItem = {
     /**
      * Set the value of a notification badge next to the sidebar item.
      * @param count - The number to display in the badge. A value of 0 will hide the badge.
      */
     setCount: (count: number) => void;
 };
+export {};

package/src/types/storage.d.ts

@@ -0,0 +1,23 @@
+import type { JSONCompatible, JSONValue } from "./utils";
+/**
+ * Utilities to interact with frontend-plugin storage.
+ * @category Storage
+ */
+export type StorageSDK = {
+    /**
+     * Get the storage.
+     * @returns The storage.
+     */
+    get: () => JSONValue;
+    /**
+     * Set the storage.
+     * @param value The value to set the storage to
+     * @returns A promise that resolves when the storage has been set.
+     */
+    set: <T>(value: JSONCompatible<T>) => Promise<void>;
+    /**
+     * Subscribe to storage changes.
+     * @param callback The callback to call when the storage changes.
+     */
+    onChange: (callback: (value: JSONValue) => void) => void;
+};

package/src/types/ui.d.ts

@@ -0,0 +1,71 @@
+import type { HTTPRequestEditor, HTTPResponseEditor } from "./editor";
+import type { Icon } from "./utils";
+/**
+ * Utilities to create UI components.
+ * @category UI
+ */
+export type UISDK = {
+    /**
+     * Create a button.
+     * @param options Options for the button.
+     * @param options.variant The variant of the button.
+     * @param options.label The label of the button.
+     * @param options.leadingIcon The leading icon of the button.
+     * @param options.trailingIcon The trailing icon of the button.
+     * @param options.size The size of the button.
+     * @returns The button element.
+     *
+     * @example
+     * ```ts
+     * const deleteButton = sdk.ui.button({
+     *   variant: "primary",
+     *   label: "Delete",
+     *   trailingIcon: "fas fa-trash-can",
+     *   size: "small",
+     * });
+     * ```
+     */
+    button: (options?: {
+        variant?: "primary" | "secondary" | "tertiary";
+        label?: string;
+        leadingIcon?: Icon;
+        trailingIcon?: Icon;
+        size?: "small" | "medium" | "large";
+    }) => HTMLElement;
+    /**
+     * Create a card.
+     * @param options Options for the card.
+     * @param options.header The header of the card.
+     * @param options.body The body of the card.
+     * @param options.footer The footer of the card.
+     * @returns The card element.
+     */
+    card: (options?: {
+        header?: HTMLElement;
+        body?: HTMLElement;
+        footer?: HTMLElement;
+    }) => HTMLElement;
+    /**
+     * Create a well.
+     * @param options Options for the well.
+     * @param options.header The header of the well.
+     * @param options.body The body of the well.
+     * @param options.footer The footer of the well.
+     * @returns The well element.
+     */
+    well: (options?: {
+        header?: HTMLElement;
+        body?: HTMLElement;
+        footer?: HTMLElement;
+    }) => HTMLElement;
+    /**
+     * Create an HTTP request editor
+     * @returns The HTTP request editor.
+     */
+    httpRequestEditor: () => HTTPRequestEditor;
+    /**
+     * Create an HTTP response editor
+     * @returns The HTTP response editor.
+     */
+    httpResponseEditor: () => HTTPResponseEditor;
+};

package/src/types/utils.d.ts

@@ -1,4 +1,24 @@
 type JSONPrimitive = string | number | boolean | null | undefined;
+/**
+ * A unique Caido identifier per type.
+ */
+export type ID = string & {
+    __id?: never;
+};
+/**
+ * A unique command identifier.
+ * @example "my-super-command"
+ */
+export type CommandID = string & {
+    __commandId?: never;
+};
+/**
+ * A {@link https://fontawesome.com/icons|FontAwesome} icon class.
+ * @example "fas fa-rocket"
+ */
+export type Icon = string & {
+    __icon?: never;
+};
 export type JSONValue = JSONPrimitive | JSONValue[] | {
     [key: string]: JSONValue;
 };

package/src/types/window.d.ts

@@ -0,0 +1,23 @@
+import type { Editor } from "./editor";
+/**
+ * Utilities to interact with the active page.
+ * @category Window
+ */
+export type WindowSDK = {
+    /**
+     * Get the active editor.
+     * @returns The active editor.
+     */
+    getActiveEditor: () => Editor | undefined;
+    /**
+     * Show a toast message.
+     * @param message The message to show.
+     * @param options Options for the toast message.
+     * @param options.variant The variant of the toast message.
+     * @param options.duration The duration of the toast message in milliseconds.
+     */
+    showToast: (message: string, options?: {
+        variant?: "success" | "error" | "warning" | "info";
+        duration?: number;
+    }) => void;
+};