@secondlayer/shared 13.12.0 → 13.13.1

package/dist/src/db/queries/webhook-replays.js

@@ -0,0 +1,156 @@
+// src/db/queries/webhook-replays.ts
+import { sql } from "kysely";
+var STALE_SCAN_MINUTES = 30;
+
+class ReplayInProgressError extends Error {
+  constructor() {
+    super("replay already in progress for this webhook");
+    this.name = "ReplayInProgressError";
+  }
+}
+var ONE_SCANNING_CONSTRAINT = "webhook_replays_one_scanning";
+function isOneScanningConflict(err) {
+  if (!(err instanceof Error))
+    return false;
+  const candidate = err;
+  return candidate.code === "23505" && (candidate.constraint === ONE_SCANNING_CONSTRAINT || candidate.constraint_name === ONE_SCANNING_CONSTRAINT);
+}
+async function beginReplay(db, input) {
+  try {
+    await db.transaction().execute(async (trx) => {
+      await trx.updateTable("webhook_replays").set({
+        status: "failed",
+        error: "scan interrupted",
+        finished_at: sql`now()`
+      }).where("webhook_id", "=", input.webhookId).where("status", "=", "scanning").where("started_at", "<", sql`now() - ${sql.lit(`${STALE_SCAN_MINUTES} minutes`)}::interval`).execute();
+      const row = await trx.insertInto("webhook_replays").values({
+        id: input.id,
+        webhook_id: input.webhookId,
+        from_block: input.fromBlock,
+        to_block: input.toBlock,
+        status: "scanning"
+      }).onConflict((oc) => oc.column("id").doUpdateSet({
+        status: "scanning",
+        started_at: sql`now()`,
+        finished_at: null,
+        error: null,
+        total: null,
+        delivered: null,
+        gave_up: null
+      }).where("webhook_replays.status", "<>", "scanning")).returning("id").executeTakeFirst();
+      if (!row)
+        throw new ReplayInProgressError;
+    });
+  } catch (err) {
+    if (isOneScanningConflict(err))
+      throw new ReplayInProgressError;
+    throw err;
+  }
+}
+async function finishScan(db, id, counts) {
+  await db.updateTable("webhook_replays").set({
+    status: "running",
+    scanned_count: counts.scanned,
+    enqueued_count: sql`enqueued_count + ${counts.enqueued}`
+  }).where("id", "=", id).execute();
+}
+async function failScan(db, id, error) {
+  await db.updateTable("webhook_replays").set({ status: "failed", error, finished_at: sql`now()` }).where("id", "=", id).execute();
+}
+async function pendingCount(db, id) {
+  const row = await db.selectFrom("webhook_outbox").select(sql`count(*)`.as("n")).where("status", "=", "pending").where("replay_id", "=", id).executeTakeFirstOrThrow();
+  return Number(row.n);
+}
+async function deadCount(db, webhookId, id) {
+  const row = await db.selectFrom("webhook_outbox").select(sql`count(*)`.as("n")).where("webhook_id", "=", webhookId).where("replay_id", "=", id).where("status", "=", "dead").executeTakeFirstOrThrow();
+  return Number(row.n);
+}
+function progressOf(record, pending) {
+  const done = record.status === "done";
+  const total = done ? record.total ?? record.enqueued_count : record.enqueued_count;
+  return {
+    replayId: record.id,
+    webhookId: record.webhook_id,
+    status: record.status,
+    fromBlock: Number(record.from_block),
+    toBlock: Number(record.to_block),
+    total,
+    processed: done ? total : Math.max(0, total - pending),
+    pending: done ? 0 : pending,
+    delivered: done ? record.delivered : null,
+    gaveUp: done ? record.gave_up : null,
+    startedAt: record.started_at.toISOString(),
+    finishedAt: record.finished_at ? record.finished_at.toISOString() : null,
+    error: record.error
+  };
+}
+async function progressWithFinalize(db, record) {
+  if (record.status !== "running")
+    return progressOf(record, 0);
+  const pending = await pendingCount(db, record.id);
+  if (pending > 0)
+    return progressOf(record, pending);
+  const dead = await deadCount(db, record.webhook_id, record.id);
+  const finalized = await db.updateTable("webhook_replays").set({
+    status: "done",
+    finished_at: sql`now()`,
+    total: sql`enqueued_count`,
+    gave_up: dead,
+    delivered: sql`enqueued_count - ${dead}`
+  }).where("id", "=", record.id).where("status", "=", "running").returningAll().executeTakeFirst();
+  if (finalized)
+    return progressOf(finalized, 0);
+  const fresh = await db.selectFrom("webhook_replays").selectAll().where("id", "=", record.id).executeTakeFirstOrThrow();
+  return progressOf(fresh, fresh.status === "running" ? await pendingCount(db, fresh.id) : 0);
+}
+async function readReplay(db, webhookId, id) {
+  const record = await db.selectFrom("webhook_replays").selectAll().where("id", "=", id).where("webhook_id", "=", webhookId).executeTakeFirst();
+  return record ? progressWithFinalize(db, record) : null;
+}
+async function listReplays(db, input) {
+  if (input.webhookIds.length === 0)
+    return [];
+  const cutoff = new Date(Date.now() - input.sinceHours * 3600000);
+  const records = await db.selectFrom("webhook_replays").selectAll().where("webhook_id", "in", input.webhookIds).where((eb) => eb.or([
+    eb("status", "in", ["scanning", "running"]),
+    eb("started_at", ">", cutoff)
+  ])).orderBy("started_at", "desc").limit(input.limit).execute();
+  return Promise.all(records.map((r) => progressWithFinalize(db, r)));
+}
+async function listWebhookReplays(db, webhookId, limit) {
+  const records = await db.selectFrom("webhook_replays").selectAll().where("webhook_id", "=", webhookId).orderBy("started_at", "desc").limit(limit).execute();
+  return Promise.all(records.map((r) => progressWithFinalize(db, r)));
+}
+async function finalizeReplays(db) {
+  const running = await db.selectFrom("webhook_replays").selectAll().where("status", "=", "running").execute();
+  for (const record of running)
+    await progressWithFinalize(db, record);
+}
+async function deadSince(db, webhookId, since) {
+  let q = db.selectFrom("webhook_outbox").select(sql`count(*)`.as("n")).where("webhook_id", "=", webhookId).where("status", "=", "dead");
+  if (since)
+    q = q.where("failed_at", ">=", since);
+  return Number((await q.executeTakeFirstOrThrow()).n);
+}
+async function knownEventsInRange(db, webhookId, from, to) {
+  const row = await db.selectFrom("webhook_outbox").select(sql`count(*)`.as("n")).where("webhook_id", "=", webhookId).where("block_height", ">=", from).where("block_height", "<=", to).executeTakeFirstOrThrow();
+  return Number(row.n);
+}
+export {
+  ReplayInProgressError,
+  beginReplay,
+  deadCount,
+  deadSince,
+  failScan,
+  finalizeReplays,
+  finishScan,
+  knownEventsInRange,
+  listReplays,
+  listWebhookReplays,
+  pendingCount,
+  progressOf,
+  readReplay
+};
+
+//# debugId=E8EBA311948ADE2B64756E2164756E21
+//# sourceMappingURL=webhook-replays.js.map

