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

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 What changed in the Limitry TypeScript SDK (`@limitry/sdk`). Generated from the source on each release; newest first.
 
+## 1.0.0-rc.8 (2026-10-21)
+
+### Added
+
+- Limits have `counting`: `fast` answers the instant it decides, and
+  `guaranteed` stores every count safely before answering, so the limit
+  never goes over, even if a server fails. A `total` balance defaults to
+  `guaranteed`, every other window to `fast`. Set it when creating or
+  updating a limit (`counting`, `--counting`), or in `limitry.json`.
+
+### Changed
+
+- - Creating a limit needs only who it is for, the amount and the window:
+    `limits.create({ subject: { kind: "user" }, amount: 100, window: "month" })`
+    (`limitry limits create --subject '{"kind":"user"}' --amount 100 --window month`).
+    `action` defaults to every action (`*`), `unit` to `units`, and `name`
+    to the sentence the limit reads as, such as "100 units per user per
+    month". If a limit already has that name, the API answers `409`: give
+    this one a `name`. `limitry.json` entries still need a `name`.
+  - A limit's input names who it is for as `subject: { kind, id }` (was
+    `subjectKind` and `subjectId`), the same shape the limit itself has.
+  - What a limit counts is fixed once it is created: its subject, action,
+    unit, window, `every`, `start` and `rolling`. Changing one answers
+    `400 invalid_request`: create a new limit and archive the old one (its
+    history stays). Name, amount, fail mode and enabled still change any
+    time. `limitry sync` refuses such a change until you rename the entry.
+  - A limit says when a check last reached it (`lastCheckedAt`), so you can
+    see a limit no check names.
+- One name for each idea, everywhere: the API, both SDKs, the CLI, the MCP
+  tools, `limitry.json` and webhooks. Update your code when you upgrade:
+
+  - `hold()` is `reserve()`: it takes `cost` (was `estimate`), and the block
+    gets a `Reservation` (was `Held`; Python `Reservation` and
+    `AsyncReservation`), with the same `cost()` and `extend()`.
+  - A refusal throws `LimitReached` (was `LimitExceeded`), with `limitId`
+    (Python `limit_id`) and `reason` `limit_reached` or
+    `too_many_reservations`. When Limitry can't be reached and a limit fails
+    closed, you now get a separate `Unavailable` error. "Can't be reached"
+    also covers a `402 plan_limit_reached` and a `429` from Limitry's flood
+    guard, so each limit's fail mode decides instead of your code getting an
+    error.
+  - A check's answer lists its limits in `limits` (was `remaining`): read
+    `decision.limits[0].remaining`. Every answer that names a limit says
+    `limitId`: `reason.limitId`, `limits[].limitId`, `usage.standing`'s
+    `limits[].limitId`, and webhook payloads.
+  - The refusal code is `limit_reached` (was `limit_exceeded`), and the
+    webhook event is `limit.reached` (was `limit.exceeded`): subscribe your
+    endpoints to the new name.
+  - Usage says `refused` (was `denied`); `usage.subjects` no longer has
+    `over` (it is `refused > 0`).
+  - Credits: `limits.credits.create()` and `limits.credits.list()` at
+    `/v1/limits/{limitId}/credits` (were `limits.grants.*` at `…/grants`),
+    ids start `crd_` (were `grt_`), and the approval an agent asks for is
+    `limit.credit` (was `limit.grant`).
+  - A period that starts on the subject's billing date is
+    `start: "billing_date"` (was `"anchor"`), and `subjects.update()` takes
+    `billingDate` (was `anchor`); the subject says `billingDate` too.
+  - `usage.standing()` and `usage.query()` take one `subject`, written
+    `kind:id` (`user:usr_123`), instead of separate kind and id fields
+    (`limitry usage standing --subject user:usr_123`).
+  - A limit's id starts `lmt_` (was `lim_`); keys still start `lim_test_`
+    and `lim_live_`.
+  - `limitry sync --preview` (was `--dry-run`), and the API's `preview`
+    (was `dryRun`), in what you send and what comes back.
+
+### Removed
+
+- Limits no longer have `counting` (Fast or Guaranteed), and the CLI no
+  longer has `--counting`: every count is now saved before Limitry answers,
+  for every limit. Remove `counting` from your code and from
+  `limitry.json`; Limitry ignores it.
+
+## 1.0.0-rc.7 (2026-10-19)
+
+### Added
+
+- A refused check's `reason` has a `message`: the refusal in one sentence,
+  such as "Refused by AI budget: 3 cents left, resets
+  2026-11-01T00:00:00.000Z. Try again in 3600 s." `LimitExceeded` and
+  `limitry check` show it as the API writes it, so every client says the
+  same. Branch on `allowed` and `reason.code`, never on the message.
+
+### Fixed
+
+- - `held.cost()` refuses a cost the API can't commit (not a whole number
+    from 0 to 1,000,000,000): TypeScript throws `RangeError`, Python raises
+    `ValueError`, in your code. Before, the commit failed silently after
+    the work and its usage was never counted.
+  - TypeScript's `held.extend()` throws the API's error, such as for an
+    expired hold, as Python's already did. Both send the `ttlSeconds` you
+    give as it is, so `0` is refused rather than read as the default.
+  - Python checks, commits and releases now retry exactly as TypeScript's
+    do: a network error, `408`, `429` or `5xx`, at most twice, all within
+    the check's `timeout` (1.5 s) or 5 s for a settle. `standing()` retries
+    too, and reports an error answer that isn't JSON.
+  - `limitry check` and `limitry sync` refuse `--workspace` with an API key,
+    as every other command does, instead of ignoring it.
+
 ## 1.0.0-rc.6 (2026-10-19)
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # @limitry/sdk
 
