@limitry/sdk 0.0.0-stage → 1.0.0-rc.3

package/dist/index.d.ts

@@ -0,0 +1,483 @@
+import * as product from "./product/index.ts";
+import { verifyWebhook } from "./webhooks.ts";
+import type { components, paths } from "./v1.gen.ts";
+/**
+ * The product's API client: openapi-fetch over the types GENERATED from
+ * the /v1 routes (./v1.gen.ts — generated, gitignored). Every call is
+ * typed by path and method; responses come back as `{ data, error,
+ * response }`, or use `unwrap()` to throw an ApiError instead.
+ *
+ *   const api = createClient({ token: process.env.TOKEN!, workspace: "acme" });
+ *   const { data } = await api.GET("/workspace");
+ *
+ * Without `token`, the key is read from `<NAME>_API_KEY` (API_KEY_ENV)
+ * where `process.env` exists (Node, Bun, Deno); elsewhere — a browser, a
+ * Worker, whose secrets arrive on `env` — pass it. Decided 2026-10-11:
+ * one line fewer for most customers, as OpenAI's SDK does.
+ *
+ * Authentication is `Authorization: Bearer <token>` — a Workspace API
+ * key, or a personal access token plus `X-Workspace: <slug>` on workspace
+ * routes (docs/architecture.md "Public API"). Where the product has
+ * environments, `environment` names the one to act in (`X-Environment`;
+ * a key bound to one always acts in its own) — without it, the product's
+ * default. The default origin is the product's API host per brand.json;
+ * pass `api` to point elsewhere.
+ *
+ * Every write sends an Idempotency-Key (yours, from `{ idempotencyKey }`,
+ * else one per call) and a failed attempt — network error, 5xx, 429 —
+ * is retried with the same key, twice by default (./retry.ts), so a
+ * retried write runs once.
+ */
+export type { components, paths };
+export type Schemas = components["schemas"];
+export { ApiError, apiErrorFrom } from "./errors.ts";
+export { verifyWebhook, WebhookVerificationError, type VerifyOptions, type WebhookEvent, } from "./webhooks.ts";
+export type { Content, RequestOptions } from "./resources.ts";
+export { DEFAULT_MAX_RETRIES, keysFrom, withRetries } from "./retry.ts";
+/** The variable a missing `token` is read from: <NAME>_API_KEY. */
+export declare const API_KEY_ENV: string;
+/** The product's API origin (no path): https://api.<domain>. */
+export declare const DEFAULT_API: string;
+export type ClientOptions = {
+    /**
+     * Bearer credential: a Workspace API key or a personal access token.
+     * Default: the API_KEY_ENV environment variable, where there is one.
+     */
+    token?: string;
+    /** Workspace slug sent as X-Workspace (personal access tokens only). */
+    workspace?: string;
+    /** Environment sent as X-Environment (where the product has them; else ignored). */
+    environment?: string;
+    /** API origin, without /v1 (default: DEFAULT_API). */
+    api?: string;
+    /** Custom fetch (tests, Workers service bindings). */
+    fetch?: (input: Request) => Promise<Response>;
+    /**
+     * Automatic retries of a failed attempt (network error, 5xx, 429, a
+     * write still in progress), each with the call's same Idempotency-Key.
+     * Default 2; 0 turns them off.
+     */
+    maxRetries?: number;
+};
+/** The client before a product's own methods: raw calls plus the generated ones. */
+export type BaseClient = ReturnType<typeof createBaseClient>;
+/**
+ * A product's own methods on the client (./product/index.ts may export
+ * `productMethods(client: BaseClient)`; decided 2026-10-11): its hero
+ * helpers sit beside the generated ones — `limitry.guard(…)`,
+ * `reminix.run(…)` — instead of a second object to create.
+ */
+type ProductMethods = typeof product extends {
+    productMethods: (client: never) => infer M;
+} ? M : unknown;
+export declare function createClient(options?: ClientOptions): BaseClient & ProductMethods;
+declare function createBaseClient(options: ClientOptions): import("openapi-fetch").Client<paths, `${string}/${string}`> & {
+    checks: {
+        create: (input: import("./resources.ts").Input<"/checks", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            allowed: boolean;
+            id: string;
+            reason: {
+                code: "limit_exceeded" | "too_many_reservations";
+                limit: string | null;
+            } | null;
+            remaining: components["schemas"]["CheckRemaining"][];
+            reservation?: {
+                expiresAt: string;
+                id: string;
+            };
+            retryAfterSeconds: number | null;
+        }>;
+    };
+    limits: {
+        archive: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<undefined>;
+        create: (input: import("./resources.ts").Input<"/limits", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            action: string;
+            amount: number;
+            archivedAt: string | null;
+            createdAt: string;
+            enabled: boolean;
+            every: number;
+            failMode: "open" | "closed";
+            id: string;
+            name: string;
+            rolling: boolean;
+            start: "calendar" | "anchor" | "first_use";
+            subject: components["schemas"]["LimitSubject"];
+            unit: string;
+            updatedAt: string;
+            version: number;
+            window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
+        }>;
+        get: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+            action: string;
+            amount: number;
+            archivedAt: string | null;
+            createdAt: string;
+            enabled: boolean;
+            every: number;
+            failMode: "open" | "closed";
+            id: string;
+            name: string;
+            rolling: boolean;
+            start: "calendar" | "anchor" | "first_use";
+            subject: components["schemas"]["LimitSubject"];
+            unit: string;
+            updatedAt: string;
+            version: number;
+            window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
+        }>;
+        grants: {
+            create: (limitId: string | number, input: import("./resources.ts").Input<"/limits/{limitId}/grants", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                amount: number;
+                createdAt: string;
+                createdByUserId: string | null;
+                id: string;
+                limitId: string;
+                note: string;
+                subject: {
+                    id: string;
+                    kind: string;
+                };
+            }>;
+            list: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["LimitGrant"][];
+            }>;
+        };
+        list: (input?: import("./resources.ts").Input<"/limits", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            items: components["schemas"]["Limit"][];
+            nextCursor: string | null;
+        }>;
+        restore: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+            action: string;
+            amount: number;
+            archivedAt: string | null;
+            createdAt: string;
+            enabled: boolean;
+            every: number;
+            failMode: "open" | "closed";
+            id: string;
+            name: string;
+            rolling: boolean;
+            start: "calendar" | "anchor" | "first_use";
+            subject: components["schemas"]["LimitSubject"];
+            unit: string;
+            updatedAt: string;
+            version: number;
+            window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
+        }>;
+        sync: (input: import("./resources.ts").Input<"/limits/sync", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            archived: string[];
+            created: string[];
+            dryRun: boolean;
+            unchanged: string[];
+            updated: {
+                changes: {
+                    [key: string]: {
+                        from: string | number | boolean | null;
+                        to: string | number | boolean | null;
+                    };
+                };
+                name: string;
+            }[];
+        }>;
+        update: (limitId: string | number, input?: import("./resources.ts").Input<"/limits/{limitId}", "patch">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            action: string;
+            amount: number;
+            archivedAt: string | null;
+            createdAt: string;
+            enabled: boolean;
+            every: number;
+            failMode: "open" | "closed";
+            id: string;
+            name: string;
+            rolling: boolean;
+            start: "calendar" | "anchor" | "first_use";
+            subject: components["schemas"]["LimitSubject"];
+            unit: string;
+            updatedAt: string;
+            version: number;
+            window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
+        }>;
+    };
+    reservations: {
+        commit: (reservationId: string | number, input: import("./resources.ts").Input<"/reservations/{reservationId}/commit", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            cost: number;
+            expiresAt: string;
+            id: string;
+            reserved: number;
+            status: "held" | "committed" | "released" | "expired";
+        }>;
+        extend: (reservationId: string | number, input?: import("./resources.ts").Input<"/reservations/{reservationId}/extend", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            cost: number;
+            expiresAt: string;
+            id: string;
+            reserved: number;
+            status: "held" | "committed" | "released" | "expired";
+        }>;
+        release: (reservationId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+            cost: number;
+            expiresAt: string;
+            id: string;
+            reserved: number;
+            status: "held" | "committed" | "released" | "expired";
+        }>;
+    };
+    subjects: {
+        get: (subjectKind: string | number, subjectId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+            anchor: string | null;
+            subject: components["schemas"]["SubjectRef"];
+        }>;
+        reset: (subjectKind: string | number, subjectId: string | number, input?: import("./resources.ts").Input<"/subjects/{subjectKind}/{subjectId}/reset", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            reset: string[];
+            subject: components["schemas"]["SubjectRef"];
+        }>;
+        update: (subjectKind: string | number, subjectId: string | number, input: import("./resources.ts").Input<"/subjects/{subjectKind}/{subjectId}", "patch">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            anchor: string | null;
+            subject: components["schemas"]["SubjectRef"];
+        }>;
+    };
+    usage: {
+        query: (input: import("./resources.ts").Input<"/usage", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            granularity: "hour" | "day";
+            limitId: string;
+            points: {
+                allowed: number;
+                denied: number;
+                start: string;
+                used: number;
+            }[];
+        }>;
+        standing: (input: import("./resources.ts").Input<"/usage/standing", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            environment: string;
+            limits: {
+                action: string;
+                amount: number;
+                limit: string;
+                name: string;
+                remaining: number;
+                resetsAt: string | null;
+                rolling: boolean;
+                shared: boolean;
+                subject: {
+                    id: string;
+                    kind: string;
+                };
+                unit: string;
+                used: number;
+                window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
+            }[];
+            subject: {
+                id: string;
+                kind: string;
+            };
+        }>;
+        subjects: (input: import("./resources.ts").Input<"/usage/subjects", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+            items: {
+                denied: number;
+                over: boolean;
+                remaining: number;
+                subject: {
+                    id: string;
+                    kind: string;
+                };
+                used: number;
+            }[];
+            limitId: string;
+            windowStart: string;
+        }>;
+    };
+    user: {
+        me: (options?: import("./resources.ts").RequestOptions) => Promise<{
+            email: string;
+            id: string;
+            name: string;
+            workspaces: {
+                id: string;
+                name: string;
+                role: string;
+                slug: string;
+            }[];
+        }>;
+        revokeToken: (options?: import("./resources.ts").RequestOptions) => Promise<undefined>;
+    };
+    workspace: {
+        approvalActions: {
+            list: (options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: {
+                    approverRoles: string[];
+                    createsSecret: boolean;
+                    id: string;
+                    input: {
+                        [key: string]: unknown;
+                    };
+                    title: string;
+                }[];
+            }>;
+        };
+        approvalRequests: {
+            create: (input: import("./resources.ts").Input<"/workspace/approval-requests", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                action: string;
+                approveUrl: string;
+                createdAt: string;
+                decidedAt: string | null;
+                expiresAt: string;
+                id: string;
+                input: {
+                    [key: string]: unknown;
+                };
+                reason: string;
+                requestedBy: string | null;
+                result: {
+                    [key: string]: unknown;
+                } | null;
+                secret: {
+                    envVar: string;
+                    name: string;
+                } | null;
+                status: "pending" | "approved" | "completed" | "denied" | "failed" | "expired";
+                summary: string;
+                title: string;
+            }>;
+            get: (requestId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                action: string;
+                approveUrl: string;
+                createdAt: string;
+                decidedAt: string | null;
+                expiresAt: string;
+                id: string;
+                input: {
+                    [key: string]: unknown;
+                };
+                reason: string;
+                requestedBy: string | null;
+                result: {
+                    [key: string]: unknown;
+                } | null;
+                secret: {
+                    envVar: string;
+                    name: string;
+                } | null;
+                status: "pending" | "approved" | "completed" | "denied" | "failed" | "expired";
+                summary: string;
+                title: string;
+            }>;
+            redeem: (requestId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                envVar: string | null;
+                request: components["schemas"]["ApprovalRequest"];
+                secret: string | null;
+            }>;
+        };
+        auditEvents: {
+            list: (input?: import("./resources.ts").Input<"/workspace/audit-events", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["AuditEvent"][];
+                nextCursor: string | null;
+            }>;
+        };
+        eventTypes: {
+            list: (options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: {
+                    description: string;
+                    type: string;
+                }[];
+            }>;
+        };
+        get: (options?: import("./resources.ts").RequestOptions) => Promise<{
+            id: string;
+            name: string;
+        }>;
+        invitations: {
+            list: (input?: import("./resources.ts").Input<"/workspace/invitations", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["Invitation"][];
+                nextCursor: string | null;
+            }>;
+        };
+        members: {
+            list: (input?: import("./resources.ts").Input<"/workspace/members", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["Member"][];
+                nextCursor: string | null;
+            }>;
+        };
+        teams: {
+            list: (input?: import("./resources.ts").Input<"/workspace/teams", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["Team"][];
+                nextCursor: string | null;
+            }>;
+        };
+        usage: (options?: import("./resources.ts").RequestOptions) => Promise<{
+            meters: {
+                description: string;
+                id: string;
+                limit: number | null;
+                used: number;
+            }[];
+            notices?: string[];
+            periodEnd: string;
+            periodStart: string;
+        }>;
+        webhookDeliveries: {
+            list: (endpointId: string | number, input?: import("./resources.ts").Input<"/workspace/webhook-endpoints/{endpointId}/deliveries", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["WebhookDelivery"][];
+                nextCursor: string | null;
+            }>;
+            redeliver: (endpointId: string | number, deliveryId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                deliveryId: string;
+                ok?: boolean;
+                queued: boolean;
+                status?: number | null;
+            }>;
+        };
+        webhookEndpoints: {
+            create: (input: import("./resources.ts").Input<"/workspace/webhook-endpoints", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
+                endpoint: components["schemas"]["WebhookEndpoint"];
+                secret: string;
+            }>;
+            delete: (endpointId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<undefined>;
+            enable: (endpointId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                consecutiveFailures: number;
+                createdAt: string;
+                description: string | null;
+                enabled: boolean;
+                environment: string | null;
+                eventTypes: string[] | null;
+                id: string;
+                lastAttemptAt: string | null;
+                lastStatus: number | null;
+                url: string;
+            }>;
+            get: (endpointId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                consecutiveFailures: number;
+                createdAt: string;
+                description: string | null;
+                enabled: boolean;
+                environment: string | null;
+                eventTypes: string[] | null;
+                id: string;
+                lastAttemptAt: string | null;
+                lastStatus: number | null;
+                url: string;
+            }>;
+            list: (options?: import("./resources.ts").RequestOptions) => Promise<{
+                items: components["schemas"]["WebhookEndpoint"][];
+                nextCursor: string | null;
+            }>;
+            test: (endpointId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
+                deliveryId: string;
+                ok?: boolean;
+                queued: boolean;
+                status?: number | null;
+            }>;
+        };
+    };
+} & {
+    webhooks: {
+        verify: typeof verifyWebhook;
+    };
+};
+export type Client = ReturnType<typeof createClient>;
+/** `data` of a successful result; throws ApiError for an error result. */
+export declare function unwrap<T extends {
+    data?: unknown;
+    error?: unknown;
+    response: Response;
+}>(result: T): NonNullable<T["data"]>;
+export * from "./product/index.ts";

