@strav/herald 1.0.0-alpha.42

package/src/drivers/meta/meta_client.ts

@@ -0,0 +1,103 @@
+/**
+ * `MetaGraphClient` — thin wrapper over `graph.facebook.com`.
+ *
+ * Adds `access_token` + (when an `appSecret` is provided) the
+ * `appsecret_proof` parameter to every request — Meta strongly
+ * recommends it for hardened apps and it's mandatory when "Require
+ * App Secret" is on.
+ *
+ * Errors come back as `{ error: { message, code, type, ... } }`;
+ * the client maps them to `HeraldProviderError` with the original
+ * payload on `context.responseBody`.
+ */
+
+import { createHmac } from 'node:crypto'
+import { HeraldProviderError } from '../../errors.ts'
+
+export interface GraphResponse {
+  id?: string
+  post_id?: string
+  permalink_url?: string
+  permalink?: string
+  [key: string]: unknown
+}
+
+export class MetaGraphClient {
+  private readonly baseUrl: string
+  private readonly accessToken: string
+  private readonly appSecret: string
+  private readonly fetcher: typeof fetch
+
+  constructor(input: {
+    accessToken: string
+    appSecret: string
+    apiVersion?: string
+    fetch?: typeof fetch
+  }) {
+    this.accessToken = input.accessToken
+    this.appSecret = input.appSecret
+    this.baseUrl = `https://graph.facebook.com/${input.apiVersion ?? 'v21.0'}`
+    this.fetcher = input.fetch ?? fetch
+  }
+
+  /** Hex-encoded HMAC-SHA256(appSecret, accessToken) — required for hardened Graph calls. */
+  appsecretProof(): string {
+    return createHmac('sha256', this.appSecret).update(this.accessToken).digest('hex')
+  }
+
+  async get<T = GraphResponse>(path: string, query: Record<string, unknown> = {}): Promise<T> {
+    return this.request<T>('GET', path, query, undefined)
+  }
+
+  async post<T = GraphResponse>(
+    path: string,
+    body: Record<string, unknown>,
+  ): Promise<T> {
+    return this.request<T>('POST', path, {}, body)
+  }
+
+  async delete<T = GraphResponse>(path: string): Promise<T> {
+    return this.request<T>('DELETE', path, {}, undefined)
+  }
+
+  private async request<T>(
+    method: 'GET' | 'POST' | 'DELETE',
+    path: string,
+    query: Record<string, unknown>,
+    body: Record<string, unknown> | undefined,
+  ): Promise<T> {
+    const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`)
+    url.searchParams.set('access_token', this.accessToken)
+    url.searchParams.set('appsecret_proof', this.appsecretProof())
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== null) url.searchParams.set(k, String(v))
+    }
+
+    const init: RequestInit = { method }
+    if (body !== undefined) {
+      init.headers = { 'Content-Type': 'application/json' }
+      init.body = JSON.stringify(body)
+    }
+
+    const res = await this.fetcher(url.toString(), init)
+    const text = await res.text()
+    let parsed: unknown
+    try {
+      parsed = text ? JSON.parse(text) : {}
+    } catch {
+      parsed = { raw: text }
+    }
+    if (!res.ok) {
+      throw new HeraldProviderError(
+        `Meta Graph: ${method} ${path} failed (${res.status}).`,
+        {
+          provider: 'meta',
+          operation: `${method} ${path}`,
+          status: 502,
+          context: { responseBody: parsed },
+        },
+      )
+    }
+    return parsed as T
+  }
+}

package/src/drivers/meta/meta_config.ts

@@ -0,0 +1,45 @@
+/**
+ * `MetaProviderConfig` — `config.herald.providers['...']` shape for
+ * the Meta Graph driver. One instance serves one platform — apps
+ * publishing to both Facebook Pages and Instagram Business declare
+ * two providers, each with its own `platform` setting:
+ *
+ *   config.herald.providers = {
+ *     'facebook':  { driver: 'meta', platform: 'facebook',  ... },
+ *     'instagram': { driver: 'meta', platform: 'instagram', ... },
+ *   }
+ *
+ * Auth model:
+ *
+ *   - **Per-instance `appSecret`** — constant per Meta app. Used
+ *     for `appsecret_proof` on hardened Graph calls and for webhook
+ *     signature verification. Apps load it once from env.
+ *
+ *   - **Per-account `accessToken`** — long-lived Page token (FB) or
+ *     IG-User token (IG), one per connected account. The
+ *     `credentialsFor(accountId)` resolver returns it; apps
+ *     typically read from `@strav/social`'s `social_account` ledger.
+ */
+
+export type MetaPlatform = 'facebook' | 'instagram'
+
+export interface MetaCredentials {
+  /** Long-lived Page access token (FB) or IG-User access token (IG). */
+  accessToken: string
+}
+
+export type MetaCredentialsResolver = (
+  accountId: string,
+) => Promise<MetaCredentials | null> | MetaCredentials | null
+
+export interface MetaProviderConfig {
+  driver: 'meta'
+  platform: MetaPlatform
+  /** Meta app secret — constant per Meta app. */
+  appSecret: string
+  credentialsFor: MetaCredentialsResolver
+  /** Graph API version. Default `v21.0`. */
+  apiVersion?: string
+  /** Optional `fetch` override for tests. */
+  fetch?: typeof fetch
+}

package/src/drivers/meta/meta_driver.ts

@@ -0,0 +1,313 @@
+/**
+ * `MetaDriver` — `HeraldDriver` implementation for Meta's Graph API.
+ *
+ * One instance serves **one platform** (`facebook` or `instagram`).
+ * Apps publishing to both declare two `config.herald.providers`
+ * entries — same driver class, different `platform` setting.
+ *
+ * Facebook Pages (synchronous):
+ *
+ *   - Text-only / text-with-link → `POST /{page-id}/feed` with
+ *     `message` (+ optional `link`).
+ *   - With image → `POST /{page-id}/photos` with `url` (FB hosts
+ *     the image). Multi-image posts are deferred to a follow-up
+ *     slice (would require unpublished photo IDs + attached_media).
+ *   - Scheduled (`scheduledFor`) → `published=false` +
+ *     `scheduled_publish_time` (unix seconds).
+ *   - Update: NOT supported (FB removed feed edits via API).
+ *   - Delete: `DELETE /{post-id}`.
+ *
+ * Instagram Business (two-step container publish):
+ *
+ *   - Step 1: `POST /{ig-user-id}/media` with `image_url` +
+ *     `caption` → returns `creation_id`.
+ *   - Step 2: `POST /{ig-user-id}/media_publish` with `creation_id`
+ *     → returns the IG media `id`.
+ *   - Image-only in v1. Videos require status polling; carousels
+ *     require child containers — both deferred.
+ *   - Scheduled posts are NOT supported on the IG Content Publishing
+ *     API; `scheduledFor` throws `ProviderUnsupportedError`.
+ *   - Update + delete: NOT supported via API.
+ *
+ * Webhook ops delegated to `MetaWebhookOps`.
+ */
+
+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 { HeraldProviderError, ProviderUnsupportedError } from '../../errors.ts'
+import type { HeraldCapability } from '../../herald_capabilities.ts'
+import type { HeraldDriver, WebhookOps } from '../../herald_driver.ts'
+import { MetaGraphClient } from './meta_client.ts'
+import type {
+  MetaCredentialsResolver,
+  MetaPlatform,
+  MetaProviderConfig,
+} from './meta_config.ts'
+import { MetaWebhookOps } from './meta_webhook_ops.ts'
+
+export interface MetaDriverOptions {
+  instanceName: string
+  platform: MetaPlatform
+  /** Meta app secret — constant per Meta app. Required for `appsecret_proof` + webhook verification. */
+  appSecret: string
+  credentialsFor: MetaCredentialsResolver
+  apiVersion?: string
+  fetch?: typeof fetch
+  /** Optional webhook ops override (mainly for tests). */
+  webhook?: WebhookOps
+}
+
+const FACEBOOK_CAPS: ReadonlySet<HeraldCapability> = new Set<HeraldCapability>([
+  'post.create',
+  'post.delete',
+  'post.get',
+  'post.schedule',
+  'media.image',
+  'media.link',
+  'webhook.signature',
+  'webhook.parse',
+  'webhook.engagement.comment',
+  'webhook.engagement.review',
+])
+
+const INSTAGRAM_CAPS: ReadonlySet<HeraldCapability> = new Set<HeraldCapability>([
+  'post.create',
+  'post.get',
+  'media.image',
+  'text.hashtags',
+  'text.mentions',
+  'webhook.signature',
+  'webhook.parse',
+  'webhook.engagement.comment',
+])
+
+export class MetaDriver implements HeraldDriver {
+  readonly name = 'meta'
+  readonly instanceName: string
+  readonly platform: MetaPlatform
+  readonly capabilities: ReadonlySet<HeraldCapability>
+  readonly webhook: WebhookOps
+
+  private readonly appSecret: string
+  private readonly resolver: MetaCredentialsResolver
+  private readonly apiVersion: string | undefined
+  private readonly fetcher: typeof fetch
+
+  constructor(options: MetaDriverOptions) {
+    this.instanceName = options.instanceName
+    this.platform = options.platform
+    this.capabilities = options.platform === 'facebook' ? FACEBOOK_CAPS : INSTAGRAM_CAPS
+    this.appSecret = options.appSecret
+    this.resolver = options.credentialsFor
+    this.apiVersion = options.apiVersion
+    this.fetcher = options.fetch ?? fetch
+    this.webhook =
+      options.webhook ??
+      new MetaWebhookOps({ appSecret: options.appSecret, driverName: 'meta' })
+  }
+
+  static fromConfig(instanceName: string, config: MetaProviderConfig): MetaDriver {
+    return new MetaDriver({
+      instanceName,
+      platform: config.platform,
+      appSecret: config.appSecret,
+      credentialsFor: config.credentialsFor,
+      ...(config.apiVersion ? { apiVersion: config.apiVersion } : {}),
+      ...(config.fetch ? { fetch: config.fetch } : {}),
+    })
+  }
+
+  async publish(target: PublishTarget, input: PublishInput): Promise<PublishResult> {
+    const client = await this.clientFor(target.accountId)
+    return this.platform === 'facebook'
+      ? this.publishFacebook(target.accountId, client, input)
+      : this.publishInstagram(target.accountId, client, input)
+  }
+
+  async delete(target: PublishTarget, providerPostId: string): Promise<void> {
+    if (this.platform !== 'facebook') {
+      throw new ProviderUnsupportedError('meta-instagram', 'delete', {
+        reason: 'Instagram Graph API does not support post deletion.',
+      })
+    }
+    const client = await this.clientFor(target.accountId)
+    await client.delete(`/${providerPostId}`)
+  }
+
+  async get(target: PublishTarget, providerPostId: string): Promise<PostStatus> {
+    const client = await this.clientFor(target.accountId)
+    try {
+      await client.get(`/${providerPostId}`, { fields: 'id' })
+      return 'published'
+    } catch (cause) {
+      if (cause instanceof HeraldProviderError) return 'deleted'
+      throw cause
+    }
+  }
+
+  // ─── platform implementations ────────────────────────────────────────
+
+  private async publishFacebook(
+    accountId: string,
+    client: MetaGraphClient,
+    input: PublishInput,
+  ): Promise<PublishResult> {
+    const raw = (input.raw as Record<string, unknown> | undefined) ?? {}
+    const message = buildMessage(input)
+    const image = (input.attachments ?? []).find((a) => a.type === 'image')
+    const link = (input.attachments ?? []).find((a) => a.type === 'link')
+    const scheduled = !!input.scheduledFor
+
+    if (image) {
+      const body: Record<string, unknown> = {
+        url: image.url,
+        ...(message ? { caption: message } : {}),
+        ...raw,
+      }
+      applySchedule(body, input.scheduledFor)
+      const res = await client.post<{ id?: string; post_id?: string }>(
+        `/${accountId}/photos`,
+        body,
+      )
+      const postId = res.post_id ?? res.id
+      if (!postId) {
+        throw new HeraldProviderError(
+          'Meta (Facebook): photos endpoint returned no post_id / id.',
+          { provider: 'meta', operation: 'publishFacebook', status: 502, context: { raw: res } },
+        )
+      }
+      return this.facebookResult(postId, scheduled, res)
+    }
+
+    const body: Record<string, unknown> = {
+      ...(message ? { message } : {}),
+      ...(link ? { link: link.url } : {}),
+      ...raw,
+    }
+    applySchedule(body, input.scheduledFor)
+    const res = await client.post<{ id?: string }>(`/${accountId}/feed`, body)
+    if (!res.id) {
+      throw new HeraldProviderError(
+        'Meta (Facebook): feed endpoint returned no id.',
+        { provider: 'meta', operation: 'publishFacebook', status: 502, context: { raw: res } },
+      )
+    }
+    return this.facebookResult(res.id, scheduled, res)
+  }
+
+  private facebookResult(
+    postId: string,
+    scheduled: boolean,
+    raw: unknown,
+  ): PublishResult {
+    return {
+      provider: 'meta',
+      providerPostId: postId,
+      status: scheduled ? 'pending' : 'published',
+      raw,
+    }
+  }
+
+  private async publishInstagram(
+    accountId: string,
+    client: MetaGraphClient,
+    input: PublishInput,
+  ): Promise<PublishResult> {
+    if (input.scheduledFor) {
+      throw new ProviderUnsupportedError('meta-instagram', 'post.schedule', {
+        reason: 'IG Content Publishing API does not support scheduled posts.',
+      })
+    }
+    const image = (input.attachments ?? []).find((a) => a.type === 'image')
+    if (!image) {
+      throw new HeraldProviderError(
+        'Meta (Instagram): publish requires an image attachment in v1 (video + carousel deferred).',
+        { provider: 'meta', operation: 'publishInstagram', status: 400 },
+      )
+    }
+
+    const caption = buildCaption(input)
+    const raw = (input.raw as Record<string, unknown> | undefined) ?? {}
+
+    // Step 1 — create media container
+    const container = await client.post<{ id?: string }>(`/${accountId}/media`, {
+      image_url: image.url,
+      ...(caption ? { caption } : {}),
+      ...raw,
+    })
+    if (!container.id) {
+      throw new HeraldProviderError(
+        'Meta (Instagram): /media did not return a creation id.',
+        { provider: 'meta', operation: 'publishInstagram', status: 502, context: { raw: container } },
+      )
+    }
+
+    // Step 2 — publish container
+    const published = await client.post<{ id?: string }>(`/${accountId}/media_publish`, {
+      creation_id: container.id,
+    })
+    if (!published.id) {
+      throw new HeraldProviderError(
+        'Meta (Instagram): /media_publish did not return an id.',
+        { provider: 'meta', operation: 'publishInstagram', status: 502, context: { raw: published } },
+      )
+    }
+
+    return {
+      provider: 'meta',
+      providerPostId: published.id,
+      status: 'published',
+      raw: { container, published },
+    }
+  }
+
+  // ─── internals ───────────────────────────────────────────────────────
+
+  private async clientFor(accountId: string): Promise<MetaGraphClient> {
+    const resolved = await this.resolver(accountId)
+    if (!resolved) {
+      throw new HeraldProviderError(
+        `Meta driver: no credentials registered for account "${accountId}".`,
+        { provider: 'meta', operation: 'clientFor', status: 500 },
+      )
+    }
+    return new MetaGraphClient({
+      accessToken: resolved.accessToken,
+      appSecret: this.appSecret,
+      ...(this.apiVersion ? { apiVersion: this.apiVersion } : {}),
+      fetch: this.fetcher,
+    })
+  }
+}
+
+function buildMessage(input: PublishInput): string {
+  const parts: string[] = []
+  if (input.text) parts.push(input.text)
+  if (input.hashtags && input.hashtags.length > 0) {
+    parts.push(input.hashtags.map((h) => `#${h}`).join(' '))
+  }
+  return parts.join('\n\n')
+}
+
+function buildCaption(input: PublishInput): string {
+  // IG captions accept hashtags + emoji freely; same shape as the
+  // FB message for now. Links in captions aren't clickable on IG
+  // but are commonly included anyway.
+  const parts: string[] = []
+  if (input.text) parts.push(input.text)
+  for (const att of input.attachments ?? []) {
+    if (att.type === 'link') parts.push(att.url)
+  }
+  if (input.hashtags && input.hashtags.length > 0) {
+    parts.push(input.hashtags.map((h) => `#${h}`).join(' '))
+  }
+  return parts.join('\n\n')
+}
+
+function applySchedule(body: Record<string, unknown>, scheduledFor: Date | undefined): void {
+  if (!scheduledFor) return
+  body['published'] = false
+  body['scheduled_publish_time'] = Math.floor(scheduledFor.getTime() / 1000)
+}

