@limitry/sdk 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/product/limits.js

@@ -1,39 +1,57 @@
 import { apiErrorFrom } from "../errors.js";
+import { MOVING_HEADER, MOVING_MS, retryWaitMs } from "../retry.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(`held.cost(${units}): the cost must be a whole number from 0 to ${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"
-            : // The API's own sentence (reason.message), one wording everywhere.
-                (decision?.reason?.message ?? "Refused"));
-        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");
 /** 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 wait = (ms) => new Promise((done) => setTimeout(done, ms));
+/** Seconds of a `Retry-After`, as ms (none: undefined; `retryWaitMs` floors it at a second). */
+function retryAfterMs(response) {
+    const value = response.headers.get("retry-after");
+    const seconds = value === null ? NaN : Number(value);
+    return Number.isFinite(seconds) ? seconds * 1000 : undefined;
+}
+export function createLimits(client, options = {}, internals = {}) {
     const timeoutMs = options.timeoutMs ?? 1500;
+    const sleep = internals.sleep ?? wait;
+    const random = internals.random ?? Math.random;
     /** 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}`;
@@ -41,17 +59,32 @@ 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`). A
+     * `moving` or `busy` answer is asked again, with the same key, for up
+     * to 30 s in all: each attempt has its own `wait`.
      */
-    async function check(body, idempotencyKey, wait = timeoutMs) {
+    async function check(body, idempotencyKey, wait = timeoutMs, finishOnly = false) {
+        let waited = 0;
+        for (let tries = 0;; tries++) {
+            const answer = await checkOnce(body, idempotencyKey, wait, finishOnly);
+            if (answer.kind !== "later")
+                return answer.value;
+            const pause = retryWaitMs(answer.retryAfterMs, tries, random);
+            if (waited + pause > MOVING_MS)
+                return UNREACHABLE;
+            waited += pause;
+            await sleep(pause);
+        }
+    }
+    async function checkOnce(body, idempotencyKey, wait, finishOnly) {
         let timer;
         // Raced as well as aborted: a custom fetch (a service binding, a
         // test) may ignore the signal.
@@ -62,15 +95,25 @@ export function createLimits(client, options = {}) {
             try {
                 const { data, error, response } = await client.POST("/checks", {
                     body,
-                    headers: { "idempotency-key": idempotencyKey },
+                    headers: {
+                        "idempotency-key": idempotencyKey,
+                        // `moving` and `busy` come back here at once: this loop
+                        // retries them.
+                        [MOVING_HEADER]: "return",
+                        ...(finishOnly ? { "limitry-finish-only": "1" } : {}),
+                    },
                     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)
+                if (isRetryLater(response, error))
+                    return { later: retryAfterMs(response) };
+                // 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)}`);
@@ -87,40 +130,59 @@ export function createLimits(client, options = {}) {
             const answer = await Promise.race([asked, late]);
             if (answer instanceof Error)
                 throw answer;
-            return answer;
+            if (typeof answer === "object" && "later" in answer)
+                return { kind: "later", retryAfterMs: answer.later };
+            return { kind: "answer", value: 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.
+     * 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 {
-            if (action === "commit") {
-                await client.POST("/reservations/{reservationId}/commit", {
-                    params: { path: { reservationId: id } },
-                    body: { cost: cost ?? 0 },
-                    signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS),
-                });
+        // A commit lost would leave work uncounted: `moving` or `busy` is
+        // asked again, with the same key, for up to 30 s, each attempt with
+        // its own budget.
+        const idempotencyKey = crypto.randomUUID();
+        let waited = 0;
+        for (let tries = 0;; tries++) {
+            let retryMs = null;
+            try {
+                const headers = {
+                    "idempotency-key": idempotencyKey,
+                    [MOVING_HEADER]: "return",
+                };
+                const { error, response } = action === "commit"
+                    ? await client.POST("/reservations/{reservationId}/commit", {
+                        params: { path: { reservationId: id } },
+                        body: { cost: cost ?? 0 },
+                        headers,
+                        signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS),
+                    })
+                    : await client.POST("/reservations/{reservationId}/release", {
+                        params: { path: { reservationId: id } },
+                        headers,
+                        signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS),
+                    });
+                if (isRetryLater(response, error))
+                    retryMs = retryWaitMs(retryAfterMs(response), tries, random);
             }
-            else {
-                await client.POST("/reservations/{reservationId}/release", {
-                    params: { path: { reservationId: id } },
-                    signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS),
-                });
+            catch {
+                // The reservation expires on its own.
             }
-        }
-        catch {
-            // The hold expires on its own.
+            if (retryMs === null || waited + retryMs > MOVING_MS)
+                return;
+            waited += retryMs;
+            await sleep(retryMs);
         }
     }
     /**
-     * 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);
@@ -140,8 +202,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
@@ -158,36 +219,46 @@ export function createLimits(client, options = {}) {
         },
         /** Checks `cost`, runs `fn` only if allowed, and returns its result. */
         async guard(request, fn) {
-            const decision = await check({
+            const body = {
                 subject: request.subject,
                 shared: request.shared,
                 action: request.action,
                 cost: request.cost ?? 1,
-            }, crypto.randomUUID());
+            };
+            const idempotencyKey = crypto.randomUUID();
+            const decision = await check(body, idempotencyKey);
             if (decision === UNREACHABLE || decision === TIMED_OUT) {
                 if (failMode(request.subject, request.action) === "closed") {
-                    throw new LimitExceeded(null);
+                    throw new Unavailable();
+                }
+                if (decision === TIMED_OUT) {
+                    // No answer in time, and the work runs (fail open): the check may
+                    // be part way (held on some of Limitry's servers, across
+                    // subjects). Sent once more with the same key, in the background,
+                    // ONLY TO FINISH it — Limitry never decides it afresh then, so a
+                    // check that never arrived charges nothing.
+                    void check(body, idempotencyKey, SETTLE_TIMEOUT_MS, true).catch(() => { });
                 }
                 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,
             };
@@ -205,7 +276,7 @@ export function createLimits(client, options = {}) {
                     : Promise.resolve();
                 if (failMode(request.subject, request.action) === "closed") {
                     await unheard();
-                    throw new LimitExceeded(null);
+                    throw new Unavailable();
                 }
                 try {
                     return await fn(unmetered);
@@ -216,11 +287,11 @@ 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 = checkedCost(units);
                 },
@@ -237,7 +308,7 @@ export function createLimits(client, options = {}) {
             };
             let result;
             try {
-                result = await fn(held);
+                result = await fn(reservation);
             }
             catch (error) {
                 await settle(id, "release");
@@ -248,3 +319,9 @@ export function createLimits(client, options = {}) {
         },
     };
 }
+/** `503 moving` or `503 busy`: nothing was charged — retry with the same key. */
+function isRetryLater(response, error) {
+    const code = error?.error
+        ?.code;
+    return response.status === 503 && (code === "moving" || code === "busy");
+}

package/dist/resources.gen.d.ts

@@ -5,18 +5,18 @@ 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;
             };
             retryAfterSeconds: number | null;
-        }>;
+        } | undefined>;
     };
     limits: {
         archive: (limitId: string | number, options?: RequestOptions) => Promise<undefined>;
@@ -29,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;
@@ -47,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;
@@ -86,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;
@@ -98,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: {
@@ -119,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;
@@ -154,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<{
@@ -162,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"];
         }>;
     };
@@ -172,7 +176,7 @@ export declare function resources(client: RawClient): {
             limitId: string;
             points: {
                 allowed: number;
-                denied: number;
+                refused: number;
                 start: string;
                 used: number;
             }[];
@@ -182,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;
@@ -203,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: {

package/dist/retry.d.ts

@@ -13,9 +13,29 @@
  * handed back to the caller rather than slept through. A request whose
  * own signal aborted (a caller's timeout) is never retried: the caller
  * decided.
+ *
+ * A `503 moving` (a subject handed over between Limitry's servers, a few
+ * seconds) or `503 busy` (too many checks inside one of them at once) is
+ * retried for up to MOVING_MS whatever `maxRetries` says: nothing was
+ * charged, and the same key gets the answer once it lands. Each wait is
+ * the Retry-After (at least a second) plus full jitter on a capped
+ * exponential backoff (`retryWaitMs`), so clients turned away together
+ * don't come back together. A caller that keeps its own time budget (the
+ * guard and reserve helpers) sends `MOVING_HEADER: return` and gets
+ * either answer back at once.
  */
 export declare const DEFAULT_MAX_RETRIES = 2;
 export declare const MAX_WAIT_MS = 20000;
+/**
+ * How long a `moving` or `busy` answer is retried, all told: a handover's
+ * freeze lasts at most 30 s.
+ */
+export declare const MOVING_MS = 30000;
+/** Sent by a caller that retries `moving` and `busy` itself (never reaches the API). */
+export declare const MOVING_HEADER = "x-limitry-moving";
+/** The backoff added to a `moving` or `busy` wait: full jitter under base × 2^n, capped. */
+export declare const JITTER_BASE_MS = 250;
+export declare const JITTER_CAP_MS = 4000;
 /** The longest key a caller may pass where a client derives keys from it. */
 export declare const MAX_BASE_KEY = 200;
 type Fetch = (request: Request) => Promise<Response>;
@@ -26,7 +46,25 @@ export type RetryOptions = {
     key?: (method: string, path: string) => string | Promise<string>;
     /** Waits (tests pass a fake). */
     sleep?: (ms: number) => Promise<void>;
+    /** 0 ≤ x < 1 for the jitter (tests pass a fixed one). */
+    random?: () => number;
 };
+/**
+ * The wait before retrying a `moving` or `busy` answer, the `attempt`th
+ * in a row (0 first): the server's Retry-After, at least a second (a 0,
+ * or a date past, must not spin), plus full jitter — anywhere from 0 to
+ * min(JITTER_CAP_MS, JITTER_BASE_MS × 2^attempt).
+ */
+export declare function retryWaitMs(retryAfterMs: number | undefined, attempt: number, random?: () => number): number;
+/** A `503` that says retry later with the same key: `moving` or `busy` (else null). */
+export declare function retryLater(response: Response): Promise<"moving" | "busy" | null>;
+/** A `503` whose error code is `moving`. */
+export declare function isMoving(response: Response): Promise<boolean>;
+/**
+ * `fetch` that only drops MOVING_HEADER (a client with retries off): the
+ * header is between the SDK's own parts, never sent to the API.
+ */
+export declare function withoutMovingHeader(fetch: Fetch): Fetch;
 /** `fetch` with the rule above. Each request is one logical call. */
 export declare function withRetries(fetch: Fetch, options?: RetryOptions): Fetch;
 /**