@strav/herald 1.0.0-alpha.42

package/src/herald_config.ts

@@ -0,0 +1,32 @@
+/**
+ * `@strav/herald` — runtime config shapes.
+ *
+ * `HeraldConfig` is the `config.herald` shape apps declare in
+ * `config/herald.ts`. Multi-provider by default — a single Albastr
+ * tenant might publish to one GBP location, one Facebook Page, one
+ * Instagram account, and one WordPress site all in parallel.
+ * `providers` is keyed by app-chosen instance name; each entry carries
+ * a `driver` discriminator the framework resolves to a concrete
+ * `HeraldDriver`.
+ *
+ * `ProviderConfig` is free-form so each adapter owns its own config
+ * shape (`MetaProviderConfig` etc.) without forcing the core to know
+ * every vendor field.
+ */
+
+export interface HeraldConfig {
+  /** Key into `providers`. The default routing target for unqualified `herald.*` calls. */
+  default: string
+  providers: Record<string, ProviderConfig>
+}
+
+export interface ProviderConfig {
+  /**
+   * Driver identifier — must match a name registered via
+   * `manager.extend(name, factory)` (typically by an adapter
+   * ServiceProvider).
+   */
+  driver: string
+  /** Driver-specific fields — see each adapter's `*Config`. */
+  [key: string]: unknown
+}

package/src/herald_driver.ts

@@ -0,0 +1,86 @@
+/**
+ * `HeraldDriver` — the driver contract every adapter implements.
+ *
+ * One driver represents a configured provider instance
+ * (`config.herald.providers['meta']`). The manager holds one driver
+ * per configured name and routes publish / update / delete / webhook
+ * calls into it.
+ *
+ * Methods drivers don't support throw `ProviderUnsupportedError`
+ * synchronously. The driver's `capabilities` set declares the
+ * supported surfaces — apps that branch on capability avoid the throw
+ * by checking first.
+ */
+
+import type { PostStatus } from './dto/post_status.ts'
+import type { PublishInput } from './dto/publish_input.ts'
+import type { PublishResult } from './dto/publish_result.ts'
+import type { PublishTarget } from './dto/publish_target.ts'
+import type { HeraldCapability } from './herald_capabilities.ts'
+import type { HeraldWebhookEvent } from './webhook/herald_event.ts'
+
+/**
+ * Inbound webhook verification + parsing. Drivers that lack a webhook
+ * surface (rare for a publishing target — engagement comes back as
+ * comments / reviews) declare neither `webhook.signature` nor
+ * `webhook.parse` capabilities and throw `ProviderUnsupportedError`
+ * from these methods.
+ */
+export interface WebhookOps {
+  /**
+   * Verify the provider signature against the raw request body.
+   * Returns `true` when the signature matches. Drivers throw
+   * `WebhookSignatureError` only when the header is missing / malformed;
+   * a clean mismatch returns `false` so the route can decide how to
+   * respond.
+   */
+  verifySignature(rawBody: string, signature: string | null | undefined): boolean
+  /**
+   * Parse a verified raw body into the framework's normalized
+   * `HeraldWebhookEvent` union. Drivers translate every event variant
+   * they can recognise; unknown shapes map to
+   * `{ type: 'unknown', raw, … }`. One delivery often carries
+   * multiple events (Meta batches feed updates) — return them in
+   * order; the dispatcher dedupes per-event by `event.id`.
+   */
+  parse(rawBody: string): HeraldWebhookEvent[]
+}
+
+export interface HeraldDriver {
+  /** Driver identifier — matches the `driver:` discriminator in `ProviderConfig`. */
+  readonly name: string
+  /** App-chosen instance name (`config.herald.providers[name]`). */
+  readonly instanceName: string
+  /** Declared feature set. Apps check this to branch around `ProviderUnsupportedError`. */
+  readonly capabilities: ReadonlySet<HeraldCapability>
+
+  /** Publish a post to the target account. */
+  publish(target: PublishTarget, input: PublishInput): Promise<PublishResult>
+
+  /**
+   * Update an existing post on the platform. Drivers that don't
+   * support edits (GBP Posts, IG feed posts) throw
+   * `ProviderUnsupportedError`.
+   */
+  update?(
+    target: PublishTarget,
+    providerPostId: string,
+    input: PublishInput,
+  ): Promise<PublishResult>
+
+  /** Delete a post from the platform. */
+  delete?(target: PublishTarget, providerPostId: string): Promise<void>
+
+  /** Read the platform-side status of a previously published post. */
+  get?(target: PublishTarget, providerPostId: string): Promise<PostStatus>
+
+  readonly webhook: WebhookOps
+}
+
+/** Factory the manager invokes for each configured provider. */
+export type HeraldDriverFactory = (config: {
+  /** App-chosen instance name (`'meta'`, `'meta-marketing'`, …). */
+  instanceName: string
+  /** Provider-config object with `driver:` + driver-specific fields. */
+  config: Record<string, unknown> & { driver: string }
+}) => HeraldDriver

