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

package/dist/api/annon-types.d.ts

@@ -0,0 +1,108 @@
+/** Options and results of the Annon client: construction, sell and buy. */
+import type { SellData } from '../envelope/replay.js';
+import type { Deposit, OneClick, OneClickQuote, Origin } from '../oneclick/oneclick.js';
+import type { EncryptedRecord } from '../pay/backup.js';
+import type { PurchaseRecord } from '../pay/purchase.js';
+import type { SplitCall } from '../pay/split.js';
+import type { Store } from '../pay/store.js';
+import type { PaymentRequired } from '../pay/x402.js';
+import type { BaseSponsorship } from '../relay/capabilities.js';
+import type { ProtocolFee } from '../relay/fees.js';
+import type { BuyRoute } from '../routes.js';
+import type { Identity } from '../settle-near/identity.js';
+import type { Terms } from '../settle-near/terms.js';
+import type { IdentityWallet, NearWallet } from '../wallet/wallet.js';
+import type { ShareHosting, ShareOptions } from './sharing.js';
+export interface AnnonOptions {
+    relayer?: string;
+    fetch?: typeof fetch;
+    nearRpc: string;
+    baseRpc: string;
+    contractId: string;
+    network: string;
+    rawStore: Store<EncryptedRecord>;
+    backupSecret: Uint8Array;
+    /** Write the encrypted file durably (Node file, download, or an app's backup destination). */
+    writeBackup(name: string, encryptedFile: string): Promise<void>;
+    /** A transaction transport. Wait for final execution and return its decoded result/outcome. NEAR wallets can call directly when omitted. */
+    send?: (method: string, args: object, wallet?: NearWallet) => Promise<unknown>;
+    mpcKey?: string;
+    now?: () => number;
+    /** A relayer capability reader; only sponsored registrations apply its fee. */
+    sponsorship?: () => Promise<{
+        fee: ProtocolFee;
+    }>;
+    /** Maximum advertised fee, in USDC base units plus basis points. */
+    maxProtocolFee?: Pick<ProtocolFee, 'fixed' | 'bps'>;
+}
+export interface SellOptions<T extends SellData = Uint8Array> {
+    /** Hosted jobs use the shared reservation sequence; publish remains a post-registration callback. */
+    hosting?: ShareHosting & Pick<ShareOptions, 'listingStorage' | 'confirmBackup'>;
+    /** Attached yoctoNEAR for a self-funded listing. */
+    storageBudget?: bigint;
+    /** Called before registration or Base split transactions. */
+    onSplit?: (near: Terms['near'], fee?: ProtocolFee, aboveMaximum?: boolean) => void | Promise<void>;
+    data: T;
+    name: string;
+    mime: string;
+    seller: IdentityWallet;
+    near: {
+        price: string;
+        recipients: {
+            identity: Identity;
+            bps: number;
+        }[];
+        remainder: Identity;
+    };
+    base?: {
+        price: string;
+        kind?: 'push' | 'pull';
+        sendTransaction: (call: SplitCall) => Promise<void>;
+    };
+    moderator?: string;
+    fileId?: string;
+    previewLen?: number;
+    /** Store/host the encrypted file and its public header. Consume streamed files fully before resolving. Called after header authorization. */
+    publish: (file: {
+        file: import('../envelope/replay.js').SellFile<T>;
+        header: Uint8Array;
+        terms: Terms;
+    }) => Promise<void>;
+}
+export interface BuyOptions {
+    /** Explicit selection never falls back to another payment route. */
+    route?: BuyRoute;
+    baseUnlock?: 'relayer' | 'self';
+    baseSponsorship?: BaseSponsorship;
+    /** Persist the workflow association before an SDK write can become uncertain. */
+    beforeSave?: (record: PurchaseRecord) => Promise<void>;
+    /** Awaited after each durable purchase and backup write, before external effects. */
+    onSaved?: (record: PurchaseRecord) => Promise<void>;
+    /** Last durable UI checkpoint before payment submission or releasing deposit instructions. */
+    beforePayment?: (record: PurchaseRecord) => Promise<void>;
+    fileId: string;
+    header: Uint8Array;
+    recovery: IdentityWallet;
+    refund: Identity;
+    payer?: IdentityWallet;
+    maxPrice: bigint;
+    moderators?: readonly string[];
+    paymentRequired?: PaymentRequired;
+    url?: string;
+    oneClick?: Pick<OneClick, 'quote'>;
+    origin?: Origin;
+    /** Review the live 1Click quote after its encrypted backup is saved, before recovery proof and deposit instructions. */
+    onQuote?: (quote: OneClickQuote) => void | Promise<void>;
+    /** Submit the saved Base payload to the host/facilitator. Return only after its request completes. */
+    submitBase?: (header: string) => Promise<void>;
+}
+export interface Bought {
+    route: BuyRoute;
+    record: PurchaseRecord;
+    instructions?: Deposit;
+    uncertain?: {
+        purchaseId: string;
+        txHash: string;
+    };
+    payment?: string;
+}

package/dist/api/annon-types.js

