@naulon/sdk 0.1.0

package/dist/crypto/fixture.d.ts

@@ -0,0 +1,13 @@
+import type { SettlementBody } from "../contract/settlement.ts";
+export declare function makeSignedSettlementFixture(opts: {
+    secret: string;
+    body?: SettlementBody;
+    now?: number;
+}): {
+    rawBody: string;
+    headers: {
+        "x-naulon-timestamp": string;
+        "x-naulon-signature": string;
+    };
+};
+//# sourceMappingURL=fixture.d.ts.map

package/dist/crypto/fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../src/crypto/fixture.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAwBhE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE;QAAE,oBAAoB,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAS/F"}

package/dist/crypto/fixture.js

@@ -0,0 +1,39 @@
+/**
+ * Offline conformance helper. A publisher feeds the output into THEIR own receiver
+ * in THEIR test harness and asserts a 200 + a written payout — proving their
+ * integration without ever POSTing to production (there is no dry-run path; a
+ * money receiver gets no public "pretend" mode). The CLI prints this fixture.
+ */
+import { signSettlement } from "./sign.js";
+/** A valid sample body (Σ splits === gross, exactly one primary) — passes settlementBodySchema. */
+const SAMPLE_BODY = {
+    eventId: "11111111-2222-4333-8444-555555555555",
+    slug: "on-stillness",
+    txHash: "0xfeed",
+    chainId: 5042002,
+    currency: "USDC",
+    grossAmount: "5000",
+    paidTo: "0x1111111111111111111111111111111111111111",
+    payer: "0x3333333333333333333333333333333333333333",
+    settledAt: "2023-11-14T22:13:20.000Z",
+    splits: [
+        {
+            authorId: "mira",
+            wallet: "0x1111111111111111111111111111111111111111",
+            amount: "5000",
+            weight: 1000,
+            primary: true,
+        },
+    ],
+};
+export function makeSignedSettlementFixture(opts) {
+    const body = opts.body ?? SAMPLE_BODY;
+    const rawBody = JSON.stringify(body);
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const { timestamp, signature } = signSettlement(rawBody, opts.secret, now);
+    return {
+        rawBody,
+        headers: { "x-naulon-timestamp": timestamp, "x-naulon-signature": signature },
+    };
+}
+//# sourceMappingURL=fixture.js.map

package/dist/crypto/fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.js","sourceRoot":"","sources":["../../src/crypto/fixture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,mGAAmG;AACnG,MAAM,WAAW,GAAmB;IAClC,OAAO,EAAE,sCAAsC;IAC/C,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,OAAO;IAChB,QAAQ,EAAE,MAAM;IAChB,WAAW,EAAE,MAAM;IACnB,MAAM,EAAE,4CAAwE;IAChF,KAAK,EAAE,4CAAwE;IAC/E,SAAS,EAAE,0BAA0B;IACrC,MAAM,EAAE;QACN;YACE,QAAQ,EAAE,MAAM;YAChB,MAAM,EAAE,4CAAwE;YAChF,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,IAAI;SACd;KACF;CACF,CAAC;AAEF,MAAM,UAAU,2BAA2B,CAAC,IAI3C;IACC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,WAAW,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACtD,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3E,OAAO;QACL,OAAO;QACP,OAAO,EAAE,EAAE,oBAAoB,EAAE,SAAS,EAAE,oBAAoB,EAAE,SAAS,EAAE;KAC9E,CAAC;AACJ,CAAC"}

package/dist/crypto/sign.d.ts

@@ -0,0 +1,7 @@
+/** Headers the receiver verifies: a unix-seconds timestamp and the HMAC. */
+export interface SignedSettlement {
+    timestamp: string;
+    signature: string;
+}
+export declare function signSettlement(rawBody: string, secret: string, unixSeconds: number): SignedSettlement;
+//# sourceMappingURL=sign.d.ts.map

