@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/payments/refund.js

@@ -0,0 +1,123 @@
+/**
+ * A card payment's refund on the claim's charge row (S3/S6: the console must not offer Refund
+ * twice). Read from the facilitator — `GET /v1/card/refunds/:claimId`, the Stripe refunds it has
+ * for the claim — never on the console's word. PAY has no refund: its transfer is final.
+ *
+ *   - `refreshRefund`: one claim, now (S3's refresh route).
+ *   - `refreshRefunds`: the reconcile's arm — card charges paid in the last REFUND_WINDOW_DAYS,
+ *     each asked again at most every REFUND_RECHECK_MS, REFUND_BATCH per run; so a refund made
+ *     anywhere (the console, the operator's Stripe dashboard, a dispute) lands unasked.
+ *
+ * `refunded` when what was refunded (succeeded + pending) covers the claim's own cents, else
+ * `partially_refunded`; nothing refunded (none, or a refund canceled or failed) is `paid` again.
+ */
+import { and, asc, eq, gt, inArray, isNull, lt, or, sql } from "drizzle-orm";
+import { apiCharges } from "../../db/schema.js";
+import { createFacilitatorClient } from "./facilitator.js";
+import { chargeTerms } from "./terms.js";
+/** A card payment can be refunded or disputed for months: Stripe's dispute window is 120 days. */
+export const REFUND_WINDOW_DAYS = 120;
+export const REFUND_RECHECK_MS = 60 * 60_000;
+export const REFUND_BATCH = 25;
+/** A PAY charge is marked checked once, forever: there is nothing to refund. */
+const NEVER = new Date("9999-12-31T00:00:00Z");
+const PAID_STATES = ["paid", "refunded", "partially_refunded"];
+export async function refreshRefund(deps, claimId, now = new Date()) {
+    const { db } = deps;
+    const charge = await db.query.apiCharges.findFirst({ where: eq(apiCharges.claimId, claimId) });
+    if (!charge)
+        return { status: "skipped", reason: "no_charge" };
+    if (chargeTerms(charge).scheme !== "stripe-manual-capture") {
+        return { status: "skipped", reason: "not_card" };
+    }
+    if (!PAID_STATES.includes(charge.status)) {
+        return { status: "skipped", reason: "not_paid" };
+    }
+    const read = await createFacilitatorClient(deps).refunds(claimId);
+    if (!read) {
+        // Not a paid card claim of ours at the facilitator: nothing to record (and never an error).
+        await db
+            .update(apiCharges)
+            .set({ refundCheckedAt: now })
+            .where(eq(apiCharges.claimId, claimId));
+        return { status: "skipped", reason: "unknown_to_facilitator" };
+    }
+    if (!read.refunded || read.refundedAmountCents <= 0) {
+        await db
+            .update(apiCharges)
+            .set({
+            status: "paid",
+            refundedAt: null,
+            refundId: null,
+            refundedAmountCents: null,
+            refundCheckedAt: now,
+        })
+            .where(and(eq(apiCharges.claimId, claimId), inArray(apiCharges.status, [...PAID_STATES])));
+        if (charge.status !== "paid") {
+            deps.logger.warn("payments.refund.reverted", { claimId, was: charge.status });
+        }
+        return { status: "paid" };
+    }
+    // Counted as the facilitator counts them: succeeded, pending, and a dashboard refund (no status).
+    const live = read.refunds.filter((r) => r.status === null || r.status === "succeeded" || r.status === "pending");
+    const latest = [...(live.length > 0 ? live : read.refunds)].sort((a, b) => (a.at ?? "") < (b.at ?? "") ? 1 : -1)[0];
+    const status = read.refundedAmountCents >= charge.amountCents ? "refunded" : "partially_refunded";
+    await db
+        .update(apiCharges)
+        .set({
+        status,
+        refundedAt: latest?.at ? new Date(latest.at) : now,
+        refundId: latest?.refundId ?? null,
+        refundedAmountCents: read.refundedAmountCents,
+        refundCheckedAt: now,
+    })
+        .where(and(eq(apiCharges.claimId, claimId), inArray(apiCharges.status, [...PAID_STATES])));
+    if (charge.status !== status || charge.refundedAmountCents !== read.refundedAmountCents) {
+        deps.logger.info("payments.refunded", {
+            claimId,
+            status,
+            refundedAmountCents: read.refundedAmountCents,
+            amountCents: charge.amountCents,
+        });
+    }
+    return { status, refundedAmountCents: read.refundedAmountCents };
+}
+/** The reconcile's refund arm (see the top). Returns how many charges it asked about. */
+export async function refreshRefunds(deps, now = new Date(), batch = REFUND_BATCH) {
+    const { db } = deps;
+    const due = await db
+        .select({
+        claimId: apiCharges.claimId,
+        amount: apiCharges.amount,
+        amountCents: apiCharges.amountCents,
+        scheme: apiCharges.scheme,
+        paymentHeader: apiCharges.paymentHeader,
+    })
+        .from(apiCharges)
+        .where(and(inArray(apiCharges.status, [...PAID_STATES]), gt(apiCharges.createdAt, new Date(now.getTime() - REFUND_WINDOW_DAYS * 86_400_000)), or(isNull(apiCharges.refundCheckedAt), lt(apiCharges.refundCheckedAt, new Date(now.getTime() - REFUND_RECHECK_MS)))))
+        .orderBy(sql `${apiCharges.refundCheckedAt} IS NOT NULL`, asc(apiCharges.refundCheckedAt))
+        .limit(batch);
+    let checked = 0;
+    let refunded = 0;
+    for (const row of due) {
+        if (chargeTerms(row).scheme !== "stripe-manual-capture") {
+            await db
+                .update(apiCharges)
+                .set({ refundCheckedAt: NEVER })
+                .where(eq(apiCharges.claimId, row.claimId));
+            continue;
+        }
+        try {
+            const outcome = await refreshRefund(deps, row.claimId, now);
+            checked += 1;
+            if (outcome.status === "refunded" || outcome.status === "partially_refunded")
+                refunded += 1;
+        }
+        catch (err) {
+            // The facilitator could not be asked: the next run tries again (the row was not touched).
+            deps.logger.warn("payments.refund.unreadable", { claimId: row.claimId, detail: String(err) });
+        }
+    }
+    return { checked, refunded };
+}
+//# sourceMappingURL=refund.js.map

