@unicitylabs/sphere-sdk 0.14.0-dev.1 → 0.14.0-dev.2

package/dist/impl/wallet-api-v2/index.d.cts

@@ -0,0 +1,577 @@
+interface HttpResponseLike {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly headers?: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+interface HttpRequestInit {
+    method: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+}
+type FetchLike = (url: string, init?: HttpRequestInit) => Promise<HttpResponseLike>;
+declare class WalletApiHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Milliseconds, parsed from a Retry-After header when present. */
+    readonly retryAfter?: number;
+    constructor(status: number, code: string, message: string, retryAfter?: number);
+}
+declare function isWalletApiHttpError(err: unknown, status?: number): err is WalletApiHttpError;
+interface WalletApiHttpConfig {
+    baseUrl: string;
+    fetchFn: FetchLike;
+    /** Bearer source; `null` sends the request unauthenticated. */
+    getToken: () => string | null;
+}
+interface RequestOptions {
+    /** Default true; auth endpoints opt out so a stale bearer is never attached. */
+    auth?: boolean;
+}
+interface WalletApiHttp {
+    readonly baseUrl: string;
+    request(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<unknown>;
+    /** Direct fetch for presigned S3 URLs — no base URL, no bearer. */
+    fetchRaw(url: string, init: HttpRequestInit): Promise<HttpResponseLike>;
+}
+/** ARCHITECTURE §4 transport rule: non-loopback MUST be https. Returns the URL without a trailing slash. */
+declare function assertSecureBaseUrl(baseUrl: string): string;
+declare function createWalletApiHttp(config: WalletApiHttpConfig): WalletApiHttp;
+
+interface AuthChallengeWire {
+    nonce: string;
+    challenge: string;
+    expiresAt: string;
+}
+interface AuthTokensWire {
+    jwt: string;
+    refreshToken: string;
+}
+interface AssetWire {
+    coinId: string;
+    amount: string;
+}
+interface InventoryItemWire {
+    tokenId: string;
+    status: 'active' | 'removed';
+    seq: number;
+    stateHash: string;
+    assets?: AssetWire[];
+}
+interface InventoryPageWire {
+    cursor: number;
+    syncEpoch: number;
+    more: boolean;
+    items: InventoryItemWire[];
+}
+interface BalanceWire {
+    coinId: string;
+    total: string;
+    tokenCount: number;
+}
+interface BlobUrlWire {
+    tokenId: string;
+    getUrl: string;
+}
+interface UploadUrlWire {
+    sha256: string;
+    key: string;
+    putUrl: string;
+}
+interface ApplyDeltaWire {
+    cursor: number;
+    syncEpoch: number;
+}
+interface IntentWire {
+    transferId: string;
+    payload: string;
+    status: 'open' | 'aborted';
+    createdAt: string;
+}
+interface ProgressRecordWire {
+    opIndex: number;
+    payload: string;
+    createdAt: string;
+}
+interface MailboxDepositEntry {
+    recipientPubkey: string;
+    key: string;
+    transferId: string;
+    tokenId: string;
+    stateHash: string;
+    memo?: string;
+}
+interface MailboxEntryWire {
+    entryId: string;
+    seq: number;
+    status: string;
+    transferId: string;
+    tokenId: string;
+    assets: AssetWire[];
+    senderPubkey: string;
+    memo?: string;
+    createdAt: string;
+    getUrl?: string;
+    blobCollected?: boolean;
+}
+interface MailboxPageWire {
+    readPointer: number;
+    cursor: number;
+    syncEpoch: number;
+    more: boolean;
+    entries: MailboxEntryWire[];
+}
+interface ClaimResultWire {
+    claimed: string[];
+    alreadyClaimed: {
+        entryId: string;
+        intoInventory: boolean;
+    }[];
+    failed: {
+        entryId: string;
+        code: string;
+    }[];
+}
+type MailboxRejectReason = 'invalid' | 'not-owned' | 'storage-rejected' | 'other';
+interface HistoryRecordWire {
+    dedupKey: string;
+    id: string;
+    type: 'SENT' | 'RECEIVED' | 'MINT';
+    assets: AssetWire[];
+    ts: string;
+    transferId?: string;
+    tokenId?: string;
+    counterpartyPubkey?: string;
+    counterpartyNametag?: string;
+    memo?: string;
+}
+interface HistoryPageWire {
+    records: HistoryRecordWire[];
+    more: boolean;
+    cursor: string | null;
+    syncEpoch: number;
+}
+type PaymentRequestWireStatus = 'open' | 'paid' | 'declined' | 'expired';
+interface PaymentRequestWire {
+    id: string;
+    seq: number;
+    fromPubkey: string;
+    toPubkey: string;
+    assets: AssetWire[];
+    memo?: string;
+    status: PaymentRequestWireStatus;
+    transferId: string | null;
+    createdAt: string;
+    expiresAt?: string;
+}
+interface PaymentRequestsPageWire {
+    requests: PaymentRequestWire[];
+    more: boolean;
+    cursor: number | string | null;
+    syncEpoch: number;
+}
+type ListPaymentRequestsParams = {
+    role: 'incoming';
+    status?: PaymentRequestWireStatus;
+    since?: number;
+} | {
+    role: 'outgoing';
+    status?: PaymentRequestWireStatus;
+    before?: string;
+};
+type RespondPaymentRequestInput = {
+    action: 'paid';
+    transferId: string;
+} | {
+    action: 'declined';
+};
+declare class WalletApiV2Client {
+    private readonly http;
+    constructor(http: WalletApiHttp);
+    get baseUrl(): string;
+    authChallenge(pubkey: string): Promise<AuthChallengeWire>;
+    authVerify(input: {
+        nonce: string;
+        signature: string;
+        deviceId: string;
+    }): Promise<AuthTokensWire>;
+    authRefresh(refreshToken: string): Promise<AuthTokensWire>;
+    authLogout(): Promise<void>;
+    listInventory(since?: number): Promise<InventoryPageWire>;
+    balances(): Promise<BalanceWire[]>;
+    blobUrls(tokenIds: string[]): Promise<BlobUrlWire[]>;
+    uploadUrls(blobs: {
+        sha256: string;
+        size: number;
+    }[]): Promise<UploadUrlWire[]>;
+    apply(delta: {
+        transferId: string;
+        spent: string[];
+        added: {
+            tokenId: string;
+            key: string;
+        }[];
+    }): Promise<ApplyDeltaWire>;
+    fetchBlob(getUrl: string): Promise<Uint8Array>;
+    /**
+     * PUT to a presigned S3 URL. `x-amz-checksum-sha256` (base64) and
+     * `If-None-Match: *` are SIGNED headers — sent verbatim. S3 412 = the
+     * identical blob already exists = success.
+     */
+    uploadBlob(putUrl: string, bytes: Uint8Array): Promise<void>;
+    putIntent(transferId: string, payloadEnvelope: string, requiresSeedClose?: boolean): Promise<void>;
+    listIntents(status?: 'open' | 'aborted'): Promise<IntentWire[]>;
+    abortIntent(transferId: string): Promise<void>;
+    completeIntent(transferId: string, signature?: string): Promise<void>;
+    postProgress(transferId: string, opIndex: number, payloadEnvelope: string, signature: string): Promise<ProgressRecordWire>;
+    getProgress(transferId: string): Promise<ProgressRecordWire[]>;
+    deposit(entry: MailboxDepositEntry): Promise<string>;
+    depositBatch(entries: MailboxDepositEntry[]): Promise<{
+        entryId: string;
+        seq: number;
+    }[]>;
+    listMailbox(since?: number): Promise<MailboxPageWire>;
+    claim(entryIds: string[], intoInventory: boolean): Promise<ClaimResultWire>;
+    reject(entryIds: string[], reason?: MailboxRejectReason, detail?: string): Promise<string[]>;
+    postHistory(records: HistoryRecordWire[]): Promise<{
+        inserted: number;
+        deduped: number;
+    }>;
+    listHistory(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<HistoryPageWire>;
+    createPaymentRequest(input: {
+        toPubkey: string;
+        assets: AssetWire[];
+        memo?: string;
+        expiresAt?: string;
+    }): Promise<PaymentRequestWire>;
+    listPaymentRequests(params: ListPaymentRequestsParams): Promise<PaymentRequestsPageWire>;
+    respondPaymentRequest(id: string, response: RespondPaymentRequestInput): Promise<PaymentRequestWire>;
+    wsTicket(): Promise<string>;
+}
+
+/**
+ * token-engine/engine.ts — the FROZEN public port (ITokenEngine) + its config.
+ *
+ * This is the contract both migration tracks build against. It is sphere-domain
+ * only (see types.ts). The granular, SDK-typed steps (buildMint, submit,
+ * awaitProof, certify, …) are an INTERNAL concern of the real adapter and are
+ * intentionally NOT part of this public interface.
+ */
+
+/**
+ * Durable, any-device store for a split's burn checkpoint (sdk-changes E.4, sphere-sdk#501
+ * option b). The engine passes opaque PLAINTEXT bytes; a transport adapter (the wallet-api
+ * provider) is responsible for AAD-encryption and the wallet-api §16 intent-progress round-trip.
+ *
+ * The store is the resume seed for the one split input the engine cannot re-derive — the burn's
+ * aggregator-issued inclusion proof — so the mint justification is rebuilt from stored bytes, not
+ * a refetch (the aggregator regenerates proofs per request).
+ */
+interface SplitCheckpointStore {
+    /**
+     * Insert-once, first-write-wins. MUST resolve only AFTER the store acked durability, and MUST
+     * resolve with the AUTHORITATIVE stored bytes — the caller's own on a fresh write, or the FIRST
+     * writer's when the slot `(transferId, opIndex)` was already taken (the caller adopts those and
+     * mints from them, so concurrent resumers converge on one burn proof).
+     */
+    put(transferId: string, opIndex: number, bytes: Uint8Array): Promise<Uint8Array>;
+    /** The stored bytes for the slot, or `null` when none exists. */
+    get(transferId: string, opIndex: number): Promise<Uint8Array | null>;
+}
+
+interface ScopedKV {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+
+/**
+ * The JWT generation cell (#692 F8/F14). Every write is a compare-and-swap on
+ * a generation captured at operation start — the CAS lives INSIDE the setter,
+ * so a continuation returning from an await can never clobber a newer session.
+ */
+declare class JwtGenerationCell {
+    private gen;
+    private jwt;
+    get generation(): number;
+    token(): string | null;
+    install(generation: number, jwt: string): boolean;
+    /** authGone(G) is a no-op when the cell moved to G+1 (F14). */
+    clearIfCurrent(generation: number): boolean;
+    dropIfMatches(generation: number, jwt: string): void;
+    bump(): number;
+}
+type WakeStream = 'inventory' | 'mailbox' | 'payment_requests';
+declare const WAKE_STREAMS: readonly WakeStream[];
+type ConnectionStatus = 'connected' | 'degraded' | 'offline';
+interface SessionSigner {
+    readonly pubkey: string;
+    readonly network: string;
+    sign(message: string): string | Promise<string>;
+}
+interface WebSocketLike {
+    onopen: (() => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: {
+        code?: number;
+    }) => void) | null;
+    onerror: ((err: unknown) => void) | null;
+    close(code?: number, reason?: string): void;
+}
+type WebSocketFactory = (url: string) => WebSocketLike;
+interface SessionTimers {
+    setTimeout(cb: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    setInterval(cb: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+interface SessionTiming {
+    pullIntervalMs: number;
+    reconnectBaseMs: number;
+    reconnectCapMs: number;
+    heartbeatTimeoutMs: number;
+    offlineAfterFailures: number;
+}
+declare const DEFAULT_SESSION_TIMING: SessionTiming;
+interface WalletApiSessionDeps {
+    client: WalletApiV2Client;
+    cell: JwtGenerationCell;
+    signer: SessionSigner;
+    deviceId: string;
+    kv: ScopedKV;
+    webSocketFactory: WebSocketFactory;
+    emitStatus: (status: ConnectionStatus) => void;
+    /** Runs the syncEpoch re-seed protocol BEFORE any stream resumes. */
+    onEpochChange: (epoch: string) => Promise<void>;
+    timing?: Partial<SessionTiming>;
+    timers?: SessionTimers;
+    random?: () => number;
+}
+declare function refreshTokenKey(deviceId: string): string;
+declare class WalletApiSession {
+    private readonly deps;
+    private readonly timing;
+    private readonly timers;
+    private readonly random;
+    private readonly refreshKey;
+    private authFlight;
+    private epochLatch;
+    private reseedChain;
+    private reseedsPending;
+    private readonly handlers;
+    private socket;
+    private started;
+    private stopped;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private pullTimers;
+    private lastStatus;
+    constructor(deps: WalletApiSessionDeps);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    token(): string | null;
+    /** Identity switch / lock / logout: supersede every in-flight auth continuation. */
+    invalidate(): void;
+    ensureAuthenticated(): Promise<string>;
+    /** Run an authenticated op; one 401 → single-flight re-auth → one retry. */
+    withAuth<T>(op: (jwt: string) => Promise<T>): Promise<T>;
+    private runAuthSingleFlight;
+    private authenticate;
+    private tryRefresh;
+    private challengeSignIn;
+    noteEpoch(epoch: string): void;
+    private runReseed;
+    subscribeStream(stream: WakeStream, handler: () => void): () => void;
+    private dispatch;
+    private nudgeAllStreams;
+    private startPullTimers;
+    status(): ConnectionStatus;
+    private emitStatus;
+    private connect;
+    private openSocket;
+    private handleOpen;
+    private handleMessage;
+    private handleClose;
+    private scheduleReconnect;
+    private armHeartbeat;
+    private clearHeartbeat;
+}
+
+interface InventoryAsset {
+    coinId: string;
+    amount: string;
+}
+interface InventoryItem {
+    tokenId: string;
+    status: 'active' | 'removed';
+    seq: number;
+    stateHash: string;
+    assets?: InventoryAsset[];
+}
+interface InventoryPage {
+    cursor: number;
+    syncEpoch: string;
+    more: boolean;
+    items: InventoryItem[];
+}
+interface ApplyDeltaResult {
+    cursor: number;
+    syncEpoch: string;
+}
+interface StoragePort {
+    listInventory(since?: number): Promise<InventoryPage>;
+    balances(): Promise<{
+        coinId: string;
+        total: string;
+        tokenCount: number;
+    }[]>;
+    getBlobs(tokenIds: string[]): Promise<Map<string, Uint8Array>>;
+    uploadBlobs(blobs: {
+        sha256: string;
+        bytes: Uint8Array;
+    }[]): Promise<Map<string, string>>;
+    applyDelta(delta: {
+        transferId: string;
+        spent: string[];
+        added: {
+            tokenId: string;
+            key: string;
+        }[];
+    }): Promise<ApplyDeltaResult>;
+}
+interface DeliveryReceipt {
+    deliveryId: string;
+}
+interface IncomingDelivery {
+    deliveryId: string;
+    transferId?: string;
+    senderPubkey?: string;
+    senderNametag?: string;
+    memo?: string;
+    fetchBlob(): Promise<Uint8Array>;
+    cursor: string;
+}
+interface DeliverOptions {
+    transferId: string;
+    memo?: string;
+    senderNametag?: string;
+}
+interface DeliveryPort {
+    bindDeliveryKeys(derive: (blob: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>): void;
+    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
+    deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
+    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    onWake?(cb: () => void): () => void;
+}
+
+type StoragePortClient = Pick<WalletApiV2Client, 'listInventory' | 'balances' | 'blobUrls' | 'uploadUrls' | 'apply' | 'fetchBlob' | 'uploadBlob'>;
+declare class WalletApiStoragePort implements StoragePort {
+    private readonly client;
+    constructor(client: StoragePortClient);
+    listInventory(since?: number): Promise<InventoryPage>;
+    balances(): Promise<{
+        coinId: string;
+        total: string;
+        tokenCount: number;
+    }[]>;
+    getBlobs(tokenIds: string[]): Promise<Map<string, Uint8Array>>;
+    uploadBlobs(blobs: {
+        sha256: string;
+        bytes: Uint8Array;
+    }[]): Promise<Map<string, string>>;
+    applyDelta(delta: {
+        transferId: string;
+        spent: string[];
+        added: {
+            tokenId: string;
+            key: string;
+        }[];
+    }): Promise<ApplyDeltaResult>;
+}
+
+type DeliveryPortClient = Pick<WalletApiV2Client, 'uploadUrls' | 'uploadBlob' | 'fetchBlob' | 'deposit' | 'depositBatch' | 'listMailbox' | 'claim' | 'reject'>;
+type DeliveryCustody = 'inventory' | 'external';
+interface WakeSource {
+    subscribeStream(stream: 'inventory' | 'mailbox' | 'payment_requests', handler: () => void): () => void;
+}
+interface DeliveryIdentity {
+    privateKey: string;
+    chainPubkey: string;
+    nametag?: string;
+}
+interface WalletApiDeliveryPortConfig {
+    client: DeliveryPortClient;
+    kv: ScopedKV;
+    identity: DeliveryIdentity;
+    /** Composition-time custody (S7) — NEVER a per-call flag. */
+    custody: DeliveryCustody;
+    wake?: WakeSource;
+    deliveryKeys?: (blob: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>;
+}
+declare class WalletApiDeliveryPort implements DeliveryPort {
+    readonly custody: DeliveryCustody;
+    private readonly client;
+    private readonly kv;
+    private readonly identity;
+    private readonly wake;
+    private deriveFn;
+    private seenChain;
+    constructor(config: WalletApiDeliveryPortConfig);
+    bindDeliveryKeys(derive: (blob: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>): void;
+    private deriveKeys;
+    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
+    deliverBatch(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
+    private prepare;
+    private buildEnvelope;
+    private upload;
+    private depositAll;
+    private depositOne;
+    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    private toIncoming;
+    private openEnvelope;
+    private fetchVerified;
+    ack(deliveryId: string, disposition: 'claimed' | 'rejected', reason?: 'invalid' | 'not-owned' | 'storage-rejected' | 'other'): Promise<void>;
+    onWake(cb: () => void): () => void;
+    private readSeen;
+    private addSeen;
+}
+
+type CheckpointClient = Pick<WalletApiV2Client, 'postProgress' | 'getProgress'>;
+interface WalletApiSplitCheckpointStoreConfig {
+    client: CheckpointClient;
+    kv: ScopedKV;
+    /** S6 self-scoped field key (`deriveFieldEncryptionKey`). */
+    fieldKey: Uint8Array;
+    /** Signs the wallet-api.progress.v1 message with the chain key. */
+    signProgress: (message: string) => string | Promise<string>;
+}
+declare class WalletApiSplitCheckpointStore implements SplitCheckpointStore {
+    private readonly config;
+    constructor(config: WalletApiSplitCheckpointStoreConfig);
+    private cacheKey;
+    private aad;
+    put(transferId: string, opIndex: number, bytes: Uint8Array): Promise<Uint8Array>;
+    get(transferId: string, opIndex: number): Promise<Uint8Array | null>;
+    private open;
+}
+
+export { type ConnectionStatus, DEFAULT_SESSION_TIMING, type FetchLike, JwtGenerationCell, type SessionSigner, type SessionTimers, type SessionTiming, WAKE_STREAMS, type WakeStream, WalletApiDeliveryPort, type WalletApiHttp, type WalletApiHttpConfig, WalletApiHttpError, WalletApiSession, type WalletApiSessionDeps, WalletApiSplitCheckpointStore, WalletApiStoragePort, WalletApiV2Client, type WebSocketFactory, type WebSocketLike, assertSecureBaseUrl, createWalletApiHttp, isWalletApiHttpError, refreshTokenKey };