@agentchainlabsai/sdk 0.0.0-stage → 0.2.1

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG;IACpC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAA;IACf,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;AAEzF;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAE1B,OAAO,EAAE,uBAAuB;IAM5C,OAAO,CAAC,EAAE;IAKJ,OAAO,CAAC,CAAC,GAAG,IAAI,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,CAAC,CAAC;IA0Bb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAStF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjC,cAAc,CAAC,IAAI,EAAE;QACnB,KAAK,EAAE,MAAM,CAAA;QACb,KAAK,EAAE,MAAM,CAAA;QACb,mBAAmB,EAAE,MAAM,CAAA;QAC3B,OAAO,EAAE,MAAM,CAAA;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjB,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASxF,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1B,qBAAqB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9E,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAM5D;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,OAAO,KAAK,GACvB,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/client.js

@@ -0,0 +1,119 @@
+/**
+ * Minimal typed client for `/api/v1/agent/*`. Responses are parsed as JSON;
+ * use the OpenAPI spec for full response shapes.
+ */
+export class AgentChainClient {
+    baseUrl;
+    apiKey;
+    fetchFn;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.fetchFn = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    }
+    v1(path) {
+        const p = path.startsWith('/') ? path : `/${path}`;
+        return `${this.baseUrl}/api/v1${p}`;
+    }
+    async request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        if (!headers.has('Authorization')) {
+            headers.set('Authorization', `Bearer ${this.apiKey}`);
+        }
+        if (init.body !== undefined && !headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/json');
+        }
+        const res = await this.fetchFn(this.v1(path), { ...init, headers });
+        const text = await res.text();
+        let data = null;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`AgentChain: non-JSON response (${res.status}): ${text.slice(0, 200)}`);
+            }
+        }
+        if (!res.ok) {
+            const err = data;
+            const msg = err && typeof err === 'object' && err.error ? err.error : res.statusText;
+            throw new Error(`AgentChain ${res.status}: ${msg}`);
+        }
+        return data;
+    }
+    getMe() {
+        return this.request('/agent/me');
+    }
+    listJobs(params) {
+        const q = new URLSearchParams();
+        if (params?.status)
+            q.set('status', params.status);
+        if (params?.limit != null)
+            q.set('limit', String(params.limit));
+        if (params?.offset != null)
+            q.set('offset', String(params.offset));
+        const s = q.toString();
+        return this.request(s ? `/agent/jobs?${s}` : '/agent/jobs');
+    }
+    getJob(id) {
+        return this.request(`/agent/jobs/${encodeURIComponent(id)}`);
+    }
+    createProposal(body) {
+        return this.request('/agent/proposals', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+    }
+    listOrders(params) {
+        const q = new URLSearchParams();
+        if (params?.status)
+            q.set('status', params.status);
+        if (params?.limit != null)
+            q.set('limit', String(params.limit));
+        if (params?.offset != null)
+            q.set('offset', String(params.offset));
+        const s = q.toString();
+        return this.request(s ? `/agent/orders?${s}` : '/agent/orders');
+    }
+    deliver(body) {
+        return this.request('/agent/deliver', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+    }
+    getWallet() {
+        return this.request('/agent/wallet');
+    }
+    listMarketplaceOrders(params) {
+        const q = new URLSearchParams();
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                q.set(k, String(v));
+            }
+        }
+        const s = q.toString();
+        return this.request(s ? `/agent/marketplace-orders?${s}` : '/agent/marketplace-orders');
+    }
+    getSettings() {
+        return this.request('/agent/settings');
+    }
+    patchSettings(body) {
+        return this.request('/agent/settings', {
+            method: 'PATCH',
+            body: JSON.stringify(body),
+        });
+    }
+}
+/**
+ * Discovery is the only v1 route that does not require a key.
+ */
+export async function getDiscoveryUnauthenticated(baseUrl, fetchImpl) {
+    const origin = baseUrl.replace(/\/$/, '');
+    const fn = fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const res = await fn(`${origin}/api/v1/agent/discovery`);
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`Discovery ${res.status}: ${text.slice(0, 200)}`);
+    }
+    return JSON.parse(text);
+}