package/src/drivers/meta/meta_provider.ts

@@ -0,0 +1,45 @@
+/**
+ * `MetaHeraldProvider` — `ServiceProvider` that registers the Meta
+ * driver factory on the `HeraldManager`.
+ *
+ * Apps list this AFTER `HeraldProvider`. One factory registration
+ * covers every Meta-driven instance — the per-instance `platform`
+ * field (`facebook` | `instagram`) flips behaviour inside the driver.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { HeraldConfigError } from '../../errors.ts'
+import { HeraldManager } from '../../herald_manager.ts'
+import type { MetaProviderConfig } from './meta_config.ts'
+import { MetaDriver } from './meta_driver.ts'
+
+export class MetaHeraldProvider extends ServiceProvider {
+  override readonly name = 'herald-meta'
+  override readonly dependencies = ['herald']
+
+  override register(app: Application): void {
+    const manager = app.resolve(HeraldManager)
+    manager.extend('meta', ({ instanceName, config }) => {
+      const cfg = config as unknown as MetaProviderConfig
+      if (!cfg.platform || (cfg.platform !== 'facebook' && cfg.platform !== 'instagram')) {
+        throw new HeraldConfigError(
+          `MetaHeraldProvider: provider "${instanceName}" needs \`platform: 'facebook' | 'instagram'\`.`,
+          { context: { instanceName, platform: cfg.platform } },
+        )
+      }
+      if (!cfg.appSecret) {
+        throw new HeraldConfigError(
+          `MetaHeraldProvider: provider "${instanceName}" needs \`appSecret\` (the Meta app secret).`,
+          { context: { instanceName } },
+        )
+      }
+      if (!cfg.credentialsFor) {
+        throw new HeraldConfigError(
+          `MetaHeraldProvider: provider "${instanceName}" needs a \`credentialsFor\` resolver.`,
+          { context: { instanceName } },
+        )
+      }
+      return MetaDriver.fromConfig(instanceName, cfg)
+    })
+  }
+}