@didis/client 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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
+
+- Requests now carry `user-agent: didis-client/<version>` (Node, Deno, Bun and other non-browser runtimes; browsers keep their own user agent). Only the package name and version are sent, so DID.is can count SDK use separately from other HTTP clients. New export `VERSION`.
+
+- Type `LinkedAccountEvidence` and `Evidence.linkedAccounts`: each `alsoKnownAs` value with whether that website links back to the DID (`CONFIRMED`, `NOT_CONFIRMED`, `FAILED`, `UNSUPPORTED`, `UNREACHABLE`, `NOT_CHECKABLE`). A confirmation proves the same party controls the website origin and the DID; it does not prove who that party is.
+
+- Policy rule `linkedAccounts` in `PolicyRules`: 1–4 https origins (for example `["https://shop.example"]`) that must be listed in the DID's `alsoKnownAs` and confirm the DID back. Use it to require "this DID belongs to our official website" in one policy call.
+
 ## [0.2.2] - 2026-10-18
 
 ### Added
@@ -46,7 +62,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.2...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
 [0.2.0]: https://github.com/did-is/didis-js/compare/v0.1.0...v0.2.0

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

@@ -128,6 +128,19 @@ export interface DomainBindingEvidence {
     credentials: LinkageCredentialEvidence[];
     detail: string;
 }
+/** One `alsoKnownAs` value checked for a reciprocal link back to the DID. */
+export interface LinkedAccountEvidence {
+    /** The `alsoKnownAs` value exactly as declared. */
+    value: string;
+    /** `WEB_ORIGIN` | `WEB_PAGE` | `SAME_ORIGIN` | `DID` | `OTHER` */
+    kind: string;
+    origin?: string;
+    /** `CONFIRMED` | `NOT_CONFIRMED` | `FAILED` | `UNSUPPORTED` | `UNREACHABLE` | `NOT_CHECKABLE` */
+    status: string;
+    configurationStatus?: string;
+    configurationSha256?: string;
+    detail: string;
+}
 export interface LogEntryEvidence {
     versionId: string;
     versionNumber: number;
@@ -195,6 +208,8 @@ export interface Evidence {
     keys: KeyEvidence[];
     services: ServiceEvidence[];
     domainBinding?: DomainBindingEvidence;
+    /** Reciprocal checks of `alsoKnownAs`; absent when nothing is declared. */
+    linkedAccounts?: LinkedAccountEvidence[];
     tls?: TlsEvidence;
     history?: HistoryEvidence;
 }
@@ -552,6 +567,8 @@ export interface PolicyRules {
     requireKeyRelationship?: string;
     domainBinding?: "required" | "optional";
     tlsMinDaysRemaining?: number;
+    /** 1–4 bare https origins that must be declared in `alsoKnownAs` and link back to the DID. */
+    linkedAccounts?: string[];
     verifiableHistory?: "required";
     maxCacheAgeSeconds?: number;
     credentialStatus?: "active";
@@ -655,16 +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.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,29 +12,76 @@ 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.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
+ * controls the user agent and an extra header would add a CORS preflight to every call.
+ */
+const SDK_HEADERS = typeof globalThis.document === "undefined" ? { "user-agent": `didis-client/${VERSION}` } : {};
 const enc = (s) => encodeURIComponent(s.trim());
 export class DidisClient {
     baseUrl;
     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 {
             const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
                 method,
                 signal: controller.signal,
-                headers: { accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}), ...headers },
+                headers: { ...SDK_HEADERS, accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}), ...headers },
                 body: body !== undefined ? JSON.stringify(body) : undefined,
             });
             const text = await res.text();
@@ -79,7 +126,7 @@ export class DidisClient {
     /** Live resolution over server-sent events. */
     async *stream(did, opts = { noCache: true }) {
         const res = await this.fetchImpl(`${this.baseUrl}/v1/stream/${enc(did)}${opts.noCache ? "?noCache=true" : ""}`, {
-            headers: { accept: "text/event-stream" },
+            headers: { ...SDK_HEADERS, accept: "text/event-stream" },
         });
         if (!res.ok || !res.body)
             throw new DidisError(res.status, { type: "about:blank", title: `HTTP ${res.status}`, detail: "stream failed" });

package/package.json

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