@dvmkit/sdk 0.0.0 → 0.1.0-rc.2

package/dist/postgres-consumed-credential-store-VHBT4KEA.js

@@ -0,0 +1,72 @@
+import {
+  withSdkInitLock
+} from "./chunk-S3XAHZQY.js";
+
+// src/sdk/server/postgres-consumed-credential-store.ts
+var DEFAULT_TABLE_NAME = "consumed_credentials";
+var DEFAULT_GC_SAMPLE_RATE = 0.01;
+var VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var PostgresConsumedCredentialStore = class {
+  pool;
+  tableName;
+  gcSampleRate;
+  now;
+  constructor(pool, opts) {
+    const tableName = opts?.tableName ?? DEFAULT_TABLE_NAME;
+    if (!VALID_IDENTIFIER.test(tableName)) {
+      throw new Error(
+        `PostgresConsumedCredentialStore: tableName must match ${VALID_IDENTIFIER.source}, got "${tableName}"`
+      );
+    }
+    this.pool = pool;
+    this.tableName = tableName;
+    this.gcSampleRate = opts?.gcSampleRate ?? DEFAULT_GC_SAMPLE_RATE;
+    this.now = opts?.now ?? (() => Date.now());
+  }
+  /** Run the CREATE TABLE migration. Idempotent — safe to call repeatedly. */
+  async init() {
+    await withSdkInitLock(this.pool, () => this.createTables());
+  }
+  /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
+  async createTables() {
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        realm        TEXT NOT NULL,
+        challenge_id TEXT NOT NULL,
+        expires_at   BIGINT NOT NULL,
+        PRIMARY KEY (realm, challenge_id)
+      );
+      CREATE INDEX IF NOT EXISTS ${this.tableName}_expires_at_idx
+        ON ${this.tableName} (expires_at);
+    `);
+  }
+  async has(realm, challengeId) {
+    const { rowCount } = await this.pool.query(
+      `SELECT 1 FROM ${this.tableName}
+       WHERE realm = $1 AND challenge_id = $2 AND expires_at > $3`,
+      [realm, challengeId, this.now()]
+    );
+    return (rowCount ?? 0) > 0;
+  }
+  async mark(realm, challengeId, ttlSeconds) {
+    const now = this.now();
+    const expiresAt = now + ttlSeconds * 1e3;
+    await this.pool.query(
+      `INSERT INTO ${this.tableName} (realm, challenge_id, expires_at)
+       VALUES ($1, $2, $3)
+       ON CONFLICT (realm, challenge_id) DO UPDATE SET expires_at = EXCLUDED.expires_at`,
+      [realm, challengeId, expiresAt]
+    );
+    if (this.gcSampleRate > 0 && Math.random() < this.gcSampleRate) {
+      this.gcSweep(now);
+    }
+  }
+  gcSweep(now) {
+    this.pool.query(`DELETE FROM ${this.tableName} WHERE expires_at < $1`, [now]).catch((err) => {
+      console.error("PostgresConsumedCredentialStore GC sweep failed:", err);
+    });
+  }
+};
+export {
+  PostgresConsumedCredentialStore
+};

package/dist/postgres-job-store-J5F4GUWU.js

@@ -0,0 +1,7 @@
+import {
+  PostgresJobStore
+} from "./chunk-6JZIX5WW.js";
+import "./chunk-S3XAHZQY.js";
+export {
+  PostgresJobStore
+};

package/dist/postgres-kv-store-JFBDP5IP.js

@@ -0,0 +1,7 @@
+import {
+  PostgresKVStore
+} from "./chunk-FROTD5XQ.js";
+import "./chunk-S3XAHZQY.js";
+export {
+  PostgresKVStore
+};

package/dist/postgres-replay-store-UJXRT6VO.js

@@ -0,0 +1,7 @@
+import {
+  PostgresReplayStore
+} from "./chunk-L4OYF4DQ.js";
+import "./chunk-S3XAHZQY.js";
+export {
+  PostgresReplayStore
+};

package/dist/pricing-4CEB34RM.js

@@ -0,0 +1,48 @@
+import {
+  DEFAULT_FX_CURRENCIES,
+  DEFAULT_FX_RATE_SOURCE,
+  FX_CACHE_TTL_MS,
+  FX_RETRY_COUNT,
+  FxRateUnavailableError,
+  InvalidCurrencyError,
+  UnsupportedCurrencyError,
+  buildUpfront,
+  createFxFetcher,
+  fxRateFor,
+  resolveFxSourceFromEnv,
+  validateCurrency,
+  warmFxSnapshot
+} from "./chunk-27V2ILSR.js";
+import {
+  InvalidFxRateError,
+  InvalidUsdPriceError,
+  fiatToSatsCeil,
+  formatFiat,
+  formatUsd,
+  parseUsdPrice,
+  roundUsd,
+  satsToFiat
+} from "./chunk-AT6V3SY7.js";
+export {
+  DEFAULT_FX_CURRENCIES,
+  DEFAULT_FX_RATE_SOURCE,
+  FX_CACHE_TTL_MS,
+  FX_RETRY_COUNT,
+  FxRateUnavailableError,
+  InvalidCurrencyError,
+  InvalidFxRateError,
+  InvalidUsdPriceError,
+  UnsupportedCurrencyError,
+  buildUpfront,
+  createFxFetcher,
+  fiatToSatsCeil,
+  formatFiat,
+  formatUsd,
+  fxRateFor,
+  parseUsdPrice,
+  resolveFxSourceFromEnv,
+  roundUsd,
+  satsToFiat,
+  validateCurrency,
+  warmFxSnapshot
+};

package/dist/processed-payment-store-HAA4SFNK.js

@@ -0,0 +1,11 @@
+import {
+  MemoryProcessedPaymentStore,
+  PostgresProcessedPaymentStore,
+  ProcessedPaymentReplayError
+} from "./chunk-DMNLFNTW.js";
+import "./chunk-S3XAHZQY.js";
+export {
+  MemoryProcessedPaymentStore,
+  PostgresProcessedPaymentStore,
+  ProcessedPaymentReplayError
+};

package/dist/revenue-reporter-GB4WKLDC.js

@@ -0,0 +1,510 @@
+import {
+  withSdkInitLock
+} from "./chunk-S3XAHZQY.js";
+
+// src/sdk/server/revenue-reporter.ts
+import { randomUUID } from "crypto";
+var ENDPOINTS = {
+  revenue: "/_internal/job-revenue",
+  deposit: "/_internal/credit-deposit",
+  release: "/_internal/credit-draw-release",
+  drain: "/_internal/credit-drain",
+  payout: "/_internal/payout",
+  expiry_release: "/_internal/credit-expiry-release"
+};
+var RevenueReporter = class _RevenueReporter {
+  // 24h of failed retries
+  constructor(db, platformUrl, platformToken) {
+    this.db = db;
+    this.platformUrl = platformUrl;
+    this.platformToken = platformToken;
+  }
+  db;
+  platformUrl;
+  platformToken;
+  retryTimer = null;
+  static RETRY_INTERVAL_MS = 3e4;
+  static MAX_BACKOFF_MS = 3e5;
+  // 5 min
+  static ABANDON_AFTER_MS = 24 * 60 * 60 * 1e3;
+  /** Create the pending-reports table (idempotent). */
+  async init() {
+    await withSdkInitLock(this.db, () => this.createTables());
+  }
+  /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
+  async createTables() {
+    await this.db.query(`
+      CREATE TABLE IF NOT EXISTS pending_revenue_reports (
+        id            TEXT PRIMARY KEY,
+        payload       JSONB NOT NULL,
+        retry_count   INTEGER NOT NULL DEFAULT 0,
+        next_retry_at BIGINT NOT NULL DEFAULT 0,
+        stale         BOOLEAN NOT NULL DEFAULT false,
+        stale_reason  TEXT,
+        created_at    BIGINT NOT NULL,
+        kind          TEXT NOT NULL DEFAULT 'revenue'
+      )
+    `);
+    await this.db.query(
+      "ALTER TABLE pending_revenue_reports ADD COLUMN IF NOT EXISTS stale_reason TEXT"
+    );
+    await this.db.query(
+      "ALTER TABLE pending_revenue_reports ADD COLUMN IF NOT EXISTS kind TEXT NOT NULL DEFAULT 'revenue'"
+    );
+  }
+  /** Persist a revenue report and attempt immediate delivery. */
+  async report(payload) {
+    return this.enqueue("revenue", payload, payload.jobId);
+  }
+  /**
+   * Join a credit deposit to the caller-owned rail transaction.
+   *
+   * This method performs no network I/O: it only writes the reporter-owned
+   * durable queue row through `tx`. The retry drain delivers the row after the
+   * rail transaction commits, including after a process restart.
+   */
+  async enqueueDeposit(tx, payload) {
+    await this.insertPending(tx, "deposit", payload);
+  }
+  /** Join a released draw to the transaction that made the hold terminal. */
+  async enqueueCreditDrawRelease(tx, payload) {
+    await this.insertPending(tx, "release", payload);
+  }
+  /**
+   * Join a credit drain to the transaction that made it terminal (internal-review).
+   *
+   * Same discipline as {@link enqueueDeposit} and the same reason: no network
+   * I/O here, only the durable queue row, written through `tx` so the report
+   * and the status CAS commit or roll back together. A drain whose row was
+   * lost between the two would overstate outstanding liability forever —
+   * the mirror image of a lost deposit.
+   *
+   * Named for the payload rather than the verb because `drain` already means
+   * "flush the queue" in this class (see {@link drainPending}).
+   */
+  async enqueueCreditDrain(tx, payload) {
+    await this.insertPending(tx, "drain", payload);
+  }
+  /**
+   * Join a payout to the transaction that commits the movement it reports
+   * (internal-review) — the batch close, the accumulator mark, the drain booking.
+   * No network I/O, only the durable queue row through `tx`, the discipline
+   * {@link enqueueCreditDrain} set and for the same reason: the money has
+   * already moved on a rail this ledger does not own, so the platform row is
+   * the only record the builder's dashboard has of it, and a row lost between
+   * the fact and the queue would understate "paid out" forever. Without `tx`
+   * the row is queued on the pool, for callers with no fact of their own to
+   * commit. Idempotent on `(dvmId, payoutId)` platform-side, so the retry
+   * loop redelivers freely.
+   */
+  async enqueuePayout(payload, tx) {
+    await this.insertPending(tx ?? this.db, "payout", payload);
+  }
+  /**
+   * Report one landed payout on its own and try to deliver it at once — the
+   * live Tempo settlement, which has no dvmkit transaction to join. Durable
+   * like {@link report}.
+   */
+  async reportPayout(payload) {
+    return this.enqueue("payout", payload, payload.payoutId);
+  }
+  /**
+   * Report one rail's pending-pool snapshot (internal-review). Best-effort and
+   * fire-and-forget, deliberately unlike {@link reportPayout}: a snapshot is
+   * replaced by the next tick, so queueing a stale one behind an outage would
+   * only deliver figures the platform already has newer ones for.
+   */
+  async reportPayoutPending(payload) {
+    const url = `${this.platformUrl}/_internal/payout-pending`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.platformToken}`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) {
+        console.warn(
+          JSON.stringify({
+            level: "payout_pending_report_failed",
+            rail: payload.rail,
+            status: res.status
+          })
+        );
+      }
+    } catch (err) {
+      console.warn(
+        JSON.stringify({
+          level: "payout_pending_report_failed",
+          rail: payload.rail,
+          error: err instanceof Error ? err.message : String(err)
+        })
+      );
+    }
+  }
+  /**
+   * Join a credit-expiry release — or the revival that reverses one — to the
+   * transaction that made it true (internal-review).
+   *
+   * Same discipline as {@link enqueueCreditDrain}: no network I/O, only the
+   * durable queue row written through `tx`. A release whose row was lost after
+   * the sweep committed would understate committed value forever; a lost
+   * reversal would overstate it, which is the worse direction — the builder
+   * would see money as theirs that a revived credit can still buy work with.
+   */
+  async enqueueCreditExpiryRelease(tx, payload) {
+    await this.insertPending(tx, "expiry_release", payload);
+  }
+  /**
+   * Report a reaper-force-failed paid job to the platform (internal-review) so the
+   * operator receives an ambient notice that a DVM died or wedged mid-job.
+   * Best-effort and fire-and-forget: unlike {@link report} there is no local
+   * durable queue — a non-2xx or transport failure is structured-logged
+   * (`paid_job_death_report_failed`) and dropped, since the reaper's own
+   * `stale_job_failed` log is the durable record and a failed *alert* must never
+   * wedge the sweep.
+   */
+  async reportPaidJobDeath(payload) {
+    const url = `${this.platformUrl}/_internal/paid-job-death`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.platformToken}`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) {
+        console.warn(
+          JSON.stringify({
+            level: "paid_job_death_report_failed",
+            jobId: payload.jobId,
+            status: res.status
+          })
+        );
+      }
+    } catch (err) {
+      console.warn(
+        JSON.stringify({
+          level: "paid_job_death_report_failed",
+          jobId: payload.jobId,
+          error: err instanceof Error ? err.message : String(err)
+        })
+      );
+    }
+  }
+  /**
+   * Report a settled draw whose revenue event was skipped (internal-review).
+   * Best-effort and fire-and-forget: the SDK's structured
+   * `revenue_skipped_no_rail` log is the durable backstop, so a failed notice
+   * must never wedge terminal handling or the orphan-draw reconciler.
+   */
+  async reportRevenueSkippedNoRail(payload) {
+    const url = `${this.platformUrl}/_internal/revenue-skipped-no-rail`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.platformToken}`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) {
+        console.warn(
+          JSON.stringify({
+            level: "revenue_skipped_no_rail_report_failed",
+            jobId: payload.jobId,
+            drawId: payload.drawId,
+            reason: payload.reason,
+            status: res.status
+          })
+        );
+      }
+    } catch (err) {
+      console.warn(
+        JSON.stringify({
+          level: "revenue_skipped_no_rail_report_failed",
+          jobId: payload.jobId,
+          drawId: payload.drawId,
+          reason: payload.reason,
+          error: err instanceof Error ? err.message : String(err)
+        })
+      );
+    }
+  }
+  /** Report the self-relay's Base gas gauge for platform-side paging and recovery. */
+  async reportX402SelfRelayGasBalance(payload) {
+    const url = `${this.platformUrl}/_internal/x402-self-relay-gas-balance`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.platformToken}`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) {
+        console.warn(
+          JSON.stringify({
+            level: "x402_self_relay_gas_balance_report_failed",
+            address: payload.address,
+            status: res.status
+          })
+        );
+      }
+    } catch (err) {
+      console.warn(
+        JSON.stringify({
+          level: "x402_self_relay_gas_balance_report_failed",
+          address: payload.address,
+          error: err instanceof Error ? err.message : String(err)
+        })
+      );
+    }
+  }
+  /** Report redacted self-relay RPC health for platform-side paging and recovery. */
+  async reportX402SelfRelayRpcHealth(payload) {
+    const url = `${this.platformUrl}/_internal/x402-self-relay-rpc-health`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.platformToken}`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) {
+        console.warn(
+          JSON.stringify({
+            level: "x402_self_relay_rpc_health_report_failed",
+            address: payload.address,
+            status: res.status
+          })
+        );
+      }
+    } catch {
+      console.warn(
+        JSON.stringify({
+          level: "x402_self_relay_rpc_health_report_failed",
+          address: payload.address,
+          reason: "transport"
+        })
+      );
+    }
+  }
+  /** Report the Tempo operator's fee-token gauge for paging and recovery. */
+  async reportTempoSettlementBalance(payload) {
+    await this.postTempoSettlementReadiness("balance", payload);
+  }
+  /** Report a redacted operator fee rejection immediately. */
+  async reportTempoSettlementFailure(payload) {
+    await this.postTempoSettlementReadiness("failure", payload);
+  }
+  async postTempoSettlementReadiness(kind, payload) {
+    const url = `${this.platformUrl}/_internal/tempo-settlement-${kind}`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.platformToken}`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) {
+        console.warn(
+          JSON.stringify({
+            level: "tempo_settlement_readiness_report_failed",
+            kind,
+            address: payload.address,
+            status: res.status
+          })
+        );
+      }
+    } catch {
+      console.warn(
+        JSON.stringify({
+          level: "tempo_settlement_readiness_report_failed",
+          kind,
+          address: payload.address,
+          reason: "transport"
+        })
+      );
+    }
+  }
+  /** Start the background retry loop. */
+  startRetryLoop() {
+    if (this.retryTimer) return;
+    this.retryTimer = setInterval(() => {
+      void this.drainPending();
+    }, _RevenueReporter.RETRY_INTERVAL_MS);
+  }
+  /** Stop the background retry loop. */
+  stop() {
+    if (this.retryTimer) {
+      clearInterval(this.retryTimer);
+      this.retryTimer = null;
+    }
+  }
+  /**
+   * Operator-facing queue snapshot: distinguishes the live retry queue from
+   * terminal (stale) rows and breaks the latter down by classification reason
+   * (`token_rotated`, `client_error:<status>`, `abandoned`). Lets monitoring tell
+   * transient backlog apart from permanently-failed rows.
+   */
+  async getQueueStats() {
+    const { rows } = await this.db.query(
+      `SELECT stale, stale_reason, COUNT(*)::int AS count
+       FROM pending_revenue_reports
+       GROUP BY stale, stale_reason`
+    );
+    let liveRetry = 0;
+    let stale = 0;
+    const byReason = {};
+    for (const row of rows) {
+      const count = Number(row.count);
+      if (row.stale) {
+        stale += count;
+        const reason = row.stale_reason ?? "unknown";
+        byReason[reason] = (byReason[reason] ?? 0) + count;
+      } else {
+        liveRetry += count;
+      }
+    }
+    return { liveRetry, stale, byReason };
+  }
+  /**
+   * Deliver one bounded batch from the durable queue.
+   *
+   * Public so startup/recovery tests and operator tooling can drive the same
+   * drain the background timer uses without reaching into private state.
+   */
+  async drainPending() {
+    try {
+      const { rows } = await this.db.query(
+        `SELECT id, payload, retry_count, created_at, kind FROM pending_revenue_reports
+         WHERE stale = false AND next_retry_at <= $1
+         ORDER BY created_at LIMIT 10`,
+        [Date.now()]
+      );
+      for (const row of rows) {
+        const label = row.payload.jobId ?? row.payload.creditId ?? row.payload.payoutId ?? row.id;
+        try {
+          await this.attemptDelivery(row.id, row.payload, row.kind, label);
+        } catch {
+          const retryCount = row.retry_count + 1;
+          if (Date.now() - Number(row.created_at) >= _RevenueReporter.ABANDON_AFTER_MS) {
+            await this.markStale(row.id, "abandoned");
+            console.warn(
+              JSON.stringify({
+                level: "revenue_reporter_abandoned",
+                id: row.id,
+                kind: row.kind,
+                retryCount,
+                dvmId: row.payload.dvmId,
+                label,
+                // A drain names its payout rail `method`; every other kind
+                // carries `rail`. An abandoned row is the one place an
+                // operator sees this payload at all, so don't log it blank.
+                rail: row.payload.rail ?? row.payload.method
+              })
+            );
+            continue;
+          }
+          const backoff = Math.min(
+            3e4 * Math.pow(2, retryCount - 1),
+            _RevenueReporter.MAX_BACKOFF_MS
+          );
+          await this.db.query(
+            `UPDATE pending_revenue_reports
+             SET retry_count = $1, next_retry_at = $2
+             WHERE id = $3`,
+            [retryCount, Date.now() + backoff, row.id]
+          );
+        }
+      }
+    } catch (err) {
+      console.error("[revenue-reporter] Retry loop error:", err);
+    }
+  }
+  /** Durably queue one report of either kind, then try it once immediately. */
+  async enqueue(kind, payload, label) {
+    const id = await this.insertPending(this.db, kind, payload);
+    void this.attemptDelivery(id, payload, kind, label).catch(() => {
+    });
+  }
+  /** Insert one pending report through either the pool or an open transaction. */
+  async insertPending(q, kind, payload) {
+    const id = randomUUID();
+    await q.query(
+      `INSERT INTO pending_revenue_reports (id, payload, created_at, kind)
+       VALUES ($1, $2, $3, $4)`,
+      [id, JSON.stringify(payload), Date.now(), kind]
+    );
+    return id;
+  }
+  async attemptDelivery(id, payload, kind, label) {
+    const url = `${this.platformUrl}${ENDPOINTS[kind]}`;
+    let res;
+    try {
+      res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.platformToken}`
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      console.warn(
+        `[revenue-reporter] delivery failed for ${id}: transport error (${reason}) \u2014 will retry`
+      );
+      throw err;
+    }
+    if (res.ok) {
+      await this.db.query("DELETE FROM pending_revenue_reports WHERE id = $1", [id]);
+      console.log(`[revenue-reporter] reported ${kind} ${label}`);
+      return;
+    }
+    if (res.status === 401) {
+      await this.markStale(id, "token_rotated");
+      console.warn(
+        `[revenue-reporter] Report ${id} got 401 \u2014 marking stale (token likely rotated)`
+      );
+      return;
+    }
+    if (res.status >= 400 && res.status < 500) {
+      await this.markStale(id, `client_error:${res.status}`);
+      console.warn(
+        `[revenue-reporter] Report ${id} got HTTP ${res.status} \u2014 marking stale (permanent client error, will not retry)`
+      );
+      return;
+    }
+    console.warn(`[revenue-reporter] delivery failed for ${id}: HTTP ${res.status} \u2014 will retry`);
+    throw new Error(`Platform returned ${res.status}`);
+  }
+  /** Mark a pending row terminal (stale) with a classification reason. */
+  async markStale(id, reason) {
+    await this.db.query(
+      "UPDATE pending_revenue_reports SET stale = true, stale_reason = $1 WHERE id = $2",
+      [reason, id]
+    );
+  }
+};
+export {
+  RevenueReporter
+};