@1sat/wallet-toolbox 0.0.2 → 0.0.4

package/dist/indexers/types.d.ts

@@ -42,6 +42,8 @@ export interface Bsv21TransactionData {
 export interface IndexData {
     data: unknown;
     tags: string[];
+    /** Optional text content (e.g., from text inscriptions). */
+    content?: string;
 }
 /**
  * IndexSummary contains transaction-level summary information
@@ -60,6 +62,8 @@ export interface ParseResult {
     tags: string[];
     owner?: string;
     basket?: string;
+    /** Optional text content (e.g., from text inscriptions). Truncated to 1000 chars when stored. */
+    content?: string;
 }
 /**
  * Transaction output structure used during parsing

package/dist/services/OneSatServices.d.ts

@@ -13,13 +13,13 @@ export type { SyncOutput };
  * interface required by wallet-toolbox.
  *
  * API Routes:
- * - /api/chaintracks/* - Block headers and chain tracking
- * - /api/beef/* - Raw transactions and proofs
- * - /api/arcade/* - Transaction broadcasting
- * - /api/bsv21/* - BSV21 token data
- * - /api/txo/* - Transaction outputs
- * - /api/owner/* - Address queries and sync
- * - /api/ordfs/* - Content/inscription serving
+ * - /1sat/chaintracks/* - Block headers and chain tracking
+ * - /1sat/beef/* - Raw transactions and proofs
+ * - /1sat/arcade/* - Transaction broadcasting
+ * - /1sat/bsv21/* - BSV21 token data
+ * - /1sat/txo/* - Transaction outputs
+ * - /1sat/owner/* - Address queries and sync
+ * - /1sat/ordfs/* - Content/inscription serving
  */
 export declare class OneSatServices implements WalletServices {
     chain: Chain;

package/dist/services/client/ArcadeClient.d.ts

@@ -1,7 +1,7 @@
 import type { ClientOptions, Policy, SubmitOptions, TransactionStatus } from "../types";
 import { BaseClient } from "./BaseClient";
 /**
- * Client for /api/arcade/* routes.
+ * Client for /1sat/arcade/* routes.
  * Provides transaction broadcast and status checking.
  *
  * Routes:

package/dist/services/client/BeefClient.d.ts

@@ -1,7 +1,7 @@
 import type { ClientOptions } from "../types";
 import { BaseClient } from "./BaseClient";
 /**
- * Client for /api/beef/* routes.
+ * Client for /1sat/beef/* routes.
  * Provides BEEF data, raw transactions, and merkle proofs.
  *
  * Routes:

package/dist/services/client/Bsv21Client.d.ts

@@ -1,7 +1,7 @@
 import type { Bsv21TokenDetails, Bsv21TransactionData, ClientOptions, IndexedOutput } from "../types";
 import { BaseClient } from "./BaseClient";
 /**
- * Client for /api/bsv21/* routes.
+ * Client for /1sat/bsv21/* routes.
  * Provides BSV21 token queries.
  *
  * Routes:

package/dist/services/client/ChaintracksClient.d.ts

@@ -2,7 +2,7 @@ import type { ChainTracker } from "@bsv/sdk";
 import type { BlockHeader, ClientOptions } from "../types";
 import { BaseClient } from "./BaseClient";
 /**
- * Client for /api/chaintracks/* routes.
+ * Client for /1sat/chaintracks/* routes.
  * Provides block header data and implements ChainTracker interface.
  *
  * Routes:

package/dist/services/client/OrdfsClient.d.ts

@@ -1,32 +1,47 @@
-import type { ClientOptions, OrdfsMetadata } from "../types";
+import type { ClientOptions, OrdfsContentOptions, OrdfsContentResponse, OrdfsMetadata } from "../types";
 import { BaseClient } from "./BaseClient";
 /**
  * Client for ordfs routes.
  * Provides inscription content and metadata.
  *
- * Content is served from baseUrl directly (e.g., https://api.1sat.app/:outpoint)
- * API routes use /api/ordfs (e.g., https://api.1sat.app/api/ordfs/metadata/:outpoint)
+ * Content is served from /1sat/content (e.g., https://api.1sat.app/1sat/content/:outpoint)
+ * API routes use /1sat/ordfs (e.g., https://api.1sat.app/1sat/ordfs/metadata/:outpoint)
  */
 export declare class OrdfsClient extends BaseClient {
+    private readonly contentBaseUrl;
     constructor(baseUrl: string, options?: ClientOptions);
     /**
      * Get metadata for an inscription
+     * @param outpoint - Outpoint (txid_vout) or txid
+     * @param seq - Optional sequence number (-1 for latest)
      */
-    getMetadata(outpoint: string): Promise<OrdfsMetadata>;
+    getMetadata(outpoint: string, seq?: number): Promise<OrdfsMetadata>;
     /**
-     * Get inscription content as binary (fetches from content URL)
+     * Get inscription content with full response headers
+     * @param outpoint - Outpoint (txid_vout) or txid
+     * @param options - Content request options
      */
-    getContent(outpoint: string): Promise<Uint8Array>;
+    getContent(outpoint: string, options?: OrdfsContentOptions): Promise<OrdfsContentResponse>;
     /**
-     * Get inscription content with content-type header
+     * Preview base64-encoded HTML content
+     * @param b64HtmlData - Base64-encoded HTML
      */
-    getContentWithType(outpoint: string): Promise<{
-        data: Uint8Array;
-        contentType: string;
-    }>;
+    previewHtml(b64HtmlData: string): Promise<string>;
     /**
-     * Get the URL for fetching inscription content directly
-     * Useful for displaying in img/video tags
+     * Preview content by posting it directly
+     * @param content - Content to preview
+     * @param contentType - Content type header
      */
-    getContentUrl(outpoint: string): string;
+    previewContent(content: Uint8Array, contentType: string): Promise<Uint8Array>;
+    /**
+     * Get the URL for fetching inscription content directly.
+     * Useful for displaying in img/video tags.
+     * @param outpoint - Outpoint (txid_vout) or txid
+     * @param options - Content request options
+     */
+    getContentUrl(outpoint: string, options?: OrdfsContentOptions): string;
+    /**
+     * Parse response headers into structured object
+     */
+    private parseResponseHeaders;
 }

package/dist/services/client/OwnerClient.d.ts

@@ -1,13 +1,13 @@
 import type { BalanceResponse, ClientOptions, IndexedOutput, SyncOutput, TxoQueryOptions } from "../types";
 import { BaseClient } from "./BaseClient";
 /**
- * Client for /api/owner/* routes.
+ * Client for /1sat/owner/* routes.
  * Provides owner (address) queries and sync.
  *
  * Routes:
  * - GET /:owner/txos - Get TXOs for owner
  * - GET /:owner/balance - Get balance
- * - GET /:owner/sync - SSE stream of outputs for sync
+ * - GET /sync?owner=... - SSE stream of outputs for sync (supports multiple owners)
  */
 export declare class OwnerClient extends BaseClient {
     constructor(baseUrl: string, options?: ClientOptions);
@@ -22,19 +22,7 @@ export declare class OwnerClient extends BaseClient {
      */
     getBalance(owner: string): Promise<BalanceResponse>;
     /**
-     * Sync outputs for an owner via SSE stream.
-     * Returns an EventSource that emits SyncOutput events.
-     *
-     * @param owner - Address/owner to sync
-     * @param onOutput - Callback for each output
-     * @param from - Starting score (for pagination/resumption)
-     * @param onDone - Callback when sync completes (client should retry after delay)
-     * @param onError - Callback for errors
-     * @returns Unsubscribe function
-     */
-    sync(owner: string, onOutput: (output: SyncOutput) => void, from?: number, onDone?: () => void, onError?: (error: Error) => void): () => void;
-    /**
-     * Sync outputs for multiple owners via SSE stream.
+     * Sync outputs for owner(s) via SSE stream.
      * The server merges results from all owners in score order.
      *
      * @param owners - Array of addresses/owners to sync
@@ -44,15 +32,10 @@ export declare class OwnerClient extends BaseClient {
      * @param onError - Callback for errors
      * @returns Unsubscribe function
      */
-    syncMulti(owners: string[], onOutput: (output: SyncOutput) => void, from?: number, onDone?: () => void, onError?: (error: Error) => void): () => void;
+    sync(owners: string[], onOutput: (output: SyncOutput) => void, from?: number, onDone?: () => void, onError?: (error: Error) => void): () => void;
     /**
      * Sync outputs as an async iterator.
      * Yields SyncOutput objects until the stream is done.
      */
-    syncIterator(owner: string, from?: number): AsyncGenerator<SyncOutput, void, unknown>;
-    /**
-     * Sync outputs for multiple owners as an async iterator.
-     * Yields SyncOutput objects until the stream is done.
-     */
-    syncMultiIterator(owners: string[], from?: number): AsyncGenerator<SyncOutput, void, unknown>;
+    syncIterator(owners: string[], from?: number): AsyncGenerator<SyncOutput, void, unknown>;
 }

package/dist/services/client/TxoClient.d.ts

@@ -1,17 +1,16 @@
-import type { ClientOptions, IndexedOutput, SearchRequest, TxoQueryOptions } from "../types";
+import type { ClientOptions, IndexedOutput, TxoQueryOptions } from "../types";
 import { BaseClient } from "./BaseClient";
 /**
- * Client for /api/txo/* routes.
+ * Client for /1sat/txo/* routes.
  * Provides TXO (transaction output) lookup and search.
  *
  * Routes:
- * - GET /outpoint/:outpoint - Get single TXO
- * - GET /outpoint/:outpoint/spend - Get spend info
+ * - GET /:outpoint - Get single TXO (outpoint pattern-matched)
+ * - GET /:outpoint/spend - Get spend info
  * - POST /outpoints - Get multiple TXOs
- * - POST /outpoints/spends - Get multiple spends
+ * - POST /spends - Get multiple spends
  * - GET /tx/:txid - Get all TXOs for a transaction
- * - GET /search/:key - Search by single key
- * - POST /search - Search by multiple keys
+ * - GET /search?key=... - Search by key(s)
  */
 export declare class TxoClient extends BaseClient {
     constructor(baseUrl: string, options?: ClientOptions);
@@ -36,11 +35,7 @@ export declare class TxoClient extends BaseClient {
      */
     getByTxid(txid: string, opts?: TxoQueryOptions): Promise<IndexedOutput[]>;
     /**
-     * Search TXOs by a single key
+     * Search TXOs by key(s)
      */
-    search(key: string, opts?: TxoQueryOptions): Promise<IndexedOutput[]>;
-    /**
-     * Search TXOs by multiple keys
-     */
-    searchMultiple(req: SearchRequest): Promise<IndexedOutput[]>;
+    search(keys: string | string[], opts?: TxoQueryOptions): Promise<IndexedOutput[]>;
 }

package/dist/services/types.d.ts

@@ -12,7 +12,7 @@ export interface ClientOptions {
     fetch?: typeof fetch;
 }
 /**
- * Server capabilities returned by /api/capabilities endpoint.
+ * Server capabilities returned by /1sat/capabilities endpoint.
  * These match the actual capability names from 1sat-stack.
  */
 export type Capability = "beef" | "pubsub" | "txo" | "owner" | "indexer" | "bsv21" | "ordfs" | "chaintracks" | "arcade" | "overlay";
@@ -74,19 +74,19 @@ export interface Policy {
     };
 }
 /**
- * Indexed transaction output
+ * Indexed transaction output.
+ * Base fields (outpoint, score) are always present.
+ * Other fields are present based on query options.
  */
 export interface IndexedOutput {
     outpoint: string;
-    satoshis: number;
-    script?: string;
-    height?: number;
-    idx?: number;
-    owners?: string[];
+    score: number;
+    satoshis?: number;
+    blockHeight?: number;
+    blockIdx?: number;
+    spend?: string;
     events?: string[];
     data?: Record<string, unknown>;
-    spend?: string;
-    score: number;
 }
 /**
  * Spend information response
@@ -98,10 +98,6 @@ export interface SpendResponse {
  * Options for querying TXOs
  */
 export interface TxoQueryOptions {
-    /** Tags to include in response data */
-    tags?: string[];
-    /** Include script in response */
-    script?: boolean;
     /** Starting score for pagination */
     from?: number;
     /** Maximum results to return */
@@ -110,16 +106,15 @@ export interface TxoQueryOptions {
     rev?: boolean;
     /** Filter for unspent only */
     unspent?: boolean;
-}
-/**
- * Search request for multiple keys
- */
-export interface SearchRequest {
-    keys: string[];
-    limit?: number;
-    from?: number;
-    reverse?: boolean;
-    unspent?: boolean;
+    /** Include satoshis in response */
+    sats?: boolean;
+    /** Include spend txid in response */
+    spend?: boolean;
+    /** Include events array in response */
+    events?: boolean;
+    /** Include blockHeight and blockIdx in response */
+    block?: boolean;
+    /** Data tags to include in response */
     tags?: string[];
 }
 /**
@@ -168,6 +163,38 @@ export interface OrdfsMetadata {
     parent?: string;
     map?: Record<string, unknown>;
 }
+/**
+ * Options for OrdFS content requests
+ */
+export interface OrdfsContentOptions {
+    /** Sequence number (-1 for latest, 0+ for specific sequence) */
+    seq?: number;
+    /** Include MAP data in X-Map header */
+    map?: boolean;
+    /** Include parent outpoint in X-Parent header */
+    parent?: boolean;
+    /** Return raw directory JSON instead of resolving */
+    raw?: boolean;
+}
+/**
+ * Headers returned from OrdFS content responses
+ */
+export interface OrdfsResponseHeaders {
+    contentType: string;
+    outpoint?: string;
+    origin?: string;
+    sequence?: number;
+    cacheControl?: string;
+    map?: Record<string, unknown>;
+    parent?: string;
+}
+/**
+ * Full content response from OrdFS including headers
+ */
+export interface OrdfsContentResponse {
+    data: Uint8Array;
+    headers: OrdfsResponseHeaders;
+}
 /**
  * BSV21 token details (deploy data)
  */

package/dist/sync/IndexedDbSyncQueue.d.ts

@@ -0,0 +1,30 @@
+import type { SyncQueueInput, SyncQueueItem, SyncQueueStats, SyncQueueStorage, SyncState } from "./types";
+/**
+ * IndexedDB implementation of SyncQueueStorage for browser environments.
+ */
+export declare class IndexedDbSyncQueue implements SyncQueueStorage {
+    private dbName;
+    private db;
+    private dbPromise;
+    /**
+     * Create a new IndexedDB sync queue.
+     * @param accountId - Unique identifier for the account (e.g., address, pubkey hash)
+     */
+    constructor(accountId: string);
+    private getDb;
+    enqueue(items: SyncQueueInput[]): Promise<void>;
+    claim(count?: number): Promise<Map<string, SyncQueueItem[]>>;
+    private getPendingByTxid;
+    private markProcessing;
+    complete(id: string): Promise<void>;
+    completeMany(ids: string[]): Promise<void>;
+    fail(id: string, error: string): Promise<void>;
+    getByTxid(txid: string): Promise<SyncQueueItem[]>;
+    getByStatus(status: SyncQueueItem["status"], limit?: number): Promise<SyncQueueItem[]>;
+    getStats(): Promise<SyncQueueStats>;
+    getState(): Promise<SyncState>;
+    setState(state: Partial<SyncState>): Promise<void>;
+    resetProcessing(): Promise<number>;
+    clear(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/sync/SqliteSyncQueue.d.ts

@@ -0,0 +1,54 @@
+import type { SyncQueueInput, SyncQueueItem, SyncQueueItemStatus, SyncQueueStats, SyncQueueStorage, SyncState } from "./types";
+/**
+ * Generic interface for SQLite database (works with better-sqlite3 and bun:sqlite)
+ */
+interface SqliteDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    close(): void;
+}
+interface SqliteStatement {
+    run(...params: unknown[]): {
+        changes: number;
+    };
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+/**
+ * SQLite implementation of SyncQueueStorage for Node/Bun environments.
+ *
+ * Works with both `better-sqlite3` (Node) and `bun:sqlite` (Bun).
+ */
+export declare class SqliteSyncQueue implements SyncQueueStorage {
+    private db;
+    /**
+     * Create a new SQLite sync queue.
+     * @param db - SQLite database instance (from better-sqlite3 or bun:sqlite)
+     */
+    constructor(db: SqliteDatabase);
+    /**
+     * Create and open a SQLite database for an account.
+     * Helper for common use case.
+     *
+     * @param accountId - Unique identifier for the account (e.g., address, pubkey hash)
+     * @param dataDir - Directory for database files
+     * @param Database - SQLite Database constructor (e.g., from better-sqlite3 or bun:sqlite)
+     */
+    static create(accountId: string, dataDir: string, Database: new (path: string) => any): SqliteSyncQueue;
+    private initialize;
+    enqueue(items: SyncQueueInput[]): Promise<void>;
+    claim(count?: number): Promise<Map<string, SyncQueueItem[]>>;
+    complete(id: string): Promise<void>;
+    completeMany(ids: string[]): Promise<void>;
+    fail(id: string, error: string): Promise<void>;
+    getByTxid(txid: string): Promise<SyncQueueItem[]>;
+    getByStatus(status: SyncQueueItemStatus, limit?: number): Promise<SyncQueueItem[]>;
+    getStats(): Promise<SyncQueueStats>;
+    getState(): Promise<SyncState>;
+    setState(state: Partial<SyncState>): Promise<void>;
+    resetProcessing(): Promise<number>;
+    clear(): Promise<void>;
+    close(): Promise<void>;
+    private rowToItem;
+}
+export {};

package/dist/sync/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export { IndexedDbSyncQueue } from "./IndexedDbSyncQueue";
+export { SqliteSyncQueue } from "./SqliteSyncQueue";

package/dist/sync/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Sync queue types for background transaction processing.
+ */
+/**
+ * Sync state tracks SSE stream progress.
+ */
+export interface SyncState {
+    /** Highest score received from SSE, used to resume stream */
+    lastQueuedScore: number;
+    /** Timestamp of last sync activity */
+    lastSyncedAt?: number;
+}
+/**
+ * Status of a queue item.
+ */
+export type SyncQueueItemStatus = "pending" | "processing" | "done" | "failed";
+/**
+ * A single item in the sync queue.
+ */
+export interface SyncQueueItem {
+    /** Unique per record: `${outpoint}:${score}` */
+    id: string;
+    /** Outpoint in txid_vout format */
+    outpoint: string;
+    /** Score from SSE stream (ordering) */
+    score: number;
+    /** If this is a spend event, the txid that spent it */
+    spendTxid?: string;
+    /** Current processing status */
+    status: SyncQueueItemStatus;
+    /** Number of processing attempts */
+    attempts: number;
+    /** Last error message if failed */
+    lastError?: string;
+    /** Timestamp when item was queued */
+    createdAt: number;
+    /** Timestamp of last status update */
+    updatedAt: number;
+}
+/**
+ * Input for enqueueing new items (fields auto-populated by enqueue).
+ */
+export interface SyncQueueInput {
+    outpoint: string;
+    score: number;
+    spendTxid?: string;
+}
+/**
+ * Queue statistics (transaction-level counts).
+ */
+export interface SyncQueueStats {
+    pending: number;
+    processing: number;
+    done: number;
+    failed: number;
+}
+/**
+ * Storage interface for the sync queue.
+ * Implementations: IndexedDB (browser), SQLite (Node/Bun).
+ */
+export interface SyncQueueStorage {
+    /**
+     * Add items to the queue.
+     * Items are created with status 'pending'.
+     */
+    enqueue(items: SyncQueueInput[]): Promise<void>;
+    /**
+     * Claim items for processing.
+     * Finds pending items, gathers all related items by txid, marks them all
+     * as 'processing', and returns them grouped by txid.
+     * @param count - Maximum number of seed items to start from (default: 1)
+     * @returns Map of txid -> items for that txid
+     */
+    claim(count?: number): Promise<Map<string, SyncQueueItem[]>>;
+    /**
+     * Mark an item as complete.
+     * @param id - Queue item ID
+     */
+    complete(id: string): Promise<void>;
+    /**
+     * Mark multiple items as complete.
+     * @param ids - Queue item IDs
+     */
+    completeMany(ids: string[]): Promise<void>;
+    /**
+     * Mark an item as failed.
+     * @param id - Queue item ID
+     * @param error - Error message
+     */
+    fail(id: string, error: string): Promise<void>;
+    /**
+     * Get all queue items for a given txid.
+     * Used to gather spend info before ingesting a transaction.
+     * @param txid - Transaction ID (first 64 chars of outpoint)
+     */
+    getByTxid(txid: string): Promise<SyncQueueItem[]>;
+    /**
+     * Get queue items by status.
+     * @param status - Status to filter by
+     * @param limit - Maximum number of items to return (default: 100)
+     */
+    getByStatus(status: SyncQueueItemStatus, limit?: number): Promise<SyncQueueItem[]>;
+    /**
+     * Get queue statistics.
+     */
+    getStats(): Promise<SyncQueueStats>;
+    /**
+     * Get sync state.
+     */
+    getState(): Promise<SyncState>;
+    /**
+     * Update sync state.
+     */
+    setState(state: Partial<SyncState>): Promise<void>;
+    /**
+     * Reset any items stuck in "processing" back to "pending".
+     * Called at sync start to recover from crashed sessions.
+     */
+    resetProcessing(): Promise<number>;
+    /**
+     * Clear all queue items and reset state.
+     * Next sync will start from score 0.
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the storage connection.
+     */
+    close(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1sat/wallet-toolbox",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "BSV wallet library extending @bsv/wallet-toolbox with 1Sat Ordinals protocol support",
   "author": "1Sat Team",
   "license": "MIT",