@limitry/sdk 1.0.0-rc.6 → 1.0.0-rc.8

package/dist/product/limits.js

@@ -1,40 +1,40 @@
-/**
- * A refusal in the CLI's words, naming the limit rather than its id:
- * "Refused by AI replies per day: 0 replies left, resets …. Try again in
- * 42 s."
- */
-function refusal(decision) {
-    const id = decision?.reason?.limit ?? null;
-    const limit = decision?.remaining.find((r) => r.limit === id);
-    const retry = decision?.retryAfterSeconds != null
-        ? ` Try again in ${decision.retryAfterSeconds} s.`
-        : "";
-    if (!limit)
-        return `Refused: limit ${id ?? "(unknown)"} is used up.${retry}`;
-    const resets = limit.resetsAt ? `, resets ${limit.resetsAt}` : "";
-    return `Refused by ${limit.name}: ${limit.remaining} ${limit.unit} left${resets}.${retry}`;
+import { apiErrorFrom } from "../errors.js";
+/** The largest cost a commit takes. */
+const MAX_COST = 1_000_000_000;
+function checkedCost(units) {
+    if (!Number.isInteger(units) || units < 0 || units > MAX_COST) {
+        throw new RangeError(`reservation.cost(${units}): the cost must be a whole number from 0 to ${MAX_COST}`);
+    }
+    return units;
 }
-/** Not allowed: a limit is used up — or Limitry is unreachable and a limit fails closed. */
-export class LimitExceeded extends Error {
+/** Refused: a limit is reached, or the subject holds too many open reservations. */
+export class LimitReached extends Error {
     reason;
-    /** The limit that refused; null when unavailable or too many holds. */
-    limit;
+    /** The limit that refused; null for too many open reservations. */
+    limitId;
     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"
-                : refusal(decision));
-        this.name = "LimitExceeded";
-        this.reason = reason;
-        this.limit = decision?.reason?.limit ?? null;
-        this.retryAfterSeconds = decision?.retryAfterSeconds ?? null;
+        // The API's own sentence (reason.message), one wording everywhere.
+        super(decision.reason?.message ?? "Refused");
+        this.name = "LimitReached";
+        this.reason = decision.reason?.code ?? "limit_reached";
+        this.limitId = decision.reason?.limitId ?? null;
+        this.retryAfterSeconds = decision.retryAfterSeconds ?? null;
         this.decision = decision;
     }
 }
+/**
+ * Limitry could not be reached (an error, a 5xx, a timeout, the plan's
+ * allowance used up, or the flood guard's 429) and a limit on this
+ * subject and action fails closed. With `open`, the work runs instead.
+ */
+export class Unavailable extends Error {
+    constructor() {
+        super("Limitry could not be reached and a limit refuses when unreachable");
+        this.name = "Unavailable";
+    }
+}
 const UNREACHABLE = Symbol("unreachable");
 /** No answer in time: unlike an error, the check may have been decided. */
 const TIMED_OUT = Symbol("timed out");
