@dvmkit/sdk 0.1.3-rc.7 → 0.1.4-rc.7

package/README.md

@@ -2,21 +2,105 @@
 
 Build Digital Vending Machines: accountless HTTPS services with typed inputs, jobs, and payment rails.
 
-## Development
+Requires Node.js 22 or later. This is pre-1.0 alpha software: pin the exact package version and read the [release notes](./CHANGELOG.md) before upgrading.
+
+## Quickstart: a free DVM
+
+Create a project and install the SDK:
+
+```sh
+mkdir hello-dvm && cd hello-dvm
+npm init -y
+npm install --save-exact @dvmkit/sdk
+```
+
+Save this as `handler.mjs`:
+
+```js
+import { configureDVM, z } from "@dvmkit/sdk";
+
+export default configureDVM({
+  name: "hello",
+  capability: "echo",
+  input: z.object({ text: z.string().min(1) }),
+  example: { text: "hello" },
+  onJob(ctx) {
+    ctx.artifact({ mime_type: "text/plain", data: ctx.input.text });
+    ctx.complete("Echoed the input");
+  },
+});
+```
+
+Save this as `server.mjs`, then run it with `node server.mjs`:
+
+```js
+import { serve } from "@dvmkit/sdk/server";
+import dvm from "./handler.mjs";
+
+await serve(dvm, { devMode: true });
+```
+
+Submit a local request. `devMode` makes Postgres optional and skips payment verification when no Cashu mint is configured:
+
+```sh
+curl -sS http://localhost:8080/v1/job \
+  -H 'content-type: application/json' \
+  --data '{"capability":"echo","data":{"text":"hello"}}'
+```
+
+Test the handler without opening a port or configuring a payment rail:
+
+```js
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTestContext } from "@dvmkit/sdk/testing";
+import dvm from "./handler.mjs";
+
+test("echoes its input", async () => {
+  const ctx = createTestContext({ input: { text: "hello" } });
+  await dvm.capabilities.echo.onJob(ctx);
+  assert.equal(ctx.completed, true);
+  assert.equal(ctx.messages[0].content.data, "hello");
+});
+```
+
+Run that file with `node --test handler.test.mjs`. The repository carries the complete version under [`examples/quickstart`](./examples/quickstart), plus runnable [signed-auth/custom-route](./examples/authenticated-route) and [payment/lifecycle](./examples/payments-and-lifecycle) examples.
+
+## Public entry points
+
+| Import | Use it for |
+| --- | --- |
+| `@dvmkit/sdk` | DVM descriptors, handler context, bundled Zod, pricing, signing and safe-fetch helpers |
+| `@dvmkit/sdk/server` | Node hosting, Postgres stores, signed-request auth, compatibility gates and payment infrastructure |
+| `@dvmkit/sdk/testing` | Deterministic handler contexts and in-memory stores |
+
+The generated [API reference](./docs/API.md) lists every declaration under these three entries. Deep imports from `dist/` are unsupported.
+
+## Production next steps
+
+- Use Postgres through `DATABASE_URL`; production boot refuses an in-memory job store unless you deliberately supply another durable implementation.
+- Add `auth: secp256k1Auth()` for caller-owned state. The host automatically uses a Postgres replay store when one is available; a per-process replay window is unsafe across replicas.
+- Configure only the rails you operate: Cashu, x402, and Tempo are job payment methods. Lightning is a receive-only prepaid-credit funding leg. Keep every private key, wallet connection, and platform token in your secret store rather than source.
+- A `credit` block opts into reusable prepaid balances and their reclaim obligations. Reusable channels return undrawn collateral through their channel lifecycle; one-payment stablecoin funding is disabled unless `allowOneShotStablecoin: true` because it creates manual refunds. Run and monitor the documented reclaim/payout worker.
+- Honour `ctx.signal`, use `ctx.fetch` for abortable provider calls, and declare provider cost with `ctx.cost` only after the durable step that incurred it.
+
+The public [SDK guide](https://dvmkit.com/docs/sdk) covers signed requests, custom routes, rail configuration, credit reclaim, persistence, and deployment in depth. The [protocol guide](https://dvmkit.com/docs/protocol) specifies the HTTP contract.
+
+## Repository development
 
 Use the Node.js release in `.nvmrc` (Node 22). Install with `npm ci`, then run the same gate CI runs with `npm run verify`: the toolchain check, lint, build, typecheck (including the release scripts under `checkJs`), unit and database tests, the public API surface and package-shape checks, a consumer install, a public-safety scan, the release contract, and a clean-install smoke.
 
 `DATABASE_URL` is optional locally. Without it the database suite is skipped rather than passed, and `verify` says so in its summary, because a skipped suite verified nothing and must not be reported as green. Point `DATABASE_URL` at a scratch Postgres to run it, and pass `npm run verify -- --require-database` to make a missing one a failure, which is what CI does.
 
-The public surface is exactly `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`. There is a fourth entry point, `@dvmkit/sdk/internal`, which is not part of it; see below. Documentation is at [dvmkit.ai](https://dvmkit.ai/docs/sdk).
+The public surface is exactly `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`.
 
 ## Compatibility and versioning
 
 This is pre-1.0 alpha software and the promises match that. Breaking changes can land in any release, they are announced in the release notes for the release that carries them, and there is no long-term support release. Security fixes are made on the latest published release rather than backported.
 
-The public surface is exactly three entry points: `@dvmkit/sdk`, `@dvmkit/sdk/server`, and `@dvmkit/sdk/testing`. Nothing reachable only through a deep path into `dist/` is public, nothing under `@dvmkit/sdk/internal` is public, and `npm run check:api` pins every exported declaration name against `api-surface.json`, so a change to that surface is a deliberate, reviewed act rather than a side effect.
+Nothing reachable only through a deep path into `dist/` is public. `npm run check:api` pins every exported declaration name against `api-surface.json` and the generated API reference, so a change to the supported surface is a deliberate, reviewed act rather than a side effect.
 
-Wire compatibility with callers is separate from the package version and is declared per endpoint. A server built on this SDK answers `DVM-Protocol-Version: 1`, and an individual endpoint may require a set of named capability tokens the caller advertises, a minimum caller version, or both. Capability tokens are additive, so an endpoint that declares no requirement stays reachable by a caller that sends no compatibility headers at all. A caller that cannot meet what an endpoint declares gets HTTP 426 naming the required capabilities and, where one is declared, the minimum version. The protocol is specified at [dvmkit.ai/docs/protocol](https://dvmkit.ai/docs/protocol).
+Wire compatibility with callers is separate from the package version and is declared per endpoint. A server built on this SDK answers `DVM-Protocol-Version: 1`, and an individual endpoint may require a set of named capability tokens the caller advertises, a minimum caller version, or both. Capability tokens are additive, so an endpoint that declares no requirement stays reachable by a caller that sends no compatibility headers at all. A caller that cannot meet what an endpoint declares gets HTTP 426 naming the required capabilities and, where one is declared, the minimum version. The protocol is specified at [dvmkit.com/docs/protocol](https://dvmkit.com/docs/protocol).
 
 ## Job credentials
 
@@ -34,13 +118,28 @@ The same values are accepted as `--endpoint <url>` and `--job-token <hex>`. Thes
 
 If an upgrade broke something for you, an [API compatibility report](https://github.com/dvmkit/sdk/issues/new/choose) is the most useful thing you can send us. It tells us which parts of the published surface people actually build on, which no test of ours can.
 
-## Internal entry point
+## Per-job costs
+
+A handler can declare what a job cost **you**, the builder, to serve — a vendor API call, a GPU minute, a per-request licence fee — and the SDK reports it to the platform alongside what the caller paid, so your dashboard can state a margin instead of guessing at one.
+
+```ts
+const transcript = await ctx.step("transcribe", async () => {
+  const result = await whisper(audio);
+  ctx.cost({ amount: result.seconds * 0.0001, currency: "usd" });
+  return result;
+});
+ctx.artifact({ mime_type: "text/plain", data: transcript.text });
+```
+
+`amount` is in whole currency units, like every other money figure you hand the SDK. Call it once per cost you incur; the declarations for one job are summed, and only the total is rounded, to a millionth of a unit. That ordering is what makes fine-grained declarations safe: a per-token charge of $0.0000003 is below the reported resolution on its own, but a thousand of them still add up to $0.0003 rather than to nothing. Every call in a job must name the same currency.
 
-`@dvmkit/sdk/internal` exists for one consumer: the dvmkit platform, which runs on this source instead of keeping a fork of it. Do not build on it.
+Three things worth knowing:
 
-It carries no stability promise of any kind. A name under it can change meaning, change signature, or disappear in any release, including a patch release, and that is not a breaking change: it needs no `!` marker, no `BREAKING CHANGE:` footer, and no note in the release notes. It is not documented, its contents track what the platform happens to need, and it is excluded from everything the three public entry points promise above.
+- **Declaring nothing is not declaring zero.** A job whose handler never calls `ctx.cost` reports no cost at all, and the dashboard says the margin is unknown rather than showing it as 100%. `ctx.cost({ amount: 0, currency: "usd" })` is how you say a job genuinely cost you nothing.
+- **Declare the cost where you incur it, including inside `ctx.step`.** The step cache carries those declarations with the result and applies them once when a replay skips the body.
+- **Every terminal job reports its declared cost.** A paid completion carries the cost on its revenue report. A free completion, failure, or cancellation sends a separate cost-only report and does not create revenue.
 
-The names in it are still pinned in `api-surface.json`, so a change to them is visible in review rather than silent; the pin records what moved, it does not promise that it will not move. If something under `./internal` is genuinely useful to a third party, the way to get it is to ask for it: graduating a name to `.`, `./server` or `./testing` is a deliberate, reviewed `feat`, and only then does it acquire the compatibility promises on this page.
+The cost is yours, never the caller's: it is recorded separately from what the caller paid and is never netted against it. Both report shapes use the same durable outbox. Cost-only reports are keyed on the job id and revisioned, so retries and cross-machine updates converge on the latest cumulative value. With the Postgres job store, boot-time and periodic reconciliation enqueue any terminal cost revision that a process exited before reporting.
 
 ## Contributing
 

package/dist/{chunk-YDIYXGYL.js → chunk-E4EVGPDX.js}

@@ -11,24 +11,31 @@ var StepCache = class _StepCache {
   }
   /** Get a cached step result. Throws if not present. */
   get(id) {
-    if (!this.cache.has(id)) {
-      throw new Error(`StepCache: no cached result for step "${id}"`);
-    }
-    return this.cache.get(id);
+    return this.getRecord(id).value;
+  }
+  /** Get a cached step record, including replay metadata. Throws if not present. */
+  getRecord(id) {
+    const record = this.cache.get(id);
+    if (record === void 0) throw new Error(`StepCache: no cached result for step "${id}"`);
+    return record;
   }
   /** Cache a step result. */
-  set(id, value) {
-    this.cache.set(id, value);
+  set(id, value, costs) {
+    this.cache.set(id, {
+      id,
+      value,
+      ...costs !== void 0 && costs.length > 0 ? { costs: costs.map(({ amount, currency }) => ({ amount, currency })) } : {}
+    });
   }
   /** Export all cached steps for persistence. */
   serialize() {
-    return [...this.cache.entries()].map(([id, value]) => ({ id, value }));
+    return [...this.cache.values()];
   }
   /** Restore a StepCache from persisted records. */
   static deserialize(records) {
     const cache = new _StepCache();
-    for (const { id, value } of records) {
-      cache.set(id, value);
+    for (const { id, value, costs } of records) {
+      cache.set(id, value, costs);
     }
     return cache;
   }

package/dist/{chunk-EPNDZ5DH.js → chunk-EDDYHZ6W.js}

@@ -5,13 +5,13 @@ import {
 // src/lib/mints.ts
 var RECOMMENDED_MINTS = [
   {
-    name: "Testnut",
-    description: "Cashu test mint \u2014 use for testing only, not real funds",
-    url: "https://testnut.cashu.space"
+    name: "Coinos",
+    description: "Primary Cashu mint accepted by dvmkit DVMs",
+    url: "https://mint.coinos.io"
   },
   {
     name: "Voltz Mint",
-    description: "Production Cashu mint by the Voltz Wallet team",
+    description: "Fallback Cashu mint accepted by dvmkit DVMs",
     url: "https://mint.lnvoltz.com"
   }
 ];

package/dist/{chunk-NFRM5QYP.js → chunk-EVBK675R.js}

@@ -6,6 +6,7 @@ import {
 import { randomUUID } from "crypto";
 var ENDPOINTS = {
   revenue: "/_internal/job-revenue",
+  cost: "/_internal/job-cost",
   deposit: "/_internal/credit-deposit",
   release: "/_internal/credit-draw-release",
   drain: "/_internal/credit-drain",
@@ -129,6 +130,10 @@ var RevenueReporter = class _RevenueReporter {
   async report(payload) {
     return this.enqueue("revenue", payload, payload.jobId);
   }
+  /** Persist a zero-revenue job cost and attempt immediate delivery. */
+  async reportCost(payload) {
+    return this.enqueue("cost", payload, payload.jobId);
+  }
   /**
    * Join a credit deposit to the caller-owned rail transaction.
    *