@caido/sdk-backend 0.1.6 → 0.40.0

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@caido/sdk-backend",
-  "version": "0.1.6",
+  "version": "0.40.0",
   "description": "Typing for the Caido Backend SDK",
   "author": "Caido Labs Inc. <dev@caido.io>",
   "license": "MIT",
   "types": "./src/index.d.ts",
   "files": [
     "src/*"
-  ]
+  ],
+  "dependencies": {
+    "@caido/quickjs-types": "0.2.1"
+  }
 }

package/src/index.d.ts

@@ -1,3 +1,4 @@
 ///<reference path="types/runtime.d.ts" />
 ///<reference path="types/common.d.ts" />
 ///<reference path="types/typing.d.ts" />
+///<reference types="@caido/quickjs-types" />

package/src/types/common.d.ts

@@ -40,6 +40,7 @@ declare module "caido:utils" {
     getHeaders(): Record<string, Array<string>>;
     getHeader(name: string): Array<string> | undefined;
     getBody(): Body | undefined;
+    getCreatedAt(): Date;
     toSpec(): RequestSpec;
     toSpecRaw(): RequestSpecRaw;
   };
@@ -103,6 +104,8 @@ declare module "caido:utils" {
     getHeaders(): Record<string, Array<string>>;
     getHeader(name: string): Array<string> | undefined;
     getBody(): Body | undefined;
+    getRoundtripTime(): number;
+    getCreatedAt(): Date;
   };
 
   /**
@@ -113,10 +116,108 @@ declare module "caido:utils" {
     response: Response;
   };
 
+  /**
+   * Information on the current page of paginated data.
+   */
+  export type PageInfo = {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor: string;
+    endCursor: string;
+  };
+
+  export type RequestOrderField =
+    | "ext"
+    | "host"
+    | "id"
+    | "method"
+    | "path"
+    | "query"
+    | "created_at"
+    | "source";
+  export type ResponseOrderField = "length" | "roundtrip" | "code";
+
+  export type RequestsConnectionItem = {
+    cursor: string;
+    request: Request;
+    response?: Response;
+  };
+
+  export type RequestsConnection = {
+    pageInfo: PageInfo;
+    items: Array<RequestsConnectionItem>;
+  };
+
+  /**
+   * Query builder to fetch requests.
+   */
+  export type RequestsQuery = {
+    /**
+     * Requests after a given cursor.
+     * @param cursor Cursor of the request
+     */
+    after(cursor: string): RequestsQuery;
+
+    /**
+     * Requests before a given cursor.
+     * @param cursor Cursor of the request
+     */
+    before(cursor: string): RequestsQuery;
+
+    /**
+     * First n requests.
+     * @param n Number of requests to return
+     */
+    first(n: number): RequestsQuery;
+
+    /**
+     * Last n requests.
+     * @param n Number of requests to return
+     */
+    last(n: number): RequestsQuery;
+
+    /**
+     * Filter requests.
+     * @param filter HTTPQL filter
+     */
+    filter(filter: string): RequestsQuery;
+
+    /**
+     * Ascending ordering.
+     * @param target Target of the ordering: req or resp.
+     * @param field Field to order by.
+     */
+    ascending(target: "req", field: RequestOrderField): RequestsQuery;
+    ascending(target: "resp", field: ResponseOrderField): RequestsQuery;
+
+    /**
+     * Descending ordering.
+     * @param target Target of the ordering: req or resp.
+     * @param field Field to order by.
+     */
+    descending(target: "req", field: RequestOrderField): RequestsQuery;
+    descending(target: "resp", field: ResponseOrderField): RequestsQuery;
+
+    /**
+     * Execute the query.
+     *
+     * @throws {Error} If a query parameter is invalid or the query cannot be executed.
+     */
+    execute(): Promise<RequestsConnection>;
+  };
+
   /**
    * The SDK for the Requests service.
    */
   export type RequestsSDK = {
+    /**
+     * Query requests of the current project.
+     *
+     * @example
+     * const page = await sqk.requests.query().first(2).execute();
+     * sdk.console.log(`ID: ${page.items[1].request.getId()}`);
+     */
+    query(): RequestsQuery;
     /**
      * Sends a request.
      *
@@ -126,14 +227,13 @@ declare module "caido:utils" {
      *
      * @example
      * const spec = new RequestSpec("https://example.com");
-     * sdk.requests.send(request)
-     *   .then((res) => {
-     *     console.log(res.request.getId());
-     *     console.log(res.response.getCode());
-     *   })
-     *   .catch((err) => {
-     *     console.error(err);
-     *   });
+     * try {
+     *   const res = await sdk.requests.send(request)
+     *   sdk.console.log(res.request.getId());
+     *   sdk.console.log(res.response.getCode());
+     * } catch (err) {
+     *   sdk.console.error(err);
+     * }
      */
     send(request: RequestSpec | RequestSpecRaw): Promise<RequestResponse>;
 
@@ -142,7 +242,7 @@ declare module "caido:utils" {
      *
      * @example
      * if (sdk.requests.inScope(request)) {
-     *  console.log("In scope");
+     *  sdk.console.log("In scope");
      * }
      */
     inScope(request: Request | RequestSpec): boolean;
@@ -150,13 +250,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 +274,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;
   };
 
@@ -180,10 +308,11 @@ declare module "caido:utils" {
      * @throws {Error} If the request cannot be saved.
      *
      * @example
-     * sdk.findings.create({
+     * await sdk.findings.create({
      *   title: "Title",
      *   description: "Description",
      *   reporter: "Reporter",
+     *   dedupe: `${request.getHost()}-${request.getPath()}`,
      *   request,
      * });
      */

package/src/types/runtime.d.ts

@@ -1,148 +1,3 @@
-declare global {
-  /**
-   * Console interface for logging.
-   *
-   * Currently logs are only available in the backend logs.
-   * See https://docs.caido.io/report_bug.html#1-backend-logs
-   */
-  type Console = {
-    debug(message: any): void;
-    log(message: any): void;
-    warn(message: any): void;
-    error(message: any): void;
-  };
-  var console: Console;
-
-  /**
-   * The URLSearchParams interface defines utility methods to work with the query string of a URL.
-   */
-  class URLSearchParams implements Iterable<[string, string]> {
-    constructor(
-      init?:
-        | URLSearchParams
-        | string
-        | { readonly [name: string]: string }
-        | Iterable<readonly [name: string, value: string]>
-        | ReadonlyArray<readonly [name: string, value: string]>,
-    );
-    /**
-     * Append a new name-value pair to the query string.
-     */
-    append(name: string, value: string): void;
-    /**
-     * If `value` is provided, removes all name-value pairs
-     * where name is `name` and value is `value`.
-     *
-     * If `value` is not provided, removes all name-value pairs whose name is `name`.
-     */
-    delete(name: string, value?: string): void;
-    /**
-     * Returns an ES6 `Iterator` over each of the name-value pairs in the query.
-     * Each item of the iterator is a JavaScript `Array`. The first item of the `Array` is the `name`, the second item of the `Array` is the `value`.
-     *
-     * Alias for `urlSearchParams[@@iterator]()`.
-     */
-    entries(): IterableIterator<[string, string]>;
-    /**
-     * Iterates over each name-value pair in the query and invokes the given function.
-     *
-     * ```js
-     * const myURL = new URL('https://example.org/?a=b&#x26;c=d');
-     * myURL.searchParams.forEach((value, name) => {
-     *   console.log(name, value);
-     * });
-     * // Prints:
-     * //   a b
-     * //   c d
-     * ```
-     * @param fn Invoked for each name-value pair in the query
-     */
-    forEach(fn: (value: string, name: string) => void): void;
-    /**
-     * Returns the value of the first name-value pair whose name is `name`. If there
-     * are no such pairs, `null` is returned.
-     * @return or `null` if there is no name-value pair with the given `name`.
-     */
-    get(name: string): string | null;
-    /**
-     * Returns the values of all name-value pairs whose name is `name`. If there are
-     * no such pairs, an empty array is returned.
-     */
-    getAll(name: string): string[];
-    /**
-     * Checks if the `URLSearchParams` object contains key-value pair(s) based on `name` and an optional `value` argument.
-     *
-     * If `value` is provided, returns `true` when name-value pair with
-     * same `name` and `value` exists.
-     *
-     * If `value` is not provided, returns `true` if there is at least one name-value
-     * pair whose name is `name`.
-     */
-    has(name: string, value?: string): boolean;
-    /**
-     * Returns an ES6 `Iterator` over the names of each name-value pair.
-     *
-     * ```js
-     * const params = new URLSearchParams('foo=bar&#x26;foo=baz');
-     * for (const name of params.keys()) {
-     *   console.log(name);
-     * }
-     * // Prints:
-     * //   foo
-     * //   foo
-     * ```
-     */
-    keys(): IterableIterator<string>;
-    /**
-     * Sets the value in the `URLSearchParams` object associated with `name` to `value`. If there are any pre-existing name-value pairs whose names are `name`,
-     * set the first such pair's value to `value` and remove all others. If not,
-     * append the name-value pair to the query string.
-     *
-     * ```js
-     * const params = new URLSearchParams();
-     * params.append('foo', 'bar');
-     * params.append('foo', 'baz');
-     * params.append('abc', 'def');
-     * console.log(params.toString());
-     * // Prints foo=bar&#x26;foo=baz&#x26;abc=def
-     *
-     * params.set('foo', 'def');
-     * params.set('xyz', 'opq');
-     * console.log(params.toString());
-     * // Prints foo=def&#x26;abc=def&#x26;xyz=opq
-     * ```
-     */
-    set(name: string, value: string): void;
-    /**
-     * The total number of parameter entries.
-     */
-    readonly size: number;
-    /**
-     * Sort all existing name-value pairs in-place by their names. Sorting is done
-     * with a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), so relative order between name-value pairs
-     * with the same name is preserved.
-     *
-     * This method can be used, in particular, to increase cache hits.
-     *
-     * ```js
-     * const params = new URLSearchParams('query[]=abc&#x26;type=search&#x26;query[]=123');
-     * params.sort();
-     * console.log(params.toString());
-     * // Prints query%5B%5D=abc&#x26;query%5B%5D=123&#x26;type=search
-     * ```
-     */
-    sort(): void;
-    /**
-     * Returns the search parameters serialized as a string, with characters
-     * percent-encoded where necessary.
-     */
-    toString(): string;
-    /**
-     * Returns an ES6 `Iterator` over the values of each name-value pair.
-     */
-    values(): IterableIterator<string>;
-    [Symbol.iterator](): IterableIterator<[string, string]>;
-  }
-}
-
 export {};
+
+declare global {}

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;
   };
 }