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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caido/sdk-frontend",
-  "version": "0.40.0",
+  "version": "0.40.1-beta.1",
   "description": "Typing for the Caido Frontend SDK",
   "author": "Caido Labs Inc. <dev@caido.io>",
   "license": "MIT",
@@ -9,5 +9,7 @@
   "module": "./src/index.js",
   "files": [
     "src/*"
-  ]
+  ],
+  "peerDependencies": {},
+  "peerDependenciesMeta": {}
 }

package/src/types/__generated__/graphql-sdk.d.ts

@@ -82,6 +82,10 @@ export type Scalars = {
         input: JSONValue;
         output: JSONValue;
     };
+    JsonRaw: {
+        input: string;
+        output: string;
+    };
     Port: {
         input: number;
         output: number;
@@ -785,6 +789,11 @@ export type CreatedInterceptMessagePayload = {
     messageEdge: InterceptMessageEdge;
     snapshot: Scalars["Snapshot"]["output"];
 };
+export type CreatedPluginEventPayload = {
+    eventArgs: Array<Scalars["JsonRaw"]["output"]>;
+    eventName: Scalars["String"]["output"];
+    pluginId: Scalars["ID"]["output"];
+};
 export type CreatedPluginPackagePayload = {
     package: PluginPackage;
 };
@@ -2627,7 +2636,7 @@ export type StartExportRequestsTaskPayload = {
     task?: Maybe<DataExportTask>;
 };
 export type StartExportRequestsTaskPayloadError = OtherUserError | PermissionDeniedUserError;
-export type StartReplayTaskError = OtherUserError | TaskInProgressUserError;
+export type StartReplayTaskError = OtherUserError | PermissionDeniedUserError | TaskInProgressUserError;
 export type StartReplayTaskInput = {
     connection: ConnectionInfoInput;
     raw: Scalars["Blob"]["input"];
@@ -2758,6 +2767,7 @@ export type SubscriptionRoot = {
     createdFinding: CreatedFindingPayload;
     createdInterceptEntry: CreatedInterceptEntryPayload;
     createdInterceptMessage: CreatedInterceptMessagePayload;
+    createdPluginEvent: CreatedPluginEventPayload;
     createdPluginPackage: CreatedPluginPackagePayload;
     createdProject: CreatedProjectPayload;
     createdReplaySession: CreatedReplaySessionPayload;
@@ -8217,6 +8227,10 @@ export type StartReplayTaskMutation = {
         error?: {
             __typename: "OtherUserError";
             code: string;
+        } | {
+            __typename: "PermissionDeniedUserError";
+            code: string;
+            permissionDeniedReason: PermissionDeniedErrorReason;
         } | {
             __typename: "TaskInProgressUserError";
             taskId: string;
@@ -12803,6 +12817,16 @@ export type UpdatedPluginSubscription = {
         };
     };
 };
+export type CreatedPluginEventSubscriptionVariables = Exact<{
+    [key: string]: never;
+}>;
+export type CreatedPluginEventSubscription = {
+    createdPluginEvent: {
+        pluginId: string;
+        eventArgs: Array<string>;
+        eventName: string;
+    };
+};
 export type CreatedProjectSubscriptionVariables = Exact<{
     [key: string]: never;
 }>;
@@ -13707,7 +13731,7 @@ export declare const SetActiveReplaySessionEntryDocument = "\n    mutation setAc
 export declare const DeleteReplaySessionsDocument = "\n    mutation deleteReplaySessions($ids: [ID!]!) {\n  deleteReplaySessions(ids: $ids) {\n    deletedIds\n  }\n}\n    ";
 export declare const CreateReplaySessionDocument = "\n    mutation createReplaySession($input: CreateReplaySessionInput!) {\n  createReplaySession(input: $input) {\n    session {\n      ...replaySessionMeta\n      collection {\n        ...replaySessionCollectionMeta\n      }\n    }\n  }\n}\n    \n    fragment replaySessionMeta on ReplaySession {\n  __typename\n  id\n  name\n  activeEntry {\n    ...replayEntryMeta\n  }\n  collection {\n    id\n  }\n  entries {\n    nodes {\n      ...replayEntryMeta\n    }\n    pageInfo {\n      ...pageInfoFull\n    }\n    count {\n      ...countFull\n    }\n  }\n}\n    \n\n    fragment replayEntryMeta on ReplayEntry {\n  __typename\n  id\n  error\n  connection {\n    ...connectionInfoFull\n  }\n  session {\n    id\n  }\n  request {\n    ...requestMeta\n  }\n}\n    \n\n    fragment connectionInfoFull on ConnectionInfo {\n  __typename\n  host\n  port\n  isTls\n}\n    \n\n    fragment requestMeta on Request {\n  __typename\n  id\n  host\n  port\n  path\n  query\n  method\n  edited\n  isTls\n  length\n  alteration\n  metadata {\n    ...requestMetadataFull\n  }\n  fileExtension\n  source\n  createdAt\n  response {\n    ...responseMeta\n  }\n}\n    \n\n    fragment requestMetadataFull on RequestMetadata {\n  __typename\n  id\n  color\n}\n    \n\n    fragment responseMeta on Response {\n  __typename\n  id\n  statusCode\n  roundtripTime\n  length\n  createdAt\n  alteration\n  edited\n}\n    \n\n    fragment pageInfoFull on PageInfo {\n  __typename\n  hasPreviousPage\n  hasNextPage\n  startCursor\n  endCursor\n}\n    \n\n    fragment countFull on Count {\n  __typename\n  value\n  snapshot\n}\n    \n\n    fragment replaySessionCollectionMeta on ReplaySessionCollection {\n  __typename\n  id\n  name\n  sessions {\n    ...replaySessionMeta\n  }\n}\n    ";
 export declare const MoveReplaySessionDocument = "\n    mutation moveReplaySession($id: ID!, $collectionId: ID!) {\n  moveReplaySession(collectionId: $collectionId, id: $id) {\n    session {\n      ...replaySessionMeta\n    }\n  }\n}\n    \n    fragment replaySessionMeta on ReplaySession {\n  __typename\n  id\n  name\n  activeEntry {\n    ...replayEntryMeta\n  }\n  collection {\n    id\n  }\n  entries {\n    nodes {\n      ...replayEntryMeta\n    }\n    pageInfo {\n      ...pageInfoFull\n    }\n    count {\n      ...countFull\n    }\n  }\n}\n    \n\n    fragment replayEntryMeta on ReplayEntry {\n  __typename\n  id\n  error\n  connection {\n    ...connectionInfoFull\n  }\n  session {\n    id\n  }\n  request {\n    ...requestMeta\n  }\n}\n    \n\n    fragment connectionInfoFull on ConnectionInfo {\n  __typename\n  host\n  port\n  isTls\n}\n    \n\n    fragment requestMeta on Request {\n  __typename\n  id\n  host\n  port\n  path\n  query\n  method\n  edited\n  isTls\n  length\n  alteration\n  metadata {\n    ...requestMetadataFull\n  }\n  fileExtension\n  source\n  createdAt\n  response {\n    ...responseMeta\n  }\n}\n    \n\n    fragment requestMetadataFull on RequestMetadata {\n  __typename\n  id\n  color\n}\n    \n\n    fragment responseMeta on Response {\n  __typename\n  id\n  statusCode\n  roundtripTime\n  length\n  createdAt\n  alteration\n  edited\n}\n    \n\n    fragment pageInfoFull on PageInfo {\n  __typename\n  hasPreviousPage\n  hasNextPage\n  startCursor\n  endCursor\n}\n    \n\n    fragment countFull on Count {\n  __typename\n  value\n  snapshot\n}\n    ";
-export declare const StartReplayTaskDocument = "\n    mutation startReplayTask($sessionId: ID!, $input: StartReplayTaskInput!) {\n  startReplayTask(sessionId: $sessionId, input: $input) {\n    task {\n      ...replayTaskMeta\n    }\n    error {\n      ... on TaskInProgressUserError {\n        ...taskInProgressUserErrorFull\n      }\n      ... on OtherUserError {\n        ...otherUserErrorFull\n      }\n    }\n  }\n}\n    \n    fragment replayTaskMeta on ReplayTask {\n  ...taskMeta\n  replayEntry {\n    ...replayEntryMeta\n  }\n}\n    \n\n    fragment taskMeta on Task {\n  __typename\n  id\n  createdAt\n}\n    \n\n    fragment replayEntryMeta on ReplayEntry {\n  __typename\n  id\n  error\n  connection {\n    ...connectionInfoFull\n  }\n  session {\n    id\n  }\n  request {\n    ...requestMeta\n  }\n}\n    \n\n    fragment connectionInfoFull on ConnectionInfo {\n  __typename\n  host\n  port\n  isTls\n}\n    \n\n    fragment requestMeta on Request {\n  __typename\n  id\n  host\n  port\n  path\n  query\n  method\n  edited\n  isTls\n  length\n  alteration\n  metadata {\n    ...requestMetadataFull\n  }\n  fileExtension\n  source\n  createdAt\n  response {\n    ...responseMeta\n  }\n}\n    \n\n    fragment requestMetadataFull on RequestMetadata {\n  __typename\n  id\n  color\n}\n    \n\n    fragment responseMeta on Response {\n  __typename\n  id\n  statusCode\n  roundtripTime\n  length\n  createdAt\n  alteration\n  edited\n}\n    \n\n    fragment taskInProgressUserErrorFull on TaskInProgressUserError {\n  ...userErrorFull\n  taskId\n}\n    \n\n    fragment userErrorFull on UserError {\n  __typename\n  code\n}\n    \n\n    fragment otherUserErrorFull on OtherUserError {\n  ...userErrorFull\n}\n    ";
+export declare const StartReplayTaskDocument = "\n    mutation startReplayTask($sessionId: ID!, $input: StartReplayTaskInput!) {\n  startReplayTask(sessionId: $sessionId, input: $input) {\n    task {\n      ...replayTaskMeta\n    }\n    error {\n      ... on TaskInProgressUserError {\n        ...taskInProgressUserErrorFull\n      }\n      ... on PermissionDeniedUserError {\n        ...permissionDeniedUserErrorFull\n      }\n      ... on OtherUserError {\n        ...otherUserErrorFull\n      }\n    }\n  }\n}\n    \n    fragment replayTaskMeta on ReplayTask {\n  ...taskMeta\n  replayEntry {\n    ...replayEntryMeta\n  }\n}\n    \n\n    fragment taskMeta on Task {\n  __typename\n  id\n  createdAt\n}\n    \n\n    fragment replayEntryMeta on ReplayEntry {\n  __typename\n  id\n  error\n  connection {\n    ...connectionInfoFull\n  }\n  session {\n    id\n  }\n  request {\n    ...requestMeta\n  }\n}\n    \n\n    fragment connectionInfoFull on ConnectionInfo {\n  __typename\n  host\n  port\n  isTls\n}\n    \n\n    fragment requestMeta on Request {\n  __typename\n  id\n  host\n  port\n  path\n  query\n  method\n  edited\n  isTls\n  length\n  alteration\n  metadata {\n    ...requestMetadataFull\n  }\n  fileExtension\n  source\n  createdAt\n  response {\n    ...responseMeta\n  }\n}\n    \n\n    fragment requestMetadataFull on RequestMetadata {\n  __typename\n  id\n  color\n}\n    \n\n    fragment responseMeta on Response {\n  __typename\n  id\n  statusCode\n  roundtripTime\n  length\n  createdAt\n  alteration\n  edited\n}\n    \n\n    fragment taskInProgressUserErrorFull on TaskInProgressUserError {\n  ...userErrorFull\n  taskId\n}\n    \n\n    fragment userErrorFull on UserError {\n  __typename\n  code\n}\n    \n\n    fragment permissionDeniedUserErrorFull on PermissionDeniedUserError {\n  ...userErrorFull\n  permissionDeniedReason: reason\n}\n    \n\n    fragment otherUserErrorFull on OtherUserError {\n  ...userErrorFull\n}\n    ";
 export declare const UpdateRequestMetadataDocument = "\n    mutation updateRequestMetadata($id: ID!, $input: UpdateRequestMetadataInput!) {\n  updateRequestMetadata(id: $id, input: $input) {\n    snapshot\n    metadata {\n      ...requestMetadataFull\n    }\n  }\n}\n    \n    fragment requestMetadataFull on RequestMetadata {\n  __typename\n  id\n  color\n}\n    ";
 export declare const StartExportRequestsTaskDocument = "\n    mutation startExportRequestsTask($input: StartExportRequestsTaskInput!) {\n  startExportRequestsTask(input: $input) {\n    task {\n      ...dataExportTaskMeta\n    }\n    error {\n      ... on OtherUserError {\n        ...otherUserErrorFull\n      }\n      ... on PermissionDeniedUserError {\n        ...permissionDeniedUserErrorFull\n      }\n    }\n  }\n}\n    \n    fragment dataExportTaskMeta on DataExportTask {\n  ...dataExportTaskMetaFields\n}\n    \n\n    fragment dataExportTaskMetaFields on DataExportTask {\n  __typename\n  id\n  export {\n    ...dataExportMeta\n  }\n}\n    \n\n    fragment dataExportMeta on DataExport {\n  ...dataExportMetaFields\n}\n    \n\n    fragment dataExportMetaFields on DataExport {\n  __typename\n  id\n  name\n  path\n  size\n  status\n  format\n  error\n  createdAt\n}\n    \n\n    fragment otherUserErrorFull on OtherUserError {\n  ...userErrorFull\n}\n    \n\n    fragment userErrorFull on UserError {\n  __typename\n  code\n}\n    \n\n    fragment permissionDeniedUserErrorFull on PermissionDeniedUserError {\n  ...userErrorFull\n  permissionDeniedReason: reason\n}\n    ";
 export declare const RenderRequestDocument = "\n    mutation renderRequest($id: ID!, $input: RenderRequestInput!) {\n  renderRequest(id: $id, input: $input) {\n    render\n    error {\n      ... on RenderFailedUserError {\n        ...renderFailedUserErrorFull\n      }\n      ... on OtherUserError {\n        ...otherUserErrorFull\n      }\n    }\n  }\n}\n    \n    fragment renderFailedUserErrorFull on RenderFailedUserError {\n  ...userErrorFull\n  reason\n}\n    \n\n    fragment userErrorFull on UserError {\n  __typename\n  code\n}\n    \n\n    fragment otherUserErrorFull on OtherUserError {\n  ...userErrorFull\n}\n    ";
@@ -13849,6 +13873,7 @@ export declare const UpdatedInterceptOptionsDocument = "\n    subscription updat
 export declare const CreatedPluginPackageDocument = "\n    subscription createdPluginPackage {\n  createdPluginPackage {\n    package {\n      ...pluginPackageFull\n    }\n  }\n}\n    \n    fragment pluginPackageFull on PluginPackage {\n  ...pluginPackageMeta\n  plugins {\n    ... on PluginFrontend {\n      ...pluginFrontendFull\n    }\n    ... on PluginBackend {\n      ...pluginBackendFull\n    }\n  }\n}\n    \n\n    fragment pluginPackageMeta on PluginPackage {\n  id\n  name\n  description\n  author {\n    ...pluginAuthorFull\n  }\n  version\n  installedAt\n  manifestId\n}\n    \n\n    fragment pluginAuthorFull on PluginAuthor {\n  name\n  email\n  url\n}\n    \n\n    fragment pluginFrontendFull on PluginFrontend {\n  ...pluginMeta\n  entrypoint\n  style\n  data\n  backend {\n    ...pluginBackendMeta\n  }\n}\n    \n\n    fragment pluginMeta on Plugin {\n  __typename\n  id\n  name\n  enabled\n  manifestId\n  package {\n    id\n  }\n}\n    \n\n    fragment pluginBackendMeta on PluginBackend {\n  __typename\n  id\n}\n    \n\n    fragment pluginBackendFull on PluginBackend {\n  ...pluginMeta\n  runtime\n  state {\n    error\n    running\n  }\n}\n    ";
 export declare const DeletedPluginPackageDocument = "\n    subscription deletedPluginPackage {\n  deletedPluginPackage {\n    deletedPackageId\n  }\n}\n    ";
 export declare const UpdatedPluginDocument = "\n    subscription updatedPlugin {\n  updatedPlugin {\n    plugin {\n      ... on PluginFrontend {\n        ...pluginFrontendFull\n      }\n      ... on PluginBackend {\n        ...pluginBackendFull\n      }\n    }\n  }\n}\n    \n    fragment pluginFrontendFull on PluginFrontend {\n  ...pluginMeta\n  entrypoint\n  style\n  data\n  backend {\n    ...pluginBackendMeta\n  }\n}\n    \n\n    fragment pluginMeta on Plugin {\n  __typename\n  id\n  name\n  enabled\n  manifestId\n  package {\n    id\n  }\n}\n    \n\n    fragment pluginBackendMeta on PluginBackend {\n  __typename\n  id\n}\n    \n\n    fragment pluginBackendFull on PluginBackend {\n  ...pluginMeta\n  runtime\n  state {\n    error\n    running\n  }\n}\n    ";
+export declare const CreatedPluginEventDocument = "\n    subscription createdPluginEvent {\n  createdPluginEvent {\n    pluginId\n    eventArgs\n    eventName\n  }\n}\n    ";
 export declare const CreatedProjectDocument = "\n    subscription createdProject {\n  createdProject {\n    project {\n      ...projectFull\n    }\n  }\n}\n    \n    fragment projectFull on Project {\n  __typename\n  id\n  name\n  path\n  version\n  status\n  size\n  createdAt\n  updatedAt\n  backups {\n    id\n  }\n}\n    ";
 export declare const UpdatedProjectDocument = "\n    subscription updatedProject {\n  updatedProject {\n    project {\n      ...projectFull\n    }\n  }\n}\n    \n    fragment projectFull on Project {\n  __typename\n  id\n  name\n  path\n  version\n  status\n  size\n  createdAt\n  updatedAt\n  backups {\n    id\n  }\n}\n    ";
 export declare const DeletedProjectDocument = "\n    subscription deletedProject {\n  deletedProject {\n    deletedProjectId\n  }\n}\n    ";
@@ -14078,6 +14103,7 @@ export declare function getSdk<C>(requester: Requester<C>): {
     createdPluginPackage(variables?: CreatedPluginPackageSubscriptionVariables, options?: C): AsyncIterable<CreatedPluginPackageSubscription>;
     deletedPluginPackage(variables?: DeletedPluginPackageSubscriptionVariables, options?: C): AsyncIterable<DeletedPluginPackageSubscription>;
     updatedPlugin(variables?: UpdatedPluginSubscriptionVariables, options?: C): AsyncIterable<UpdatedPluginSubscription>;
+    createdPluginEvent(variables?: CreatedPluginEventSubscriptionVariables, options?: C): AsyncIterable<CreatedPluginEventSubscription>;
     createdProject(variables?: CreatedProjectSubscriptionVariables, options?: C): AsyncIterable<CreatedProjectSubscription>;
     updatedProject(variables?: UpdatedProjectSubscriptionVariables, options?: C): AsyncIterable<UpdatedProjectSubscription>;
     deletedProject(variables?: DeletedProjectSubscriptionVariables, options?: C): AsyncIterable<DeletedProjectSubscription>;

package/src/types/backend.d.ts

@@ -1,4 +1,20 @@
-export type BackendAPI = Record<string, (...args: any[]) => any>;
-export type ToBackendRPC<T extends BackendAPI> = {
-    [K in keyof T]: (...args: Parameters<T[K]>) => ReturnType<T[K]> extends Promise<infer U> ? Promise<U> : Promise<ReturnType<T[K]>>;
+import type { PromisifiedReturnType } from "./utils";
+export type BackendEndpoints = {
+    [key: string]: (...args: any[]) => any;
+};
+export type BackendEvents = {
+    [key: string]: (...args: any[]) => void;
+};
+export type ToBackendRPC<T extends BackendEndpoints, E extends BackendEvents> = {
+    [K in keyof T]: (...args: Parameters<T[K]>) => PromisifiedReturnType<T[K]>;
+} & {
+    /**
+     * Subscribe to a backend event.
+     * @param event The event to subscribe to.
+     * @param callback The callback to call when the event is emitted.
+     * @returns An object with a `stop` method that can be called to stop listening to the event.
+     */
+    onEvent: <K extends keyof E>(event: K, callback: E[K]) => {
+        stop: () => void;
+    };
 };

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 { BackendAPI, 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 { BackendEndpoints, BackendEvents, ToBackendRPC } from "./backend";
+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 API<T extends BackendAPI = Record<string, never>> = {
-    ui: UI;
-    backend: ToBackendRPC<T>;
-    scopes: Scopes;
-    findings: Findings;
-    commands: Commands;
-    menu: Menu;
-    navigation: Navigation;
-    window: Window;
-    storage: Storage;
+export type { MenuItem } from "./menu";
+export type API<T extends BackendEndpoints = Record<string, never>, E extends BackendEvents = Record<string, never>> = {
+    graphql: Sdk;
+    backend: ToBackendRPC<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;
+    };
+    /**
+     * 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;
+};

package/src/types/utils.d.ts

@@ -6,4 +6,5 @@ type NotAssignableToJson = bigint | symbol | Function;
 export type JSONCompatible<T> = unknown extends T ? never : {
     [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible<T[P]>;
 };
+export type PromisifiedReturnType<T extends (...args: unknown[]) => unknown> = ReturnType<T> extends Promise<infer U> ? Promise<U> : Promise<ReturnType<T>>;
 export {};