package/dist/index.js

@@ -0,0 +1,73 @@
+import { brand } from "./brand.js";
+import createOpenApiClient from "openapi-fetch";
+import { apiErrorFrom } from "./errors.js";
+import * as product from "./product/index.js";
+import { resources } from "./resources.gen.js";
+import { withRetries } from "./retry.js";
+import { verifyWebhook } from "./webhooks.js";
+export { ApiError, apiErrorFrom } from "./errors.js";
+export { verifyWebhook, WebhookVerificationError, } from "./webhooks.js";
+export { DEFAULT_MAX_RETRIES, keysFrom, withRetries } from "./retry.js";
+/** The variable a missing `token` is read from: <NAME>_API_KEY. */
+export const API_KEY_ENV = `${brand.identifier.toUpperCase()}_API_KEY`;
+/** The product's API origin (no path): https://api.<domain>. */
+export const DEFAULT_API = `https://api.${brand.domain}`;
+export function createClient(options = {}) {
+    const client = createBaseClient(options);
+    const extend = product.productMethods;
+    if (!extend)
+        return client;
+    const methods = extend(client);
+    for (const name of Object.keys(methods)) {
+        if (name in client) {
+            throw new Error(`productMethods: "${name}" is already a client method`);
+        }
+    }
+    return Object.assign(client, methods);
+}
+function createBaseClient(options) {
+    const token = options.token ?? keyFromEnvironment();
+    if (!token) {
+        throw new Error(`${brand.productName}: no API key. Pass { token } or set ${API_KEY_ENV}.`);
+    }
+    const origin = (options.api ?? DEFAULT_API).replace(/\/+$/, "");
+    const send = options.fetch ?? ((request) => fetch(request));
+    const client = createOpenApiClient({
+        baseUrl: `${origin}/v1`,
+        fetch: options.maxRetries === 0
+            ? send
+            : withRetries(send, { maxRetries: options.maxRetries }),
+    });
+    client.use({
+        onRequest({ request }) {
+            request.headers.set("authorization", `Bearer ${token}`);
+            if (options.workspace && !request.headers.has("x-workspace")) {
+                request.headers.set("x-workspace", options.workspace);
+            }
+            if (options.environment && !request.headers.has("x-environment")) {
+                request.headers.set("x-environment", options.environment);
+            }
+            return request;
+        },
+    });
+    // A method per operation, named as the CLI names it (./resources.gen.ts):
+    // `limits list` → client.limits.list(). The raw GET/POST/… stay.
+    // `webhooks.verify` checks a delivery you received (./webhooks.ts); it
+    // calls nothing, so it's also exported on its own as verifyWebhook.
+    return Object.assign(client, resources(client), {
+        webhooks: { verify: verifyWebhook },
+    });
+}
+function keyFromEnvironment() {
+    const runtime = globalThis;
+    return runtime.process?.env?.[API_KEY_ENV] || undefined;
+}
+/** `data` of a successful result; throws ApiError for an error result. */
+export function unwrap(result) {
+    if (result.error !== undefined || !result.response.ok) {
+        throw apiErrorFrom(result.error, result.response);
+    }
+    return result.data;
+}
+// The product's own helpers (fork-owned seam: ./product/).
+export * from "./product/index.js";

