@hardkas/toolkit 0.11.1-alpha → 0.11.2-alpha

package/src/indexer.ts

@@ -1,128 +1,134 @@
-import { EventSubscriber, BackendPlugin } from '@hardkas/core';
-import { ProjectionStoreJson } from '@hardkas/query-store';
-import { ArtifactIndexStoreJson } from '@hardkas/artifacts';
-import { DagApi } from './dag/index.js';
-import { SnapshotParticipant } from './snapshot/types.js';
-
-export interface IndexerBackendPlugin extends BackendPlugin {
-    balance?(address: string): Promise<bigint>;
-    history?(address: string): Promise<unknown[]>;
-    utxos?(address: string): Promise<unknown[]>;
-}
-
-export interface IndexerToolkitOptions {
-    dataDir?: string;
-    backend?: IndexerBackendPlugin;
-}
-
-export class IndexerToolkit implements SnapshotParticipant {
-    private subscriber: EventSubscriber;
-    private projection?: ProjectionStoreJson;
-    private artifactIndex?: ArtifactIndexStoreJson;
-    public readonly dag: DagApi;
-    public readonly backend?: IndexerBackendPlugin | undefined;
-
-    private constructor(private readonly options: IndexerToolkitOptions) {
-        this.subscriber = new EventSubscriber();
-        this.backend = options.backend;
-        
-        if (!this.backend || !this.backend.capabilities.externalState) {
-            this.projection = new ProjectionStoreJson({ 
-                dirPath: options.dataDir ? `${options.dataDir}/projections` : '.hardkas/indexer/projections',
-                namespace: 'indexer'
-            });
-            this.artifactIndex = new ArtifactIndexStoreJson({
-                filePath: options.dataDir ? `${options.dataDir}/artifacts.json` : '.hardkas/indexer/artifacts.json'
-            });
-        }
-        
-        this.dag = new DagApi();
-    }
-
-    public static open(options: IndexerToolkitOptions = {}): IndexerToolkit {
-        return new IndexerToolkit(options);
-    }
-
-    public async connect(): Promise<void> {
-        if (this.backend?.connect) {
-            await this.backend.connect();
-        }
-    }
-
-    public async watch(address: string): Promise<void> {
-        // Polling wrapper as per V1 rules.
-        this.subscriber.subscribe({
-            source: {}, // mock source for facade
-            type: "payment",
-            intervalMs: 1000,
-            watchedAddresses: [address],
-            handler: async (evt) => {
-                // Internally updates projections if address is involved
-            }
-        });
-    }
-
-    public async balance(address: string): Promise<bigint> {
-        if (this.backend?.balance) {
-            return this.backend.balance(address);
-        }
-        const balances = this.projection?.get('balances') || {};
-        return BigInt(balances[address] || 0);
-    }
-
-    public async history(address: string): Promise<any[]> {
-        if (this.backend?.history) {
-            return this.backend.history(address);
-        }
-        const history = this.projection?.get('history') || {};
-        return history[address] || [];
-    }
-
-    public async findReceipts(opts: { tags: string[] }): Promise<any[]> {
-        if (!this.artifactIndex) return [];
-        return this.artifactIndex.find(opts);
-    }
-
-    public async ingestArtifact(artifact: any): Promise<void> {
-        if (!this.artifactIndex) return;
-        this.artifactIndex.index({
-            hash: artifact.id || 'mock_hash',
-            schema: artifact.schema || 'unknown.v1',
-            timestamp: new Date().toISOString(),
-            filePath: `/mock/path/${artifact.id}.json`,
-            tags: artifact.tags || []
-        });
-    }
-
-    public async snapshot(): Promise<any> {
-        if (this.backend && !this.backend.capabilities.snapshots && this.backend.capabilities.externalState) {
-            return {
-                backend: this.backend.name,
-                externalState: true,
-                snapshots: false,
-                dag: await this.dag.snapshot()
-            };
-        }
-        return {
-            projection: this.projection?.getAll() || {},
-            artifactIndex: this.artifactIndex?.getAll() || [],
-            dag: await this.dag.snapshot()
-        };
-    }
-
-    public async restore(state: any): Promise<void> {
-        if (state.externalState) {
-            // Cannot restore local state over an external backend. Just restore DAG.
-            if (state.dag) await this.dag.restore(state.dag);
-            return;
-        }
-        if (state.projection && this.projection) this.projection.setAll(state.projection);
-        if (state.artifactIndex && this.artifactIndex) this.artifactIndex.setAll(state.artifactIndex);
-        if (state.dag) await this.dag.restore(state.dag);
-    }
-
-    public async reload(): Promise<void> {
-        await this.dag.reload();
-        // Projection and artifactIndex read synchronously from memory in this version
-    }
-}
+import { EventSubscriber, BackendPlugin } from '@hardkas/core';
+import { ProjectionStoreJson } from '@hardkas/query-store';
+import { ArtifactIndexStoreJson } from '@hardkas/artifacts';
+import { DagApi } from './dag/index.js';
+import { SnapshotParticipant } from './snapshot/types.js';
+
+export interface IndexerBackendPlugin extends BackendPlugin {
+    balance?(address: string): Promise<bigint>;
+    history?(address: string): Promise<unknown[]>;
+    utxos?(address: string): Promise<unknown[]>;
+}
+
+export interface IndexerToolkitOptions {
+    dataDir?: string;
+    backend?: IndexerBackendPlugin;
+}
+
+export type WatchHandler = (evt: any) => Promise<void> | void;
+
+export class IndexerToolkit implements SnapshotParticipant {
+    private subscriber: EventSubscriber;
+    private projection?: ProjectionStoreJson;
+    private artifactIndex?: ArtifactIndexStoreJson;
+    public readonly dag: DagApi;
+    public readonly backend?: IndexerBackendPlugin | undefined;
+
+    private constructor(private readonly options: IndexerToolkitOptions) {
+        this.subscriber = new EventSubscriber();
+        this.backend = options.backend;
+        
+        if (!this.backend || !this.backend.capabilities.externalState) {
+            this.projection = new ProjectionStoreJson({ 
+                dirPath: options.dataDir ? `${options.dataDir}/projections` : '.hardkas/indexer/projections',
+                namespace: 'indexer'
+            });
+            this.artifactIndex = new ArtifactIndexStoreJson({
+                filePath: options.dataDir ? `${options.dataDir}/artifacts.json` : '.hardkas/indexer/artifacts.json'
+            });
+        }
+        
+        this.dag = new DagApi();
+    }
+
+    public static open(options: IndexerToolkitOptions = {}): IndexerToolkit {
+        return new IndexerToolkit(options);
+    }
+
+    public async connect(): Promise<void> {
+        if (this.backend?.connect) {
+            await this.backend.connect();
+        }
+    }
+
+    public async watch(address: string | string[], handler?: WatchHandler): Promise<void> {
+        const addresses = Array.isArray(address) ? address : [address];
+        // Polling wrapper as per V1 rules.
+        this.subscriber.subscribe({
+            source: {}, // mock source for facade
+            type: "payment",
+            intervalMs: 1000,
+            watchedAddresses: addresses,
+            handler: async (evt) => {
+                // Internally updates projections if address is involved
+                if (handler) {
+                    await handler(evt);
+                }
+            }
+        });
+    }
+
+    public async balance(address: string): Promise<bigint> {
+        if (this.backend?.balance) {
+            return this.backend.balance(address);
+        }
+        const balances = this.projection?.get('balances') || {};
+        return BigInt(balances[address] || 0);
+    }
+
+    public async history(address: string): Promise<any[]> {
+        if (this.backend?.history) {
+            return this.backend.history(address);
+        }
+        const history = this.projection?.get('history') || {};
+        return history[address] || [];
+    }
+
+    public async findReceipts(opts: { tags: string[] }): Promise<any[]> {
+        if (!this.artifactIndex) return [];
+        return this.artifactIndex.find(opts);
+    }
+
+    public async ingestArtifact(artifact: any): Promise<void> {
+        if (!this.artifactIndex) return;
+        this.artifactIndex.index({
+            hash: artifact.id || 'mock_hash',
+            schema: artifact.schema || 'unknown.v1',
+            timestamp: new Date().toISOString(),
+            filePath: `/mock/path/${artifact.id}.json`,
+            tags: artifact.tags || []
+        });
+    }
+
+    public async snapshot(): Promise<any> {
+        if (this.backend && !this.backend.capabilities.snapshots && this.backend.capabilities.externalState) {
+            return {
+                backend: this.backend.name,
+                externalState: true,
+                snapshots: false,
+                dag: await this.dag.snapshot()
+            };
+        }
+        return {
+            projection: this.projection?.getAll() || {},
+            artifactIndex: this.artifactIndex?.getAll() || [],
+            dag: await this.dag.snapshot()
+        };
+    }
+
+    public async restore(state: any): Promise<void> {
+        if (state.externalState) {
+            // Cannot restore local state over an external backend. Just restore DAG.
+            if (state.dag) await this.dag.restore(state.dag);
+            return;
+        }
+        if (state.projection && this.projection) this.projection.setAll(state.projection);
+        if (state.artifactIndex && this.artifactIndex) this.artifactIndex.setAll(state.artifactIndex);
+        if (state.dag) await this.dag.restore(state.dag);
+    }
+
+    public async reload(): Promise<void> {
+        await this.dag.reload();
+        // Projection and artifactIndex read synchronously from memory in this version
+    }
+}

