@strav/herald 1.0.0-alpha.42

package/README.md

@@ -0,0 +1,48 @@
+# @strav/herald
+
+Provider-agnostic **micro-publishing** for Strav apps.
+
+`@strav/herald` is the publish-side counterpart to `@strav/instant` (chat) and
+`@strav/notification` (per-user delivery). It lets an app publish a post to one
+or more external platforms (Google Business Profile, Facebook Page, Instagram,
+WordPress, …) behind a single normalized API, then receive engagement events
+(reviews, comments, reactions) back through a typed webhook registry.
+
+> **Status:** alpha — scaffold (skeleton + driver contract). Drivers ship in
+> follow-up slices: WordPress first, then Meta, then GBP.
+
+## Install
+
+```bash
+bun add @strav/herald
+```
+
+## Minimal example
+
+```ts
+import { HeraldManager } from '@strav/herald'
+
+const herald = app.resolve(HeraldManager)
+
+const result = await herald.publish(
+  { provider: 'wordpress', accountId: 'wp-tenant-42' },
+  {
+    text: "We just opened our garden patio — come by for the sunset!",
+    attachments: [{ type: 'image', url: 'https://cdn.example.com/patio.jpg' }],
+  },
+)
+
+console.log(result.providerPostId, result.url)
+```
+
+## Drivers (planned subpaths)
+
+| Subpath | Status | Platform |
+| --- | --- | --- |
+| `@strav/herald/wordpress` | planned | WordPress REST |
+| `@strav/herald/meta` | planned | Facebook Page + Instagram (Graph API) |
+| `@strav/herald/gbp` | planned | Google Business Profile |
+| `@strav/herald/x` | future | X (Twitter) |
+| `@strav/herald/tiktok` | future | TikTok |
+
+See `docs/herald/` for setup, OAuth scopes, and webhook wiring.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@strav/herald",
+  "version": "1.0.0-alpha.42",
+  "description": "Strav micro-publishing — provider-agnostic abstraction for publishing posts to social platforms (Google Business Profile, Meta/Facebook + Instagram, WordPress). Normalized PublishInput + capability-flagged drivers + inbound webhook registry for engagement events (reviews, comments, reactions). Drivers ship as subpath imports (`@strav/herald/gbp`, `@strav/herald/meta`, `@strav/herald/wordpress`). X (Twitter), TikTok, LinkedIn, Threads come in later releases.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./onboarding": "./src/onboarding/index.ts",
+    "./tenanted": "./src/tenanted/index.ts",
+    "./gbp": "./src/drivers/gbp/index.ts",
+    "./meta": "./src/drivers/meta/index.ts",
+    "./wordpress": "./src/drivers/wordpress/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/database": "1.0.0-alpha.42",
+    "@strav/http": "1.0.0-alpha.42",
+    "@strav/kernel": "1.0.0-alpha.42"
+  },
+  "devDependencies": {
+    "@strav/social": "1.0.0-alpha.42"
+  },
+  "peerDependencies": {
+    "@strav/social": "1.0.0-alpha.42",
+    "@types/bun": ">=1.3.14"
+  },
+  "peerDependenciesMeta": {
+    "@strav/social": {
+      "optional": true
+    }
+  }
+}

package/src/drivers/gbp/gbp_client.ts

