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

package/dist/product/limits.d.ts

@@ -0,0 +1,110 @@
+import type { BaseClient, Schemas } from "../index.ts";
+/**
+ * Limitry's helpers (docs/product/roadmap.md slice 6): the two shapes a
+ * product's code takes around a costly call, so adding Limitry is one
+ * wrapper — and an agent adding it writes the same thing every time.
+ *
+ *   const limitry = createClient(); // reads LIMITRY_API_KEY
+ *
+ *   // Known cost: check, then do the work only if allowed.
+ *   const response = await limitry.guard(
+ *     { subject: { kind: "apikey", id: key.id }, action: "api-request" },
+ *     () => handle(request),
+ *   );
+ *
+ *   // Cost known afterwards (an AI reply's cents), or "at most N at
+ *   // once": hold an estimate, do the work, commit what it used —
+ *   // released on failure.
+ *   const answer = await limitry.hold(
+ *     { subject: { kind: "user", id: user.id }, action: "ai-call", estimate: 5 },
+ *     async (held) => {
+ *       const res = await callModel(prompt);
+ *       held.cost(priceCents(res.usage));
+ *       return res;
+ *     },
+ *   );
+ *
+ * A refusal throws `LimitExceeded` (with `retryAfterSeconds`). When
+ * Limitry cannot be reached (an error, a 5xx, or no answer within
+ * `timeoutMs`) — or the workspace is past its plan's allowance (402
+ * `plan_limit_reached`) — each limit's fail mode decides: the last decision's
+ * `failMode` for this subject and action is remembered in memory, and
+ * `closed` refuses (`LimitExceeded` with reason `unavailable`) while
+ * `open` — the default, and the answer before any decision was seen —
+ * lets the work run unmetered.
+ *
+ * Retries are safe (docs/product idempotency): each guard or hold sends
+ * one Idempotency-Key, which the client's own retries reuse, so a check
+ * counts once however often it is sent. A hold whose check timed out may
+ * have been granted all the same: once the work is done, `hold` sends the
+ * check again with the same key — a replay, nothing counted twice — and
+ * releases the hold it finds, rather than leave it taken until it expires.
+ * Commits and releases retry too (settling twice answers the same).
+ */
+type Decision = Schemas["CheckDecision"];
+type Subject = {
+    kind: string;
+    id: string;
+};
+export type LimitsOptions = {
+    /** How long to wait for a decision before the fail mode applies. Default 1500 ms. */
+    timeoutMs?: number;
+    /** The fail mode before any decision was seen, or to force one. Default: remembered, else `open`. */
+    failMode?: "open" | "closed";
+};
+export type GuardRequest = {
+    subject: Subject;
+    action: string;
+    /** Units it uses. Default 1. */
+    cost?: number;
+    /** Pools it also draws from (a team's, an org's). */
+    shared?: Subject[];
+};
+export type HoldRequest = {
+    subject: Subject;
+    action: string;
+    /** What it will probably use — held until you commit the actual cost. Default 1. */
+    estimate?: number;
+    shared?: Subject[];
+    /** How long the hold lasts if never settled (default 300, at most 3600). */
+    ttlSeconds?: number;
+};
+export type Held = {
+    /** The cost actually used — committed when the work returns. Default: the estimate. */
+    cost(units: number): void;
+    /** Keep the hold for longer work: it expires `ttlSeconds` from now. */
+    extend(ttlSeconds?: number): Promise<void>;
+};
+/** Not allowed: a limit is used up — or Limitry is unreachable and a limit fails closed. */
+export declare class LimitExceeded extends Error {
+    readonly reason: "limit_exceeded" | "too_many_reservations" | "unavailable";
+    /** The limit that refused; null when unavailable or too many holds. */
+    readonly limit: string | null;
+    readonly retryAfterSeconds: number | null;
+    readonly decision: Decision | null;
+    constructor(decision: Decision | null);
+}
+export declare function createLimits(client: BaseClient, options?: LimitsOptions): {
+    /**
+     * Where a subject stands on every limit on it (and on `shared`
+     * subjects): used, remaining, resetsAt — for showing an end user. Call
+     * it from your server; a key never belongs in a browser. Not a check:
+     * nothing is counted; a subject with no limit gets an empty `limits`.
+     * Throws on an error answer.
+     */
+    standing(request: {
+        subject: Subject;
+        shared?: Subject[];
+    }): Promise<Schemas["UsageStanding"]>;
+    /** Checks `cost`, runs `fn` only if allowed, and returns its result. */
+    guard<T>(request: GuardRequest, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Holds `estimate`, runs `fn`, then commits the cost it reported
+     * (`held.cost(n)`, default the estimate) — or releases the hold if
+     * `fn` throws, and rethrows. A concurrent limit's slot is held for
+     * exactly as long as `fn` runs.
+     */
+    hold<T>(request: HoldRequest, fn: (held: Held) => Promise<T>): Promise<T>;
+};
+export type Limits = ReturnType<typeof createLimits>;
+export {};

package/dist/product/limits.js

@@ -0,0 +1,234 @@
+/** Not allowed: a limit is used up — or Limitry is unreachable and a limit fails closed. */
+export class LimitExceeded extends Error {
+    reason;
+    /** The limit that refused; null when unavailable or too many holds. */
+    limit;
+    retryAfterSeconds;
+    decision;
+    constructor(decision) {
+        const reason = decision?.reason?.code ?? "unavailable";
+        super(reason === "unavailable"
+            ? "Limitry could not be reached and a limit denies when unreachable"
+            : reason === "too_many_reservations"
+                ? "Too many open reservations for this subject"
+                : `Limit ${decision?.reason?.limit ?? ""} exceeded`.trim());
+        this.name = "LimitExceeded";
+        this.reason = reason;
+        this.limit = decision?.reason?.limit ?? null;
+        this.retryAfterSeconds = decision?.retryAfterSeconds ?? null;
+        this.decision = decision;
+    }
+}
+const UNREACHABLE = Symbol("unreachable");
+/** No answer in time: unlike an error, the check may have been decided. */
+const TIMED_OUT = Symbol("timed out");
+/** How long a settle (or a replay to find a hold) may take, retries included. */
+const SETTLE_TIMEOUT_MS = 5000;
+export function createLimits(client, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 1500;
+    /** The last fail mode seen per subject + action (closed if any limit is). */
+    const remembered = new Map();
+    const key = (s, action) => `${s.kind}\u0000${s.id}\u0000${action}`;
+    const failMode = (s, action) => options.failMode ?? remembered.get(key(s, action)) ?? "open";
+    const remember = (s, action, decision) => {
+        if (options.failMode)
+            return;
+        const closed = decision.remaining.some((r) => r.failMode === "closed");
+        remembered.set(key(s, action), closed ? "closed" : "open");
+        if (remembered.size > 10_000) {
+            remembered.delete(remembered.keys().next().value);
+        }
+    };
+    /**
+     * The decision — or UNREACHABLE (network error, 5xx, past the plan),
+     * or TIMED_OUT (no answer within `wait`).
+     */
+    async function check(body, idempotencyKey, wait = timeoutMs) {
+        let timer;
+        // Raced as well as aborted: a custom fetch (a service binding, a
+        // test) may ignore the signal.
+        const late = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(TIMED_OUT), wait);
+        });
+        const asked = (async () => {
+            try {
+                const { data, error, response } = await client.POST("/checks", {
+                    body,
+                    headers: { "idempotency-key": idempotencyKey },
+                    signal: AbortSignal.timeout(wait),
+                });
+                if (data)
+                    return data;
+                // Past the plan's allowance (402 plan_limit_reached): no decision
+                // — each limit's fail mode applies, as if Limitry were unreachable.
+                if (response.status === 402)
+                    return UNREACHABLE;
+                // A 4xx is the caller's mistake (bad request, bad key): say so.
+                if (response.status < 500 && error) {
+                    return new Error(`Limitry refused the check (${response.status}): ${JSON.stringify(error)}`);
+                }
+                return UNREACHABLE;
+            }
+            catch (error) {
+                return error?.name === "TimeoutError"
+                    ? TIMED_OUT
+                    : UNREACHABLE;
+            }
+        })();
+        try {
+            const answer = await Promise.race([asked, late]);
+            if (answer instanceof Error)
+                throw answer;
+            return answer;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Settling never fails the caller's work: the client retries it (the
+     * same settle answers the same), and a settle lost all the same expires
+     * by itself.
+     */
+    async function settle(id, action, cost) {
+        try {
+            if (action === "commit") {
+                await client.POST("/reservations/{reservationId}/commit", {
+                    params: { path: { reservationId: id } },
+                    body: { cost: cost ?? 0 },
+                    signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS),
+                });
+            }
+            else {
+                await client.POST("/reservations/{reservationId}/release", {
+                    params: { path: { reservationId: id } },
+                    signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS),
+                });
+            }
+        }
+        catch {
+            // The hold expires on its own.
+        }
+    }
+    /**
+     * After a hold's check timed out: ask again with the same key (a replay
+     * if Limitry decided it) and release any hold it was granted.
+     */
+    async function releaseUnheard(body, idempotencyKey) {
+        const replay = await check(body, idempotencyKey, SETTLE_TIMEOUT_MS);
+        if (typeof replay === "object" && replay.reservation) {
+            await settle(replay.reservation.id, "release");
+        }
+    }
+    return {
+        /**
+         * Where a subject stands on every limit on it (and on `shared`
+         * subjects): used, remaining, resetsAt — for showing an end user. Call
+         * it from your server; a key never belongs in a browser. Not a check:
+         * nothing is counted; a subject with no limit gets an empty `limits`.
+         * Throws on an error answer.
+         */
+        async standing(request) {
+            const { data, error, response } = await client.GET("/usage/standing", {
+                params: {
+                    query: {
+                        kind: request.subject.kind,
+                        id: request.subject.id,
+                        ...(request.shared?.length
+                            ? {
+                                shared: request.shared
+                                    .map((s) => `${s.kind}:${s.id}`)
+                                    .join(","),
+                            }
+                            : {}),
+                    },
+                },
+            });
+            if (data)
+                return data;
+            throw new Error(`Limitry refused usage.standing (${response.status}): ${JSON.stringify(error)}`);
+        },
+        /** Checks `cost`, runs `fn` only if allowed, and returns its result. */
+        async guard(request, fn) {
+            const decision = await check({
+                subject: request.subject,
+                shared: request.shared,
+                action: request.action,
+                cost: request.cost ?? 1,
+            }, crypto.randomUUID());
+            if (decision === UNREACHABLE || decision === TIMED_OUT) {
+                if (failMode(request.subject, request.action) === "closed") {
+                    throw new LimitExceeded(null);
+                }
+                return fn();
+            }
+            remember(request.subject, request.action, decision);
+            if (!decision.allowed)
+                throw new LimitExceeded(decision);
+            return fn();
+        },
+        /**
+         * Holds `estimate`, runs `fn`, then commits the cost it reported
+         * (`held.cost(n)`, default the estimate) — or releases the hold if
+         * `fn` throws, and rethrows. A concurrent limit's slot is held for
+         * exactly as long as `fn` runs.
+         */
+        async hold(request, fn) {
+            const estimate = request.estimate ?? 1;
+            const body = {
+                subject: request.subject,
+                shared: request.shared,
+                action: request.action,
+                cost: estimate,
+                mode: "reserve",
+                ttlSeconds: request.ttlSeconds,
+            };
+            const idempotencyKey = crypto.randomUUID();
+            const decision = await check(body, idempotencyKey);
+            const unmetered = { cost: () => { }, extend: async () => { } };
+            if (decision === UNREACHABLE || decision === TIMED_OUT) {
+                const unheard = () => decision === TIMED_OUT
+                    ? releaseUnheard(body, idempotencyKey)
+                    : Promise.resolve();
+                if (failMode(request.subject, request.action) === "closed") {
+                    await unheard();
+                    throw new LimitExceeded(null);
+                }
+                try {
+                    return await fn(unmetered);
+                }
+                finally {
+                    await unheard();
+                }
+            }
+            remember(request.subject, request.action, decision);
+            if (!decision.allowed || !decision.reservation) {
+                throw new LimitExceeded(decision);
+            }
+            const id = decision.reservation.id;
+            let used = estimate;
+            const held = {
+                cost(units) {
+                    used = units;
+                },
+                async extend(ttlSeconds) {
+                    await client.POST("/reservations/{reservationId}/extend", {
+                        params: { path: { reservationId: id } },
+                        body: ttlSeconds ? { ttlSeconds } : {},
+                        signal: AbortSignal.timeout(timeoutMs),
+                    });
+                },
+            };
+            let result;
+            try {
+                result = await fn(held);
+            }
+            catch (error) {
+                await settle(id, "release");
+                throw error;
+            }
+            await settle(id, "commit", used);
+            return result;
+        },
+    };
+}

