@strav/herald 1.0.0-alpha.42

package/src/drivers/meta/meta_webhook_ops.ts

@@ -0,0 +1,227 @@
+/**
+ * `MetaWebhookOps` — Graph API webhook verification + parsing.
+ *
+ * **Signature**: Meta signs the raw body with HMAC-SHA256 keyed by
+ * the app secret and sends the hex digest in `x-hub-signature-256`
+ * as `sha256={hex}`. (The legacy `x-hub-signature` is SHA-1; the
+ * herald route handler probes the 256 header first.) Drivers
+ * compare in constant time to defeat timing oracles.
+ *
+ * **Payload shape** (the bits we care about):
+ *
+ *   {
+ *     "object": "page" | "instagram",
+ *     "entry": [{
+ *       "id": "<page-or-ig-id>",
+ *       "time": <unix>,
+ *       "changes": [{
+ *         "field": "feed" | "comments" | "mention" | "ratings" | ...,
+ *         "value": { ... }
+ *       }]
+ *     }]
+ *   }
+ *
+ * V1 normalization:
+ *
+ *   - **Page feed comment** (`object='page'`, `field='feed'`,
+ *     `value.item='comment'`, `value.verb='add'`)
+ *     → `engagement.comment`
+ *
+ *   - **Page rating/review** (`field='ratings'`) → `engagement.review`
+ *
+ *   - **IG comment** (`object='instagram'`, `field='comments'`)
+ *     → `engagement.comment`
+ *
+ *   - Everything else → `unknown` (the dedup row still records
+ *     receipt; ops can spot novel events).
+ *
+ * `event.id` is derived deterministically from the payload — Meta
+ * doesn't always include a stable event id, so we hash the salient
+ * fields (page id + change index + value.comment_id when present)
+ * to keep dedup idempotent under provider retries.
+ */
+
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
+import { WebhookSignatureError } from '../../errors.ts'
+import type { WebhookOps } from '../../herald_driver.ts'
+import type {
+  CommentEvent,
+  HeraldWebhookEvent,
+  ReviewEvent,
+  UnknownEvent,
+} from '../../webhook/herald_event.ts'
+
+export interface MetaWebhookOpsOptions {
+  /** Meta app secret — the HMAC key. Must match the secret configured for the Meta app. */
+  appSecret: string
+  /** Driver name to stamp onto every normalized event (`'meta'`). */
+  driverName: string
+}
+
+interface MetaPayload {
+  object?: string
+  entry?: Array<{
+    id?: string
+    time?: number
+    changes?: Array<{
+      field?: string
+      value?: Record<string, unknown>
+    }>
+  }>
+}
+
+export class MetaWebhookOps implements WebhookOps {
+  private readonly appSecret: string
+  private readonly driverName: string
+
+  constructor(options: MetaWebhookOpsOptions) {
+    this.appSecret = options.appSecret
+    this.driverName = options.driverName
+  }
+
+  verifySignature(rawBody: string, signature: string | null | undefined): boolean {
+    if (!signature) {
+      throw new WebhookSignatureError('Meta webhook: missing x-hub-signature-256 header.')
+    }
+    const prefix = 'sha256='
+    if (!signature.startsWith(prefix)) {
+      throw new WebhookSignatureError(
+        `Meta webhook: signature header must start with "${prefix}", got "${signature.slice(0, 16)}…".`,
+      )
+    }
+    const provided = signature.slice(prefix.length)
+    const expected = createHmac('sha256', this.appSecret).update(rawBody).digest('hex')
+    if (provided.length !== expected.length) return false
+    return timingSafeEqual(Buffer.from(provided, 'hex'), Buffer.from(expected, 'hex'))
+  }
+
+  parse(rawBody: string): HeraldWebhookEvent[] {
+    let payload: MetaPayload
+    try {
+      payload = JSON.parse(rawBody) as MetaPayload
+    } catch (cause) {
+      throw new WebhookSignatureError('Meta webhook: payload is not valid JSON.', {
+        cause,
+      })
+    }
+
+    const object = payload.object
+    const events: HeraldWebhookEvent[] = []
+
+    for (const [entryIdx, entry] of (payload.entry ?? []).entries()) {
+      const accountId = entry.id ?? ''
+      const occurredAt = entry.time ? new Date(entry.time * 1000) : undefined
+      const changes = entry.changes ?? []
+      for (const [changeIdx, change] of changes.entries()) {
+        const event = this.normalize({
+          object,
+          entryIdx,
+          changeIdx,
+          accountId,
+          occurredAt,
+          field: change.field,
+          value: change.value ?? {},
+        })
+        events.push(event)
+      }
+    }
+
+    return events
+  }
+
+  private normalize(input: {
+    object: string | undefined
+    entryIdx: number
+    changeIdx: number
+    accountId: string
+    occurredAt: Date | undefined
+    field: string | undefined
+    value: Record<string, unknown>
+  }): HeraldWebhookEvent {
+    const { object, accountId, occurredAt, field, value } = input
+    const id = this.eventId(input)
+
+    const base = {
+      id,
+      provider: this.driverName,
+      accountId,
+      ...(occurredAt ? { occurredAt } : {}),
+      raw: { object, field, value },
+    } as const
+
+    // Facebook Page feed comment
+    if (object === 'page' && field === 'feed' && value['item'] === 'comment') {
+      const commentId = str(value['comment_id']) ?? str(value['id']) ?? id
+      const postId = str(value['post_id'])
+      const event: CommentEvent = {
+        ...base,
+        type: 'engagement.comment',
+        commentId,
+        ...(postId ? { providerPostId: postId } : { providerPostId: accountId }),
+        ...(str(value['from_id']) ? { authorId: str(value['from_id'])! } : {}),
+        ...(str(value['from_name']) ? { authorName: str(value['from_name'])! } : {}),
+        ...(str(value['message']) ? { text: str(value['message'])! } : {}),
+        ...(str(value['parent_id']) ? { parentCommentId: str(value['parent_id'])! } : {}),
+      }
+      return event
+    }
+
+    // Facebook Page rating / review
+    if (object === 'page' && field === 'ratings') {
+      const reviewId = str(value['review_id']) ?? str(value['comment_id']) ?? id
+      const event: ReviewEvent = {
+        ...base,
+        type: 'engagement.review',
+        reviewId,
+        ...(typeof value['rating'] === 'number' ? { rating: value['rating'] as number } : {}),
+        ...(str(value['review_text']) ? { text: str(value['review_text'])! } : {}),
+        ...(str(value['reviewer_name']) ? { authorName: str(value['reviewer_name'])! } : {}),
+      }
+      return event
+    }
+
+    // Instagram comments
+    if (object === 'instagram' && field === 'comments') {
+      const commentId = str(value['id']) ?? id
+      const mediaId = str((value['media'] as Record<string, unknown> | undefined)?.['id'])
+      const event: CommentEvent = {
+        ...base,
+        type: 'engagement.comment',
+        commentId,
+        ...(mediaId ? { providerPostId: mediaId } : { providerPostId: accountId }),
+        ...(str((value['from'] as Record<string, unknown> | undefined)?.['id'])
+          ? { authorId: str((value['from'] as Record<string, unknown>)['id'])! }
+          : {}),
+        ...(str((value['from'] as Record<string, unknown> | undefined)?.['username'])
+          ? { authorName: str((value['from'] as Record<string, unknown>)['username'])! }
+          : {}),
+        ...(str(value['text']) ? { text: str(value['text'])! } : {}),
+      }
+      return event
+    }
+
+    const unknown: UnknownEvent = { ...base, type: 'unknown' }
+    return unknown
+  }
+
+  private eventId(input: {
+    object: string | undefined
+    entryIdx: number
+    changeIdx: number
+    accountId: string
+    field: string | undefined
+    value: Record<string, unknown>
+  }): string {
+    const salient =
+      str(input.value['comment_id']) ??
+      str(input.value['id']) ??
+      str(input.value['review_id']) ??
+      `${input.entryIdx}:${input.changeIdx}`
+    const seed = `${input.object ?? ''}|${input.accountId}|${input.field ?? ''}|${salient}`
+    return createHash('sha256').update(seed).digest('hex').slice(0, 32)
+  }
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined
+}

