@dlbr/eid-sdk API reference

Generated from packages/sdk/dist/*.d.ts by packages/sdk/scripts/generate-api-reference.mjs.

This reference documents the public TypeScript declarations shipped by the package. Import from @dlbr/eid-sdk; do not import internal source paths.

Resource overview

• sessions: create, retrieve, wait for completion, cancel/delete, and stream status events.
• apiKeys: list, create, rotate, and revoke restricted keys.
• webhooks.endpoints: read and configure the tenant webhook endpoint.
• webhooks.failures: list, paginate, iterate, and replay failed deliveries.
• auditLog: list, paginate, and iterate tenant audit entries.
• rawRequest(): authenticated escape hatch for newly released endpoints.
• webhooks.constructEvent(): Stripe-style webhook verification alias.

index.d.ts

export { DEFAULT_BASE_URL, EidClient, type EidClientLogger, type EidClientOptions, type EidClientRequestEvent, type EidClientResponseMetadata, type ListPage, type ListRequestOptions, type RequestOptions, type SessionEventStream } from "./client.js";
export { DlbrIdApiError, DlbrIdAuthenticationError, DlbrIdError, DlbrIdEnvironmentMismatchError, DlbrIdNetworkError, DlbrIdRateLimitError, DlbrIdRequestTimeoutError, DlbrIdTimeoutError, DlbrIdValidationError, DlbrIdWebhookReplayError, type ApiErrorOptions, type DlbrIdErrorKind, type DlbrIdRateLimitMetadata, } from "./errors.js";
export { createMemoryWebhookReplayStore, verifyWebhook, type VerifyWebhookOptions, type WebhookEvent, type WebhookHeaders, type WebhookReplayStore } from "./webhooks.js";
export { createExpressWebhookMiddleware, createFastifyWebhookHandler, createNestWebhookMiddleware, createNextWebhookHandler, type ExpressWebhookMiddleware, type ExpressWebhookNext, type ExpressWebhookRequestLike, type ExpressWebhookResponseLike, type FastifyWebhookHandler, type FastifyWebhookReplyLike, type FastifyWebhookRequestLike, type NextWebhookRoute, type WebhookAdapterOptions, } from "./webhook-middleware.js";
export type { ClaimFilter, ApiKey, ApiKeyScope, ApiKeySecret, AuditLogEntry, CreateApiKeyRequest, CredentialRequest, CreateSessionRequest, DeepLinks, Session, SessionClaims, SessionStatus, SessionStatusEvent, VerificationDetails, WebhookEndpoint, WebhookEndpointSecret, WebhookFailure, WebhookHostStatus, } from "./types.js";

client.d.ts

import type { ApiKey, ApiKeySecret, AuditLogEntry, CreateApiKeyRequest, CreateSessionRequest, Session, SessionStatusEvent, SessionStatusResponse, WebhookEndpoint, WebhookEndpointSecret, WebhookFailure } from "./types.js";
import { type VerifyWebhookOptions, type WebhookEvent, type WebhookHeaders } from "./webhooks.js";
export interface EidClientOptions {
    /** Public API origin. Defaults by key prefix: staging for `sk_test_`, production otherwise. */
    baseUrl?: string;
    apiKey: string;
    fetch?: typeof globalThis.fetch;
    timeoutMs?: number;
    /** Number of automatic retries for safe or idempotent requests. Defaults to 2. */
    maxNetworkRetries?: number;
    /** Optional value appended to the SDK's user-agent metadata for support diagnostics. */
    appInfo?: string;
    /** Explicitly validate that the API key belongs to the selected mode. */
    mode?: "test" | "live";
    /** Gateway API version sent as `X-API-Version`. */
    apiVersion?: string;
    logger?: EidClientLogger;
    onRequest?: (event: EidClientRequestEvent) => void | Promise<void>;
    /** WebSocket constructor override for runtimes that do not expose a global WebSocket. */
    webSocket?: typeof WebSocket;
}
export interface EidClientLogger {
    debug?: (message: string, context?: Record<string, unknown>) => void;
    warn?: (message: string, context?: Record<string, unknown>) => void;
    error?: (message: string, context?: Record<string, unknown>) => void;
}
export interface EidClientRequestEvent {
    method: string;
    path: string;
    status?: number;
    requestId?: string;
    attempt: number;
    durationMs: number;
    retrying: boolean;
}
export interface RequestOptions {
    idempotencyKey?: string;
    signal?: AbortSignal;
    timeoutMs?: number;
    maxNetworkRetries?: number;
}
export interface ListRequestOptions extends RequestOptions {
    limit?: number;
    cursor?: string;
}
export interface ListPage<T> {
    data: T[];
    hasMore: boolean;
    nextCursor?: string;
}
export interface SessionEventStream {
    readonly socket: WebSocket;
    readonly lastEventId?: number;
    close: (code?: number, reason?: string) => void;
    [Symbol.asyncIterator](): AsyncIterator<SessionStatusEvent>;
}
export interface EidClientResponseMetadata {
    status: number;
    requestId?: string;
    headers: Record<string, string>;
    attempt: number;
}
export declare const DEFAULT_BASE_URL = "https://api.dlbr.app";
export declare class EidClient {
    /** Metadata from the most recent completed HTTP request. Useful for support and tracing. */
    lastResponse?: EidClientResponseMetadata;
    /** Redacted metadata from the most recent request; never contains API keys or bodies. */
    lastRequest?: EidClientRequestEvent;
    readonly webhooks: {
        verify: (rawBody: string, headers: Headers | WebhookHeaders, secret: string, options?: VerifyWebhookOptions) => Promise<WebhookEvent>;
        constructEvent: (rawBody: string, headers: Headers | WebhookHeaders, secret: string, options?: VerifyWebhookOptions) => Promise<WebhookEvent>;
        endpoints: {
            get: (options?: RequestOptions) => Promise<WebhookEndpoint>;
            upsert: (request: {
                url: string;
                signing_secret?: string;
            }, options?: RequestOptions) => Promise<WebhookEndpointSecret>;
        };
        failures: {
            list: (options?: ListRequestOptions) => Promise<WebhookFailure[]>;
            listPage: (options?: ListRequestOptions) => Promise<ListPage<WebhookFailure>>;
            iterate: (options?: ListRequestOptions) => AsyncIterable<WebhookFailure>;
            retry: (failureId: string, options?: RequestOptions) => Promise<{
                status: "REPLAYED";
                id: string;
                session_id: string;
            }>;
        };
    };
    readonly auditLog: {
        list: (options?: ListRequestOptions) => Promise<AuditLogEntry[]>;
        listPage: (options?: ListRequestOptions) => Promise<ListPage<AuditLogEntry>>;
        iterate: (options?: ListRequestOptions) => AsyncIterable<AuditLogEntry>;
    };
    readonly sessions: {
        create: (request: CreateSessionRequest, options?: RequestOptions) => Promise<Session>;
        retrieve: (sessionId: string, options?: RequestOptions) => Promise<SessionStatusResponse>;
        get: (sessionId: string, options?: RequestOptions) => Promise<SessionStatusResponse>;
        waitForCompletion: (sessionId: string, options?: {
            timeoutMs?: number;
            pollIntervalMs?: number;
            signal?: AbortSignal;
        }) => Promise<SessionStatusResponse>;
        events: {
            connect: (sessionId: string, options?: {
                after?: number;
                signal?: AbortSignal;
            }) => SessionEventStream;
        };
        cancel: (sessionId: string, options?: RequestOptions) => Promise<void>;
        delete: (sessionId: string, options?: RequestOptions) => Promise<void>;
    };
    readonly apiKeys: {
        list: (options?: RequestOptions) => Promise<ApiKey[]>;
        create: (request: CreateApiKeyRequest, options?: RequestOptions) => Promise<ApiKeySecret>;
        rotate: (keyId: string, options?: RequestOptions) => Promise<ApiKeySecret>;
        revoke: (keyId: string, options?: RequestOptions) => Promise<void>;
    };
    private readonly baseUrl;
    private readonly apiKey;
    private readonly fetchFn;
    private readonly timeoutMs;
    private readonly maxNetworkRetries;
    private readonly appInfo?;
    private readonly apiVersion?;
    private readonly logger?;
    private readonly onRequest?;
    private readonly webSocket?;
    constructor(options: EidClientOptions);
    /**
     * Sends a typed or untyped request through the SDK's authenticated pipeline.
     * Use this for a newly released Gateway endpoint before a resource helper is added.
     */
    rawRequest<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
    private createSession;
    private getSession;
    private waitForCompletion;
    private connectSessionEvents;
    private deleteSession;
    private listApiKeys;
    private createApiKey;
    private rotateApiKey;
    private revokeApiKey;
    private getWebhookEndpoint;
    private upsertWebhookEndpoint;
    private listWebhookFailures;
    private listWebhookFailuresPage;
    private retryWebhookFailure;
    private listAuditLog;
    private listAuditLogPage;
    private iteratePages;
    private toListPage;
    private withLimit;
    private request;
    private responseMetadata;
    private isRetryableStatus;
    private retryDelay;
    private apiErrorOptions;
    private createApiError;
    private retryAfterMs;
    private rateLimitMetadata;
    private parseHeaderNumber;
    private emitRequest;
    private backoffDelay;
    private validateRetries;
    private validateBaseUrl;
    private validateApiKeyMode;
    private newIdempotencyKey;
    private combineSignals;
    private delay;
}
/** @deprecated Use EidClientOptions instead. */
export type DlbrIdOptions = EidClientOptions;
/** @deprecated Use EidClientLogger instead. */
export type DlbrIdLogger = EidClientLogger;
/** @deprecated Use EidClientRequestEvent instead. */
export type DlbrIdRequestEvent = EidClientRequestEvent;
/** @deprecated Use EidClientResponseMetadata instead. */
export type DlbrIdResponseMetadata = EidClientResponseMetadata;
/** @deprecated Use EidClient instead. */
export { EidClient as DlbrId };