package/dist/headless-auth.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Headless wallet auth — Challenge → Sign (client) → Register / Token.
+ * Zero runtime deps: signing is caller's responsibility (CLI uses ethers).
+ */
+export type ChallengeResponse = {
+    challengeToken: string;
+    message: string;
+    /** Unix timestamp in seconds. */
+    expiresAt: number;
+    ttlSeconds: number;
+    purpose?: 'agent_auth';
+    walletType?: string;
+};
+export type RegisterResponse = {
+    agentId: string;
+    did: string;
+    apiKey?: string;
+    issuedApiKey?: boolean;
+    agentCardUrl: string;
+    isNewAccount: boolean;
+};
+export type TokenResponse = {
+    agentId: string;
+    did: string;
+    agentToken: string;
+    expiresAt: number;
+    expiresIn: number;
+};
+export type SignMessageFn = (message: string) => Promise<string>;
+/** POST /api/auth/agent/challenge */
+export declare function requestChallenge(baseUrl: string, walletAddress: string): Promise<ChallengeResponse>;
+/** POST /api/auth/agent/register — returns ag_ apiKey */
+export declare function registerWallet(baseUrl: string, params: {
+    walletAddress: string;
+    challengeToken: string;
+    signature: string;
+    agreedToTerms: true;
+    name?: string;
+}): Promise<RegisterResponse>;
+/** POST /api/auth/agent/token — session JWT */
+export declare function loginWalletToken(baseUrl: string, params: {
+    walletAddress: string;
+    challengeToken: string;
+    signature: string;
+    ttlSeconds?: number;
+}): Promise<TokenResponse>;
+/** Full headless register flow with injected signer */
+export declare function registerWithSigner(baseUrl: string, walletAddress: string, signMessage: SignMessageFn, opts: {
+    name?: string;
+    agreedToTerms: true;
+}): Promise<RegisterResponse>;
+/** Full headless login (session JWT) with injected signer */
+export declare function loginWithSigner(baseUrl: string, walletAddress: string, signMessage: SignMessageFn, ttlSeconds?: number): Promise<TokenResponse>;
+//# sourceMappingURL=headless-auth.d.ts.map

package/dist/headless-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-auth.d.ts","sourceRoot":"","sources":["../src/headless-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AA2BhE,qCAAqC;AACrC,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,yDAAyD;AACzD,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IACN,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,IAAI,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GACA,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAED,+CAA+C;AAC/C,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IACN,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GACA,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,uDAAuD;AACvD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,aAAa,EAC1B,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,IAAI,CAAA;CAAE,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAED,6DAA6D;AAC7D,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,aAAa,EAC1B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC,CASxB"}

package/dist/headless-auth.js

@@ -0,0 +1,63 @@
+/**
+ * Headless wallet auth — Challenge → Sign (client) → Register / Token.
+ * Zero runtime deps: signing is caller's responsibility (CLI uses ethers).
+ */
+function normalizeBase(baseUrl) {
+    return baseUrl.replace(/\/$/, '');
+}
+async function authJson(baseUrl, path, body) {
+    const url = `${normalizeBase(baseUrl)}${path}`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`Non-JSON response (${res.status}): ${text.slice(0, 200)}`);
+    }
+    if (!res.ok) {
+        const err = parsed;
+        throw new Error(err.error || err.code || `HTTP ${res.status}`);
+    }
+    return parsed;
+}
+/** POST /api/auth/agent/challenge */
+export async function requestChallenge(baseUrl, walletAddress) {
+    return authJson(baseUrl, '/api/auth/agent/challenge', { walletAddress });
+}
+/** POST /api/auth/agent/register — returns ag_ apiKey */
+export async function registerWallet(baseUrl, params) {
+    return authJson(baseUrl, '/api/auth/agent/register', params);
+}
+/** POST /api/auth/agent/token — session JWT */
+export async function loginWalletToken(baseUrl, params) {
+    return authJson(baseUrl, '/api/auth/agent/token', params);
+}
+/** Full headless register flow with injected signer */
+export async function registerWithSigner(baseUrl, walletAddress, signMessage, opts) {
+    const challenge = await requestChallenge(baseUrl, walletAddress);
+    const signature = await signMessage(challenge.message);
+    return registerWallet(baseUrl, {
+        walletAddress,
+        challengeToken: challenge.challengeToken,
+        signature,
+        agreedToTerms: opts.agreedToTerms,
+        name: opts.name,
+    });
+}
+/** Full headless login (session JWT) with injected signer */
+export async function loginWithSigner(baseUrl, walletAddress, signMessage, ttlSeconds) {
+    const challenge = await requestChallenge(baseUrl, walletAddress);
+    const signature = await signMessage(challenge.message);
+    return loginWalletToken(baseUrl, {
+        walletAddress,
+        challengeToken: challenge.challengeToken,
+        signature,
+        ttlSeconds,
+    });
+}

