@exayard/sdk 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @exayard/sdk — official TypeScript SDK for the Exayard API.
+ *
+ * Every API operation is generated from the API spec (apps/api/openapi.json)
+ * into src/_generated/ by scripts/generate.mts, and callable by name or as a
+ * typed method. The resource groups (exa.projects, exa.files, ...) are a
+ * hand-written layer over the same calls, with helpers such as files.upload.
+ *
+ * Usage:
+ *
+ *   import { Exayard } from '@exayard/sdk'
+ *   const exa = new Exayard({ apiKey: process.env.EXAYARD_API_KEY, endUser: 'customer-42' })
+ *   const projects = await exa.projects.list({})
+ *   const quotes = await exa.api.listVendorQuotes({ id: projectId })
+ *   const same = await exa.call('list_vendor_quotes', { id: projectId })
+ *
+ * Design notes:
+ * - Keys: `exa_live_` / `exa_test_` app keys and the older `ak_` keys and `xa_app_` secrets all work.
+ * - `organizationId` is optional on every call: the key implies the company, or the client's default fills it.
+ * - `endUser` (client or per call) is sent as the Exayard-End-User header and recorded on the call's usage.
+ * - 429, 5xx and dropped connections are retried (2 retries by default), honouring Retry-After; every
+ *   POST/PATCH/PUT/DELETE carries one Idempotency-Key that every retry reuses.
+ * - Errors are typed by the problem+json `code` (RateLimitError, AuthenticationError, ...), all ExayardError.
+ * - Webhook verification: `exa.webhooks.constructEvent(rawBody, signatureHeader, secret)`.
+ */
+export { Exayard } from './client';
+export type { ExayardOptions, VendorQuoteStatus, VendorQuoteLineItem, DocumentShare, BidWarning, GeneratedDocument } from './client';
+export { OPERATIONS } from './_generated/operations';
+export type { OperationInput, OperationMethods, OperationName, OperationOutput, OperationParam, OperationSpec } from './_generated/operations';
+export type { CallOptions, WithOptionalOrganization } from './options';
+export { END_USER_HEADER, END_USER_MAX_LENGTH, isValidEndUser } from './options';
+export { APIConnectionError, AuthenticationError, BadRequestError, ConflictError, errorFromProblem, ExayardError, InternalServerError, NotFoundError, PaymentRequiredError, PermissionDeniedError, RateLimitError, UnprocessableEntityError } from './error';
+export type { ExayardErrorBody, ExayardErrorCode } from './error';
+export { constructWebhookEvent, signWebhookPayload, WebhookSignatureError, WEBHOOK_EVENT_TYPES, WEBHOOK_SIGNATURE_HEADER, DEFAULT_WEBHOOK_TOLERANCE_SECONDS } from './webhooks';
+export type { WebhookEvent, WebhookEventType } from './webhooks';
+export { parseServerSentEvents, WebhookListeners } from './listeners';
+export type { ListenerEvent, ListenerEventsOptions, ServerSentEvent, WebhookListener } from './listeners';
+export { DEFAULT_MAX_RETRIES, parseRetryAfter } from './retry';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,iBAAiB,EAClB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACpD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,yBAAyB,CAAA;AAChC,YAAY,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACtE,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChF,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EACzB,MAAM,SAAS,CAAA;AAChB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AACjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,iCAAiC,EAClC,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACrE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACzG,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * @exayard/sdk — official TypeScript SDK for the Exayard API.
+ *
+ * Every API operation is generated from the API spec (apps/api/openapi.json)
+ * into src/_generated/ by scripts/generate.mts, and callable by name or as a
+ * typed method. The resource groups (exa.projects, exa.files, ...) are a
+ * hand-written layer over the same calls, with helpers such as files.upload.
+ *
+ * Usage:
+ *
+ *   import { Exayard } from '@exayard/sdk'
+ *   const exa = new Exayard({ apiKey: process.env.EXAYARD_API_KEY, endUser: 'customer-42' })
+ *   const projects = await exa.projects.list({})
+ *   const quotes = await exa.api.listVendorQuotes({ id: projectId })
+ *   const same = await exa.call('list_vendor_quotes', { id: projectId })
+ *
+ * Design notes:
+ * - Keys: `exa_live_` / `exa_test_` app keys and the older `ak_` keys and `xa_app_` secrets all work.
+ * - `organizationId` is optional on every call: the key implies the company, or the client's default fills it.
+ * - `endUser` (client or per call) is sent as the Exayard-End-User header and recorded on the call's usage.
+ * - 429, 5xx and dropped connections are retried (2 retries by default), honouring Retry-After; every
+ *   POST/PATCH/PUT/DELETE carries one Idempotency-Key that every retry reuses.
+ * - Errors are typed by the problem+json `code` (RateLimitError, AuthenticationError, ...), all ExayardError.
+ * - Webhook verification: `exa.webhooks.constructEvent(rawBody, signatureHeader, secret)`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRetryAfter = exports.DEFAULT_MAX_RETRIES = exports.WebhookListeners = exports.parseServerSentEvents = exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOK_SIGNATURE_HEADER = exports.WEBHOOK_EVENT_TYPES = exports.WebhookSignatureError = exports.signWebhookPayload = exports.constructWebhookEvent = exports.UnprocessableEntityError = exports.RateLimitError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.NotFoundError = exports.InternalServerError = exports.ExayardError = exports.errorFromProblem = exports.ConflictError = exports.BadRequestError = exports.AuthenticationError = exports.APIConnectionError = exports.isValidEndUser = exports.END_USER_MAX_LENGTH = exports.END_USER_HEADER = exports.OPERATIONS = exports.Exayard = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Exayard", { enumerable: true, get: function () { return client_1.Exayard; } });
+var operations_1 = require("./_generated/operations");
+Object.defineProperty(exports, "OPERATIONS", { enumerable: true, get: function () { return operations_1.OPERATIONS; } });
+var options_1 = require("./options");
+Object.defineProperty(exports, "END_USER_HEADER", { enumerable: true, get: function () { return options_1.END_USER_HEADER; } });
+Object.defineProperty(exports, "END_USER_MAX_LENGTH", { enumerable: true, get: function () { return options_1.END_USER_MAX_LENGTH; } });
+Object.defineProperty(exports, "isValidEndUser", { enumerable: true, get: function () { return options_1.isValidEndUser; } });
+var error_1 = require("./error");
+Object.defineProperty(exports, "APIConnectionError", { enumerable: true, get: function () { return error_1.APIConnectionError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return error_1.AuthenticationError; } });
+Object.defineProperty(exports, "BadRequestError", { enumerable: true, get: function () { return error_1.BadRequestError; } });
+Object.defineProperty(exports, "ConflictError", { enumerable: true, get: function () { return error_1.ConflictError; } });
+Object.defineProperty(exports, "errorFromProblem", { enumerable: true, get: function () { return error_1.errorFromProblem; } });
+Object.defineProperty(exports, "ExayardError", { enumerable: true, get: function () { return error_1.ExayardError; } });
+Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return error_1.InternalServerError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return error_1.NotFoundError; } });
+Object.defineProperty(exports, "PaymentRequiredError", { enumerable: true, get: function () { return error_1.PaymentRequiredError; } });
+Object.defineProperty(exports, "PermissionDeniedError", { enumerable: true, get: function () { return error_1.PermissionDeniedError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_1.RateLimitError; } });
+Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, get: function () { return error_1.UnprocessableEntityError; } });
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "constructWebhookEvent", { enumerable: true, get: function () { return webhooks_1.constructWebhookEvent; } });
+Object.defineProperty(exports, "signWebhookPayload", { enumerable: true, get: function () { return webhooks_1.signWebhookPayload; } });
+Object.defineProperty(exports, "WebhookSignatureError", { enumerable: true, get: function () { return webhooks_1.WebhookSignatureError; } });
+Object.defineProperty(exports, "WEBHOOK_EVENT_TYPES", { enumerable: true, get: function () { return webhooks_1.WEBHOOK_EVENT_TYPES; } });
+Object.defineProperty(exports, "WEBHOOK_SIGNATURE_HEADER", { enumerable: true, get: function () { return webhooks_1.WEBHOOK_SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "DEFAULT_WEBHOOK_TOLERANCE_SECONDS", { enumerable: true, get: function () { return webhooks_1.DEFAULT_WEBHOOK_TOLERANCE_SECONDS; } });
+var listeners_1 = require("./listeners");
+Object.defineProperty(exports, "parseServerSentEvents", { enumerable: true, get: function () { return listeners_1.parseServerSentEvents; } });
+Object.defineProperty(exports, "WebhookListeners", { enumerable: true, get: function () { return listeners_1.WebhookListeners; } });
+var retry_1 = require("./retry");
+Object.defineProperty(exports, "DEFAULT_MAX_RETRIES", { enumerable: true, get: function () { return retry_1.DEFAULT_MAX_RETRIES; } });
+Object.defineProperty(exports, "parseRetryAfter", { enumerable: true, get: function () { return retry_1.parseRetryAfter; } });

package/dist/listeners.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Webhook listeners: receive the company's webhook events over a server-sent event stream instead of at a public
+ * endpoint. This is what `exayard listen` runs on; the server protocol is agents/lab/developer-platform/W/LISTEN.md
+ * (routes in apps/api/routes/v1/webhook-handlers.ts).
+ *
+ *   const listener = await exa.webhooks.listeners.start({ events: ['bid.won'], name: 'my-laptop' })
+ *   for await (const event of exa.webhooks.listeners.events(listener.id)) {
+ *     // event.payload is the exact body a webhook endpoint would receive; sign it with listener.secret to forward it
+ *   }
+ *   await exa.webhooks.listeners.stop(listener.id)
+ *
+ * The server closes each stream after about two minutes with `event: reconnect`; `events()` reconnects at once with
+ * Last-Event-ID, so nothing is missed. A stream that ends any other way is reopened after the server's `retry:`
+ * interval. A stopped or swept listener answers 404, which `events()` throws as NotFoundError.
+ */
+import type { CallOptions } from './options';
+import type { WebhookEventType } from './webhooks';
+export interface WebhookListener {
+    id: string;
+    /** The whsec_ secret forwarded events are signed with. Returned only by start; keep it in memory. */
+    secret: string;
+    events: string[];
+    name?: string;
+}
+/** One event on a listener's stream. */
+export interface ListenerEvent {
+    /** The listener's own sequence number, 1, 2, 3, ...; resume after it with `after`. */
+    seq: number;
+    eventId: string;
+    type: WebhookEventType;
+    test: boolean;
+    createdAt: number;
+    /** The exact JSON body a webhook endpoint would receive. Forward these bytes unchanged and sign exactly them. */
+    payload: string;
+}
+/** One parsed server-sent event (the fields of the HTML event-stream format). */
+export interface ServerSentEvent {
+    id?: string;
+    event?: string;
+    data: string;
+    retry?: number;
+}
+/**
+ * Parse a text/event-stream body into its events. Comment lines (`: keepalive`) are skipped; an event with no
+ * data and no `retry:` is skipped too, while a lone `retry:` is passed on so the caller can read the interval.
+ */
+export declare function parseServerSentEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent>;
+/** What the listener API needs from the client: its request primitive. */
+export interface ListenerTransport {
+    request<R>(opts: {
+        method: 'GET' | 'POST' | 'DELETE';
+        path: string;
+        query?: Record<string, string | undefined>;
+        body?: unknown;
+        headers?: Record<string, string>;
+        raw?: boolean;
+        options?: CallOptions;
+    }): Promise<R>;
+    organizationId(named?: string): string | undefined;
+}
+export interface ListenerEventsOptions {
+    /** Resume after this sequence number (Last-Event-ID). Unset: from the start of what the listener holds. */
+    after?: number;
+    organizationId?: string;
+    /** Stops the stream. */
+    signal?: AbortSignal;
+    /** Reconnects in a row that may fail (no answer, or a 5xx after the SDK's own retries) before it gives up. Default 10. */
+    maxReconnects?: number;
+    /** Called each time the stream is reopened, with the sequence number it resumes after. */
+    onReconnect?: (after: number | undefined) => void;
+}
+export declare class WebhookListeners {
+    private readonly transport;
+    constructor(transport: ListenerTransport);
+    /** Start a listener. `events` defaults to every event (`["*"]`). Needs `write:webhooks`. */
+    start(body?: {
+        events?: string[];
+        name?: string;
+        organizationId?: string;
+    }, opts?: CallOptions): Promise<WebhookListener>;
+    /** Send a test event of a concrete type to the listener; it arrives on the stream with `test: true`. */
+    sendTest(id: string, body: {
+        type: WebhookEventType;
+        organizationId?: string;
+    }, opts?: CallOptions): Promise<{
+        eventId: string;
+        seq: number;
+    }>;
+    /** Stop the listener and delete its events. */
+    stop(id: string, query?: {
+        organizationId?: string;
+    }, opts?: CallOptions): Promise<void>;
+    /** Open the stream once and return the raw Response (text/event-stream). Most callers want `events()`. */
+    open(id: string, opts?: {
+        after?: number;
+        organizationId?: string;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * The listener's events, in order, for as long as the listener lives: reconnects on `event: reconnect` and on a
+     * dropped stream, resuming after the last event it yielded. Ends when `signal` aborts. Throws NotFoundError when
+     * the listener was stopped or swept, and the last error after `maxReconnects` failed reconnects in a row.
+     */
+    events(id: string, opts?: ListenerEventsOptions): AsyncGenerator<ListenerEvent>;
+}
+//# sourceMappingURL=listeners.d.ts.map

package/dist/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../src/listeners.ts"],"names":[],"mappings":"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"}

package/dist/listeners.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Webhook listeners: receive the company's webhook events over a server-sent event stream instead of at a public
+ * endpoint. This is what `exayard listen` runs on; the server protocol is agents/lab/developer-platform/W/LISTEN.md
+ * (routes in apps/api/routes/v1/webhook-handlers.ts).
+ *
+ *   const listener = await exa.webhooks.listeners.start({ events: ['bid.won'], name: 'my-laptop' })
+ *   for await (const event of exa.webhooks.listeners.events(listener.id)) {
+ *     // event.payload is the exact body a webhook endpoint would receive; sign it with listener.secret to forward it
+ *   }
+ *   await exa.webhooks.listeners.stop(listener.id)
+ *
+ * The server closes each stream after about two minutes with `event: reconnect`; `events()` reconnects at once with
+ * Last-Event-ID, so nothing is missed. A stream that ends any other way is reopened after the server's `retry:`
+ * interval. A stopped or swept listener answers 404, which `events()` throws as NotFoundError.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookListeners = void 0;
+exports.parseServerSentEvents = parseServerSentEvents;
+const error_1 = require("./error");
+const retry_1 = require("./retry");
+/**
+ * Parse a text/event-stream body into its events. Comment lines (`: keepalive`) are skipped; an event with no
+ * data and no `retry:` is skipped too, while a lone `retry:` is passed on so the caller can read the interval.
+ */
+async function* parseServerSentEvents(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let current = { data: [] };
+    const flush = () => {
+        const out = current;
+        current = { data: [] };
+        if (out.data.length === 0 && out.retry === undefined && out.event === undefined)
+            return null;
+        return {
+            ...(out.id !== undefined ? { id: out.id } : {}),
+            ...(out.event !== undefined ? { event: out.event } : {}),
+            data: out.data.join('\n'),
+            ...(out.retry !== undefined ? { retry: out.retry } : {})
+        };
+    };
+    const take = function* (line) {
+        if (line === '') {
+            const event = flush();
+            if (event)
+                yield event;
+            return;
+        }
+        if (line.startsWith(':'))
+            return;
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'data')
+            current.data.push(value);
+        else if (field === 'event')
+            current.event = value;
+        else if (field === 'id')
+            current.id = value;
+        else if (field === 'retry' && /^\d+$/.test(value))
+            current.retry = Number(value);
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let newline = buffer.search(/\r\n|\r|\n/);
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline);
+                const width = buffer.startsWith('\r\n', newline) ? 2 : 1;
+                // A lone \r at the very end may be the first half of \r\n: wait for the next chunk.
+                if (width === 1 && buffer[newline] === '\r' && newline === buffer.length - 1)
+                    break;
+                buffer = buffer.slice(newline + width);
+                yield* take(line);
+                newline = buffer.search(/\r\n|\r|\n/);
+            }
+        }
+        buffer += decoder.decode();
+        if (buffer !== '')
+            yield* take(buffer);
+        // A final event without its blank line is discarded, as the format says.
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+const DEFAULT_RETRY_MS = 1_000;
+const DEFAULT_MAX_RECONNECTS = 10;
+class WebhookListeners {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Start a listener. `events` defaults to every event (`["*"]`). Needs `write:webhooks`. */
+    start(body = {}, opts = {}) {
+        return this.transport.request({
+            method: 'POST',
+            path: '/webhook_listeners',
+            body: { ...body, organizationId: this.transport.organizationId(body.organizationId) },
+            options: opts
+        });
+    }
+    /** Send a test event of a concrete type to the listener; it arrives on the stream with `test: true`. */
+    sendTest(id, body, opts = {}) {
+        return this.transport.request({
+            method: 'POST',
+            path: `/webhook_listeners/${encodeURIComponent(id)}/test`,
+            body: { ...body, organizationId: this.transport.organizationId(body.organizationId) },
+            options: opts
+        });
+    }
+    /** Stop the listener and delete its events. */
+    async stop(id, query = {}, opts = {}) {
+        await this.transport.request({
+            method: 'DELETE',
+            path: `/webhook_listeners/${encodeURIComponent(id)}`,
+            query: { organizationId: this.transport.organizationId(query.organizationId) },
+            options: opts
+        });
+    }
+    /** Open the stream once and return the raw Response (text/event-stream). Most callers want `events()`. */
+    open(id, opts = {}) {
+        return this.transport.request({
+            method: 'GET',
+            path: `/webhook_listeners/${encodeURIComponent(id)}/events`,
+            query: { organizationId: this.transport.organizationId(opts.organizationId) },
+            headers: {
+                Accept: 'text/event-stream',
+                ...(opts.after !== undefined ? { 'Last-Event-ID': String(opts.after) } : {})
+            },
+            raw: true,
+            // The stream stays open for minutes: no per-attempt timeout once the answer has started.
+            options: { signal: opts.signal, timeoutMs: 30_000 }
+        });
+    }
+    /**
+     * The listener's events, in order, for as long as the listener lives: reconnects on `event: reconnect` and on a
+     * dropped stream, resuming after the last event it yielded. Ends when `signal` aborts. Throws NotFoundError when
+     * the listener was stopped or swept, and the last error after `maxReconnects` failed reconnects in a row.
+     */
+    async *events(id, opts = {}) {
+        let after = opts.after;
+        let retryMs = DEFAULT_RETRY_MS;
+        let failures = 0;
+        let first = true;
+        const maxReconnects = opts.maxReconnects ?? DEFAULT_MAX_RECONNECTS;
+        while (!opts.signal?.aborted) {
+            if (!first)
+                opts.onReconnect?.(after);
+            first = false;
+            let res;
+            try {
+                res = await this.open(id, { after, organizationId: opts.organizationId, signal: opts.signal });
+            }
+            catch (err) {
+                if (opts.signal?.aborted)
+                    return;
+                if (err instanceof error_1.NotFoundError || (err instanceof error_1.ExayardError && err.status >= 400 && err.status < 500 && err.status !== 429))
+                    throw err;
+                failures += 1;
+                if (failures > maxReconnects)
+                    throw err;
+                await sleepUnlessAborted(Math.max(retryMs, (0, retry_1.retryDelayMs)(failures)), opts.signal);
+                continue;
+            }
+            if (!res.body)
+                throw new Error('Exayard: the listener stream answered with no body.');
+            failures = 0;
+            let reconnectAtOnce = false;
+            try {
+                for await (const message of parseServerSentEvents(res.body)) {
+                    if (message.retry !== undefined)
+                        retryMs = message.retry;
+                    if (message.event === 'reconnect') {
+                        reconnectAtOnce = true;
+                        break;
+                    }
+                    if (message.event !== 'webhook' || message.data === '')
+                        continue;
+                    const event = JSON.parse(message.data);
+                    after = event.seq;
+                    yield event;
+                }
+            }
+            catch (err) {
+                if (opts.signal?.aborted)
+                    return;
+                if (err instanceof SyntaxError)
+                    throw err;
+                // A read that failed mid-stream: reopen it like any dropped stream.
+            }
+            finally {
+                await res.body.cancel().catch(() => undefined);
+            }
+            if (!reconnectAtOnce)
+                await sleepUnlessAborted(retryMs, opts.signal);
+        }
+    }
+}
+exports.WebhookListeners = WebhookListeners;
+const sleepUnlessAborted = async (ms, signal) => {
+    try {
+        await (0, retry_1.sleep)(ms, signal);
+    }
+    catch {
+        // Aborted: the loop condition ends the stream.
+    }
+};

package/dist/options.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-request options, the last argument of every SDK call.
+ *
+ * Hand-written (the generated operation table imports it), so a spec
+ * regeneration never changes what a call accepts beyond its input.
+ */
+export interface CallOptions {
+    /**
+     * Sent as Idempotency-Key. A POST, PATCH, PUT or DELETE gets one generated when this is unset, and every retry of
+     * that call reuses it, so a retried call never runs twice.
+     */
+    idempotencyKey?: string;
+    /**
+     * Your own id for the person or account this call is for, sent as the `Exayard-End-User` header. It is recorded on
+     * the call's usage, so the Usage screen and the usage API can break usage down by end user. 1 to 128 printable
+     * characters; an opaque id, never an email address. Overrides the client's `endUser` for this call.
+     */
+    endUser?: string;
+    /** Retries after a 429, a 5xx or a dropped connection. Overrides the client's `maxRetries` for this call. */
+    maxRetries?: number;
+    /** Timeout for each attempt, in milliseconds. Overrides the client's `timeoutMs` for this call. */
+    timeoutMs?: number;
+    /** Cancels the call, including any retry wait. */
+    signal?: AbortSignal;
+}
+/** The request header that names the end user (the server's END_USER_HEADER). */
+export declare const END_USER_HEADER = "Exayard-End-User";
+/** The longest end user id the API accepts, in characters. */
+export declare const END_USER_MAX_LENGTH = 128;
+/** Whether the API accepts this end user id: printable ASCII, space included, 1 to 128 characters. */
+export declare const isValidEndUser: (value: string) => boolean;
+/**
+ * The company field is optional on every call: a company key, or an `exa_` key bound to its own company, implies
+ * the company, and the client's `organizationId` fills it otherwise. A personal key or sign-in still names one.
+ */
+export type WithOptionalOrganization<T> = T extends {
+    organizationId: infer O;
+} ? Omit<T, 'organizationId'> & {
+    organizationId?: O;
+} : T;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6GAA6G;IAC7G,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mGAAmG;IACnG,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,qBAAqB,CAAA;AAEjD,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAItC,sGAAsG;AACtG,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,OAAuC,CAAA;AAEtF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,cAAc,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3E,IAAI,CAAC,CAAC,EAAE,gBAAgB,CAAC,GAAG;IAAE,cAAc,CAAC,EAAE,CAAC,CAAA;CAAE,GAClD,CAAC,CAAA"}

package/dist/options.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidEndUser = exports.END_USER_MAX_LENGTH = exports.END_USER_HEADER = void 0;
+/** The request header that names the end user (the server's END_USER_HEADER). */
+exports.END_USER_HEADER = 'Exayard-End-User';
+/** The longest end user id the API accepts, in characters. */
+exports.END_USER_MAX_LENGTH = 128;
+const END_USER_PATTERN = new RegExp(`^[\\x20-\\x7E]{1,${exports.END_USER_MAX_LENGTH}}$`);
+/** Whether the API accepts this end user id: printable ASCII, space included, 1 to 128 characters. */
+const isValidEndUser = (value) => END_USER_PATTERN.test(value);
+exports.isValidEndUser = isValidEndUser;

package/dist/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * When the SDK retries a call, and how long it waits first.
+ *
+ * Retried: 429, every 5xx, and a request that got no answer (dropped connection, per-attempt timeout). Every POST,
+ * PATCH, PUT and DELETE carries an Idempotency-Key that each retry reuses, so the server runs the call once at most;
+ * the server never stores a 5xx under the key, so a retry after one is a real second attempt.
+ */
+/** Retries after the first attempt, unless the client or the call says otherwise. */
+export declare const DEFAULT_MAX_RETRIES = 2;
+/** The longest wait the SDK honours from Retry-After; a longer one is answered as the error itself. */
+export declare const MAX_RETRY_AFTER_SECONDS = 60;
+export declare const isRetryableStatus: (status: number) => boolean;
+/**
+ * Retry-After in seconds: delta-seconds or an HTTP date (RFC 9110 10.2.3). Undefined when absent or unreadable.
+ */
+export declare const parseRetryAfter: (value: string | null | undefined, now?: number) => number | undefined;
+/**
+ * The wait before retry number `attempt` (1 for the first retry): Retry-After when the server sent one, else
+ * exponential backoff from 0.5 s, capped at 8 s, with up to 25% jitter taken off.
+ */
+export declare const retryDelayMs: (attempt: number, retryAfterSeconds?: number, random?: () => number) => number;
+/** Resolves after `ms`, or rejects at once when `signal` aborts. */
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAKzC,eAAO,MAAM,iBAAiB,WAAY,MAAM,KAAG,OAA0C,CAAA;AAE7F;;GAEG;AACH,eAAO,MAAM,eAAe,UAAW,MAAM,GAAG,IAAI,GAAG,SAAS,QAAO,MAAM,KAAgB,MAAM,GAAG,SAQrG,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,YAAa,MAAM,sBAAsB,MAAM,WAAU,MAAM,MAAM,KAAiB,MAI9G,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,KAAK,OAAQ,MAAM,WAAW,WAAW,KAAG,OAAO,CAAC,IAAI,CAejE,CAAA"}

package/dist/retry.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * When the SDK retries a call, and how long it waits first.
+ *
+ * Retried: 429, every 5xx, and a request that got no answer (dropped connection, per-attempt timeout). Every POST,
+ * PATCH, PUT and DELETE carries an Idempotency-Key that each retry reuses, so the server runs the call once at most;
+ * the server never stores a 5xx under the key, so a retry after one is a real second attempt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = exports.retryDelayMs = exports.parseRetryAfter = exports.isRetryableStatus = exports.MAX_RETRY_AFTER_SECONDS = exports.DEFAULT_MAX_RETRIES = void 0;
+/** Retries after the first attempt, unless the client or the call says otherwise. */
+exports.DEFAULT_MAX_RETRIES = 2;
+/** The longest wait the SDK honours from Retry-After; a longer one is answered as the error itself. */
+exports.MAX_RETRY_AFTER_SECONDS = 60;
+const BASE_DELAY_MS = 500;
+const MAX_BACKOFF_MS = 8_000;
+const isRetryableStatus = (status) => status === 429 || status >= 500;
+exports.isRetryableStatus = isRetryableStatus;
+/**
+ * Retry-After in seconds: delta-seconds or an HTTP date (RFC 9110 10.2.3). Undefined when absent or unreadable.
+ */
+const parseRetryAfter = (value, now = Date.now()) => {
+    if (value === null || value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return undefined;
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, (at - now) / 1000);
+};
+exports.parseRetryAfter = parseRetryAfter;
+/**
+ * The wait before retry number `attempt` (1 for the first retry): Retry-After when the server sent one, else
+ * exponential backoff from 0.5 s, capped at 8 s, with up to 25% jitter taken off.
+ */
+const retryDelayMs = (attempt, retryAfterSeconds, random = Math.random) => {
+    if (retryAfterSeconds !== undefined)
+        return Math.ceil(retryAfterSeconds * 1000);
+    const backoff = Math.min(MAX_BACKOFF_MS, BASE_DELAY_MS * 2 ** (attempt - 1));
+    return Math.round(backoff * (1 - 0.25 * random()));
+};
+exports.retryDelayMs = retryDelayMs;
+/** Resolves after `ms`, or rejects at once when `signal` aborts. */
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason ?? new Error('Aborted'));
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason ?? new Error('Aborted'));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+exports.sleep = sleep;