-The Limitry TypeScript SDK puts a limit around costly work in one call: `guard` checks before your code runs, and `hold` reserves an estimate, then charges what the work actually cost. Every API operation is a typed method too.
+The Limitry TypeScript SDK puts a limit around costly work in one call: `guard` checks before your code runs, and `reserve` reserves what the work will probably cost, then charges what it actually cost. Every API operation is a typed method too.
 
 Limitry is the limits, credits and budgets layer for your software: give each of your users, teams, tenants, API keys or agents an allowance, and before any costly action one call tells your code whether it may happen.
 
@@ -19,7 +19,7 @@ key (`lim_test_…`) while you build.
 it counts one AI call against a limit such as 100 a day:
 
 ```ts
-import { createClient, LimitExceeded } from "@limitry/sdk";
+import { createClient, LimitReached } from "@limitry/sdk";
 
 const limitry = createClient(); // reads LIMITRY_API_KEY
 
@@ -29,7 +29,7 @@ try {
     () => callModel(prompt),
   );
 } catch (error) {
-  if (error instanceof LimitExceeded) {
+  if (error instanceof LimitReached) {
     console.log(`Try again in ${error.retryAfterSeconds} seconds`);
   }
 }
@@ -38,26 +38,28 @@ try {
 ## Charge what it actually cost
 
 When you only know the cost afterwards, such as an AI reply priced by
-the token, `hold` reserves an estimate (5 cents here), runs your code
-and charges what it used. If your code throws, the hold is released:
+the token, `reserve` reserves what it will probably cost (5 cents here),
+runs your code and charges what it used. If your code throws, the
+reservation is released:
 
 ```ts
 import { createClient } from "@limitry/sdk";
 
 const limitry = createClient();
 