@@ -0,0 +1,155 @@
+/**
+ * `GbpClient` — thin wrapper over `mybusiness.googleapis.com/v4/...`.
+ *
+ * The Posts surface lives at
+ * `/v4/accounts/{aid}/locations/{lid}/localPosts[/{postId}]` —
+ * callers pass the location resource path (`accountId` from
+ * `PublishTarget`) and the client appends the relative leaf.
+ *
+ * Auth is OAuth2 bearer; the token comes from the driver's per-call
+ * `credentialsFor()` resolution. The client doesn't refresh — that's
+ * the app's job inside the resolver.
+ */
+
+import { HeraldProviderError } from '../../errors.ts'
+import type { GbpTopicType } from './gbp_config.ts'
+
+export interface GbpMedia {
+  mediaFormat: 'PHOTO' | 'VIDEO'
+  sourceUrl: string
+}
+
+export interface GbpCallToAction {
+  actionType:
+    | 'BOOK'
+    | 'ORDER'
+    | 'SHOP'
+    | 'LEARN_MORE'
+    | 'SIGN_UP'
+    | 'CALL'
+    | 'GET_OFFER'
+  url?: string
+}
+
+export interface GbpLocalPostBody {
+  languageCode: string
+  summary: string
+  topicType: GbpTopicType
+  media?: GbpMedia[]
+  callToAction?: GbpCallToAction
+  [key: string]: unknown
+}
+
+export interface GbpLocalPost {
+  name: string
+  languageCode: string
+  summary: string
+  topicType: GbpTopicType
+  state: 'LOCAL_POST_STATE_UNSPECIFIED' | 'REJECTED' | 'LIVE' | 'PROCESSING'
+  searchUrl?: string
+  createTime?: string
+  updateTime?: string
+  [key: string]: unknown
+}
+
+export class GbpClient {
+  private readonly fetcher: typeof fetch
+  private readonly accessToken: string
+  private readonly baseUrl = 'https://mybusiness.googleapis.com/v4'
+
+  constructor(input: { accessToken: string; fetch?: typeof fetch }) {
+    this.accessToken = input.accessToken
+    this.fetcher = input.fetch ?? fetch
+  }
+
+  async createLocalPost(location: string, body: GbpLocalPostBody): Promise<GbpLocalPost> {
+    return this.json<GbpLocalPost>('POST', `/${trimSlash(location)}/localPosts`, body)
+  }
+
+  async updateLocalPost(
+    postName: string,
+    body: Partial<GbpLocalPostBody>,
+    updateMask: readonly string[],
+  ): Promise<GbpLocalPost> {
+    const mask = encodeURIComponent(updateMask.join(','))
+    return this.json<GbpLocalPost>(
+      'PATCH',
+      `/${trimSlash(postName)}?updateMask=${mask}`,
+      body,
+    )
+  }
+
+  async deleteLocalPost(postName: string): Promise<void> {
+    await this.bare('DELETE', `/${trimSlash(postName)}`)
+  }
+
+  async getLocalPost(postName: string): Promise<GbpLocalPost> {
+    return this.json<GbpLocalPost>('GET', `/${trimSlash(postName)}`, undefined)
+  }
+
+  private async json<T>(
+    method: 'GET' | 'POST' | 'PATCH',
+    path: string,
+    body: unknown,
+  ): Promise<T> {
+    const res = await this.fetcher(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    })
+    const text = await res.text()
+    let parsed: unknown
+    try {
+      parsed = text ? JSON.parse(text) : {}
+    } catch {
+      parsed = { raw: text }
+    }
+    if (!res.ok) {
+      throw new HeraldProviderError(
+        `GBP: ${method} ${path} failed (${res.status}).`,
+        {
+          provider: 'gbp',
+          operation: `${method} ${path}`,
+          status: 502,
+          context: { responseBody: parsed },
+        },
+      )
+    }
+    return parsed as T
+  }
+
+  private async bare(method: 'DELETE', path: string): Promise<void> {
+    const res = await this.fetcher(`${this.baseUrl}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${this.accessToken}` },
+    })
+    if (!res.ok) {
+      const text = await safeText(res)
+      throw new HeraldProviderError(
+        `GBP: ${method} ${path} failed (${res.status}).`,
+        {
+          provider: 'gbp',
+          operation: `${method} ${path}`,
+          status: 502,
+          context: { responseBody: text },
+        },
+      )
+    }
+  }
+}
+
+function trimSlash(s: string): string {
+  return s.replace(/^\/+/, '').replace(/\/+$/, '')
+}
+
+async function safeText(res: Response): Promise<string> {
+  try {
+    return await res.text()
+  } catch {
+    return ''
+  }
+}