package/dist/src/db/queries/webhook-replays.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/db/queries/webhook-replays.ts"],
+  "sourcesContent": [
+    "import { type Kysely, sql } from \"kysely\";\nimport type { ReplayProgress } from \"../../schemas/webhooks.ts\";\nimport type { Database, WebhookReplay } from \"../types.ts\";\n\n/**\n * Stored record of each webhook replay. A replay is `scanning` while the\n * request scans its block range, `running` once its outbox rows exist, `done`\n * when none are pending, `failed` if the scan threw or the process died.\n *\n * Progress while running is `enqueued - pending`, where pending is counted\n * through the existing partial index on pending outbox rows (`webhook_outbox`\n * has no index on `replay_id` on purpose). Rows that gave up are counted once,\n * when the replay finalizes.\n */\n\n/** A `scanning` row older than this is a crashed process, not a live scan. */\nconst STALE_SCAN_MINUTES = 30;\n\n/** Thrown by {@link beginReplay} when a replay is still scanning for the\n *  webhook. The route maps this to 409; `force` does not bypass it. */\nexport class ReplayInProgressError extends Error {\n\tconstructor() {\n\t\tsuper(\"replay already in progress for this webhook\");\n\t\tthis.name = \"ReplayInProgressError\";\n\t}\n}\n\nconst ONE_SCANNING_CONSTRAINT = \"webhook_replays_one_scanning\";\n\nfunction isOneScanningConflict(err: unknown): boolean {\n\tif (!(err instanceof Error)) return false;\n\tconst candidate = err as Error & {\n\t\tcode?: string;\n\t\tconstraint?: string;\n\t\tconstraint_name?: string;\n\t};\n\treturn (\n\t\tcandidate.code === \"23505\" &&\n\t\t(candidate.constraint === ONE_SCANNING_CONSTRAINT ||\n\t\t\tcandidate.constraint_name === ONE_SCANNING_CONSTRAINT)\n\t);\n}\n\nexport async function beginReplay(\n\tdb: Kysely<Database>,\n\tinput: {\n\t\tid: string;\n\t\twebhookId: string;\n\t\tfromBlock: number;\n\t\ttoBlock: number;\n\t},\n): Promise<void> {\n\ttry {\n\t\tawait db.transaction().execute(async (trx) => {\n\t\t\tawait trx\n\t\t\t\t.updateTable(\"webhook_replays\")\n\t\t\t\t.set({\n\t\t\t\t\tstatus: \"failed\",\n\t\t\t\t\terror: \"scan interrupted\",\n\t\t\t\t\tfinished_at: sql`now()`,\n\t\t\t\t})\n\t\t\t\t.where(\"webhook_id\", \"=\", input.webhookId)\n\t\t\t\t.where(\"status\", \"=\", \"scanning\")\n\t\t\t\t.where(\n\t\t\t\t\t\"started_at\",\n\t\t\t\t\t\"<\",\n\t\t\t\t\tsql<Date>`now() - ${sql.lit(`${STALE_SCAN_MINUTES} minutes`)}::interval`,\n\t\t\t\t)\n\t\t\t\t.execute();\n\t\t\t// Re-running a range reuses its record. A row of this very id that is\n\t\t\t// still scanning is a concurrent scan: the WHERE leaves it untouched and\n\t\t\t// no row comes back.\n\t\t\tconst row = await trx\n\t\t\t\t.insertInto(\"webhook_replays\")\n\t\t\t\t.values({\n\t\t\t\t\tid: input.id,\n\t\t\t\t\twebhook_id: input.webhookId,\n\t\t\t\t\tfrom_block: input.fromBlock,\n\t\t\t\t\tto_block: input.toBlock,\n\t\t\t\t\tstatus: \"scanning\",\n\t\t\t\t})\n\t\t\t\t.onConflict((oc) =>\n\t\t\t\t\toc\n\t\t\t\t\t\t.column(\"id\")\n\t\t\t\t\t\t.doUpdateSet({\n\t\t\t\t\t\t\tstatus: \"scanning\",\n\t\t\t\t\t\t\tstarted_at: sql`now()`,\n\t\t\t\t\t\t\tfinished_at: null,\n\t\t\t\t\t\t\terror: null,\n\t\t\t\t\t\t\ttotal: null,\n\t\t\t\t\t\t\tdelivered: null,\n\t\t\t\t\t\t\tgave_up: null,\n\t\t\t\t\t\t})\n\t\t\t\t\t\t.where(\"webhook_replays.status\", \"<>\", \"scanning\"),\n\t\t\t\t)\n\t\t\t\t.returning(\"id\")\n\t\t\t\t.executeTakeFirst();\n\t\t\tif (!row) throw new ReplayInProgressError();\n\t\t});\n\t} catch (err) {\n\t\tif (isOneScanningConflict(err)) throw new ReplayInProgressError();\n\t\tthrow err;\n\t}\n}\n\nexport async function finishScan(\n\tdb: Kysely<Database>,\n\tid: string,\n\tcounts: { scanned: number; enqueued: number },\n): Promise<void> {\n\tawait db\n\t\t.updateTable(\"webhook_replays\")\n\t\t.set({\n\t\t\tstatus: \"running\",\n\t\t\tscanned_count: counts.scanned,\n\t\t\tenqueued_count: sql`enqueued_count + ${counts.enqueued}`,\n\t\t})\n\t\t.where(\"id\", \"=\", id)\n\t\t.execute();\n}\n\nexport async function failScan(\n\tdb: Kysely<Database>,\n\tid: string,\n\terror: string,\n): Promise<void> {\n\tawait db\n\t\t.updateTable(\"webhook_replays\")\n\t\t.set({ status: \"failed\", error, finished_at: sql`now()` })\n\t\t.where(\"id\", \"=\", id)\n\t\t.execute();\n}\n\n/** Outbox rows of this replay still waiting to be delivered or to give up. */\nexport async function pendingCount(\n\tdb: Kysely<Database>,\n\tid: string,\n): Promise<number> {\n\tconst row = await db\n\t\t.selectFrom(\"webhook_outbox\")\n\t\t.select(sql<string>`count(*)`.as(\"n\"))\n\t\t.where(\"status\", \"=\", \"pending\")\n\t\t.where(\"replay_id\", \"=\", id)\n\t\t.executeTakeFirstOrThrow();\n\treturn Number(row.n);\n}\n\n/** Outbox rows of this replay that gave up. Finalize only; never on a poll. */\nexport async function deadCount(\n\tdb: Kysely<Database>,\n\twebhookId: string,\n\tid: string,\n): Promise<number> {\n\tconst row = await db\n\t\t.selectFrom(\"webhook_outbox\")\n\t\t.select(sql<string>`count(*)`.as(\"n\"))\n\t\t.where(\"webhook_id\", \"=\", webhookId)\n\t\t.where(\"replay_id\", \"=\", id)\n\t\t.where(\"status\", \"=\", \"dead\")\n\t\t.executeTakeFirstOrThrow();\n\treturn Number(row.n);\n}\n\nexport function progressOf(\n\trecord: WebhookReplay,\n\tpending: number,\n): ReplayProgress {\n\tconst done = record.status === \"done\";\n\tconst total = done\n\t\t? (record.total ?? record.enqueued_count)\n\t\t: record.enqueued_count;\n\treturn {\n\t\treplayId: record.id,\n\t\twebhookId: record.webhook_id,\n\t\tstatus: record.status,\n\t\tfromBlock: Number(record.from_block),\n\t\ttoBlock: Number(record.to_block),\n\t\ttotal,\n\t\tprocessed: done ? total : Math.max(0, total - pending),\n\t\tpending: done ? 0 : pending,\n\t\tdelivered: done ? record.delivered : null,\n\t\tgaveUp: done ? record.gave_up : null,\n\t\tstartedAt: record.started_at.toISOString(),\n\t\tfinishedAt: record.finished_at ? record.finished_at.toISOString() : null,\n\t\terror: record.error,\n\t};\n}\n\n/** Progress for one record, finalizing it once nothing is pending. */\nasync function progressWithFinalize(\n\tdb: Kysely<Database>,\n\trecord: WebhookReplay,\n): Promise<ReplayProgress> {\n\tif (record.status !== \"running\") return progressOf(record, 0);\n\tconst pending = await pendingCount(db, record.id);\n\tif (pending > 0) return progressOf(record, pending);\n\n\tconst dead = await deadCount(db, record.webhook_id, record.id);\n\tconst finalized = await db\n\t\t.updateTable(\"webhook_replays\")\n\t\t.set({\n\t\t\tstatus: \"done\",\n\t\t\tfinished_at: sql`now()`,\n\t\t\ttotal: sql`enqueued_count`,\n\t\t\tgave_up: dead,\n\t\t\tdelivered: sql`enqueued_count - ${dead}`,\n\t\t})\n\t\t.where(\"id\", \"=\", record.id)\n\t\t.where(\"status\", \"=\", \"running\")\n\t\t.returningAll()\n\t\t.executeTakeFirst();\n\tif (finalized) return progressOf(finalized, 0);\n\t// Lost a race to another finalizer (or a requeue): re-read.\n\tconst fresh = await db\n\t\t.selectFrom(\"webhook_replays\")\n\t\t.selectAll()\n\t\t.where(\"id\", \"=\", record.id)\n\t\t.executeTakeFirstOrThrow();\n\treturn progressOf(\n\t\tfresh,\n\t\tfresh.status === \"running\" ? await pendingCount(db, fresh.id) : 0,\n\t);\n}\n\nexport async function readReplay(\n\tdb: Kysely<Database>,\n\twebhookId: string,\n\tid: string,\n): Promise<ReplayProgress | null> {\n\tconst record = await db\n\t\t.selectFrom(\"webhook_replays\")\n\t\t.selectAll()\n\t\t.where(\"id\", \"=\", id)\n\t\t.where(\"webhook_id\", \"=\", webhookId)\n\t\t.executeTakeFirst();\n\treturn record ? progressWithFinalize(db, record) : null;\n}\n\n/** Replays in progress or started within `sinceHours`, newest first. */\nexport async function listReplays(\n\tdb: Kysely<Database>,\n\tinput: { webhookIds: string[]; sinceHours: number; limit: number },\n): Promise<ReplayProgress[]> {\n\tif (input.webhookIds.length === 0) return [];\n\tconst cutoff = new Date(Date.now() - input.sinceHours * 3_600_000);\n\tconst records = await db\n\t\t.selectFrom(\"webhook_replays\")\n\t\t.selectAll()\n\t\t.where(\"webhook_id\", \"in\", input.webhookIds)\n\t\t.where((eb) =>\n\t\t\teb.or([\n\t\t\t\teb(\"status\", \"in\", [\"scanning\", \"running\"]),\n\t\t\t\teb(\"started_at\", \">\", cutoff),\n\t\t\t]),\n\t\t)\n\t\t.orderBy(\"started_at\", \"desc\")\n\t\t.limit(input.limit)\n\t\t.execute();\n\treturn Promise.all(records.map((r) => progressWithFinalize(db, r)));\n}\n\n/** Newest replays of one webhook, finalizing any that have drained. */\nexport async function listWebhookReplays(\n\tdb: Kysely<Database>,\n\twebhookId: string,\n\tlimit: number,\n): Promise<ReplayProgress[]> {\n\tconst records = await db\n\t\t.selectFrom(\"webhook_replays\")\n\t\t.selectAll()\n\t\t.where(\"webhook_id\", \"=\", webhookId)\n\t\t.orderBy(\"started_at\", \"desc\")\n\t\t.limit(limit)\n\t\t.execute();\n\treturn Promise.all(records.map((r) => progressWithFinalize(db, r)));\n}\n\n/** Retention backstop: finalize every running replay that has drained. */\nexport async function finalizeReplays(db: Kysely<Database>): Promise<void> {\n\tconst running = await db\n\t\t.selectFrom(\"webhook_replays\")\n\t\t.selectAll()\n\t\t.where(\"status\", \"=\", \"running\")\n\t\t.execute();\n\tfor (const record of running) await progressWithFinalize(db, record);\n}\n\nexport async function deadSince(\n\tdb: Kysely<Database>,\n\twebhookId: string,\n\tsince: Date | null,\n): Promise<number> {\n\tlet q = db\n\t\t.selectFrom(\"webhook_outbox\")\n\t\t.select(sql<string>`count(*)`.as(\"n\"))\n\t\t.where(\"webhook_id\", \"=\", webhookId)\n\t\t.where(\"status\", \"=\", \"dead\");\n\tif (since) q = q.where(\"failed_at\", \">=\", since);\n\treturn Number((await q.executeTakeFirstOrThrow()).n);\n}\n\nexport async function knownEventsInRange(\n\tdb: Kysely<Database>,\n\twebhookId: string,\n\tfrom: number,\n\tto: number,\n): Promise<number> {\n\tconst row = await db\n\t\t.selectFrom(\"webhook_outbox\")\n\t\t.select(sql<string>`count(*)`.as(\"n\"))\n\t\t.where(\"webhook_id\", \"=\", webhookId)\n\t\t.where(\"block_height\", \">=\", from)\n\t\t.where(\"block_height\", \"<=\", to)\n\t\t.executeTakeFirstOrThrow();\n\treturn Number(row.n);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "E8EBA311948ADE2B64756E2164756E21",
+  "names": []
+}

