@strav/herald 1.0.0-alpha.42

package/src/ledger/publication_schema.ts

@@ -0,0 +1,70 @@
+/**
+ * `publicationSchema` — ledger of posts published to external
+ * platforms via `@strav/herald`. **Non-tenanted by default**
+ * (framework policy: multitenancy is opt-in). Apps that need
+ * per-tenant scoping import `tenantedPublicationSchema` from
+ * `@strav/herald/tenanted` instead.
+ *
+ * One row per publish attempt that the platform accepted. Apps that
+ * fan out a single conceptual "post" to GBP + Facebook + Instagram +
+ * WordPress get four rows here — one per provider — all linked back
+ * to the app-side post via `source_id`. Failed publishes are recorded
+ * too (status = `failed`) so retry logic + ops dashboards see them.
+ *
+ * Composite uniqueness lives in the migration:
+ *   `(provider, instance_name, provider_post_id)` — one canonical
+ *   row per platform-side post. Re-publishing the same provider_post_id
+ *   (e.g. on webhook reconciliation) upserts.
+ *
+ * Columns:
+ *
+ *   - `id`                ULID PK.
+ *   - `source_id`         App-side post / draft id (free-form
+ *                         string so apps with ULID / int / uuid
+ *                         PKs all fit). Lets apps query "all
+ *                         channels this post went to".
+ *   - `provider`          Driver identifier (`'gbp'` /
+ *                         `'meta'` / `'wordpress'` / custom).
+ *   - `instance_name`     `config.herald.providers[name]` —
+ *                         distinguishes two configs of the same
+ *                         driver (e.g. `meta-th` vs `meta-en`).
+ *   - `account_id`        Provider-side account this was posted
+ *                         to (FB Page id, GBP location id, WP
+ *                         site host). Matches `PublishTarget.accountId`.
+ *   - `provider_post_id`  Provider-issued id of the resulting
+ *                         post. Required once status leaves
+ *                         `pending`; nullable while waiting.
+ *   - `url`               Public URL of the post (when the
+ *                         platform exposes one).
+ *   - `status`            `pending` / `published` / `failed` /
+ *                         `deleted`. Matches `PostStatus`.
+ *   - `published_at`      When the platform confirmed (or our
+ *                         best-known timestamp from the webhook).
+ *   - `error_message`     Last platform-reported failure reason
+ *                         (set when status flips to `failed`).
+ *   - `metadata`          Free-form jsonb — driver extras (GBP
+ *                         search-url, IG media-type, WP post-type, …).
+ *   - `created_at` / `updated_at`
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const publicationSchema = 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()
+  },
+)

package/src/onboarding/complete_channel_connect.ts

@@ -0,0 +1,154 @@
+/**
+ * `completeChannelConnect` — pure async function that runs the
+ * OAuth-callback half of "connect a publishing channel" against
+ * `@strav/social`.
+ *
+ * Flow:
+ *
+ *   1. `social.use(provider).exchange({ code, state?, expectedState?,
+ *      codeVerifier? })` → `OAuthTokens`.
+ *   2. `social.use(provider).profile(tokens.accessToken)` →
+ *      `SocialProfile` (the user we just authenticated).
+ *   3. Per `enumerate` strategy, fetch the connectable list — FB
+ *      pages, IG Business accounts (via FB), or GBP locations.
+ *
+ * Returns `{ provider, profile, tokens, connectables }`. Apps render
+ * the connectable list, let the user pick one (or many), and persist
+ * their choice into `social_account` (or wherever the publishing
+ * driver's `credentialsFor` resolver reads from).
+ *
+ * No state / cookie / session handling lives here — apps verify state
+ * themselves (or via the `connectChannelCallback()` route handler
+ * which wraps this fn plus a cookie-based verifier).
+ *
+ * Duck-type checks the driver for the enumerate-helper method so
+ * `@strav/herald` doesn't take a hard `@strav/social` dep at the
+ * type level (the `SocialManager` peer dep is the only contract).
+ */
+
+import type { OAuthTokens, SocialManager, SocialProfile } from '@strav/social'
+import { HeraldProviderError } from '../errors.ts'
+import type { ChannelConnectable, EnumerationStrategy } from './types.ts'
+
+export interface CompleteChannelConnectInput {
+  social: SocialManager
+  /** Name of the social provider that handles the OAuth dance (typically `'facebook'` or `'google'`). */
+  provider: string
+  /** OAuth callback `code` query param. */
+  code: string
+  /** Redirect URI registered with the provider — must match the one passed at authorize-time. */
+  redirectUri: string
+  /** OAuth callback `state` query param — the value the user came back with. */
+  state?: string
+  /** State the app issued at authorize-time (the trust anchor for verification). */
+  expectedState?: string
+  /** PKCE verifier the app persisted at authorize-time. Required for drivers with PKCE. */
+  codeVerifier?: string
+  /** Which enumeration to run after exchange. `'none'` skips it (apps that only want tokens). */
+  enumerate?: EnumerationStrategy
+}
+
+export interface ChannelConnectResult {
+  provider: string
+  profile: SocialProfile
+  tokens: OAuthTokens
+  connectables: ChannelConnectable[]
+}
+
+interface FacebookEnumerateOps {
+  listPages(token: string): Promise<
+    Array<{ id: string; name: string; category?: string; accessToken: string; tasks?: readonly string[]; raw: unknown }>
+  >
+  listInstagramBusinessAccounts(token: string): Promise<
+    Array<{
+      id: string
+      username?: string
+      name?: string
+      profilePictureUrl?: string
+      pageId: string
+      pageAccessToken: string
+      raw: unknown
+    }>
+  >
+}
+
+interface GoogleEnumerateOps {
+  listGbpLocations(token: string): Promise<
+    Array<{
+      name: string
+      accountName: string
+      title: string
+      address?: string
+      languageCode?: string
+      storeCode?: string
+      raw: unknown
+    }>
+  >
+}
+
+export async function completeChannelConnect(
+  input: CompleteChannelConnectInput,
+): Promise<ChannelConnectResult> {
+  const driver = input.social.use(input.provider)
+  const tokens = await driver.exchange({
+    code: input.code,
+    redirectUri: input.redirectUri,
+    ...(input.state !== undefined ? { state: input.state } : {}),
+    ...(input.expectedState !== undefined ? { expectedState: input.expectedState } : {}),
+    ...(input.codeVerifier !== undefined ? { codeVerifier: input.codeVerifier } : {}),
+  })
+  const profile = await driver.profile(tokens.accessToken)
+
+  const connectables = await enumerate(driver, tokens.accessToken, input.enumerate ?? 'none')
+
+  return { provider: input.provider, profile, tokens, connectables }
+}
+
+async function enumerate(
+  driver: unknown,
+  accessToken: string,
+  strategy: EnumerationStrategy,
+): Promise<ChannelConnectable[]> {
+  if (strategy === 'none') return []
+
+  if (strategy === 'facebook-pages') {
+    const ops = driver as Partial<FacebookEnumerateOps>
+    if (typeof ops.listPages !== 'function') {
+      throw new HeraldProviderError(
+        `completeChannelConnect: enumerate='facebook-pages' requires a social driver that exposes \`listPages\` (e.g. \`@strav/social/facebook\`).`,
+        { provider: 'herald.onboarding', operation: 'enumerate', status: 500 },
+      )
+    }
+    const pages = await ops.listPages(accessToken)
+    return pages.map((p) => ({ kind: 'facebook-page' as const, ...p }))
+  }
+
+  if (strategy === 'facebook-ig-accounts') {
+    const ops = driver as Partial<FacebookEnumerateOps>
+    if (typeof ops.listInstagramBusinessAccounts !== 'function') {
+      throw new HeraldProviderError(
+        `completeChannelConnect: enumerate='facebook-ig-accounts' requires a social driver that exposes \`listInstagramBusinessAccounts\` (e.g. \`@strav/social/facebook\`).`,
+        { provider: 'herald.onboarding', operation: 'enumerate', status: 500 },
+      )
+    }
+    const accounts = await ops.listInstagramBusinessAccounts(accessToken)
+    return accounts.map((a) => ({ kind: 'facebook-ig-account' as const, ...a }))
+  }
+
+  if (strategy === 'gbp-locations') {
+    const ops = driver as Partial<GoogleEnumerateOps>
+    if (typeof ops.listGbpLocations !== 'function') {
+      throw new HeraldProviderError(
+        `completeChannelConnect: enumerate='gbp-locations' requires a social driver that exposes \`listGbpLocations\` (e.g. \`@strav/social/google\`).`,
+        { provider: 'herald.onboarding', operation: 'enumerate', status: 500 },
+      )
+    }
+    const locations = await ops.listGbpLocations(accessToken)
+    return locations.map((l) => ({ kind: 'gbp-location' as const, ...l }))
+  }
+
+  throw new HeraldProviderError(
+    `completeChannelConnect: unknown enumerate strategy "${strategy}".`,
+    { provider: 'herald.onboarding', operation: 'enumerate', status: 500 },
+  )
+}

