@strav/herald 1.0.0-alpha.42

package/src/tenanted/tenanted_publication_repository.ts

@@ -0,0 +1,145 @@
+/**
+ * `TenantedPublicationRepository` — same surface as
+ * `PublicationRepository`, scoped to the tenanted schema. Callers
+ * MUST be inside a `TenantManager.withTenant(...)` scope; INSERTs
+ * rely on the session's `app.tenant_id` setting (RLS).
+ *
+ * Mirrors the non-tenanted Repository line-for-line — minor
+ * duplication is worth keeping both variants narrowly scoped + avoid
+ * runtime branching on a tenancy flag.
+ */
+
+import { quoteIdent, Repository } from '@strav/database'
+import { ulid } from '@strav/kernel'
+import type { PublishResult } from '../dto/publish_result.ts'
+import type { PublishTarget } from '../dto/publish_target.ts'
+import { TenantedPublication } from './tenanted_publication.ts'
+import { tenantedPublicationSchema } from './tenanted_publication_schema.ts'
+
+export interface RecordInput {
+  sourceId: string
+  instanceName: string
+  target: PublishTarget
+  result: PublishResult
+  metadata?: Record<string, unknown>
+}
+
+export interface MarkPublishedInput {
+  providerPostId: string
+  url?: string
+  publishedAt?: Date
+}
+
+export class TenantedPublicationRepository extends Repository<TenantedPublication> {
+  static override readonly schema = tenantedPublicationSchema
+  static override readonly model = TenantedPublication
+
+  async record(input: RecordInput): Promise<TenantedPublication> {
+    const now = new Date()
+
+    if (input.result.providerPostId) {
+      const existing = await this.findByProviderPostId(
+        input.target.provider,
+        input.instanceName,
+        input.result.providerPostId,
+      )
+      if (existing) {
+        return this.update(existing, {
+          source_id: input.sourceId,
+          account_id: input.target.accountId,
+          url: input.result.url ?? null,
+          status: input.result.status,
+          published_at: input.result.status === 'published' ? now : existing.published_at,
+          error_message: null,
+          metadata: { ...existing.metadata, ...(input.metadata ?? {}) },
+          updated_at: now,
+        } as Partial<TenantedPublication>)
+      }
+    }
+
+    return this.create({
+      id: ulid(),
+      source_id: input.sourceId,
+      provider: input.target.provider,
+      instance_name: input.instanceName,
+      account_id: input.target.accountId,
+      provider_post_id: input.result.providerPostId || null,
+      url: input.result.url ?? null,
+      status: input.result.status,
+      published_at: input.result.status === 'published' ? now : null,
+      error_message: null,
+      metadata: input.metadata ?? {},
+      created_at: now,
+      updated_at: now,
+    } as Partial<TenantedPublication>)
+  }
+
+  async markPublished(id: string, input: MarkPublishedInput): Promise<void> {
+    const table = quoteIdent(tenantedPublicationSchema.name)
+    await this.db.execute(
+      `UPDATE ${table}
+       SET "provider_post_id" = $2,
+           "url" = $3,
+           "status" = 'published',
+           "published_at" = $4,
+           "error_message" = NULL,
+           "updated_at" = $5
+       WHERE "id" = $1`,
+      [
+        id,
+        input.providerPostId,
+        input.url ?? null,
+        input.publishedAt ?? new Date(),
+        new Date(),
+      ],
+    )
+  }
+
+  async markFailed(id: string, errorMessage: string): Promise<void> {
+    const table = quoteIdent(tenantedPublicationSchema.name)
+    await this.db.execute(
+      `UPDATE ${table}
+       SET "status" = 'failed',
+           "error_message" = $2,
+           "updated_at" = $3
+       WHERE "id" = $1`,
+      [id, errorMessage, new Date()],
+    )
+  }
+
+  async markDeleted(id: string): Promise<void> {
+    const table = quoteIdent(tenantedPublicationSchema.name)
+    await this.db.execute(
+      `UPDATE ${table}
+       SET "status" = 'deleted',
+           "updated_at" = $2
+       WHERE "id" = $1`,
+      [id, new Date()],
+    )
+  }
+
+  async findBySource(sourceId: string): Promise<TenantedPublication[]> {
+    const table = quoteIdent(tenantedPublicationSchema.name)
+    const rows = await this.db.query<Record<string, unknown>>(
+      `SELECT * FROM ${table} WHERE "source_id" = $1 ORDER BY "created_at"`,
+      [sourceId],
+    )
+    return Promise.all(rows.map((r) => this.hydrate(r)))
+  }
+
+  async findByProviderPostId(
+    provider: string,
+    instanceName: string,
+    providerPostId: string,
+  ): Promise<TenantedPublication | null> {
+    const table = quoteIdent(tenantedPublicationSchema.name)
+    const rows = await this.db.query<Record<string, unknown>>(
+      `SELECT * FROM ${table}
+       WHERE "provider" = $1 AND "instance_name" = $2 AND "provider_post_id" = $3
+       LIMIT 1`,
+      [provider, instanceName, providerPostId],
+    )
+    if (rows.length === 0) return null
+    return this.hydrate(rows[0]!)
+  }
+}