package/src/herald_manager.ts

@@ -0,0 +1,169 @@
+/**
+ * `HeraldManager` — the facade apps use for micro-publishing
+ * workflows.
+ *
+ * Mirrors the manager-pattern shared with `@strav/payment`,
+ * `@strav/instant`, and `@strav/notification`:
+ *
+ *   - **Drivers.** Apps declare providers in
+ *     `config.herald.providers`. The manager constructs each driver
+ *     lazily on first `use(name)` + memoizes. Adapter packages
+ *     register their factories via `manager.extend(name, factory)`.
+ *
+ *   - **Default routing.** `manager.publish(target, input)` looks
+ *     up the driver named by `target.provider` (not the
+ *     `config.default`); the default only kicks in for
+ *     unqualified `use()` calls in tests / one-offs.
+ *
+ *   - **Webhooks.** `manager.verify(provider, rawBody, sig)` and
+ *     `manager.parseWebhook(provider, rawBody)` delegate into the
+ *     driver's `WebhookOps`. Apps wire these into their HTTP route
+ *     (one route per provider). Slice 3 adds `manager.webhook` — a
+ *     `HeraldWebhookRegistry` for typed-handler dispatch with
+ *     idempotency + ledger persistence.
+ */
+
+import type { PostStatus } from './dto/post_status.ts'
+import type { PublishInput } from './dto/publish_input.ts'
+import type { PublishResult } from './dto/publish_result.ts'
+import type { PublishTarget } from './dto/publish_target.ts'
+import { HeraldConfigError, ProviderUnsupportedError, UnknownProviderError } from './errors.ts'
+import type { HeraldConfig, ProviderConfig } from './herald_config.ts'
+import type { HeraldDriver, HeraldDriverFactory } from './herald_driver.ts'
+import type {
+  HeraldEventType,
+  HeraldWebhookEvent,
+  WebhookHandler,
+  WebhookHandlerFilter,
+} from './webhook/herald_event.ts'
+import { HeraldWebhookRegistry } from './webhook/herald_webhook_registry.ts'
+
+export interface HeraldManagerOptions {
+  config: HeraldConfig
+}
+
+export class HeraldManager {
+  readonly config: HeraldConfig
+  readonly webhookRegistry: HeraldWebhookRegistry = new HeraldWebhookRegistry()
+
+  private readonly drivers = new Map<string, HeraldDriver>()
+  private readonly extensions = new Map<string, HeraldDriverFactory>()
+
+  constructor(options: HeraldManagerOptions) {
+    const { config } = options
+    if (!config.providers[config.default]) {
+      throw new HeraldConfigError(
+        `HeraldManager: default provider "${config.default}" is not configured.`,
+        {
+          context: {
+            default: config.default,
+            available: Object.keys(config.providers),
+          },
+        },
+      )
+    }
+    this.config = config
+  }
+
+  // ─── Driver routing ──────────────────────────────────────────────────
+
+  /** Resolve a driver by app-chosen instance name (or the default when omitted). */
+  use(name?: string): HeraldDriver {
+    const key = name ?? this.config.default
+    const cached = this.drivers.get(key)
+    if (cached) return cached
+
+    const cfg = this.config.providers[key]
+    if (!cfg) {
+      throw new UnknownProviderError(key, Object.keys(this.config.providers))
+    }
+    const ext = this.extensions.get(cfg.driver)
+    if (!ext) {
+      throw new HeraldConfigError(
+        `HeraldManager: unknown driver "${cfg.driver}" for provider "${key}". Register it via \`manager.extend("${cfg.driver}", factory)\` or install the matching adapter package.`,
+        { context: { driver: cfg.driver, available: [...this.extensions.keys()] } },
+      )
+    }
+    const driver = ext({
+      instanceName: key,
+      config: cfg as ProviderConfig & { driver: string },
+    })
+    this.drivers.set(key, driver)
+    return driver
+  }
+
+  /**
+   * Register a driver factory. Adapter packages call this from their
+   * ServiceProvider's `register()` step.
+   */
+  extend(driverName: string, factory: HeraldDriverFactory): void {
+    this.extensions.set(driverName, factory)
+  }
+
+  /** Hand-wire a driver instance under an app-chosen name (tests / one-offs). */
+  useDriver(instanceName: string, driver: HeraldDriver): void {
+    this.drivers.set(instanceName, driver)
+  }
+
+  // ─── Convenience delegates ───────────────────────────────────────────
+
+  publish(target: PublishTarget, input: PublishInput): Promise<PublishResult> {
+    return this.use(target.provider).publish(target, input)
+  }
+
+  update(
+    target: PublishTarget,
+    providerPostId: string,
+    input: PublishInput,
+  ): Promise<PublishResult> {
+    const driver = this.use(target.provider)
+    if (!driver.update) throw new ProviderUnsupportedError(driver.name, 'update')
+    return driver.update(target, providerPostId, input)
+  }
+
+  delete(target: PublishTarget, providerPostId: string): Promise<void> {
+    const driver = this.use(target.provider)
+    if (!driver.delete) throw new ProviderUnsupportedError(driver.name, 'delete')
+    return driver.delete(target, providerPostId)
+  }
+
+  get(target: PublishTarget, providerPostId: string): Promise<PostStatus> {
+    const driver = this.use(target.provider)
+    if (!driver.get) throw new ProviderUnsupportedError(driver.name, 'get')
+    return driver.get(target, providerPostId)
+  }
+
+  // ─── Webhook routing ─────────────────────────────────────────────────
+
+  /** Verify a webhook signature using the named provider's driver. */
+  verify(provider: string, rawBody: string, signature: string | null | undefined): boolean {
+    return this.use(provider).webhook.verifySignature(rawBody, signature)
+  }
+
+  /** Parse a verified raw webhook body into the framework's normalized event union. */
+  parseWebhook(provider: string, rawBody: string): HeraldWebhookEvent[] {
+    return this.use(provider).webhook.parse(rawBody)
+  }
+
+  /**
+   * Register a handler for a normalized webhook event type.
+   * Sugar over `manager.webhookRegistry.on(...)`.
+   */
+  onWebhookEvent(eventType: HeraldEventType, handler: WebhookHandler): void
+  onWebhookEvent(
+    eventType: HeraldEventType,
+    filter: WebhookHandlerFilter,
+    handler: WebhookHandler,
+  ): void
+  onWebhookEvent(
+    eventType: HeraldEventType,
+    filterOrHandler: WebhookHandlerFilter | WebhookHandler,
+    maybeHandler?: WebhookHandler,
+  ): void {
+    if (typeof filterOrHandler === 'function') {
+      this.webhookRegistry.on(eventType, filterOrHandler)
+    } else {
+      this.webhookRegistry.on(eventType, filterOrHandler, maybeHandler!)
+    }
+  }
+}

