@otskit/client 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -1,361 +0,0 @@
-import { Timestamp, BlockHeader, Attestation } from '@otskit/core';
-export { Attestation, BitcoinAttestation, DetachedTimestampFile, PendingAttestation, Timestamp, verifyAgainstBlockheader } from '@otskit/core';
-
-/**
- * Type definitions for the OpenTimestamps Client SDK
- */
-/** Logger interface for observability */
-interface Logger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}
-/** Backoff strategy for retries */
-type BackoffStrategy = 'exponential' | 'linear' | 'constant';
-/** Jitter type for randomizing backoff delays */
-type JitterType = 'none' | 'full' | 'equal';
-/** Retry configuration */
-interface RetryOptions {
-    enabled: boolean;
-    maxAttempts: number;
-    backoff: {
-        strategy: BackoffStrategy;
-        initialDelayMs: number;
-        maxDelayMs?: number;
-        jitter: JitterType;
-    };
-}
-/** Circuit breaker configuration */
-interface CircuitBreakerOptions {
-    enabled: boolean;
-    failureThreshold: number;
-    recoveryTimeoutMs: number;
-    halfOpenMaxAttempts?: number;
-}
-/** Network resilience configuration */
-interface ResilienceOptions {
-    totalTimeoutMs: number;
-    connectTimeoutMs: number;
-    retries: RetryOptions;
-    circuitBreaker: CircuitBreakerOptions;
-}
-/** Client configuration options */
-interface ClientOptions {
-    /** List of OpenTimestamps calendar URLs */
-    calendars?: string[];
-    /** Network resilience configuration */
-    resilience?: Partial<ResilienceOptions>;
-    /** Optional logger for observability */
-    logger?: Logger;
-    /** Optional AbortSignal to cancel all operations */
-    signal?: AbortSignal;
-    /** Minimum successful calendar submissions required (default: 2) */
-    minimumSuccessfulSubmissions?: number;
-}
-/** Operation-specific options */
-interface OperationOptions {
-    signal?: AbortSignal;
-}
-/** Verification result */
-interface VerificationResult {
-    valid: boolean;
-    blockHeight?: number;
-    blockHash?: string;
-    timestamp?: number;
-    error?: string;
-}
-/** Default calendar servers */
-declare const DEFAULT_CALENDARS: string[];
-/** Default resilience configuration */
-declare const DEFAULT_RESILIENCE: ResilienceOptions;
-
-/**
- * Main OpenTimestamps Client SDK
- */
-
-/**
- * OpenTimestamps Client SDK
- *
- * Provides a high-level interface for interacting with OpenTimestamps calendars
- * with built-in resilience patterns (timeout, retry, circuit breaker)
- *
- * @example
- * ```typescript
- * const client = new OpenTimestampsClient({
- *   calendars: ['https://alice.btc.calendar.opentimestamps.org']
- * })
- *
- * // Create timestamp
- * const fileHash = Buffer.from('a'.repeat(64), 'hex')
- * const otsProof = await client.stamp(fileHash)
- *
- * // Later, upgrade to get Bitcoin confirmation
- * const upgradedProof = await client.upgrade(otsProof)
- *
- * // Verify the timestamp
- * const result = await client.verify(upgradedProof, fileHash)
- * console.log(`Confirmed in block ${result.blockHeight}`)
- * ```
- */
-declare class OpenTimestampsClient {
-    private calendars;
-    private networkLayer;
-    private logger?;
-    private globalSignal?;
-    private minimumSuccessfulSubmissions;
-    /**
-     * Create a new OpenTimestamps client
-     *
-     * @param options Client configuration options
-     */
-    constructor(options?: ClientOptions);
-    /**
-     * Create a timestamp by submitting a hash to calendar servers
-     *
-     * @param hash SHA-256 hash of the data to timestamp (as Buffer or hex string)
-     * @param options Operation-specific options
-     * @returns Initial .ots proof with pending attestations
-     *
-     * @throws {ValidationError} If the hash is invalid
-     * @throws {StampError} If submission fails to all calendars
-     * @throws {NetworkError} If network errors occur
-     *
-     * @example
-     * ```typescript
-     * const hash = crypto.createHash('sha256').update('my data').digest()
-     * const otsProof = await client.stamp(hash)
-     * // Save otsProof to database as Buffer
-     * ```
-     */
-    stamp(hash: Buffer | string, options?: OperationOptions): Promise<Buffer>;
-    /**
-     * Upgrade an incomplete timestamp proof by querying calendars for Bitcoin confirmation
-     *
-     * @param incompleteProof The initial .ots proof returned by stamp()
-     * @param options Operation-specific options
-     * @returns Upgraded .ots proof with Bitcoin attestation (if available)
-     *
-     * @throws {ValidationError} If the proof format is invalid
-     * @throws {UpgradeError} If no calendar has confirmed the timestamp yet
-     * @throws {NetworkError} If network errors occur
-     *
-     * @example
-     * ```typescript
-     * // Proof already has pending attestations from stamp()
-     * const upgradedProof = await client.upgrade(incompleteProof)
-     *
-     * // If upgrade throws UpgradeError, Bitcoin hasn't confirmed yet
-     * // Retry later (typically 10-60 minutes after stamp)
-     * ```
-     */
-    upgrade(incompleteProof: Buffer, options?: OperationOptions): Promise<Buffer>;
-    /**
-     * Verify a complete timestamp proof against the Bitcoin blockchain
-     *
-     * @param proof The complete .ots proof with Bitcoin attestation
-     * @param originalDataHash Optional: the original data hash to verify against
-     * @returns Verification result with block details
-     *
-     * @example
-     * ```typescript
-     * const result = await client.verify(completeProof, originalHash)
-     *
-     * if (result.valid) {
-     *   console.log(`Timestamp confirmed in Bitcoin block ${result.blockHeight}`)
-     *   console.log(`Block timestamp: ${new Date(result.timestamp! * 1000)}`)
-     * } else {
-     *   console.error(`Verification failed: ${result.error}`)
-     * }
-     * ```
-     */
-    verify(proof: Buffer, originalDataHash?: Buffer | string): Promise<VerificationResult>;
-    /**
-     * Get the current state of the circuit breaker for a calendar
-     * Useful for monitoring and debugging
-     *
-     * @param calendarUrl The calendar URL to check
-     * @returns Circuit state: 'CLOSED', 'OPEN', or 'HALF_OPEN' (undefined if not yet initialized)
-     */
-    getCircuitState(calendarUrl: string): 'CLOSED' | 'OPEN' | 'HALF_OPEN' | undefined;
-    /**
-     * Reset the circuit breaker for a specific calendar
-     * Use this to manually recover a calendar that has been marked as failing
-     *
-     * @param calendarUrl The calendar URL to reset
-     */
-    resetCircuit(calendarUrl: string): void;
-    /**
-     * Reset all circuit breakers
-     * Use this to clear all failure states
-     */
-    resetAllCircuits(): void;
-}
-
-/**
- * Custom error classes for the OpenTimestamps Client SDK
- */
-/** Base class for all SDK-specific errors */
-declare class OpenTimestampsClientError extends Error {
-    readonly cause?: Error;
-    constructor(message: string, options?: {
-        cause?: Error;
-    });
-}
-/** Error during input validation */
-declare class ValidationError extends OpenTimestampsClientError {
-}
-/** Error during stamp operation */
-declare class StampError extends OpenTimestampsClientError {
-    readonly successfulSubmissions: Array<{
-        calendar: string;
-        proof?: Buffer;
-    }>;
-    readonly failedSubmissions: Array<{
-        calendar: string;
-        error: Error;
-    }>;
-    constructor(message: string, successful: Array<{
-        calendar: string;
-        proof?: Buffer;
-    }>, failed: Array<{
-        calendar: string;
-        error: Error;
-    }>, options?: {
-        cause?: Error;
-    });
-}
-/** Error during upgrade operation */
-declare class UpgradeError extends OpenTimestampsClientError {
-}
-/** Network-related error (timeout, all retries failed, etc.) */
-declare class NetworkError extends OpenTimestampsClientError {
-    /** HTTP status code, cuando el fallo viene de una respuesta HTTP. */
-    readonly status?: number;
-    constructor(message: string, options?: {
-        cause?: Error;
-        status?: number;
-    });
-}
-/** Circuit breaker is open, request rejected */
-declare class CircuitBreakerError extends NetworkError {
-    constructor(calendar: string);
-}
-/** El calendario no conoce (todavía) el commitment consultado (HTTP 404). */
-declare class CommitmentNotFoundError extends NetworkError {
-}
-/** La respuesta del calendario supera el límite de tamaño permitido (defensa DoS). */
-declare class CalendarResponseTooLargeError extends NetworkError {
-}
-/** Respuesta del explorador Esplora inválida: vacía, no-JSON, malformada o demasiado grande (defensa DoS). */
-declare class EsploraResponseError extends NetworkError {
-}
-
-/**
- * Circuit Breaker implementation for protecting against cascading failures
- */
-
-declare enum CircuitState {
-    CLOSED = "CLOSED",
-    OPEN = "OPEN",
-    HALF_OPEN = "HALF_OPEN"
-}
-
-/**
- * Universal fetch adapter for multi-runtime compatibility
- * Works in Node.js 18+, browsers, and edge runtimes
- */
-interface FetchRequest {
-    url: string;
-    method: 'GET' | 'POST';
-    body?: Uint8Array;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-}
-interface FetchResponse {
-    ok: boolean;
-    status: number;
-    statusText: string;
-    data: Uint8Array;
-}
-
-declare class ResilientNetworkLayer {
-    private options;
-    private logger?;
-    private circuitBreaker;
-    constructor(options: ResilienceOptions, logger?: Logger | undefined);
-    /**
-     * Execute a request with full resilience pipeline
-     */
-    request(calendarUrl: string, request: Omit<FetchRequest, 'signal'>, parentSignal?: AbortSignal): Promise<FetchResponse>;
-    /** Get circuit breaker state for a calendar */
-    getCircuitState(calendarUrl: string): CircuitState | undefined;
-    /** Reset circuit breaker for a calendar */
-    resetCircuit(calendarUrl: string): void;
-    /** Reset all circuit breakers */
-    resetAllCircuits(): void;
-}
-
-/**
- * Cliente de un calendario remoto OpenTimestamps (protocolo OTS real).
- */
-
-/** Límite de tamaño de la respuesta de un calendario (defensa DoS). */
-declare const MAX_CALENDAR_RESPONSE_SIZE = 10000;
-/** Interfaz con un servidor de calendario remoto. */
-declare class CalendarClient {
-    #private;
-    private readonly url;
-    private readonly networkLayer;
-    private readonly logger?;
-    constructor(url: string, networkLayer: ResilientNetworkLayer, logger?: Logger | undefined);
-    /** Envía un digest al calendario y devuelve el Timestamp que lo commit-ea. */
-    submit(digest: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
-    /** Pregunta al calendario si tiene un Timestamp más completo para `commitment` (upgrade). */
-    getTimestamp(commitment: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
-}
-/** Lista blanca de URLs de calendario de confianza. */
-declare class UrlWhitelist {
-    #private;
-    constructor(urls?: readonly string[]);
-    /** Añade un patrón; si no trae esquema, se añaden las variantes http y https. */
-    add(url: string): void;
-    /** Verdadero si `url` casa con algún patrón de la whitelist. */
-    contains(url: string): boolean;
-    toString(): string;
-}
-/** Calendarios de confianza por defecto para verificación/upgrade. */
-declare const DEFAULT_CALENDAR_WHITELIST: UrlWhitelist;
-/** Agregadores por defecto a los que enviar digests al sellar. */
-declare const DEFAULT_AGGREGATORS: readonly string[];
-
-/** Explorador Esplora público por defecto (Bitcoin mainnet). */
-declare const PUBLIC_ESPLORA_URL = "https://blockstream.info/api";
-/** Límite de tamaño de una respuesta de Esplora (defensa DoS). Una cabecera JSON ronda los cientos de bytes. */
-declare const MAX_ESPLORA_RESPONSE_SIZE = 100000;
-interface EsploraClientOptions {
-    /** URL base del explorador (por defecto Blockstream). Útil para apuntar a un Esplora de Litecoin. */
-    url?: string;
-    logger?: Logger;
-}
-/** Cliente de un explorador Esplora remoto. */
-declare class EsploraClient {
-    #private;
-    constructor(networkLayer: ResilientNetworkLayer, options?: EsploraClientOptions);
-    /** Devuelve el hash (hex 64, minúsculas) del bloque a la altura dada. */
-    blockHash(height: number, signal?: AbortSignal): Promise<string>;
-    /** Devuelve la cabecera del bloque (merkleroot + time) dado su hash. */
-    block(hash: string, signal?: AbortSignal): Promise<BlockHeader>;
-}
-/**
- * Verifica una atestación Bitcoin/Litecoin contra la cabecera del bloque correspondiente.
- *
- * `digest` es el commitment final del árbol del timestamp en el punto de la atestación
- * (32 bytes, debe ser el merkleroot del bloque). `explorer` debe apuntar a la cadena de la
- * atestación (Blockstream para Bitcoin; un Esplora de Litecoin para Litecoin). Devuelve el
- * tiempo del bloque (epoch s) en éxito; lanza `VerificationError` si no coincide o si la
- * atestación no es verificable en cadena (`pending`/`unknown`). Fail-closed.
- */
-declare function verifyTimestampAttestation(digest: Uint8Array, attestation: Attestation, explorer: EsploraClient, signal?: AbortSignal): Promise<number>;
-
-export { type BackoffStrategy, CalendarClient, CalendarResponseTooLargeError, CircuitBreakerError, type CircuitBreakerOptions, CircuitState, type ClientOptions, CommitmentNotFoundError, DEFAULT_AGGREGATORS, DEFAULT_CALENDARS, DEFAULT_CALENDAR_WHITELIST, DEFAULT_RESILIENCE, EsploraClient, type EsploraClientOptions, EsploraResponseError, type JitterType, type Logger, MAX_CALENDAR_RESPONSE_SIZE, MAX_ESPLORA_RESPONSE_SIZE, NetworkError, OpenTimestampsClient, OpenTimestampsClientError, type OperationOptions, PUBLIC_ESPLORA_URL, type ResilienceOptions, ResilientNetworkLayer, type RetryOptions, StampError, UpgradeError, UrlWhitelist, ValidationError, type VerificationResult, verifyTimestampAttestation };