@@ -0,0 +1,2 @@
+/** Options and results of the Annon client: construction, sell and buy. */
+export {};

package/dist/api/annon.d.ts

@@ -0,0 +1,117 @@
+import { AnnonError } from '../errors.js';
+import { HostedSelling, type ShareHosting, type ShareOptions } from './sharing.js';
+import { type FileMeta } from '../envelope/pay2.js';
+import { type ReplayableSource, type SellData, type Spool } from '../envelope/replay.js';
+import { type RecoveryRecord } from '../pay/backup.js';
+import { type PurchaseRecord } from '../pay/purchase.js';
+import type { Store } from '../pay/store.js';
+import { type Terms } from '../settle-near/terms.js';
+import type { IdentityWallet, NearWallet } from '../wallet/wallet.js';
+import type { AnnonOptions, Bought, BuyOptions, SellOptions } from './annon-types.js';
+export type { BuyRoute } from '../routes.js';
+export type { AnnonOptions, Bought, BuyOptions, SellOptions } from './annon-types.js';
+export declare class SellError extends AnnonError {
+    readonly fileId: string;
+    readonly txHash?: string;
+    readonly retryAfterSeconds?: number;
+    constructor(fileId: string, options?: ErrorOptions);
+}
+export declare class Annon {
+    private readonly o;
+    readonly store: Store<PurchaseRecord>;
+    readonly hosted: HostedSelling;
+    private readonly sellerKeys;
+    private readonly sells;
+    private readonly recoveries;
+    private readonly selfUnlockWallets;
+    private readonly unlocked;
+    constructor(o: AnnonOptions);
+    private withBackup;
+    private now;
+    private auth;
+    private call;
+    /** Allocate file storage directly with NEAR, or request a seller-signed sponsored top-up. */
+    fund(fileId: string, amount: bigint, seller: IdentityWallet, options?: {
+        nonce?: string;
+        deadline?: number;
+    }): Promise<unknown>;
+    private answer;
+    private file;
+    /** Hosted sale with a pending backup saved before the first approval. */
+    private startShare;
+    share(options: ShareOptions): Promise<import("./sharing-types.js").Shared>;
+    resumeShare(options: Pick<ShareOptions, 'data' | 'seller' | 'hosting'> & {
+        fileId: string;
+    }): Promise<import("./sharing-types.js").Shared>;
+    private hostedFile;
+    sell<T extends SellData>(o: SellOptions<T>): Promise<{
+        file: import("../envelope/replay.js").SellFile<T>;
+        header: Uint8Array<ArrayBuffer>;
+        baseSplit?: {
+            address: string;
+            kind: "push" | "pull";
+            salt: string;
+        };
+        terms: Terms;
+    }>;
+    /** Resume with the original plaintext; the saved file key reproduces the registered cipher hash. */
+    resumeSell<T extends SellData>(o: {
+        fileId: string;
+        data: T;
+        seller: IdentityWallet;
+        publish: SellOptions<T>['publish'];
+        hosting?: ShareHosting;
+    }): Promise<{
+        file: import("../envelope/replay.js").SellFile<T>;
+        header: Uint8Array<ArrayBuffer>;
+        baseSplit?: {
+            address: string;
+            kind: "push" | "pull";
+            salt: string;
+        };
+        terms: Terms;
+    }>;
+    /** A new seller one-time key is backed up before the single-use reopen_seller call. */
+    reopenSeller(o: {
+        fileId: string;
+        seller: IdentityWallet;
+    }): Promise<Uint8Array>;
+    private finishSell;
+    buy(o: BuyOptions): Promise<Bought>;
+    /** Reprove the same saved purchase after reload, without preparing or submitting a payment. */
+    proveRecovery(record: PurchaseRecord, wallet: IdentityWallet): Promise<PurchaseRecord>;
+    /** Resume a paid Base purchase before any host download, which requires a final grant. */
+    accept(record: PurchaseRecord | undefined, id?: string | undefined, options?: {
+        unlockWallet?: NearWallet;
+    }): Promise<boolean>;
+    open(o: {
+        file: Uint8Array;
+        record?: PurchaseRecord;
+        recovery?: RecoveryRecord;
+    }): Promise<{
+        meta: FileMeta;
+        data: Uint8Array;
+    }>;
+    /** Replay PAY2 to a provisional sink; resolve after every check. Single-use streams require a ciphertext spool. */
+    openTo(o: {
+        file: ReplayableSource | ReadableStream<Uint8Array>;
+        sink: WritableStream<Uint8Array>;
+        spool?: Spool;
+        record?: PurchaseRecord;
+        recovery?: RecoveryRecord;
+    }): Promise<{
+        meta: FileMeta;
+    }>;
+    private openSource;
+    recover(o: {
+        wallet: IdentityWallet;
+        purchaseId?: string;
+        limit?: number;
+        /** Batch errors are isolated; an explicit purchase still rejects on failure. */
+        onError?: (purchaseId: string, error: unknown) => void;
+    }): Promise<RecoveryRecord[]>;
+    stop(o: {
+        fileId: string;
+        seller: IdentityWallet;
+    }): Promise<void>;
+}