package/src/tenanted/tenanted_publication_schema.ts

@@ -0,0 +1,35 @@
+/**
+ * `tenantedPublicationSchema` — opt-in tenant-scoped variant of the
+ * publication ledger. Imported from `@strav/herald/tenanted` so apps
+ * that don't need multitenancy don't pay for it.
+ *
+ * Same columns as the default `publicationSchema`, with
+ * `tenanted: true` so `@strav/database` injects the `tenant_id` FK
+ * + RLS policy. Composite unique becomes
+ * `(tenant_id, provider, instance_name, provider_post_id)` — two
+ * tenants can each have a publication for the same provider id
+ * (rare in practice; collision-safe by construction).
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const tenantedPublicationSchema = defineSchema(
+  'publication',
+  Archetype.Entity,
+  (t) => {
+    t.id()
+    t.string('source_id').max(64).notNull()
+    t.string('provider').max(64).notNull()
+    t.string('instance_name').max(64).notNull()
+    t.string('account_id').max(255).notNull()
+    t.string('provider_post_id').max(255).nullable()
+    t.string('url').max(2048).nullable()
+    t.string('status').max(16).notNull()
+    t.timestamp('published_at').nullable()
+    t.string('error_message').max(1024).nullable()
+    t.json('metadata').notNull().default({})
+    t.timestamp('created_at').notNull()
+    t.timestamp('updated_at').notNull()
+  },
+  { tenanted: true },
+)

package/src/webhook/apply_herald_webhook_event_migration.ts

@@ -0,0 +1,42 @@
+/**
+ * `applyHeraldWebhookEventMigration` — DDL for the webhook dedup
+ * ledger plus the composite-unique index it relies on.
+ *
+ * Non-tenanted by construction: webhooks arrive before tenant
+ * context is known. Apps include this migration regardless of
+ * whether they use the tenanted publication ledger variant.
+ */
+
+import {
+  emitCreateTable,
+  type DatabaseExecutor,
+  type SchemaRegistry,
+} from '@strav/database'
+import { heraldWebhookEventSchema } from './herald_webhook_event_schema.ts'
+
+export interface ApplyHeraldWebhookEventMigrationOptions {
+  registry: SchemaRegistry
+}
+
+export async function applyHeraldWebhookEventMigration(
+  db: DatabaseExecutor,
+  options: ApplyHeraldWebhookEventMigrationOptions,
+): Promise<void> {
+  const { registry } = options
+
+  await db.execute(emitCreateTable(heraldWebhookEventSchema, { registry }).sql)
+
+  // Dedup contract — first INSERT for a `(provider, provider_event_id)`
+  // wins; replays return 200 without re-firing handlers.
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_herald_webhook_event_dedup"
+     ON "${heraldWebhookEventSchema.name}" ("provider", "provider_event_id")`,
+  )
+
+  // Ops query: "stuck deliveries" — received but never processed.
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_herald_webhook_event_unprocessed"
+     ON "${heraldWebhookEventSchema.name}" ("received_at")
+     WHERE "processed_at" IS NULL`,
+  )
+}