package/dist/lib/payments/refund.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.js","sourceRoot":"","sources":["../../../src/lib/payments/refund.ts"],"names":[],"mappings":"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"}

package/dist/lib/payments/review-billing.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Per-review checker billing for CHAIN claims (owner, 2026-10-14; switched on by IXO's plan for the
+ * oracle, `planAllowsReviewBilling`): an
+ * organisation pays for each review of its collections' claims from its own subscription credits,
+ * over the same x402 facilitator the Decision API pays through — instead of an evaluation payment
+ * escrowed on the collection. The evaluation fee is never escrowed: verify reserves this oracle's
+ * published price (`publishedPrice`, the Agent Card's), settle takes it on the engine's receipt.
+ *
+ * The standing authority is ONE x402-ixo-pay payment delegation per organisation, stored on its
+ * Decision API source (`PUT /v1/api/source/review-billing`, `review_billing_delegations`): signed
+ * by the organisation's CURRENT chain owner (the facilitator debits the issuer's subscription deed),
+ * addressed to the facilitator, bound to this oracle alone. Per claim the oracle wraps it into the
+ * x402 `PaymentPayload` of a fresh offer — the facilitator accepts it from the resource server (the
+ * nonce binds the offer, `nb.oracles` binds the caller).
+ *
+ * This module: the switch, the delegation at rest (sealed with `WEBHOOK_ENCRYPTION_KEY`), the
+ * prices, the view the Console reads, and per claim: who pays (`resolvePayer`, fresh every time),
+ * whether their credits cover a review (`creditsCover`, register's gate), the reservation before
+ * the decision (`reserveChainClaim`) and its release when no receipt will ever come
+ * (`releaseChainClaim`). Settle and extend are the API lane's own (settle.ts, extend.ts), keyed by
+ * the charge row.
+ */
+import type { Config } from "../../config.js";
+import type { Price, ReviewBilling, ReviewBillingState } from "../../contracts/index.js";
+import type { Database } from "../../db/client.js";
+import { type ApiSource, type ReviewBillingDelegation } from "../../db/schema.js";
+import { type EmailLaneDeps } from "../api-lane/member-emails.js";
+import type { CollectionCompany } from "../engine/types.js";
+import { AppError } from "../errors.js";
+import { type FacilitatorDeps, type ReleaseReason, type UpayBalances } from "./facilitator.js";
+/**
+ * Whether IXO's plan for this oracle allows per-review billing — the ONLY switch (owner,
+ * 2026-10-14: an oracle never turns it on by itself): the engine's `GET /v1/oracles/me`
+ * `reviewBilling`, absent ⇒ false, KV-cached 5 minutes. The facilitator holds the real lock
+ * (it refuses a chain-lane reservation for an oracle whose plan does not allow it); this keeps the
+ * oracle from offering what it cannot sell. Throws on engine trouble.
+ */
+export declare function planAllowsReviewBilling(deps: Pick<FacilitatorDeps, "config" | "logger" | "trace" | "cache">): Promise<boolean>;
+/**
+ * Per-review billing is ACTIVE when IXO's plan allows it, on an oracle running the Decision API
+ * lane (the paying sources are its). Not active ⇒ the routes 404, `GET /v1/info` says `escrow`,
+ * register keeps its evaluation-payment gate. Never throws: a plan the engine cannot tell reads as
+ * not active (nothing is offered).
+ */
+export declare function reviewBillingActive(deps: Pick<FacilitatorDeps, "config" | "logger" | "trace" | "cache">): Promise<boolean>;
+/** The pauses only a payer can lift (`watched_collections.pausedReason`). */
+export declare const PAYER_PAUSES: readonly ["payer-credits", "payer-delegation"];
+export type PayerPause = (typeof PAYER_PAUSES)[number];
+/**
+ * Every review-billing pause: the payer's two, and `oracle-plan` — the facilitator says IXO's plan
+ * does not let this oracle bill reviews (`review_billing_not_allowed`, `plan_inactive`): IXO's to
+ * fix (paged), never the payer's (no notice), lifted when the plan allows again.
+ */
+export declare const BILLING_PAUSES: readonly ["payer-credits", "payer-delegation", "oracle-plan"];
+export type BillingPause = (typeof BILLING_PAUSES)[number];
+/** A delegation must still have this long to run when it is stored. */
+export declare const MIN_DELEGATION_LIFE_MS = 86400000;
+/** The stored delegation (base64 CAR), opened — for the per-claim payment only. */
+export declare const delegationOf: (config: Pick<Config, "WEBHOOK_ENCRYPTION_KEY">, row: Pick<ReviewBillingDelegation, "delegationCiphertext">) => Promise<string>;
+/** What a PUT stores, the delegation already checked (routes/v1/api/review-billing.ts). */
+export interface StoredDelegation {
+    sourceId: string;
+    payerDid: string;
+    delegationCid: string;
+    maxAmount: string;
+    expiresAt: Date;
+    notBefore: Date | null;
+    delegation: string;
+    createdBy: string;
+}
+/**
+ * Upsert the source's one row. The same CID again keeps what it has spent; a new one starts at 0,
+ * as the facilitator's per-CID count does.
+ */
+export declare function storeDelegation(db: Database, config: Pick<Config, "WEBHOOK_ENCRYPTION_KEY">, d: StoredDelegation): Promise<ReviewBillingDelegation>;
+export interface ReviewPrice {
+    protocolDid: string;
+    amount: string;
+    amountCents: number;
+}
+/**
+ * Every published per-review price this oracle can name a protocol for: its `supportedProtocols`,
+ * the protocols `pricing.api.byProtocol` lists and `watched` (the per-review collections'
+ * protocols, `perReviewProtocols`) — what the Console shows beside the cap.
+ */
+export declare function pricesPerReview(config: Pick<Config, "API_PRICE_USD_CENTS">, watched?: readonly string[]): ReviewPrice[];
+/**
+ * The protocols of the watched chain collections billed per review here (`billingSourceId` set) —
+ * one source's when `sourceId` is given. An open oracle (`supportedProtocols: []`, a protocol per
+ * ask) charges these too, so the facilitator must find their price on the public route.
+ */
+export declare function perReviewProtocols(db: Database, sourceId?: string): Promise<string[]>;
+/**
+ * The one per-review price the oracle advertises (`GET /v1/info` `reviewBilling`, the Agent Card):
+ * the price its supported protocols share, else the protocol-independent default
+ * (`pricing.api.amountMicroUsd`, then `API_PRICE_USD_CENTS`); null when it publishes none.
+ */
+export declare function advertisedPrice(config: Pick<Config, "API_PRICE_USD_CENTS">): string | null;
+/** The lowest price a review here can cost — a delegation's cap must cover at least one. */
+export declare function lowestPrice(config: Pick<Config, "API_PRICE_USD_CENTS">): bigint | null;
+/**
+ * Where the stored delegation stands: `expired` past its `exp`, `exhausted` when what is left
+ * covers no review, `payer_not_owner` when its signer is no longer the organisation's chain owner
+ * (`ownerDid` — null when the chain could not be read, which never flips the state), else `active`.
+ */
+export declare function stateOf(config: Pick<Config, "API_PRICE_USD_CENTS">, row: ReviewBillingDelegation, ownerDid: string | null, now?: Date): ReviewBillingState;
+/** The Console's one read (`GET`/`PUT /v1/api/source/review-billing`) — never the delegation. */
+export declare function reviewBillingView(deps: {
+    db: Database;
+    config: Pick<Config, "API_PRICE_USD_CENTS">;
+}, row: ReviewBillingDelegation, extra: {
+    ownerDid: string | null;
+    credits: UpayBalances | null;
+}, now?: Date): Promise<ReviewBilling>;
+/**
+ * A chain claim id the facilitator can key a reservation by (x402-ixo-pay 0.7.0, S4's final rule):
+ * a CIDv1 in lowercase base32 (multibase `b`), any codec. The package checks the form only (it has
+ * no CID decoder), so this mirrors its regex exactly. A Matrix event id (`$…`), a UUID or a CIDv0
+ * (`Qm…`) is refused: such a claim gets no offer (`unbillable-claim-id`).
+ */
+export declare const CHAIN_CLAIM_ID: RegExp;
+export interface BillingDeps extends FacilitatorDeps {
+    db: Database;
+}
+/** Who pays for one claim's review, resolved fresh. */
+export interface Payer {
+    source: ApiSource;
+    row: ReviewBillingDelegation;
+    price: Price;
+}
+/**
+ * Why no one can pay: `none` (no live delegation for the company: none stored, expired, its
+ * signer no longer the owner, its cap used up, no published price) or `disputed` (the engine
+ * cannot say which organisation the collection is). `detail` is for a log line.
+ */
+export type NoPayer = {
+    ok: false;
+    why: "none" | "disputed";
+    detail: string;
+};
+/** Trouble reading who pays (the engine, the chain): retry, never a guess. */
+export declare class PayerUnavailable extends AppError {
+    readonly reason: "company_unavailable" | "credits_unavailable";
+    constructor(reason: "company_unavailable" | "credits_unavailable", message: string, cause?: unknown);
+}
+/** The collection's company, as the ENGINE derives it — never guessed; null for an unknown one. */
+export declare function companyOf(deps: Pick<FacilitatorDeps, "config" | "logger" | "trace" | "cache">, collectionId: string): Promise<CollectionCompany | null>;
+/**
+ * Who pays for a review of `collectionId`'s claims under `protocolDid` (owner rulings 2026-10-14):
+ * its company (the engine's answer, `company`) → that organisation's source holding a live
+ * review-billing delegation → still signed by the organisation's CURRENT chain owner (read
+ * uncached) → this oracle's published price → a cap that still covers it.
+ */
+export declare function resolvePayer(deps: BillingDeps, company: CollectionCompany | null, protocolDid: string, now?: Date): Promise<({
+    ok: true;
+} & Payer) | NoPayer>;
+/**
+ * The payer's credits as the facilitator holds them, read WITH the stored delegation (0.7.0). Both
+ * what a new reservation could take now and what is left of the cap must cover `price`. A read
+ * the facilitator refuses or cannot answer is `credits_unavailable` — never a guess.
+ */
+export declare function creditsCover(deps: BillingDeps, payer: Payer): Promise<boolean>;
+/**
+ * What a reservation came to: reserved; or why not — a pause only the payer can lift, a retry (a
+ * fresh offer next attempt), or a failure no retry fixes.
+ */
+export type Reserved = {
+    ok: true;
+} | {
+    ok: false;
+    pause: BillingPause;
+    detail: string;
+} | {
+    ok: false;
+    retry: true;
+    detail: string;
+} | {
+    ok: false;
+    fail: true;
+    detail: string;
+};
+/**
+ * Reserve this oracle's published price for ONE chain claim before it is decided (never decide
+ * without a reservation): an offer for the claim (`lane: chain`, its collection), the stored
+ * delegation wrapped into the offer's `PaymentPayload`, `/verify`. The charge row is written
+ * `offered` BEFORE `/verify`, in the same batch as the spend on the delegation's mirror, so a retry
+ * re-verifies the SAME header (the facilitator is idempotent per offer) and never offers twice. A
+ * refusal deletes the row and gives the spend back (nothing was reserved), then says what to do.
+ * Called only once the facts lane has built (the claim WILL be decided), so a facts-lane
+ * `unusable` / `invalid_facts` never spends the cap. Throws only on trouble the step retries.
+ */
+export declare function reserveChainClaim(deps: BillingDeps, payer: Payer, claim: {
+    claimId: string;
+    collectionId: string;
+    protocolDid: string;
+}): Promise<Reserved>;
+/**
+ * Free a chain claim's reservation that will never get a receipt (the facts lane could not build
+ * after it was reserved, the engine refused the claim, the run gave up) — the facilitator gives the
+ * amount back to the deed AND the delegation's cap, so the mirror gives it back too. NEVER throws:
+ * an outage or a refusal leaves the reservation to lapse on its own (24 h; its cap not returned).
+ */
+export declare function releaseChainClaim(deps: BillingDeps, claimId: string, reason: ReleaseReason): Promise<void>;
+/**
+ * The expiry reminders (owner, 2026-10-14): every stored delegation ending within 30 days gets
+ * its payer emailed at the 30-day and the 7-day mark, once each (`emailReviewBillingExpiring`'s
+ * dedupe). Hourly, bounded, soonest first; one ending later than 30 days out (a 100-year one)
+ * never gets one. Returns how many it looked at.
+ */
+export declare function remindExpiringDelegations(deps: EmailLaneDeps, now?: Date): Promise<number>;
+/**
+ * The "cap almost used" warnings (owner, 2026-10-14): a live delegation whose `spent` has crossed
+ * 80% of its cap gets its payer emailed once, and once more at 95% (`rb_cap:<cid>:<80|95>`, the
+ * expiry reminders' dedupe). Keyed by the CID, so a new delegation — a raised cap — starts its own
+ * pair. Hourly, beside the expiry reminders: a reservation never waits on an email. Only rows
+ * whose current stage has no `sent` / `sending` row are read, so warned rows never crowd out new
+ * ones. Returns how many it looked at.
+ */
+export declare function remindCapDelegations(deps: EmailLaneDeps & {
+    config: Pick<Config, "API_PRICE_USD_CENTS">;
+}, now?: Date): Promise<number>;
+//# sourceMappingURL=review-billing.d.ts.map

package/dist/lib/payments/review-billing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-billing.d.ts","sourceRoot":"","sources":["../../../src/lib/payments/review-billing.ts"],"names":[],"mappings":"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"}