coco-cashu-plugin-npc

coco-cashu-plugin-npc integrates one or more NPubCash accounts with @cashu/coco-core. It syncs paid quotes from NPC servers, imports them as coco mint quotes, and redeems them through the host's mint operation service.

• Polls NPC for paid quotes since a per-account persisted timestamp
• Optionally listens for realtime websocket updates per account
• Groups quotes by mintUrl before importing and redeeming them through coco
• Exposes an account-aware npc extension API for account management, username management, quote inspection, and manual sync

Installation

bun add coco-cashu-plugin-npc

Install the required peer dependencies in the host app as well:

bun add @cashu/coco-core@^2.0.0 typescript

This package uses npubcash-sdk internally for NPC API access and JWT auth.

Upgrading from v2? See Migrating To v3.

Quick Start

import { NPCPlugin, MemorySinceStore } from "coco-cashu-plugin-npc";

const plugin = new NPCPlugin({
  defaultBaseUrl: "https://npubx.cash",
  syncIntervalMs: 25_000,
  useWebsocket: true,
});

// manager.use(plugin)

const account = await manager.ext.npc.addAccount({
  id: "wallet-main",
  signer,
  sinceStore: new MemorySinceStore(0),
});

await account.sync();

The host calls onInit() during plugin registration and onReady() when services are ready. The plugin registers manager.ext.npc immediately, even with zero accounts. Accounts can then sync from interval timers, websocket notifications, or manual account-level sync() calls.

Configuration

NPCPlugin accepts plugin-level defaults:

interface NPCPluginOptions {
  defaultBaseUrl?: string;
  accountStore?: NPCAccountStore;
  sinceStoreFactory?: NPCSinceStoreFactory;
  syncIntervalMs?: number;
  useWebsocket?: boolean;
  logger?: Logger;
}

• defaultBaseUrl: NPC server URL used when an account does not provide one
• accountStore: optional host-owned store for account metadata
• sinceStoreFactory: optional factory for per-account SinceStore instances
• syncIntervalMs: default polling interval in milliseconds; omit to disable interval syncing
• useWebsocket: default websocket setting for new account runtimes
• logger: optional logger used by the plugin and derived child loggers

NPCPluginOptions no longer accepts a signer or a single sinceStore. Signers and explicit stores are supplied per account.

Extension API

When the plugin is initialized it registers the root npc extension on the host. The root extension manages accounts:

const npc = manager.ext.npc;

const account = await npc.addAccount({
  id: "wallet-main",
  signer,
  baseUrl: "https://npubx.cash",
  syncIntervalMs: 60_000,
  useWebsocket: true,
});

await npc.syncAll();

const sameAccount = npc.getAccount("wallet-main");
await sameAccount?.getInfo();

Available root methods:

• addAccount(options): create or return an account runtime
• removeAccount(accountId): stop and remove an account runtime
• getAccount(accountId): return one account API if registered
• listAccounts(): list registered accounts, including stopped accounts
• getStatus(): summarize registry and runtime state
• syncAll(): run all account syncs concurrently
• shutdownAccount(accountId): shut down one account runtime without removing it

Each account exposes the operations that were global in v2:

await account.getInfo();
await account.getQuotesSince(0);
await account.sync();

const result = await account.setUsername("alice", true);
if (!result.success) {
  console.log(result.pr);
}

Available account methods:

• getInfo(): fetch authenticated NPC account metadata
• setUsername(username, attemptPayment?): set the NPC username and optionally handle the payment-required flow through coco
• getQuotesSince(sinceUnix): inspect raw NPC quotes without importing them into coco
• sync(): manually trigger this account's quote sync pipeline
• start(): start this account's timer and websocket behavior
• stop(): stop this account's timer and websocket behavior
• getStatus(): inspect this account runtime state

The old root methods manager.ext.npc.getInfo(), manager.ext.npc.setUsername(), manager.ext.npc.getQuotesSince(), and manager.ext.npc.sync() were removed in v3. Use the account returned by addAccount() or manager.ext.npc.getAccount(id).

Accounts And Persistence

Account ids are host-defined. The plugin does not derive ids from signers, even when a signer can expose a public key.

await manager.ext.npc.addAccount({
  id: "wallet-main",
  signer,
  baseUrl: "https://npubx.cash",
  sinceStore,
  autoStart: true,
});

addAccount() is idempotent when the incoming configuration matches the registered account: account id, resolved base URL, signer reference, explicit SinceStore reference, interval setting, websocket setting, and autoStart setting. Reusing an id with different configuration throws; remove the account before re-adding it.

Each account resolves its SinceStore in this order:

1. AddNPCAccountOptions.sinceStore
2. plugin sinceStoreFactory(accountId, baseUrl)
3. a new in-memory MemorySinceStore(0)

NPCAccountStore persists account metadata only. It does not persist signer material, and the plugin does not automatically activate stored records. Hosts must reconstruct signer material and call addAccount() for the accounts they want active.

Sync Behavior

Each account sync cycle:

1. Reads the last processed timestamp from that account's SinceStore
2. Fetches paid quotes from NPC with getQuotesSince(since)
3. Filters out already-processed timestamps, invalid quotes, and invalid mint URLs
4. Groups valid quotes by mintUrl
5. Adds each mint as trusted and forwards transformed quotes to coco
6. Advances since to the highest contiguous paidAt watermark with no unresolved failures

Important behaviors:

• overlapping sync requests are serialized per account
• syncAll() runs accounts concurrently
• interval polling rearms after the current account sync finishes
• websocket failures are cleaned up before reconnect attempts are scheduled
• manager pauseSubscriptions() / resumeSubscriptions() lifecycle events pause and resume NPC websocket subscriptions for running accounts
• already-tracked quotes are skipped safely on retry
• since only advances to a safe watermark before the first unresolved failure

Public Exports

The package exports:

export * from "./plugins/NPCPlugin";
export * from "./sync/sinceStore";
export * from "./types";
export * from "./PluginApi";

Development

Useful commands:

bun run typecheck
bun test
bun run build