@superclerk/sdk 0.0.0-stage → 0.1.0

package/generated/types.js

@@ -0,0 +1,2 @@
+// Generated by script/generate.ts from the public OpenAPI document. Do not edit.
+export {};

package/generated/version.d.ts

@@ -0,0 +1,4 @@
+export declare const SDK_VERSION = "0.1.0";
+/** The API behavior this SDK was generated for. Every request pins it with the Superclerk-Version header. */
+export declare const API_VERSION = "2026-11-05";
+export declare const DEFAULT_BASE_URL = "https://api.superclerk.com";

package/generated/version.js

@@ -0,0 +1,5 @@
+// Generated by script/generate.ts from the public OpenAPI document. Do not edit.
+export const SDK_VERSION = "0.1.0";
+/** The API behavior this SDK was generated for. Every request pins it with the Superclerk-Version header. */
+export const API_VERSION = "2026-11-05";
+export const DEFAULT_BASE_URL = "https://api.superclerk.com";

package/generated/webhooks.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectLinkFailedEvent, ConnectLinkSucceededEvent, ConnectionRemovedEvent, ConnectionUpdatedEvent, ContactCreatedEvent, ContactMergedEvent, ConversationHandedOffEvent, ConversationMessageReceivedEvent, OpportunityStageChangedEvent, TaskCompletedEvent, ToolRunCompletedEvent, ToolRunFailedEvent } from "./types.js";
+/** Every event a webhook endpoint receives, told apart by its `type`. */
+export type WebhookEvent = ConnectLinkSucceededEvent | ConnectLinkFailedEvent | ConnectionUpdatedEvent | ConnectionRemovedEvent | ToolRunCompletedEvent | ToolRunFailedEvent | ConversationMessageReceivedEvent | ConversationHandedOffEvent | ContactCreatedEvent | ContactMergedEvent | OpportunityStageChangedEvent | TaskCompletedEvent;
+export type WebhookEventType = WebhookEvent["type"];

package/generated/webhooks.js

@@ -0,0 +1,2 @@
+// Generated by script/generate.ts from the public OpenAPI document. Do not edit.
+export {};

package/index.d.ts

@@ -0,0 +1,14 @@
+export { Superclerk } from "./generated/client.js";
+export type { ClientOptions, HttpMethod, Operation, RequestOptions } from "./core/client.js";
+export { APIPromise } from "./core/api-promise.js";
+export { Page, PagePromise } from "./core/pagination.js";
+export { APIConnectionError, APIError, SuperclerkError, ToolRunError, WebhookVerificationError, type FieldError, } from "./core/errors.js";
+export type { ToolRunParams } from "./lib/tools.js";
+export type { SettledToolRun } from "./lib/tools.js";
+export type { ProxyInit } from "./lib/connections.js";
+export type { MediaUploadParams } from "./lib/social.js";
+export type { WebhookHeaders, WebhookSignOptions, WebhookVerifyOptions } from "./lib/webhooks.js";
+export type * from "./generated/types.js";
+export type { ToolID, Tools } from "./generated/tools.js";
+export type { WebhookEvent, WebhookEventType } from "./generated/webhooks.js";
+export { API_VERSION, SDK_VERSION } from "./generated/version.js";

package/index.js

@@ -0,0 +1,5 @@
+export { Superclerk } from "./generated/client.js";
+export { APIPromise } from "./core/api-promise.js";
+export { Page, PagePromise } from "./core/pagination.js";
+export { APIConnectionError, APIError, SuperclerkError, ToolRunError, WebhookVerificationError, } from "./core/errors.js";
+export { API_VERSION, SDK_VERSION } from "./generated/version.js";

package/lib/connect.d.ts