types.d.ts

export type CredentialFormat = "vc+sd-jwt" | "dc+sd-jwt" | "mso_mdoc";
export type TrustDomain = "pid" | "pub_eaa" | "mdoc";
export interface ClaimFilter {
    type?: string | string[];
    const?: unknown;
    enum?: unknown[];
    minimum?: number;
    maximum?: number;
    exclusiveMinimum?: number;
    exclusiveMaximum?: number;
    pattern?: string;
    format?: string;
    formatMinimum?: string;
    formatMaximum?: string;
}
export interface CredentialRequest {
    id?: string;
    format: CredentialFormat;
    issuer_id: string;
    namespace?: string;
    doc_type?: string;
    claims: string[];
    alg?: "ES256" | "ES384" | "ES512";
    trust_domain?: TrustDomain;
    subject_claim_paths?: string[];
    claim_filters?: Record<string, ClaimFilter>;
}
export interface CreateSessionRequest {
    ttl_ms?: number;
    credentials: CredentialRequest[];
    same_subject_groups?: string[][];
    redirect_uri?: string;
}
export type ApiKeyScope = "session:create" | "session:read" | "audit:read" | "api_keys:manage";
export interface ApiKey {
    id: string;
    name: string | null;
    scopes: ApiKeyScope[] | null;
    revoked: boolean;
    livemode: boolean;
    created_at: string;
    expires_at: string | null;
    last_used_at: string | null;
}
export interface CreateApiKeyRequest {
    name?: string;
    scopes: ApiKeyScope[];
    expires_at?: string | null;
}
export interface ApiKeySecret {
    id: string;
    name: string | null;
    scopes: ApiKeyScope[] | null;
    api_key: string;
    livemode: boolean;
    created_at?: string;
    expires_at: string | null;
    last_used_at: string | null;
}
export type WebhookHostStatus = "PENDING" | "APPROVED" | "REJECTED";
export interface WebhookEndpoint {
    client_id: string;
    url: string;
    created_at: string;
    host_status: WebhookHostStatus;
    host_review_note: string | null;
}
export interface WebhookEndpointSecret extends WebhookEndpoint {
    signing_secret: string;
}
export interface WebhookFailure {
    id: string;
    session_id: string;
    client_id: string;
    payload: unknown;
    error_message: string | null;
    attempts: number;
    failed_at: string;
}
export interface AuditLogEntry {
    session_id: string;
    status: string;
    credential_types: string[];
    issuer_ids: string[];
    error_code: string;
    latency_ms: number;
    occurred_at: string;
    prev_hash: string;
    entry_hash: string;
    chain_intact: boolean;
}
export interface DeepLinks {
    [key: string]: string;
}
export interface Session {
    session_id: string;
    livemode: boolean;
    expires_at: string;
    qr_code_url: string;
    deep_links: DeepLinks;
    dc_api_request_url: string;
    dc_api_response_url: string;
    iso_mdoc_request_url: string;
    iso_mdoc_response_url: string;
}
export interface VerificationDetails {
    issuer_auth?: unknown;
    device_auth?: unknown;
    trust_chain?: unknown;
    revocation_check?: unknown;
    claim_subject_binding?: {
        status: string;
        evaluated_paths?: string[];
    };
    subject_binding?: unknown;
}
export type SessionStatus = "CREATED" | "PENDING" | "VERIFYING" | "VERIFIED" | "FAILED" | "EXPIRED";
export type SessionClaims = Record<string, unknown>;
export interface SessionStatusResponse {
    session_id: string;
    status: SessionStatus;
    livemode: boolean;
    expires_at?: string;
    claims?: SessionClaims;
    verification_details?: Record<string, VerificationDetails>;
    reason?: string;
}
export interface SessionStatusEvent {
    type: "status";
    status: SessionStatus;
    seq: number;
}

