@didis/client 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@didis/client` are listed here. The format follows [Keep
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-10-19
+
+### Added
+
+- Automatic wait-and-retry for `429` (request budget used up) and `503` (temporarily overloaded) responses that carry `Retry-After`. By default the client retries up to 2 times and never waits longer than 10 seconds per attempt; a short random delay is added so clients refused together do not return together. Both statuses are refused before the request is processed, so retrying is safe for every call. Tune with `new DidisClient({ retry: { maxRetries, maxWaitMs } })` or turn off with `retry: false`. When retries run out, the last `DidisError` is thrown as before, with `problem.retryAfter`.
+
 ## [0.2.3] - 2026-10-18
 
 ### Added
@@ -56,7 +62,8 @@ All notable changes to `@didis/client` are listed here. The format follows [Keep
 - `DidisError` carrying the RFC 9457 problem body and `Retry-After`.
 - Webhook helpers `verifyWebhookSignature` and `verifyCustomerMonitorSignature`.
 
-[Unreleased]: https://github.com/did-is/didis-js/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/did-is/didis-js/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/did-is/didis-js/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/did-is/didis-js/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/did-is/didis-js/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/did-is/didis-js/compare/v0.2.0...v0.2.1

package/README.md

@@ -63,6 +63,8 @@ try {
 
 Identifiers are percent-encoded exactly once by the client. Non-2xx responses throw `DidisError` with the RFC 9457 problem body (including the resolution `trace` where available).
 
+**Rate limits.** When the public budget is used up the API answers `429` with `Retry-After`. The client waits that long and retries (up to 2 times, at most 10 s per wait), so a loop of calls slows down instead of failing. Tune with `new DidisClient({ retry: { maxRetries: 3, maxWaitMs: 5000 } })` or turn it off with `retry: false`.
+
 ## Guard agent tools
 
 Wrap a tool handler so it runs only when (1) the tool definition the agent received still matches the one you approved and (2) DID.is says the agent's registered delegation grants the tool. Every failure throws `DidisGuardError` and the handler does not run (fail-closed).

package/dist/index.d.ts

@@ -672,18 +672,38 @@ export interface DidisClientOptions {
     adminToken?: string;
     timeoutMs?: number;
     fetch?: typeof fetch;
+    /**
+     * Automatic wait-and-retry when the API answers 429 (request budget used up) or 503
+     * (temporarily overloaded) with a `Retry-After` header. Such refusals happen before the
+     * request is processed, so retrying is safe for every call. Default: up to 2 retries,
+     * never waiting longer than 10 s for one retry. Pass `false` to turn it off.
+     */
+    retry?: false | {
+        maxRetries?: number;
+        maxWaitMs?: number;
+    };
 }
+/** Milliseconds to wait from a `Retry-After` value (delta-seconds or HTTP-date); null if unusable. */
+export declare function retryAfterMs(value: string | null | undefined, now?: number): number | null;
 /** Public DID.is API. Point `baseUrl` at your own deployment when self-hosting. */
 export declare const DEFAULT_BASE_URL = "https://did.is/api";
 /** Package version, kept equal to package.json (checked by the test suite). */
-export declare const VERSION = "0.2.3";
+export declare const VERSION = "0.2.4";
 export declare class DidisClient {
     private readonly baseUrl;
     private readonly adminToken?;
     private readonly timeoutMs;
     private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly maxWaitMs;
     constructor(options?: string | DidisClientOptions);
+    /**
+     * Waits out a 429/503 refusal when the server says how long, within the configured bounds.
+     * A small random delay spreads out many clients that were refused at the same moment.
+     */
+    private backoff;
     private request;
+    private once;
     private admin;
     health(): Promise<HealthStatus>;
     /** Enriched resolution: verdict, evidence dimensions, graph, telemetry. */

package/dist/index.js

@@ -12,10 +12,21 @@ export class DidisError extends Error {
         this.problem = problem;
     }
 }
+/** Milliseconds to wait from a `Retry-After` value (delta-seconds or HTTP-date); null if unusable. */
+export function retryAfterMs(value, now = Date.now()) {
+    if (!value)
+        return null;
+    const v = value.trim();
+    if (/^\d+$/.test(v))
+        return Number(v) * 1000;
+    const at = Date.parse(v);
+    return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Public DID.is API. Point `baseUrl` at your own deployment when self-hosting. */
 export const DEFAULT_BASE_URL = "https://did.is/api";
 /** Package version, kept equal to package.json (checked by the test suite). */
-export const VERSION = "0.2.3";
+export const VERSION = "0.2.4";
 /**
  * Identifies the SDK to the API so DID.is can count SDK use apart from other HTTP clients.
  * Only the product name and version are sent. Browsers are left alone: there the browser
@@ -28,14 +39,42 @@ export class DidisClient {
     adminToken;
     timeoutMs;
     fetchImpl;
+    maxRetries;
+    maxWaitMs;
     constructor(options = {}) {
         const o = typeof options === "string" ? { baseUrl: options } : options;
         this.baseUrl = (o.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
         this.adminToken = o.adminToken;
         this.timeoutMs = o.timeoutMs ?? 30_000;
         this.fetchImpl = o.fetch ?? fetch;
+        this.maxRetries = o.retry === false ? 0 : Math.max(0, Math.floor(o.retry?.maxRetries ?? 2));
+        this.maxWaitMs = o.retry === false ? 0 : Math.max(0, o.retry?.maxWaitMs ?? 10_000);
+    }
+    /**
+     * Waits out a 429/503 refusal when the server says how long, within the configured bounds.
+     * A small random delay spreads out many clients that were refused at the same moment.
+     */
+    async backoff(attempt, status, retryAfter) {
+        if (attempt >= this.maxRetries || (status !== 429 && status !== 503))
+            return false;
+        const wait = retryAfterMs(retryAfter);
+        if (wait === null || wait > this.maxWaitMs)
+            return false;
+        await sleep(wait + Math.floor(Math.random() * 250));
+        return true;
     }
     async request(method, path, body, headers = {}) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.once(method, path, body, headers);
+            }
+            catch (e) {
+                if (!(e instanceof DidisError) || !(await this.backoff(attempt, e.status, e.problem.retryAfter ?? null)))
+                    throw e;
+            }
+        }
+    }
+    async once(method, path, body, headers = {}) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@didis/client",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Official TypeScript/JavaScript SDK for the DID.is public API: DID resolution with evidence, credentials, policies and agent trust",
   "type": "module",
   "main": "./dist/index.js",