@@ -0,0 +1,12 @@
+import type { RequestOptions } from "../core/client.js";
+import { ConnectBase, ConnectLinks as ConnectLinksBase } from "../generated/resources.js";
+export declare class ConnectLinks extends ConnectLinksBase {
+    /**
+     * Reads a link until the person is done with it, and answers it once it has succeeded, failed or expired. Its
+     * `connection` is the account they connected. Aborting the signal stops the waiting; the link stays open.
+     */
+    wait(connectLinkID: string, options?: RequestOptions): Promise<import("../index.js").ConnectLink>;
+}
+export declare class Connect extends ConnectBase {
+    readonly links: ConnectLinks;
+}

package/lib/connect.js

@@ -0,0 +1,14 @@
+import { settle } from "../core/timing.js";
+import { ConnectBase, ConnectLinks as ConnectLinksBase } from "../generated/resources.js";
+export class ConnectLinks extends ConnectLinksBase {
+    /**
+     * Reads a link until the person is done with it, and answers it once it has succeeded, failed or expired. Its
+     * `connection` is the account they connected. Aborting the signal stops the waiting; the link stays open.
+     */
+    wait(connectLinkID, options = {}) {
+        return settle(this._client, (held) => this.get(connectLinkID, held), options);
+    }
+}
+export class Connect extends ConnectBase {
+    links = new ConnectLinks(this._client);
+}

package/lib/connections.d.ts

@@ -0,0 +1,17 @@
+import { type RequestOptions } from "../core/client.js";
+import { ConnectionsBase } from "../generated/resources.js";
+export interface ProxyInit extends RequestOptions {
+    /** GET, POST or DELETE, as the app's `proxy.methods` allows. Defaults to GET. */
+    method?: "GET" | "POST" | "DELETE";
+    /** A JSON value, or a string, Blob, FormData or URLSearchParams sent as it is. */
+    body?: unknown;
+}
+export declare class Connections extends ConnectionsBase {
+    /**
+     * Calls the provider's own API through a connection, with its credentials added on the server, and answers the
+     * provider's response whatever its status. `path` is the provider's path and query, sent as written, such as
+     * `/me/adaccounts?fields=id,name`. A call still running when the API stops holding it is waited for. A request
+     * the gateway refuses, or a run that fails, such as a write whose outcome is unknown, throws APIError.
+     */
+    fetch(connectionID: string, path: string, init?: ProxyInit): Promise<Response>;
+}

package/lib/connections.js

@@ -0,0 +1,28 @@
+import { pathParam } from "../core/client.js";
+import { holding, isPending, settle } from "../core/timing.js";
+import { ConnectionsBase } from "../generated/resources.js";
+export class Connections extends ConnectionsBase {
+    /**
+     * Calls the provider's own API through a connection, with its credentials added on the server, and answers the
+     * provider's response whatever its status. `path` is the provider's path and query, sent as written, such as
+     * `/me/adaccounts?fields=id,name`. A call still running when the API stops holding it is waited for. A request
+     * the gateway refuses, or a run that fails, such as a write whose outcome is unknown, throws APIError.
+     */
+    async fetch(connectionID, path, init = {}) {
+        const { method = "GET", body, ...options } = init;
+        // Only the path and query are the provider's; the API resolves them against the connection's provider.
+        const { pathname, search } = new URL(path, "https://provider.invalid");
+        const response = await this._client.request({
+            method,
+            path: `/v1/connections/${pathParam(connectionID)}/proxy${pathname}${search}`,
+            body,
+            idempotent: true,
+            response: "raw",
+        }, holding(this._client, options));
+        if (!isPending(response))
+            return response;
+        await response.body?.cancel();
+        const runID = response.headers.get("x-superclerk-run-id");
+        return settle(this._client, (held) => this.proxy.runs.get(runID, held), options);
+    }
+}

package/lib/social.d.ts