package/src/onboarding/connect_channel_callback.ts

@@ -0,0 +1,138 @@
+/**
+ * `connectChannelCallback` — HTTP route handler that wraps
+ * `completeChannelConnect` plus a small amount of state-lookup wiring.
+ *
+ * Mount once per app:
+ *
+ *   router.get('/oauth/connect/:provider/callback', connectChannelCallback({
+ *     social: app.resolve(SocialManager),
+ *     strategies: {
+ *       'fb-page': { provider: 'facebook', enumerate: 'facebook-pages' },
+ *       'ig':      { provider: 'facebook', enumerate: 'facebook-ig-accounts' },
+ *       'gbp':     { provider: 'google',   enumerate: 'gbp-locations' },
+ *     },
+ *     loadCodeVerifier: (state) => sessionStore.get(`pkce:${state}`),
+ *     loadExpectedState: (state) => sessionStore.get(`state:${state}`),
+ *   }))
+ *
+ * Per request flow:
+ *
+ *   1. Resolve `:provider` against the `strategies` map → the social
+ *      provider name + enumeration strategy.
+ *   2. Read `code` + `state` from the query string.
+ *   3. Load the persisted `codeVerifier` + `expectedState` (apps that
+ *      use cookie-based sessions plug their session store in via
+ *      the callbacks).
+ *   4. Hand off to `completeChannelConnect`.
+ *   5. Return JSON: `{ provider, profile, tokens, connectables }`.
+ *
+ * Apps render the connectables (FB Pages / IG accounts / GBP
+ * locations), let the owner pick one, and persist to `social_account`.
+ *
+ * Apps that need a redirect-rendered HTML page instead of JSON wrap
+ * `completeChannelConnect` in their own route. The route handler here
+ * is opinionated: JSON in, JSON out.
+ */
+
+import type { HttpContext } from '@strav/http'
+import type { SocialManager } from '@strav/social'
+import { HeraldConfigError } from '../errors.ts'
+import { completeChannelConnect } from './complete_channel_connect.ts'
+import type { EnumerationStrategy } from './types.ts'
+
+export interface ConnectChannelStrategy {
+  /** Social provider name to exchange against (`'facebook'`, `'google'`). */
+  provider: string
+  /** Which enumeration helper to run after exchange. */
+  enumerate?: EnumerationStrategy
+  /**
+   * Redirect URI registered with the provider. Must match the URI
+   * passed to `authorize()` at flow-start. Omit to let the handler
+   * derive it from the inbound request URL (origin + path, no query).
+   */
+  redirectUri?: string
+}
+
+export interface ConnectChannelCallbackOptions {
+  social: SocialManager
+  /** Maps the `:provider` URL param to a social provider + enumeration strategy. */
+  strategies: Record<string, ConnectChannelStrategy>
+  /** Resolve the PKCE verifier the app stored at authorize-time, keyed by the OAuth state. */
+  loadCodeVerifier?: (
+    state: string,
+  ) => Promise<string | undefined> | string | undefined
+  /** Resolve the expected state value the app stored at authorize-time, keyed by the OAuth state. */
+  loadExpectedState?: (
+    state: string,
+  ) => Promise<string | undefined> | string | undefined
+}
+
+export function connectChannelCallback(
+  options: ConnectChannelCallbackOptions,
+): (ctx: HttpContext) => Promise<Response> {
+  if (!options.strategies || Object.keys(options.strategies).length === 0) {
+    throw new HeraldConfigError(
+      'connectChannelCallback: `strategies` map is empty. Declare at least one URL-param → social-provider mapping.',
+    )
+  }
+
+  return async (ctx: HttpContext): Promise<Response> => {
+    const paramName = ctx.request.params['provider']
+    if (!paramName) {
+      return ctx.response.json(
+        { error: 'Missing :provider route param. Mount as `/oauth/connect/:provider/callback`.' },
+        { status: 400 },
+      )
+    }
+    const strategy = options.strategies[paramName]
+    if (!strategy) {
+      return ctx.response.json(
+        {
+          error: `Unknown provider "${paramName}".`,
+          available: Object.keys(options.strategies),
+        },
+        { status: 404 },
+      )
+    }
+
+    const url = new URL(ctx.request.raw.url)
+    const code = url.searchParams.get('code')
+    const state = url.searchParams.get('state') ?? undefined
+
+    if (!code) {
+      const error = url.searchParams.get('error')
+      const description = url.searchParams.get('error_description')
+      return ctx.response.json(
+        {
+          error: error ?? 'Missing `code` query param.',
+          ...(description ? { error_description: description } : {}),
+        },
+        { status: 400 },
+      )
+    }
+
+    const codeVerifier =
+      state && options.loadCodeVerifier
+        ? (await options.loadCodeVerifier(state)) ?? undefined
+        : undefined
+    const expectedState =
+      state && options.loadExpectedState
+        ? (await options.loadExpectedState(state)) ?? undefined
+        : undefined
+
+    const redirectUri = strategy.redirectUri ?? `${url.origin}${url.pathname}`
+
+    const result = await completeChannelConnect({
+      social: options.social,
+      provider: strategy.provider,
+      code,
+      redirectUri,
+      ...(state !== undefined ? { state } : {}),
+      ...(expectedState !== undefined ? { expectedState } : {}),
+      ...(codeVerifier !== undefined ? { codeVerifier } : {}),
+      ...(strategy.enumerate !== undefined ? { enumerate: strategy.enumerate } : {}),
+    })
+
+    return ctx.response.json(result)
+  }
+}

