@routedock/routedock 0.1.1 → 0.2.0

package/dist/SessionReconciler-bi0z2qtN.d.cts

@@ -0,0 +1,125 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { S as SeenTxStore, a as SettlementRecord } from './MppSessionHandler-B4TyD7Xg.cjs';
+import { R as RouteDockManifest } from './types-DmhmfLzP.cjs';
+import { Keypair } from '@stellar/stellar-sdk';
+
+/**
+ * Settlement idempotency backed by Postgres via Supabase.
+ *
+ * The in-memory default {@link InMemorySeenTxStore} is per-handler and
+ * per-process. On serverless/edge runtimes (Cloudflare Workers, Deno Deploy,
+ * Lambda@Edge) each request may land in a fresh isolate with an empty cache.
+ * An agent retrying after a post-settlement timeout would miss the cache and
+ * settle a second time, charging twice on-chain.
+ *
+ * Postgres gives the read-your-writes consistency this needs; Workers KV
+ * would not, since a retry can outrun propagation and reintroduce the double
+ * settle.
+ *
+ * Requires the `settlements` table from migration `003_settlement_idempotency`:
+ *
+ * ```sql
+ * CREATE TABLE settlements (
+ *   key        TEXT PRIMARY KEY,
+ *   tx_hash    TEXT,
+ *   headers    JSONB,
+ *   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { SupabaseSeenTxStore } from '@routedock/routedock/store'
+ * import { createClient } from '@supabase/supabase-js'
+ *
+ * const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY!)
+ * const seenTxStore = new SupabaseSeenTxStore(supabase)
+ *
+ * routedockHono({ ..., seenTxStore })
+ * ```
+ */
+declare class SupabaseSeenTxStore implements SeenTxStore {
+    private readonly supabase;
+    constructor(supabase: SupabaseClient);
+    get(key: string): Promise<SettlementRecord | undefined>;
+    set(key: string, record: SettlementRecord): Promise<void>;
+}
+
+interface RegisterProviderOptions {
+    supabase: SupabaseClient;
+    manifest: RouteDockManifest & {
+        signature?: string;
+        signature_version?: string;
+    };
+    baseUrl: string;
+    /**
+     * Whether to flag the provider record as verified in Supabase.
+     * Defaults to true (since signature is verified before writing).
+     */
+    verified?: boolean;
+}
+/**
+ * Register a provider in the Supabase `providers` table.
+ *
+ * Verifies the manifest's Ed25519 signature before upserting into the
+ * database keyed on `base_url`.
+ *
+ * Throws `RouteDockSignatureError` if the manifest is unsigned or invalid,
+ * and `Error` if the database upsert fails.
+ */
+declare function registerProvider(optionsOrSupabase: RegisterProviderOptions | SupabaseClient, manifestArg?: RouteDockManifest & {
+    signature?: string;
+}, baseUrlArg?: string, verifiedArg?: boolean): Promise<void>;
+
+/**
+ * Session Reconciler — Recovery mechanism for orphaned MPP sessions
+ *
+ * Scans Supabase for sessions marked as "closing" (client initiated close but
+ * provider crashed before broadcasting settlement). Recovers abandoned funds by
+ * broadcasting the channel close transaction with the latest signed commitment.
+ *
+ * Idempotent: Safe to run multiple times on the same session (settlement_tx_hash
+ * acts as deduplication key).
+ */
+
+type Network = 'testnet' | 'mainnet';
+type ChannelCloseFn = (args: {
+    channel: string;
+    amount: bigint;
+    signature: Buffer;
+    feePayer: {
+        envelopeSigner: Keypair;
+    };
+    network: 'stellar:testnet' | 'stellar:pubnet';
+}) => Promise<string>;
+interface SessionReconcilerOptions {
+    supabase: SupabaseClient;
+    network: Network;
+    payeeSecretKey: string;
+    onRecovered?: (channelId: string, txHash: string, totalPaid: string) => Promise<void>;
+    /** Injectable for testing. Defaults to @stellar/mpp/channel/server close() */
+    channelClose?: ChannelCloseFn;
+}
+interface ReconciliationStats {
+    orphanedCount: number;
+    recoveredCount: number;
+    skippedCount: number;
+    failedCount: number;
+    errors: Array<{
+        channelId: string;
+        reason: string;
+    }>;
+}
+declare function decimalToStroops(amountStr: string): bigint;
+/**
+ * Scan for abandoned sessions and attempt recovery.
+ * Idempotent: sessions with settlement_tx_hash are skipped (already recovered).
+ */
+declare function reconcileAbandonedSessions(opts: SessionReconcilerOptions): Promise<ReconciliationStats>;
+/**
+ * Run reconciliation on provider startup.
+ * Logs results and recovers orphaned sessions before accepting new connections.
+ */
+declare function runStartupReconciliation(opts: SessionReconcilerOptions, logger?: (msg: string) => void): Promise<void>;
+
+export { type ReconciliationStats as R, type SessionReconcilerOptions as S, type RegisterProviderOptions as a, SupabaseSeenTxStore as b, registerProvider as c, decimalToStroops as d, runStartupReconciliation as e, reconcileAbandonedSessions as r };

