@didis/client 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@didis/client` are listed here. The format follows [Keep
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-10-19
+
+### Added
+
+- Optional project API key: `new DidisClient({ apiKey })`. With a key, MCP inspection, A2A inspection, tool-call authorization and delegation-chain checks use the paid `/v1/customer/*` routes and count against your team's monthly allowance instead of the anonymous per-IP limit. Results are identical to the public routes. Each call sends one fresh `Idempotency-Key`; automatic `429`/`503` retries reuse it, so a request is never billed twice. The key is never sent to public routes, and `register: true` delegation checks always use the public route. Without a key nothing changes.
+- `usage()` returns this month's team allowance (`CustomerUsage`: used, reserved, limit and remaining per pool). Requires the API key.
+
+## [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 +69,9 @@ 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.5...HEAD
+[0.2.5]: https://github.com/did-is/didis-js/compare/v0.2.4...v0.2.5
+[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,10 @@ 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`.
+
+**Project API key (optional).** Every check works without a key. A team that needs more than the anonymous per-IP limit can create a key in the DID.is console (Free plan included) and pass it: `new DidisClient({ apiKey: process.env.DIDIS_API_KEY })`. Then `inspectMcp`, `inspectA2a`, `authorize` and `verifyDelegation` use the `/v1/customer/*` routes and count against the team's monthly allowance; results are identical. Each call sends one fresh `Idempotency-Key` (retries reuse it, so nothing is billed twice). `await didis.usage()` shows the allowance left. Keep the key server-side; it is never sent to public routes.
+
 ## 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).
@@ -146,6 +150,7 @@ const ok = await verifyWebhookSignature(
 | `inspectMcp(endpoint)` / `inspectA2a(url)` | `GET /v1/mcp/inspect`, `/v1/a2a/inspect` |
 | `verifyDelegation(chain, opts)` / `authorize(chain, tool, opts)` / `verifyTool(agent, tool, root?)` | `/v1/agents/*` |
 | `fastVerifyDid(did)` / `fastVerifyJws(jws, relationship?)` | `/v1/fast-verify/*` |
+| `usage()` (with `apiKey`) | `GET /v1/customer/usage` |
 | `watch` / `watches` / `unwatch` / `events` | `/v1/monitoring/*` (admin) |
 
 Public API reference: <https://did.is/developers>. Monitoring routes (`watch`, `watches`, `unwatch`, `events`) need an admin token and are only available on self-hosted deployments; they are not exposed by the public API.

package/dist/index.d.ts

@@ -360,6 +360,18 @@ export interface ToolEvidence {
     drift: string;
     inputSchema: unknown;
 }
+/** `GET /v1/customer/usage`: this month's team allowance (all of the team's projects share it). */
+export interface CustomerUsage {
+    period: string;
+    standardUsed: number;
+    standardReserved: number;
+    standardLimit: number;
+    standardRemaining: number;
+    expensiveUsed: number;
+    expensiveReserved: number;
+    expensiveLimit: number;
+    expensiveRemaining: number;
+}
 export interface McpInspection {
     endpoint: string;
     status: "INSPECTED" | "AUTH_REQUIRED" | string;
@@ -670,20 +682,55 @@ export interface DidisClientOptions {
     baseUrl?: string;
     /** Bearer token for admin-only monitoring routes. Never ship it to browsers. */
     adminToken?: string;
+    /**
+     * Project API key from the DID.is console (optional). With a key, `inspectMcp`, `inspectA2a`,
+     * `authorize` and `verifyDelegation` use the paid routes and count against your team's monthly
+     * allowance instead of the anonymous per-IP limit. Results are identical. The key is sent only
+     * to `/v1/customer/*` routes, never to public routes. Keep it server-side.
+     */
+    apiKey?: 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.5";
 export declare class DidisClient {
     private readonly baseUrl;
     private readonly adminToken?;
+    private readonly apiKey?;
     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;
+    /**
+     * Paid route call: the project API key plus one fresh Idempotency-Key. Automatic retries of a
+     * 429/503 reuse the same key, so a request is never billed twice.
+     */
+    private paid;
+    /** Team allowance for this month (requires `apiKey`). Same numbers as the RateLimit headers. */
+    usage(): Promise<CustomerUsage>;
     private admin;
     health(): Promise<HealthStatus>;
     /** Enriched resolution: verdict, evidence dimensions, graph, telemetry. */
@@ -709,6 +756,10 @@ export declare class DidisClient {
     }, credential?: unknown): Promise<PolicyResponse>;
     inspectMcp(endpoint: string): Promise<McpInspection>;
     inspectA2a(url: string): Promise<A2aInspection>;
+    /**
+     * `register: true` stores the chain for `verifyTool`; it always uses the public route (the paid
+     * route never writes shared state), so the API key is not sent for it.
+     */
     verifyDelegation(chain: string[], opts?: {
         trustedRoots?: string[];
         register?: boolean;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { subtle } from "./webcrypto.js";
+import { randomId, subtle } from "./webcrypto.js";
 // ---------------------------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------------------------
@@ -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.5";
 /**
  * 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
@@ -26,16 +37,46 @@ const enc = (s) => encodeURIComponent(s.trim());
 export class DidisClient {
     baseUrl;
     adminToken;
+    apiKey;
     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.apiKey = o.apiKey || undefined;
         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 {
@@ -65,6 +106,20 @@ export class DidisClient {
             clearTimeout(timer);
         }
     }
+    /**
+     * Paid route call: the project API key plus one fresh Idempotency-Key. Automatic retries of a
+     * 429/503 reuse the same key, so a request is never billed twice.
+     */
+    async paid(method, path, body) {
+        const headers = { authorization: `Bearer ${this.apiKey}`, ...(method === "POST" ? { "idempotency-key": await randomId() } : {}) };
+        return this.request(method, `/v1/customer/${path}`, body, headers);
+    }
+    /** Team allowance for this month (requires `apiKey`). Same numbers as the RateLimit headers. */
+    usage() {
+        if (!this.apiKey)
+            return Promise.reject(new Error("apiKey is required for usage()"));
+        return this.paid("GET", "usage");
+    }
     admin() {
         if (!this.adminToken)
             throw new Error("adminToken is required for monitoring routes");
@@ -152,15 +207,28 @@ export class DidisClient {
         return this.request("POST", "/v1/policies/evaluate", { did, policy, credential });
     }
     inspectMcp(endpoint) {
+        if (this.apiKey)
+            return this.paid("POST", "mcp/inspect", { endpoint });
         return this.request("GET", `/v1/mcp/inspect?endpoint=${encodeURIComponent(endpoint)}`);
     }
     inspectA2a(url) {
+        if (this.apiKey)
+            return this.paid("POST", "a2a/inspect", { url });
         return this.request("GET", `/v1/a2a/inspect?url=${encodeURIComponent(url)}`);
     }
+    /**
+     * `register: true` stores the chain for `verifyTool`; it always uses the public route (the paid
+     * route never writes shared state), so the API key is not sent for it.
+     */
     verifyDelegation(chain, opts = {}) {
+        if (this.apiKey && !opts.register) {
+            return this.paid("POST", "agents/verify-delegation", { chain, ...(opts.trustedRoots ? { trustedRoots: opts.trustedRoots } : {}) });
+        }
         return this.request("POST", "/v1/agents/verify-delegation", { chain, ...opts });
     }
     authorize(chain, tool, opts = {}) {
+        if (this.apiKey)
+            return this.paid("POST", "agents/authorize", { chain, tool, ...(opts.trustedRoots ? { trustedRoots: opts.trustedRoots } : {}) });
         return this.request("POST", "/v1/agents/authorize", { chain, tool, ...opts });
     }
     verifyTool(agent, tool, root) {

package/dist/webcrypto.d.ts

@@ -1 +1,3 @@
 export declare function subtle(): Promise<SubtleCrypto>;
+/** Random UUID v4 for idempotency keys; Node 18 has no global `crypto`. */
+export declare function randomId(): Promise<string>;

package/dist/webcrypto.js

@@ -14,3 +14,13 @@ export function subtle() {
     }
     return cached;
 }
+/** Random UUID v4 for idempotency keys; Node 18 has no global `crypto`. */
+export async function randomId() {
+    const g = globalThis.crypto;
+    if (g?.randomUUID)
+        return g.randomUUID();
+    const m = (await import("node:crypto"));
+    if (!m.randomUUID)
+        throw new Error("crypto.randomUUID is not available in this runtime");
+    return m.randomUUID();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@didis/client",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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",