@lumifyai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumify AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# @lumifyai/sdk
+
+Official TypeScript/JavaScript client for [Lumify](https://lumify.ai), the
+agent-ready sports intelligence API — schedules, live scores, odds, line
+movement, public betting splits, and AI bet intelligence across MLB, NFL,
+NCAAF, NBA, NHL, tennis, and soccer.
+
+> **Status:** v0.1.0 — the data-plane slice (sports/seasons/events/teams/players,
+> SSE streaming, webhooks, agent onboarding). Same data as the REST API and the
+> [MCP server](https://www.npmjs.com/package/@lumifyai/mcp) — this SDK *is* the
+> typed REST path, not a third implementation.
+
+## Install
+
+```bash
+npm install @lumifyai/sdk
+```
+
+Requires Node.js 18+ (uses native `fetch` and Web Crypto — zero runtime
+dependencies) or any modern browser/edge runtime.
+
+## Quick start
+
+```ts
+import { Lumify } from "@lumifyai/sdk";
+
+const client = new Lumify({ apiKey: process.env.LUMIFY_API_KEY! });
+
+const { sports } = await client.sports.list();
+
+const event = await client.events.get(12345, {
+  includeOdds: true,
+  includeIntelligence: true,
+});
+console.log(event.status, event.intelligence?.bets);
+```
+
+Create a key at <https://lumify.ai/api-keys> or programmatically via
+`client.agent.keys.create()`.
+
+## Resources
+
+```ts
+client.sports.list() / client.seasons.list()
+client.events.list(filters) / .get(id, { includeOdds?, includeIntelligence?, bookmaker? })
+client.events.odds(id) / .oddsHistory(id) / .score(id) / .intelligence(id) / .splits(id)
+client.events.stream(id)          // SSE async iterator of live score updates
+client.events.paginate(filters) / .iterate(filters)   // cursor pagination helpers
+client.teams.list(filters) / .get(id)
+client.players.list(filters) / .get(id) / .events(id, filters)
+client.webhooks.create() / .list() / .delete(id) / .verify(secret, header, rawBody)
+client.agent.keys.create() / .list() / .revoke(id)
+client.agent.credits.get() / .listPacks() / .topup(packId)
+```
+
+Every method maps 1:1 to a REST endpoint and returns the same JSON shape you'd
+get from `curl` — see <https://lumify.ai/docs/reference> for full field docs.
+
+## Pagination
+
+List endpoints are cursor-paginated (`after_id`/`limit`, max 100). Use the
+iterator helpers instead of tracking cursors by hand:
+
+```ts
+for await (const event of client.events.iterate({ sport: "nfl", status: "scheduled" })) {
+  console.log(event.id, event.starts_at);
+}
+
+// Or page-by-page (events pages use `events`, not `data`):
+for await (const page of client.events.paginate({ sport: "nfl" }, { limit: 50 })) {
+  console.log(page.events?.length, "events, next cursor:", page.next_after_id);
+}
+```
+
+## Live score streaming (SSE)
+
+```ts
+for await (const evt of client.events.stream(eventId)) {
+  if (evt.event === "score") console.log(evt.data.status, evt.data.clock);
+  if (evt.event === "done") break;
+}
+```
+
+Cheaper than polling `client.events.score(id)` — the server only emits on
+change, plus periodic keep-alives, and closes when the event finishes.
+
+## Webhooks
+
+```ts
+const sub = await client.webhooks.create({ url: "https://you.example.com/hooks/lumify" });
+// sub.signing_secret ("whsec_...") is returned once — store it.
+
+// In your webhook handler, verify against the *raw* request body:
+await client.webhooks.verify(signingSecret, req.header("Lumify-Signature")!, rawBody);
+```
+
+`verify()` throws `WebhookSignatureError` (bad format, signature mismatch, or a
+stale/replayed timestamp) — treat that as "reject with 4xx", not a crash.
+
+## Errors
+
+Every non-2xx response throws a typed subclass of `LumifyError` — switch on
+`err.code` (the stable machine-readable slug), not `err.message`:
+
+```ts
+import { NotFoundError, RateLimitError, ValidationError } from "@lumifyai/sdk";
+
+try {
+  await client.events.get(999999999);
+} catch (err) {
+  if (err instanceof NotFoundError) { /* ... */ }
+  if (err instanceof RateLimitError) console.log("retry after", err.retryAfter, "s");
+  if (err instanceof ValidationError) console.log(err.fieldErrors);
+}
+```
+
+`AuthenticationError` (401), `PaymentError` (402), `PermissionError` (403, has `.upgradeUrl` on
+sport-scope denials), `NotFoundError` (404), `ValidationError` (422, has
+`.fieldErrors`), `RateLimitError` (429, has `.retryAfter` from the envelope or
+`Retry-After` header), `APIError` (5xx), and `ConnectionError` (network/timeout,
+never reached the server) all extend `LumifyError` (`.code`, `.status`, `.docUrl`,
+`.requestId`).
+
+GET requests are automatically retried (default: 2 attempts) with exponential
+backoff on `429`/`5xx`/network failures, honoring `Retry-After`. Non-idempotent
+requests (`POST`/webhook & key creation) are never auto-retried. Configure with
+`maxRetries` / `timeoutMs` on the `Lumify` constructor.
+
+## Credits and rate limits
+
+Every successful response carries `X-Credits-Used`, `X-Credits-Remaining`, and
+`X-RateLimit-*` headers. Read them via `getMeta()` (attached as hidden metadata
+on the returned object, so it never pollutes `JSON.stringify` or your own
+types):
+
+```ts
+import { getMeta } from "@lumifyai/sdk";
+
+const odds = await client.events.odds(eventId);
+const meta = getMeta(odds);
+console.log(meta?.creditsUsed, meta?.rateLimitRemaining);
+```
+
+Queries for data that isn't available yet (e.g. odds not yet posted) return
+`creditsUsed: 0` — you're never charged for a "not available" read.
+
+## Sync with REST, MCP, and the OpenAPI contract
+
+This SDK's response types (`src/generated/models.ts`) are generated from
+Lumify's live OpenAPI schema, not hand-maintained — see
+`scripts/export_openapi_sdk.py` (repo root) and `scripts/gen-models.mjs`
+(this package). CI fails if either is stale, so the SDK can't silently drift
+from what the API actually returns. The client ergonomics (this README's
+resource shape, pagination/SSE/webhook helpers) are hand-written on top.
+
+```bash
+python scripts/export_openapi_sdk.py            # regenerate the schema slice
+node clients/lumify-sdk/scripts/gen-models.mjs   # regenerate the TS models
+```
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm test        # build + node --test
+```
+
+## License
+
+[MIT](./LICENSE) © 2026 Lumify AI
+
+## Related
+
+- Docs: <https://lumify.ai/docs>
+- MCP server (for AI agent runtimes): [`@lumifyai/mcp`](https://www.npmjs.com/package/@lumifyai/mcp)
+- npm: <https://www.npmjs.com/package/@lumifyai/sdk>

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+export declare const DEFAULT_BASE_URL = "https://lumify.ai";
+export interface LumifyClientOptions {
+    /** Lumify API key (`lmfy-...`). Create one at https://lumify.ai/api-keys. */
+    apiKey: string;
+    /** Override the API origin — mainly for testing against a local server. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Retries for idempotent (GET) requests on 429/5xx/network errors. Default 2. */
+    maxRetries?: number;
+    /** Injectable fetch implementation (tests, non-standard runtimes). */
+    fetch?: typeof fetch;
+    /** Extra string appended to the User-Agent header. */
+    userAgent?: string;
+}
+export type QueryParams = Record<string, string | number | boolean | null | undefined>;
+export interface RequestOptions {
+    query?: QueryParams;
+    body?: unknown;
+    /** Override retry behavior for this call (defaults to the method's idempotency). */
+    idempotent?: boolean;
+    signal?: AbortSignal;
+}
+/** Low-level HTTP transport shared by every resource. Not usually constructed directly — use {@link Lumify}. */
+export declare class LumifyClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    constructor(opts: LumifyClientOptions);
+    /** Build an absolute URL for a path, without performing the request. */
+    url(path: string, query?: QueryParams): string;
+    /**
+     * Base headers for a request that needs raw `fetch` (SSE streaming), where
+     * `request()`'s buffered JSON handling doesn't apply. Not part of the
+     * supported public API surface for arbitrary callers — resources within
+     * this package use it to avoid duplicating auth/UA construction.
+     */
+    authHeaders(accept?: string): Record<string, string>;
+    /** The injected/global `fetch` this client uses — for raw streaming calls (SSE). */
+    get fetchFn(): typeof fetch;
+    /** Per-request timeout (ms) configured on this client — used as the SSE connect timeout default. */
+    get requestTimeoutMs(): number;
+    /** GET a resource and parse its JSON body. */
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** POST a resource and parse its JSON body. Not retried by default (not idempotent). */
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** DELETE a resource and parse its JSON body. */
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Perform the raw fetch, with:
+     *  - Bearer auth + JSON headers
+     *  - a hard per-request timeout
+     *  - retries with exponential backoff for idempotent requests on 429/5xx/network
+     *    failures, honoring `Retry-After` / `error.retry_after` on 429
+     *  - the unified error envelope mapped to a typed {@link LumifyError} subclass
+     *  - X-Credits and X-RateLimit response headers attached to the parsed body
+     *    via {@link attachMeta} (read with {@link getMeta})
+     */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private shouldRetry;
+    private backoffMs;
+    private attempt;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAKpD,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,oFAAoF;IACpF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAiBD,gHAAgH;AAChH,qBAAa,YAAY;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,IAAI,EAAE,mBAAmB,EAgBpC;IAED,wEAAwE;IACxE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,CAE7C;IAED;;;;;OAKG;IACH,WAAW,CAAC,MAAM,SAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM/D;IAED,oFAAoF;IACpF,IAAI,OAAO,IAAI,OAAO,KAAK,CAE1B;IAED,oGAAoG;IACpG,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,8CAA8C;IAC9C,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAE7D;IAED,wFAAwF;IACxF,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAE9D;IAED,iDAAiD;IACjD,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhE;IAED;;;;;;;;;OASG;IACG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAoBvF;IAED,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,SAAS;YAUH,OAAO;CAmDtB"}

package/dist/client.js

@@ -0,0 +1,205 @@
+import { ConnectionError, APIError, errorFromResponse } from "./errors.js";
+import { attachMeta, parseMeta } from "./meta.js";
+export const DEFAULT_BASE_URL = "https://lumify.ai";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const SDK_VERSION = "0.1.0";
+function buildQuery(params) {
+    if (!params)
+        return "";
+    const usp = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        usp.set(key, String(value));
+    }
+    const qs = usp.toString();
+    return qs ? `?${qs}` : "";
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Low-level HTTP transport shared by every resource. Not usually constructed directly — use {@link Lumify}. */
+export class LumifyClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    userAgent;
+    constructor(opts) {
+        if (!opts.apiKey) {
+            throw new Error("Lumify SDK: `apiKey` is required (create one at https://lumify.ai/api-keys).");
+        }
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("Lumify SDK: no `fetch` available in this runtime. Use Node 18+, a browser, " +
+                "or pass a `fetch` implementation in the client options.");
+        }
+        this.userAgent = `lumify-sdk-js/${SDK_VERSION}${opts.userAgent ? ` ${opts.userAgent}` : ""}`;
+    }
+    /** Build an absolute URL for a path, without performing the request. */
+    url(path, query) {
+        return `${this.baseUrl}${path}${buildQuery(query)}`;
+    }
+    /**
+     * Base headers for a request that needs raw `fetch` (SSE streaming), where
+     * `request()`'s buffered JSON handling doesn't apply. Not part of the
+     * supported public API surface for arbitrary callers — resources within
+     * this package use it to avoid duplicating auth/UA construction.
+     */
+    authHeaders(accept = "application/json") {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: accept,
+            "User-Agent": this.userAgent,
+        };
+    }
+    /** The injected/global `fetch` this client uses — for raw streaming calls (SSE). */
+    get fetchFn() {
+        return this.fetchImpl;
+    }
+    /** Per-request timeout (ms) configured on this client — used as the SSE connect timeout default. */
+    get requestTimeoutMs() {
+        return this.timeoutMs;
+    }
+    /** GET a resource and parse its JSON body. */
+    get(path, options = {}) {
+        return this.request("GET", path, { ...options, idempotent: options.idempotent ?? true });
+    }
+    /** POST a resource and parse its JSON body. Not retried by default (not idempotent). */
+    post(path, options = {}) {
+        return this.request("POST", path, { ...options, idempotent: options.idempotent ?? false });
+    }
+    /** DELETE a resource and parse its JSON body. */
+    delete(path, options = {}) {
+        return this.request("DELETE", path, { ...options, idempotent: options.idempotent ?? true });
+    }
+    /**
+     * Perform the raw fetch, with:
+     *  - Bearer auth + JSON headers
+     *  - a hard per-request timeout
+     *  - retries with exponential backoff for idempotent requests on 429/5xx/network
+     *    failures, honoring `Retry-After` / `error.retry_after` on 429
+     *  - the unified error envelope mapped to a typed {@link LumifyError} subclass
+     *  - X-Credits and X-RateLimit response headers attached to the parsed body
+     *    via {@link attachMeta} (read with {@link getMeta})
+     */
+    async request(method, path, options = {}) {
+        const idempotent = options.idempotent ?? method === "GET";
+        const attempts = idempotent ? Math.max(1, this.maxRetries + 1) : 1;
+        let lastError;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            if (attempt > 0) {
+                await sleep(this.backoffMs(attempt, lastError));
+            }
+            try {
+                return await this.attempt(method, path, options);
+            }
+            catch (err) {
+                lastError = err;
+                if (!this.shouldRetry(err) || attempt === attempts - 1) {
+                    throw err;
+                }
+            }
+        }
+        // Unreachable — the loop always returns or throws — but keeps TS satisfied.
+        throw lastError;
+    }
+    shouldRetry(err) {
+        if (err instanceof ConnectionError)
+            return true;
+        const status = err.status;
+        return status === 429 || (typeof status === "number" && status >= 500);
+    }
+    backoffMs(attempt, lastError) {
+        const retryAfter = lastError?.retryAfter;
+        if (typeof retryAfter === "number" && retryAfter >= 0) {
+            return retryAfter * 1000;
+        }
+        const base = 250 * 2 ** (attempt - 1);
+        const jitter = Math.random() * 100;
+        return base + jitter;
+    }
+    async attempt(method, path, options) {
+        const url = this.url(path, options.query);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": this.userAgent,
+        };
+        let body;
+        if (options.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(options.body);
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error("timeout")), this.timeoutMs);
+        const signal = options.signal ? anySignal([options.signal, controller.signal]) : controller.signal;
+        let res;
+        try {
+            res = await this.fetchImpl(url, { method, headers, body, signal });
+        }
+        catch (err) {
+            throw new ConnectionError(`Request to ${method} ${path} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const requestId = res.headers.get("x-request-id");
+        const text = await res.text();
+        const json = text ? safeJsonParse(text) : undefined;
+        const parseFailed = Boolean(text) && json === undefined;
+        if (!res.ok) {
+            const payload = json?.error;
+            const retryAfterHeader = parseRetryAfter(res.headers.get("retry-after"));
+            throw errorFromResponse(res.status, payload, requestId, { retryAfterHeader });
+        }
+        if (parseFailed) {
+            throw new APIError(`Response from ${method} ${path} was not valid JSON.`, {
+                status: res.status,
+                code: "invalid_response",
+                requestId,
+            });
+        }
+        const meta = parseMeta(res.headers);
+        return attachMeta(json, meta);
+    }
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse `Retry-After` as seconds. Supports integer seconds; ignores HTTP-date forms. */
+function parseRetryAfter(header) {
+    if (header == null || header === "")
+        return undefined;
+    const seconds = Number(header);
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return undefined;
+    return seconds;
+}
+/** Minimal AbortSignal.any polyfill-free combinator (works without lib.dom's AbortSignal.any). */
+function anySignal(signals) {
+    if (typeof AbortSignal !== "undefined" && "any" in AbortSignal) {
+        return AbortSignal.any(signals);
+    }
+    const controller = new AbortController();
+    for (const s of signals) {
+        if (s.aborted) {
+            controller.abort(s.reason);
+            break;
+        }
+        s.addEventListener("abort", () => controller.abort(s.reason), { once: true });
+    }
+    return controller.signal;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,91 @@
+/** Shape of the `error` object inside every Lumify error envelope. */
+export interface LumifyErrorPayload {
+    code: string;
+    message: string;
+    status: number;
+    doc_url?: string;
+    /** Present on 429 responses; seconds until the rate-limit window resets. */
+    retry_after?: number;
+    /** Present on some 403 responses (sport-scope denials). */
+    upgrade_url?: string;
+    /** Present on 422 validation errors. */
+    errors?: Array<{
+        field: string;
+        message: string;
+        type: string;
+    }>;
+    [key: string]: unknown;
+}
+export interface LumifyErrorOptions {
+    status: number;
+    code: string;
+    docUrl?: string;
+    requestId?: string | null;
+    payload?: LumifyErrorPayload;
+    cause?: unknown;
+}
+/** Base class for every error the SDK throws for a non-2xx API response. */
+export declare class LumifyError extends Error {
+    /** Stable machine-readable slug, e.g. "not_found" — switch on this. */
+    readonly code: string;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Link to the error-code reference docs. */
+    readonly docUrl?: string;
+    /** Value of the `X-Request-Id` request header, if the caller sent one. */
+    readonly requestId?: string | null;
+    /** The full parsed `error` object from the response envelope. */
+    readonly payload?: LumifyErrorPayload;
+    constructor(message: string, opts: LumifyErrorOptions);
+}
+export declare class AuthenticationError extends LumifyError {
+    constructor(message: string, opts: LumifyErrorOptions);
+}
+export declare class PermissionError extends LumifyError {
+    /** Present on sport-scope denials — where to upgrade the API key's plan/scope. */
+    readonly upgradeUrl?: string;
+    constructor(message: string, opts: LumifyErrorOptions);
+}
+export declare class NotFoundError extends LumifyError {
+    constructor(message: string, opts: LumifyErrorOptions);
+}
+export declare class RateLimitError extends LumifyError {
+    /** Seconds to wait before retrying (mirrors the `Retry-After` header / `error.retry_after`). */
+    readonly retryAfter?: number;
+    constructor(message: string, opts: LumifyErrorOptions & {
+        retryAfter?: number;
+    });
+}
+export interface FieldError {
+    field: string;
+    message: string;
+    type: string;
+}
+export declare class ValidationError extends LumifyError {
+    readonly fieldErrors: FieldError[];
+    constructor(message: string, opts: LumifyErrorOptions);
+}
+/** 402 — credit top-up or payment method required. */
+export declare class PaymentError extends LumifyError {
+    constructor(message: string, opts: LumifyErrorOptions);
+}
+/** 5xx or any status this SDK doesn't have a dedicated class for. */
+export declare class APIError extends LumifyError {
+    constructor(message: string, opts: LumifyErrorOptions);
+}
+/** Network failure, timeout, or abort — the request never got a response. */
+export declare class ConnectionError extends LumifyError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+export interface ErrorFromResponseOptions {
+    /** Seconds parsed from the `Retry-After` response header, when present. */
+    retryAfterHeader?: number;
+}
+/**
+ * Build the right LumifyError subclass from a parsed error envelope.
+ * Falls back to APIError for unrecognized status codes.
+ */
+export declare function errorFromResponse(status: number, payload: LumifyErrorPayload | undefined, requestId: string | null, options?: ErrorFromResponseOptions): LumifyError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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