package/src/onboarding/index.ts

@@ -0,0 +1,26 @@
+// Public API of `@strav/herald/onboarding`.
+//
+// Glue for the "connect a publishing channel" OAuth callback:
+// `completeChannelConnect` runs the social.exchange → profile →
+// enumerate sequence; `connectChannelCallback` wraps it into a
+// mountable HTTP route handler. Apps render the returned
+// `connectables` and persist the owner's pick into their social
+// account ledger.
+
+export {
+  type ChannelConnectResult,
+  type CompleteChannelConnectInput,
+  completeChannelConnect,
+} from './complete_channel_connect.ts'
+export {
+  type ConnectChannelCallbackOptions,
+  type ConnectChannelStrategy,
+  connectChannelCallback,
+} from './connect_channel_callback.ts'
+export type {
+  ChannelConnectable,
+  EnumerationStrategy,
+  FacebookIgAccountConnectable,
+  FacebookPageConnectable,
+  GbpLocationConnectable,
+} from './types.ts'

package/src/onboarding/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Discriminated union of "connectable" rows the onboarding helpers
+ * return — what an authenticated user can be offered as publishing
+ * destinations after an OAuth exchange.
+ *
+ * Each variant carries the IDs + tokens the matching `@strav/herald/*`
+ * driver expects:
+ *
+ *   - `facebook-page.id` + `accessToken` → `PublishTarget.accountId`
+ *     and the credential the FB Meta driver consumes.
+ *   - `facebook-ig-account.id` (IG Business id) + `pageAccessToken`
+ *     (parent Page token) → IG Meta driver.
+ *   - `gbp-location.name` (full `accounts/.../locations/...` resource
+ *     path) → GBP driver. The access token is the OAuth-exchange
+ *     `tokens.accessToken` (Google access tokens are short-lived
+ *     and refreshable; apps store the `refresh_token` and rotate).
+ *
+ * The runtime shape mirrors `FacebookPage` / `FacebookIgBusinessAccount`
+ * / `GbpLocation` from `@strav/social` — re-declared here so apps that
+ * only consume the result don't have to depend on `@strav/social`
+ * types.
+ */
+
+export type ChannelConnectable =
+  | FacebookPageConnectable
+  | FacebookIgAccountConnectable
+  | GbpLocationConnectable
+
+export interface FacebookPageConnectable {
+  kind: 'facebook-page'
+  id: string
+  name: string
+  category?: string
+  accessToken: string
+  tasks?: readonly string[]
+  raw: unknown
+}
+
+export interface FacebookIgAccountConnectable {
+  kind: 'facebook-ig-account'
+  id: string
+  username?: string
+  name?: string
+  profilePictureUrl?: string
+  pageId: string
+  pageAccessToken: string
+  raw: unknown
+}
+
+export interface GbpLocationConnectable {
+  kind: 'gbp-location'
+  /** Full resource path: `accounts/{aid}/locations/{lid}`. */
+  name: string
+  accountName: string
+  title: string
+  address?: string
+  languageCode?: string
+  storeCode?: string
+  raw: unknown
+}
+
+/** Strategy keys for the enumeration step in `completeChannelConnect`. */
+export type EnumerationStrategy =
+  | 'facebook-pages'
+  | 'facebook-ig-accounts'
+  | 'gbp-locations'
+  | 'none'

