@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/cli/commands/api.js

@@ -0,0 +1,737 @@
+/**
+ * `decision-oracle api …` — the Decision API lane's operator surface (go-prod spec §3.2, §12.2), for
+ * whoever runs an oracle with `API_LANE` on and has no console in front of it yet. Every call is a
+ * console invocation signed as the AuthHub session `decision-oracle login` saved: `{ with:
+ * ixo:oracle/<oracle did:web>, can: <the route's action> }` for the account and operator routes,
+ * `…/source/<id>` + `X-Source-Id` for a source's own (`middleware/api/console.ts`; the action is
+ * the route's `API_ACTIONS` entry, named by its op at each call), 120 s, audience read off the
+ * oracle's did.json. The session invokes as itself, with no grant — so on a source it must be a
+ * current controller (admin) of the source's organisation (D10); on `/admin` its DID must be in the
+ * oracle's `ORACLE_ADMIN_DIDS`.
+ *
+ *   api source create --name <n> --contact <email> --entity <did:ixo:entity:…>
+ *                                                         add this oracle to an organisation you
+ *                                                         control (pending-link; secret shown once)
+ *   api source link <sourceId> [--engine-url <url>] [--yes]
+ *                                                         finish it as the console's "Add oracle"
+ *                                                         does: sign the organisation's link, PUT
+ *                                                         it to the ENGINE (`company/link` on
+ *                                                         `ixo:eval-engine`), then the oracle's
+ *                                                         company sync → active
+ *   api source delete <sourceId> [--yes]                 remove this oracle from the organisation:
+ *                                                         the source and every row off it (the
+ *                                                         undo for a wrong link; root only)
+ *   api sources [--entity <did:ixo:entity:…>]            the session's memberships on this oracle;
+ *                                                         with --entity, every source of an
+ *                                                         organisation it controls (pending too)
+ *   api key create --source <id> --scopes <s,…> [--name <n>] [--max-spend-cents <n>]
+ *   api keys --source <id>
+ *   api key revoke --source <id> <prefix|masked key> [--grace-days <n>] [--yes]
+ *   api admin sources
+ *   api admin pause <sourceId> [--note <text>] [--yes]
+ *   api admin resume <sourceId> [--yes]
+ *   api admin protocols <sourceId> <did,…>|--none [--yes]  replaces the allow-list whole
+ *   api admin billing-mode <sourceId> x402|none [--yes]    operator-only by design (§3.2)
+ *   api review-billing enable --source <id> [--cap <PAY>] [--yes]
+ *                                                         "Pay for reviews" (contracts 1.22.0): the
+ *                                                         organisation's chain owner signs the x402
+ *                                                         payment delegation and stores it here
+ *   api review-billing status --source <id>
+ *   api review-billing disable --source <id> [--yes]     drop it here, then revoke it in the UCAN store
+ *
+ * Common: `--kit <url>` (else the project's `ORACLE_HOSTNAME`), `--env-file`, `--network`
+ * (which saved session; else the project's `IXO_NETWORK`, else devnet), `--json` (the response body
+ * as the API answered it — stdout is that JSON and nothing else: a gate's plan goes to stderr, so a
+ * dry run under `--json` prints nothing on stdout). A refusal prints the §4.1 envelope's code,
+ * message and requestId and exits 1. Every write carries a fresh `Idempotency-Key`.
+ */
+import process from "node:process";
+import { oracleResource, sourceResource } from "../../contracts/capabilities.js";
+import { NETWORKS } from "../../networks.js";
+import { parse, UsageError } from "../lib/args.js";
+import { confirm, fail, resolveEntity, resolveNetwork } from "../lib/chain.js";
+import { loadProjectConfig, oracleUrlFor, readProjectEnv } from "../lib/devvars.js";
+import { engineUrlFor } from "../lib/engine.js";
+import { kitFetch, loadSession, sessionInvocation, signCompanyLink, } from "../lib/session.js";
+const COMMON = {
+    kit: { type: "string" },
+    "env-file": { type: "string" },
+    network: { type: "string" },
+    json: { type: "boolean" },
+    yes: { type: "boolean" },
+};
+/**
+ * `review-billing enable`'s default lifetime cap, in PAY (1 PAY = 1 000 000 upay = $1): a sensible
+ * default the owner raises with `--cap` (owner, 2026-10-14 — about 2 000 reviews at 0.5 PAY), the
+ * same on every network. The delegation's `maxAmount` is cumulative over its whole life (the
+ * facilitator never refunds or resets it), so a raise is a new delegation that replaces this one.
+ */
+const DEFAULT_CAP_PAY = "1000";
+/** The delegation's life (S4, 2026-10-14): ~100 years. A standing authority, not a top-up; the
+ *  cap is what bounds it, and `disable` (plus a revoke) is what ends it. */
+const REVIEW_BILLING_LIFE_SEC = Math.round(100 * 365.25 * 86_400);
+export const API_USAGE = `usage: decision-oracle api <subcommand> [options]
+
+  source create --name <n> --contact <email> --entity <did>
+                                                 add this oracle to an organisation you control —
+                                                 pending-link until its link syncs; secret shown ONCE
+  source link <sourceId> [--engine-url <url>]    sign the organisation's link, store it at the
+                                                 engine and sync it: pending-link → active
+  source delete <sourceId>                       remove this oracle from the organisation: the
+                                                 source, its keys, members, webhooks and claims
+  sources [--entity <did>]                      the sources your login belongs to; with --entity,
+                                                 every source of an organisation you control
+                                                 (pending-link ones included)
+  key create --source <id> --scopes <s,…> [--name <n>] [--max-spend-cents <n>]
+                                                 mint an API key — shown ONCE
+  keys --source <id>                             a source's keys, masked
+  key revoke --source <id> <prefix|masked key> [--grace-days <n>]
+  admin sources                                  every source (your DID in ORACLE_ADMIN_DIDS)
+  admin pause <sourceId> [--note <text>]
+  admin resume <sourceId>
+  admin protocols <sourceId> <did,…>|--none      replace a source's allowed protocols (--none: no
+                                                 protocol at all)
+  admin billing-mode <sourceId> x402|none
+  review-billing enable --source <id> [--cap <PAY>]
+                                                 "Pay for reviews": sign, as the organisation's
+                                                 chain owner, a payment delegation for this oracle's
+                                                 reviews (a lifetime cap, default ${DEFAULT_CAP_PAY} PAY;
+                                                 ~100 years) and store it; enable again with a higher
+                                                 --cap replaces it
+  review-billing status --source <id>            the stored delegation: state, cap, spent, credits
+  review-billing disable --source <id>           drop it here, then revoke it in the UCAN store
+
+common: --kit <url> (else ORACLE_HOSTNAME from the project), --env-file <path>,
+--network devnet|testnet|mainnet (else the project's IXO_NETWORK, else devnet), --json (the API's
+answer, alone on stdout), --yes (a source link or delete, a key revoke, every admin change and a
+review-billing enable or disable are dry runs without it)
+`;
+export async function run(argv) {
+    const [group, verb, ...rest] = argv;
+    if (group === "help" || group === "--help" || group === "-h") {
+        console.log(API_USAGE);
+        return 0;
+    }
+    // `api <group> <verb> --help`: that command's usage line(s) plus the common flags — parseArgs is
+    // strict, so without this a per-command `--help` dies as "Unknown option".
+    const isHelp = (arg) => arg === "--help" || arg === "-h";
+    if (isHelp(verb) || rest.some(isHelp)) {
+        const name = isHelp(verb) ? group : `${group} ${verb}`;
+        const lines = API_USAGE.split("\n");
+        const start = lines.findIndex((line) => line.trimStart().startsWith(`${name} `));
+        if (start === -1) {
+            console.log(API_USAGE);
+            return 0;
+        }
+        let end = start + 1;
+        while (end < lines.length && /^\s{10,}\S/.test(lines[end] ?? ""))
+            end++;
+        const common = lines.findIndex((line) => line.startsWith("common:"));
+        console.log([...lines.slice(start, end), "", ...(common === -1 ? [] : lines.slice(common))].join("\n"));
+        return 0;
+    }
+    switch (`${group} ${verb}`) {
+        case "source create":
+            return call(rest, { name: { type: "string" }, contact: { type: "string" }, entity: { type: "string" } }, sourceCreate);
+        case "source link":
+            return call(rest, { "engine-url": { type: "string" } }, sourceLink);
+        case "source delete":
+            return call(rest, {}, sourceDelete);
+        case "key create":
+            return call(rest, {
+                source: { type: "string" },
+                scopes: { type: "string" },
+                name: { type: "string" },
+                "max-spend-cents": { type: "string" },
+            }, keyCreate);
+        case "key revoke":
+            return call(rest, { source: { type: "string" }, "grace-days": { type: "string" } }, keyRevoke);
+        case "admin sources":
+            return call(rest, {}, adminSources);
+        case "admin pause":
+            return call(rest, { note: { type: "string" } }, adminPause);
+        case "admin resume":
+            return call(rest, {}, adminResume);
+        case "admin protocols":
+            return call(rest, { none: { type: "boolean" } }, adminProtocols);
+        case "admin billing-mode":
+            return call(rest, {}, adminBillingMode);
+        case "review-billing enable":
+            return call(rest, { source: { type: "string" }, cap: { type: "string" } }, reviewBillingEnable);
+        case "review-billing status":
+            return call(rest, { source: { type: "string" } }, reviewBillingStatus);
+        case "review-billing disable":
+            return call(rest, { source: { type: "string" } }, reviewBillingDisable);
+    }
+    // The two list verbs take no second word.
+    const tail = verb === undefined ? [] : [verb, ...rest];
+    if (group === "sources")
+        return call(tail, { entity: { type: "string" } }, sources);
+    if (group === "keys")
+        return call(tail, { source: { type: "string" } }, keys);
+    throw new UsageError(group === undefined
+        ? "api needs a subcommand (source create|sources|key create|keys|key revoke|admin …|review-billing …)"
+        : `unknown api subcommand: ${[group, verb].filter(Boolean).join(" ")}`);
+}
+// --- a source's own routes (the session must be a controller of its organisation) --------------
+async function sourceCreate({ api, values, }) {
+    const name = required(values.name, "api source create needs --name <name>");
+    const contactEmail = required(values.contact, "api source create needs --contact <email>");
+    const entityDid = required(values.entity, "api source create needs --entity <did:ixo:entity:…> (the organisation you control)");
+    const body = await api("createSource", "POST", "/v1/api/sources", {
+        name,
+        contactEmail,
+        entityDid,
+    });
+    return out(body, [
+        `created ${sourceLine(body.source)}`,
+        "pending-link: it takes no claims or keys until the organisation's link is signed in the",
+        "Decision Console (which then syncs it), or with",
+        `\`decision-oracle api source link ${body.source.sourceId} --yes\`. Find it again with`,
+        `\`decision-oracle api sources --entity ${entityDid}\`.`,
+        "",
+        "webhook signing secret — shown ONCE, store it now (only a rotation gets you another):",
+        `  ${body.webhookSecret ?? "(not returned: an idempotent replay never repeats a secret)"}`,
+    ]);
+}
+/**
+ * The console's "Add oracle" steps 2 and 3 (eval-engine-dashboard `lib/addOracle.ts` `linkSource`)
+ * for a source `source create` left `pending-link`: the session — a current controller of the
+ * source's organisation — signs the `SourceCompanyLink`, PUTs it to the ENGINE, the link's one home
+ * (`PUT /v1/sources/:oracleDid/:sourceId/company`, `{ can: company/link, with: ixo:eval-engine }`),
+ * then asks the oracle to mirror it (`company/sync`) → `active`, or `disputed` when the engine
+ * holds another organisation's link. The organisation is the source's own (`GET /v1/api/me`), so
+ * the link can name no other. A source that is already linked is printed and left alone.
+ */
+async function sourceLink({ api, values, positionals, gate, session, network, oracleUrl, }) {
+    const sourceId = required(positionals[0], "api source link needs <sourceId>");
+    const me = await api("getMe", "GET", "/v1/api/me", undefined, sourceId);
+    const source = me.source;
+    if (source.status !== "pending-link") {
+        return out({ source }, [
+            source.status === "disputed"
+                ? "disputed: the engine holds another organisation's link for this source. Delete it and add the oracle again."
+                : "already linked — nothing to do.",
+            sourceLine(source),
+        ]);
+    }
+    const entityDid = source.companyEntityDid;
+    const engineUrl = engineUrlFor({ network, engineUrl: values["engine-url"] });
+    gate(`link source ${sourceId} to its organisation`, [
+        `entity  : ${entityDid}`,
+        `engine  : ${engineUrl} (PUT …/company, company/link)`,
+        "then    : the oracle's company sync",
+    ]);
+    const oracleDid = await fetch(`${oracleUrl}/.well-known/did.json`)
+        .then(async (res) => (await res.json()).id)
+        .catch(() => {
+        throw new Error(`no did.json at ${oracleUrl}`);
+    });
+    const link = await signCompanyLink(session, { entityDid, oracleDid, sourceId });
+    const { token } = await sessionInvocation(session, engineUrl, "engine", () => ({
+        can: "company/link",
+        with: "ixo:eval-engine",
+    }));
+    const path = `/v1/sources/${encodeURIComponent(oracleDid)}/${encodeURIComponent(sourceId)}/company`;
+    const res = await fetch(`${engineUrl}${path}`, {
+        method: "PUT",
+        headers: {
+            authorization: `Bearer ${token}`,
+            "x-auth-type": "ucan",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({ link }),
+    });
+    if (!res.ok) {
+        refused(res.status, `${engineUrl}${path}`, await res.text());
+    }
+    const synced = await api("syncSourceCompany", "POST", `/v1/api/sources/${encodeURIComponent(sourceId)}/company/sync`, undefined, sourceId);
+    const now = synced.source;
+    return out(synced, [
+        now.status === "active"
+            ? `linked ${sourceLine(now)}`
+            : `the oracle reads it as ${now.status}: ${sourceLine(now)}`,
+    ]);
+}
+/**
+ * `DELETE /v1/api/sources/:id` — the clean undo for a wrong organisation link (and the way out of
+ * `disputed`). Root only, like `source link`: a current controller of the source's organisation,
+ * no proof. The plan names what goes, read off `/me` first, so a dry run shows the source by name.
+ * Nothing on chain or at the engine changes.
+ */
+async function sourceDelete({ api, positionals, gate }) {
+    const sourceId = required(positionals[0], "api source delete needs <sourceId>");
+    const source = (await api("getMe", "GET", "/v1/api/me", undefined, sourceId)).source;
+    gate(`DELETE source ${sourceId} and every row off it (keys, members, webhooks, claims)`, [
+        `name    : ${source.name}`,
+        `status  : ${source.status}`,
+        `entity  : ${source.companyEntityDid}`,
+    ]);
+    const path = `/v1/api/sources/${encodeURIComponent(sourceId)}`;
+    await api("deleteSource", "DELETE", path, undefined, sourceId);
+    const raw = { deleted: true, sourceId };
+    return out(raw, [JSON.stringify(raw)]);
+}
+async function sources({ api, values }) {
+    if (values.entity) {
+        // A controller has no membership: its organisation's sources (pending-link ones included) are
+        // only here — the list a retry must read before it signs up a second source.
+        const items = await allPages(api, "listOrganisationSources", `/v1/api/organisations/${encodeURIComponent(values.entity)}/sources`);
+        return out({ items }, items.length === 0
+            ? ["no sources of this organisation on this oracle"]
+            : items.map(sourceLine));
+    }
+    const body = await api("listMySources", "GET", "/v1/api/sources");
+    const items = body.items;
+    return out(body, items.length === 0
+        ? [
+            "no memberships. A controller (admin) of an organisation is a member of none: list its",
+            "sources, pending-link ones included, with `decision-oracle api sources --entity <did:ixo:entity:…>`",
+            "before `decision-oracle api source create` adds another.",
+        ]
+        : items.map((m) => `${sourceLine(m.source)}  role=${m.role} (${m.status})`));
+}
+/** Every page of a keyset-paged source list (100 a page): the cursor is followed to the end. */
+async function allPages(api, op, path) {
+    const items = [];
+    let cursor = null;
+    do {
+        const page = await api(op, "GET", cursor ? `${path}?cursor=${encodeURIComponent(cursor)}` : path);
+        items.push(...page.items);
+        cursor = page.nextCursor ?? null;
+    } while (cursor);
+    return items;
+}
+async function keyCreate({ api, values, }) {
+    const sourceId = required(values.source, "api key create needs --source <id>");
+    const scopes = list(required(values.scopes, "api key create needs --scopes <scope,…>"));
+    const max = values["max-spend-cents"];
+    const body = await api("createApiKey", "POST", "/v1/api/keys", {
+        scopes,
+        ...(values.name ? { name: values.name } : {}),
+        ...(max !== undefined ? { maxSpendCentsPerDay: integer(max, "--max-spend-cents") } : {}),
+    }, sourceId);
+    return out(body, [
+        `created ${keyLine(body)}`,
+        "",
+        "API key — shown ONCE, store it now (the oracle keeps only its hash):",
+        `  ${body.key ?? "(not returned: an idempotent replay never repeats a key)"}`,
+    ]);
+}
+async function keys({ api, values }) {
+    const sourceId = required(values.source, "api keys needs --source <id>");
+    const body = await api("listApiKeys", "GET", "/v1/api/keys", undefined, sourceId);
+    const items = body.items;
+    return out(body, items.length === 0 ? ["no keys on this source"] : items.map(keyLine));
+}
+async function keyRevoke({ api, values, positionals, gate, }) {
+    const sourceId = required(values.source, "api key revoke needs --source <id>");
+    const prefix = keyPrefix(required(positionals[0], "api key revoke needs the key's <prefix> (or its masked form)"));
+    const graceDays = integer(values["grace-days"] ?? "0", "--grace-days");
+    gate(`revoke API key ${prefix}`, [
+        `source  : ${sourceId}`,
+        `grace   : ${graceDays > 0 ? `the key keeps working ${graceDays} day(s)` : "none — at once"}`,
+    ]);
+    const path = `/v1/api/keys/${encodeURIComponent(prefix)}?graceDays=${graceDays}`;
+    const body = await api("revokeApiKey", "DELETE", path, undefined, sourceId);
+    return out(body, [`revoked ${keyLine(body)}`]);
+}
+// --- the operator view (the session must be in the oracle's ORACLE_ADMIN_DIDS) ------------------------
+const ADMIN = "/v1/api/admin/sources";
+const adminPath = (sourceId, tail) => `${ADMIN}/${encodeURIComponent(sourceId)}/${tail}`;
+const sourceOut = (body) => out(body, [sourceLine(body)]);
+async function adminSources({ api }) {
+    const items = await allPages(api, "adminListSources", ADMIN);
+    return out({ items }, items.length === 0 ? ["no sources on this oracle"] : items.map(sourceLine));
+}
+async function adminPause({ api, values, positionals, gate }) {
+    const id = required(positionals[0], "api admin pause needs <sourceId>");
+    gate(`pause source ${id}`, values.note ? [`note    : ${values.note}`] : []);
+    return sourceOut(await api("adminPauseSource", "POST", adminPath(id, "pause"), values.note ? { note: values.note } : {}));
+}
+async function adminResume({ api, positionals, gate }) {
+    const id = required(positionals[0], "api admin resume needs <sourceId>");
+    gate(`resume source ${id}`, []);
+    return sourceOut(await api("adminResumeSource", "POST", adminPath(id, "resume")));
+}
+async function adminProtocols({ api, values, positionals, gate }) {
+    const usage = "api admin protocols needs <sourceId> <did,…> (or --none)";
+    const id = required(positionals[0], usage);
+    // `--none` is the explicit empty list: the server takes `[]` as "nothing is allowed on this lane",
+    // which an empty positional could only say by accident.
+    if (values.none && positionals[1] !== undefined) {
+        throw new UsageError("api admin protocols takes <did,…> or --none, not both");
+    }
+    const dids = values.none ? [] : list(required(positionals[1], usage));
+    gate(`replace source ${id}'s allowed protocols`, dids.length === 0
+        ? ["protocols: NONE — the source can submit nothing"]
+        : dids.map((did) => `protocol: ${did}`));
+    const protocols = dids.map((protocolDid) => ({ protocolDid }));
+    return sourceOut(await api("adminSetSourceProtocols", "PUT", adminPath(id, "protocols"), { protocols }));
+}
+async function adminBillingMode({ api, positionals, gate }) {
+    const [id, billingMode] = positionals;
+    if (!id || (billingMode !== "x402" && billingMode !== "none")) {
+        throw new UsageError("api admin billing-mode needs <sourceId> x402|none");
+    }
+    gate(`set source ${id}'s billing mode`, [`mode    : ${billingMode}`]);
+    return sourceOut(await api("adminSetSourceBillingMode", "PUT", adminPath(id, "billing-mode"), {
+        billingMode,
+    }));
+}
+// --- review billing ("Pay for reviews", contracts 1.22.0; routes/v1/api/review-billing.ts) -------
+const REVIEW_BILLING = "/v1/api/source/review-billing";
+/**
+ * The Decision Console's "Pay for reviews" from a terminal: the session — the organisation's
+ * CURRENT chain owner, since the facilitator debits the signer's own credits — signs one standing
+ * x402-ixo-pay payment delegation (`billing/pay` on `billing:decision-api`, `nb: { maxAmount, denom:
+ * upay, oracles: [this oracle] }`, to the facilitator's did:web, ~100 years) and PUTs it on the
+ * source. Everything the oracle would refuse for a reason the caller can fix is checked first —
+ * the oracle's plan (`/v1/info`), the source's billing mode, the owner on chain, the cap against the
+ * price — so a dry run is the whole answer; the oracle re-checks all of it, and the signature.
+ * The token is then deposited in the UCAN store (fail-soft): the store revokes by CID only a
+ * delegation it holds, and the oracle never hands the token back, so that is what lets `disable`
+ * revoke it.
+ */
+async function reviewBillingEnable({ api, values, gate, session, network, oracleUrl, }) {
+    const sourceId = required(values.source, "api review-billing enable needs --source <id>");
+    const maxAmount = upayFromPay(values.cap ?? DEFAULT_CAP_PAY, "--cap");
+    const info = await oracleInfo(oracleUrl);
+    const billing = info.reviewBilling;
+    if (billing?.mode !== "x402") {
+        refuse(`this oracle does not bill reviews per review (its /v1/info reviewBilling.mode is ${billing?.mode ?? "absent"}): IXO switches that on in the oracle's plan. Until then its collections pay by an on-chain evaluation payment.`);
+    }
+    const price = billing.pricePerReview?.amount ??
+        refuse("this oracle publishes no per-review price, so it cannot bill reviews. Ask its operator.");
+    if (BigInt(maxAmount) < BigInt(price)) {
+        refuse(`--cap ${pay(maxAmount)} PAY is below the price of one review (${pay(price)} PAY).`);
+    }
+    const source = (await api("getMe", "GET", "/v1/api/me", undefined, sourceId)).source;
+    if (source.billingMode !== "x402") {
+        refuse(`source ${sourceId} is not billed (billing mode ${source.billingMode}), so it cannot pay for reviews. Ask the oracle's operator to bill it.`);
+    }
+    const entityDid = source.companyEntityDid ?? refuse(`source ${sourceId} is linked to no organisation.`);
+    const owner = (await resolveEntity(NETWORKS[network].blocksync, entityDid)).owner;
+    const ownerDid = owner ? `did:ixo:${owner}` : null;
+    if (ownerDid !== session.did) {
+        refuse(`you are not the organisation's owner on chain, so you cannot pay for its reviews: ${entityDid} is owned by ${ownerDid ?? "no account Blocksync knows"}, and you are logged in as ${session.did}. Reviews are charged to the signer's own credits, so the owner signs: log in as the owner (decision-oracle login) and run this again.`);
+    }
+    const facilitatorDid = `did:web:${new URL(NETWORKS[network].facilitator).host}`;
+    const expiration = Math.floor(Date.now() / 1000) + REVIEW_BILLING_LIFE_SEC;
+    gate(`pay for source ${sourceId}'s reviews from your credits (sign a payment delegation)`, [
+        `entity  : ${entityDid} (you own it on chain)`,
+        `payer   : ${session.did} — each review is charged to YOUR credits`,
+        `to      : ${facilitatorDid} (billing/pay on billing:decision-api)`,
+        `bound   : nb.oracles = ["${info.serviceDid}"] — only this oracle can charge it`,
+        `price   : ${pay(price)} PAY a review`,
+        `cap     : ${pay(maxAmount)} PAY (${maxAmount} upay), about ${BigInt(maxAmount) / BigInt(price)} review(s)`,
+        "          a LIFETIME total: every review adds to what it has spent, and nothing is ever",
+        "          refunded or reset. When it runs low, run enable again with a higher --cap: the new",
+        "          delegation replaces this one and starts again from 0 spent.",
+        `expires : ${new Date(expiration * 1000).toISOString().slice(0, 10)} (~100 years)`,
+        `then    : PUT ${REVIEW_BILLING}, then a copy to the UCAN store (so disable can revoke it)`,
+    ]);
+    const { signerFromMnemonic } = await import("@ixo/ucan");
+    const { buildPaymentDelegation } = await import("@ixo/x402-ixo-pay");
+    const { signer } = await signerFromMnemonic(session.edSigningMnemonic ?? fail("AuthHub session has no edSigningMnemonic — re-run login"), session.did);
+    const delegation = await buildPaymentDelegation({
+        issuer: signer,
+        facilitatorDid,
+        maxAmount,
+        expiration,
+        oracles: [info.serviceDid],
+    });
+    await api("setReviewBilling", "PUT", REVIEW_BILLING, { delegation }, sourceId);
+    const deposit = await storeCall(session, network, "store/add", "/api/delegations", {
+        token: delegation,
+        note: `review billing: source ${sourceId} on ${info.serviceDid}`,
+    });
+    const status = (await api("getReviewBilling", "GET", REVIEW_BILLING, undefined, sourceId));
+    return out(status, [
+        `review billing is on for source ${sourceId}`,
+        ...reviewBillingLines(status),
+        ...(deposit.ok
+            ? []
+            : [
+                `warning: the UCAN store did not take a copy (${deposit.detail}), so disable cannot`,
+                "revoke it there; disable still stops it here, and only this oracle can charge it.",
+            ]),
+    ]);
+}
+async function reviewBillingStatus({ find, values }) {
+    const sourceId = required(values.source, "api review-billing status needs --source <id>");
+    const status = (await find("getReviewBilling", REVIEW_BILLING, sourceId));
+    if (!status) {
+        return out(null, [
+            `source ${sourceId} holds no review-billing delegation (or this oracle does not bill reviews`,
+            `per review). Turn it on with: decision-oracle api review-billing enable --source ${sourceId}`,
+        ]);
+    }
+    return out(status, reviewBillingLines(status));
+}
+/**
+ * Drops the source's delegation (`DELETE`: this oracle stops charging it, and its collections'
+ * reviews pause), then revokes it in the UCAN store — the full stop the route's answer asks for,
+ * since the facilitator checks every payment delegation against the store's revocations. The store
+ * revokes by CID only a delegation it holds (`enable` deposits one) and only for an issuer in its
+ * chain, so one signed by someone else, or stored from the Console, is left for its signer to
+ * revoke, and the output says so. A revocation is permanent: enable signs a new delegation.
+ */
+async function reviewBillingDisable({ api, find, values, gate, session, network, }) {
+    const sourceId = required(values.source, "api review-billing disable needs --source <id>");
+    const held = (await find("getReviewBilling", REVIEW_BILLING, sourceId));
+    if (!held) {
+        return out({ deleted: false, revoked: false }, [
+            `source ${sourceId} holds no review-billing delegation (or this oracle does not bill reviews`,
+            "per review): nothing to disable.",
+        ]);
+    }
+    const mine = held.payer === session.did;
+    gate(`stop paying for source ${sourceId}'s reviews`, [
+        `payer   : ${held.payer}`,
+        `cid     : ${held.delegationCid}`,
+        `spent   : ${pay(held.spent)} of ${pay(held.maxAmount)} PAY`,
+        `then    : DELETE ${REVIEW_BILLING}: this oracle stops charging it, and its`,
+        "          collections' reviews pause until a delegation is stored again",
+        mine
+            ? "and     : REVOKE it in the UCAN store, permanently (enable signs a new one)"
+            : `and     : no revoke here: only its signer (${held.payer}) can revoke it`,
+    ]);
+    const deleted = await api("deleteReviewBilling", "DELETE", REVIEW_BILLING, undefined, sourceId);
+    const revoke = mine
+        ? await storeCall(session, network, "store/revoke", "/api/revocations", {
+            cid: held.delegationCid,
+            reason: `review billing disabled: source ${sourceId}`,
+        })
+        : null;
+    const lines = [`review billing is off for source ${sourceId}`];
+    if (revoke?.ok) {
+        lines.push(`revoked ${held.delegationCid} in the UCAN store`);
+    }
+    else {
+        lines.push(revoke === null
+            ? `not revoked: ${held.payer} signed it, not you.`
+            : revoke.status === 404
+                ? "not revoked: the UCAN store holds no copy (it was not stored by this CLI)."
+                : `not revoked: the UCAN store answered ${revoke.detail}.`, "It stays valid until it expires, but only this oracle can charge it and this oracle no", "longer holds it. For a full stop, its signer revokes it in the Decision Console.");
+    }
+    return out({ ...deleted, revoked: revoke?.ok === true, delegationCid: held.delegationCid }, lines);
+}
+/** The public `/v1/info`: whether this oracle bills reviews, at what price, and its did:web. */
+async function oracleInfo(oracleUrl) {
+    const url = `${oracleUrl}/v1/info`;
+    const res = await fetch(url);
+    const text = await res.text();
+    if (!res.ok)
+        refused(res.status, url, text);
+    return JSON.parse(text);
+}
+/** One self-signed call to the network's UCAN store (`{ can, with: ixo:ucan-store }`, a fresh
+ *  invocation each time: the store refuses a replay). Never throws — the caller says what a miss
+ *  means. */
+async function storeCall(session, network, can, path, body) {
+    const storeUrl = NETWORKS[network].ucanStore;
+    try {
+        const { token } = await sessionInvocation(session, storeUrl, "UCAN store", () => ({
+            can,
+            with: "ixo:ucan-store",
+        }));
+        const res = await fetch(`${storeUrl}${path}`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const text = await res.text();
+        const message = jsonOrUndefined(text)?.message;
+        return {
+            ok: res.ok,
+            status: res.status,
+            detail: `${res.status} ${message ?? text.slice(0, 200)}`,
+        };
+    }
+    catch (err) {
+        return { ok: false, status: 0, detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+function reviewBillingLines(b) {
+    const credits = b.credits
+        ? `${pay(b.credits.available)} PAY available`
+        : "not read yet (after the first review is reserved)";
+    const prices = b.pricePerReview.map((p) => `${pay(p.amount)} PAY (${p.protocolDid})`);
+    const paused = b.pausedCollections.map((p) => `${p.collectionId} ${p.reason} since ${p.since}`);
+    return [
+        `state   : ${b.state}`,
+        `payer   : ${b.payer}`,
+        `cap     : ${pay(b.maxAmount)} PAY lifetime — spent ${pay(b.spent)}, remaining ${pay(b.remaining)}`,
+        `expires : ${b.expiresAt}`,
+        `credits : ${credits}`,
+        `price   : ${prices.length === 0 ? "none published" : prices.join(", ")}`,
+        `paused  : ${paused.length === 0 ? "none" : paused.join(", ")}`,
+        `cid     : ${b.delegationCid}`,
+    ];
+}
+/** A PAY figure ("100", "12.5") → the upay integer string a delegation carries (1 PAY = 10^6). */
+function upayFromPay(value, flag) {
+    const match = /^(\d+)(?:\.(\d{1,6}))?$/.exec(value.trim());
+    const upay = match
+        ? BigInt(match[1]) * 1000000n + BigInt((match[2] ?? "").padEnd(6, "0"))
+        : 0n;
+    if (upay <= 0n)
+        throw new UsageError(`${flag} must be a positive PAY amount, at most 6 decimals`);
+    return upay.toString();
+}
+/** upay → PAY for display, exact (no float). */
+function pay(upay) {
+    const n = BigInt(upay);
+    const fraction = (n % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+    return `${n / 1000000n}${fraction ? `.${fraction}` : ""}`;
+}
+// --- the shared plumbing ------------------------------------------------------------------------
+/** The API refused; the envelope is already printed. Exit 1. */
+class Refused extends Error {
+}
+/** A refusal of the CLI's own, before anything is signed: the reason on stderr, exit 1. */
+function refuse(message) {
+    console.error(`error: ${message}`);
+    throw new Refused();
+}
+function jsonOrUndefined(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Prints a refusal's §4.1 envelope — code, message, requestId (the engine answers the same
+ *  shape) — or the status and the start of a body that is not one, and ends the command (exit 1). */
+function refused(status, url, text) {
+    const err = jsonOrUndefined(text)?.error;
+    console.error(err?.code
+        ? `error: ${err.code} — ${err.message ?? ""}${err.requestId ? ` (requestId ${err.requestId})` : ""}`
+        : `error: ${status} from ${url}: ${text.slice(0, 200)}`);
+    throw new Refused();
+}
+/**
+ * Parses the common flags plus `options`, resolves the oracle URL and the session, runs `command`
+ * with an `api()` that signs each call as a console invocation and returns the 2xx body, and prints
+ * what it hands back. A refusal prints the §4.1 envelope — code, message, requestId — and exits 1.
+ */
+async function call(argv, options, command) {
+    const { values, positionals } = parse(argv, { options: { ...COMMON, ...options } });
+    const flag = values.kit;
+    const envFile = values["env-file"];
+    // The raw project vars (no config validation) — only the network is read off them when `--kit`
+    // names the oracle. Without `--kit` the project must load as a Config, and when it does not, its
+    // own error (which var, where) is the answer — never "no project".
+    let vars;
+    try {
+        vars = readProjectEnv(process.cwd(), { envFile });
+    }
+    catch {
+        vars = undefined;
+    }
+    if (!flag && !vars) {
+        throw new UsageError("api needs --kit <url> (no project .dev.vars to read it from)");
+    }
+    const oracleUrl = oracleUrlFor({
+        kit: flag,
+        devVars: flag ? undefined : loadProjectConfig({ envFile }),
+    });
+    const network = resolveNetwork(values.network ?? vars?.IXO_NETWORK);
+    const session = await loadSession(network);
+    const request = async (op, method, path, payload, sourceId) => {
+        const { res } = await kitFetch(session, oracleUrl, path, {
+            method,
+            ...(payload !== undefined ? { body: JSON.stringify(payload) } : {}),
+            headers: {
+                ...(sourceId ? { "x-source-id": sourceId } : {}),
+                // A fresh key per write (§4.1): the same request re-sent after a lost answer is a replay,
+                // never a second source or key.
+                ...(method === "GET" ? {} : { "idempotency-key": crypto.randomUUID() }),
+            },
+        }, {
+            op,
+            resource: sourceId ? (oracleDid) => sourceResource(oracleDid, sourceId) : oracleResource,
+        });
+        return { status: res.status, ok: res.ok, text: await res.text() };
+    };
+    const body2xx = (path, { status, ok, text }) => {
+        if (!ok)
+            refused(status, `${oracleUrl}${path}`, text);
+        if (status === 204)
+            return {};
+        const body = jsonOrUndefined(text);
+        if (body === undefined || body === null || typeof body !== "object") {
+            throw new Error(`${oracleUrl}${path} answered ${status} with a non-JSON body`);
+        }
+        return body;
+    };
+    const api = async (op, method, path, payload, sourceId) => body2xx(path, await request(op, method, path, payload, sourceId));
+    const find = async (op, path, sourceId) => {
+        const answer = await request(op, "GET", path, undefined, sourceId);
+        return answer.status === 404 ? null : body2xx(path, answer);
+    };
+    const gate = (action, planLines) => confirm({ network, signer: session.did, action, lines: [`oracle  : ${oracleUrl}`, ...planLines] }, values.yes === true, {
+        proceeding: "sending…",
+        ...(values.json ? { print: (line) => console.error(line) } : {}),
+    });
+    let result;
+    try {
+        result = await command({
+            api,
+            find,
+            values: values,
+            positionals,
+            gate,
+            session,
+            network,
+            oracleUrl,
+        });
+    }
+    catch (err) {
+        if (err instanceof Refused)
+            return 1;
+        throw err;
+    }
+    if (values.json)
+        console.log(JSON.stringify(result.raw, null, 2));
+    else
+        for (const line of result.text)
+            console.log(line);
+    return 0;
+}
+const out = (raw, text) => ({ raw, text });
+function required(value, message) {
+    if (!value)
+        throw new UsageError(message);
+    return value;
+}
+const list = (value) => value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+function integer(value, flag) {
+    if (!/^\d+$/.test(value))
+        throw new UsageError(`${flag} must be a whole number`);
+    return Number(value);
+}
+/** The 8-char lookup prefix out of a bare prefix, the masked form a listing prints
+ *  (`eo_test_7f3a9c1d_…`) or a whole key — only the prefix ever leaves this function. */
+function keyPrefix(value) {
+    const match = /^eo_(?:live|test)_([0-9a-z]{8})(?:_.*)?$/.exec(value) ?? /^([0-9a-z]{8})$/.exec(value);
+    if (!match?.[1]) {
+        throw new UsageError("api key revoke needs an 8-char key prefix, or the masked key (eo_…_<prefix>_…)");
+    }
+    return match[1];
+}
+function sourceLine(s) {
+    const status = s.status === "paused" ? `paused (${s.pausedReason})` : s.status;
+    return `${s.sourceId}  "${s.name}"  ${status}  billing=${s.billingMode}  protocols=${s.allowedProtocols.length}  owner=${s.ownerDid}`;
+}
+function keyLine(k) {
+    const cap = k.maxSpendCentsPerDay === null ? "" : `  cap=${k.maxSpendCentsPerDay}¢/day`;
+    const revoked = k.revokedAt ? `  revoked=${k.revokedAt}` : "";
+    return `${k.masked}  [${k.scopes.join(",")}]${k.name ? `  "${k.name}"` : ""}${cap}  last used ${k.lastUsedAt ?? "never"}${revoked}`;
+}
+//# sourceMappingURL=api.js.map