tapimo 0.0.2 → 0.2.0

package/src/db/tables/webhookDeliveries.ts

@@ -0,0 +1,159 @@
+import type { Selectable } from 'kysely'
+
+import type * as Webhooks from '../../internal/Webhooks.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `webhook_deliveries` table, derived from `Schema.WebhookDelivery`. */
+export type Table = db_Schema.WebhookDelivery
+
+/** A stored webhook-delivery row. */
+export type Record = Selectable<Table>
+
+/** Maps a stored row to the domain delivery (null columns → absent fields). */
+export function toDelivery(row: Record): Webhooks.Delivery {
+  return {
+    attempt: row.attempt,
+    createdAt: row.createdAt,
+    envelope: row.envelope,
+    ...(row.error === null ? {} : { error: row.error }),
+    eventId: row.eventId,
+    id: row.id,
+    requestUrl: row.requestUrl,
+    ...(row.responseMs === null ? {} : { responseMs: row.responseMs }),
+    ...(row.responseStatus === null ? {} : { responseStatus: row.responseStatus }),
+    status: row.status,
+    subscriptionId: row.subscriptionId,
+  }
+}
+
+/**
+ * Inserts a delivery row from its domain value.
+ *
+ * @param db - The database.
+ * @param delivery - The delivery to insert.
+ * @param expiresAt - Retention deadline (ISO); the row is invisible past it.
+ */
+export async function insert(
+  db: Db.Db,
+  delivery: Webhooks.Delivery,
+  expiresAt: string,
+): Promise<void> {
+  await db.kysely
+    .insertInto('webhook_deliveries')
+    .values({
+      attempt: delivery.attempt,
+      createdAt: delivery.createdAt,
+      envelope: delivery.envelope,
+      error: delivery.error ?? null,
+      eventId: delivery.eventId,
+      expiresAt,
+      id: delivery.id,
+      requestUrl: delivery.requestUrl,
+      responseMs: delivery.responseMs ?? null,
+      responseStatus: delivery.responseStatus ?? null,
+      status: delivery.status,
+      subscriptionId: delivery.subscriptionId,
+    })
+    .execute()
+}
+
+/**
+ * Lists a subscription's unexpired deliveries, newest first, with keyset
+ * paging (`id < cursor` — ids embed a zero-padded timestamp, so lexical order
+ * is chronological).
+ *
+ * @param db - The database.
+ * @param subscriptionId - The owning subscription id (`wh_…`).
+ * @param options - Paging options plus the retention timestamp.
+ * @returns The deliveries.
+ */
+export async function list(
+  db: Db.Db,
+  subscriptionId: string,
+  options: list.Options,
+): Promise<Webhooks.Delivery[]> {
+  let query = db.kysely
+    .selectFrom('webhook_deliveries')
+    .selectAll()
+    .where('subscriptionId', '=', subscriptionId)
+    .where('expiresAt', '>', options.now)
+    .orderBy('id', 'desc')
+  if (options.cursor) query = query.where('id', '<', options.cursor)
+  if (options.offset) query = query.offset(options.offset)
+  if (options.limit !== undefined) query = query.limit(options.limit)
+  return (await query.execute()).map(toDelivery)
+}
+
+export declare namespace list {
+  /** Options for {@link list}. */
+  type Options = {
+    /** Return deliveries whose id sorts before this one (older entries). */
+    cursor?: string | undefined
+    /** Maximum deliveries to return. */
+    limit?: number | undefined
+    /** ISO timestamp retention is evaluated against. */
+    now: string
+    /** Rows to skip from the head (positional pagination; exclusive with `cursor`). */
+    offset?: number | undefined
+  }
+}
+
+/**
+ * Counts a subscription's unexpired deliveries.
+ *
+ * @param db - The database.
+ * @param subscriptionId - The owning subscription id (`wh_…`).
+ * @param now - ISO timestamp retention is evaluated against.
+ * @returns The count.
+ */
+export async function count(db: Db.Db, subscriptionId: string, now: string): Promise<number> {
+  const row = await db.kysely
+    .selectFrom('webhook_deliveries')
+    .select((eb) => eb.fn.countAll().as('count'))
+    .where('subscriptionId', '=', subscriptionId)
+    .where('expiresAt', '>', now)
+    .executeTakeFirstOrThrow()
+  return Number(row.count)
+}
+
+/**
+ * Reads a single unexpired delivery scoped to its subscription.
+ *
+ * @param db - The database.
+ * @param subscriptionId - The owning subscription id (`wh_…`).
+ * @param deliveryId - The delivery id (`whd_…`).
+ * @param now - ISO timestamp retention is evaluated against.
+ * @returns The delivery, or `null` when absent.
+ */
+export async function get(
+  db: Db.Db,
+  subscriptionId: string,
+  deliveryId: string,
+  now: string,
+): Promise<Webhooks.Delivery | null> {
+  const row = await db.kysely
+    .selectFrom('webhook_deliveries')
+    .selectAll()
+    .where('subscriptionId', '=', subscriptionId)
+    .where('id', '=', deliveryId)
+    .where('expiresAt', '>', now)
+    .executeTakeFirst()
+  return row ? toDelivery(row) : null
+}
+
+/**
+ * Deletes deliveries past their retention deadline. Called best-effort from
+ * the poller tick.
+ *
+ * @param db - The database.
+ * @param now - ISO timestamp retention is evaluated against.
+ * @returns The number of rows deleted.
+ */
+export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
+  const result = await db.kysely
+    .deleteFrom('webhook_deliveries')
+    .where('expiresAt', '<=', now)
+    .executeTakeFirst()
+  return Number(result.numDeletedRows)
+}

