@defdone/annon 0.0.0-stage → 0.1.0-alpha.0

package/dist/browser/purchases.d.ts

@@ -0,0 +1,98 @@
+/** Durable SDK orchestration. Storage belongs to the embedding origin; no UI or wallet connector. */
+import { Annon, type AnnonOptions, type BuyOptions, type BuyRoute } from '../api/annon.js';
+import { AnnonError } from '../errors.js';
+import { type Deposit, OneClick, type PollOptions } from '../oneclick/oneclick.js';
+import { type EncryptedRecord, type RecoveryRecord } from '../pay/backup.js';
+import { type PurchaseRecord } from '../pay/purchase.js';
+import { type Store } from '../pay/store.js';
+import type { IdentityWallet } from '../wallet/wallet.js';
+import { type BrowserDownloadOptions } from './download.js';
+import type { BrowserPurchaseRecord, BrowserPurchaseState } from './record.js';
+export type { BrowserPurchaseRecord, BrowserPurchaseState } from './record.js';
+export type PurchaseSdk = Pick<Annon, 'buy' | 'accept' | 'open' | 'recover' | 'proveRecovery'>;
+export interface BrowserPurchaseStorage {
+    rawStore: Store<EncryptedRecord>;
+    backupSecret: Uint8Array;
+    writeBackup(name: string, encryptedFile: string): Promise<void>;
+    load(id: string): Promise<BrowserPurchaseRecord | null>;
+    save(expected: BrowserPurchaseRecord | null, next: BrowserPurchaseRecord): Promise<void>;
+    restorePurchase(record: PurchaseRecord): Promise<PurchaseRecord>;
+    list(): Promise<Pick<BrowserPurchaseRecord, 'id' | 'fileId' | 'route' | 'state'>[]>;
+    exportReceipt(id: string, secret: Uint8Array): Promise<string>;
+    importReceipt(file: string, secret: Uint8Array): Promise<string>;
+    recoveryArchives(purchaseId: string): Promise<RecoveryRecord[]>;
+}
+/** Local secret is random, persisted once with CAS. Clearing site storage removes local recovery. */
+export declare function browserPurchaseStorage(options?: {
+    name?: string;
+    factory?: IDBFactory;
+}): Promise<BrowserPurchaseStorage>;
+export interface PurchaseProgress {
+    id: string;
+    state: BrowserPurchaseState;
+    revision: number;
+    /** A safe status code; raw upstream details stay in the encrypted record. */
+    swapStatus?: string;
+    /** Unix seconds when another tab or a crashed owner releases this checkout. */
+    leaseWaitUntil?: number;
+}
+export type BrowserOpenOptions = Pick<BrowserDownloadOptions, 'fetch' | 'signal' | 'size' | 'onProgress' | 'retries' | 'settleTries' | 'wait'>;
+export interface ControllerOptions {
+    storage: BrowserPurchaseStorage;
+    sdk: PurchaseSdk;
+    id: string;
+    now?: () => number;
+}
+export interface PurchaseTermsReview {
+    /** Caller-chosen stable checkout id deduplicates double clicks and tabs. */
+    id: string;
+    fileId: string;
+    header: Uint8Array;
+    resourceUrl: string;
+    route: BuyRoute;
+    maxPrice: bigint;
+}
+/** Build the real SDK using the same encrypted storage and durable internal backups. */
+export declare function browserAnnon(storage: BrowserPurchaseStorage, options: Omit<AnnonOptions, 'rawStore' | 'backupSecret' | 'writeBackup'>): Annon;
+export declare class PurchaseLeaseBusy extends AnnonError {
+    readonly waitUntil: number;
+    readonly code = "lease_busy";
+    constructor(waitUntil: number);
+}
+export declare class BrowserPurchaseController {
+    private readonly options;
+    readonly storage: BrowserPurchaseStorage;
+    private readonly owner;
+    private readonly listeners;
+    constructor(options: ControllerOptions);
+    static create(options: Omit<ControllerOptions, 'id'>, terms: PurchaseTermsReview): Promise<BrowserPurchaseController>;
+    subscribe(listener: (event: PurchaseProgress) => void): () => void;
+    private read;
+    /** Safe to render. Full records are available only through the persistence adapter. */
+    snapshot(): Promise<PurchaseProgress & {
+        fileId: string;
+        route: BuyRoute;
+        resourceUrl: string;
+    }>;
+    private now;
+    private waiting;
+    private emit;
+    private busy;
+    /** Every asynchronous operation owns a renewable lease, with revision CAS on every write. */
+    private withLease;
+    private change;
+    start(options: Omit<BuyOptions, 'fileId' | 'header' | 'url' | 'route' | 'maxPrice' | 'onSaved' | 'beforeSave' | 'beforePayment' | 'onQuote'>): Promise<void>;
+    private deposit;
+    instructions(): Promise<Deposit | null>;
+    resume(options?: {
+        recovery?: IdentityWallet;
+    }): Promise<void>;
+    /** Polling remains available after the deposit cutoff to track late deposits and refunds. */
+    poll(options?: Omit<PollOptions, 'checkpoint' | 'memo' | 'onProgress'> & {
+        oneClick?: Pick<OneClick, 'poll'>;
+    }): Promise<void>;
+    recover(wallet: IdentityWallet): Promise<void>;
+    /** Open supplied ciphertext, or download with the saved grant. Returns plaintext only in memory. */
+    open(input?: Uint8Array | BrowserOpenOptions): ReturnType<Annon['open']>;
+    exportReceipt(secret: Uint8Array): Promise<string>;
+}