@decentnetwork/billing-client

npm install @decentnetwork/billing-client@0.1.2

// stub-server.mjs
// A local stand-in for the billing service: same paths, same JSON envelope
// ({ ok: true, ... } / { ok: false, error }), same x-billing-token header.
// It keeps holds in memory and never computes real prices.
import { createServer } from "node:http";

export function startStub({ token, port = 0, broke = new Set() }) {
  const holds = new Map();
  const log = [];
  const server = createServer(async (req, res) => {
    const url = new URL(req.url, "http://stub");
    let body = {};
    for await (const chunk of req) body = JSON.parse(chunk.toString() || "{}");
    log.push(`${req.method} ${url.pathname} token=${req.headers["x-billing-token"] === token ? "ok" : "bad"}`);
    const send = (status, data) => { res.writeHead(status, { "content-type": "application/json" }); res.end(JSON.stringify(data)); };
    if (req.headers["x-billing-token"] !== token) return send(401, { ok: false, error: "bad token" });
    switch (`${req.method} ${url.pathname}`) {
      case "GET /balance": return send(200, { ok: true, balance: 0, held: 0 });
      case "POST /hold":
        if (broke.has(body.userid)) return send(400, { ok: false, error: "insufficient balance" });
        holds.set(body.taskId, body);
        return send(200, { ok: true, amount: 0 });
      case "POST /capture":
        if (!holds.delete(body.taskId)) return send(404, { ok: false, error: `no hold for task ${body.taskId}` });
        return send(200, { ok: true, entry: {} });
      case "POST /release": holds.delete(body.taskId); return send(200, { ok: true });
      case "GET /history": return send(200, { ok: true, entries: [] });
      default: return send(404, { ok: false, error: "not found" });
    }
  });
  return new Promise((resolve) => server.listen(port, "127.0.0.1", () =>
    resolve({ url: `http://127.0.0.1:${server.address().port}`, log, close: () => server.close() })));
}

// quickstart.mjs
import { BillingClient, BillingError } from "@decentnetwork/billing-client";
import { startStub } from "./stub-server.mjs";

const stub = await startStub({ token: "dev-token", broke: new Set(["broke-user"]) });
const billing = new BillingClient({ baseUrl: stub.url, token: "dev-token", timeoutMs: 5000 });
const NODE = "my-node-userid";

// One task, the way a node runs it: hold -> work -> capture (or release).
async function runTask(userid, taskId, work) {
  await billing.hold({ userid, taskId, kind: "audio", seconds: 42, service: "interview", node: NODE });
  try {
    const actualSeconds = await work();
    await billing.capture(taskId, { kind: "audio", seconds: actualSeconds });
    return "captured";
  } catch (err) {
    await billing.release(taskId);
    return `released (${err.message})`;
  }
}

console.log("task-1:", await runTask("alice", "task-1", async () => 40));
console.log("task-2:", await runTask("alice", "task-2", async () => { throw new Error("TTS failed"); }));

try {
  await runTask("broke-user", "task-3", async () => 10);
} catch (err) {
  if (err instanceof BillingError && err.code === "insufficient") console.log("task-3: ask the user to top up");
  else throw err;
}

const bad = new BillingClient({ baseUrl: stub.url, token: "wrong" });
await bad.history("alice").catch((e) => console.log("wrong token:", e.name, e.code, e.status, e.message));

console.log("balance keys:", Object.keys(await billing.balance("alice")).join(", "));
console.log("requests seen by the stub:\n  " + stub.log.join("\n  "));
stub.close();

$ node quickstart.mjs
task-1: captured
task-2: released (TTS failed)
task-3: ask the user to top up
wrong token: BillingError http 401 bad token
balance keys: balance, held
requests seen by the stub:
  POST /hold token=ok
  POST /capture token=ok
  POST /hold token=ok
  POST /release token=ok
  POST /hold token=ok
  GET /history token=bad
  GET /balance token=ok

interface BillingClientOptions {
  baseUrl: string;      // e.g. "http://<billing virtual IP>:<port>" over AgentNet
  token: string;        // shared secret, sent as the x-billing-token header
  timeoutMs?: number;   // per request, default 10000
}
type TaskKind = "audio" | "video";

class BillingError extends Error {
  name: "BillingError";
  code: "insufficient" | "http";   // "insufficient" when the message matches /insufficient/i
  status?: number;                 // HTTP status
}