@dvmkit/sdk 0.0.0 → 0.1.0-rc.1

package/dist/revenue-reporter-M35KP6V7.js

@@ -0,0 +1,435 @@
+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"
+};
+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);
+  }
+  /**
+   * 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.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
+};