@fusionkit/sdk 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+import type { ActorRef, ChainedEvent, ClaimResult, DisclosureReport, Policy, Receipt, ReceiptBundle, RunnerSummary, RunRequestInput, RunStatus, RunSummary, RunView } from "@fusionkit/protocol";
+export declare class PlaneClientError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+/** Thin HTTP client over the plane API, shared by the CLI, SDKs, and runner. */
+export declare class PlaneClient {
+    readonly baseUrl: string;
+    private readonly adminToken?;
+    constructor(baseUrl: string, adminToken?: string);
+    private json;
+    enroll(input: {
+        enrollToken: string;
+        publicKeyPem: string;
+        pool: string;
+    }): Promise<{
+        runnerId: string;
+        runnerToken: string;
+    }>;
+    putBlob(content: Buffer, token?: string): Promise<string>;
+    getBlob(hash: string): Promise<Buffer>;
+    requestRun(request: RunRequestInput): Promise<{
+        runId: string;
+        status: RunStatus;
+        consentRequirements: string[];
+    }>;
+    dryRun(request: RunRequestInput): Promise<DisclosureReport>;
+    approve(runId: string, actor: ActorRef): Promise<{
+        runId: string;
+        status: RunStatus;
+    }>;
+    cancel(runId: string, actor: ActorRef): Promise<{
+        runId: string;
+        status: RunStatus;
+    }>;
+    getRun(runId: string): Promise<RunView>;
+    listRuns(): Promise<{
+        runs: RunSummary[];
+    }>;
+    listRunners(): Promise<{
+        runners: RunnerSummary[];
+    }>;
+    getPolicy(): Promise<{
+        policy: Policy;
+        policyHash: string;
+    }>;
+    claim(input: {
+        runnerToken: string;
+        pool: string;
+    }): Promise<ClaimResult | {
+        empty: true;
+    }>;
+    postEvents(runId: string, claimToken: string, events: ChainedEvent[]): Promise<{
+        ok: boolean;
+    }>;
+    complete(runId: string, claimToken: string, receipt: Receipt): Promise<{
+        receipt: Receipt;
+    }>;
+    getBundle(runId: string): Promise<ReceiptBundle>;
+    private runBundlePath;
+    /** Canonical download URL for a run's signed receipt bundle. */
+    runBundleUrl(runId: string): string;
+    /** Canonical control-panel deep link for a run. */
+    runUiUrl(runId: string): string;
+    exportJsonl(since?: string): Promise<string>;
+}

package/dist/client.js