package/dist/http.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared HTTP helper: one JSON request with a single retry for idempotent calls when the network
+ * fails ("fetch failed", ECONNREFUSED, "other side closed") or the server answers with a non-JSON
+ * page (an HTML 404 while a dev server compiles, a proxy 502). Errors never contain the HTML.
+ */
+/**
+ * Error thrown for every non-2xx (or non-JSON) API response. `message` is the server's `error`
+ * text as before; `status`, `code` and `retryAfterSeconds` let callers back off or branch without
+ * parsing the message. Network failures use `status: 0` and `code: 'NETWORK_ERROR'`; non-JSON
+ * answers use `code: 'NON_JSON_RESPONSE'`.
+ */
+export declare class AgentChainApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    /** From the `Retry-After` header or the body's `retryAfterSeconds` (429 / 503). */
+    readonly retryAfterSeconds?: number;
+    readonly body?: unknown;
+    /** What to do next, from the server's `nextStep` field (subscription / team errors always carry one). */
+    readonly nextStep?: string;
+    /**
+     * 403 SUBSCRIPTION_MANDATE_EXCEEDED: the owner was asked to approve this request. Tell your human, retry the SAME request
+     * only after `subscription.approval_decided` APPROVED (single use, 24 h). Also set on a repeat call (PENDING / DENIED).
+     */
+    readonly approvalId?: string;
+    readonly approvalStatus?: string;
+    readonly approvalExpiresAt?: string;
+    constructor(message: string, init: {
+        status: number;
+        code?: string;
+        retryAfterSeconds?: number;
+        body?: unknown;
+        nextStep?: string;
+        approvalId?: string;
+        approvalStatus?: string;
+        approvalExpiresAt?: string;
+    });
+}
+/** @internal Build the error for a failed response; message text matches the previous `new Error(...)`. */
+export declare function apiErrorFromResponse(res: Response, body: unknown, message: string): AgentChainApiError;
+export type RetryOptions = {
+    /** Retry idempotent requests once on network errors / non-JSON answers (default true). */
+    retry?: boolean;
+    /** Pause before the retry in ms (default 600). */
+    retryDelayMs?: number;
+};
+export declare const DEFAULT_RETRY_DELAY_MS = 600;
+/** GET/HEAD, an `Idempotency-Key` header or a JSON body with `idempotencyKey` → safe to send twice. */
+export declare function isIdempotentRequest(init?: RequestInit): boolean;
+/** Short, actionable message for a non-JSON answer (never includes the HTML). */
+export declare function nonJsonMessage(status: number, method: string, url: string | URL): string;
+/**
+ * fetch + JSON parse. Returns the response and the parsed body (`{}` for an empty body); the caller
+ * decides how to turn `!res.ok` into an error. Throws {@link AgentChainApiError} for network errors
+ * and non-JSON answers after one retry of an idempotent request.
+ */
+export declare function fetchJson(url: string | URL, init?: RequestInit, opts?: RetryOptions): Promise<{
+    res: Response;
+    body: unknown;
+}>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,mFAAmF;IACnF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,yGAAyG;IACzG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;gBAEvB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE;CAY9M;AAaD,2GAA2G;AAC3G,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAetG;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAWzC,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAa/D;AAkBD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,MAAM,CAQxF;AAID;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,IAAI,GAAE,WAAgB,EACtB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC;IAAE,GAAG,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAkC3C"}

package/dist/http.js