package/dist/SessionStore-BpK8vv0L.d.cts

@@ -0,0 +1,111 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { m as SessionState } from './types-DmhmfLzP.cjs';
+
+/** Stable error codes for programmatic handling. */
+type RouteDockErrorCode = 'MANIFEST' | 'MANIFEST_TIMEOUT' | 'MANIFEST_SUNSET' | 'NO_SUPPORTED_MODE' | 'FACILITATOR' | 'NETWORK' | 'SIGNATURE' | 'VOUCHER_MONOTONICITY' | 'POLICY_REJECT' | 'CHANNEL_STATE' | 'DISPUTE' | 'REFUND_WINDOW' | 'CLIENT_VERSION_TOO_OLD' | 'TRUSTLINE';
+interface RouteDockErrorOptions {
+    cause?: unknown;
+    /** Milliseconds to wait before retry (e.g. from Retry-After header). */
+    retryAfterMs?: number;
+}
+/** Base error for all RouteDock SDK failures. */
+declare class RouteDockError extends Error {
+    readonly code: RouteDockErrorCode;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    constructor(message: string, code: RouteDockErrorCode, retryable: boolean, options?: RouteDockErrorOptions);
+}
+/** Manifest fetch failed, schema invalid, or required fields missing. */
+declare class RouteDockManifestError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Manifest fetch exceeded the configured timeout without receiving a response. */
+declare class RouteDockManifestTimeoutError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** The provider's signed manifest has reached its declared sunset timestamp. */
+declare class RouteDockManifestSunsetError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** No payment mode in the manifest is supported by this client. */
+declare class RouteDockNoSupportedModeError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** This client's SDK version is below the manifest's min_client_version. Upgrade the SDK to proceed. */
+declare class RouteDockClientVersionError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/**
+ * Account is missing a trustline for the payment asset.
+ * Thrown preflight — before any payment transaction is submitted —
+ * so the caller can establish the trustline first.
+ */
+declare class RouteDockTrustlineError extends RouteDockError {
+    readonly asset: string;
+    readonly issuer: string;
+    readonly remediation: string;
+    constructor(asset: string, issuer: string, remediation: string, options?: RouteDockErrorOptions);
+}
+/** x402 facilitator or provider returned a retryable HTTP failure (5xx, 429). */
+declare class RouteDockFacilitatorError extends RouteDockError {
+    readonly status: number;
+    constructor(message: string, status: number, options?: RouteDockErrorOptions);
+}
+/** Transient network failure (timeouts, connection reset, unreachable host). */
+declare class RouteDockNetworkError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Payment or commitment signature could not be produced or verified. */
+declare class RouteDockSignatureError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Voucher cumulative amount did not increase monotonically. */
+declare class RouteDockVoucherMonotonicityError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Local spend cap or on-chain policy rejected the payment. */
+declare class RouteDockPolicyRejectError extends RouteDockError {
+    readonly reason: string;
+    constructor(reason: string, options?: RouteDockErrorOptions);
+}
+/** Channel lifecycle failure (open, simulate, close, missing settlement fields). */
+declare class RouteDockChannelStateError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Channel dispute operation failed (refund request, settlement, or contract invariant). */
+declare class RouteDockDisputeError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Refund window has not yet opened or has already expired. */
+declare class RouteDockRefundWindowError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** @deprecated Use {@link RouteDockPolicyRejectError} */
+declare const RouteDockPolicyRejectedError: typeof RouteDockPolicyRejectError;
+/** @deprecated Use {@link RouteDockVoucherMonotonicityError} or {@link RouteDockChannelStateError} */
+declare const RouteDockSessionError: typeof RouteDockVoucherMonotonicityError;
+/** Parse Retry-After from a Response (seconds or HTTP-date). */
+declare function parseRetryAfterMs(response: Response): number | undefined;
+/** Map an HTTP status to a typed, retryable-aware RouteDock error. */
+declare function httpStatusToError(message: string, status: number, response?: Response): RouteDockError;
+/** Wrap a low-level fetch failure; preserves existing RouteDockErrors. */
+declare function wrapFetchError(err: unknown, context: string): RouteDockError;
+
+interface SessionStore {
+    get(channelId: string): Promise<SessionState | null>;
+    /** Enforce monotonic invariant at application level before writing (used for voucher amount advances) */
+    upsert(channelId: string, state: SessionState): Promise<void>;
+    /** Update session status without altering cumulative_amount */
+    setStatus(channelId: string, status: SessionState['status'], settlementTxHash?: string | null): Promise<void>;
+    close(channelId: string): Promise<void>;
+}
+declare class SupabaseSessionStore implements SessionStore {
+    private readonly supabase;
+    constructor(supabase: SupabaseClient);
+    get(channelId: string): Promise<SessionState | null>;
+    upsert(channelId: string, state: SessionState): Promise<void>;
+    setStatus(channelId: string, status: SessionState['status'], settlementTxHash?: string | null): Promise<void>;
+    close(channelId: string): Promise<void>;
+}
+
+export { RouteDockChannelStateError as R, type SessionStore as S, RouteDockClientVersionError as a, RouteDockDisputeError as b, RouteDockError as c, type RouteDockErrorCode as d, type RouteDockErrorOptions as e, RouteDockFacilitatorError as f, RouteDockManifestError as g, RouteDockManifestSunsetError as h, RouteDockManifestTimeoutError as i, RouteDockNetworkError as j, RouteDockNoSupportedModeError as k, RouteDockPolicyRejectError as l, RouteDockPolicyRejectedError as m, RouteDockRefundWindowError as n, RouteDockSessionError as o, RouteDockSignatureError as p, RouteDockTrustlineError as q, RouteDockVoucherMonotonicityError as r, SupabaseSessionStore as s, httpStatusToError as t, parseRetryAfterMs as u, wrapFetchError as w };