@@ -0,0 +1,168 @@
+export class PlaneClientError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        const message = typeof body === "object" && body !== null && "error" in body
+            ? String(body.error)
+            : `plane request failed with status ${status}`;
+        super(message);
+        this.name = "PlaneClientError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Default transport-retry policy for idempotent requests. */
+const DEFAULT_RETRY_ATTEMPTS = 3;
+const RETRY_BACKOFF_STEP_MS = 100;
+/**
+ * Retry idempotent requests on transport-level failures: a keep-alive
+ * socket the server closed while idle surfaces as a TypeError from fetch,
+ * not as an HTTP error. GETs are idempotent by construction in this API;
+ * blob uploads are content-addressed, so retrying them is also safe. Other
+ * POSTs (run requests, claims, events, completion) are never retried here.
+ */
+async function fetchIdempotent(url, init, attempts = DEFAULT_RETRY_ATTEMPTS) {
+    const retryable = init.idempotent ?? init.method === "GET";
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await fetch(url, init);
+        }
+        catch (error) {
+            if (!(error instanceof TypeError) || !retryable || attempt >= attempts) {
+                throw error;
+            }
+            // Linear backoff: brief, since this only covers idle-socket races.
+            await new Promise((resolve) => setTimeout(resolve, RETRY_BACKOFF_STEP_MS * attempt));
+        }
+    }
+}
+/** Parse a response body as JSON, tolerating empty or non-JSON bodies. */
+async function parseJsonResponse(response) {
+    const text = await response.text();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { error: text };
+    }
+}
+/** Thin HTTP client over the plane API, shared by the CLI, SDKs, and runner. */
+export class PlaneClient {
+    baseUrl;
+    adminToken;
+    constructor(baseUrl, adminToken) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.adminToken = adminToken;
+    }
+    async json(method, path, body, token) {
+        const headers = {};
+        const auth = token ?? this.adminToken;
+        if (auth)
+            headers.authorization = `Bearer ${auth}`;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const response = await fetchIdempotent(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body)
+        });
+        const payload = await parseJsonResponse(response);
+        if (!response.ok)
+            throw new PlaneClientError(response.status, payload);
+        return payload;
+    }
+    enroll(input) {
+        return this.json("POST", "/v1/runners/enroll", input);
+    }
+    async putBlob(content, token) {
+        const headers = {
+            "content-type": "application/octet-stream"
+        };
+        const auth = token ?? this.adminToken;
+        if (auth)
+            headers.authorization = `Bearer ${auth}`;
+        const response = await fetchIdempotent(`${this.baseUrl}/v1/blobs`, {
+            method: "POST",
+            headers,
+            body: new Uint8Array(content),
+            idempotent: true
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.hash) {
+            throw new PlaneClientError(response.status, payload);
+        }
+        return payload.hash;
+    }
+    async getBlob(hash) {
+        const response = await fetchIdempotent(`${this.baseUrl}/v1/blobs/${hash}`, {
+            method: "GET"
+        });
+        if (!response.ok) {
+            throw new PlaneClientError(response.status, await response.json());
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
+    requestRun(request) {
+        return this.json("POST", "/v1/runs", { request });
+    }
+    dryRun(request) {
+        return this.json("POST", "/v1/runs", { request, dryRun: true });
+    }
+    approve(runId, actor) {
+        return this.json("POST", `/v1/runs/${runId}/approve`, { actor });
+    }
+    cancel(runId, actor) {
+        return this.json("POST", `/v1/runs/${runId}/cancel`, { actor });
+    }
+    getRun(runId) {
+        return this.json("GET", `/v1/runs/${runId}`);
+    }
+    listRuns() {
+        return this.json("GET", "/v1/runs");
+    }
+    listRunners() {
+        return this.json("GET", "/v1/runners");
+    }
+    getPolicy() {
+        return this.json("GET", "/v1/policy");
+    }
+    claim(input) {
+        return this.json("POST", "/v1/claims", input);
+    }
+    postEvents(runId, claimToken, events) {
+        return this.json("POST", `/v1/runs/${runId}/events`, { claimToken, events });
+    }
+    complete(runId, claimToken, receipt) {
+        return this.json("POST", `/v1/runs/${runId}/complete`, { claimToken, receipt });
+    }
+    getBundle(runId) {
+        return this.json("GET", this.runBundlePath(runId));
+    }
+    runBundlePath(runId) {
+        return `/v1/runs/${runId}/bundle`;
+    }
+    /** Canonical download URL for a run's signed receipt bundle. */
+    runBundleUrl(runId) {
+        return `${this.baseUrl}${this.runBundlePath(runId)}`;
+    }
+    /** Canonical control-panel deep link for a run. */
+    runUiUrl(runId) {
+        return `${this.baseUrl}/ui/#/runs/${runId}`;
+    }
+    async exportJsonl(since) {
+        const query = since ? `?since=${encodeURIComponent(since)}` : "";
+        const headers = {};
+        if (this.adminToken)
+            headers.authorization = `Bearer ${this.adminToken}`;
+        const response = await fetchIdempotent(`${this.baseUrl}/v1/export${query}`, {
+            method: "GET",
+            headers
+        });
+        if (!response.ok) {
+            throw new PlaneClientError(response.status, await response.json());
+        }
+        return response.text();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fusionkit/sdk — a thin client over the plane API. Protocol primitives
+ * (verification, hashing, wire types) live in @fusionkit/protocol; consumers
+ * import them from there rather than through this package.
+ */
+export { PlaneClient, PlaneClientError } from "./client.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fusionkit/sdk — a thin client over the plane API. Protocol primitives
+ * (verification, hashing, wire types) live in @fusionkit/protocol; consumers
+ * import them from there rather than through this package.
+ */
+export { PlaneClient, PlaneClientError } from "./client.js";

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fusionkit/sdk",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/sdk"
+  },
+  "description": "Warrant SDK: a thin client over the plane API plus offline receipt verification.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@fusionkit/protocol": "0.1.0"
+  }
+}