errors.d.ts

export type DlbrIdErrorKind = "sdk_error" | "api_error" | "authentication_error" | "validation_error" | "rate_limit_error" | "network_error" | "timeout_error";
export declare class DlbrIdError extends Error {
    readonly name: string;
    readonly kind: DlbrIdErrorKind;
    constructor(message: string, options?: {
        cause?: unknown;
        kind?: DlbrIdErrorKind;
    });
    isRetryable(): boolean;
    isRateLimited(): boolean;
    isValidationError(): boolean;
    isAuthenticationError(): boolean;
}
export interface ApiErrorOptions {
    kind?: DlbrIdErrorKind;
    type?: string;
    param?: string;
    requestId?: string;
    headers?: Record<string, string>;
    raw?: unknown;
    retryAfterMs?: number;
    rateLimit?: DlbrIdRateLimitMetadata;
}
/** Server-provided quota information for a rate-limited request. */
export interface DlbrIdRateLimitMetadata {
    limit?: number;
    remaining?: number;
    /** Milliseconds until the fixed-window quota is expected to reset. */
    resetAfterMs?: number;
}
export declare class DlbrIdApiError extends DlbrIdError {
    readonly name: string;
    readonly status: number;
    readonly statusCode: number;
    readonly code: string;
    readonly type: string;
    readonly param?: string;
    readonly requestId?: string;
    readonly headers: Record<string, string>;
    readonly raw: unknown;
    readonly retryAfterMs?: number;
    readonly rateLimit?: DlbrIdRateLimitMetadata;
    constructor(status: number, code: string, message: string, options?: ApiErrorOptions);
    isRetryable(): boolean;
}
export declare class DlbrIdAuthenticationError extends DlbrIdApiError {
    readonly name: string;
    constructor(status: number, code: string, message: string, options?: ApiErrorOptions);
}
export declare class DlbrIdEnvironmentMismatchError extends DlbrIdError {
    readonly name: string;
    readonly code = "ERR_DLBR_ENV_MISMATCH";
    constructor(message?: string);
}
export declare class DlbrIdValidationError extends DlbrIdApiError {
    readonly name: string;
    constructor(status: number, code: string, message: string, options?: ApiErrorOptions);
}
export declare class DlbrIdWebhookReplayError extends DlbrIdError {
    readonly name = "DlbrIdWebhookReplayError";
    readonly replayKey: string;
    constructor(replayKey: string);
}
export declare class DlbrIdRateLimitError extends DlbrIdApiError {
    readonly name: string;
    constructor(status: number, code: string, message: string, options?: ApiErrorOptions);
}
export declare class DlbrIdNetworkError extends DlbrIdError {
    readonly name: string;
    constructor(message?: string, options?: {
        cause?: unknown;
    });
}
export declare class DlbrIdRequestTimeoutError extends DlbrIdError {
    readonly name: string;
    constructor(timeoutMs: number, options?: {
        cause?: unknown;
    });
}
export declare class DlbrIdTimeoutError extends DlbrIdError {
    readonly name: string;
    readonly sessionId: string;
    constructor(sessionId: string, timeoutMs: number);
}