package/src/webhook/herald_event.ts

@@ -0,0 +1,139 @@
+/**
+ * Normalized webhook event types for `@strav/herald`.
+ *
+ * Drivers map their native event shapes (GBP `LOCAL_POST_REVIEW`,
+ * Meta `feed.comment`, WP REST custom hooks) onto this closed union.
+ * Apps register handlers by normalized type via
+ * `HeraldWebhookRegistry`; the native event is on `ctx.raw`.
+ *
+ * Two event families:
+ *
+ *   - **post.** — async confirmation of a publish that initially
+ *     returned `pending`. Apps reconcile by calling
+ *     `PublicationRepository.markPublished` / `markFailed` /
+ *     `markDeleted` from the handler.
+ *
+ *   - **engagement.** — inbound interactions on a published post
+ *     (comments, reactions, reviews). Apps surface these to
+ *     operators, notify the owner, run moderation, etc.
+ *
+ * The `unknown` variant is for events the driver can't (or won't)
+ * map onto the closed union — the dedup row still records receipt
+ * so ops dashboards can spot novel events.
+ */
+
+export type HeraldEventType =
+  // publish lifecycle (async confirmation)
+  | 'post.published'
+  | 'post.failed'
+  | 'post.deleted'
+  // engagement on a published post
+  | 'engagement.comment'
+  | 'engagement.review'
+  | 'engagement.reaction'
+  // catch-all
+  | 'unknown'
+
+export interface HeraldWebhookEventBase {
+  /** Driver-assigned id; the dedup key. */
+  id: string
+  /** Normalized type. */
+  type: HeraldEventType
+  /**
+   * App-chosen instance name (the `:provider` route param, matches
+   * `herald.use(name)`). Drivers' `parse` sets this to the driver
+   * name (`'gbp'` / `'meta'`); the dispatcher overrides with the
+   * instance name.
+   */
+  provider: string
+  /**
+   * Provider-side account the event belongs to (FB Page id, GBP
+   * location id, WP site host). Matches `PublishTarget.accountId`.
+   * Lets apps reverse-lookup the tenant via their account → tenant
+   * map; webhooks themselves arrive without tenant context.
+   */
+  accountId: string
+  /** Provider-issued post id the event refers to, when applicable. */
+  providerPostId?: string
+  /** Best-known platform-side timestamp of the event. */
+  occurredAt?: Date
+  /** Native provider event payload. */
+  raw: unknown
+}
+
+export interface PostPublishedEvent extends HeraldWebhookEventBase {
+  type: 'post.published'
+  providerPostId: string
+  url?: string
+}
+
+export interface PostFailedEvent extends HeraldWebhookEventBase {
+  type: 'post.failed'
+  errorMessage: string
+}
+
+export interface PostDeletedEvent extends HeraldWebhookEventBase {
+  type: 'post.deleted'
+  providerPostId: string
+}
+
+export interface CommentEvent extends HeraldWebhookEventBase {
+  type: 'engagement.comment'
+  providerPostId: string
+  commentId: string
+  authorId?: string
+  authorName?: string
+  text?: string
+  parentCommentId?: string
+}
+
+export interface ReviewEvent extends HeraldWebhookEventBase {
+  type: 'engagement.review'
+  reviewId: string
+  rating?: number
+  text?: string
+  authorName?: string
+}
+
+export interface ReactionEvent extends HeraldWebhookEventBase {
+  type: 'engagement.reaction'
+  providerPostId: string
+  reactionType: string
+  authorId?: string
+}
+
+export interface UnknownEvent extends HeraldWebhookEventBase {
+  type: 'unknown'
+}
+
+export type HeraldWebhookEvent =
+  | PostPublishedEvent
+  | PostFailedEvent
+  | PostDeletedEvent
+  | CommentEvent
+  | ReviewEvent
+  | ReactionEvent
+  | UnknownEvent
+
+// ─── Handler types ──────────────────────────────────────────────────
+
+export interface WebhookHandlerContext {
+  event: HeraldWebhookEvent
+  /** Convenience shortcut for `event.id`. */
+  eventId: string
+  /** Convenience shortcut for `event.type`. */
+  eventType: HeraldEventType
+  /** Convenience shortcut for `event.provider`. */
+  provider: string
+  /** Convenience shortcut for `event.accountId`. */
+  accountId: string
+  /** Convenience shortcut for `event.raw`. */
+  raw: unknown
+}
+
+export type WebhookHandler = (ctx: WebhookHandlerContext) => void | Promise<void>
+
+export interface WebhookHandlerFilter {
+  /** Restrict the handler to one provider instance. Omitted = fires for any provider that emits the type. */
+  provider?: string
+}

