@1sat/wallet-toolbox 0.0.1 → 0.0.3

package/README.md

@@ -186,6 +186,26 @@ const services = new OneSatServices("main", "https://ordfs.network");
 | `getBsv21TokenByTxid(tokenId, txid)` | Get BSV21 token data |
 | `getBsv21TokenDetails(tokenId)` | Get BSV21 token metadata (cached) |
 
+#### Available Clients
+
+OneSatServices exposes specialized API clients as public properties:
+
+| Client | Property | Purpose |
+|--------|----------|---------|
+| Chaintracks | `.chaintracks` | Block headers and chain tracking |
+| BEEF | `.beef` | Raw transactions and BEEF proofs |
+| Arcade | `.arcade` | Transaction broadcasting |
+| TXO | `.txo` | Transaction output queries |
+| Owner | `.owner` | Address queries and SSE sync |
+| OrdFS | `.ordfs` | Content and inscription metadata |
+| BSV21 | `.bsv21` | BSV21 token data |
+
+```typescript
+const services = new OneSatServices("main");
+const rawTx = await services.beef.getRawTx(txid);
+const metadata = await services.ordfs.getMetadata(outpoint);
+```
+
 ---
 
 ### ReadOnlySigner
@@ -242,25 +262,6 @@ Tags enable filtered queries via `listOutputs({ tags })`. Tags are only added fo
 
 ---
 
-### TransactionParser
-
-Runs indexers over transactions to extract basket/tags for wallet-toolbox storage.
-
-```typescript
-import { TransactionParser, FundIndexer, OriginIndexer } from "@1sat/wallet-toolbox";
-
-const parser = new TransactionParser(
-  [new FundIndexer(owners, "mainnet"), new OriginIndexer(owners, "mainnet", services)],
-  owners,
-  services
-);
-
-const result = await parser.parse(transaction, true);
-// result.outputs: ParsedOutput[] with vout, basket, tags, customInstructions
-```
-
----
-
 ## Project Status
 
 ### Completed
@@ -269,12 +270,12 @@ const result = await parser.parse(transaction, true);
 - [x] Read-only mode via public key
 - [x] OneSatServices (WalletServices implementation)
 - [x] All indexers migrated from yours-wallet
-- [x] TransactionParser for indexed ingestion
 - [x] `ingestTransaction()` method
 - [x] `syncAddress()` / `syncAll()` synchronization
 - [x] Event system for sync progress
 - [x] `broadcast()` method
 - [x] `getChainTracker()` implementation
+- [x] Modular API client architecture
 
 ### TODO
 
@@ -287,7 +288,6 @@ const result = await parser.parse(transaction, true);
   - [ ] `getScriptHashHistory()`
   - [ ] `hashToHeader()`
   - [ ] `nLockTimeIsFinal()`
-- [ ] Improve basket/tag extraction in TransactionParser
 - [ ] Tests
 - [ ] Integration with yours-wallet
 

package/dist/OneSatWallet.d.ts

@@ -1,37 +1,37 @@
-import { Wallet, WalletStorageManager } from "@bsv/wallet-toolbox/mobile";
+import { type PrivateKey, Transaction } from "@bsv/sdk";
+import { Wallet, type WalletStorageManager } from "@bsv/wallet-toolbox/mobile";
 import type { Chain } from "@bsv/wallet-toolbox/mobile/out/src/sdk/types";