package/src/drivers/wordpress/index.ts

@@ -0,0 +1,24 @@
+// Public API of `@strav/herald/wordpress`.
+//
+// WordPress REST driver — auth via Application Password (built into
+// WP core since 5.6, no plugin needed). Supports publish, update,
+// delete, get, schedule, and image/link attachments. Engagement
+// webhooks unsupported (WP doesn't ship them).
+
+export type {
+  WordPressCredentials,
+  WordPressCredentialsResolver,
+  WordPressProviderConfig,
+} from './wordpress_config.ts'
+export {
+  WordPressClient,
+  type WPMedia,
+  type WPPost,
+  type WPPostBody,
+} from './wordpress_client.ts'
+export { WordPressDriver, type WordPressDriverOptions } from './wordpress_driver.ts'
+export { WordPressHeraldProvider } from './wordpress_provider.ts'
+export {
+  validateWordPressCredentials,
+  type WordPressConnectionInfo,
+} from './wordpress_validate.ts'

package/src/drivers/wordpress/wordpress_client.ts

@@ -0,0 +1,185 @@
+/**
+ * `WordPressClient` — thin wrapper over the WordPress REST API
+ * (`/wp-json/wp/v2`). Only the surfaces the driver uses are
+ * implemented; everything else apps reach for via the `raw`
+ * passthrough on `PublishInput.raw`.
+ *
+ * Auth is HTTP Basic with `(username, applicationPassword)`. The
+ * client constructs the header once at construction time.
+ */
+
+import { HeraldProviderError } from '../../errors.ts'
+import type { WordPressCredentials } from './wordpress_config.ts'
+
+export interface WPPostBody {
+  title?: string
+  content: string
+  status: 'publish' | 'future' | 'draft' | 'pending' | 'private'
+  date_gmt?: string
+  featured_media?: number
+  [key: string]: unknown
+}
+
+export interface WPPost {
+  id: number
+  link: string
+  status: WPPostBody['status']
+  date_gmt: string
+  [key: string]: unknown
+}
+
+export interface WPMedia {
+  id: number
+  source_url: string
+  [key: string]: unknown
+}
+
+export class WordPressClient {
+  private readonly fetcher: typeof fetch
+  private readonly authHeader: string
+  private readonly baseUrl: string
+
+  constructor(creds: WordPressCredentials, fetcher: typeof fetch = fetch) {
+    this.baseUrl = creds.siteUrl.replace(/\/+$/, '')
+    this.fetcher = fetcher
+    const raw = `${creds.username}:${creds.applicationPassword}`
+    this.authHeader = `Basic ${Buffer.from(raw, 'utf-8').toString('base64')}`
+  }
+
+  private url(path: string): string {
+    return `${this.baseUrl}/wp-json/wp/v2${path}`
+  }
+
+  async createPost(body: WPPostBody): Promise<WPPost> {
+    return this.json<WPPost>('POST', '/posts', body)
+  }
+
+  async updatePost(id: number, body: Partial<WPPostBody>): Promise<WPPost> {
+    return this.json<WPPost>('POST', `/posts/${id}`, body)
+  }
+
+  async deletePost(id: number, options: { force?: boolean } = {}): Promise<void> {
+    const force = options.force ? '?force=true' : ''
+    await this.bare('DELETE', `/posts/${id}${force}`)
+  }
+
+  async getPost(id: number): Promise<WPPost> {
+    return this.json<WPPost>('GET', `/posts/${id}`, undefined)
+  }
+
+  /**
+   * Fetch a remote image and upload it as a WP media attachment.
+   * Returns the created media row. Apps that already host media on
+   * WP pass the existing id via `raw.featured_media` instead.
+   */
+  async uploadMediaFromUrl(
+    url: string,
+    options: { filename?: string; altText?: string } = {},
+  ): Promise<WPMedia> {
+    const sourceRes = await this.fetcher(url)
+    if (!sourceRes.ok) {
+      throw new HeraldProviderError(
+        `WordPress driver: failed to download media from ${url} (${sourceRes.status}).`,
+        { provider: 'wordpress', operation: 'uploadMediaFromUrl', status: 502 },
+      )
+    }
+    const bytes = await sourceRes.arrayBuffer()
+    const contentType = sourceRes.headers.get('content-type') ?? 'application/octet-stream'
+    const filename =
+      options.filename ?? url.split('/').pop()?.split('?')[0] ?? 'upload.bin'
+
+    const res = await this.fetcher(this.url('/media'), {
+      method: 'POST',
+      headers: {
+        Authorization: this.authHeader,
+        'Content-Type': contentType,
+        'Content-Disposition': `attachment; filename="${filename}"`,
+      },
+      body: bytes,
+    })
+    if (!res.ok) {
+      const text = await safeText(res)
+      throw new HeraldProviderError(
+        `WordPress driver: media upload failed (${res.status}).`,
+        {
+          provider: 'wordpress',
+          operation: 'uploadMediaFromUrl',
+          status: 502,
+          context: { responseBody: text },
+        },
+      )
+    }
+    const media = (await res.json()) as WPMedia
+
+    if (options.altText) {
+      // alt_text is settable via PATCH on the media endpoint; failure
+      // here is non-fatal — return the media anyway.
+      await this.fetcher(this.url(`/media/${media.id}`), {
+        method: 'POST',
+        headers: {
+          Authorization: this.authHeader,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ alt_text: options.altText }),
+      }).catch(() => {})
+    }
+
+    return media
+  }
+
+  private async json<T>(
+    method: 'GET' | 'POST' | 'DELETE',
+    path: string,
+    body: unknown,
+  ): Promise<T> {
+    const res = await this.fetcher(this.url(path), {
+      method,
+      headers: {
+        Authorization: this.authHeader,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    })
+    if (!res.ok) {
+      const text = await safeText(res)
+      throw new HeraldProviderError(
+        `WordPress driver: ${method} ${path} failed (${res.status}).`,
+        {
+          provider: 'wordpress',
+          operation: `${method} ${path}`,
+          status: 502,
+          context: { responseBody: text },
+        },
+      )
+    }
+    return (await res.json()) as T
+  }
+
+  private async bare(method: 'DELETE', path: string): Promise<void> {
+    const res = await this.fetcher(this.url(path), {
+      method,
+      headers: { Authorization: this.authHeader },
+    })
+    if (!res.ok) {
+      const text = await safeText(res)
+      throw new HeraldProviderError(
+        `WordPress driver: ${method} ${path} failed (${res.status}).`,
+        {
+          provider: 'wordpress',
+          operation: `${method} ${path}`,
+          status: 502,
+          context: { responseBody: text },
+        },
+      )
+    }
+  }
+}
+
+async function safeText(res: Response): Promise<string> {
+  try {
+    return await res.text()
+  } catch {
+    return ''
+  }
+}

