@strav/herald 1.0.0-alpha.42

package/src/drivers/wordpress/wordpress_driver.ts

@@ -0,0 +1,277 @@
+/**
+ * `WordPressDriver` — `HeraldDriver` implementation for the WordPress
+ * REST API (`/wp-json/wp/v2`).
+ *
+ * Synchronous publish lifecycle: WP returns the created post with
+ * its id + URL in the same request — no async reconciliation needed.
+ * Scheduled posts (`scheduledFor`) come back as status `pending`
+ * until the cron flips them to `published`; apps that care reconcile
+ * by polling `get()`.
+ *
+ * Content mapping (LCD `PublishInput` → WP):
+ *
+ *   - `text` becomes the post `content`. WP requires a `title` but
+ *     accepts empty string — the driver passes `''` so the body is
+ *     the canonical place to read. Apps that want a real title
+ *     supply it via `raw.title` (the raw object is shallow-merged
+ *     over the LCD body).
+ *
+ *   - First `image` attachment becomes `featured_media` (uploaded
+ *     via `/wp/v2/media` first). Additional images are passed
+ *     through in `content` as `<figure>` tags. Apps doing structured
+ *     galleries reach for `raw.content` directly.
+ *
+ *   - `link` attachments are appended to `content` as `<p><a>` tags.
+ *
+ *   - `hashtags` are NOT mapped to WP tags by default (WP tags are
+ *     site-managed taxonomy entities, not free-form hashtags). Apps
+ *     that want this set `raw.tags` to existing tag ids.
+ *
+ *   - `scheduledFor` flips status to `future` + sets `date_gmt`.
+ *
+ * Webhooks: WP doesn't ship engagement webhooks out of the box.
+ * `webhook.verifySignature` and `webhook.parse` throw
+ * `ProviderUnsupportedError`. Apps that wire a webhook plugin
+ * (WP Webhooks, JetPack, …) provide their own `WebhookOps`.
+ */
+
+import type { PostStatus } from '../../dto/post_status.ts'
+import type { PublishAttachment, PublishInput } from '../../dto/publish_input.ts'
+import type { PublishResult } from '../../dto/publish_result.ts'
+import type { PublishTarget } from '../../dto/publish_target.ts'
+import { HeraldProviderError, ProviderUnsupportedError } from '../../errors.ts'
+import type { HeraldCapability } from '../../herald_capabilities.ts'
+import type { HeraldDriver, WebhookOps } from '../../herald_driver.ts'
+import type { HeraldWebhookEvent } from '../../webhook/herald_event.ts'
+import type {
+  WordPressCredentials,
+  WordPressCredentialsResolver,
+  WordPressProviderConfig,
+} from './wordpress_config.ts'
+import { type WPPostBody, WordPressClient, type WPPost } from './wordpress_client.ts'
+
+export interface WordPressDriverOptions {
+  instanceName: string
+  sites?: Record<string, WordPressCredentials>
+  credentialsFor?: WordPressCredentialsResolver
+  fetch?: typeof fetch
+}
+
+const CAPABILITIES: ReadonlySet<HeraldCapability> = new Set<HeraldCapability>([
+  'post.create',
+  'post.update',
+  'post.delete',
+  'post.get',
+  'post.schedule',
+  'media.image',
+  'media.link',
+])
+
+const UNSUPPORTED_WEBHOOK: WebhookOps = {
+  verifySignature(): boolean {
+    throw new ProviderUnsupportedError('wordpress', 'webhook.verifySignature', {
+      reason: 'WordPress core does not ship engagement webhooks.',
+    })
+  },
+  parse(): HeraldWebhookEvent[] {
+    throw new ProviderUnsupportedError('wordpress', 'webhook.parse', {
+      reason: 'WordPress core does not ship engagement webhooks.',
+    })
+  },
+}
+
+export class WordPressDriver implements HeraldDriver {
+  readonly name = 'wordpress'
+  readonly instanceName: string
+  readonly capabilities = CAPABILITIES
+  readonly webhook: WebhookOps = UNSUPPORTED_WEBHOOK
+
+  private readonly sites: Record<string, WordPressCredentials>
+  private readonly resolver: WordPressCredentialsResolver | undefined
+  private readonly fetcher: typeof fetch
+
+  constructor(options: WordPressDriverOptions) {
+    this.instanceName = options.instanceName
+    this.sites = options.sites ?? {}
+    this.resolver = options.credentialsFor
+    this.fetcher = options.fetch ?? fetch
+  }
+
+  static fromConfig(
+    instanceName: string,
+    config: WordPressProviderConfig,
+  ): WordPressDriver {
+    return new WordPressDriver({
+      instanceName,
+      ...(config.sites ? { sites: config.sites } : {}),
+      ...(config.credentialsFor ? { credentialsFor: config.credentialsFor } : {}),
+      ...(config.fetch ? { fetch: config.fetch } : {}),
+    })
+  }
+
+  async publish(target: PublishTarget, input: PublishInput): Promise<PublishResult> {
+    const client = await this.clientFor(target.accountId)
+    const body = await this.buildBody(client, input)
+    const created = await client.createPost(body)
+    return this.toResult(created)
+  }
+
+  async update(
+    target: PublishTarget,
+    providerPostId: string,
+    input: PublishInput,
+  ): Promise<PublishResult> {
+    const client = await this.clientFor(target.accountId)
+    const body = await this.buildBody(client, input)
+    const updated = await client.updatePost(toInt(providerPostId), body)
+    return this.toResult(updated)
+  }
+
+  async delete(target: PublishTarget, providerPostId: string): Promise<void> {
+    const client = await this.clientFor(target.accountId)
+    await client.deletePost(toInt(providerPostId), { force: true })
+  }
+
+  async get(target: PublishTarget, providerPostId: string): Promise<PostStatus> {
+    const client = await this.clientFor(target.accountId)
+    const post = await client.getPost(toInt(providerPostId))
+    return mapStatus(post.status)
+  }
+
+  // ─── internals ───────────────────────────────────────────────────────
+
+  private async clientFor(accountId: string): Promise<WordPressClient> {
+    const creds = await this.credentialsFor(accountId)
+    if (!creds) {
+      throw new HeraldProviderError(
+        `WordPress driver: no credentials registered for account "${accountId}". Add it to \`config.herald.providers.${this.instanceName}.sites\` or return it from \`credentialsFor\`.`,
+        { provider: 'wordpress', operation: 'clientFor', status: 500 },
+      )
+    }
+    return new WordPressClient(creds, this.fetcher)
+  }
+
+  private async credentialsFor(accountId: string): Promise<WordPressCredentials | null> {
+    if (this.resolver) {
+      const resolved = await this.resolver(accountId)
+      if (resolved) return resolved
+    }
+    return this.sites[accountId] ?? null
+  }
+
+  private async buildBody(
+    client: WordPressClient,
+    input: PublishInput,
+  ): Promise<WPPostBody> {
+    const raw = (input.raw as Partial<WPPostBody> | undefined) ?? {}
+
+    const content = raw.content ?? renderContent(input)
+    const status: WPPostBody['status'] =
+      raw.status ?? (input.scheduledFor ? 'future' : 'publish')
+
+    const body: WPPostBody = {
+      title: raw.title ?? '',
+      content,
+      status,
+      ...(input.scheduledFor && !raw.date_gmt
+        ? { date_gmt: toGmtString(input.scheduledFor) }
+        : {}),
+      ...raw,
+    }
+
+    // featured image — first image attachment unless raw.featured_media is set
+    if (body.featured_media === undefined) {
+      const firstImage = (input.attachments ?? []).find((a) => a.type === 'image')
+      if (firstImage) {
+        const media = await client.uploadMediaFromUrl(firstImage.url, {
+          ...(firstImage.altText ? { altText: firstImage.altText } : {}),
+        })
+        body.featured_media = media.id
+      }
+    }
+
+    return body
+  }
+
+  private toResult(post: WPPost): PublishResult {
+    return {
+      provider: 'wordpress',
+      providerPostId: String(post.id),
+      url: post.link,
+      status: mapStatus(post.status),
+      raw: post,
+    }
+  }
+}
+
+function renderContent(input: PublishInput): string {
+  const parts: string[] = []
+  if (input.text) {
+    for (const para of input.text.split(/\n{2,}/)) {
+      parts.push(`<p>${escapeHtml(para.trim())}</p>`)
+    }
+  }
+  for (const attachment of input.attachments ?? []) {
+    parts.push(renderAttachment(attachment))
+  }
+  if (input.hashtags && input.hashtags.length > 0) {
+    parts.push(
+      `<p>${input.hashtags.map((h) => `#${escapeHtml(h)}`).join(' ')}</p>`,
+    )
+  }
+  return parts.join('\n')
+}
+
+function renderAttachment(attachment: PublishAttachment): string {
+  switch (attachment.type) {
+    case 'image':
+      return `<figure><img src="${escapeAttr(attachment.url)}" alt="${escapeAttr(
+        attachment.altText ?? '',
+      )}" /></figure>`
+    case 'video':
+      return `<video controls src="${escapeAttr(attachment.url)}"></video>`
+    case 'link':
+      return `<p><a href="${escapeAttr(attachment.url)}">${escapeHtml(
+        attachment.title ?? attachment.url,
+      )}</a></p>`
+  }
+}
+
+function mapStatus(wpStatus: WPPostBody['status']): PostStatus {
+  switch (wpStatus) {
+    case 'publish':
+      return 'published'
+    case 'future':
+    case 'draft':
+    case 'pending':
+    case 'private':
+      return 'pending'
+  }
+}
+
+function toGmtString(date: Date): string {
+  // WP expects ISO without timezone, interpreted as UTC.
+  return date.toISOString().replace(/\.\d+Z$/, '')
+}
+
+function toInt(id: string): number {
+  const n = Number.parseInt(id, 10)
+  if (!Number.isFinite(n)) {
+    throw new HeraldProviderError(
+      `WordPress driver: providerPostId "${id}" is not a valid integer.`,
+      { provider: 'wordpress', operation: 'toInt', status: 400 },
+    )
+  }
+  return n
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function escapeAttr(s: string): string {
+  return escapeHtml(s).replace(/"/g, '&quot;')
+}

package/src/drivers/wordpress/wordpress_provider.ts

@@ -0,0 +1,37 @@
+/**
+ * `WordPressHeraldProvider` — `ServiceProvider` that registers the
+ * WordPress driver factory on the `HeraldManager`.
+ *
+ * Apps list this AFTER `HeraldProvider` in `bootstrap/providers.ts`.
+ * Driver instances construct lazily on first `herald.use(name)` call.
+ *
+ * The driver self-validates at first use: a missing `sites` map AND
+ * missing `credentialsFor` resolver throws at the first `publish()`
+ * call. Apps can pre-validate by force-resolving a provider during
+ * boot.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { HeraldConfigError } from '../../errors.ts'
+import { HeraldManager } from '../../herald_manager.ts'
+import type { WordPressProviderConfig } from './wordpress_config.ts'
+import { WordPressDriver } from './wordpress_driver.ts'
+
+export class WordPressHeraldProvider extends ServiceProvider {
+  override readonly name = 'herald-wordpress'
+  override readonly dependencies = ['herald']
+
+  override register(app: Application): void {
+    const manager = app.resolve(HeraldManager)
+    manager.extend('wordpress', ({ instanceName, config }) => {
+      const cfg = config as WordPressProviderConfig
+      if (!cfg.sites && !cfg.credentialsFor) {
+        throw new HeraldConfigError(
+          `WordPressHeraldProvider: provider "${instanceName}" needs either an inline \`sites\` map or a \`credentialsFor\` resolver.`,
+          { context: { instanceName } },
+        )
+      }
+      return WordPressDriver.fromConfig(instanceName, cfg)
+    })
+  }
+}

package/src/drivers/wordpress/wordpress_validate.ts

@@ -0,0 +1,122 @@
+/**
+ * `validateWordPressCredentials` — confirm a `(siteUrl, username,
+ * applicationPassword)` triple authenticates against the WP REST API.
+ *
+ * Unlike the OAuth-flow providers (Meta, GBP) WordPress connections
+ * are typically set up by an owner pasting an Application Password
+ * into a form. This helper is the "validate on submit" step apps run
+ * before persisting credentials into `social_account`. Hits
+ * `GET /wp-json/wp/v2/users/me?context=edit` — `context=edit`
+ * forces WP to check capabilities, so a stolen-token-with-no-permissions
+ * doesn't slip through.
+ *
+ * Returns the public identity bits the connect UI usually echoes back
+ * ("Connected as Liva on example.com").
+ *
+ * Throws `HeraldProviderError` (status 401) when WP rejects the
+ * credentials, and (status 502) when the request fails for any other
+ * reason. Apps wrap the call in a try/catch to render a friendly
+ * "couldn't connect — check your password" message on the form.
+ */
+
+import { HeraldProviderError } from '../../errors.ts'
+import type { WordPressCredentials } from './wordpress_config.ts'
+
+export interface WordPressConnectionInfo {
+  siteUrl: string
+  userId: number
+  username: string
+  displayName?: string
+  email?: string
+  /** WP capabilities the credential grants (`publish_posts`, `edit_others_posts`, …). */
+  capabilities: Record<string, boolean>
+  raw: unknown
+}
+
+interface WPUserMeResponse {
+  id?: number
+  username?: string
+  slug?: string
+  name?: string
+  email?: string
+  capabilities?: Record<string, boolean>
+}
+
+export async function validateWordPressCredentials(
+  creds: WordPressCredentials,
+  options: { fetch?: typeof fetch } = {},
+): Promise<WordPressConnectionInfo> {
+  const fetcher = options.fetch ?? fetch
+  const siteUrl = creds.siteUrl.replace(/\/+$/, '')
+  const url = `${siteUrl}/wp-json/wp/v2/users/me?context=edit`
+  const auth = `Basic ${Buffer.from(`${creds.username}:${creds.applicationPassword}`, 'utf-8').toString('base64')}`
+
+  let res: Response
+  try {
+    res = await fetcher(url, {
+      method: 'GET',
+      headers: { Authorization: auth, Accept: 'application/json' },
+    })
+  } catch (cause) {
+    throw new HeraldProviderError(
+      `validateWordPressCredentials: network failure reaching ${siteUrl}.`,
+      { provider: 'wordpress', operation: 'validateCredentials', status: 502, cause },
+    )
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    const body = await safeText(res)
+    throw new HeraldProviderError(
+      `validateWordPressCredentials: WordPress rejected the credentials (HTTP ${res.status}). Confirm the username matches the Application Password owner and that the user has at least Editor role.`,
+      {
+        provider: 'wordpress',
+        operation: 'validateCredentials',
+        status: 401,
+        context: { responseBody: body },
+      },
+    )
+  }
+  if (!res.ok) {
+    const body = await safeText(res)
+    throw new HeraldProviderError(
+      `validateWordPressCredentials: WordPress responded HTTP ${res.status}.`,
+      {
+        provider: 'wordpress',
+        operation: 'validateCredentials',
+        status: 502,
+        context: { responseBody: body },
+      },
+    )
+  }
+
+  const body = (await res.json()) as WPUserMeResponse
+  if (typeof body.id !== 'number') {
+    throw new HeraldProviderError(
+      `validateWordPressCredentials: /users/me response missing \`id\`.`,
+      {
+        provider: 'wordpress',
+        operation: 'validateCredentials',
+        status: 502,
+        context: { responseBody: body },
+      },
+    )
+  }
+
+  return {
+    siteUrl,
+    userId: body.id,
+    username: body.username ?? body.slug ?? String(body.id),
+    ...(body.name ? { displayName: body.name } : {}),
+    ...(body.email ? { email: body.email } : {}),
+    capabilities: body.capabilities ?? {},
+    raw: body,
+  }
+}
+
+async function safeText(res: Response): Promise<string> {
+  try {
+    return await res.text()
+  } catch {
+    return ''
+  }
+}

package/src/dto/post_status.ts

@@ -0,0 +1,14 @@
+/**
+ * `PostStatus` — normalized lifecycle state of a published post.
+ *
+ *   - `pending`    — accepted by the platform but not yet visible
+ *                    (moderation, scheduled future delivery).
+ *   - `published`  — live and visible on the platform.
+ *   - `failed`     — platform rejected the post (policy violation,
+ *                    media transcoding failure, …). See driver
+ *                    `raw` for the platform-specific reason.
+ *   - `deleted`    — removed from the platform (by us or by the
+ *                    platform).
+ */
+
+export type PostStatus = 'pending' | 'published' | 'failed' | 'deleted'

package/src/dto/publish_input.ts

@@ -0,0 +1,38 @@
+/**
+ * `PublishInput` — the lowest-common-denominator wire shape for a post
+ * the `HeraldManager` accepts. Apps targeting multiple platforms stick
+ * to these fields; apps needing platform-specific richness (a GBP Call
+ * To Action button, an IG carousel ordering) drop down to `raw` or
+ * call into the subpath driver directly.
+ *
+ * Every field is optional so the same shape can carry "just text",
+ * "text + image", "link preview only", etc. Drivers throw
+ * `ProviderUnsupportedError` for fields they can't fulfil — apps
+ * gate on `driver.capabilities` to branch ahead of the call.
+ */
+
+export interface PublishInput {
+  /** Plain-text body of the post. */
+  text?: string
+  /** Media + link attached to the post. */
+  attachments?: PublishAttachment[]
+  /** Hashtags, where the platform recognises them as first-class. */
+  hashtags?: string[]
+  /**
+   * Schedule the post for future delivery. Honoured only when the
+   * driver declares `post.schedule`; otherwise the call throws
+   * `ProviderUnsupportedError`.
+   */
+  scheduledFor?: Date
+  /**
+   * Provider-native post object. When set, the driver forwards it
+   * verbatim and ignores the LCD fields above. Use this when reaching
+   * for provider-specific richness (e.g. a GBP CTA, a WP excerpt).
+   */
+  raw?: unknown
+}
+
+export type PublishAttachment =
+  | { type: 'image'; url: string; altText?: string }
+  | { type: 'video'; url: string; thumbnailUrl?: string; durationMs?: number }
+  | { type: 'link'; url: string; title?: string; description?: string }

package/src/dto/publish_result.ts

@@ -0,0 +1,23 @@
+/**
+ * `PublishResult` — what every publish call returns. Drivers populate
+ * `providerPostId` and `url` when the platform hands them back at
+ * create time. Asynchronous-publish platforms (GBP Posts that need a
+ * moderation pass, scheduled posts) return `status: 'pending'` and
+ * leave `url` undefined until the platform confirms via webhook —
+ * apps reconcile by listening for `post.published` on the registry.
+ */
+
+import type { PostStatus } from './post_status.ts'
+
+export interface PublishResult {
+  /** Driver name (`'gbp'`, `'meta'`, `'wordpress'`, …). */
+  provider: string
+  /** Provider-issued post id. Required once the platform has accepted the post. */
+  providerPostId: string
+  /** Public URL of the post, when the platform exposes one. */
+  url?: string
+  /** Current platform-side status. */
+  status: PostStatus
+  /** Raw provider response for advanced inspection. */
+  raw?: unknown
+}

package/src/dto/publish_target.ts

@@ -0,0 +1,15 @@
+/**
+ * `PublishTarget` — addresses a single configured publishing endpoint.
+ *
+ * `provider` selects the manager instance (key in `config.herald.providers`).
+ * `accountId` identifies the connected social account whose OAuth
+ * tokens the driver should use — typically the `provider_user_id` on
+ * a `@strav/social` `SocialAccount` row (e.g. a Facebook Page id, a
+ * GBP location id, a WordPress site host). Drivers resolve the actual
+ * access/refresh tokens via the social ledger at call time.
+ */
+
+export interface PublishTarget {
+  provider: string
+  accountId: string
+}

package/src/errors.ts

@@ -0,0 +1,122 @@
+/**
+ * `HeraldError` hierarchy — typed wrappers for failures across the
+ * publishing stack. Vendor-native errors (Graph API rejections, WP REST
+ * 4xx responses) are preserved on `.cause` so apps can still
+ * `instanceof` the underlying type for retry / recovery logic; the
+ * wrapping just gives the framework a consistent `StravError` for the
+ * standard exception handler.
+ *
+ * Subclasses:
+ *
+ *   - `HeraldConfigError` — `config.herald` missing required fields.
+ *     Thrown at boot from `HeraldProvider`.
+ *
+ *   - `ProviderUnsupportedError` — driver doesn't implement the
+ *     requested operation (e.g. `gbp.update(...)` — GBP Posts are
+ *     immutable). Thrown synchronously so apps fail fast.
+ *
+ *   - `UnknownProviderError` — `herald.use('x')` for a name not
+ *     configured.
+ *
+ *   - `WebhookSignatureError` — signature header missing or doesn't
+ *     verify. Webhook route returns 400; providers retry.
+ *
+ *   - `HeraldProviderError` — generic wrapper around a vendor
+ *     exception that doesn't map to a more specific subclass.
+ *     Preserves `.cause`; default status 502.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class HeraldError extends StravError {
+  constructor(
+    message: string,
+    options: {
+      code?: string
+      status?: number
+      context?: Record<string, unknown>
+      cause?: unknown
+    } = {},
+  ) {
+    super(
+      message,
+      { code: options.code ?? 'herald.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+export class HeraldConfigError extends HeraldError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'herald.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+export class UnknownProviderError extends HeraldError {
+  constructor(name: string, available: readonly string[]) {
+    super(
+      `Herald provider "${name}" is not configured. Available: ${available.join(', ') || '<none>'}.`,
+      {
+        code: 'herald.unknown_provider',
+        status: 400,
+        context: { requested: name, available },
+      },
+    )
+  }
+}
+
+export class ProviderUnsupportedError extends HeraldError {
+  constructor(provider: string, operation: string, options: { reason?: string } = {}) {
+    const trailer = options.reason ? ` ${options.reason}` : ''
+    super(`Herald provider "${provider}" does not support "${operation}".${trailer}`, {
+      code: 'herald.provider_unsupported',
+      status: 400,
+      context: { provider, operation, ...(options.reason ? { reason: options.reason } : {}) },
+    })
+  }
+}
+
+export class WebhookSignatureError extends HeraldError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'herald.webhook_signature',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+export class HeraldProviderError extends HeraldError {
+  constructor(
+    message: string,
+    options: {
+      provider: string
+      operation: string
+      context?: Record<string, unknown>
+      cause?: unknown
+      status?: number
+    },
+  ) {
+    super(message, {
+      code: 'herald.provider_error',
+      status: options.status ?? 502,
+      context: {
+        provider: options.provider,
+        operation: options.operation,
+        ...(options.context ?? {}),
+      },
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}

package/src/herald_capabilities.ts

@@ -0,0 +1,37 @@
+/**
+ * `HeraldCapability` — granular feature flags every driver declares
+ * in `driver.capabilities`. Apps that build provider-neutral flows
+ * branch on capability before calling:
+ *
+ *   if (herald.use('meta').capabilities.has('post.schedule')) { ... }
+ *
+ * Granularity is intentionally fine — one flag per non-trivial surface
+ * — so e.g. GBP can claim `post.create` + `post.delete` but omit
+ * `post.update` (Posts are immutable), and Instagram can claim
+ * `media.video` without `media.carousel`.
+ *
+ * Drivers omit a capability when they can't fulfil it faithfully. Apps
+ * reach into provider-specific subpath imports (`@strav/herald/meta`)
+ * when they need behaviour that doesn't map to a common capability.
+ */
+
+export type HeraldCapability =
+  // outbound post lifecycle
+  | 'post.create'
+  | 'post.update'
+  | 'post.delete'
+  | 'post.get'
+  | 'post.schedule'
+  // content shapes
+  | 'media.image'
+  | 'media.video'
+  | 'media.carousel'
+  | 'media.link'
+  | 'text.hashtags'
+  | 'text.mentions'
+  // inbound webhook surfaces
+  | 'webhook.signature'
+  | 'webhook.parse'
+  | 'webhook.engagement.comment'
+  | 'webhook.engagement.review'
+  | 'webhook.engagement.reaction'