@exayard/sdk 0.3.0

package/dist/client.js

@@ -0,0 +1,404 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Exayard = void 0;
+const operations_1 = require("./_generated/operations");
+const error_1 = require("./error");
+const listeners_1 = require("./listeners");
+const options_1 = require("./options");
+const retry_1 = require("./retry");
+const webhooks_1 = require("./webhooks");
+const UNSAFE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+const randomIdempotencyKey = () => {
+    // Good enough for SDK auto-retries; callers needing deterministic keys
+    // pass their own. Uses crypto.randomUUID in runtimes that have it and
+    // falls back to timestamp+random.
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+        return `idem_${crypto.randomUUID().replace(/-/g, '')}`;
+    }
+    return `idem_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+};
+const envApiKey = () => {
+    if (typeof process === 'undefined' || !process.env)
+        return undefined;
+    const value = process.env.EXAYARD_API_KEY;
+    return value && value.trim() !== '' ? value.trim() : undefined;
+};
+const checkEndUser = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (!(0, options_1.isValidEndUser)(value)) {
+        throw new TypeError(`Exayard: endUser must be 1 to ${options_1.END_USER_MAX_LENGTH} printable characters.`);
+    }
+    return value;
+};
+const transportProblem = (code, status, detail, requestId) => ({
+    type: `https://developers.exayard.com/concepts/errors#${code}`,
+    title: code === 'transport_error' ? 'Transport Error' : code === 'timeout' ? 'Timeout' : 'Connection Error',
+    status,
+    detail,
+    code,
+    doc_url: `https://developers.exayard.com/concepts/errors#${code}`,
+    ...(requestId ? { request_id: requestId } : {})
+});
+class Exayard {
+    credential;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    defaultOrganizationId;
+    defaultEndUser;
+    constructor(opts = {}) {
+        const credential = opts.apiKey ?? opts.bearerToken ?? envApiKey();
+        if (!credential) {
+            throw new Error('Exayard: pass `apiKey` (or set EXAYARD_API_KEY) or `bearerToken` — see https://developers.exayard.com/api-reference.');
+        }
+        this.credential = credential;
+        this.baseUrl = (opts.baseUrl ?? 'https://api.exayard.com/v1').replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 60_000;
+        this.maxRetries = Math.max(0, opts.maxRetries ?? retry_1.DEFAULT_MAX_RETRIES);
+        this.fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
+        this.defaultOrganizationId = opts.organizationId;
+        this.defaultEndUser = checkEndUser(opts.endUser);
+    }
+    /** The company a call names, else the client's default; undefined lets the key imply it. */
+    organizationFor(named) {
+        return named ?? this.defaultOrganizationId;
+    }
+    // One attempt: the per-attempt timeout covers the wait for the answer's headers only, so a stream body is never
+    // cut by it; the caller's signal aborts both (its listener stays while the body may still be read).
+    async attempt(url, init, timeoutMs, signal) {
+        const ac = new AbortController();
+        let timedOut = false;
+        const onAbort = () => ac.abort(signal?.reason);
+        if (signal?.aborted)
+            ac.abort(signal.reason);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        const timer = timeoutMs > 0 ? setTimeout(() => ((timedOut = true), ac.abort()), timeoutMs) : undefined;
+        try {
+            return await this.fetchImpl(url, { ...init, signal: ac.signal });
+        }
+        catch (err) {
+            signal?.removeEventListener('abort', onAbort);
+            if (signal?.aborted)
+                throw err;
+            throw new error_1.APIConnectionError(timedOut
+                ? transportProblem('timeout', 0, `No answer within ${timeoutMs} ms.`)
+                : transportProblem('connection_error', 0, err?.message || 'The connection failed.'));
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async toError(res) {
+        const retryAfter = (0, retry_1.parseRetryAfter)(res.headers.get('Retry-After'));
+        const ct = res.headers.get('Content-Type') ?? '';
+        if (ct.includes('problem+json') || ct.includes('application/json')) {
+            const body = (await res.json().catch(() => null));
+            if (body && typeof body === 'object')
+                return (0, error_1.errorFromProblem)({ ...body, status: body.status ?? res.status }, retryAfter);
+        }
+        // Fallback for non-JSON error pages (shouldn't happen against /v1 but
+        // could hit a CDN error page if the service is down).
+        const text = await res.text().catch(() => '');
+        const body = transportProblem('transport_error', res.status, text.slice(0, 500) || `HTTP ${res.status}`, res.headers.get('X-Request-Id') ?? undefined);
+        return (0, error_1.errorFromProblem)({ ...body, code: res.status === 429 ? 'rate_limited' : body.code }, retryAfter);
+    }
+    // Internal request primitive. Public resource methods compose this.
+    async request(opts) {
+        const call = opts.options ?? {};
+        const url = new URL(`${this.baseUrl}${opts.path}`);
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            Accept: 'application/json',
+            Authorization: `Bearer ${this.credential}`,
+            ...opts.headers
+        };
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const endUser = checkEndUser(call.endUser) ?? this.defaultEndUser;
+        if (endUser !== undefined)
+            headers[options_1.END_USER_HEADER] = endUser;
+        // Idempotency-Key for unsafe methods, generated once and sent on every retry, so the server runs the call once
+        // at most. A caller's own key wins.
+        if (call.idempotencyKey)
+            headers['Idempotency-Key'] = call.idempotencyKey;
+        else if (UNSAFE_METHODS.has(opts.method))
+            headers['Idempotency-Key'] = randomIdempotencyKey();
+        const init = {
+            method: opts.method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined
+        };
+        const maxRetries = Math.max(0, call.maxRetries ?? this.maxRetries);
+        const timeoutMs = call.timeoutMs ?? this.timeoutMs;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.attempt(url.toString(), init, timeoutMs, call.signal);
+            }
+            catch (err) {
+                if (err instanceof error_1.APIConnectionError && attempt < maxRetries) {
+                    await (0, retry_1.sleep)((0, retry_1.retryDelayMs)(attempt + 1), call.signal);
+                    continue;
+                }
+                throw err;
+            }
+            if (res.ok) {
+                if (opts.raw)
+                    return res;
+                if (res.status === 204)
+                    return undefined;
+                const text = await res.text();
+                return (text === '' ? undefined : JSON.parse(text));
+            }
+            if ((0, retry_1.isRetryableStatus)(res.status) && attempt < maxRetries) {
+                const retryAfter = (0, retry_1.parseRetryAfter)(res.headers.get('Retry-After'));
+                if (retryAfter === undefined || retryAfter <= retry_1.MAX_RETRY_AFTER_SECONDS) {
+                    await res.body?.cancel().catch(() => undefined);
+                    await (0, retry_1.sleep)((0, retry_1.retryDelayMs)(attempt + 1, retryAfter), call.signal);
+                    continue;
+                }
+            }
+            throw await this.toError(res);
+        }
+    }
+    /**
+     * Call any API operation by its name: the spec's operationId, which is also
+     * its MCP tool name and its CLI command. The input is the operation's path,
+     * query and body fields merged flat, the same input its MCP tool takes.
+     */
+    call(name, input, opts = {}) {
+        const op = operations_1.OPERATIONS[name];
+        if (!op)
+            throw new Error(`Exayard: no operation named ${String(name)}`);
+        const args = { ...input };
+        const known = new Set(op.params.map(param => param.name));
+        const unknown = Object.keys(args).filter(field => !known.has(field));
+        if (unknown.length > 0)
+            throw new Error(`Exayard: ${name} does not take ${unknown.join(', ')}`);
+        if (known.has('organizationId') && args.organizationId === undefined && this.defaultOrganizationId) {
+            args.organizationId = this.defaultOrganizationId;
+        }
+        let path = op.path;
+        const query = {};
+        const body = {};
+        for (const param of op.params) {
+            const value = args[param.name];
+            if (param.in === 'path') {
+                if (value === undefined || value === null || value === '')
+                    throw new Error(`Exayard: ${name} needs ${param.name}`);
+                path = path.replace(`{${param.name}}`, encodeURIComponent(String(value)));
+            }
+            else if (value !== undefined) {
+                if (param.in === 'query')
+                    query[param.name] = value;
+                else
+                    body[param.name] = value;
+            }
+        }
+        return this.request({
+            method: op.method,
+            path,
+            query,
+            body: op.body ? body : undefined,
+            raw: op.response === 'stream',
+            options: opts
+        });
+    }
+    /**
+     * Every API operation as a typed method, generated from the API spec:
+     * `exa.api.listVendorQuotes({ id: projectId })`.
+     */
+    api = Object.fromEntries(Object.entries(operations_1.OPERATION_METHODS).map(([method, name]) => [
+        method,
+        (input, opts) => this.call(name, input, opts)
+    ]));
+    // ---------------------------------------------------------------------------
+    // Resource surface — a curated layer over the generated operations for the
+    // flows agents and integrations most often hit. Each method is a call() of the
+    // operation it names, so its input and output types come from the API spec.
+    // Everything else is on `exa.api` and `exa.call`. `organizationId` is optional
+    // everywhere: the key implies the company, or the client's default fills it.
+    // ---------------------------------------------------------------------------
+    me = {
+        get: () => this.call('get_me', {})
+    };
+    projects = {
+        // GET /v1/projects returns a raw array; there is no { items, next_cursor }
+        // envelope and no limit/cursor pagination yet.
+        list: (query) => this.call('list_projects', query),
+        get: (id, query = {}) => this.call('get_project', { id, ...query }),
+        create: (body, opts = {}) => this.call('create_project', body, opts),
+        export: (id, query = {}) => this.call('export_project', { id, ...query }),
+        archive: (id, query = {}) => this.call('archive_project', { id, ...query })
+    };
+    // File upload is a 3-step dance: presign (get an R2 upload URL) → PUT the
+    // bytes straight to R2 → confirm (which also kicks off PDF page extraction).
+    // `upload` wraps all three. A PDF becomes pages asynchronously after confirm —
+    // poll pages.list() until processingStatus is 'complete' before proposing/running.
+    // The project decides the organization, so none of the three takes one.
+    files = {
+        presign: (body) => this.call('presign_file_upload', body),
+        confirm: (fileId, r2Key) => this.call('confirm_file_upload', { id: fileId, r2Key }),
+        // Convenience: presign → PUT bytes to the presigned R2 URL → confirm.
+        // The PUT goes directly to R2 (a different host, self-authenticated by the
+        // signed URL) — not through the /v1 request primitive.
+        upload: async (body) => {
+            const buf = body.bytes instanceof ArrayBuffer ? new Uint8Array(body.bytes) : body.bytes;
+            const { fileId, uploadUrl, r2Key } = await this.files.presign({
+                projectId: body.projectId,
+                filename: body.filename,
+                mimeType: body.mimeType,
+                fileSize: buf.byteLength,
+                folderId: body.folderId
+            });
+            const put = await this.fetchImpl(uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': body.mimeType },
+                // Node/undici fetch accepts a Uint8Array body at runtime; the DOM
+                // BodyInit type doesn't list it, so cast at this boundary.
+                body: buf
+            });
+            if (!put.ok) {
+                throw new error_1.ExayardError({
+                    type: 'https://developers.exayard.com/concepts/errors#transport_error',
+                    title: 'Upload Failed',
+                    status: put.status,
+                    detail: `PUT to storage failed: HTTP ${put.status}`,
+                    code: 'transport_error',
+                    doc_url: 'https://developers.exayard.com/concepts/errors#transport_error'
+                });
+            }
+            await this.files.confirm(fileId, r2Key);
+            return { fileId };
+        }
+    };
+    // List a project's pages (grouped by file). Use to discover pageIds + poll
+    // each file's processingStatus until extraction finishes.
+    pages = {
+        list: (projectId, query = {}) => this.call('list_pages', { id: projectId, ...query })
+    };
+    // AI takeoff assessments. Reads resolve the org from the project/assessment
+    // (no organizationId). `run` kicks off an AI run on an existing project's
+    // pages — pair with the assessment.completed webhook + latest()/takeoffSummary
+    // to pull results once it finishes.
+    assessments = {
+        list: (projectId) => this.call('list_assessments', { id: projectId }),
+        latest: (projectId) => this.call('get_latest_assessment', { id: projectId }),
+        get: (id) => this.call('get_assessment', { id }),
+        takeoffSummary: (projectId) => this.call('get_takeoff_summary', { id: projectId }),
+        // Ask the AI what to measure: a natural-language prompt + pageIds → a
+        // proposed `elements` array (id/name/category/hexColor) you can pass
+        // straight to run(). The bridge for callers who don't already know the
+        // elements.
+        propose: (projectId, body) => this.call('propose_analysis', { id: projectId, ...body }),
+        // Run an AI takeoff analysis on an existing project and let it complete
+        // end-to-end (no human approval step). You specify exactly what to detect
+        // via `elements` (each: id, name, category area|linear|count, hexColor) on
+        // the given pageIds. Returns { assessmentId, pageIds }; track completion via
+        // the assessment.completed webhook + latest()/takeoffSummary.
+        //
+        // (The auto-detect POST /assessments path pauses at awaiting_approval,
+        // which needs a human, so it isn't wrapped here; it is exa.api.createAssessment.)
+        run: (projectId, body, opts = {}) => this.call('run_approved_analysis', { id: projectId, ...body }, opts)
+    };
+    // Generate an estimate from a project's takeoff and persist it as a document.
+    // Blocking: the estimator typically runs 30–60s, which is at the default
+    // 60s client timeout — raise `timeoutMs` when constructing the client.
+    //
+    // The saved document is PRIVATE to your organization. `share: true` also
+    // publishes it on a public link anyone holding the URL can read, and makes
+    // `documentUrl` the public path instead of the signed-in one. Set it only
+    // when the customer asked for a shareable link; `documents.setSharing` can
+    // share or unshare later either way.
+    //
+    // (The streaming sibling POST /v1/projects/{id}/estimates/generate persists
+    // no document and has no `share` flag; it is exa.api.generateEstimate, which
+    // returns the event-stream Response.)
+    estimates = {
+        create: (projectId, body, opts = {}) => this.call('create_estimate', { id: projectId, ...body }, opts)
+    };
+    // Same estimator wrapped with bid-formatting instructions, persisted as a
+    // bid document. Same blocking timing and same private-by-default `share`
+    // semantics as estimates.create. When `measurementContext` is omitted the
+    // takeoff is auto-loaded server-side, which can 422 on line items with
+    // missing formula variables — retry with `ignoreMissingVariables: true` to
+    // skip them (the skipped rows come back in `warnings`).
+    bids = {
+        create: (projectId, body, opts = {}) => this.call('create_bid', { id: projectId, ...body }, opts)
+    };
+    // Documents (estimates, bids, and anything else saved to a project) plus the
+    // sharing switch. Documents are private to the organization until someone
+    // enables sharing; enabling mints a secret and publishes a link readable by
+    // anyone on the internet who has the URL — no sign-in, no expiry.
+    //
+    // Disabling revokes access but KEEPS the secret, so re-enabling later revives
+    // the same URL. There is no rotate operation: a leaked link means the
+    // document is burned, not that a disable/enable cycle gives you a fresh one.
+    documents = {
+        // Both list endpoints return a raw array (no { items, next_cursor }
+        // envelope), like projects.list. They're here because setSharing needs a
+        // document id and only documents you just generated hand you one directly.
+        list: (query) => this.call('list_org_documents', query),
+        listByProject: (projectId, query = {}) => this.call('list_documents', { id: projectId, ...query }),
+        // Current sharing state rides the document body: `shareEnabled` and
+        // `shareSecret` come back on GET.
+        get: (id, query = {}) => this.call('get_document', { id, ...query }),
+        // A document id belonging to another organization answers 404 exactly like
+        // an id that doesn't exist.
+        setSharing: (id, body, opts = {}) => this.call('set_document_sharing', { id, ...body }, opts)
+    };
+    // Vendor quotes. Request a quote from a vendor for a project, advance it to
+    // `received` once the vendor responds (with priced line items), then record a
+    // terminal accepted | rejected | expired decision. Each transition fires a
+    // quote.* webhook. Note: there is no product UI for vendor quotes yet — these
+    // are visible only via this API and the webhooks.
+    quotes = {
+        list: (projectId, query) => this.call('list_vendor_quotes', { id: projectId, ...query }),
+        get: (id, query = {}) => this.call('get_vendor_quote', { id, ...query }),
+        create: (projectId, body, opts = {}) => this.call('create_vendor_quote', { id: projectId, ...body }, opts),
+        receive: (id, body, opts = {}) => this.call('receive_vendor_quote', { id, ...body }, opts),
+        updateStatus: (id, body, opts = {}) => this.call('update_vendor_quote_status', { id, ...body }, opts)
+    };
+    help = {
+        search: (body) => this.call('search_help_articles', body)
+    };
+    webhooks = {
+        listEndpoints: (query = {}) => this.call('list_webhook_endpoints', query),
+        createEndpoint: (body) => this.call('create_webhook_endpoint', body),
+        deleteEndpoint: (id, query = {}) => this.call('delete_webhook_endpoint', { id, ...query }),
+        listDeliveries: (id, query = {}) => this.call('list_webhook_deliveries', { id, ...query }),
+        /** Send a test event of one type to an endpoint, signed as usual, its body marked `"test": true`. */
+        sendTestEvent: (id, body, opts = {}) => this.request({
+            method: 'POST',
+            path: `/webhook_endpoints/${encodeURIComponent(id)}/test`,
+            body: { ...body, organizationId: this.organizationFor(body.organizationId) },
+            options: opts
+        }),
+        /** Send a delivery again, as a new delivery with the same event id and body. */
+        resendDelivery: (deliveryId, body = {}, opts = {}) => this.request({
+            method: 'POST',
+            path: `/webhook_deliveries/${encodeURIComponent(deliveryId)}/resend`,
+            body: { organizationId: this.organizationFor(body.organizationId) },
+            options: opts
+        }),
+        /** Receive the company's events over a stream, without a public endpoint (what `exayard listen` runs on). */
+        listeners: new listeners_1.WebhookListeners({
+            request: (opts) => this.request(opts),
+            organizationId: named => this.organizationFor(named)
+        }),
+        /**
+         * Parse + verify an inbound webhook delivery: `constructEvent(rawBody, signatureHeader, secret)`. Throws
+         * WebhookSignatureError on any signature failure — always catch and return 400 to let us retry.
+         */
+        constructEvent: webhooks_1.constructWebhookEvent
+    };
+}
+exports.Exayard = Exayard;