@@ -0,0 +1,32 @@
+import type { RequestOptions } from "../core/client.js";
+import { SocialBase, SocialMedia as SocialMediaBase } from "../generated/resources.js";
+import type { SocialMediaCreateParams } from "../generated/types.js";
+export interface MediaUploadParams {
+    filename: string;
+    contentType: SocialMediaCreateParams["contentType"];
+    /** `public` gives the asset a URL anyone can open; `private` shares it only through short-lived links. */
+    storageAccess: SocialMediaCreateParams["storageAccess"];
+}
+export declare class SocialMedia extends SocialMediaBase {
+    /**
+     * Uploads an image or video and answers its asset once it's ready to attach to a post: it creates the asset, sends
+     * the bytes to the upload URL the API signs, and confirms them. To finish an upload that was cut off, call it again
+     * with the same `idempotencyKey`: an asset already ready comes back at once, and bytes already stored are confirmed.
+     */
+    upload(file: Blob | ArrayBuffer | Uint8Array, params: MediaUploadParams, options?: RequestOptions): Promise<{
+        id: string;
+        filename: string;
+        contentType: "image/jpeg" | "image/png" | "image/webp" | "video/mp4";
+        sizeBytes: number;
+        sha256: string;
+        storageAccess: "private" | "public";
+        status: "pending" | "ready";
+        url: string | null;
+        createdAt: number;
+        updatedAt: number;
+        confirmedAt: number | null;
+    }>;
+}
+export declare class Social extends SocialBase {
+    readonly media: SocialMedia;
+}

package/lib/social.js

@@ -0,0 +1,27 @@
+import { SuperclerkError } from "../core/errors.js";
+import { SocialBase, SocialMedia as SocialMediaBase } from "../generated/resources.js";
+export class SocialMedia extends SocialMediaBase {
+    /**
+     * Uploads an image or video and answers its asset once it's ready to attach to a post: it creates the asset, sends
+     * the bytes to the upload URL the API signs, and confirms them. To finish an upload that was cut off, call it again
+     * with the same `idempotencyKey`: an asset already ready comes back at once, and bytes already stored are confirmed.
+     */
+    async upload(file, params, options = {}) {
+        const bytes = new Uint8Array(file instanceof Blob ? await file.arrayBuffer() : file);
+        const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+        const sha256 = Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+        const { asset, upload } = await this.create({ ...params, sha256, sizeBytes: bytes.length }, options);
+        if (asset.status === "ready")
+            return asset;
+        const stored = await this._client.attempt(upload.url, { method: upload.method, headers: upload.headers, body: bytes }, options);
+        await stored.body?.cancel();
+        // The URL writes once: 412 means an earlier try already stored the bytes, which confirm checks either way.
+        if (!stored.ok && stored.status !== 412) {
+            throw new SuperclerkError("upload_failed", `The upload URL answered ${stored.status}`);
+        }
+        return this.confirm(asset.id, options);
+    }
+}
+export class Social extends SocialBase {
+    media = new SocialMedia(this._client);
+}

package/lib/tools.d.ts

@@ -0,0 +1,33 @@
+import type { RequestOptions } from "../core/client.js";
+import { ToolsBase, ToolsRuns as ToolsRunsBase } from "../generated/resources.js";
+import type { ToolID, Tools as ToolTypes } from "../generated/tools.js";
+import type { ToolsRunsGetResponse } from "../generated/types.js";
+/** The tool to run, its input, and the connection or built-in app that runs it. */
+export type ToolRunParams<Tool extends ToolID> = {
+    tool: Tool;
+    input: ToolTypes[Tool]["input"];
+} & ({
+    connectionID: string;
+    appID?: never;
+} | {
+    appID: string;
+    connectionID?: never;
+});
+/** A run that has ended, completed or failed: GET /v1/tools/runs/{runID} answers 202 while a run goes on, 200 after. */
+export type SettledToolRun = Exclude<ToolsRunsGetResponse, {
+    status: "running";
+}>;
+export declare class ToolsRuns extends ToolsRunsBase {
+    /** Reads a run until it ends and answers it. Aborting the signal stops the waiting, not the run. */
+    wait(runID: string, options?: RequestOptions): Promise<SettledToolRun>;
+}
+export declare class Tools extends ToolsBase {
+    readonly runs: ToolsRuns;
+    /**
+     * Runs a tool and answers its output, typed by the tool, waiting while the run goes on. A run that ends failed or
+     * cancelled throws ToolRunError, whose `code` is the run's `error.kind`; a request the API refuses before any run
+     * starts throws APIError. Retries of this call, the SDK's own included, reuse one Idempotency-Key, so the tool runs
+     * once.
+     */
+    run<Tool extends ToolID>({ tool, ...params }: ToolRunParams<Tool>, options?: RequestOptions): Promise<ToolTypes[Tool]["output"]>;
+}