package/src/drivers/gbp/gbp_config.ts

@@ -0,0 +1,48 @@
+/**
+ * `GbpProviderConfig` — `config.herald.providers['...']` shape for the
+ * Google Business Profile driver.
+ *
+ * GBP posts hang off a **location** (a single physical place a SME
+ * operates). One Google account often manages many locations, and a
+ * single SaaS app may manage thousands. The driver addresses
+ * locations via `PublishTarget.accountId` carrying the full GBP
+ * resource path — `accounts/{accountId}/locations/{locationId}` — so
+ * the resolver only needs to look up tokens by that path.
+ *
+ * Auth model:
+ *
+ *   - **Per-account `accessToken`** — short-lived (~1h). The
+ *     `credentialsFor(accountId)` resolver is the app's hook to
+ *     refresh from a stored `refresh_token` before returning. The
+ *     driver does NOT refresh on its own to keep `@strav/herald`
+ *     dependency-free; apps using `@strav/social`'s Google driver
+ *     call `socialDriver.refresh(refreshToken)` inside their
+ *     resolver and persist the rotated access token.
+ *
+ *   - **Default `languageCode`** — GBP requires every post to carry
+ *     a BCP-47 language code. Apps publishing in one language set it
+ *     once on config; multi-language apps override per call via
+ *     `raw.languageCode`.
+ */
+
+export type GbpTopicType = 'STANDARD' | 'EVENT' | 'OFFER' | 'ALERT'
+
+export interface GbpCredentials {
+  /** Short-lived OAuth2 access token with `business.manage` scope. */
+  accessToken: string
+}
+
+export type GbpCredentialsResolver = (
+  accountId: string,
+) => Promise<GbpCredentials | null> | GbpCredentials | null
+
+export interface GbpProviderConfig {
+  driver: 'gbp'
+  credentialsFor: GbpCredentialsResolver
+  /** BCP-47 default language stamped on every post unless `raw.languageCode` overrides. */
+  defaultLanguageCode: string
+  /** Default topic type for `STANDARD` posts. Apps reach for `raw.topicType` to set `EVENT` / `OFFER` / `ALERT`. */
+  defaultTopicType?: GbpTopicType
+  /** Optional `fetch` override for tests. */
+  fetch?: typeof fetch
+}

package/src/drivers/gbp/gbp_driver.ts