package/dist/crypto/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../src/crypto/sign.ts"],"names":[],"mappings":"AAUA,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAKlB"}

package/dist/crypto/sign.js

@@ -0,0 +1,15 @@
+/**
+ * HMAC signing of the settlement body — the producer half of the trust boundary.
+ *
+ * Pure: no fetch, no ambient clock. The caller passes the unix-seconds timestamp
+ * and signs the EXACT raw body bytes it will send — serialize once, sign that
+ * string, send that string. The receiver recomputes HMAC-SHA256(`${ts}.${body}`)
+ * and rejects a mismatch (401) or a timestamp skewed past the window.
+ */
+import { createHmac } from "node:crypto";
+export function signSettlement(rawBody, secret, unixSeconds) {
+    const timestamp = String(unixSeconds);
+    const signature = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
+    return { timestamp, signature };
+}
+//# sourceMappingURL=sign.js.map

package/dist/crypto/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../../src/crypto/sign.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQzC,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,MAAc,EACd,WAAmB;IAEnB,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACtC,MAAM,SAAS,GACb,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3F,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC"}

package/dist/crypto/verify.d.ts

@@ -0,0 +1,21 @@
+import { type SettlementBody } from "../contract/settlement.ts";
+/** Max clock skew (seconds) between the signer and the receiver. */
+export declare const MAX_SKEW_SECONDS = 300;
+export type VerifyResult = {
+    ok: true;
+    event: SettlementBody;
+} | {
+    ok: false;
+    status: 400 | 401;
+    reason: string;
+};
+export declare function verifySettlement(opts: {
+    rawBody: string;
+    timestampHeader: string | null;
+    signatureHeader: string | null;
+    /** 1..n secrets; >1 during a rotation overlap. */
+    secrets: string[];
+    /** Injectable clock (unix seconds) for tests; defaults to now. */
+    now?: number;
+}): VerifyResult;
+//# sourceMappingURL=verify.d.ts.map

package/dist/crypto/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/crypto/verify.ts"],"names":[],"mappings":"AAcA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEtF,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBrD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kDAAkD;IAClD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,YAAY,CA4Bf"}

package/dist/crypto/verify.js