package/src/webhook/herald_webhook.ts

@@ -0,0 +1,149 @@
+/**
+ * Provider-agnostic webhook route handler.
+ *
+ * Mount once per app:
+ *
+ *   router.post('/webhooks/herald/:provider', heraldWebhook())
+ *
+ * Per request flow:
+ *
+ *   1. Read the `:provider` route param — picks the driver instance
+ *      to verify against.
+ *   2. Read the raw body. Signature is computed over the bytes, so
+ *      JSON-parsing first invalidates verification.
+ *   3. Resolve the signature header — drivers carry their own header
+ *      name (`x-hub-signature-256` for Meta, `x-wp-signature` for
+ *      WP, …); the handler reads them all.
+ *   4. `driver.webhook.verifySignature(rawBody, signature)` — 400 on
+ *      missing / malformed; `false` on clean mismatch also returns
+ *      400 (provider retries).
+ *   5. `driver.webhook.parse(rawBody)` — driver normalizes every
+ *      event in the batch into the `HeraldWebhookEvent` union.
+ *   6. Per event: idempotency claim against
+ *      `herald_webhook_event(provider, provider_event_id)`. The
+ *      first delivery wins; replays are skipped.
+ *   7. Dispatch matching handlers from `HeraldWebhookRegistry`.
+ *      Handlers run in registration order. Throwing leaves
+ *      `processed_at` NULL so dashboards surface stuck events; the
+ *      route returns 500 so the provider retries the batch.
+ *   8. Mark `processed_at` on success.
+ */
+
+import type { HttpContext } from '@strav/http'
+import { UnknownProviderError, WebhookSignatureError } from '../errors.ts'
+import { HeraldManager } from '../herald_manager.ts'
+import type { HeraldWebhookEvent, WebhookHandlerContext } from './herald_event.ts'
+import { HeraldWebhookEventRepository } from './herald_webhook_event_repository.ts'
+
+export interface HeraldWebhookOptions {
+  /**
+   * Extra header names to probe for the provider signature. The
+   * built-in list covers the v1 drivers; apps with custom drivers
+   * append theirs.
+   */
+  signatureHeaders?: readonly string[]
+}
+
+const DEFAULT_SIGNATURE_HEADERS = [
+  // Meta (Facebook + Instagram)
+  'x-hub-signature-256',
+  'x-hub-signature',
+  // WordPress (custom plugin)
+  'x-wp-signature',
+  // Google (X-Goog-Channel-Token + signature)
+  'x-goog-signature',
+  // Generic fallback for custom drivers
+  'webhook-signature',
+]
+
+export function heraldWebhook(
+  options: HeraldWebhookOptions = {},
+): (ctx: HttpContext) => Promise<Response> {
+  const headerNames = options.signatureHeaders ?? DEFAULT_SIGNATURE_HEADERS
+
+  return async (ctx: HttpContext): Promise<Response> => {
+    const providerName = ctx.request.params['provider']
+    if (!providerName) {
+      return ctx.response.json(
+        { error: 'Missing :provider route param. Mount as `/webhooks/herald/:provider`.' },
+        { status: 400 },
+      )
+    }
+
+    const manager = ctx.container.resolve(HeraldManager)
+    let driver
+    try {
+      driver = manager.use(providerName)
+    } catch (cause) {
+      if (cause instanceof UnknownProviderError) {
+        return ctx.response.json({ error: cause.message }, { status: 404 })
+      }
+      throw cause
+    }
+
+    const signature = findSignatureHeader(ctx.request.headers, headerNames)
+    const rawBody = await ctx.request.raw.text()
+
+    let verified: boolean
+    try {
+      verified = driver.webhook.verifySignature(rawBody, signature)
+    } catch (cause) {
+      if (cause instanceof WebhookSignatureError) {
+        return ctx.response.json({ error: cause.message }, { status: 400 })
+      }
+      throw cause
+    }
+    if (!verified) {
+      return ctx.response.json({ error: 'Webhook signature verification failed.' }, { status: 400 })
+    }
+
+    const events = driver.webhook.parse(rawBody) as HeraldWebhookEvent[]
+    const repo = ctx.container.resolve(HeraldWebhookEventRepository)
+    const results: Array<{ id: string; type: string; duplicate: boolean }> = []
+
+    for (const event of events) {
+      // Honour instance-name routing — drivers stamp `provider` with
+      // their own name (`'meta'`); the route param is the instance
+      // name apps configured under (`'meta-marketing'`). Handlers
+      // resolve against the instance name.
+      const routed: HeraldWebhookEvent = { ...event, provider: providerName }
+      const claimed = await repo.claim(providerName, routed.id, routed.type)
+      if (!claimed) {
+        results.push({ id: routed.id, type: routed.type, duplicate: true })
+        continue
+      }
+      await dispatch(manager, routed)
+      await repo.markProcessed(providerName, routed.id)
+      results.push({ id: routed.id, type: routed.type, duplicate: false })
+    }
+
+    return ctx.response.json({ received: true, events: results })
+  }
+}
+
+async function dispatch(
+  manager: HeraldManager,
+  event: HeraldWebhookEvent,
+): Promise<void> {
+  const handlers = manager.webhookRegistry.resolve(event.type, event.provider)
+  if (handlers.length === 0) return
+  const ctx: WebhookHandlerContext = {
+    event,
+    eventId: event.id,
+    eventType: event.type,
+    provider: event.provider,
+    accountId: event.accountId,
+    raw: event.raw,
+  }
+  for (const handler of handlers) {
+    await handler(ctx)
+  }
+}
+
+function findSignatureHeader(headers: Headers, names: readonly string[]): string | null {
+  for (const name of names) {
+    const value = headers.get(name)
+    if (value) return value
+  }
+  return null
+}

