@caido/sdk-backend 0.1.6 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caido/sdk-backend",
-  "version": "0.1.6",
+  "version": "0.39.0",
   "description": "Typing for the Caido Backend SDK",
   "author": "Caido Labs Inc. <dev@caido.io>",
   "license": "MIT",

package/src/types/common.d.ts

@@ -150,13 +150,23 @@ declare module "caido:utils" {
 
   /**
    * A saved immutable Finding.
-   *
-   * To modify, use `toSpec` to get a `FindingSpec` object.
    */
   export type Finding = {
+    /**
+     * The unique Caido {@link ID} of the finding.
+     */
     getId(): ID;
+    /**
+     * The title of the finding.
+     */
     getTitle(): string;
+    /**
+     * The description of the finding.
+     */
     getDescription(): string | undefined;
+    /**
+     * The name of the reporter.
+     */
     getReporter(): string;
   };
 
@@ -164,9 +174,27 @@ declare module "caido:utils" {
    * A mutable Finding not yet created.
    */
   export type FindingSpec = {
+    /**
+     * The title of the finding.
+     */
     title: string;
+    /**
+     * The description of the finding.
+     */
     description?: string | undefined;
+    /**
+     * The name of the reporter.
+     * It will be used to group findings.
+     */
     reporter: string;
+    /**
+     * Deduplication key for findings.
+     * If a finding with the same dedupe key already exists, it will not be created.
+     */
+    dedupeKey?: string | undefined;
+    /**
+     * The associated {@link Request}.
+     */
     request: Request;
   };
 
@@ -184,6 +212,7 @@ declare module "caido:utils" {
      *   title: "Title",
      *   description: "Description",
      *   reporter: "Reporter",
+     *   dedupe: `${request.getHost()}-${request.getPath()}`,
      *   request,
      * });
      */

package/src/types/typing.d.ts

@@ -1,5 +1,11 @@
 declare module "caido:plugin" {
-  import { MaybePromise, FindingsSDK, RequestsSDK } from "caido:utils";
+  import {
+    MaybePromise,
+    FindingsSDK,
+    RequestsSDK,
+    Request,
+    Response,
+  } from "caido:utils";
 
   export type DefineAPI<
     API extends Record<string, (...args: any[]) => MaybePromise<any>>,
@@ -22,7 +28,7 @@ declare module "caido:plugin" {
      * Registers a new backend function for the RPC.
      *
      * @example
-     * sdk.api.register("multiply", (a: number, b: number) => {
+     * sdk.api.register("multiply", (sdk: SDK, a: number, b: number) => {
      *    return a * b;
      * });
      */
@@ -32,6 +38,43 @@ declare module "caido:plugin" {
     ): void;
   };
 
+  /**
+   * The SDK for the API RPC service.
+   */
+  export type EventsSDK = {
+    /**
+     * Registers an callback on new intercepted requests.
+     *
+     * This callback is called asynchronously and cannot modify requests.
+     *
+     * @example
+     * sdk.events.onInterceptRequest((sdk: SDK, request: Request) => {
+     *    // Do something with the request
+     * });
+     */
+    onInterceptRequest(
+      callback: (sdk: SDK, request: Request) => MaybePromise<void>,
+    ): void;
+
+    /**
+     * Registers an callback on new intercepted responses.
+     *
+     * This callback is called asynchronously and cannot modify responses.
+     *
+     * @example
+     * sdk.events.onInterceptResponse((sdk: SDK, request: Request, response: Response) => {
+     *    // Do something with the request/response
+     * });
+     */
+    onInterceptResponse(
+      callback: (
+        sdk: SDK,
+        request: Request,
+        response: Response,
+      ) => MaybePromise<void>,
+    ): void;
+  };
+
   /**
    * The SDK object available to all scripts.
    */
@@ -54,5 +97,9 @@ declare module "caido:plugin" {
      * The SDK for the API RPC service.
      */
     api: APISDK;
+    /**
+     * The SDK for the Events service.
+     */
+    events: EventsSDK;
   };
 }