-const answer = await limitry.hold(
-  { subject: { kind: "user", id: "usr_123" }, action: "ai-call", estimate: 5 },
-  async (held) => {
+const answer = await limitry.reserve(
+  { subject: { kind: "user", id: "usr_123" }, action: "ai-call", cost: 5 },
+  async (reservation) => {
     const response = await callModel(prompt);
-    held.cost(priceCents(response.usage)); // your prices, in cents
+    reservation.cost(priceCents(response.usage)); // your prices, in cents
     return response;
   },
 );
 ```
 
-If Limitry can't be reached, each limit's fail mode decides: `open` lets
-the work run, `closed` refuses it.
+A refusal throws `LimitReached`. If Limitry can't be reached, each
+limit's fail mode decides: `open` lets the work run, `closed` throws
+`Unavailable`.
 
 ## Everything else
 
@@ -69,9 +71,9 @@ import { createClient } from "@limitry/sdk";
 
 const limitry = createClient();
 
+// "100 units per user per day for ai-call"
 await limitry.limits.create({
-  name: "AI replies per day",
-  subjectKind: "user",
+  subject: { kind: "user" },
   action: "ai-call",
   amount: 100,
   window: "day",

package/dist/index.d.ts

@@ -76,11 +76,12 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
         create: (input: import("./resources.ts").Input<"/checks", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
             allowed: boolean;
             id: string;
+            limits: 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: components["schemas"]["CheckRemaining"][];
             reservation?: {
                 expiresAt: string;
                 id: string;
@@ -99,15 +100,33 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             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: components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
             version: number;
             window: "minute" | "hour" | "day" | "week" | "month" | "year" | "total" | "concurrent";
         }>;
+        credits: {
+            create: (limitId: string | number, input: import("./resources.ts").Input<"/limits/{limitId}/credits", "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"]["Credit"][];
+            }>;
+        };
         get: (limitId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
             action: string;
             amount: number;
@@ -117,32 +136,16 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             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: 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;
@@ -156,9 +159,10 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             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: components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
@@ -168,7 +172,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
         sync: (input: import("./resources.ts").Input<"/limits/sync", "post">, options?: import("./resources.ts").RequestOptions) => Promise<{
             archived: string[];
             created: string[];
-            dryRun: boolean;
+            preview: boolean;
             unchanged: string[];
             updated: {
                 changes: {
@@ -189,9 +193,10 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             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: components["schemas"]["LimitSubject"];
             unit: string;
             updatedAt: string;
@@ -224,7 +229,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
     };
     subjects: {
         get: (subjectKind: string | number, subjectId: string | number, options?: import("./resources.ts").RequestOptions) => Promise<{
-            anchor: string | null;
+            billingDate: 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<{
@@ -232,7 +237,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             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;
+            billingDate: string | null;
             subject: components["schemas"]["SubjectRef"];
         }>;
     };
@@ -242,7 +247,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             limitId: string;
             points: {
                 allowed: number;
-                denied: number;
+                refused: number;
                 start: string;
                 used: number;
             }[];
@@ -252,7 +257,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
             limits: {
                 action: string;
                 amount: number;
-                limit: string;
+                limitId: string;
                 name: string;
                 remaining: number;
                 resetsAt: string | null;
@@ -273,8 +278,7 @@ declare function createBaseClient(options: ClientOptions): import("openapi-fetch
         }>;
         subjects: (input: import("./resources.ts").Input<"/usage/subjects", "get">, options?: import("./resources.ts").RequestOptions) => Promise<{
             items: {
-                denied: number;
-                over: boolean;
+                refused: number;
                 remaining: number;
                 subject: {
                     id: string;

package/dist/product/index.d.ts

@@ -1,16 +1,16 @@
 /**
  * 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
+ * it. `guard` / `reserve` (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 { createLimits, LimitReached, Unavailable, type GuardRequest, type Limits, type LimitsOptions, type Reservation, type ReserveRequest, } from "./limits.ts";
+/** Limitry's methods on the client: `limitry.guard(…)`, `limitry.reserve(…)`, `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>;
+    reserve: <T>(request: import("./limits.ts").ReserveRequest, fn: (reservation: import("./limits.ts").Reservation) => Promise<T>) => Promise<T>;
     standing: (request: {
         subject: {
             kind: string;

package/dist/product/index.js

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

package/dist/product/limits.d.ts

@@ -13,33 +13,34 @@ import type { BaseClient, Schemas } from "../index.ts";
  *   );
  *
  *   // 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) => {
+ *   // once": reserve what it will probably cost, do the work, commit
+ *   // what it used — released on failure.
+ *   const answer = await limitry.reserve(
+ *     { subject: { kind: "user", id: user.id }, action: "ai-call", cost: 5 },
+ *     async (reservation) => {
  *       const res = await callModel(prompt);
- *       held.cost(priceCents(res.usage));
+ *       reservation.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.
+ * A refusal throws `LimitReached` (with `limitId` and
+ * `retryAfterSeconds`). When Limitry cannot be reached — an error, a 5xx,
+ * no answer within `timeoutMs`, the workspace past its plan's allowance
+ * (402 `plan_limit_reached`) or the edge's flood guard (429) — each
+ * limit's fail mode decides: the last decision's `failMode` for this
+ * subject and action is remembered in memory, and `closed` throws
+ * `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).
+ * Retries are safe (docs/product idempotency): each guard or reserve
+ * sends one Idempotency-Key, which the client's own retries reuse, so a
+ * check counts once however often it is sent. A reservation whose check
+ * timed out may have been made all the same: once the work is done,
+ * `reserve` sends the check again with the same key — a replay, nothing
+ * counted twice — and releases the reservation it finds, rather than
+ * leave it taken until it expires. Commits and releases retry too
+ * (committing or releasing twice answers the same).
  */
 type Decision = Schemas["CheckDecision"];
 type Subject = {
@@ -60,29 +61,47 @@ export type GuardRequest = {
     /** Pools it also draws from (a team's, an org's). */
     shared?: Subject[];
 };
-export type HoldRequest = {
+export type ReserveRequest = {
     subject: Subject;
     action: string;
-    /** What it will probably use — held until you commit the actual cost. Default 1. */
-    estimate?: number;
+    /** What it will probably use — reserved until you commit the actual cost. Default 1. */
+    cost?: number;
     shared?: Subject[];
-    /** How long the hold lasts if never settled (default 300, at most 3600). */
+    /** How long the reservation lasts if never committed or released (default 300, at most 3600). */
     ttlSeconds?: number;
 };
-export type Held = {
-    /** The cost actually used — committed when the work returns. Default: the estimate. */
+export type Reservation = {
+    /**
+     * The cost actually used — committed when the work returns. Default: the
+     * reserved cost. A whole number from 0 to 1,000,000,000, as the API
+     * commits: anything else throws a RangeError here, in your code, rather
+     * than a commit the API refuses after the work (whose usage would go
+     * uncounted).
+     */
     cost(units: number): void;
-    /** Keep the hold for longer work: it expires `ttlSeconds` from now. */
+    /**
+     * Keep the reservation for longer work: it expires `ttlSeconds` from now
+     * (default 300, 1 to 3600). Throws the API's error, such as for a
+     * reservation that already expired.
+     */
     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;
+/** Refused: a limit is reached, or the subject holds too many open reservations. */
+export declare class LimitReached extends Error {
+    readonly reason: "limit_reached" | "too_many_reservations";
+    /** The limit that refused; null for too many open reservations. */
+    readonly limitId: string | null;
     readonly retryAfterSeconds: number | null;
-    readonly decision: Decision | null;
-    constructor(decision: Decision | null);
+    readonly decision: Decision;
+    constructor(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 declare class Unavailable extends Error {
+    constructor();
 }
 export declare function createLimits(client: BaseClient, options?: LimitsOptions): {
     /**
@@ -99,12 +118,12 @@ export declare function createLimits(client: BaseClient, options?: LimitsOptions
     /** 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.
+     * 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.
      */
-    hold<T>(request: HoldRequest, fn: (held: Held) => Promise<T>): Promise<T>;
+    reserve<T>(request: ReserveRequest, fn: (reservation: Reservation) => Promise<T>): Promise<T>;
 };
 export type Limits = ReturnType<typeof createLimits>;
 export {};