@@ -49,15 +49,15 @@ export function createLimits(client, options = {}) {
     const remember = (s, action, decision) => {
         if (options.failMode)
             return;
-        const closed = decision.remaining.some((r) => r.failMode === "closed");
+        const closed = decision.limits.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`).
+     * The decision — or UNREACHABLE (network error, 5xx, past the plan, the
+     * flood guard's 429), or TIMED_OUT (no answer within `wait`).
      */
     async function check(body, idempotencyKey, wait = timeoutMs) {
         let timer;
@@ -75,10 +75,12 @@ export function createLimits(client, options = {}) {
                 });
                 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)
+                // Past the plan's allowance (402 plan_limit_reached), or stopped by
+                // the edge's flood guard (429): no decision — each limit's fail
+                // mode applies, as if Limitry were unreachable.
+                if (response.status === 402 || response.status === 429) {
                     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)}`);
@@ -102,9 +104,9 @@ export function createLimits(client, options = {}) {
         }
     }
     /**
-     * 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.
+     * Committing or releasing never fails the caller's work: the client
+     * retries it (the same commit answers the same), and one lost all the
+     * same expires by itself.
      */
     async function settle(id, action, cost) {
         try {
@@ -123,12 +125,12 @@ export function createLimits(client, options = {}) {
             }
         }
         catch {
-            // The hold expires on its own.
+            // The reservation 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.
+     * After a reservation's check timed out: ask again with the same key (a
+     * replay if Limitry decided it) and release any reservation it made.
      */
     async function releaseUnheard(body, idempotencyKey) {
         const replay = await check(body, idempotencyKey, SETTLE_TIMEOUT_MS);
@@ -148,8 +150,7 @@ export function createLimits(client, options = {}) {
             const { data, error, response } = await client.GET("/usage/standing", {
                 params: {
                     query: {
-                        kind: request.subject.kind,
-                        id: request.subject.id,
+                        subject: `${request.subject.kind}:${request.subject.id}`,
                         ...(request.shared?.length
                             ? {
                                 shared: request.shared
@@ -174,41 +175,46 @@ export function createLimits(client, options = {}) {
             }, crypto.randomUUID());
             if (decision === UNREACHABLE || decision === TIMED_OUT) {
                 if (failMode(request.subject, request.action) === "closed") {
-                    throw new LimitExceeded(null);
+                    throw new Unavailable();
                 }
                 return fn();
             }
             remember(request.subject, request.action, decision);
             if (!decision.allowed)
-                throw new LimitExceeded(decision);
+                throw new LimitReached(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.
+         * Reserves `cost`, runs `fn`, then commits the cost it reported
+         * (`reservation.cost(n)`, default the reserved cost) — or releases the
+         * reservation if `fn` throws, and rethrows. A concurrent limit's slot
+         * is taken for exactly as long as `fn` runs.
          */
-        async hold(request, fn) {
-            const estimate = request.estimate ?? 1;
+        async reserve(request, fn) {
+            const reserved = request.cost ?? 1;
             const body = {
                 subject: request.subject,
                 shared: request.shared,
                 action: request.action,
-                cost: estimate,
+                cost: reserved,
                 mode: "reserve",
                 ttlSeconds: request.ttlSeconds,
             };
             const idempotencyKey = crypto.randomUUID();
             const decision = await check(body, idempotencyKey);
-            const unmetered = { cost: () => { }, extend: async () => { } };
+            const unmetered = {
+                // Checked even unmetered: the mistake shows whether or not
+                // Limitry answered.
+                cost: (units) => void checkedCost(units),
+                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);
+                    throw new Unavailable();
                 }
                 try {
                     return await fn(unmetered);
@@ -219,25 +225,28 @@ export function createLimits(client, options = {}) {
             }
             remember(request.subject, request.action, decision);
             if (!decision.allowed || !decision.reservation) {
-                throw new LimitExceeded(decision);
+                throw new LimitReached(decision);
             }
             const id = decision.reservation.id;
-            let used = estimate;
-            const held = {
+            let used = reserved;
+            const reservation = {
                 cost(units) {
-                    used = units;
+                    used = checkedCost(units);
                 },
                 async extend(ttlSeconds) {
-                    await client.POST("/reservations/{reservationId}/extend", {
+                    // Passed as given: the API refuses a bad one (0, past 3600).
+                    const { error, response } = await client.POST("/reservations/{reservationId}/extend", {
                         params: { path: { reservationId: id } },
-                        body: ttlSeconds ? { ttlSeconds } : {},
+                        body: ttlSeconds === undefined ? {} : { ttlSeconds },
                         signal: AbortSignal.timeout(timeoutMs),
                     });
+                    if (error !== undefined)
+                        throw apiErrorFrom(error, response);
                 },
             };
             let result;
             try {
-                result = await fn(held);
+                result = await fn(reservation);
             }
             catch (error) {
                 await settle(id, "release");

package/dist/resources.gen.d.ts

@@ -5,11 +5,12 @@ export declare function resources(client: RawClient): {
         create: (input: Input<"/checks", "post">, options?: RequestOptions) => Promise<{
             allowed: boolean;
             id: string;
+            limits: import("./v1.gen.ts").components["schemas"]["CheckLimit"][];
             reason: {
-                code: "limit_exceeded" | "too_many_reservations";
-                limit: string | null;
+                code: "limit_reached" | "too_many_reservations";
+                limitId: string | null;
+                message: string;
             } | null;
-            remaining: import("./v1.gen.ts").components["schemas"]["CheckRemaining"][];
             reservation?: {
                 expiresAt: string;
                 id: string;
@@ -28,15 +29,33 @@ export declare function resources(client: RawClient): {
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: import("./v1.gen.ts").components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
             version: number;
             window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
         }>;
+        credits: {
+            create: (limitId: string | number, input: Input<"/limits/{limitId}/credits", "post">, options?: 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?: RequestOptions) => Promise<{
+                items: import("./v1.gen.ts").components["schemas"]["Credit"][];
+            }>;
+        };
         get: (limitId: string | number, options?: RequestOptions) => Promise<{
             action: string;
             amount: number;
@@ -46,32 +65,16 @@ export declare function resources(client: RawClient): {
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: import("./v1.gen.ts").components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
             version: number;
             window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
         }>;
-        grants: {
-            create: (limitId: string | number, input: Input<"/limits/{limitId}/grants", "post">, options?: 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?: RequestOptions) => Promise<{
-                items: import("./v1.gen.ts").components["schemas"]["LimitGrant"][];
-            }>;
-        };
         list: (input?: Input<"/limits", "get">, options?: RequestOptions) => Promise<{
             items: import("./v1.gen.ts").components["schemas"]["Limit"][];
             nextCursor: string | null;
@@ -85,9 +88,10 @@ export declare function resources(client: RawClient): {
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: import("./v1.gen.ts").components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
@@ -97,7 +101,7 @@ export declare function resources(client: RawClient): {
         sync: (input: Input<"/limits/sync", "post">, options?: RequestOptions) => Promise<{
             archived: string[];
             created: string[];
-            dryRun: boolean;
+            preview: boolean;
             unchanged: string[];
             updated: {
                 changes: {
@@ -118,9 +122,10 @@ export declare function resources(client: RawClient): {
             every: number;
             failMode: "open" | "closed";
             id: string;
+            lastCheckedAt: string | null;
             name: string;
             rolling: boolean;
-            start: "calendar" | "anchor" | "first_use";
+            start: "calendar" | "billing_date" | "first_use";
             subject: import("./v1.gen.ts").components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
@@ -153,7 +158,7 @@ export declare function resources(client: RawClient): {
     };
     subjects: {
         get: (subjectKind: string | number, subjectId: string | number, options?: RequestOptions) => Promise<{
-            anchor: string | null;
+            billingDate: string | null;
             subject: import("./v1.gen.ts").components["schemas"]["SubjectRef"];
         }>;
         reset: (subjectKind: string | number, subjectId: string | number, input?: Input<"/subjects/{subjectKind}/{subjectId}/reset", "post">, options?: RequestOptions) => Promise<{
@@ -161,7 +166,7 @@ export declare function resources(client: RawClient): {
             subject: import("./v1.gen.ts").components["schemas"]["SubjectRef"];
         }>;
         update: (subjectKind: string | number, subjectId: string | number, input: Input<"/subjects/{subjectKind}/{subjectId}", "patch">, options?: RequestOptions) => Promise<{
-            anchor: string | null;
+            billingDate: string | null;
             subject: import("./v1.gen.ts").components["schemas"]["SubjectRef"];
         }>;
     };
@@ -171,7 +176,7 @@ export declare function resources(client: RawClient): {
             limitId: string;
             points: {
                 allowed: number;
-                denied: number;
+                refused: number;
                 start: string;
                 used: number;
             }[];
@@ -181,7 +186,7 @@ export declare function resources(client: RawClient): {
             limits: {
                 action: string;
                 amount: number;
-                limit: string;
+                limitId: string;
                 name: string;
                 remaining: number;
                 resetsAt: string | null;
@@ -202,8 +207,7 @@ export declare function resources(client: RawClient): {
         }>;
         subjects: (input: Input<"/usage/subjects", "get">, options?: RequestOptions) => Promise<{
             items: {
-                denied: number;
-                over: boolean;
+                refused: number;
                 remaining: number;
                 subject: {
                     id: string;

package/dist/resources.gen.js

@@ -11,11 +11,11 @@ export function resources(client) {
         limits: {
             archive: /** Archive a limit */ (limitId, options) => call(client, { "method": "post", "path": "/limits/{limitId}/archive", "query": [], "hasBody": false }, { "limitId": limitId }, undefined, options),
             create: /** Create a limit */ (input, options) => call(client, { "method": "post", "path": "/limits", "query": [], "hasBody": true }, {}, input, options),
-            get: /** Get a limit */ (limitId, options) => call(client, { "method": "get", "path": "/limits/{limitId}", "query": [], "hasBody": false }, { "limitId": limitId }, undefined, options),
-            grants: {
-                create: /** Add credits to a balance */ (limitId, input, options) => call(client, { "method": "post", "path": "/limits/{limitId}/grants", "query": [], "hasBody": true }, { "limitId": limitId }, input, options),
-                list: /** List a balance's grants */ (limitId, options) => call(client, { "method": "get", "path": "/limits/{limitId}/grants", "query": [], "hasBody": false }, { "limitId": limitId }, undefined, options),
+            credits: {
+                create: /** Add credits to a balance */ (limitId, input, options) => call(client, { "method": "post", "path": "/limits/{limitId}/credits", "query": [], "hasBody": true }, { "limitId": limitId }, input, options),
+                list: /** List a balance's credits */ (limitId, options) => call(client, { "method": "get", "path": "/limits/{limitId}/credits", "query": [], "hasBody": false }, { "limitId": limitId }, undefined, options),
             },
+            get: /** Get a limit */ (limitId, options) => call(client, { "method": "get", "path": "/limits/{limitId}", "query": [], "hasBody": false }, { "limitId": limitId }, undefined, options),
             list: /** List limits */ (input, options) => call(client, { "method": "get", "path": "/limits", "query": ["limit", "cursor", "subjectKind", "action", "archived"], "hasBody": false }, {}, input, options),
             restore: /** Restore an archived limit */ (limitId, options) => call(client, { "method": "post", "path": "/limits/{limitId}/restore", "query": [], "hasBody": false }, { "limitId": limitId }, undefined, options),
             sync: /** Sync limits from a list */ (input, options) => call(client, { "method": "post", "path": "/limits/sync", "query": [], "hasBody": true }, {}, input, options),
@@ -29,11 +29,11 @@ export function resources(client) {
         subjects: {
             get: /** Get a subject */ (subjectKind, subjectId, options) => call(client, { "method": "get", "path": "/subjects/{subjectKind}/{subjectId}", "query": [], "hasBody": false }, { "subjectKind": subjectKind, "subjectId": subjectId }, undefined, options),
             reset: /** Reset a subject's limits */ (subjectKind, subjectId, input, options) => call(client, { "method": "post", "path": "/subjects/{subjectKind}/{subjectId}/reset", "query": [], "hasBody": true }, { "subjectKind": subjectKind, "subjectId": subjectId }, input, options),
-            update: /** Set a subject's anchor */ (subjectKind, subjectId, input, options) => call(client, { "method": "patch", "path": "/subjects/{subjectKind}/{subjectId}", "query": [], "hasBody": true }, { "subjectKind": subjectKind, "subjectId": subjectId }, input, options),
+            update: /** Set a subject's billing date */ (subjectKind, subjectId, input, options) => call(client, { "method": "patch", "path": "/subjects/{subjectKind}/{subjectId}", "query": [], "hasBody": true }, { "subjectKind": subjectKind, "subjectId": subjectId }, input, options),
         },
         usage: {
-            query: /** Get a limit's usage over time */ (input, options) => call(client, { "method": "get", "path": "/usage", "query": ["limitId", "subjectKind", "subjectId", "from", "to", "granularity"], "hasBody": false }, {}, input, options),
-            standing: /** Get where a subject stands */ (input, options) => call(client, { "method": "get", "path": "/usage/standing", "query": ["kind", "id", "shared"], "hasBody": false }, {}, input, options),
+            query: /** Get a limit's usage over time */ (input, options) => call(client, { "method": "get", "path": "/usage", "query": ["limitId", "subject", "from", "to", "granularity"], "hasBody": false }, {}, input, options),
+            standing: /** Get where a subject stands */ (input, options) => call(client, { "method": "get", "path": "/usage/standing", "query": ["subject", "shared"], "hasBody": false }, {}, input, options),
             subjects: /** List who is using a limit now */ (input, options) => call(client, { "method": "get", "path": "/usage/subjects", "query": ["limitId", "limit"], "hasBody": false }, {}, input, options),
         },
         user: {