webhooks.d.ts

export interface WebhookEvent {
    sessionId: string;
    clientId: string;
    status: "VERIFIED" | "EXPIRED" | "FAILED";
    latencyMs: number;
    issuerIds: string[];
}
export interface WebhookHeaders {
    "webhook-signature"?: string;
    "x-idempotency-key"?: string;
    "x-signature"?: string;
    "x-timestamp"?: string;
    [key: string]: string | undefined;
}
export interface VerifyWebhookOptions {
    /** Maximum accepted age of a delivery in milliseconds. Defaults to five minutes. */
    toleranceMs?: number;
    /** Current time in milliseconds, injectable for deterministic tests. */
    nowMs?: number;
    /** Optional atomic store used to reject the same signed delivery more than once. */
    replayStore?: WebhookReplayStore;
}
/**
 * Storage adapter for webhook replay protection. `claim` must be atomic in a
 * distributed deployment (for example Redis SET NX, KV with a Durable Object,
 * or a D1 uniqueness constraint). Return true only for the first claim.
 */
export interface WebhookReplayStore {
    claim(key: string, expiresAtMs: number, nowMs?: number): boolean | Promise<boolean>;
}
/**
 * Development-friendly replay store. It is process-local and therefore not a
 * substitute for Redis/KV/Durable Object storage when multiple instances can
 * receive the same webhook.
 */
export declare function createMemoryWebhookReplayStore(maxEntries?: number): WebhookReplayStore;
/**
 * Verifies a gateway webhook against the exact raw request body and returns its parsed event.
 * The body must be read as text before parsing; re-serializing JSON can change the signed bytes.
 */
export declare function verifyWebhook(rawBody: string, headers: Headers | WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<WebhookEvent>;