-import { PrivateKey, Transaction, type InternalizeActionResult } from "@bsv/sdk";
-export interface SyncStartEvent {
-    address: string;
-    fromScore: number;
-}
-export interface SyncProgressEvent {
-    address: string;
-    processed: number;
-    remaining: number;
-    currentScore: number;
-    done: boolean;
-}
-export interface SyncTxEvent {
-    address: string;
-    txid: string;
-    type: "output" | "spend";
-}
-export interface SyncErrorEvent {
-    address: string;
-    error: Error;
-}
-export interface SyncCompleteEvent {
-    address: string;
-    processed: number;
-    finalScore: number;
+import { Outpoint } from "./indexers/Outpoint";
+import type { Indexer, ParseContext, Txo } from "./indexers/types";
+import { OneSatServices } from "./services/OneSatServices";
+import type { SyncQueueStorage } from "./sync/types";
+/**
+ * Result of ingestTransaction including parse context for debugging
+ */
+export interface IngestResult {
+    parseContext: ParseContext;
+    internalizedCount: number;
 }
+/**
+ * Events emitted by OneSatWallet during sync operations
+ */
 export interface OneSatWalletEvents {
-    "sync:start": SyncStartEvent;
-    "sync:progress": SyncProgressEvent;
-    "sync:tx": SyncTxEvent;
-    "sync:error": SyncErrorEvent;
-    "sync:complete": SyncCompleteEvent;
+    /** Sync started */
+    "sync:start": {
+        addresses: string[];
+    };
+    /** Sync progress update */
+    "sync:progress": {
+        pending: number;
+        done: number;
+        failed: number;
+    };
+    /** Sync complete (queue empty and stream done) */
+    "sync:complete": Record<string, never>;
+    /** Sync error */
+    "sync:error": {
+        message: string;
+    };
 }
 type EventCallback<T> = (event: T) => void;
 export interface OneSatWalletArgs {
@@ -52,13 +52,27 @@ export interface OneSatWalletArgs {
      */
     owners?: Set<string>;
     /**
-     * Custom OrdFS server URL (default: https://ordfs.network)
+     * Indexers to use for parsing transactions.
+     * If not provided, default indexers will be used.
      */
-    ordfsUrl?: string;
+    indexers?: Indexer[];
     /**
-     * Custom 1Sat indexer URL (default: based on chain - mainnet or testnet)
+     * Custom 1Sat API URL (default: based on chain - mainnet or testnet)
      */
     onesatUrl?: string;
+    /**
+     * Automatically start syncing all owner addresses on construction.
+     */
+    autoSync?: boolean;
+    /**
+     * Sync queue storage for background processing.
+     * If provided, enables queue-based sync via sync() method.
+     */
+    syncQueue?: SyncQueueStorage;
+    /**
+     * Batch size for queue processing (default: 20).
+     */
+    syncBatchSize?: number;
 }
 /**
  * OneSatWallet extends the BRC-100 Wallet with 1Sat-specific indexing and services.
@@ -69,64 +83,205 @@ export interface OneSatWalletArgs {
  */
 export declare class OneSatWallet extends Wallet {
     private readonly isReadOnly;
-    private readonly parser;
-    private readonly oneSatServices;
+    private readonly indexers;
+    readonly services: OneSatServices;
     private owners;
     private listeners;
+    private syncQueue;
+    private syncBatchSize;
+    private syncRunning;
+    private syncStopRequested;
+    private activeQueueSync;
+    private sseStreamActive;
+    private sseUnsubscribe;
+    private processorActive;
+    private processorStopRequested;
+    private streamDone;
     constructor(args: OneSatWalletArgs);
     /**
      * Returns true if this wallet was created with only a public key.
      * Read-only wallets can query but not sign transactions.
      */
     get readOnly(): boolean;
+    /**
+     * Subscribe to wallet events
+     */
+    on<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
+    /**
+     * Unsubscribe from wallet events
+     */
+    off<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
+    /**
+     * Emit a wallet event
+     */
+    private emit;
     /**
      * Add an address to the set of owned addresses.
      * Outputs to these addresses will be indexed.
      */
     addOwner(address: string): void;
     /**
-     * Subscribe to wallet events.
+     * Parse a transaction through indexers without internalizing.
+     *
+     * This is useful for debugging/testing to see what the indexers produce
+     * without actually storing the transaction in the wallet.
+     *
+     * @param tx - Transaction or txid to parse
+     * @param isBroadcasted - Whether this transaction has been broadcast
+     * @returns ParseContext with all indexer data
      */
-    on<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
+    parseTransaction(txOrTxid: Transaction | string, isBroadcasted?: boolean): Promise<ParseContext>;
     /**
-     * Unsubscribe from wallet events.
+     * Parse a single output without full transaction context.
+     * Runs all indexers' parse() methods but NOT summarize().
+     *
+     * @param output - The TransactionOutput to parse
+     * @param outpoint - The outpoint identifying this output
+     * @returns Txo with all indexer data populated
      */
-    off<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
-    private emit;
+    parseOutput(output: Transaction["outputs"][0], outpoint: Outpoint): Promise<Txo>;
+    /**
+     * Load and parse a single output by outpoint.
+     * Loads the transaction, extracts the output, and runs indexers on it.
+     *
+     * @param outpoint - Outpoint string (txid_vout)
+     * @returns Txo with all indexer data populated
+     */
+    loadTxo(outpoint: string): Promise<Txo>;
+    /**
+     * Run all indexers on a single Txo and populate its data/owner/basket
+     */
+    runIndexersOnTxo(txo: Txo): Promise<void>;
+    /**
+     * Parse all inputs - run indexers on source outputs to populate ctx.spends
+     */
+    private parseInputs;
+    /**
+     * Load a transaction by txid.
+     * Checks storage first, falls back to beef service.
+     *
+     * @param txid - Transaction ID to load
+     * @returns Transaction (without source transactions hydrated)
+     */
+    loadTransaction(txid: string): Promise<Transaction>;
+    /**
+     * Load and attach source transactions for all inputs (1 level deep).
+     * Modifies the transaction in place.
+     */
+    hydrateSourceTransactions(tx: Transaction): Promise<void>;
+    /**
+     * Build minimal parse context from transaction
+     */
+    buildParseContext(tx: Transaction): ParseContext;
     /**
-     * Ingest a transaction by running it through indexers and then internalizing.
+     * Ingest a transaction by running it through indexers and writing directly to storage.
      *
      * This is the main entry point for adding external transactions to the wallet.
      * The indexers extract basket, tags, and custom instructions which are then
-     * passed to the underlying wallet's internalizeAction.
+     * written directly to the wallet's storage.
      *
-     * @param tx - Transaction or BEEF to ingest
+     * Unlike internalizeAction, this method also marks any wallet outputs that are
+     * consumed as inputs in the transaction as spent (spentBy, spendable: false).
+     *
+     * @param tx - Transaction to ingest
      * @param description - Human-readable description
      * @param labels - Optional labels for the transaction
      * @param isBroadcasted - Whether this transaction has been broadcast (affects validation)
+     * @returns Result including parse details for all outputs
      */
-    ingestTransaction(tx: Transaction, description: string, labels?: string[], isBroadcasted?: boolean): Promise<InternalizeActionResult>;
+    ingestTransaction(tx: Transaction, description: string, labels?: string[], isBroadcasted?: boolean): Promise<IngestResult>;
     /**
      * Broadcast a transaction and ingest it into the wallet if successful.
      *
      * @param tx - Transaction to broadcast
      * @param description - Human-readable description for the transaction
      * @param labels - Optional labels for the transaction
-     * @returns The internalize result if successful
+     * @returns The ingest result if successful
      * @throws Error if broadcast fails
      */
-    broadcast(tx: Transaction, description: string, labels?: string[]): Promise<InternalizeActionResult>;
+    broadcast(tx: Transaction, description: string, labels?: string[]): Promise<IngestResult>;
     /**
-     * Sync a single address from the 1Sat indexer.
-     * Fetches new outputs and spends, ingesting transactions as needed.
+     * Start queue-based sync for all owner addresses.
+     * Requires syncQueue to be provided in constructor args.
      *
-     * @param address - The address to sync
-     * @param limit - Max outputs per page (default 100)
+     * This method:
+     * 1. Opens SSE stream and enqueues outputs
+     * 2. Processes queue in batches using Promise.all()
+     * 3. Continues until queue is empty and stream is done
+     */
+    sync(): Promise<void>;
+    /**
+     * Handle a single output from the SSE stream.
+     * Enqueues to the sync queue and updates lastQueuedScore with reorg protection.
+     */
+    private handleSyncOutput;
+    /**
+     * Process queue in batches until empty or stopped.
+     */
+    private processQueueLoop;
+    /**
+     * Group queue items by txid.
+     * @deprecated - claim() now returns items already grouped
+     */
+    private groupItemsByTxid;
+    /**
+     * Process a single txid - ingest transaction and complete queue items.
+     * Items are already marked as "processing" by claim().
+     */
+    private processTxid;
+    /**
+     * Ingest a transaction with knowledge of which outputs are already spent.
+     */
+    private ingestWithSpendInfo;
+    /**
+     * Mark outputs as spent for spend-only queue items.
+     */
+    private markOutputsSpent;
+    /**
+     * Stop the sync.
+     */
+    stopSync(): void;
+    /**
+     * Close the wallet and cleanup all sync connections.
+     */
+    close(): void;
+    /**
+     * Check if sync is currently running.
+     */
+    isSyncing(): boolean;
+    /**
+     * Get the sync queue instance (if provided).
+     */
+    getQueue(): SyncQueueStorage | null;
+    /**
+     * Start only the SSE stream, enqueueing outputs without processing.
+     * Useful for testing to observe queue buildup.
+     */
+    startStream(): Promise<void>;
+    /**
+     * Stop the SSE stream.
+     */
+    stopStream(): void;
+    /**
+     * Check if SSE stream is active.
+     */
+    isStreamActive(): boolean;
+    /**
+     * Check if SSE stream has completed.
+     */
+    isStreamDone(): boolean;
+    /**
+     * Start only the queue processor, without starting a new SSE stream.
+     * Useful for testing to process queued items independently.
+     */
+    startProcessor(): Promise<void>;
+    /**
+     * Stop the queue processor.
      */
-    syncAddress(address: string, limit?: number): Promise<void>;
+    stopProcessor(): void;
     /**
-     * Sync all owner addresses in parallel.
+     * Check if queue processor is active.
      */
-    syncAll(): Promise<void>;
+    isProcessorActive(): boolean;
 }
 export {};

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-export { OneSatWallet, type OneSatWalletArgs, type OneSatWalletEvents, type SyncStartEvent, type SyncProgressEvent, type SyncTxEvent, type SyncErrorEvent, type SyncCompleteEvent, } from "./OneSatWallet";
-export { OneSatServices, type OrdfsMetadata } from "./services/OneSatServices";
+export { OneSatWallet, type OneSatWalletArgs, type OneSatWalletEvents, type IngestResult, } from "./OneSatWallet";
+export { OneSatServices, type SyncOutput } from "./services/OneSatServices";
+export type { OrdfsMetadata, OrdfsContentOptions, OrdfsContentResponse, OrdfsResponseHeaders, Capability, } from "./services/types";
+export * from "./services/client";
 export { ReadOnlySigner } from "./signers/ReadOnlySigner";
 export * from "./indexers";
-export { WalletStorageManager } from "@bsv/wallet-toolbox/mobile";
+export * from "./sync";
+export { WalletStorageManager, StorageProvider, } from "@bsv/wallet-toolbox/mobile";
 export { StorageIdb } from "@bsv/wallet-toolbox/mobile/out/src/storage/StorageIdb";
-export type { Chain } from "@bsv/wallet-toolbox/mobile/out/src/sdk/types";