package/lib/tools.js

@@ -0,0 +1,31 @@
+import { APIError, ToolRunError } from "../core/errors.js";
+import { holding, settle } from "../core/timing.js";
+import { ToolsBase, ToolsRuns as ToolsRunsBase } from "../generated/resources.js";
+export class ToolsRuns extends ToolsRunsBase {
+    /** Reads a run until it ends and answers it. Aborting the signal stops the waiting, not the run. */
+    wait(runID, options = {}) {
+        return settle(this._client, (held) => this.get(runID, held), options);
+    }
+}
+export class Tools extends ToolsBase {
+    runs = new ToolsRuns(this._client);
+    /**
+     * Runs a tool and answers its output, typed by the tool, waiting while the run goes on. A run that ends failed or
+     * cancelled throws ToolRunError, whose `code` is the run's `error.kind`; a request the API refuses before any run
+     * starts throws APIError. Retries of this call, the SDK's own included, reuse one Idempotency-Key, so the tool runs
+     * once.
+     */
+    async run({ tool, ...params }, options = {}) {
+        const created = await this.runs
+            .create({ toolID: tool, ...params }, holding(this._client, options))
+            .catch((error) => {
+            // A run that ended at submission answers with the run itself as its body, not the API's `{ error }`.
+            const run = error instanceof APIError ? error.body : undefined;
+            throw run?.status === "failed" || run?.status === "cancelled" ? new ToolRunError(run) : error;
+        });
+        const finished = created.status === "running" ? await this.runs.wait(created.id, options) : created;
+        if (finished.status !== "completed")
+            throw new ToolRunError(finished);
+        return finished.output;
+    }
+}

package/lib/webhooks.d.ts

@@ -0,0 +1,38 @@
+import { WebhooksBase } from "../generated/resources.js";
+import type { WebhookEvent } from "../generated/webhooks.js";
+export type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+export interface WebhookVerifyOptions {
+    /** The endpoint's secret, `whsec_…`. Defaults to the client's webhookSecret. */
+    secret?: string;
+    /** Seconds an event's timestamp may differ from now. Defaults to 300, Standard Webhooks' replay window. */
+    tolerance?: number;
+}
+export interface WebhookSignOptions {
+    /** The endpoint's secret, `whsec_…`. Defaults to the client's webhookSecret. */
+    secret?: string;
+    /** The delivery's time, in seconds since the epoch. Defaults to now. */
+    timestamp?: number;
+}
+/** Your webhooks, and the events Superclerk delivers to them, verified as Standard Webhooks specify. */
+export declare class Webhooks extends WebhooksBase {
+    #private;
+    /**
+     * Verifies an event and answers it, typed by its `type`. Pass the body exactly as it arrived, before any JSON
+     * parsing, with the request's headers.
+     */
+    unwrap(body: string, headers: WebhookHeaders, options?: WebhookVerifyOptions): Promise<WebhookEvent>;
+    /** Throws WebhookVerificationError unless the body carries a valid signature from the endpoint's secret. */
+    verify(body: string, headers: WebhookHeaders, { secret, tolerance }?: WebhookVerifyOptions): Promise<void>;
+    /**
+     * Signs an event as Superclerk signs its deliveries, so a test can post your endpoint a delivery that verifies:
+     * send `body` with `headers`. The event's `id` is the delivery's `webhook-id`, as in a real delivery.
+     */
+    sign(event: WebhookEvent, { secret, timestamp }?: WebhookSignOptions): Promise<{
+        body: string;
+        headers: {
+            "webhook-id": string;
+            "webhook-timestamp": string;
+            "webhook-signature": string;
+        };
+    }>;
+}