package/dist/error.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Typed error surface for SDK consumers.
+ *
+ * Every non-2xx response from /v1 is RFC 9457 problem+json with a stable `code`. The SDK throws the subclass that
+ * code (or, for a code it does not know, the HTTP status) belongs to, so callers can `instanceof` a class or branch
+ * on `err.code`. Every class extends ExayardError and carries the problem fields (code, param, doc_url, request_id)
+ * plus any extension members.
+ */
+export interface ExayardErrorBody {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    instance?: string;
+    code: string;
+    param?: string;
+    doc_url?: string;
+    request_id?: string;
+    [extension: string]: unknown;
+}
+/** The problem codes the API documents. Any other string can still arrive: branch on it as a string. */
+export type ExayardErrorCode = 'invalid_request' | 'invalid_end_user' | 'company_required' | 'company_mismatch' | 'unauthenticated' | 'api_key_expired' | 'insufficient_credits' | 'subscription_required' | 'upgrade_required' | 'paid_plan_required' | 'project_limit_reached' | 'usage_limit_reached' | 'forbidden' | 'insufficient_scope' | 'app_not_installed' | 'app_suspended' | 'partner_company_limit_reached' | 'not_found' | 'conflict' | 'idempotency_key_reused' | 'rate_limited' | 'internal_error' | 'transport_error' | 'connection_error' | 'timeout';
+export declare class ExayardError extends Error {
+    readonly type: string;
+    readonly title: string;
+    readonly status: number;
+    readonly detail: string;
+    readonly instance?: string;
+    readonly code: ExayardErrorCode | (string & {});
+    readonly param?: string;
+    readonly docUrl?: string;
+    readonly requestId?: string;
+    /** Problem extension members, such as `limit` on usage_limit_reached. */
+    readonly extensions: Record<string, unknown>;
+    constructor(body: ExayardErrorBody);
+    isRateLimited(): boolean;
+    isUnauthenticated(): boolean;
+    isNotFound(): boolean;
+    isInsufficientScope(): boolean;
+    isIdempotencyConflict(): boolean;
+}
+/** 400: the request is malformed (invalid_request, invalid_end_user, company_required, company_mismatch). */
+export declare class BadRequestError extends ExayardError {
+}
+/** 401: no credential, or one that is unknown, revoked or expired (unauthenticated, api_key_expired). */
+export declare class AuthenticationError extends ExayardError {
+}
+/** 402: the company's plan or AI usage does not cover the call (insufficient_credits, usage_limit_reached, ...). */
+export declare class PaymentRequiredError extends ExayardError {
+}
+/** 403: the credential may not do this (forbidden, insufficient_scope, app_not_installed, app_suspended). */
+export declare class PermissionDeniedError extends ExayardError {
+}
+/** 404: no such record, or one in another company. */
+export declare class NotFoundError extends ExayardError {
+}
+/** 409: a conflict, or an Idempotency-Key reused with a different request (idempotency_key_reused). */
+export declare class ConflictError extends ExayardError {
+}
+/** 422: the request is well formed but cannot be carried out. */
+export declare class UnprocessableEntityError extends ExayardError {
+}
+/** 429: too many requests. `retryAfter` is the server's Retry-After in seconds, when it sent one. */
+export declare class RateLimitError extends ExayardError {
+    readonly retryAfter?: number;
+    constructor(body: ExayardErrorBody, retryAfter?: number);
+}
+/** 5xx: the API failed. The SDK has already retried it. */
+export declare class InternalServerError extends ExayardError {
+}
+/** The request never got an answer: a dropped connection or a timeout (code connection_error or timeout). */
+export declare class APIConnectionError extends ExayardError {
+}
+/** The typed error for a problem+json body: by its `code`, else by its status. */
+export declare const errorFromProblem: (body: ExayardErrorBody, retryAfter?: number) => ExayardError;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAA;CAC7B;AAED,wGAAwG;AACxG,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,GACjB,iBAAiB,GACjB,sBAAsB,GACtB,uBAAuB,GACvB,kBAAkB,GAClB,oBAAoB,GACpB,uBAAuB,GACvB,qBAAqB,GACrB,WAAW,GACX,oBAAoB,GACpB,mBAAmB,GACnB,eAAe,GACf,+BAA+B,GAC/B,WAAW,GACX,UAAU,GACV,wBAAwB,GACxB,cAAc,GACd,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,SAAS,CAAA;AAIb,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAE5C,YAAY,IAAI,EAAE,gBAAgB,EAqBjC;IAGD,aAAa,IAAI,OAAO,CAEvB;IAED,iBAAiB,IAAI,OAAO,CAE3B;IAED,UAAU,IAAI,OAAO,CAEpB;IAED,mBAAmB,IAAI,OAAO,CAE7B;IAED,qBAAqB,IAAI,OAAO,CAE/B;CACF;AAED,6GAA6G;AAC7G,qBAAa,eAAgB,SAAQ,YAAY;CAAG;AACpD,yGAAyG;AACzG,qBAAa,mBAAoB,SAAQ,YAAY;CAAG;AACxD,oHAAoH;AACpH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG;AACzD,6GAA6G;AAC7G,qBAAa,qBAAsB,SAAQ,YAAY;CAAG;AAC1D,sDAAsD;AACtD,qBAAa,aAAc,SAAQ,YAAY;CAAG;AAClD,uGAAuG;AACvG,qBAAa,aAAc,SAAQ,YAAY;CAAG;AAClD,iEAAiE;AACjE,qBAAa,wBAAyB,SAAQ,YAAY;CAAG;AAC7D,qGAAqG;AACrG,qBAAa,cAAe,SAAQ,YAAY;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAE5B,YAAY,IAAI,EAAE,gBAAgB,EAAE,UAAU,CAAC,EAAE,MAAM,EAGtD;CACF;AACD,2DAA2D;AAC3D,qBAAa,mBAAoB,SAAQ,YAAY;CAAG;AACxD,6GAA6G;AAC7G,qBAAa,kBAAmB,SAAQ,YAAY;CAAG;AAwCvD,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,SAAU,gBAAgB,eAAe,MAAM,KAAG,YAK9E,CAAA"}