package/src/db/tables/webhookSubscriptions.ts

@@ -0,0 +1,358 @@
+import type { ExpressionBuilder, Selectable } from 'kysely'
+import { sql } from 'kysely'
+
+import type * as Webhooks from '../../internal/Webhooks.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `webhook_subscriptions` table, derived from `Schema.WebhookSubscription`. */
+export type Table = db_Schema.WebhookSubscription
+
+/** A stored webhook-subscription row. */
+export type Record = Selectable<Table>
+
+/** Maps an owner union to its stored `ownerId` column value. */
+export function ownerId(owner: Webhooks.Owner): string {
+  return owner.type === 'api_key' ? owner.orgId : owner.payer
+}
+
+/** Maps a stored row to the domain subscription (null columns → absent fields). */
+export function toSubscription(row: Record): Webhooks.Subscription {
+  return {
+    chainId: row.chainId,
+    ...(row.context === null ? {} : { context: row.context }),
+    createdAt: row.createdAt,
+    destination: row.destination,
+    eventType: row.eventType,
+    ...(row.expiresAt === null ? {} : { expiresAt: row.expiresAt }),
+    failureCount: row.failureCount,
+    filters: row.filters,
+    id: row.id,
+    ...(row.lastDeliveryAt === null ? {} : { lastDeliveryAt: row.lastDeliveryAt }),
+    owner:
+      row.ownerType === 'api_key'
+        ? { orgId: row.ownerId, type: 'api_key' }
+        : { payer: row.ownerId, type: 'mpp' },
+    secret: row.secret,
+    status: row.status,
+    updatedAt: row.updatedAt,
+  }
+}
+
+/**
+ * Inserts a subscription row from its domain value.
+ *
+ * @param db - The database.
+ * @param subscription - The subscription to insert.
+ */
+export async function insert(db: Db.Db, subscription: Webhooks.Subscription): Promise<void> {
+  await db.kysely
+    .insertInto('webhook_subscriptions')
+    .values({
+      chainId: subscription.chainId,
+      context: subscription.context ?? null,
+      createdAt: subscription.createdAt,
+      destination: subscription.destination,
+      eventType: subscription.eventType,
+      expiresAt: subscription.expiresAt ?? null,
+      failureCount: subscription.failureCount,
+      filters: subscription.filters,
+      id: subscription.id,
+      lastDeliveryAt: subscription.lastDeliveryAt ?? null,
+      ownerId: ownerId(subscription.owner),
+      ownerType: subscription.owner.type,
+      pollerCursor: null,
+      secret: subscription.secret,
+      status: subscription.status,
+      updatedAt: subscription.updatedAt,
+    })
+    .execute()
+}
+
+/**
+ * Reads an owner's subscription by id; expired rows never match (query-time
+ * expiry, same read semantics as the old store TTL).
+ *
+ * @param db - The database.
+ * @param owner - The authenticated owner.
+ * @param id - The subscription id (`wh_…`).
+ * @param now - ISO timestamp expiry is evaluated against.
+ * @returns The subscription, or `null` when absent (or not the owner's).
+ */
+export async function get(
+  db: Db.Db,
+  owner: Webhooks.Owner,
+  id: string,
+  now: string,
+): Promise<Webhooks.Subscription | null> {
+  const row = await db.kysely
+    .selectFrom('webhook_subscriptions')
+    .selectAll()
+    .where('id', '=', id)
+    .where('ownerType', '=', owner.type)
+    .where('ownerId', '=', ownerId(owner))
+    .where(live(now))
+    .executeTakeFirst()
+  return row ? toSubscription(row) : null
+}
+
+/**
+ * Lists an owner's live subscriptions, newest first, with keyset paging
+ * (`id < cursor` — ids embed a zero-padded timestamp, so lexical order is
+ * chronological).
+ *
+ * @param db - The database.
+ * @param owner - The authenticated owner.
+ * @param options - Paging options plus the expiry timestamp.
+ * @returns The subscriptions.
+ */
+export async function list(
+  db: Db.Db,
+  owner: Webhooks.Owner,
+  options: list.Options,
+): Promise<Webhooks.Subscription[]> {
+  let query = db.kysely
+    .selectFrom('webhook_subscriptions')
+    .selectAll()
+    .where('ownerType', '=', owner.type)
+    .where('ownerId', '=', ownerId(owner))
+    .where(live(options.now))
+    .orderBy('id', 'desc')
+  if (options.cursor) query = query.where('id', '<', options.cursor)
+  if (options.offset) query = query.offset(options.offset)
+  if (options.limit !== undefined) query = query.limit(options.limit)
+  return (await query.execute()).map(toSubscription)
+}
+
+export declare namespace list {
+  /** Options for {@link list}. */
+  type Options = {
+    /** Return subscriptions older than this id (keyset paging, newest first). */
+    cursor?: string | undefined
+    /** Maximum subscriptions to return. */
+    limit?: number | undefined
+    /** ISO timestamp expiry is evaluated against. */
+    now: string
+    /** Rows to skip from the head (positional pagination; exclusive with `cursor`). */
+    offset?: number | undefined
+  }
+}
+
+/**
+ * Counts an owner's live subscriptions.
+ *
+ * @param db - The database.
+ * @param owner - The authenticated owner.
+ * @param now - ISO timestamp expiry is evaluated against.
+ * @returns The count.
+ */
+export async function count(db: Db.Db, owner: Webhooks.Owner, now: string): Promise<number> {
+  const row = await db.kysely
+    .selectFrom('webhook_subscriptions')
+    .select((eb) => eb.fn.countAll().as('count'))
+    .where('ownerType', '=', owner.type)
+    .where('ownerId', '=', ownerId(owner))
+    .where(live(now))
+    .executeTakeFirstOrThrow()
+  return Number(row.count)
+}
+
+/**
+ * Applies a column patch to a subscription. Only the provided columns are
+ * written; `context: null` clears the stored context.
+ *
+ * @param db - The database.
+ * @param id - The subscription id (`wh_…`).
+ * @param set - The columns to write.
+ * @returns The updated row's subscription, or `undefined` when absent.
+ */
+export async function update(
+  db: Db.Db,
+  id: string,
+  set: update.Set,
+): Promise<Webhooks.Subscription | undefined> {
+  const row = await db.kysely
+    .updateTable('webhook_subscriptions')
+    .set(set)
+    .where('id', '=', id)
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toSubscription(row) : undefined
+}
+
+export declare namespace update {
+  /** Columns writable by a subscription patch. */
+  type Set = {
+    /** New human context; null clears it. */
+    context?: Webhooks.Context | null | undefined
+    /** New delivery destination. */
+    destination?: Webhooks.Destination | undefined
+    /** New filter predicates. */
+    filters?: Webhooks.Subscription['filters'] | undefined
+    /** New lifecycle status. */
+    status?: Webhooks.Status | undefined
+    /** Mutation timestamp (ISO). */
+    updatedAt: string
+  }
+}
+
+/**
+ * Deletes an owner's live subscription; delivery rows cascade via the FK.
+ *
+ * @param db - The database.
+ * @param owner - The authenticated owner.
+ * @param id - The subscription id (`wh_…`).
+ * @param now - ISO timestamp expiry is evaluated against.
+ * @returns Whether a row was deleted.
+ */
+export async function remove(
+  db: Db.Db,
+  owner: Webhooks.Owner,
+  id: string,
+  now: string,
+): Promise<boolean> {
+  const result = await db.kysely
+    .deleteFrom('webhook_subscriptions')
+    .where('id', '=', id)
+    .where('ownerType', '=', owner.type)
+    .where('ownerId', '=', ownerId(owner))
+    .where(live(now))
+    .executeTakeFirst()
+  return result.numDeletedRows > 0n
+}
+
+/**
+ * Lists live `active` subscriptions for a `(chainId, eventType)` stream — the
+ * poller's per-stream lookup, served by the partial status index.
+ *
+ * @param db - The database.
+ * @param chainId - Chain the stream belongs to.
+ * @param eventType - Event type of the stream.
+ * @param now - ISO timestamp expiry is evaluated against.
+ * @returns The subscriptions, in id (chronological) order.
+ */
+export async function listActive(
+  db: Db.Db,
+  chainId: number,
+  eventType: Webhooks.EventType,
+  now: string,
+): Promise<Webhooks.Subscription[]> {
+  const rows = await db.kysely
+    .selectFrom('webhook_subscriptions')
+    .selectAll()
+    .where('chainId', '=', chainId)
+    .where('eventType', '=', eventType)
+    .where('status', '=', 'active')
+    .where(live(now))
+    .orderBy('id')
+    .execute()
+  return rows.map(toSubscription)
+}
+
+/**
+ * Reads a subscription's poller cursor.
+ *
+ * @param db - The database.
+ * @param id - The subscription id (`wh_…`).
+ * @returns The cursor, or `null` when unset (or the row is absent).
+ */
+export async function getCursor(db: Db.Db, id: string): Promise<string | null> {
+  const row = await db.kysely
+    .selectFrom('webhook_subscriptions')
+    .select('pollerCursor')
+    .where('id', '=', id)
+    .executeTakeFirst()
+  return row?.pollerCursor ?? null
+}
+
+/**
+ * Writes a subscription's poller cursor. Deliberately does not touch
+ * `updatedAt` — the cursor advances every tick and is not a user mutation.
+ *
+ * @param db - The database.
+ * @param id - The subscription id (`wh_…`).
+ * @param cursor - The keyset cursor to store.
+ */
+export async function setCursor(db: Db.Db, id: string, cursor: string): Promise<void> {
+  await db.kysely
+    .updateTable('webhook_subscriptions')
+    .set({ pollerCursor: cursor })
+    .where('id', '=', id)
+    .execute()
+}
+
+/**
+ * Records a successful delivery: resets the consecutive-failure counter and
+ * stamps `lastDeliveryAt`.
+ *
+ * @param db - The database.
+ * @param id - The subscription id (`wh_…`).
+ * @param now - Delivery timestamp (ISO).
+ * @returns The updated subscription, or `undefined` when the row is absent.
+ */
+export async function recordSuccess(
+  db: Db.Db,
+  id: string,
+  now: string,
+): Promise<Webhooks.Subscription | undefined> {
+  const row = await db.kysely
+    .updateTable('webhook_subscriptions')
+    .set({ failureCount: 0, lastDeliveryAt: now, updatedAt: now })
+    .where('id', '=', id)
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toSubscription(row) : undefined
+}
+
+/**
+ * Records a failed delivery: atomically increments the consecutive-failure
+ * counter and disables the subscription once it reaches `maxFailures` (raw
+ * fragments use storage column names — they bypass the camelCase mapping).
+ *
+ * @param db - The database.
+ * @param id - The subscription id (`wh_…`).
+ * @param maxFailures - Consecutive failures before auto-disabling.
+ * @param now - Failure timestamp (ISO).
+ * @returns The updated subscription, or `undefined` when the row is absent.
+ */
+export async function recordFailure(
+  db: Db.Db,
+  id: string,
+  maxFailures: number,
+  now: string,
+): Promise<Webhooks.Subscription | undefined> {
+  const row = await db.kysely
+    .updateTable('webhook_subscriptions')
+    .set({
+      failureCount: sql`failure_count + 1`,
+      status: sql`CASE WHEN failure_count + 1 >= ${maxFailures} THEN 'disabled' ELSE status END`,
+      updatedAt: now,
+    })
+    .where('id', '=', id)
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toSubscription(row) : undefined
+}
+
+/**
+ * Deletes expired subscriptions (their delivery rows cascade). Called
+ * best-effort from the poller tick.
+ *
+ * @param db - The database.
+ * @param now - ISO timestamp expiry is evaluated against.
+ * @returns The number of rows deleted.
+ */
+export async function pruneExpired(db: Db.Db, now: string): Promise<number> {
+  const result = await db.kysely
+    .deleteFrom('webhook_subscriptions')
+    .where('expiresAt', 'is not', null)
+    .where('expiresAt', '<=', now)
+    .executeTakeFirst()
+  return Number(result.numDeletedRows)
+}
+
+/** Live-row predicate: no expiry, or expiry strictly in the future. */
+function live(now: string) {
+  return (eb: ExpressionBuilder<Db.Database, 'webhook_subscriptions'>) =>
+    eb.or([eb('expiresAt', 'is', null), eb('expiresAt', '>', now)])
+}