package/src/webhook/herald_webhook_event.ts

@@ -0,0 +1,25 @@
+/**
+ * `HeraldWebhookEventRecord` — typed row of the dedup ledger.
+ *
+ * Apps rarely touch this directly. Operator dashboards use it to list
+ * recent events, surface processing latencies, or flag stuck
+ * deliveries (rows where `processed_at` is still NULL after dispatch
+ * should have completed).
+ *
+ * Named `…Record` (not `…Event`) to avoid colliding with the
+ * normalized `HeraldWebhookEvent` union in `herald_event.ts`.
+ */
+
+import { Model } from '@strav/database'
+import { heraldWebhookEventSchema } from './herald_webhook_event_schema.ts'
+
+export class HeraldWebhookEventRecord extends Model {
+  static override readonly schema = heraldWebhookEventSchema
+
+  id!: string
+  provider!: string
+  provider_event_id!: string
+  event_type!: string
+  received_at!: Date
+  processed_at!: Date | null
+}

package/src/webhook/herald_webhook_event_repository.ts

@@ -0,0 +1,65 @@
+/**
+ * `HeraldWebhookEventRepository` — data access for the webhook
+ * dedup ledger.
+ *
+ * Two custom helpers on top of the generic CRUD surface:
+ *
+ *   - `claim(provider, eventId, type)` — atomic INSERT ... ON
+ *     CONFLICT DO NOTHING RETURNING *. Returns the row on win,
+ *     `null` when another delivery already recorded the
+ *     `(provider, provider_event_id)` pair.
+ *
+ *   - `markProcessed(provider, eventId)` — bumps `processed_at` to
+ *     NOW(). Observability-only; not part of the dedup decision.
+ *     Rows with `received_at` set but `processed_at` NULL surface
+ *     stuck deliveries (handler threw / process crashed
+ *     mid-dispatch).
+ */
+
+import { quoteIdent, Repository } from '@strav/database'
+import { ulid } from '@strav/kernel'
+import { HeraldWebhookEventRecord } from './herald_webhook_event.ts'
+import { heraldWebhookEventSchema } from './herald_webhook_event_schema.ts'
+
+export class HeraldWebhookEventRepository extends Repository<HeraldWebhookEventRecord> {
+  static override readonly schema = heraldWebhookEventSchema
+  static override readonly model = HeraldWebhookEventRecord
+
+  /**
+   * Atomically record receipt of an event. Returns the inserted row
+   * when this call won the race, `null` when the
+   * `(provider, provider_event_id)` pair was already recorded.
+   */
+  async claim(
+    provider: string,
+    providerEventId: string,
+    eventType: string,
+  ): Promise<HeraldWebhookEventRecord | null> {
+    const table = quoteIdent(heraldWebhookEventSchema.name)
+    const sql = `
+      INSERT INTO ${table}
+        ("id", "provider", "provider_event_id", "event_type", "received_at")
+      VALUES ($1, $2, $3, $4, NOW())
+      ON CONFLICT ("provider", "provider_event_id") DO NOTHING
+      RETURNING *
+    `
+    const rows = await this.db.query<Record<string, unknown>>(sql, [
+      ulid(),
+      provider,
+      providerEventId,
+      eventType,
+    ])
+    if (rows.length === 0) return null
+    return this.hydrate(rows[0]!)
+  }
+
+  /** Bump `processed_at` to NOW(). No-op when the row doesn't exist. */
+  async markProcessed(provider: string, providerEventId: string): Promise<void> {
+    const table = quoteIdent(heraldWebhookEventSchema.name)
+    await this.db.execute(
+      `UPDATE ${table} SET "processed_at" = NOW()
+       WHERE "provider" = $1 AND "provider_event_id" = $2`,
+      [provider, providerEventId],
+    )
+  }
+}