package/dist/SessionStore-DvkZv8-E.d.ts

@@ -0,0 +1,111 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { m as SessionState } from './types-DmhmfLzP.js';
+
+/** Stable error codes for programmatic handling. */
+type RouteDockErrorCode = 'MANIFEST' | 'MANIFEST_TIMEOUT' | 'MANIFEST_SUNSET' | 'NO_SUPPORTED_MODE' | 'FACILITATOR' | 'NETWORK' | 'SIGNATURE' | 'VOUCHER_MONOTONICITY' | 'POLICY_REJECT' | 'CHANNEL_STATE' | 'DISPUTE' | 'REFUND_WINDOW' | 'CLIENT_VERSION_TOO_OLD' | 'TRUSTLINE';
+interface RouteDockErrorOptions {
+    cause?: unknown;
+    /** Milliseconds to wait before retry (e.g. from Retry-After header). */
+    retryAfterMs?: number;
+}
+/** Base error for all RouteDock SDK failures. */
+declare class RouteDockError extends Error {
+    readonly code: RouteDockErrorCode;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    constructor(message: string, code: RouteDockErrorCode, retryable: boolean, options?: RouteDockErrorOptions);
+}
+/** Manifest fetch failed, schema invalid, or required fields missing. */
+declare class RouteDockManifestError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Manifest fetch exceeded the configured timeout without receiving a response. */
+declare class RouteDockManifestTimeoutError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** The provider's signed manifest has reached its declared sunset timestamp. */
+declare class RouteDockManifestSunsetError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** No payment mode in the manifest is supported by this client. */
+declare class RouteDockNoSupportedModeError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** This client's SDK version is below the manifest's min_client_version. Upgrade the SDK to proceed. */
+declare class RouteDockClientVersionError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/**
+ * Account is missing a trustline for the payment asset.
+ * Thrown preflight — before any payment transaction is submitted —
+ * so the caller can establish the trustline first.
+ */
+declare class RouteDockTrustlineError extends RouteDockError {
+    readonly asset: string;
+    readonly issuer: string;
+    readonly remediation: string;
+    constructor(asset: string, issuer: string, remediation: string, options?: RouteDockErrorOptions);
+}
+/** x402 facilitator or provider returned a retryable HTTP failure (5xx, 429). */
+declare class RouteDockFacilitatorError extends RouteDockError {
+    readonly status: number;
+    constructor(message: string, status: number, options?: RouteDockErrorOptions);
+}
+/** Transient network failure (timeouts, connection reset, unreachable host). */
+declare class RouteDockNetworkError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Payment or commitment signature could not be produced or verified. */
+declare class RouteDockSignatureError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Voucher cumulative amount did not increase monotonically. */
+declare class RouteDockVoucherMonotonicityError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Local spend cap or on-chain policy rejected the payment. */
+declare class RouteDockPolicyRejectError extends RouteDockError {
+    readonly reason: string;
+    constructor(reason: string, options?: RouteDockErrorOptions);
+}
+/** Channel lifecycle failure (open, simulate, close, missing settlement fields). */
+declare class RouteDockChannelStateError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Channel dispute operation failed (refund request, settlement, or contract invariant). */
+declare class RouteDockDisputeError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** Refund window has not yet opened or has already expired. */
+declare class RouteDockRefundWindowError extends RouteDockError {
+    constructor(message: string, options?: RouteDockErrorOptions);
+}
+/** @deprecated Use {@link RouteDockPolicyRejectError} */
+declare const RouteDockPolicyRejectedError: typeof RouteDockPolicyRejectError;
+/** @deprecated Use {@link RouteDockVoucherMonotonicityError} or {@link RouteDockChannelStateError} */
+declare const RouteDockSessionError: typeof RouteDockVoucherMonotonicityError;
+/** Parse Retry-After from a Response (seconds or HTTP-date). */
+declare function parseRetryAfterMs(response: Response): number | undefined;
+/** Map an HTTP status to a typed, retryable-aware RouteDock error. */
+declare function httpStatusToError(message: string, status: number, response?: Response): RouteDockError;
+/** Wrap a low-level fetch failure; preserves existing RouteDockErrors. */
+declare function wrapFetchError(err: unknown, context: string): RouteDockError;
+
+interface SessionStore {
+    get(channelId: string): Promise<SessionState | null>;
+    /** Enforce monotonic invariant at application level before writing (used for voucher amount advances) */
+    upsert(channelId: string, state: SessionState): Promise<void>;
+    /** Update session status without altering cumulative_amount */
+    setStatus(channelId: string, status: SessionState['status'], settlementTxHash?: string | null): Promise<void>;
+    close(channelId: string): Promise<void>;
+}
+declare class SupabaseSessionStore implements SessionStore {
+    private readonly supabase;
+    constructor(supabase: SupabaseClient);
+    get(channelId: string): Promise<SessionState | null>;
+    upsert(channelId: string, state: SessionState): Promise<void>;
+    setStatus(channelId: string, status: SessionState['status'], settlementTxHash?: string | null): Promise<void>;
+    close(channelId: string): Promise<void>;
+}
+
+export { RouteDockChannelStateError as R, type SessionStore as S, RouteDockClientVersionError as a, RouteDockDisputeError as b, RouteDockError as c, type RouteDockErrorCode as d, type RouteDockErrorOptions as e, RouteDockFacilitatorError as f, RouteDockManifestError as g, RouteDockManifestSunsetError as h, RouteDockManifestTimeoutError as i, RouteDockNetworkError as j, RouteDockNoSupportedModeError as k, RouteDockPolicyRejectError as l, RouteDockPolicyRejectedError as m, RouteDockRefundWindowError as n, RouteDockSessionError as o, RouteDockSignatureError as p, RouteDockTrustlineError as q, RouteDockVoucherMonotonicityError as r, SupabaseSessionStore as s, httpStatusToError as t, parseRetryAfterMs as u, wrapFetchError as w };