package/src/tenanted/apply_tenanted_publication_migration.ts

@@ -0,0 +1,46 @@
+/**
+ * `applyTenantedPublicationMigration` — DDL for the opt-in tenanted
+ * variant of the publication ledger.
+ *
+ * Composite unique becomes `(tenant_id, provider, instance_name,
+ * provider_post_id)`. The `source_id` index serves the "all channels
+ * for source" lookup; the `provider/status` index serves operational
+ * queries like "all pending publishes for provider X".
+ */
+
+import {
+  emitCreateTable,
+  type DatabaseExecutor,
+  type SchemaRegistry,
+} from '@strav/database'
+import { tenantedPublicationSchema } from './tenanted_publication_schema.ts'
+
+export interface ApplyTenantedPublicationMigrationOptions {
+  /** Required for `emitCreateTable` to resolve the tenant FK ref. */
+  registry: SchemaRegistry
+}
+
+export async function applyTenantedPublicationMigration(
+  db: DatabaseExecutor,
+  options: ApplyTenantedPublicationMigrationOptions,
+): Promise<void> {
+  const { registry } = options
+
+  await db.execute(emitCreateTable(tenantedPublicationSchema, { registry }).sql)
+
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_publication_tenant_provider_post"
+     ON "${tenantedPublicationSchema.name}" ("tenant_id", "provider", "instance_name", "provider_post_id")
+     WHERE "provider_post_id" IS NOT NULL`,
+  )
+
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_publication_source"
+     ON "${tenantedPublicationSchema.name}" ("source_id")`,
+  )
+
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_publication_provider_status"
+     ON "${tenantedPublicationSchema.name}" ("provider", "status")`,
+  )
+}

package/src/tenanted/index.ts

@@ -0,0 +1,18 @@
+// Public API of `@strav/herald/tenanted` — the opt-in tenant-scoped
+// variant of the publication ledger.
+//
+// Apps that need per-tenant publications import from here. Default
+// single-tenant apps stay on `@strav/herald` and never pay for the
+// extra column / RLS / `withTenant` wrapping.
+
+export {
+  applyTenantedPublicationMigration,
+  type ApplyTenantedPublicationMigrationOptions,
+} from './apply_tenanted_publication_migration.ts'
+export { TenantedPublication } from './tenanted_publication.ts'
+export {
+  type MarkPublishedInput,
+  type RecordInput,
+  TenantedPublicationRepository,
+} from './tenanted_publication_repository.ts'
+export { tenantedPublicationSchema } from './tenanted_publication_schema.ts'

package/src/tenanted/tenanted_publication.ts

@@ -0,0 +1,28 @@
+/**
+ * `TenantedPublication` — typed row of the opt-in tenanted ledger.
+ * Identical fields to `Publication`; its `static schema` points at
+ * the tenanted variant so the Repository runs against the right
+ * DDL + RLS policy.
+ */
+
+import { Model } from '@strav/database'
+import type { PostStatus } from '../dto/post_status.ts'
+import { tenantedPublicationSchema } from './tenanted_publication_schema.ts'
+
+export class TenantedPublication extends Model {
+  static override readonly schema = tenantedPublicationSchema
+
+  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
+}