package/dist/resources.d.ts

@@ -0,0 +1,71 @@
+import type { Client as OpenApiClient } from "openapi-fetch";
+import type { paths } from "./v1.gen.ts";
+/**
+ * The SDK's RESOURCE METHODS — `client.limits.list()`,
+ * `client.runs.create(slug, { inputs })` — one per /v1 operation, named
+ * as the CLI names it (`limits list`), generated into ./resources.gen.ts
+ * from the same operation table as the CLI's commands and the MCP
+ * server's tools (scripts/generate.mjs; gitignored, regenerated by every
+ * build). Path parameters are arguments, in path order; query and body
+ * fields are one input object, typed from ./v1.gen.ts; the answer is the
+ * response's data, and a non-2xx throws ApiError. Decided 2026-10-11,
+ * before 1.0: nobody guesses `api.POST("/scripts/{slug}/runs", { params:
+ * { path: { slug } }, body })` wrapped in `unwrap(...)`. The names are
+ * the CLI's, so the surface snapshot (surfaces.test.ts) covers them.
+ */
+export type RawClient = OpenApiClient<paths>;
+type Method = "get" | "post" | "put" | "patch" | "delete";
+type Op<P extends keyof paths, M extends Method> = M extends keyof paths[P] ? paths[P][M] : never;
+type NonEmpty<T, Else> = [NonNullable<T>] extends [never] ? Else : NonNullable<T>;
+type QueryOf<O> = O extends {
+    parameters: {
+        query?: infer Q;
+    };
+} ? NonEmpty<Q, unknown> : unknown;
+type BodyOf<O> = O extends {
+    requestBody?: infer R;
+} ? NonEmpty<R, never> extends {
+    content: {
+        "application/json": infer B;
+    };
+} ? B : unknown : unknown;
+/** An operation's query and body fields, as one object. */
+export type Input<P extends keyof paths, M extends Method> = QueryOf<Op<P, M>> & BodyOf<Op<P, M>>;
+type Json<R> = R extends {
+    content: {
+        "application/json": infer J;
+    };
+} ? J : undefined;
+/** What an operation answers on success (its 2xx JSON). */
+export type Output<P extends keyof paths, M extends Method> = Op<P, M> extends {
+    responses: infer R;
+} ? {
+    [K in keyof R]: K extends 200 | 201 | 202 ? Json<R[K]> : K extends 204 ? undefined : never;
+}[keyof R] : never;
+export type RequestOptions = {
+    /**
+     * Sent as Idempotency-Key. Every write gets one anyway (one per call,
+     * reused on the client's own retries); pass yours to make a retry
+     * YOU make — a rerun job, a redelivered webhook — count once too.
+     */
+    idempotencyKey?: string;
+    /** More request headers. */
+    headers?: Record<string, string>;
+};
+/** One operation's request, as the generated method describes it. */
+export type Call = {
+    method: Method;
+    path: string;
+    /** The input's fields that go in the query string; the rest is the body. */
+    query: readonly string[];
+    hasBody: boolean;
+    /** Takes raw bytes as the body (the route's media type). */
+    rawBody?: string;
+    /** Answers with raw bytes: the method returns a Blob. */
+    rawResponse?: string;
+};
+/** Raw bytes for an operation that takes them, such as a file upload. */
+export type Content = Blob | ArrayBuffer | Uint8Array | string;
+/** Makes the call; the data, or throws ApiError. */
+export declare function call<T>(client: RawClient, op: Call, pathParams: Record<string, string | number>, input: object | undefined, options?: RequestOptions, content?: Content): Promise<T>;
+export {};