@didis/client 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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
@@ -62,7 +69,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.4...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

package/README.md

@@ -65,6 +65,8 @@ Identifiers are percent-encoded exactly once by the client. Non-2xx responses th
 
 **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).
@@ -148,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,6 +682,13 @@ 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;
     /**
@@ -688,10 +707,11 @@ export declare function retryAfterMs(value: string | null | undefined, now?: num
 /** 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.4";
+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;
@@ -704,6 +724,13 @@ export declare class DidisClient {
     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. */
@@ -729,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
 // ---------------------------------------------------------------------------------------------
@@ -26,7 +26,7 @@ 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.4";
+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
@@ -37,6 +37,7 @@ const enc = (s) => encodeURIComponent(s.trim());
 export class DidisClient {
     baseUrl;
     adminToken;
+    apiKey;
     timeoutMs;
     fetchImpl;
     maxRetries;
@@ -45,6 +46,7 @@ export class DidisClient {
         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));
@@ -104,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");
@@ -191,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.4",
+  "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",