package/dist/src/db/queries/webhooks.d.ts

@@ -402,6 +402,7 @@ interface InsightsTable {
 	clear_streak: Generated<number>;
 	resolved_at: Date | null;
 	dismissed_at: Date | null;
+	snoozed_until: Date | null;
 }
 /** "Expected": mutes one rule for one resource until removed. */
 interface InsightMutesTable {
@@ -895,6 +896,7 @@ interface Database {
 	webhooks: WebhooksTable;
 	webhook_outbox: WebhookOutboxTable;
 	webhook_deliveries: WebhookDeliveriesTable;
+	webhook_replays: WebhookReplaysTable;
 	trigger_evaluator_state: TriggerEvaluatorStateTable;
 	decoded_events: DecodedEventsTable;
 	decoder_checkpoints: DecoderCheckpointsTable;
@@ -943,6 +945,9 @@ interface Database {
 	insights: InsightsTable;
 	insight_mutes: InsightMutesTable;
 	feedback_tickets: FeedbackTicketsTable;
+	push_subscriptions: PushSubscriptionsTable;
+	push_prefs: PushPrefsTable;
+	push_sent: PushSentTable;
 }
 interface ServiceHeartbeatsTable {
 	name: string;
@@ -1035,6 +1040,36 @@ interface WebhookIncidentAlertsTable {
 	email_attempts: Generated<number>;
 	resolved_at: Date | null;
 }
+/** One browser/device push subscription; the endpoint is unique. */
+interface PushSubscriptionsTable {
+	id: Generated<string>;
+	account_id: string;
+	endpoint: string;
+	p256dh: string;
+	auth: string;
+	user_agent: string | null;
+	created_at: Generated<Date>;
+	last_success_at: Date | null;
+	failed_count: Generated<number>;
+}
+/** Per-account push toggles. A missing row means the column defaults. */
+interface PushPrefsTable {
+	account_id: string;
+	webhook_failing: Generated<boolean>;
+	subgraph_stopped: Generated<boolean>;
+	subgraph_not_serving: Generated<boolean>;
+	replay_done: Generated<boolean>;
+	spend_cap: Generated<boolean>;
+	key_repeat: Generated<boolean>;
+	updated_at: Generated<Date>;
+}
+/** A push already sent, keyed by what it was about; debounces repeat signals. */
+interface PushSentTable {
+	account_id: string;
+	key: string;
+	kind: string;
+	sent_at: Generated<Date>;
+}
 type CliDeviceLoginStatus = "pending" | "approved" | "denied" | "consumed";
 /** The product that started a CLI sign-in; null is `sl login`. */
 type CliDeviceProduct = "sentinel";
@@ -1179,6 +1214,8 @@ interface WebhookOutboxTable {
 	next_attempt_at: Generated<Date>;
 	status: ColumnType<OutboxStatus, OutboxStatus | undefined, OutboxStatus>;
 	is_replay: Generated<boolean>;
+	/** The replay that created this row; null for live rows. */
+	replay_id: string | null;
 	/** The chain block_time of the matched event/tx. Null for rows written
 	*  before this column existed, and for the settlement scan path (not yet
 	*  wired). Lets `delivered_at - block_time` measure end-to-end webhook
@@ -1194,6 +1231,22 @@ interface WebhookOutboxTable {
 	last_error: string | null;
 	created_at: Generated<Date>;
 }
+type WebhookReplayStatus = "scanning" | "running" | "done" | "failed";
+interface WebhookReplaysTable {
+	id: string;
+	webhook_id: string;
+	from_block: number | bigint;
+	to_block: number | bigint;
+	status: WebhookReplayStatus;
+	scanned_count: Generated<number>;
+	enqueued_count: Generated<number>;
+	total: number | null;
+	delivered: number | null;
+	gave_up: number | null;
+	error: string | null;
+	started_at: Generated<Date>;
+	finished_at: Date | null;
+}
 interface WebhookDeliveriesTable {
 	id: Generated<string>;
 	/** Nullable after migration 0077 — outbox row may be cleaned up while

package/dist/src/db/schema.d.ts

@@ -401,6 +401,7 @@ interface InsightsTable {
 	clear_streak: Generated<number>;
 	resolved_at: Date | null;
 	dismissed_at: Date | null;
+	snoozed_until: Date | null;
 }
 /** "Expected": mutes one rule for one resource until removed. */
 interface InsightMutesTable {
@@ -894,6 +895,7 @@ interface Database {
 	webhooks: WebhooksTable;
 	webhook_outbox: WebhookOutboxTable;
 	webhook_deliveries: WebhookDeliveriesTable;
+	webhook_replays: WebhookReplaysTable;
 	trigger_evaluator_state: TriggerEvaluatorStateTable;
 	decoded_events: DecodedEventsTable;
 	decoder_checkpoints: DecoderCheckpointsTable;
@@ -942,6 +944,9 @@ interface Database {
 	insights: InsightsTable;
 	insight_mutes: InsightMutesTable;
 	feedback_tickets: FeedbackTicketsTable;
+	push_subscriptions: PushSubscriptionsTable;
+	push_prefs: PushPrefsTable;
+	push_sent: PushSentTable;
 }
 interface ServiceHeartbeatsTable {
 	name: string;
@@ -1047,6 +1052,38 @@ interface WebhookIncidentAlertsTable {
 	resolved_at: Date | null;
 }
 type WebhookIncidentAlert = Selectable<WebhookIncidentAlertsTable>;
+/** One browser/device push subscription; the endpoint is unique. */
+interface PushSubscriptionsTable {
+	id: Generated<string>;
+	account_id: string;
+	endpoint: string;
+	p256dh: string;
+	auth: string;
+	user_agent: string | null;
+	created_at: Generated<Date>;
+	last_success_at: Date | null;
+	failed_count: Generated<number>;
+}
+type PushSubscription = Selectable<PushSubscriptionsTable>;
+/** Per-account push toggles. A missing row means the column defaults. */
+interface PushPrefsTable {
+	account_id: string;
+	webhook_failing: Generated<boolean>;
+	subgraph_stopped: Generated<boolean>;
+	subgraph_not_serving: Generated<boolean>;
+	replay_done: Generated<boolean>;
+	spend_cap: Generated<boolean>;
+	key_repeat: Generated<boolean>;
+	updated_at: Generated<Date>;
+}
+type PushPrefs = Selectable<PushPrefsTable>;
+/** A push already sent, keyed by what it was about; debounces repeat signals. */
+interface PushSentTable {
+	account_id: string;
+	key: string;
+	kind: string;
+	sent_at: Generated<Date>;
+}
 type CliDeviceLoginStatus = "pending" | "approved" | "denied" | "consumed";
 /** The product that started a CLI sign-in; null is `sl login`. */
 type CliDeviceProduct = "sentinel";
@@ -1241,6 +1278,8 @@ interface WebhookOutboxTable {
 	next_attempt_at: Generated<Date>;
 	status: ColumnType<OutboxStatus, OutboxStatus | undefined, OutboxStatus>;
 	is_replay: Generated<boolean>;
+	/** The replay that created this row; null for live rows. */
+	replay_id: string | null;
 	/** The chain block_time of the matched event/tx. Null for rows written
 	*  before this column existed, and for the settlement scan path (not yet
 	*  wired). Lets `delivered_at - block_time` measure end-to-end webhook
@@ -1256,7 +1295,28 @@ interface WebhookOutboxTable {
 	last_error: string | null;
 	created_at: Generated<Date>;
 }
-type WebhookOutbox = Selectable<WebhookOutboxTable>;
+type WebhookReplayStatus = "scanning" | "running" | "done" | "failed";
+interface WebhookReplaysTable {
+	id: string;
+	webhook_id: string;
+	from_block: number | bigint;
+	to_block: number | bigint;
+	status: WebhookReplayStatus;
+	scanned_count: Generated<number>;
+	enqueued_count: Generated<number>;
+	total: number | null;
+	delivered: number | null;
+	gave_up: number | null;
+	error: string | null;
+	started_at: Generated<Date>;
+	finished_at: Date | null;
+}
+type WebhookReplay = Selectable<WebhookReplaysTable>;
+/** `replay_id` is optional on the row type so hand-built rows (the test
+*  delivery, fixtures) need not carry it; reads still return it. */
+type WebhookOutbox = Omit<Selectable<WebhookOutboxTable>, "replay_id"> & {
+	replay_id?: string | null
+};
 type InsertWebhookOutbox = Insertable<WebhookOutboxTable>;
 type UpdateWebhookOutbox = Updateable<WebhookOutboxTable>;
 interface WebhookDeliveriesTable {
@@ -1400,4 +1460,4 @@ type WaitlistSignup = Selectable<WaitlistSignupsTable>;
 type InsertWaitlistSignup = Insertable<WaitlistSignupsTable>;
 type ContactRequest = Selectable<ContactRequestsTable>;
 type InsertContactRequest = Insertable<ContactRequestsTable>;
-export { Account, AccountBalanceAlerts, AccountBalanceAlertsTable, AccountCredits, AccountCreditsTable, AccountSpendCap, AccountSpendCapsTable, AccountsTable, ApiFailedRequest, ApiFailedRequestsTable, ApiKey, ApiKeysTable, ApiRequestLogRow, ApiRequestLogTable, ArchiveFetch, ArchiveFetchesTable, Block, BlocksTable, BnsMarketplaceAction, BnsMarketplaceEventsTable, BnsNameEventTopic, BnsNameEventsTable, BnsNamesTable, BnsNamespaceEventStatus, BnsNamespaceEventsTable, BnsNamespacesTable, BurnBlockRewardSlotsTable, BurnBlockRewardsTable, ChainReadCacheTable, ChainReorgsTable, CliDeviceLogin, CliDeviceLoginStatus, CliDeviceLoginsTable, CliDeviceProduct, ContactRequest, ContactRequestsTable, Contract, ContractsTable, CoverageSegmentsTable, Database, DeadLetterEventsTable, DecodedEventsTable, DecoderCheckpointsTable, Event, EventsArchiveTable, EventsTable, FailureClass, FailureUnit, FeedbackTicket, FeedbackTicketsTable, IndexProgress, IndexProgressTable, InsertAccount, InsertAccountBalanceAlerts, InsertAccountCredits, InsertAccountSpendCap, InsertApiFailedRequest, InsertApiKey, InsertApiRequestLogRow, InsertArchiveFetch, InsertBlock, InsertContactRequest, InsertContract, InsertEvent, InsertFeedbackTicket, InsertIndexProgress, InsertMagicLink, InsertMempoolTransaction, InsertSession, InsertStateWrite, InsertSubgraph, InsertSubgraphGap, InsertSubgraphHealthSnapshot, InsertSubgraphOperation, InsertTransaction, InsertUsageLedgerRow, InsertVmEvent, InsertWaitlistSignup, InsertWebhook, InsertWebhookDelivery, InsertWebhookOutbox, InsightMutesTable, InsightsTable, InstancesTable, MagicLink, MagicLinksTable, MempoolTransaction, MempoolTransactionsTable, NativeClock, OauthClient, OauthClientsTable, OauthCodesTable, OauthGrant, OauthGrantsTable, OauthRefreshRetiredTable, OauthRequestStatus, OauthRequestsTable, OauthTokenKind, OauthTokensTable, ObserverJournalStatus, ObserverJournalTable, OutboxStatus, PendingForkBlocksTable, Pox4CallsTable, Pox4FunctionName, Pox5CycleSignersTable, Pox5CyclesTable, Pox5EventTopic, Pox5EventsTable, ProcessedStripeEventsTable, RepairMode, RetryState, RunStatus, SbtcEventTopic, SbtcEventsTable, SbtcSettlementsTable, SbtcTokenEventType, SbtcTokenEventsTable, SentinelAccount, SentinelAccountsTable, ServiceHeartbeatsTable, Session, SessionsTable, StageBlockReceiptsTable, StageFailuresTable, StageKind, StageRegistryTable, StageRunsTable, StateWrite, StateWritesArchiveTable, StateWritesTable, Subgraph, SubgraphErrorGroupsTable, SubgraphGap, SubgraphGapsTable, SubgraphHealthSnapshot, SubgraphHealthSnapshotsTable, SubgraphOperation, SubgraphOperationKind, SubgraphOperationStatus, SubgraphOperationsTable, SubgraphProcessingStatsTable, SubgraphViolationsTable, SubgraphsTable, SyncScopesTable, Transaction, TransactionsArchiveTable, TransactionsTable, TriggerEvaluatorState, TriggerEvaluatorStateTable, UpdateAccountBalanceAlerts, UpdateAccountCredits, UpdateAccountSpendCap, UpdateApiKey, UpdateArchiveFetch, UpdateBlock, UpdateContract, UpdateEvent, UpdateIndexProgress, UpdateSubgraph, UpdateSubgraphOperation, UpdateTransaction, UpdateUsageLedgerRow, UpdateVmEvent, UpdateWebhook, UpdateWebhookOutbox, UsageLedgerRow, UsageLedgerTable, VmEvent, VmEventsArchiveTable, VmEventsTable, Waitlist, WaitlistSignup, WaitlistSignupsTable, WaitlistsTable, Webhook, WebhookDeliveriesTable, WebhookDelivery, WebhookFormat, WebhookIncidentAlert, WebhookIncidentAlertsTable, WebhookKind, WebhookOutbox, WebhookOutboxTable, WebhookStatus, WebhooksTable };
+export { Account, AccountBalanceAlerts, AccountBalanceAlertsTable, AccountCredits, AccountCreditsTable, AccountSpendCap, AccountSpendCapsTable, AccountsTable, ApiFailedRequest, ApiFailedRequestsTable, ApiKey, ApiKeysTable, ApiRequestLogRow, ApiRequestLogTable, ArchiveFetch, ArchiveFetchesTable, Block, BlocksTable, BnsMarketplaceAction, BnsMarketplaceEventsTable, BnsNameEventTopic, BnsNameEventsTable, BnsNamesTable, BnsNamespaceEventStatus, BnsNamespaceEventsTable, BnsNamespacesTable, BurnBlockRewardSlotsTable, BurnBlockRewardsTable, ChainReadCacheTable, ChainReorgsTable, CliDeviceLogin, CliDeviceLoginStatus, CliDeviceLoginsTable, CliDeviceProduct, ContactRequest, ContactRequestsTable, Contract, ContractsTable, CoverageSegmentsTable, Database, DeadLetterEventsTable, DecodedEventsTable, DecoderCheckpointsTable, Event, EventsArchiveTable, EventsTable, FailureClass, FailureUnit, FeedbackTicket, FeedbackTicketsTable, IndexProgress, IndexProgressTable, InsertAccount, InsertAccountBalanceAlerts, InsertAccountCredits, InsertAccountSpendCap, InsertApiFailedRequest, InsertApiKey, InsertApiRequestLogRow, InsertArchiveFetch, InsertBlock, InsertContactRequest, InsertContract, InsertEvent, InsertFeedbackTicket, InsertIndexProgress, InsertMagicLink, InsertMempoolTransaction, InsertSession, InsertStateWrite, InsertSubgraph, InsertSubgraphGap, InsertSubgraphHealthSnapshot, InsertSubgraphOperation, InsertTransaction, InsertUsageLedgerRow, InsertVmEvent, InsertWaitlistSignup, InsertWebhook, InsertWebhookDelivery, InsertWebhookOutbox, InsightMutesTable, InsightsTable, InstancesTable, MagicLink, MagicLinksTable, MempoolTransaction, MempoolTransactionsTable, NativeClock, OauthClient, OauthClientsTable, OauthCodesTable, OauthGrant, OauthGrantsTable, OauthRefreshRetiredTable, OauthRequestStatus, OauthRequestsTable, OauthTokenKind, OauthTokensTable, ObserverJournalStatus, ObserverJournalTable, OutboxStatus, PendingForkBlocksTable, Pox4CallsTable, Pox4FunctionName, Pox5CycleSignersTable, Pox5CyclesTable, Pox5EventTopic, Pox5EventsTable, ProcessedStripeEventsTable, PushPrefs, PushPrefsTable, PushSentTable, PushSubscription, PushSubscriptionsTable, RepairMode, RetryState, RunStatus, SbtcEventTopic, SbtcEventsTable, SbtcSettlementsTable, SbtcTokenEventType, SbtcTokenEventsTable, SentinelAccount, SentinelAccountsTable, ServiceHeartbeatsTable, Session, SessionsTable, StageBlockReceiptsTable, StageFailuresTable, StageKind, StageRegistryTable, StageRunsTable, StateWrite, StateWritesArchiveTable, StateWritesTable, Subgraph, SubgraphErrorGroupsTable, SubgraphGap, SubgraphGapsTable, SubgraphHealthSnapshot, SubgraphHealthSnapshotsTable, SubgraphOperation, SubgraphOperationKind, SubgraphOperationStatus, SubgraphOperationsTable, SubgraphProcessingStatsTable, SubgraphViolationsTable, SubgraphsTable, SyncScopesTable, Transaction, TransactionsArchiveTable, TransactionsTable, TriggerEvaluatorState, TriggerEvaluatorStateTable, UpdateAccountBalanceAlerts, UpdateAccountCredits, UpdateAccountSpendCap, UpdateApiKey, UpdateArchiveFetch, UpdateBlock, UpdateContract, UpdateEvent, UpdateIndexProgress, UpdateSubgraph, UpdateSubgraphOperation, UpdateTransaction, UpdateUsageLedgerRow, UpdateVmEvent, UpdateWebhook, UpdateWebhookOutbox, UsageLedgerRow, UsageLedgerTable, VmEvent, VmEventsArchiveTable, VmEventsTable, Waitlist, WaitlistSignup, WaitlistSignupsTable, WaitlistsTable, Webhook, WebhookDeliveriesTable, WebhookDelivery, WebhookFormat, WebhookIncidentAlert, WebhookIncidentAlertsTable, WebhookKind, WebhookOutbox, WebhookOutboxTable, WebhookReplay, WebhookReplayStatus, WebhookReplaysTable, WebhookStatus, WebhooksTable };

package/dist/src/email/index.d.ts

@@ -1,8 +1,14 @@
 /**
-* The one HTML/text layout every customer email renders through. Table-based
-* HTML, inline styles only (email clients strip <style>), 560px max width,
-* white background, #111 text, one black button — same look as the login
-* email this was lifted from. Text is the same content, plainer.
+* The one HTML/text layout every customer email renders through, in the
+* brand's "Figure" look: logo + wordmark, a 24px heading, muted prose, the
+* code or facts inside a hairline code figure whose bar names it and carries
+* a status chip, one blue button, and a hairline footer.
+*
+* Table-based HTML with inline styles (most clients strip <style>). The head
+* <style> only adds dark mode for clients that honor `prefers-color-scheme`
+* (Apple Mail, iOS); everyone else gets the light palette, which Gmail
+* inverts on its own. Geist loads where web fonts work, the system stack
+* elsewhere. Callers pass content; every color lives here.
 */
 interface FactRow {
 	label: string;
@@ -12,13 +18,28 @@ interface EmailCta {
 	label: string;
 	url: string;
 }
+/** `alarm` only for failures and stops, `ok` only for success. */
+type EmailTone = "neutral" | "ok" | "alarm";
+interface EmailStatus {
+	tone: EmailTone;
+	text: string;
+}
 interface RenderEmailInput {
 	heading: string;
+	/** The inbox preview line after the subject. Not shown in the body. */
+	preheader?: string;
 	paragraphs: string[];
-	/** A code shown in a large, letter-spaced box (login codes). */
+	/** Someone else's words, quoted (a contact form message). */
+	quote?: string;
+	/** A sign-in code, shown as one selectable run of digits in the figure. */
 	code?: string;
 	facts?: FactRow[];
+	/** The figure's title bar. Defaults to "sign-in code" or "details". */
+	figure?: string;
+	/** A chip in the figure bar, or a status line when there is no figure. */
+	status?: EmailStatus;
 	cta?: EmailCta;
+	/** Why the reader got this email and how to stop it. */
 	footnote?: string;
 }
 interface RenderedEmail {
@@ -46,4 +67,4 @@ type SendEmailResult = {
 	skipped: false
 };
 declare function sendEmail(input: SendEmailInput): Promise<SendEmailResult>;
-export { EmailCta, FactRow, RenderEmailInput, RenderedEmail, SendEmailInput, SendEmailResult, renderEmail, sendEmail };
+export { EmailCta, EmailStatus, EmailTone, FactRow, RenderEmailInput, RenderedEmail, SendEmailInput, SendEmailResult, renderEmail, sendEmail };