package/dist/product/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PRODUCT-OWNED: Limitry's SDK helpers (fork-owned seam — docs/conventions.md
+ * "Fork-owned seams"): re-exported by the SDK entry and published with
+ * it. `guard` / `hold` (docs/product/roadmap.md slice 6) sit on the client
+ * (`limitry.guard(…)`, the SDK's `productMethods` seam); `createLimits(client,
+ * options)` gives them with your own timeout or fail mode.
+ */
+import type { BaseClient } from "../index.ts";
+export { createLimits, LimitExceeded, type GuardRequest, type Held, type HoldRequest, type Limits, type LimitsOptions, } from "./limits.ts";
+/** Limitry's methods on the client: `limitry.guard(…)`, `limitry.hold(…)`, `limitry.standing(…)`. */
+export declare const productMethods: (client: BaseClient) => {
+    guard: <T>(request: import("./limits.ts").GuardRequest, fn: () => Promise<T>) => Promise<T>;
+    hold: <T>(request: import("./limits.ts").HoldRequest, fn: (held: import("./limits.ts").Held) => Promise<T>) => Promise<T>;
+    standing: (request: {
+        subject: {
+            kind: string;
+            id: string;
+        };
+        shared?: {
+            kind: string;
+            id: string;
+        }[];
+    }) => Promise<import("../index.ts").Schemas["UsageStanding"]>;
+};

package/dist/product/index.js

@@ -0,0 +1,7 @@
+import { createLimits } from "./limits.js";
+export { createLimits, LimitExceeded, } from "./limits.js";
+/** Limitry's methods on the client: `limitry.guard(…)`, `limitry.hold(…)`, `limitry.standing(…)`. */
+export const productMethods = (client) => {
+    const limits = createLimits(client);
+    return { guard: limits.guard, hold: limits.hold, standing: limits.standing };
+};