@@ -0,0 +1,246 @@
+/**
+ * `GbpDriver` — `HeraldDriver` implementation for Google Business
+ * Profile localPosts.
+ *
+ * Synchronous publish: GBP returns the created `LocalPost` resource
+ * with its `name` + `state` in the same response. State semantics:
+ *
+ *   - `LIVE`       → `published`
+ *   - `PROCESSING` → `pending` (moderation pending; very rare for
+ *                    well-formed posts)
+ *   - `REJECTED`   → `failed`
+ *
+ * `PublishTarget.accountId` carries the **location resource path**:
+ * `accounts/{accountId}/locations/{locationId}`. The driver appends
+ * `/localPosts[/{id}]` to address posts.
+ *
+ * Content mapping (LCD `PublishInput` → GBP):
+ *
+ *   - `text`         → `summary` (max 1500 chars; the driver lets
+ *                      GBP enforce — it returns a 400 with a clear
+ *                      message).
+ *   - first `image`  → `media: [{ mediaFormat: 'PHOTO', sourceUrl }]`.
+ *                      Additional images are ignored — apps wanting
+ *                      multi-image posts reach for `raw.media`.
+ *   - first `link`   → `callToAction: { actionType: 'LEARN_MORE',
+ *                      url }`. Apps wanting `BOOK` / `ORDER` /
+ *                      `SHOP` etc. set `raw.callToAction.actionType`.
+ *   - `hashtags`     → NOT mapped — GBP doesn't surface hashtags.
+ *                      Apps that want them in-line append manually
+ *                      via `text`.
+ *   - `scheduledFor` → throws `ProviderUnsupportedError` (GBP API
+ *                      has no scheduling).
+ *
+ * Updates: GBP requires an explicit `updateMask` query param. The
+ * driver derives the mask from the keys present in the `PublishInput`
+ * (`summary` always; `media` when an image attachment is present;
+ * `callToAction` when a link is present). Apps that want narrower
+ * masks reach for `raw` to suppress fields.
+ *
+ * Webhooks: GBP doesn't ship HTTP webhooks — review notifications
+ * arrive via Google Cloud Pub/Sub subscription. `webhook.*` throws
+ * `ProviderUnsupportedError`. Apps that want review events wire
+ * their own Pub/Sub listener and call into the registry directly.
+ */
+
+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 type { HeraldWebhookEvent } from '../../webhook/herald_event.ts'
+import {
+  GbpClient,
+  type GbpCallToAction,
+  type GbpLocalPost,
+  type GbpLocalPostBody,
+  type GbpMedia,
+} from './gbp_client.ts'
+import type {
+  GbpCredentialsResolver,
+  GbpProviderConfig,
+  GbpTopicType,
+} from './gbp_config.ts'
+
+export interface GbpDriverOptions {
+  instanceName: string
+  credentialsFor: GbpCredentialsResolver
+  defaultLanguageCode: string
+  defaultTopicType?: GbpTopicType
+  fetch?: typeof fetch
+}
+
+const CAPABILITIES: ReadonlySet<HeraldCapability> = new Set<HeraldCapability>([
+  'post.create',
+  'post.update',
+  'post.delete',
+  'post.get',
+  'media.image',
+  'media.link',
+])
+
+const UNSUPPORTED_WEBHOOK: WebhookOps = {
+  verifySignature(): boolean {
+    throw new ProviderUnsupportedError('gbp', 'webhook.verifySignature', {
+      reason: 'GBP delivers review notifications via Google Cloud Pub/Sub, not HTTP webhooks.',
+    })
+  },
+  parse(): HeraldWebhookEvent[] {
+    throw new ProviderUnsupportedError('gbp', 'webhook.parse', {
+      reason: 'GBP delivers review notifications via Google Cloud Pub/Sub, not HTTP webhooks.',
+    })
+  },
+}
+
+export class GbpDriver implements HeraldDriver {
+  readonly name = 'gbp'
+  readonly instanceName: string
+  readonly capabilities = CAPABILITIES
+  readonly webhook: WebhookOps = UNSUPPORTED_WEBHOOK
+
+  private readonly resolver: GbpCredentialsResolver
+  private readonly defaultLanguageCode: string
+  private readonly defaultTopicType: GbpTopicType
+  private readonly fetcher: typeof fetch
+
+  constructor(options: GbpDriverOptions) {
+    this.instanceName = options.instanceName
+    this.resolver = options.credentialsFor
+    this.defaultLanguageCode = options.defaultLanguageCode
+    this.defaultTopicType = options.defaultTopicType ?? 'STANDARD'
+    this.fetcher = options.fetch ?? fetch
+  }
+
+  static fromConfig(instanceName: string, config: GbpProviderConfig): GbpDriver {
+    return new GbpDriver({
+      instanceName,
+      credentialsFor: config.credentialsFor,
+      defaultLanguageCode: config.defaultLanguageCode,
+      ...(config.defaultTopicType ? { defaultTopicType: config.defaultTopicType } : {}),
+      ...(config.fetch ? { fetch: config.fetch } : {}),
+    })
+  }
+
+  async publish(target: PublishTarget, input: PublishInput): Promise<PublishResult> {
+    if (input.scheduledFor) {
+      throw new ProviderUnsupportedError('gbp', 'post.schedule', {
+        reason: 'GBP Posts API does not support scheduled publishing.',
+      })
+    }
+    const client = await this.clientFor(target.accountId)
+    const body = this.buildBody(input)
+    const created = await client.createLocalPost(target.accountId, body)
+    return this.toResult(created)
+  }
+
+  async update(
+    target: PublishTarget,
+    providerPostId: string,
+    input: PublishInput,
+  ): Promise<PublishResult> {
+    const client = await this.clientFor(target.accountId)
+    const body = this.buildBody(input)
+    const mask = this.updateMask(input)
+    const updated = await client.updateLocalPost(providerPostId, body, mask)
+    return this.toResult(updated)
+  }
+
+  async delete(_target: PublishTarget, providerPostId: string): Promise<void> {
+    const client = await this.clientFor(_target.accountId)
+    await client.deleteLocalPost(providerPostId)
+  }
+
+  async get(target: PublishTarget, providerPostId: string): Promise<PostStatus> {
+    const client = await this.clientFor(target.accountId)
+    const post = await client.getLocalPost(providerPostId)
+    return mapState(post.state)
+  }
+
+  // ─── internals ───────────────────────────────────────────────────────
+
+  private async clientFor(accountId: string): Promise<GbpClient> {
+    const creds = await this.resolver(accountId)
+    if (!creds) {
+      throw new HeraldProviderError(
+        `GBP driver: no credentials registered for location "${accountId}".`,
+        { provider: 'gbp', operation: 'clientFor', status: 500 },
+      )
+    }
+    return new GbpClient({ accessToken: creds.accessToken, fetch: this.fetcher })
+  }
+
+  private buildBody(input: PublishInput): GbpLocalPostBody {
+    const raw = (input.raw as Partial<GbpLocalPostBody> | undefined) ?? {}
+
+    const summary = raw.summary ?? input.text ?? ''
+    if (!summary) {
+      throw new HeraldProviderError(
+        'GBP driver: post requires a non-empty `text` or `raw.summary`.',
+        { provider: 'gbp', operation: 'buildBody', status: 400 },
+      )
+    }
+
+    const media = raw.media ?? deriveMedia(input)
+    const callToAction = raw.callToAction ?? deriveCta(input)
+
+    const body: GbpLocalPostBody = {
+      languageCode: raw.languageCode ?? this.defaultLanguageCode,
+      summary,
+      topicType: raw.topicType ?? this.defaultTopicType,
+      ...(media && media.length > 0 ? { media } : {}),
+      ...(callToAction ? { callToAction } : {}),
+      ...raw,
+    }
+    return body
+  }
+
+  private updateMask(input: PublishInput): string[] {
+    const raw = (input.raw as Partial<GbpLocalPostBody> | undefined) ?? {}
+    const mask = new Set<string>(['summary'])
+    if (raw.media || (input.attachments ?? []).some((a) => a.type === 'image')) {
+      mask.add('media')
+    }
+    if (raw.callToAction || (input.attachments ?? []).some((a) => a.type === 'link')) {
+      mask.add('callToAction')
+    }
+    if (raw.topicType) mask.add('topicType')
+    if (raw.languageCode) mask.add('languageCode')
+    return [...mask]
+  }
+
+  private toResult(post: GbpLocalPost): PublishResult {
+    return {
+      provider: 'gbp',
+      providerPostId: post.name,
+      ...(post.searchUrl ? { url: post.searchUrl } : {}),
+      status: mapState(post.state),
+      raw: post,
+    }
+  }
+}
+
+function deriveMedia(input: PublishInput): GbpMedia[] | undefined {
+  const firstImage = (input.attachments ?? []).find((a) => a.type === 'image')
+  if (!firstImage) return undefined
+  return [{ mediaFormat: 'PHOTO', sourceUrl: firstImage.url }]
+}
+
+function deriveCta(input: PublishInput): GbpCallToAction | undefined {
+  const firstLink = (input.attachments ?? []).find((a) => a.type === 'link')
+  if (!firstLink) return undefined
+  return { actionType: 'LEARN_MORE', url: firstLink.url }
+}
+
+function mapState(state: GbpLocalPost['state']): PostStatus {
+  switch (state) {
+    case 'LIVE':
+      return 'published'
+    case 'PROCESSING':
+    case 'LOCAL_POST_STATE_UNSPECIFIED':
+      return 'pending'
+    case 'REJECTED':
+      return 'failed'
+  }
+}