package/dist/error.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Typed error surface for SDK consumers.
+ *
+ * Every non-2xx response from /v1 is RFC 9457 problem+json with a stable `code`. The SDK throws the subclass that
+ * code (or, for a code it does not know, the HTTP status) belongs to, so callers can `instanceof` a class or branch
+ * on `err.code`. Every class extends ExayardError and carries the problem fields (code, param, doc_url, request_id)
+ * plus any extension members.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorFromProblem = exports.APIConnectionError = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.BadRequestError = exports.ExayardError = void 0;
+const KNOWN_FIELDS = new Set(['type', 'title', 'status', 'detail', 'instance', 'code', 'param', 'doc_url', 'request_id']);
+class ExayardError extends Error {
+    type;
+    title;
+    status;
+    detail;
+    instance;
+    code;
+    param;
+    docUrl;
+    requestId;
+    /** Problem extension members, such as `limit` on usage_limit_reached. */
+    extensions;
+    constructor(body) {
+        // Guard against upstream error pages that don't conform to Problem Details —
+        // a missing code/title/detail should still produce a useful message rather
+        // than the string "undefined (undefined): undefined".
+        const title = body.title ?? 'error';
+        const status = typeof body.status === 'number' ? body.status : 0;
+        const code = body.code ?? `http_${status || 'unknown'}`;
+        const detail = body.detail ?? '';
+        const message = detail ? `${title} (${code}): ${detail}` : `HTTP ${status || 'unknown'}: ${title}`;
+        super(message);
+        this.name = new.target.name;
+        this.type = body.type ?? 'about:blank';
+        this.title = title;
+        this.status = status;
+        this.detail = detail;
+        this.instance = body.instance;
+        this.code = code;
+        this.param = body.param;
+        this.docUrl = body.doc_url;
+        this.requestId = body.request_id;
+        this.extensions = Object.fromEntries(Object.entries(body).filter(([key]) => !KNOWN_FIELDS.has(key)));
+    }
+    // Convenience guards for the most common branching points.
+    isRateLimited() {
+        return this.code === 'rate_limited' || this.status === 429;
+    }
+    isUnauthenticated() {
+        return this.code === 'unauthenticated' || this.code === 'api_key_expired' || this.status === 401;
+    }
+    isNotFound() {
+        return this.code === 'not_found' || this.status === 404;
+    }
+    isInsufficientScope() {
+        return this.code === 'insufficient_scope' || this.status === 403;
+    }
+    isIdempotencyConflict() {
+        return this.code === 'idempotency_key_reused';
+    }
+}
+exports.ExayardError = ExayardError;
+/** 400: the request is malformed (invalid_request, invalid_end_user, company_required, company_mismatch). */
+class BadRequestError extends ExayardError {
+}
+exports.BadRequestError = BadRequestError;
+/** 401: no credential, or one that is unknown, revoked or expired (unauthenticated, api_key_expired). */
+class AuthenticationError extends ExayardError {
+}
+exports.AuthenticationError = AuthenticationError;
+/** 402: the company's plan or AI usage does not cover the call (insufficient_credits, usage_limit_reached, ...). */
+class PaymentRequiredError extends ExayardError {
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+/** 403: the credential may not do this (forbidden, insufficient_scope, app_not_installed, app_suspended). */
+class PermissionDeniedError extends ExayardError {
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+/** 404: no such record, or one in another company. */
+class NotFoundError extends ExayardError {
+}
+exports.NotFoundError = NotFoundError;
+/** 409: a conflict, or an Idempotency-Key reused with a different request (idempotency_key_reused). */
+class ConflictError extends ExayardError {
+}
+exports.ConflictError = ConflictError;
+/** 422: the request is well formed but cannot be carried out. */
+class UnprocessableEntityError extends ExayardError {
+}
+exports.UnprocessableEntityError = UnprocessableEntityError;
+/** 429: too many requests. `retryAfter` is the server's Retry-After in seconds, when it sent one. */
+class RateLimitError extends ExayardError {
+    retryAfter;
+    constructor(body, retryAfter) {
+        super(body);
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/** 5xx: the API failed. The SDK has already retried it. */
+class InternalServerError extends ExayardError {
+}
+exports.InternalServerError = InternalServerError;
+/** The request never got an answer: a dropped connection or a timeout (code connection_error or timeout). */
+class APIConnectionError extends ExayardError {
+}
+exports.APIConnectionError = APIConnectionError;
+const BY_CODE = {
+    invalid_request: BadRequestError,
+    invalid_end_user: BadRequestError,
+    company_required: BadRequestError,
+    company_mismatch: BadRequestError,
+    unauthenticated: AuthenticationError,
+    api_key_expired: AuthenticationError,
+    insufficient_credits: PaymentRequiredError,
+    subscription_required: PaymentRequiredError,
+    upgrade_required: PaymentRequiredError,
+    paid_plan_required: PaymentRequiredError,
+    project_limit_reached: PaymentRequiredError,
+    usage_limit_reached: PaymentRequiredError,
+    forbidden: PermissionDeniedError,
+    insufficient_scope: PermissionDeniedError,
+    app_not_installed: PermissionDeniedError,
+    app_suspended: PermissionDeniedError,
+    partner_company_limit_reached: PermissionDeniedError,
+    not_found: NotFoundError,
+    conflict: ConflictError,
+    idempotency_key_reused: ConflictError,
+    rate_limited: RateLimitError,
+    internal_error: InternalServerError
+};
+const BY_STATUS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError
+};
+/** The typed error for a problem+json body: by its `code`, else by its status. */
+const errorFromProblem = (body, retryAfter) => {
+    const status = typeof body.status === 'number' ? body.status : 0;
+    const cls = BY_CODE[body.code] ?? BY_STATUS[status] ?? (status >= 500 ? InternalServerError : ExayardError);
+    if (cls === RateLimitError)
+        return new RateLimitError(body, retryAfter);
+    return new cls(body);
+};
+exports.errorFromProblem = errorFromProblem;