@eudi-verify/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+/**
+ * @eudi-verify/client - Shared Types
+ *
+ * Re-exported types from the server package for client-side use.
+ * These types define the contract between client and server.
+ */
+/**
+ * Claims that can be requested from an EUDI Wallet.
+ * Each property set to `true` requests that specific claim.
+ */
+interface VerificationRequest {
+    age_over_18?: true;
+    age_over_21?: true;
+    nationality?: true;
+    given_name?: true;
+    family_name?: true;
+    birth_date?: true;
+    [key: string]: true | undefined;
+}
+/**
+ * Session lifecycle states.
+ */
+type SessionStatus = 'pending' | 'waiting_for_wallet' | 'verified' | 'rejected' | 'expired' | 'cancelled' | 'error';
+/**
+ * Terminal states that cannot transition further.
+ */
+declare const TERMINAL_STATUSES: readonly SessionStatus[];
+/**
+ * Check if a status is terminal (cannot transition).
+ */
+declare function isTerminalStatus(status: SessionStatus): boolean;
+/**
+ * Claims extracted from a verified presentation.
+ */
+interface VerifiedClaims {
+    age_over_18?: boolean;
+    age_over_21?: boolean;
+    nationality?: string;
+    given_name?: string;
+    family_name?: string;
+    birth_date?: string;
+    [key: string]: unknown;
+}
+/**
+ * Session as returned by the API.
+ */
+interface Session {
+    id: string;
+    status: SessionStatus;
+    qrUrl?: string;
+    token?: string;
+    claims?: VerifiedClaims;
+    error?: string;
+    createdAt: string;
+    expiresAt: string;
+}
+/**
+ * API error response.
+ */
+interface ApiError {
+    error: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+
+/**
+ * @eudi-verify/client - Polling Utility
+ *
+ * Exponential backoff polling with configurable intervals.
+ */
+/**
+ * Configuration for the poller.
+ */
+interface PollingConfig {
+    /** Initial interval in milliseconds (default: 1000) */
+    initialIntervalMs?: number;
+    /** Maximum interval in milliseconds (default: 10000) */
+    maxIntervalMs?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+}
+/**
+ * Poller instance returned by createPoller.
+ */
+interface Poller {
+    /** Start polling */
+    start(): void;
+    /** Stop polling */
+    stop(): void;
+    /** Reset interval to initial value */
+    reset(): void;
+}
+/**
+ * Create an exponential backoff poller.
+ *
+ * @param fn - Function to call on each poll. Returns true to stop polling.
+ * @param config - Polling configuration.
+ * @returns Poller instance with start/stop/reset methods.
+ *
+ * @example
+ * ```ts
+ * const poller = createPoller(async () => {
+ *   const result = await checkStatus();
+ *   return result.complete; // true stops polling
+ * });
+ *
+ * poller.start();
+ * // ... later
+ * poller.stop();
+ * ```
+ */
+declare function createPoller(fn: () => Promise<boolean>, config?: PollingConfig): Poller;
+
+/**
+ * @eudi-verify/client - QR Code Generator
+ *
+ * Minimal QR code generation for OpenID4VP URLs.
+ * Implements ISO/IEC 18004 (QR Code) with byte mode encoding.
+ */
+interface QRCodeOptions {
+    /** Size in pixels (default: 200) */
+    size?: number;
+    /** Error correction level (default: 'M') */
+    errorCorrection?: 'L' | 'M' | 'Q' | 'H';
+    /** Quiet zone modules (default: 4) */
+    quietZone?: number;
+}
+/**
+ * Generate a QR code as an SVG string.
+ */
+declare function generateQRSvg(data: string, options?: QRCodeOptions): string;
+/**
+ * Generate a QR code as a data URL (PNG via canvas).
+ */
+declare function generateQRDataUrl(data: string, options?: QRCodeOptions): string;
+
+/**
+ * @eudi-verify/client - Verification State Machine
+ *
+ * Manages the verification flow with state transitions and polling.
+ */
+
+/**
+ * All possible verification states.
+ */
+type VerificationState = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'showQR';
+    qrDataUrl: string;
+    qrUrl: string;
+    sessionId: string;
+} | {
+    status: 'waitingForWallet';
+    sessionId: string;
+} | {
+    status: 'verified';
+    token: string;
+    claims: VerifiedClaims;
+} | {
+    status: 'rejected';
+    error?: string;
+} | {
+    status: 'expired';
+} | {
+    status: 'error';
+    error: string;
+};
+/**
+ * State change callback.
+ */
+type StateCallback = (state: VerificationState) => void;
+/**
+ * Configuration for the verification flow.
+ */
+interface VerificationConfig {
+    /** Base URL of the EUDI Verifier API */
+    apiUrl: string;
+    /** Polling configuration */
+    polling?: PollingConfig;
+    /** QR code options */
+    qr?: QRCodeOptions;
+    /** Optional fetch implementation (for testing) */
+    fetch?: typeof fetch;
+}
+/**
+ * Verification instance for managing a verification flow.
+ */
+interface Verification {
+    /** Current state (read-only) */
+    readonly state: VerificationState;
+    /** Start a new verification flow */
+    start(request: VerificationRequest): Promise<void>;
+    /** Cancel the current verification */
+    cancel(): Promise<void>;
+    /** Clean up resources */
+    destroy(): void;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(callback: StateCallback): () => void;
+}
+/**
+ * Create a new verification instance.
+ *
+ * @example
+ * ```ts
+ * const verification = createVerification({ apiUrl: 'https://api.example.com' });
+ *
+ * verification.subscribe((state) => {
+ *   console.log('State:', state.status);
+ *   if (state.status === 'verified') {
+ *     console.log('Token:', state.token);
+ *   }
+ * });
+ *
+ * await verification.start({ age_over_18: true });
+ * ```
+ */
+declare function createVerification(config: VerificationConfig): Verification;
+
+/**
+ * @eudi-verify/client - API Client
+ *
+ * Typed HTTP client for the EUDI Verifier API using native fetch.
+ */
+
+/**
+ * Configuration for the API client.
+ */
+interface ApiClientConfig {
+    /** Base URL of the EUDI Verifier API */
+    baseUrl: string;
+    /** Optional fetch implementation (for testing) */
+    fetch?: typeof fetch;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+/**
+ * Typed API client interface.
+ */
+interface EudiApiClient {
+    /** Create a new verification session */
+    createSession(request: VerificationRequest): Promise<Session>;
+    /** Get the current state of a session */
+    getSession(sessionId: string): Promise<Session>;
+    /** Cancel a pending session */
+    cancelSession(sessionId: string): Promise<Session>;
+}
+/**
+ * Create a typed API client for the EUDI Verifier API.
+ */
+declare function createApiClient(config: ApiClientConfig): EudiApiClient;
+
+/**
+ * @eudi-verify/client - Error Types
+ */
+
+/**
+ * Base error class for EUDI client errors.
+ */
+declare class EudiClientError extends Error {
+    constructor(message: string);
+}
+/**
+ * Network error (fetch failed, timeout, etc.)
+ */
+declare class NetworkError extends EudiClientError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * API returned an error response.
+ */
+declare class ApiResponseError extends EudiClientError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly details?: Record<string, unknown>;
+    constructor(statusCode: number, response: ApiError);
+}
+/**
+ * Session not found (404).
+ */
+declare class SessionNotFoundError extends ApiResponseError {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/**
+ * Rate limit exceeded (429).
+ */
+declare class RateLimitError extends ApiResponseError {
+    readonly retryAfterMs?: number;
+    constructor(retryAfterMs?: number);
+}
+/**
+ * Verification was cancelled.
+ */
+declare class VerificationCancelledError extends EudiClientError {
+    constructor();
+}
+/**
+ * Session expired.
+ */
+declare class SessionExpiredError extends EudiClientError {
+    constructor();
+}
+
+/**
+ * @eudi-verify/client
+ *
+ * Vanilla TypeScript client for EUDI Wallet verification flows.
+ * Zero framework dependencies.
+ *
+ * @example
+ * ```ts
+ * import { createVerification } from '@eudi-verify/client';
+ *
+ * const verification = createVerification({
+ *   apiUrl: 'https://api.example.com',
+ * });
+ *
+ * verification.subscribe((state) => {
+ *   if (state.status === 'showQR') {
+ *     // Display state.qrDataUrl
+ *   } else if (state.status === 'verified') {
+ *     // Use state.token for server-side verification
+ *   }
+ * });
+ *
+ * await verification.start({ age_over_18: true });
+ * ```
+ */
+declare const VERSION = "0.1.0";
+
+export { type ApiClientConfig, type ApiError, ApiResponseError, type EudiApiClient, EudiClientError, NetworkError, type Poller, type PollingConfig, type QRCodeOptions, RateLimitError, type Session, SessionExpiredError, SessionNotFoundError, type SessionStatus, type StateCallback, TERMINAL_STATUSES, VERSION, type Verification, VerificationCancelledError, type VerificationConfig, type VerificationRequest, type VerificationState, type VerifiedClaims, createApiClient, createPoller, createVerification, generateQRDataUrl, generateQRSvg, isTerminalStatus };