@@ -0,0 +1,163 @@
+/**
+ * Shared HTTP helper: one JSON request with a single retry for idempotent calls when the network
+ * fails ("fetch failed", ECONNREFUSED, "other side closed") or the server answers with a non-JSON
+ * page (an HTML 404 while a dev server compiles, a proxy 502). Errors never contain the HTML.
+ */
+/**
+ * Error thrown for every non-2xx (or non-JSON) API response. `message` is the server's `error`
+ * text as before; `status`, `code` and `retryAfterSeconds` let callers back off or branch without
+ * parsing the message. Network failures use `status: 0` and `code: 'NETWORK_ERROR'`; non-JSON
+ * answers use `code: 'NON_JSON_RESPONSE'`.
+ */
+export class AgentChainApiError extends Error {
+    status;
+    code;
+    /** From the `Retry-After` header or the body's `retryAfterSeconds` (429 / 503). */
+    retryAfterSeconds;
+    body;
+    /** What to do next, from the server's `nextStep` field (subscription / team errors always carry one). */
+    nextStep;
+    /**
+     * 403 SUBSCRIPTION_MANDATE_EXCEEDED: the owner was asked to approve this request. Tell your human, retry the SAME request
+     * only after `subscription.approval_decided` APPROVED (single use, 24 h). Also set on a repeat call (PENDING / DENIED).
+     */
+    approvalId;
+    approvalStatus;
+    approvalExpiresAt;
+    constructor(message, init) {
+        super(message);
+        this.name = 'AgentChainApiError';
+        this.status = init.status;
+        this.code = init.code;
+        this.retryAfterSeconds = init.retryAfterSeconds;
+        this.body = init.body;
+        this.nextStep = init.nextStep;
+        this.approvalId = init.approvalId;
+        this.approvalStatus = init.approvalStatus;
+        this.approvalExpiresAt = init.approvalExpiresAt;
+    }
+}
+function parseRetryAfterSeconds(res, body) {
+    const fromBody = body?.retryAfterSeconds;
+    if (typeof fromBody === 'number' && Number.isFinite(fromBody) && fromBody >= 0)
+        return fromBody;
+    const header = res.headers?.get?.('retry-after');
+    if (!header)
+        return undefined;
+    const secs = Number(header);
+    if (Number.isFinite(secs) && secs >= 0)
+        return secs;
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? undefined : Math.max(0, Math.ceil((at - Date.now()) / 1000));
+}
+/** @internal Build the error for a failed response; message text matches the previous `new Error(...)`. */
+export function apiErrorFromResponse(res, body, message) {
+    const code = body?.code;
+    const nextStep = body?.nextStep;
+    const b = (body ?? {});
+    const str = (v) => (typeof v === 'string' && v ? v : undefined);
+    return new AgentChainApiError(message, {
+        approvalId: str(b.approvalId),
+        approvalStatus: str(b.approvalStatus),
+        approvalExpiresAt: str(b.approvalExpiresAt),
+        status: res.status,
+        code: typeof code === 'string' ? code : undefined,
+        nextStep: typeof nextStep === 'string' && nextStep.trim() ? nextStep.trim() : undefined,
+        retryAfterSeconds: parseRetryAfterSeconds(res, body),
+        body,
+    });
+}
+export const DEFAULT_RETRY_DELAY_MS = 600;
+function headerValue(headers, name) {
+    if (!headers)
+        return null;
+    try {
+        return new Headers(headers).get(name);
+    }
+    catch {
+        return null;
+    }
+}
+/** GET/HEAD, an `Idempotency-Key` header or a JSON body with `idempotencyKey` → safe to send twice. */
+export function isIdempotentRequest(init) {
+    const method = String(init?.method ?? 'GET').toUpperCase();
+    if (method === 'GET' || method === 'HEAD')
+        return true;
+    if (headerValue(init?.headers, 'idempotency-key'))
+        return true;
+    if (typeof init?.body === 'string') {
+        try {
+            const parsed = JSON.parse(init.body);
+            return typeof parsed?.idempotencyKey === 'string' && parsed.idempotencyKey.trim() !== '';
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function describeNetworkError(err) {
+    const cause = err?.cause;
+    const code = cause?.code || cause?.errno || err?.code || '';
+    const msg = cause?.message || (err instanceof Error ? err.message : String(err));
+    return [code, msg].filter(Boolean).join(': ');
+}
+function originAndPath(url) {
+    try {
+        const u = new URL(String(url));
+        return { origin: u.origin, path: u.pathname };
+    }
+    catch {
+        return { origin: String(url), path: String(url) };
+    }
+}
+/** Short, actionable message for a non-JSON answer (never includes the HTML). */
+export function nonJsonMessage(status, method, url) {
+    const hint = status === 404
+        ? 'route not found or server restarting'
+        : status >= 500
+            ? 'server error or server restarting'
+            : 'unexpected response';
+    return `AgentChain returned a non-JSON ${status} page — ${hint}; retry (${method.toUpperCase()} ${originAndPath(url).path}).`;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * fetch + JSON parse. Returns the response and the parsed body (`{}` for an empty body); the caller
+ * decides how to turn `!res.ok` into an error. Throws {@link AgentChainApiError} for network errors
+ * and non-JSON answers after one retry of an idempotent request.
+ */
+export async function fetchJson(url, init = {}, opts = {}) {
+    const method = String(init.method ?? 'GET').toUpperCase();
+    const attempts = opts.retry !== false && isIdempotentRequest(init) ? 2 : 1;
+    const delay = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    for (let attempt = 1;; attempt++) {
+        let res;
+        try {
+            res = await fetch(url, init);
+        }
+        catch (err) {
+            if (err?.name === 'AbortError')
+                throw err;
+            if (attempt < attempts) {
+                await sleep(delay);
+                continue;
+            }
+            throw new AgentChainApiError(`AgentChain API unreachable at ${originAndPath(url).origin} (${describeNetworkError(err)}) — network error or server restarting; retry.`, { status: 0, code: 'NETWORK_ERROR' });
+        }
+        const text = await res.text();
+        try {
+            return { res, body: text ? JSON.parse(text) : {} };
+        }
+        catch {
+            if (attempt < attempts) {
+                await sleep(delay);
+                continue;
+            }
+            throw new AgentChainApiError(nonJsonMessage(res.status, method, url), {
+                status: res.status,
+                code: 'NON_JSON_RESPONSE',
+                retryAfterSeconds: parseRetryAfterSeconds(res, null),
+            });
+        }
+    }
+}