package/src/webhook/herald_webhook_event_schema.ts

@@ -0,0 +1,37 @@
+/**
+ * `heraldWebhookEventSchema` — system-wide dedup ledger for inbound
+ * webhooks from every configured Herald provider.
+ *
+ * On every delivery (after signature verification + parse), the
+ * framework does:
+ *
+ *   INSERT INTO herald_webhook_event (...) ON CONFLICT DO NOTHING
+ *
+ * The first delivery wins the INSERT and fires user handlers;
+ * subsequent deliveries (provider retries, concurrent webhook
+ * workers) see the conflict and return 200 without re-firing.
+ *
+ * **Why NOT tenanted:** webhooks arrive without tenant context.
+ * The dedup INSERT must run before any payload inspection (it gates
+ * handler dispatch); tenant routing — when needed — happens at the
+ * handler layer once the app has resolved `accountId → tenantId`.
+ *
+ * Composite unique `(provider, provider_event_id)` lives in the
+ * migration; different providers may emit colliding id formats so
+ * the pair is the actual uniqueness contract.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const heraldWebhookEventSchema = defineSchema(
+  'herald_webhook_event',
+  Archetype.Event,
+  (t) => {
+    t.id()
+    t.string('provider').max(64).notNull()
+    t.string('provider_event_id').max(255).notNull()
+    t.string('event_type').max(128).notNull()
+    t.timestamp('received_at').notNull()
+    t.timestamp('processed_at').nullable()
+  },
+)