@1sat/wallet-toolbox 0.0.8 → 0.0.9

package/dist/sync/SyncManager.d.ts

@@ -0,0 +1,207 @@
+/**
+ * SyncManager - Syncs external transactions to the BRC-100 wallet.
+ *
+ * Split into two components for Chrome extension compatibility:
+ * - SyncFetcher: Calls SSE endpoint and enqueues txids (runs in UI context)
+ * - SyncProcessor: Processes queue and internalizes outputs (runs in service worker)
+ *
+ * This separation is necessary because EventSource (SSE) doesn't work reliably
+ * in Chrome extension service workers due to their ephemeral nature.
+ */
+import type { WalletInterface } from "@bsv/sdk";
+import type { OneSatServices } from "../services/OneSatServices";
+import type { SyncQueueStorage } from "./types";
+import { AddressManager } from "./AddressManager";
+import { Indexer } from "../indexers/types";
+export interface SyncFetcherOptions {
+    /** 1sat services for SSE stream */
+    services: OneSatServices;
+    /** Sync queue storage (IndexedDB) */
+    syncQueue: SyncQueueStorage;
+    /** Address manager for getting addresses to sync */
+    addressManager: AddressManager;
+}
+export interface SyncFetcherEvents {
+    "fetch:start": {
+        addresses: string[];
+    };
+    "fetch:queued": {
+        outpoint: string;
+        score: number;
+    };
+    "fetch:complete": {
+        queuedCount: number;
+    };
+    "fetch:error": {
+        message: string;
+    };
+}
+type SyncFetcherEventListener<K extends keyof SyncFetcherEvents> = (data: SyncFetcherEvents[K]) => void;
+/**
+ * SyncFetcher - Fetches outputs via SSE and enqueues them.
+ *
+ * Run this from the UI context (popup) when the wallet opens.
+ * It will fetch all new outputs since the last sync and add them to the queue.
+ */
+export declare class SyncFetcher {
+    private services;
+    private syncQueue;
+    private addressManager;
+    private unsubscribeStream;
+    private listeners;
+    constructor(options: SyncFetcherOptions);
+    on<K extends keyof SyncFetcherEvents>(event: K, listener: SyncFetcherEventListener<K>): void;
+    off<K extends keyof SyncFetcherEvents>(event: K, listener: SyncFetcherEventListener<K>): void;
+    private emit;
+    /**
+     * Fetch new outputs via SSE and enqueue them.
+     * Returns when the stream completes (all historical data fetched).
+     */
+    fetch(currentHeight: number): Promise<number>;
+    /**
+     * Stop the SSE stream if running.
+     */
+    stop(): void;
+    private handleSyncOutput;
+}
+export interface SyncProcessorOptions {
+    /** The BRC-100 wallet to internalize to */
+    wallet: WalletInterface;
+    /** 1sat services for transaction fetching */
+    services: OneSatServices;
+    /** Sync queue storage (IndexedDB) */
+    syncQueue: SyncQueueStorage;
+    /** Address manager for yours receive addresses */
+    addressManager: AddressManager;
+    /** Network: mainnet or testnet */
+    network: "mainnet" | "testnet";
+    /** Batch size for queue processing (default: 20) */
+    batchSize?: number;
+    /** Custom indexers (optional, uses defaults if not provided) */
+    indexers?: Indexer[];
+}
+export interface SyncProcessorEvents {
+    "process:start": {};
+    "process:progress": {
+        pending: number;
+        done: number;
+        failed: number;
+    };
+    "process:complete": {};
+    "process:error": {
+        message: string;
+    };
+    "process:parsed": {
+        internalizedCount: number;
+    };
+}
+type SyncProcessorEventListener<K extends keyof SyncProcessorEvents> = (data: SyncProcessorEvents[K]) => void;
+/**
+ * SyncProcessor - Processes the sync queue and internalizes outputs.
+ *
+ * Run this from the service worker. It will process items from the queue
+ * until the queue is empty or stop() is called.
+ */
+export declare class SyncProcessor {
+    private wallet;
+    private services;
+    private syncQueue;
+    private addressManager;
+    private network;
+    private batchSize;
+    private indexers;
+    private processorRunning;
+    private stopRequested;
+    private listeners;
+    constructor(options: SyncProcessorOptions);
+    on<K extends keyof SyncProcessorEvents>(event: K, listener: SyncProcessorEventListener<K>): void;
+    off<K extends keyof SyncProcessorEvents>(event: K, listener: SyncProcessorEventListener<K>): void;
+    private emit;
+    /**
+     * Start processing the queue.
+     * Processes until queue is empty or stop() is called.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop processing the queue.
+     */
+    stop(): void;
+    /**
+     * Check if processor is currently running.
+     */
+    isRunning(): boolean;
+    private processQueueLoop;
+    private processTxid;
+    private parseTransaction;
+    private buildInternalizeOutput;
+    private collectTags;
+}
+export interface SyncManagerOptions {
+    /** The BRC-100 wallet to internalize to */
+    wallet: WalletInterface;
+    /** 1sat services for SSE stream and transaction fetching */
+    services: OneSatServices;
+    /** Sync queue storage (IndexedDB or SQLite) */
+    syncQueue: SyncQueueStorage;
+    /** Address manager for yours receive addresses */
+    addressManager: AddressManager;
+    /** Network: mainnet or testnet */
+    network: "mainnet" | "testnet";
+    /** Batch size for queue processing (default: 20) */
+    batchSize?: number;
+    /** Custom indexers (optional, uses defaults if not provided) */
+    indexers?: Indexer[];
+}
+export interface SyncEvents {
+    "sync:start": {
+        addresses: string[];
+    };
+    "sync:progress": {
+        pending: number;
+        done: number;
+        failed: number;
+    };
+    "sync:complete": {};
+    "sync:error": {
+        message: string;
+    };
+    "sync:parsed": {
+        internalizedCount: number;
+    };
+}
+type SyncEventListener<K extends keyof SyncEvents> = (data: SyncEvents[K]) => void;
+/**
+ * SyncManager - Legacy class that combines SSE fetching and queue processing.
+ *
+ * @deprecated For Chrome extensions, use SyncFetcher (in UI) and SyncProcessor (in service worker)
+ * separately since EventSource doesn't work reliably in service workers.
+ *
+ * This class is kept for backwards compatibility and for environments where
+ * SSE works (e.g., Node.js, React Native).
+ */
+export declare class SyncManager {
+    private fetcher;
+    private processor;
+    private wallet;
+    private addressManager;
+    private listeners;
+    private fetchPromise;
+    constructor(options: SyncManagerOptions);
+    private setupEventForwarding;
+    on<K extends keyof SyncEvents>(event: K, listener: SyncEventListener<K>): void;
+    off<K extends keyof SyncEvents>(event: K, listener: SyncEventListener<K>): void;
+    private emit;
+    /**
+     * Start syncing - opens SSE stream and starts queue processor.
+     */
+    sync(): Promise<void>;
+    /**
+     * Stop syncing - closes SSE stream and stops queue processor.
+     */
+    stop(): void;
+    /**
+     * Check if sync is currently running.
+     */
+    isSyncing(): boolean;
+}
+export {};