package/src/drivers/gbp/gbp_provider.ts

@@ -0,0 +1,35 @@
+/**
+ * `GbpHeraldProvider` — `ServiceProvider` that registers the GBP
+ * driver factory on the `HeraldManager`.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { HeraldConfigError } from '../../errors.ts'
+import { HeraldManager } from '../../herald_manager.ts'
+import type { GbpProviderConfig } from './gbp_config.ts'
+import { GbpDriver } from './gbp_driver.ts'
+
+export class GbpHeraldProvider extends ServiceProvider {
+  override readonly name = 'herald-gbp'
+  override readonly dependencies = ['herald']
+
+  override register(app: Application): void {
+    const manager = app.resolve(HeraldManager)
+    manager.extend('gbp', ({ instanceName, config }) => {
+      const cfg = config as unknown as GbpProviderConfig
+      if (!cfg.credentialsFor) {
+        throw new HeraldConfigError(
+          `GbpHeraldProvider: provider "${instanceName}" needs a \`credentialsFor\` resolver.`,
+          { context: { instanceName } },
+        )
+      }
+      if (!cfg.defaultLanguageCode) {
+        throw new HeraldConfigError(
+          `GbpHeraldProvider: provider "${instanceName}" needs a \`defaultLanguageCode\` (BCP-47, e.g. "en" or "th").`,
+          { context: { instanceName } },
+        )
+      }
+      return GbpDriver.fromConfig(instanceName, cfg)
+    })
+  }
+}

package/src/drivers/gbp/index.ts

@@ -0,0 +1,23 @@
+// Public API of `@strav/herald/gbp`.
+//
+// Google Business Profile driver — `mybusiness.googleapis.com/v4`
+// localPosts. STANDARD posts in v1 (EVENT / OFFER / ALERT via
+// `raw.topicType`). Per-account OAuth2 access token (apps refresh
+// inside their resolver). No scheduling and no HTTP webhooks (GBP
+// uses Pub/Sub for review notifications).
+
+export {
+  GbpClient,
+  type GbpCallToAction,
+  type GbpLocalPost,
+  type GbpLocalPostBody,
+  type GbpMedia,
+} from './gbp_client.ts'
+export type {
+  GbpCredentials,
+  GbpCredentialsResolver,
+  GbpProviderConfig,
+  GbpTopicType,
+} from './gbp_config.ts'
+export { GbpDriver, type GbpDriverOptions } from './gbp_driver.ts'
+export { GbpHeraldProvider } from './gbp_provider.ts'

package/src/drivers/meta/index.ts

@@ -0,0 +1,21 @@
+// Public API of `@strav/herald/meta`.
+//
+// Meta Graph driver for Facebook Pages + Instagram Business. One
+// instance per platform (`platform: 'facebook' | 'instagram'` on
+// config). Auth: per-app `appSecret` + per-account `accessToken`
+// resolver. Webhooks: HMAC-SHA256 verification + normalization of
+// page-feed comments, page ratings, IG comments.
+
+export {
+  MetaGraphClient,
+  type GraphResponse,
+} from './meta_client.ts'
+export type {
+  MetaCredentials,
+  MetaCredentialsResolver,
+  MetaPlatform,
+  MetaProviderConfig,
+} from './meta_config.ts'
+export { MetaDriver, type MetaDriverOptions } from './meta_driver.ts'
+export { MetaHeraldProvider } from './meta_provider.ts'
+export { MetaWebhookOps, type MetaWebhookOpsOptions } from './meta_webhook_ops.ts'