@1sat/wallet-toolbox 0.0.1 → 0.0.3

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

@@ -0,0 +1,47 @@
+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)
+ */
+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, seq?: number): Promise<OrdfsMetadata>;
+    /**
+     * Get inscription content with full response headers
+     * @param outpoint - Outpoint (txid_vout) or txid
+     * @param options - Content request options
+     */
+    getContent(outpoint: string, options?: OrdfsContentOptions): Promise<OrdfsContentResponse>;
+    /**
+     * Preview base64-encoded HTML content
+     * @param b64HtmlData - Base64-encoded HTML
+     */
+    previewHtml(b64HtmlData: string): Promise<string>;
+    /**
+     * Preview content by posting it directly
+     * @param content - Content to preview
+     * @param contentType - Content type header
+     */
+    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

@@ -0,0 +1,41 @@
+import type { BalanceResponse, ClientOptions, IndexedOutput, SyncOutput, TxoQueryOptions } from "../types";
+import { BaseClient } from "./BaseClient";
+/**
+ * Client for /api/owner/* routes.
+ * Provides owner (address) queries and sync.
+ *
+ * Routes:
+ * - GET /:owner/txos - Get TXOs for owner
+ * - GET /:owner/balance - Get balance
+ * - GET /sync?owner=... - SSE stream of outputs for sync (supports multiple owners)
+ */
+export declare class OwnerClient extends BaseClient {
+    constructor(baseUrl: string, options?: ClientOptions);
+    /**
+     * Get TXOs owned by an address/owner
+     */
+    getTxos(owner: string, opts?: TxoQueryOptions & {
+        refresh?: boolean;
+    }): Promise<IndexedOutput[]>;
+    /**
+     * Get balance for an address/owner
+     */
+    getBalance(owner: string): Promise<BalanceResponse>;
+    /**
+     * 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
+     * @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(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(owners: string[], from?: number): AsyncGenerator<SyncOutput, void, unknown>;
+}

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

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

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

@@ -0,0 +1,8 @@
+export { BaseClient } from "./BaseClient";
+export { ChaintracksClient } from "./ChaintracksClient";
+export { BeefClient } from "./BeefClient";
+export { ArcadeClient } from "./ArcadeClient";
+export { TxoClient } from "./TxoClient";
+export { OwnerClient } from "./OwnerClient";
+export { OrdfsClient } from "./OrdfsClient";
+export { Bsv21Client } from "./Bsv21Client";

package/dist/services/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Consolidated type definitions for 1sat-stack API clients.
+ * These types mirror the structures returned by the 1sat-stack server.
+ */
+/**
+ * Options for configuring API clients
+ */
+export interface ClientOptions {
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom fetch implementation */
+    fetch?: typeof fetch;
+}
+/**
+ * Server capabilities returned by /api/capabilities endpoint.
+ * These match the actual capability names from 1sat-stack.
+ */
+export type Capability = "beef" | "pubsub" | "txo" | "owner" | "indexer" | "bsv21" | "ordfs" | "chaintracks" | "arcade" | "overlay";
+/**
+ * Block header data returned by chaintracks endpoints
+ */
+export interface BlockHeader {
+    height: number;
+    hash: string;
+    version: number;
+    prevHash: string;
+    merkleRoot: string;
+    time: number;
+    bits: number;
+    nonce: number;
+}
+/**
+ * Transaction status values from arcade
+ */
+export type TxStatus = "UNKNOWN" | "RECEIVED" | "SENT_TO_NETWORK" | "ACCEPTED_BY_NETWORK" | "SEEN_ON_NETWORK" | "DOUBLE_SPEND_ATTEMPTED" | "REJECTED" | "MINED" | "IMMUTABLE";
+/**
+ * Transaction status response from arcade
+ */
+export interface TransactionStatus {
+    txid: string;
+    txStatus: TxStatus;
+    timestamp: string;
+    blockHash?: string;
+    blockHeight?: number;
+    merklePath?: string;
+    extraInfo?: string;
+    competingTxs?: string[];
+}
+/**
+ * Options for submitting transactions to arcade
+ */
+export interface SubmitOptions {
+    /** URL for status callbacks */
+    callbackUrl?: string;
+    /** Token for authenticating callbacks */
+    callbackToken?: string;
+    /** Receive all status updates, not just final */
+    fullStatusUpdates?: boolean;
+    /** Skip fee validation */
+    skipFeeValidation?: boolean;
+    /** Skip script validation */
+    skipScriptValidation?: boolean;
+}
+/**
+ * Mining policy from arcade
+ */
+export interface Policy {
+    maxscriptsizepolicy: number;
+    maxtxsigopscountspolicy: number;
+    maxtxsizepolicy: number;
+    miningFee: {
+        satoshis: number;
+        bytes: number;
+    };
+}
+/**
+ * Indexed transaction output.
+ * Base fields (outpoint, score) are always present.
+ * Other fields are present based on query options.
+ */
+export interface IndexedOutput {
+    outpoint: string;
+    score: number;
+    satoshis?: number;
+    blockHeight?: number;
+    blockIdx?: number;
+    spend?: string;
+    events?: string[];
+    data?: Record<string, unknown>;
+}
+/**
+ * Spend information response
+ */
+export interface SpendResponse {
+    spendTxid: string | null;
+}
+/**
+ * Options for querying TXOs
+ */
+export interface TxoQueryOptions {
+    /** Starting score for pagination */
+    from?: number;
+    /** Maximum results to return */
+    limit?: number;
+    /** Reverse order */
+    rev?: boolean;
+    /** Filter for unspent only */
+    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[];
+}
+/**
+ * Balance response from owner endpoint
+ */
+export interface BalanceResponse {
+    balance: number;
+    count: number;
+}
+/**
+ * Sync output streamed via SSE
+ */
+export interface SyncOutput {
+    outpoint: string;
+    score: number;
+    spendTxid?: string;
+}
+/**
+ * Indexed output from parse/ingest operations
+ */
+export interface IndexedTxo {
+    outpoint: string;
+    satoshis: number;
+    script?: string;
+    owners?: string[];
+    events?: string[];
+    data?: Record<string, unknown>;
+}
+/**
+ * Index context returned by parse/ingest
+ */
+export interface IndexContext {
+    txid: string;
+    score: number;
+    outputs: IndexedTxo[];
+}
+/**
+ * OrdFS metadata for an inscription
+ */
+export interface OrdfsMetadata {
+    outpoint: string;
+    origin?: string;
+    sequence: number;
+    contentType: string;
+    contentLength: number;
+    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)
+ */
+export interface Bsv21TokenDetails {
+    id: string;
+    txid: string;
+    vout: number;
+    op: string;
+    amt: string;
+    sym?: string;
+    dec: number;
+    icon?: string;
+}
+/**
+ * BSV21 token data structure from overlay API
+ */
+export interface Bsv21TokenData {
+    id: string;
+    op: string;
+    amt: string;
+    sym?: string;
+    dec?: number;
+    icon?: string;
+    address?: string;
+}
+/**
+ * BSV21 output data from overlay API
+ */
+export interface Bsv21OutputData {
+    txid: string;
+    vout: number;
+    data: {
+        bsv21: Bsv21TokenData;
+    };
+    script: string;
+    satoshis: number;
+    spend: string | null;
+    score: number;
+}
+/**
+ * BSV21 transaction data from overlay API
+ */
+export interface Bsv21TransactionData {
+    txid: string;
+    inputs: Bsv21OutputData[];
+    outputs: Bsv21OutputData[];
+    beef?: string;
+}
+/**
+ * Event from SSE subscription
+ */
+export interface SseEvent {
+    topic: string;
+    data: string;
+    score?: number;
+}

package/dist/signers/ReadOnlySigner.d.ts

@@ -1,4 +1,4 @@
-import { type KeyDeriverApi, type PrivateKey, type WalletProtocol, type Counterparty } from "@bsv/sdk";
+import { type Counterparty, type KeyDeriverApi, type PrivateKey, type WalletProtocol } from "@bsv/sdk";
 /**
  * A read-only KeyDeriver that exposes an identity key but throws on any signing/derivation operation.
  * Used when the wallet is instantiated with only a public key.

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.1",
+  "version": "0.0.3",
   "description": "BSV wallet library extending @bsv/wallet-toolbox with 1Sat Ordinals protocol support",
   "author": "1Sat Team",
   "license": "MIT",
@@ -32,10 +32,13 @@
     "dev": "tsc --watch",
     "lint": "biome check src",
     "lint:fix": "biome check --write src",
-    "test": "bun test"
+    "test": "bun test",
+    "tester:build": "bun build ./tester/src/entry.ts --outdir ./tester/dist --target browser --splitting --define 'process.env={}' --define 'global=globalThis' --sourcemap=inline",
+    "tester": "bun run build && bun run tester:build && bun ./tester/server.ts"
   },
   "dependencies": {
-    "@bsv/sdk": "^1.9.24",
+    "@bopen-io/ts-templates": "^1.1.0",
+    "@bsv/sdk": "1.9.24",
     "@bsv/wallet-toolbox": "^1.7.14",
     "buffer": "^6.0.3"
   },