package/src/jobs.ts

@@ -1,46 +1,63 @@
-import { JobRunner, JobStoreJson, JobHandler, JobRecord } from '@hardkas/jobs';
-import { SnapshotParticipant, SnapshotState } from './snapshot/types.js';
-
-export interface JobsToolkitOptions {
-    storePath?: string;
-}
-
-export class JobsToolkit implements SnapshotParticipant {
-    private runner: JobRunner;
-    private store: JobStoreJson;
-
-    private constructor(options: JobsToolkitOptions) {
-        this.store = new JobStoreJson({ filePath: options.storePath || '.hardkas-data/jobs.json' });
-        this.runner = new JobRunner({ store: this.store });
-    }
-
-    public static open(options: JobsToolkitOptions = {}): JobsToolkit {
-        return new JobsToolkit(options);
-    }
-
-    public registerHandler(type: string, handler: JobHandler): void {
-        this.runner.registerHandler(type, handler);
-    }
-
-    public async enqueue(type: string, args?: any): Promise<string> {
-        return this.runner.enqueue(type, args);
-    }
-
-    public async getJob(id: string): Promise<JobRecord | undefined> {
-        return this.runner.getJob(id);
-    }
-
-    public async snapshot(): Promise<SnapshotState> {
-        return this.store.getAll();
-    }
-
-    public async restore(state: SnapshotState): Promise<void> {
-        this.store.setAll(state as Record<string, JobRecord>);
-    }
-
-    public async reload(): Promise<void> {
-        // Runner reads from store on each operation natively in current design,
-        // but if it had internal queues/caches, we'd clear them here.
-        // E.g., this.runner.clearCache();
-    }
-}
+import { JobRunner, JobStoreJson, JobHandler, JobRecord, JobStore } from '@hardkas/jobs';
+import { SnapshotParticipant, SnapshotState } from './snapshot/types.js';
+
+export interface JobsToolkitOptions {
+    storePath?: string;
+    storage?: any; // e.g. SqliteStorage
+}
+
+export class JobsToolkit implements SnapshotParticipant {
+    private runner: JobRunner;
+    private store: JobStore;
+
+    private constructor(options: JobsToolkitOptions) {
+        if (options.storage) {
+            this.store = options.storage.createJobStore();
+        } else {
+            this.store = new JobStoreJson({ filePath: options.storePath || '.hardkas-data/jobs.json' });
+        }
+        this.runner = new JobRunner({ store: this.store });
+    }
+
+    public static open(options: JobsToolkitOptions = {}): JobsToolkit {
+        return new JobsToolkit(options);
+    }
+
+    public registerHandler(type: string, handler: JobHandler): void {
+        this.runner.registerHandler(type, handler);
+    }
+
+    public async enqueue(type: string, args?: any): Promise<string> {
+        return this.runner.enqueue(type, args);
+    }
+
+    public async resumePendingJobs(): Promise<void> {
+        return this.runner.resumePendingJobs();
+    }
+
+    public async getJob(id: string): Promise<JobRecord | undefined> {
+        return this.runner.getJob(id);
+    }
+
+    public async snapshot(): Promise<SnapshotState> {
+        return this.store.getAll();
+    }
+
+    public resetAll() {
+        // Not all stores support this, but if we really need it, we should add clear() to JobStore.
+        // For now, it's a test utility.
+        if ('setAll' in this.store) {
+            (this.store as any).setAll({});
+        }
+    }
+
+    public async restore(state: SnapshotState): Promise<void> {
+        this.store.setAll(state as Record<string, JobRecord>);
+    }
+
+    public async reload(): Promise<void> {
+        // Runner reads from store on each operation natively in current design,
+        // but if it had internal queues/caches, we'd clear them here.
+        // E.g., this.runner.clearCache();
+    }
+}