package/dist/webhooks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Webhook signature verification — Stripe-compatible pattern.
+ *
+ * Exayard signs every delivery (and `exayard listen` signs every forwarded event the same way) with:
+ *   Exayard-Signature: t=<unix seconds>,v1=<base64 HMAC-SHA256>
+ *
+ * where the signed payload is `${t}.${rawBody}` and the HMAC key is the UTF-8 bytes of the whole whsec_... secret,
+ * returned once when the endpoint (or listener) was created (server: packages/backend/convex/webhooks.ts deliver).
+ *
+ *   import { Exayard } from '@exayard/sdk'
+ *   const event = await exa.webhooks.constructEvent(rawBody, request.headers.get('Exayard-Signature')!, process.env.EXAYARD_WEBHOOK_SECRET!)
+ *   switch (event.type) {
+ *     case 'assessment.completed': ...
+ *     case 'bid.won':              ...
+ *   }
+ *
+ * Verify the raw body exactly as received: re-serializing parsed JSON changes the bytes and the signature fails.
+ */
+/** Every event type a webhook endpoint or `exayard listen` receives (the server's webhook event catalog). */
+export declare const WEBHOOK_EVENT_TYPES: readonly ['project.created', 'project.updated', 'project.archived', 'assessment.started', 'assessment.completed', 'assessment.cancelled', 'assessment.failed', 'estimate.generated', 'bid.generated', 'bid.submitted', 'bid.won', 'bid.lost', 'bid.accepted', 'bid.declined', 'bid.sent', 'bid.viewed', 'bid.commented', 'file.processed', 'addendum.uploaded', 'quote.requested', 'quote.received', 'quote.accepted', 'quote.rejected', 'quote.expired', 'conversation.started', 'conversation.handoff_requested', 'conversation.closed', 'lead.captured', 'contact.created', 'appointment.booked', 'appointment.rescheduled', 'appointment.cancelled', 'call.completed', 'call.missed', 'review.requested', 'job.written_back', 'payment.captured', 'payment.failed'];
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+export interface WebhookEvent<T = unknown> {
+    id: string;
+    type: WebhookEventType;
+    created: number;
+    /** The company the event came from (also sent as the Exayard-Organization-Id header). */
+    organizationId: string;
+    data: T;
+    /** True on a test event (sent from the Developer page, the API, or `exayard listen`). */
+    test?: boolean;
+}
+/** The header that carries the signature. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "Exayard-Signature";
+export declare class WebhookSignatureError extends Error {
+    readonly code: 'invalid_signature' | 'replay_window_exceeded' | 'malformed_header';
+    constructor(code: WebhookSignatureError['code'], message: string);
+}
+/** Default tolerance between the signature's timestamp and now: 5 minutes, as the server documents. */
+export declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS: number;
+/**
+ * The Exayard-Signature header value for a payload: what the server sends with each delivery, and what
+ * `exayard listen` sends with each forwarded event. Also useful to sign fixtures in your own tests.
+ */
+export declare const signWebhookPayload: (payload: string | Uint8Array, secret: string, options?: {
+    timestamp?: number;
+}) => Promise<string>;
+/**
+ * Verify a webhook delivery and parse its payload as a typed WebhookEvent.
+ *
+ * Throws WebhookSignatureError with a stable `code` on failure; answer it with a 400 so the delivery is retried:
+ *   - malformed_header: Exayard-Signature isn't in t=…,v1=… form
+ *   - replay_window_exceeded: the timestamp is more than `toleranceSeconds` (default 300) from now
+ *   - invalid_signature: no v1 digest matches
+ */
+export declare const constructWebhookEvent: <T = unknown>(payload: string | Uint8Array, signatureHeader: string | null | undefined, secret: string, options?: {
+    now?: number;
+    toleranceSeconds?: number;
+}) => Promise<WebhookEvent<T>>;
+//# sourceMappingURL=webhooks.d.ts.map