package/lib/webhooks.js

@@ -0,0 +1,65 @@
+import { SuperclerkError, WebhookVerificationError } from "../core/errors.js";
+import { WebhooksBase } from "../generated/resources.js";
+/** Your webhooks, and the events Superclerk delivers to them, verified as Standard Webhooks specify. */
+export class Webhooks extends WebhooksBase {
+    /**
+     * Verifies an event and answers it, typed by its `type`. Pass the body exactly as it arrived, before any JSON
+     * parsing, with the request's headers.
+     */
+    async unwrap(body, headers, options = {}) {
+        await this.verify(body, headers, options);
+        return JSON.parse(body);
+    }
+    /** Throws WebhookVerificationError unless the body carries a valid signature from the endpoint's secret. */
+    async verify(body, headers, { secret, tolerance = 300 } = {}) {
+        const key = await this.#key(secret);
+        const read = new Headers(headers);
+        const [id, timestamp, signatures] = ["webhook-id", "webhook-timestamp", "webhook-signature"].map((name) => read.get(name));
+        // A missing or unreadable timestamp is NaN, which is never inside the window.
+        if (!(Math.abs(Date.now() / 1_000 - Number(timestamp)) <= tolerance)) {
+            throw new WebhookVerificationError("The event's timestamp is missing or too far from now");
+        }
+        const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
+        // A rotating endpoint sends a signature per secret, space-separated; any one that verifies is enough. A missing
+        // header, id or signature can't verify. crypto.subtle.verify compares in constant time.
+        for (const signature of (signatures ?? "").split(" ")) {
+            if (signature.startsWith("v1,") &&
+                (await crypto.subtle.verify("HMAC", key, base64(signature.slice(3)), signed))) {
+                return;
+            }
+        }
+        throw new WebhookVerificationError("No signature matches the endpoint's secret");
+    }
+    /**
+     * Signs an event as Superclerk signs its deliveries, so a test can post your endpoint a delivery that verifies:
+     * send `body` with `headers`. The event's `id` is the delivery's `webhook-id`, as in a real delivery.
+     */
+    async sign(event, { secret, timestamp } = {}) {
+        const key = await this.#key(secret);
+        const body = JSON.stringify(event);
+        const at = String(timestamp ?? Math.floor(Date.now() / 1_000));
+        const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${event.id}.${at}.${body}`));
+        const encoded = btoa(String.fromCharCode(...new Uint8Array(signature)));
+        return { body, headers: { "webhook-id": event.id, "webhook-timestamp": at, "webhook-signature": `v1,${encoded}` } };
+    }
+    /** The endpoint's secret as an HMAC key. A missing or malformed secret is an error of its own, not a failed check. */
+    async #key(secret = this._client.webhookSecret) {
+        if (!secret) {
+            throw new SuperclerkError("missing_webhook_secret", "Pass the secret, or set SUPERCLERK_WEBHOOK_SECRET");
+        }
+        const bytes = base64(secret.replace(/^whsec_/, ""));
+        if (bytes.length === 0) {
+            throw new SuperclerkError("invalid_webhook_secret", "The secret isn't the whsec_… value its endpoint was given");
+        }
+        return crypto.subtle.importKey("raw", bytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+    }
+}
+// Bytes a sender wrote as base64; anything else decodes to no bytes, which verify nothing.
+function base64(value) {
+    try {
+        return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+    }
+    catch {
+        return new Uint8Array();
+    }
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@superclerk/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The official TypeScript SDK for the Superclerk API",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://docs.superclerk.com/sdk",
+  "keywords": [
+    "superclerk",
+    "api",
+    "sdk",
+    "integrations",
+    "oauth",
+    "tools",
+    "agents",
+    "webhooks"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "sideEffects": false,
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}