@caido/sdk-frontend 0.40.1-beta.0 → 0.40.1-beta.1

package/package.json

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

package/src/types/commands.d.ts

@@ -1,17 +1,19 @@
-export type Commands = {
-    register: (id: string, options: CommandOptions) => void;
-};
-type CommandOptions = {
-    name: string;
-    run: (context: CommandContext) => void;
-    group?: string;
-    when?: (context: CommandContext) => boolean;
-};
+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.
+ */
 type CommandContextBase = {
     type: "BaseContext";
 };
+/**
+ * The context for a command that is executed on a row in the request table.
+ */
 type CommandContextRequestRow = {
     type: "RequestRowContext";
+    /**
+     * The requests that are selected in the request table.
+     */
     requests: {
         id: string;
         host: string;
@@ -21,8 +23,14 @@ type CommandContextRequestRow = {
         isTls: boolean;
     }[];
 };
+/**
+ * The context for a command that is executed on a request pane.
+ */
 type CommandContextRequest = {
     type: "RequestContext";
+    /**
+     * The request that is currently open in the request pane.
+     */
     request: {
         host: string;
         port: number;
@@ -31,10 +39,19 @@ type CommandContextRequest = {
         isTls: boolean;
         raw: string;
     };
+    /**
+     * The currently selected text in the request pane.
+     */
     selection: string;
 };
+/**
+ * The context for a command that is executed on a response pane.
+ */
 type CommandContextResponse = {
     type: "ResponseContext";
+    /**
+     * The request that is associated with the response.
+     */
     request: {
         id: string;
         host: string;
@@ -43,13 +60,18 @@ type CommandContextResponse = {
         query: string;
         isTls: boolean;
     };
+    /**
+     * The response that is currently open in the response pane.
+     */
     response: {
         id: string;
         raw: string;
         statusCode: number;
         roundtripTime: number;
     };
+    /**
+     * The currently selected text in the response pane.
+     */
     selection: string;
 };
-export type CommandContext = CommandContextBase | CommandContextRequestRow | CommandContextRequest | CommandContextResponse;
 export {};

package/src/types/editor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generic editor interface.
+ */
+export type Editor = {
+    /**
+     * Get the currently selected text of the editor.
+     */
+    getSelectedText: () => string;
+    /**
+     * Replace the currently selected text of the editor.
+     * @param text The text to replace the selection with.
+     */
+    replaceSelectedText: (text: string) => void;
+    /**
+     * Check whether the editor is read-only.
+     * @returns Whether the editor is read-only.
+     */
+    isReadOnly: () => boolean;
+    /**
+     * Focus the editor.
+     */
+    focus: () => void;
+};

package/src/types/findings.d.ts

@@ -1,18 +1,29 @@
-export type Findings = {
-    createFinding: (requestId: string, options: CreateFindingsOptions) => Promise<Finding | undefined>;
-};
-type Finding = {
+/**
+ * Represents a finding.
+ */
+export type Finding = {
+    /**
+     * The ID of the finding.
+     */
     id: string;
+    /**
+     * The title of the finding.
+     */
     title: string;
+    /**
+     * The description of the finding.
+     */
     description?: string;
+    /**
+     * The reporter of the finding.
+     */
     reporter: string;
+    /**
+     * The host of the request attached to this finding
+     */
     host: string;
+    /**
+     * The path of the request attached to this finding
+     */
     path: string;
 };
-type CreateFindingsOptions = {
-    title: string;
-    description?: string;
-    reporter: string;
-    dedupeKey?: string;
-};
-export {};

package/src/types/index.d.ts

@@ -1,40 +1,261 @@
 import type { Sdk } from "./__generated__/graphql-sdk";
 import type { BackendEndpoints, BackendEvents, ToBackendRPC } from "./backend";
-import type { Commands } from "./commands";
-import type { Findings } from "./findings";
-import type { Menu } from "./menu";
-import type { Navigation } from "./navigation";
-import type { Scopes } from "./scopes";
-import type { Storage } from "./storage";
-import type { UI } from "./ui";
-import type { Window } from "./window";
+import type { CommandContext } from "./commands";
+import type { Editor } 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";
 export type { CommandContext } from "./commands";
+export type { MenuItem } from "./menu";
 export type API<T extends BackendEndpoints = Record<string, never>, E extends BackendEvents = Record<string, never>> = {
-    ui: UI;
+    graphql: Sdk;
     backend: ToBackendRPC<T, E>;
-    scopes: Scopes;
-    findings: Findings;
-    commands: Commands;
-    menu: Menu;
-    navigation: Navigation;
-    window: Window;
-    storage: Storage;
+    /**
+     * 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;
+    };
+    /**
+     * 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>;
+    };
+    /**
+     * 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>;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * 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;
     };
+    /**
+     * Utilities to interact with the command palette.
+     */
     commandPalette: {
+        /**
+         * Register a command.
+         * @param commandId The id of the command to register.
+         */
         register: (commandId: string) => void;
     };
+    /**
+     * Utilities to interact with the sidebar.
+     */
     sidebar: {
-        registerItem: (name: string, path: string, options?: SidebarItemOptions) => SidebarItem;
+        /**
+         * 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;
     };
-    graphql: Sdk;
-};
-type SidebarItemOptions = {
-    icon?: string;
-    group?: string;
-    isExternal?: boolean;
-};
-type SidebarItem = {
-    setCount: (count: number) => void;
 };

package/src/types/menu.d.ts

@@ -1,26 +1,62 @@
-export type Menu = {
-    registerItem: (item: MenuItem) => void;
-};
-type MenuItem = RequestRowMenuItem | SettingsMenuItem | RequestMenuItem | ResponseMenuItem;
+export type MenuItem = RequestRowMenuItem | SettingsMenuItem | RequestMenuItem | ResponseMenuItem;
+/**
+ * A context-menu item that appears when right-clicking a request row.
+ */
 type RequestRowMenuItem = {
     type: "RequestRow";
+    /**
+     * The command ID to execute when the menu item is clicked.
+     */
     commandId: string;
+    /**
+     * The icon to display to the left of the menu item.
+     */
     leadingIcon?: string;
 };
+/**
+ * A context-menu item that appears when right-clicking a request pane.
+ */
 type RequestMenuItem = {
     type: "Request";
+    /**
+     * The command ID to execute when the menu item is clicked.
+     */
     commandId: string;
+    /**
+     * The icon to display to the left of the menu item.
+     */
     leadingIcon?: string;
 };
+/**
+ * A context-menu item that appears when right-clicking a response pane.
+ */
 type ResponseMenuItem = {
     type: "Response";
+    /**
+     * The command ID to execute when the menu item is
+     */
     commandId: string;
+    /**
+     * The icon to display to the left of the menu item.
+     */
     leadingIcon?: string;
 };
+/**
+ * A menu item that appears in the settings menu.
+ */
 type SettingsMenuItem = {
     type: "Settings";
+    /**
+     * The label of the menu item.
+     */
     label: string;
+    /**
+     * The path that the user will be navigated to when the menu item is clicked
+     */
     path: string;
+    /**
+     * The icon to display to the left of the menu item.
+     */
     leadingIcon?: string;
 };
 export {};

package/src/types/scopes.d.ts

@@ -1,23 +1,21 @@
-export type Scopes = {
-    getScopes: () => Scope[];
-    createScope: (options: CreateScopeOptions) => Promise<Scope | undefined>;
-    updateScope: (id: string, options: UpdateScopeOptions) => Promise<Scope | undefined>;
-    deleteScope: (id: string) => Promise<boolean>;
-};
-type Scope = {
+/**
+ * Represents a scope.
+ */
+export type Scope = {
+    /**
+     * The unique ID of the scope.
+     */
     id: string;
+    /**
+     * The name of the scope.
+     */
     name: string;
+    /**
+     * The list of included items.
+     */
     allowlist: string[];
+    /**
+     * The list of excluded items.
+     */
     denylist: string[];
 };
-type CreateScopeOptions = {
-    name: string;
-    allowlist: string[];
-    denylist: string[];
-};
-type UpdateScopeOptions = {
-    name?: string;
-    allowlist?: string[];
-    denylist?: string[];
-};
-export {};

package/src/types/sidebar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Represents a sidebar item.
+ */
+export 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;
+};