@@ -0,0 +1,58 @@
+/**
+ * HMAC verification of the settlement body — the verify half, written once here
+ * instead of hand-rolled per publisher. Authenticity + freshness + shape, in the
+ * order the gate's retry semantics depend on:
+ *
+ *   401 = TRANSIENT (the gate retries) — signature/clock problems.
+ *   400 = PERMANENT (the gate gives up) — a malformed body; retrying won't help.
+ *
+ * Get those status codes wrong and you change the gate's retry behavior, so they
+ * are pinned by tests. This proves AUTHENTICITY only; exactly-once PERSISTENCE is
+ * the receiver's job (see IdempotencyStore) — the skew window means an authentic
+ * POST is replayable for its whole duration.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { settlementBodySchema } from "../contract/settlement.js";
+/** Max clock skew (seconds) between the signer and the receiver. */
+export const MAX_SKEW_SECONDS = 300;
+/** Constant-time compare of the provided signature against each candidate secret
+ *  (the array is what makes secret rotation safe — accept old+new during a roll). */
+function signatureMatches(timestamp, rawBody, header, secrets) {
+    const provided = Buffer.from(header);
+    for (const secret of secrets) {
+        const expected = Buffer.from("sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"));
+        if (provided.length === expected.length && timingSafeEqual(provided, expected)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function verifySettlement(opts) {
+    const { rawBody, timestampHeader, signatureHeader, secrets } = opts;
+    if (secrets.length === 0) {
+        throw new Error("verifySettlement: at least one secret is required");
+    }
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (!timestampHeader || !/^\d+$/.test(timestampHeader)) {
+        return { ok: false, status: 401, reason: "bad-timestamp" };
+    }
+    if (Math.abs(now - Number(timestampHeader)) > MAX_SKEW_SECONDS) {
+        return { ok: false, status: 401, reason: "stale-timestamp" };
+    }
+    if (!signatureHeader || !signatureMatches(timestampHeader, rawBody, signatureHeader, secrets)) {
+        return { ok: false, status: 401, reason: "bad-signature" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        return { ok: false, status: 400, reason: "bad-json" };
+    }
+    const result = settlementBodySchema.safeParse(parsed);
+    if (!result.success) {
+        return { ok: false, status: 400, reason: "invalid-event" };
+    }
+    return { ok: true, event: result.data };
+}
+//# sourceMappingURL=verify.js.map

package/dist/crypto/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/crypto/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAuB,MAAM,2BAA2B,CAAC;AAEtF,oEAAoE;AACpE,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAMpC;qFACqF;AACrF,SAAS,gBAAgB,CACvB,SAAiB,EACjB,OAAe,EACf,MAAc,EACd,OAAiB;IAEjB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAC1B,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACzF,CAAC;QACF,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC/E,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAQhC;IACC,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAEtD,IAAI,CAAC,eAAe,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC7D,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,GAAG,gBAAgB,EAAE,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,eAAe,IAAI,CAAC,gBAAgB,CAAC,eAAe,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,CAAC;QAC9F,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC7D,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAiC,EAAE,CAAC;AACvE,CAAC"}

package/dist/doctor/doctor.d.ts

@@ -0,0 +1,27 @@
+export type Level = "pass" | "warn" | "fail";
+export interface DoctorCheck {
+    name: string;
+    level: Level;
+    detail: string;
+}
+export interface DoctorInputs {
+    /** `.env` file contents, or null if it's missing. */
+    envText: string | null;
+    fileExists: (path: string) => boolean;
+    readFile: (path: string) => string;
+    /** Absolute dir the `.env` lives in — resolves a relative CREDITS_FIXTURES. */
+    cwd: string;
+    /** Provide to run live gate probes; omit to skip them (e.g. in a pure unit test). */
+    fetchImpl?: typeof fetch;
+    /** Override where the gate is; defaults to http://localhost:${TOLLGATE_PORT}. */
+    gateUrl?: string;
+}
+export interface DoctorOutcome {
+    checks: DoctorCheck[];
+    /** true when no check FAILED (warnings are allowed). */
+    ok: boolean;
+}
+/** Parse a dotenv-style file into a flat record. Comments + blanks ignored. */
+export declare function parseEnvFile(text: string): Record<string, string>;
+export declare function runDoctor(inp: DoctorInputs): Promise<DoctorOutcome>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/doctor/doctor.ts"],"names":[],"mappings":"AAgCA,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC7C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,wDAAwD;IACxD,EAAE,EAAE,OAAO,CAAC;CACb;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOjE;AAOD,wBAAsB,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAsGzE"}

package/dist/doctor/doctor.js

@@ -0,0 +1,149 @@
+/**
+ * `naulon doctor` — a health check for YOUR OWN gate.
+ *
+ * `naulon-kit check` validates a *remote* publisher's `/credits` endpoint. `doctor` is the
+ * mirror for the operator: is *my* local setup coherent and would it toll correctly? It reads
+ * the `.env`, validates it against the gate's own `configSchema`, confirms the credits source
+ * resolves, sanity-checks the settlement mode, and — if the gate is running — probes it: a human
+ * UA must read free, an agent UA must get a 402. All the logic is here (pure, with injected fs +
+ * fetch) so it is unit-testable without a real filesystem or a running server, matching the
+ * `runCheck` / `check` split.
+ */
+import { z } from "zod";
+import { parseCredits } from "../contract/credits.js";
+/**
+ * The subset of the gate's env that `doctor` reasons about. Deliberately NOT the gate's full
+ * `configSchema` (in `@naulon/shared`, which imports this package — importing it back would
+ * cycle). The gate itself fails loud on deeper config errors at boot; the live probe below
+ * catches real misbehavior. This validates the handful of vars doctor's checks depend on.
+ */
+const doctorEnvSchema = z.object({
+    PAYMENT_MODE: z.enum(["mock", "gateway"]).default("mock"),
+    ORIGIN_URL: z.string().url().default("http://localhost:3000"),
+    TOLLGATE_PORT: z.coerce.number().int().positive().default(8402),
+    ARTICLE_PATH_PREFIXES: z.string().default("essays,articles,posts"),
+    SETTLEMENT_NETWORK: z.enum(["arcTestnet", "baseSepolia", "base"]).default("arcTestnet"),
+    CREDITS_API_URL: z.string().url().optional(),
+    CREDITS_FIXTURES: z.string().optional(),
+    RELAYER_PRIVATE_KEY: z.string().optional(),
+    CIRCLE_API_KEY: z.string().optional(),
+});
+/** Parse a dotenv-style file into a flat record. Comments + blanks ignored. */
+export function parseEnvFile(text) {
+    const env = {};
+    for (const line of text.split("\n")) {
+        const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)$/);
+        if (m && m[1] && !line.trimStart().startsWith("#"))
+            env[m[1]] = (m[2] ?? "").trim();
+    }
+    return env;
+}
+function joinPath(cwd, p) {
+    if (p.startsWith("/"))
+        return p;
+    return `${cwd.replace(/\/$/, "")}/${p.replace(/^\.\//, "")}`;
+}
+export async function runDoctor(inp) {
+    const checks = [];
+    // 1. .env present + valid against the gate's OWN config schema.
+    if (inp.envText === null) {
+        checks.push({ name: "env", level: "fail", detail: "no .env found — run `naulon init`" });
+        return { checks, ok: false };
+    }
+    const parsed = doctorEnvSchema.safeParse(parseEnvFile(inp.envText));
+    if (!parsed.success) {
+        const first = parsed.error.issues[0];
+        checks.push({
+            name: "env",
+            level: "fail",
+            detail: `.env invalid: ${first ? `${first.path.join(".")} — ${first.message}` : "malformed"}`,
+        });
+        return { checks, ok: false };
+    }
+    const cfg = parsed.data;
+    checks.push({
+        name: "env",
+        level: "pass",
+        detail: `valid — mode=${cfg.PAYMENT_MODE} origin=${cfg.ORIGIN_URL} port=${cfg.TOLLGATE_PORT}`,
+    });
+    // 2. Credits source resolves.
+    let firstSlug;
+    if (cfg.CREDITS_API_URL) {
+        checks.push({
+            name: "credits",
+            level: "pass",
+            detail: `API mode → ${cfg.CREDITS_API_URL} (conformance: \`naulon check ${cfg.CREDITS_API_URL} --slug <s>\`)`,
+        });
+    }
+    else if (!cfg.CREDITS_FIXTURES) {
+        checks.push({
+            name: "credits",
+            level: "warn",
+            detail: "neither CREDITS_FIXTURES nor CREDITS_API_URL set — the gate falls back to its bundled default; run `naulon init`",
+        });
+    }
+    else {
+        const path = joinPath(inp.cwd, cfg.CREDITS_FIXTURES);
+        if (!inp.fileExists(path)) {
+            checks.push({ name: "credits", level: "fail", detail: `CREDITS_FIXTURES not found: ${cfg.CREDITS_FIXTURES}` });
+        }
+        else {
+            try {
+                const map = JSON.parse(inp.readFile(path));
+                const slugs = Object.keys(map);
+                for (const s of slugs)
+                    parseCredits(map[s], `credits "${s}"`);
+                firstSlug = slugs[0];
+                checks.push({
+                    name: "credits",
+                    level: slugs.length > 0 ? "pass" : "warn",
+                    detail: slugs.length > 0 ? `${slugs.length} valid entr${slugs.length === 1 ? "y" : "ies"}` : "file is empty — no articles to toll yet",
+                });
+            }
+            catch (e) {
+                checks.push({ name: "credits", level: "fail", detail: `CREDITS_FIXTURES invalid: ${e instanceof Error ? e.message : String(e)}` });
+            }
+        }
+    }
+    // 3. Settlement-mode coherence.
+    if (cfg.PAYMENT_MODE === "mock") {
+        checks.push({ name: "settlement", level: "warn", detail: "mock — payments signed offline, no real USDC. Fine for dev." });
+    }
+    else {
+        const hasRelayer = Boolean(cfg.RELAYER_PRIVATE_KEY);
+        const hasCircle = Boolean(cfg.CIRCLE_API_KEY);
+        const isArcMemo = cfg.SETTLEMENT_NETWORK === "arcTestnet"; // memo self-relay network
+        if (isArcMemo && !hasRelayer) {
+            checks.push({ name: "settlement", level: "warn", detail: `gateway on ${cfg.SETTLEMENT_NETWORK} but RELAYER_PRIVATE_KEY unset — real settle will error at settle-time` });
+        }
+        else if (!isArcMemo && !hasCircle) {
+            checks.push({ name: "settlement", level: "warn", detail: `gateway on ${cfg.SETTLEMENT_NETWORK} but CIRCLE_API_KEY unset` });
+        }
+        else {
+            checks.push({ name: "settlement", level: "pass", detail: `gateway on ${cfg.SETTLEMENT_NETWORK} — settlement creds present` });
+        }
+    }
+    // 4. Live gate probes (only if a fetch impl was provided).
+    if (inp.fetchImpl) {
+        const base = (inp.gateUrl ?? `http://localhost:${cfg.TOLLGATE_PORT}`).replace(/\/$/, "");
+        const prefix = cfg.ARTICLE_PATH_PREFIXES.split(",")[0]?.trim() || "essays";
+        const slug = firstSlug ?? "example";
+        const url = `${base}/${prefix}/${encodeURIComponent(slug)}`;
+        try {
+            const human = await inp.fetchImpl(url, { headers: { "user-agent": "Mozilla/5.0", accept: "text/html" }, redirect: "manual" });
+            checks.push(human.status === 402
+                ? { name: "gate:human", level: "fail", detail: `a human UA was tolled (402) on ${url} — humans must read free` }
+                : { name: "gate:human", level: "pass", detail: `human UA → not tolled (HTTP ${human.status})` });
+            const agent = await inp.fetchImpl(url, { headers: { "user-agent": "python-requests/2.31" }, redirect: "manual" });
+            const challenged = agent.status === 402 && (agent.headers.get("payment-required") !== null || agent.headers.get("link") !== null);
+            checks.push(challenged
+                ? { name: "gate:agent", level: "pass", detail: `agent UA → 402 + payment challenge on /${prefix}/${slug}` }
+                : { name: "gate:agent", level: "warn", detail: `agent UA got HTTP ${agent.status} (expected 402) on /${prefix}/${slug} — check ARTICLE_PATH_PREFIXES + credits` });
+        }
+        catch {
+            checks.push({ name: "gate", level: "warn", detail: `gate not reachable at ${base} — start it: \`make dev\`` });
+        }
+    }
+    return { checks, ok: checks.every((c) => c.level !== "fail") };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor/doctor.js.map

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

package/dist/express/_bridge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Express ⇄ web-standard bridge. The Express adapters are deliberately thin: they
+ * translate an Express `(req, res)` into the web-standard `Request`/`Response` the
+ * Next adapters already speak, then run the SAME handler. One implementation of the
+ * contract logic, two framework skins — no second copy to drift (the SDK's reason
+ * for existing). These structural types avoid a hard `@types/express` dependency:
+ * the adapters work against any Express-shaped req/res.
+ */
+export interface ExpressReqLike {
+    headers: Record<string, string | string[] | undefined>;
+    params: Record<string, string | undefined>;
+    /** Raw request body — a Buffer when the route is mounted with `express.raw()`. */
+    body?: unknown;
+}
+export interface ExpressResLike {
+    status(code: number): ExpressResLike;
+    setHeader(name: string, value: string): void;
+    send(body: string): void;
+}
+export type ExpressHandler = (req: ExpressReqLike, res: ExpressResLike) => Promise<void>;
+/** A single header value (Express folds duplicates to an array; take the first). */
+export declare function headerValue(v: string | string[] | undefined): string | undefined;
+/**
+ * The settlement HMAC is computed over the EXACT request bytes, so the receiver
+ * needs the raw body. `express.raw()` leaves it a Buffer; `express.json()` parses
+ * and discards the bytes (re-serializing changes them and every signature fails).
+ * Fail loud with the fix rather than silently 401 every valid call.
+ */
+export declare function rawBodyOf(body: unknown, who: string): string;
+/** Write a web-standard Response back onto an Express response, headers and all. */
+export declare function pipeResponse(response: Response, res: ExpressResLike): Promise<void>;
+//# sourceMappingURL=_bridge.d.ts.map

package/dist/express/_bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_bridge.d.ts","sourceRoot":"","sources":["../../src/express/_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC;IACrC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzF,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,oFAAoF;AACpF,wBAAsB,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzF"}

package/dist/express/_bridge.js

@@ -0,0 +1,34 @@
+/**
+ * Express ⇄ web-standard bridge. The Express adapters are deliberately thin: they
+ * translate an Express `(req, res)` into the web-standard `Request`/`Response` the
+ * Next adapters already speak, then run the SAME handler. One implementation of the
+ * contract logic, two framework skins — no second copy to drift (the SDK's reason
+ * for existing). These structural types avoid a hard `@types/express` dependency:
+ * the adapters work against any Express-shaped req/res.
+ */
+/** A single header value (Express folds duplicates to an array; take the first). */
+export function headerValue(v) {
+    return Array.isArray(v) ? v[0] : v;
+}
+/**
+ * The settlement HMAC is computed over the EXACT request bytes, so the receiver
+ * needs the raw body. `express.raw()` leaves it a Buffer; `express.json()` parses
+ * and discards the bytes (re-serializing changes them and every signature fails).
+ * Fail loud with the fix rather than silently 401 every valid call.
+ */
+export function rawBodyOf(body, who) {
+    if (Buffer.isBuffer(body))
+        return body.toString("utf8");
+    if (typeof body === "string")
+        return body;
+    throw new Error(`${who}: req.body must be the raw request bytes. Mount this route with ` +
+        `express.raw({ type: "*/*" }) — the HMAC signs the exact bytes, so express.json() ` +
+        `(which parses then discards them) breaks verification.`);
+}
+/** Write a web-standard Response back onto an Express response, headers and all. */
+export async function pipeResponse(response, res) {
+    res.status(response.status);
+    response.headers.forEach((value, name) => res.setHeader(name, value));
+    res.send(await response.text());
+}
+//# sourceMappingURL=_bridge.js.map

package/dist/express/_bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_bridge.js","sourceRoot":"","sources":["../../src/express/_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,oFAAoF;AACpF,MAAM,UAAU,WAAW,CAAC,CAAgC;IAC1D,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAa,EAAE,GAAW;IAClD,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,kEAAkE;QACtE,mFAAmF;QACnF,wDAAwD,CAC3D,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAkB,EAAE,GAAmB;IACxE,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACtE,GAAG,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC"}

package/dist/express/credits-route.d.ts

@@ -0,0 +1,6 @@
+import type { CreditsResolver } from "../resolver/types.ts";
+import { type ExpressHandler } from "./_bridge.ts";
+export declare function createExpressCreditsRoute(resolver: CreditsResolver, opts?: {
+    token?: string;
+}): ExpressHandler;
+//# sourceMappingURL=credits-route.d.ts.map

package/dist/express/credits-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credits-route.d.ts","sourceRoot":"","sources":["../../src/express/credits-route.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,KAAK,cAAc,EAA6B,MAAM,cAAc,CAAC;AAE9E,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,eAAe,EACzB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxB,cAAc,CAWhB"}

package/dist/express/credits-route.js

@@ -0,0 +1,23 @@
+/**
+ * Express credits route — the same minimal `CreditsResolver` framing as the Next
+ * adapter (`../next/credits-route.ts`), wrapped for an Express `(req, res)` route.
+ * Pins the one thing publishers get wrong: `404 = free read`, distinct from a
+ * `200` with credits. Wire it as:
+ *   app.get("/api/credits/:slug", createExpressCreditsRoute(resolver));
+ */
+import { createCreditsRoute } from "../next/credits-route.js";
+import { headerValue, pipeResponse } from "./_bridge.js";
+export function createExpressCreditsRoute(resolver, opts) {
+    const handler = createCreditsRoute(resolver, opts);
+    return async (req, res) => {
+        const slug = req.params.slug ?? "";
+        const headers = new Headers();
+        const auth = headerValue(req.headers["authorization"]);
+        if (auth !== undefined)
+            headers.set("authorization", auth);
+        const request = new Request(`http://credits.local/${encodeURIComponent(slug)}`, { headers });
+        const response = await handler(request, { params: Promise.resolve({ slug }) });
+        await pipeResponse(response, res);
+    };
+}
+//# sourceMappingURL=credits-route.js.map

package/dist/express/credits-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credits-route.js","sourceRoot":"","sources":["../../src/express/credits-route.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAuB,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE9E,MAAM,UAAU,yBAAyB,CACvC,QAAyB,EACzB,IAAyB;IAEzB,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACnD,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;QACvD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7F,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/E,MAAM,YAAY,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC,CAAC;AACJ,CAAC"}

package/dist/express/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@naulon/sdk/express` — Express adapters for publishers on Express instead
+ * of Next. Thin bridges over the framework-neutral handlers, so the contract logic
+ * is identical to `@naulon/sdk/next`. `express` is an optional peer dep; the
+ * adapters use structural req/res types so they need no `@types/express` to build.
+ */
+export { createExpressCreditsRoute } from "./credits-route.ts";
+export { createExpressSettlementReceiver } from "./settlement-receiver.ts";
+export type { ExpressReqLike, ExpressResLike, ExpressHandler } from "./_bridge.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/express/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/express/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/express/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@naulon/sdk/express` — Express adapters for publishers on Express instead
+ * of Next. Thin bridges over the framework-neutral handlers, so the contract logic
+ * is identical to `@naulon/sdk/next`. `express` is an optional peer dep; the
+ * adapters use structural req/res types so they need no `@types/express` to build.
+ */
+export { createExpressCreditsRoute } from "./credits-route.js";
+export { createExpressSettlementReceiver } from "./settlement-receiver.js";
+//# sourceMappingURL=index.js.map

package/dist/express/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/express/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/express/settlement-receiver.d.ts

@@ -0,0 +1,14 @@
+import type { SettlementBody } from "../contract/settlement.ts";
+import type { IdempotencyStore } from "../idempotency.ts";
+import { type ExpressHandler } from "./_bridge.ts";
+export declare function createExpressSettlementReceiver(opts: {
+    /** 1..n shared HMAC secrets; >1 only during a rotation overlap. */
+    secrets: string[];
+    /** Persist the payout here. Runs at most once per eventId (idempotency-gated). */
+    onEvent: (event: SettlementBody) => Promise<void>;
+    /** REQUIRED. memoryIdempotencyStore() is dev-only — back it with a DB unique
+     *  constraint on eventId in production (the 300s skew window makes an authentic
+     *  POST replayable for five minutes). */
+    idempotency: IdempotencyStore;
+}): ExpressHandler;
+//# sourceMappingURL=settlement-receiver.d.ts.map

package/dist/express/settlement-receiver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-receiver.d.ts","sourceRoot":"","sources":["../../src/express/settlement-receiver.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EACL,KAAK,cAAc,EAIpB,MAAM,cAAc,CAAC;AAEtB,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACpD,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;6CAEyC;IACzC,WAAW,EAAE,gBAAgB,CAAC;CAC/B,GAAG,cAAc,CAajB"}

package/dist/express/settlement-receiver.js

@@ -0,0 +1,31 @@
+/**
+ * Express settlement receiver — the same logic as the Next receiver
+ * (`../next/settlement-receiver.ts`), wrapped for an Express `(req, res)` route.
+ * It runs the web-standard handler verbatim, so HMAC verification, the 401/400
+ * retry semantics, and the mandatory exactly-once `IdempotencyStore` behave
+ * identically across both frameworks.
+ *
+ * Mount it with `express.raw()` so the body arrives as raw bytes:
+ *   app.post("/api/credits/settlement",
+ *     express.raw({ type: "*\/*" }),
+ *     createExpressSettlementReceiver({ secrets, onEvent, idempotency }));
+ */
+import { createSettlementReceiver } from "../next/settlement-receiver.js";
+import { headerValue, pipeResponse, rawBodyOf, } from "./_bridge.js";
+export function createExpressSettlementReceiver(opts) {
+    // Reuse the web handler — including its empty-secrets guard (throws here).
+    const handler = createSettlementReceiver(opts);
+    return async (req, res) => {
+        const rawBody = rawBodyOf(req.body, "createExpressSettlementReceiver");
+        const headers = new Headers();
+        const ts = headerValue(req.headers["x-naulon-timestamp"]);
+        const sig = headerValue(req.headers["x-naulon-signature"]);
+        if (ts !== undefined)
+            headers.set("x-naulon-timestamp", ts);
+        if (sig !== undefined)
+            headers.set("x-naulon-signature", sig);
+        const request = new Request("http://settlement.local", { method: "POST", headers, body: rawBody });
+        await pipeResponse(await handler(request), res);
+    };
+}
+//# sourceMappingURL=settlement-receiver.js.map

package/dist/express/settlement-receiver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-receiver.js","sourceRoot":"","sources":["../../src/express/settlement-receiver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAG1E,OAAO,EAEL,WAAW,EACX,YAAY,EACZ,SAAS,GACV,MAAM,cAAc,CAAC;AAEtB,MAAM,UAAU,+BAA+B,CAAC,IAS/C;IACC,2EAA2E;IAC3E,MAAM,OAAO,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,iCAAiC,CAAC,CAAC;QACvE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC;QAC3D,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;QAC5D,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,yBAAyB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACnG,MAAM,YAAY,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/idempotency.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Exactly-once persistence for the settlement receiver — a SEPARATE concern from
+ * `verifySettlement` (which proves authenticity only). The skew window means an
+ * authentic POST is replayable for its whole duration (5 minutes), so a money
+ * receiver without dedupe is a double-payout defect, not a choice. The receiver
+ * adapter therefore REQUIRES one of these.
+ */
+export interface IdempotencyStore {
+    /**
+     * Atomically claim `eventId`. Returns `true` the first time (proceed with the
+     * payout), `false` if it was already seen (a replay — short-circuit to 200).
+     */
+    claim(eventId: string): Promise<boolean>;
+}
+/**
+ * A process-local default so the type is always satisfiable in dev/tests.
+ *
+ * NOT DURABLE. It is lost on restart and useless across instances — any real
+ * deployment MUST back `claim` with its database (a unique constraint on the event
+ * id). Using this in production is a double-payout footgun.
+ */
+export declare function memoryIdempotencyStore(): IdempotencyStore;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CASzD"}