package/src/herald_provider.ts

@@ -0,0 +1,44 @@
+/**
+ * `HeraldProvider` — `ServiceProvider` that wires `HeraldManager` into
+ * the container from `config.herald`.
+ *
+ * Adapter packages register their drivers separately via their own
+ * ServiceProvider (e.g. `MetaHeraldProvider`). Apps list the adapter
+ * providers AFTER `HeraldProvider` in `bootstrap/providers.ts` —
+ * `register()` runs in declaration order, then `boot()` runs in the
+ * same order. Adapter `register()` calls `manager.extend(driver,
+ * factory)`; this provider's `boot()` eagerly resolves so config
+ * errors surface at startup.
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { HeraldConfigError } from './errors.ts'
+import type { HeraldConfig } from './herald_config.ts'
+import { HeraldManager } from './herald_manager.ts'
+
+export class HeraldProvider extends ServiceProvider {
+  override readonly name = 'herald'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(HeraldManager, (c) => {
+      const raw = c.resolve(ConfigRepository).get('herald') as HeraldConfig | undefined
+      if (!raw) {
+        throw new HeraldConfigError(
+          'HeraldProvider: `config.herald` is missing. Add `config/herald.ts` with at least one provider.',
+        )
+      }
+      if (!raw.providers || Object.keys(raw.providers).length === 0) {
+        throw new HeraldConfigError(
+          'HeraldProvider: `config.herald.providers` is empty. Configure at least one provider.',
+        )
+      }
+      return new HeraldManager({ config: raw })
+    })
+  }
+
+  override boot(app: Application): void {
+    // Force-resolve so config errors surface at boot, not on first publish().
+    app.resolve(HeraldManager)
+  }
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+// Public API of `@strav/herald`.
+//
+// V1: provider-agnostic micro-publishing abstraction — normalized
+// `PublishInput` + `PublishResult` + multi-provider routing. Drivers
+// (WordPress, Meta, Google Business Profile) ship as subpath imports
+// in follow-up slices: `@strav/herald/wordpress`, `@strav/herald/meta`,
+// `@strav/herald/gbp`. X (Twitter), TikTok, LinkedIn, Threads come
+// later.
+
+export type { PostStatus } from './dto/post_status.ts'
+export type { PublishAttachment, PublishInput } from './dto/publish_input.ts'
+export type { PublishResult } from './dto/publish_result.ts'
+export type { PublishTarget } from './dto/publish_target.ts'
+export {
+  HeraldConfigError,
+  HeraldError,
+  HeraldProviderError,
+  ProviderUnsupportedError,
+  UnknownProviderError,
+  WebhookSignatureError,
+} from './errors.ts'
+export type { HeraldCapability } from './herald_capabilities.ts'
+export type { HeraldConfig, ProviderConfig } from './herald_config.ts'
+export type {
+  HeraldDriver,
+  HeraldDriverFactory,
+  WebhookOps,
+} from './herald_driver.ts'
+export {
+  HeraldManager,
+  type HeraldManagerOptions,
+} from './herald_manager.ts'
+export { HeraldProvider } from './herald_provider.ts'
+export {
+  applyPublicationMigration,
+  type ApplyPublicationMigrationOptions,
+  type MarkPublishedInput,
+  Publication,
+  PublicationRepository,
+  type RecordInput,
+  publicationSchema,
+} from './ledger/index.ts'
+export {
+  applyHeraldWebhookEventMigration,
+  type ApplyHeraldWebhookEventMigrationOptions,
+  type CommentEvent,
+  type HeraldEventType,
+  type HeraldWebhookEvent,
+  type HeraldWebhookEventBase,
+  HeraldWebhookEventRecord,
+  HeraldWebhookEventRepository,
+  heraldWebhookEventSchema,
+  heraldWebhook,
+  type HeraldWebhookOptions,
+  HeraldWebhookRegistry,
+  type PostDeletedEvent,
+  type PostFailedEvent,
+  type PostPublishedEvent,
+  type ReactionEvent,
+  type ReviewEvent,
+  type UnknownEvent,
+  type WebhookHandler,
+  type WebhookHandlerContext,
+  type WebhookHandlerFilter,
+} from './webhook/index.ts'

package/src/ledger/apply_publication_migration.ts

@@ -0,0 +1,53 @@
+/**
+ * `applyPublicationMigration` — emit DDL for the `publication` table
+ * plus its composite unique constraint and lookup indexes.
+ *
+ * Non-tenanted by default (framework policy: multitenancy is opt-in).
+ * Apps that need per-tenant scoping use
+ * `applyTenantedPublicationMigration` from `@strav/herald/tenanted`
+ * instead.
+ */
+
+import {
+  emitCreateTable,
+  type DatabaseExecutor,
+  type SchemaRegistry,
+} from '@strav/database'
+import { publicationSchema } from './publication_schema.ts'
+
+export interface ApplyPublicationMigrationOptions {
+  /** Required for `emitCreateTable` to resolve relations. */
+  registry: SchemaRegistry
+}
+
+export async function applyPublicationMigration(
+  db: DatabaseExecutor,
+  options: ApplyPublicationMigrationOptions,
+): Promise<void> {
+  const { registry } = options
+
+  await db.execute(emitCreateTable(publicationSchema, { registry }).sql)
+
+  // Provider-post uniqueness — one row per platform-side post.
+  // Webhook reconciliation (`findByProviderPostId`) leans on this.
+  // Partial index: `provider_post_id` is nullable while a publish
+  // sits in `pending`; the unique constraint only applies once an id
+  // has been assigned.
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_publication_provider_post"
+     ON "${publicationSchema.name}" ("provider", "instance_name", "provider_post_id")
+     WHERE "provider_post_id" IS NOT NULL`,
+  )
+
+  // "All channels for source" lookup — per-post status UI.
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_publication_source"
+     ON "${publicationSchema.name}" ("source_id")`,
+  )
+
+  // Operational query: "all pending / failed publishes for a provider".
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_publication_provider_status"
+     ON "${publicationSchema.name}" ("provider", "status")`,
+  )
+}

package/src/ledger/index.ts

@@ -0,0 +1,11 @@
+export {
+  applyPublicationMigration,
+  type ApplyPublicationMigrationOptions,
+} from './apply_publication_migration.ts'
+export { Publication } from './publication.ts'
+export {
+  type MarkPublishedInput,
+  PublicationRepository,
+  type RecordInput,
+} from './publication_repository.ts'
+export { publicationSchema } from './publication_schema.ts'

package/src/ledger/publication.ts

@@ -0,0 +1,30 @@
+/**
+ * `Publication` — typed row of the published-post ledger.
+ *
+ * No `@encrypt` columns: this ledger holds public-facing references
+ * (provider post id, URL, status), not credentials. Credentials live
+ * in `@strav/social`'s `social_account` table and are loaded on
+ * demand by the drivers.
+ */
+
+import { Model } from '@strav/database'
+import type { PostStatus } from '../dto/post_status.ts'
+import { publicationSchema } from './publication_schema.ts'
+
+export class Publication extends Model {
+  static override readonly schema = publicationSchema
+
+  id!: string
+  source_id!: string
+  provider!: string
+  instance_name!: string
+  account_id!: string
+  provider_post_id!: string | null
+  url!: string | null
+  status!: PostStatus
+  published_at!: Date | null
+  error_message!: string | null
+  metadata!: Record<string, unknown>
+  created_at!: Date
+  updated_at!: Date
+}

package/src/ledger/publication_repository.ts

@@ -0,0 +1,172 @@
+/**
+ * `PublicationRepository` — domain helpers on top of the generic CRUD
+ * surface. The methods apps actually use:
+ *
+ *   - `record({ sourceId, target, result, instanceName })` — upsert
+ *     by `(provider, instance_name, provider_post_id)`. Called
+ *     immediately after a successful `herald.publish(...)`. When
+ *     status is `pending` (no `provider_post_id` yet), inserts a
+ *     fresh row; webhook reconciliation later updates it via
+ *     `markPublished` / `markFailed`.
+ *
+ *   - `markPublished(id, { providerPostId, url, publishedAt })` —
+ *     flip status from `pending` to `published`. Called from
+ *     webhook handlers when the platform confirms.
+ *
+ *   - `markFailed(id, errorMessage)` — flip status to `failed`.
+ *
+ *   - `markDeleted(id)` — flip status to `deleted` after a successful
+ *     `herald.delete(...)`.
+ *
+ *   - `findBySource(sourceId)` — list every channel one app-side
+ *     post fanned out to. Apps render per-post status UIs from this.
+ *
+ *   - `findByProviderPostId(provider, instanceName, providerPostId)` —
+ *     reverse lookup for webhook reconciliation: "this engagement
+ *     event names provider X post Y, which row does it belong to?"
+ */
+
+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 { Publication } from './publication.ts'
+import { publicationSchema } from './publication_schema.ts'
+
+export interface RecordInput {
+  /** App-side post / draft id this publication belongs to. */
+  sourceId: string
+  /** `config.herald.providers[name]` — usually `target.provider`. */
+  instanceName: string
+  target: PublishTarget
+  result: PublishResult
+  /** Optional driver extras to persist alongside the canonical fields. */
+  metadata?: Record<string, unknown>
+}
+
+export interface MarkPublishedInput {
+  providerPostId: string
+  url?: string
+  publishedAt?: Date
+}
+
+export class PublicationRepository extends Repository<Publication> {
+  static override readonly schema = publicationSchema
+  static override readonly model = Publication
+
+  /**
+   * Upsert a publication row from a `PublishResult`. Re-recording the
+   * same `provider_post_id` (e.g. on webhook reconciliation) updates
+   * the existing row in place rather than inserting a duplicate.
+   */
+  async record(input: RecordInput): Promise<Publication> {
+    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<Publication>)
+      }
+    }
+
+    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<Publication>)
+  }
+
+  async markPublished(id: string, input: MarkPublishedInput): Promise<void> {
+    const table = quoteIdent(publicationSchema.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(publicationSchema.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(publicationSchema.name)
+    await this.db.execute(
+      `UPDATE ${table}
+       SET "status" = 'deleted',
+           "updated_at" = $2
+       WHERE "id" = $1`,
+      [id, new Date()],
+    )
+  }
+
+  /** Every channel one app-side post fanned out to. */
+  async findBySource(sourceId: string): Promise<Publication[]> {
+    const table = quoteIdent(publicationSchema.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)))
+  }
+
+  /** Reverse lookup for webhook reconciliation. */
+  async findByProviderPostId(
+    provider: string,
+    instanceName: string,
+    providerPostId: string,
+  ): Promise<Publication | null> {
+    const table = quoteIdent(publicationSchema.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]!)
+  }
+}