package/src/drivers/wordpress/wordpress_config.ts

@@ -0,0 +1,51 @@
+/**
+ * `WordPressProviderConfig` — `config.herald.providers['wordpress']`
+ * shape for the WordPress REST driver.
+ *
+ * WordPress sites authenticate per-call via HTTP Basic with a
+ * **WordPress Application Password** — built into WP core since 5.6,
+ * no OAuth plugin required. Each connected site supplies (siteUrl,
+ * username, applicationPassword).
+ *
+ * The driver supports two credential-sourcing strategies:
+ *
+ *   - **Inline `sites` map** — for apps that publish to a small
+ *     fixed set of sites known at boot. Keyed by `accountId` (the
+ *     value `PublishTarget.accountId` resolves to — typically the
+ *     site host or a stable internal id).
+ *
+ *   - **`credentialsFor` resolver** — for multi-tenant apps where
+ *     each tenant connects their own WP site. Apps typically fetch
+ *     from a `@strav/social` `social_account` row (storing the
+ *     Application Password in `access_token` and `siteUrl` in
+ *     `metadata.site_url`) or from a bespoke tenant→site table.
+ *
+ * When both are provided, the resolver wins for accountIds it
+ * returns; otherwise the inline map is consulted as fallback.
+ */
+
+export interface WordPressCredentials {
+  /** Absolute base URL of the WP site (e.g. `https://example.com`). No trailing slash required. */
+  siteUrl: string
+  /** WP username. */
+  username: string
+  /** WP Application Password (raw, not the obfuscated dashboard display). */
+  applicationPassword: string
+}
+
+export type WordPressCredentialsResolver = (
+  accountId: string,
+) => Promise<WordPressCredentials | null> | WordPressCredentials | null
+
+export interface WordPressProviderConfig {
+  driver: 'wordpress'
+  /** Inline credentials, keyed by accountId. Convenient for small-N deployments. */
+  sites?: Record<string, WordPressCredentials>
+  /** Async resolver for dynamic / multi-tenant deployments. Beats `sites` on accountId match. */
+  credentialsFor?: WordPressCredentialsResolver
+  /**
+   * Optional `fetch` override (defaults to global `fetch`). Tests
+   * inject a mock; production rarely needs this.
+   */
+  fetch?: typeof fetch
+}