package/src/payment.ts

@@ -1,81 +1,100 @@
-import { buildKaspaUri } from '@hardkas/tx-builder';
-import { EvidenceBatchExporter } from '@hardkas/artifacts';
-import { InvoiceStoreJson, InvoiceRecord } from './stores/invoice-store.js';
-
-export interface PaymentToolkitOptions {
-    storePath?: string;
-}
-
-export class PaymentToolkit {
-    private store: InvoiceStoreJson;
-
-    private constructor(
-        public readonly merchantId: string,
-        private readonly options: PaymentToolkitOptions
-    ) {
-        this.store = new InvoiceStoreJson({ filePath: options.storePath || '.hardkas-data/invoices.json' });
-    }
-
-    public static openMerchant(merchantId: string, options: PaymentToolkitOptions = {}): PaymentToolkit {
-        return new PaymentToolkit(merchantId, options);
-    }
-
-    public async createInvoice(opts: { amount: bigint; currency: string }): Promise<InvoiceRecord> {
-        const id = `inv_${Date.now()}`;
-        const result = buildKaspaUri({
-            address: `kaspa:${this.merchantId}`,
-            amountSompi: opts.amount * 100_000_000n, // convert to sompi
-            message: `Invoice ${id}`
-        });
-
-        const invoice: InvoiceRecord = {
-            id,
-            merchantId: this.merchantId,
-            amount: opts.amount,
-            currency: opts.currency,
-            status: 'pending',
-            uri: result.uri,
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString()
-        };
-
-        this.store.save(invoice);
-        return invoice;
-    }
-
-    public async getInvoice(id: string): Promise<InvoiceRecord | undefined> {
-        return this.store.get(id);
-    }
-
-    public async listInvoices(): Promise<InvoiceRecord[]> {
-        return this.store.listByMerchant(this.merchantId);
-    }
-
-    public async stats(): Promise<{ totalInvoices: number; paidInvoices: number }> {
-        return this.store.stats(this.merchantId);
-    }
-
-    public async check(invoiceId: string): Promise<string> {
-        const inv = this.store.get(invoiceId);
-        return inv ? inv.status : 'not_found';
-    }
-
-    public async receipt(invoiceId: string): Promise<any> {
-        return {
-            schema: "paymentReceipt.v1",
-            invoiceId,
-            merchantId: this.merchantId,
-            status: "paid",
-            timestamp: new Date().toISOString()
-        };
-    }
-    
-    // For lab testing/simulation manually paying an invoice
-    public async simulatePay(invoiceId: string): Promise<void> {
-        const inv = this.store.get(invoiceId);
-        if (inv) {
-            inv.status = 'paid';
-            this.store.save(inv);
-        }
-    }
-}
+import { buildKaspaUri } from '@hardkas/tx-builder';
+import { EvidenceBatchExporter } from '@hardkas/artifacts';
+import { InvoiceStoreJson, InvoiceRecord, InvoiceStore } from './stores/invoice-store.js';
+
+export interface PaymentToolkitOptions {
+    storePath?: string;
+    storage?: any;
+}
+
+export class PaymentToolkit {
+    private store: InvoiceStore;
+
+    private constructor(
+        public readonly merchantId: string,
+        private readonly options: PaymentToolkitOptions
+    ) {
+        if (options.storage) {
+            this.store = options.storage.createInvoiceStore();
+        } else {
+            this.store = new InvoiceStoreJson({ filePath: options.storePath || '.hardkas-data/invoices.json' });
+        }
+    }
+
+    public static openMerchant(merchantId: string, options: PaymentToolkitOptions = {}): PaymentToolkit {
+        return new PaymentToolkit(merchantId, options);
+    }
+
+    public async createInvoice(opts: { amount?: bigint; amountSompi?: bigint; currency?: string }): Promise<InvoiceRecord> {
+        if (opts.amount === undefined && opts.amountSompi === undefined) {
+            throw new Error("Must provide either amount or amountSompi");
+        }
+
+        const sompi = opts.amountSompi ?? (opts.amount! * 100_000_000n);
+        const kas = opts.amount ?? (opts.amountSompi! / 100_000_000n);
+        const curr = opts.currency ?? 'KAS';
+
+        const id = `inv_${Date.now()}`;
+        const result = buildKaspaUri({
+            address: `kaspa:${this.merchantId}`,
+            amountSompi: sompi,
+            message: `Invoice ${id}`
+        });
+
+        const invoice: InvoiceRecord = {
+            id,
+            merchantId: this.merchantId,
+            amount: kas,
+            currency: curr,
+            status: 'pending',
+            uri: result.uri,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString()
+        };
+
+        await this.store.save(invoice);
+        return invoice;
+    }
+
+    public async getInvoice(id: string): Promise<InvoiceRecord | undefined> {
+        return await this.store.get(id);
+    }
+
+    public async listInvoices(): Promise<InvoiceRecord[]> {
+        return await this.store.listByMerchant(this.merchantId);
+    }
+
+    public async stats(): Promise<{ totalInvoices: number; paidInvoices: number }> {
+        return await this.store.stats(this.merchantId);
+    }
+
+    public async check(invoiceId: string): Promise<string> {
+        const inv = await this.store.get(invoiceId);
+        return inv ? inv.status : 'not_found';
+    }
+
+    public async receipt(invoiceId: string): Promise<any> {
+        const inv = await this.store.get(invoiceId);
+        if (!inv) throw new Error("Invoice not found");
+        if (inv.status !== "paid") throw new Error("Invoice is not paid");
+
+        return {
+            schema: "paymentReceipt.v1",
+            invoiceId,
+            merchantId: this.merchantId,
+            status: "paid",
+            timestamp: new Date().toISOString(),
+            amount: inv.amount,
+            currency: inv.currency
+        };
+    }
+    
+    // For lab testing/simulation manually paying an invoice
+    public async simulatePay(invoiceId: string): Promise<void> {
+        const inv = await this.store.get(invoiceId);
+        if (inv) {
+            inv.status = 'paid';
+            await this.store.save(inv);
+        }
+    }
+}