@forge-dashboard/sdk-node 1.1.0 → 2.0.1

package/README.md

@@ -12,6 +12,8 @@ REST API, generated from its OpenAPI spec with
 [openapi-fetch](https://openapi-ts.dev/openapi-fetch/). It saves you from
 hand-rolling HTTP requests and retries against the API yourself.
 
+Full API reference: <https://alrayyes.github.io/forge-dashboard-sdk-node/>
+
 ## Requirements
 
 - Node.js 20+ or [Bun](https://bun.sh) 1.1+ — anything with a native `fetch`.

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import { type Client as OpenapiFetchClient } from "openapi-fetch";
+import type { paths } from "./generated/schema.js";
+import { type RetryConfig } from "./retry.js";
+/**
+ * The environment variable {@link createForgeDashboardClient} falls back
+ * to when no token is passed explicitly via {@link ClientOptions.token}.
+ */
+export declare const TOKEN_ENV_VAR = "FORGE_DASHBOARD_TOKEN";
+export interface ClientOptions {
+    /**
+     * A forge-dashboard personal API token, generated from the dashboard's
+     * own Settings page (`POST /api/tokens`, signed in as yourself first).
+     * Overrides `FORGE_DASHBOARD_TOKEN` when both are set. See the README's
+     * "Authentication" section -- this is the real headless alternative
+     * forge-dashboard's spec documents to its browser session cookie.
+     */
+    token?: string;
+    /**
+     * Replaces the underlying `fetch`. The retry wrapper (see `retry`)
+     * wraps whatever this is, so pass something with its own request
+     * behavior already configured (a proxying fetch, a test double) rather
+     * than re-implementing retry yourself.
+     */
+    fetch?: (input: Request) => Promise<Response>;
+    /** Overrides the default retry policy. */
+    retry?: Partial<RetryConfig>;
+}
+/**
+ * A forge-dashboard API client -- the typed `openapi-fetch` client for
+ * `paths`, so every operation is available as `client.GET("/api/dashboard",
+ * ...)` / `client.POST("/api/pull-requests/merge", ...)` etc. See the
+ * README for the common operations and {@link decodeError} for turning a
+ * failed response into a typed error.
+ */
+export type ForgeDashboardClient = OpenapiFetchClient<paths>;
+/**
+ * Builds a client against `baseUrl` (the forge-dashboard instance's own
+ * origin, e.g. `"https://dashboard.example.com"`).
+ */
+export declare function createForgeDashboardClient(baseUrl: string, options?: ClientOptions): ForgeDashboardClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAqB,EAAE,KAAK,MAAM,IAAI,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,eAAO,MAAM,aAAa,0BAA0B,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9C,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,oBAAoB,CAqBtB"}

package/dist/client.js

@@ -0,0 +1,35 @@
+import createClient, {} from "openapi-fetch";
+import { createRetryFetch, defaultRetryConfig, } from "./retry.js";
+/**
+ * The environment variable {@link createForgeDashboardClient} falls back
+ * to when no token is passed explicitly via {@link ClientOptions.token}.
+ */
+export const TOKEN_ENV_VAR = "FORGE_DASHBOARD_TOKEN";
+/**
+ * Builds a client against `baseUrl` (the forge-dashboard instance's own
+ * origin, e.g. `"https://dashboard.example.com"`).
+ */
+export function createForgeDashboardClient(baseUrl, options = {}) {
+    const token = options.token ?? getEnv(TOKEN_ENV_VAR);
+    const retryConfig = { ...defaultRetryConfig, ...options.retry };
+    const baseFetch = options.fetch ?? ((request) => fetch(request));
+    const client = createClient({
+        baseUrl,
+        fetch: createRetryFetch(baseFetch, retryConfig),
+    });
+    if (token) {
+        client.use({
+            onRequest({ request }) {
+                request.headers.set("Authorization", `Bearer ${token}`);
+                return request;
+            },
+        });
+    }
+    return client;
+}
+function getEnv(name) {
+    // Bun and Node both expose process.env; guarded for a browser bundle
+    // that has no `process` at all.
+    return typeof process !== "undefined" ? process.env[name] : undefined;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,EAAE,EAAqC,MAAM,eAAe,CAAC;AAEhF,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,uBAAuB,CAAC;AA+BrD;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAe,EACf,UAAyB,EAAE;IAE3B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,aAAa,CAAC,CAAC;IACrD,MAAM,WAAW,GAAgB,EAAE,GAAG,kBAAkB,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7E,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,OAAgB,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAE1E,MAAM,MAAM,GAAG,YAAY,CAAQ;QACjC,OAAO;QACP,KAAK,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC;KAChD,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,CAAC,GAAG,CAAC;YACT,SAAS,CAAC,EAAE,OAAO,EAAE;gBACnB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;gBAExD,OAAO,OAAO,CAAC;YACjB,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,MAAM,CAAC,IAAY;IAC1B,qEAAqE;IACrE,gCAAgC;IAChC,OAAO,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACxE,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Every 4xx/5xx forge-dashboard returns shares the same `{error}` body
+ * (openapi/openapi.yaml's `Error` schema) -- one field, unlike some APIs'
+ * richer `{code, message}` shape. `ApiError` carries that alongside the
+ * HTTP status, so a caller never has to parse a raw `Response` or match
+ * against a bare string.
+ */
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly apiMessage: string;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * Builds an ApiError from a response and its already-parsed error body --
+ * openapi-fetch decodes JSON before handing you `error`, so there's no
+ * `Response` to read a second time. Returns null for a response that
+ * isn't actually an error (status < 400), so callers can call this
+ * unconditionally on openapi-fetch's `{ data, error, response }` result:
+ *
+ *   const { data, error, response } = await client.GET("/api/dashboard", {});
+ *   const apiErr = decodeError(response, error);
+ *   if (apiErr) throw apiErr;
+ */
+export declare function decodeError(response: Response, body: unknown): ApiError | null;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMhD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,OAAO,GACZ,QAAQ,GAAG,IAAI,CAQjB"}

package/dist/errors.js

@@ -0,0 +1,39 @@
+/**
+ * Every 4xx/5xx forge-dashboard returns shares the same `{error}` body
+ * (openapi/openapi.yaml's `Error` schema) -- one field, unlike some APIs'
+ * richer `{code, message}` shape. `ApiError` carries that alongside the
+ * HTTP status, so a caller never has to parse a raw `Response` or match
+ * against a bare string.
+ */
+export class ApiError extends Error {
+    statusCode;
+    apiMessage;
+    constructor(statusCode, message) {
+        super(`forge-dashboard: ${statusCode}: ${message}`);
+        this.name = "ApiError";
+        this.statusCode = statusCode;
+        this.apiMessage = message;
+    }
+}
+/**
+ * Builds an ApiError from a response and its already-parsed error body --
+ * openapi-fetch decodes JSON before handing you `error`, so there's no
+ * `Response` to read a second time. Returns null for a response that
+ * isn't actually an error (status < 400), so callers can call this
+ * unconditionally on openapi-fetch's `{ data, error, response }` result:
+ *
+ *   const { data, error, response } = await client.GET("/api/dashboard", {});
+ *   const apiErr = decodeError(response, error);
+ *   if (apiErr) throw apiErr;
+ */
+export function decodeError(response, body) {
+    if (response.status < 400) {
+        return null;
+    }
+    const parsed = isErrorBody(body) ? body : {};
+    return new ApiError(response.status, parsed.error ?? response.statusText);
+}
+function isErrorBody(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,UAAU,CAAS;IACnB,UAAU,CAAS;IAE5B,YAAY,UAAkB,EAAE,OAAe;QAC7C,KAAK,CAAC,oBAAoB,UAAU,KAAK,OAAO,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;IAC5B,CAAC;CACF;AAMD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,QAAkB,EAClB,IAAa;IAEb,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAE7C,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC"}