@strav/social 1.0.0-alpha.34 → 1.0.0-alpha.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/social",
-  "version": "1.0.0-alpha.34",
+  "version": "1.0.0-alpha.36",
   "description": "Strav social-login module — provider-agnostic OAuth/OIDC client. Normalized profile + token DTOs, state + PKCE helpers, capability gating, multi-provider routing. Line / Google / Facebook adapters ship as subpath imports (`@strav/social/line`, `@strav/social/google`, `@strav/social/facebook`).",
   "type": "module",
   "main": "./src/index.ts",
@@ -23,9 +23,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.34",
-    "@strav/http": "1.0.0-alpha.34",
-    "@strav/kernel": "1.0.0-alpha.34"
+    "@strav/database": "1.0.0-alpha.36",
+    "@strav/http": "1.0.0-alpha.36",
+    "@strav/kernel": "1.0.0-alpha.36"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/drivers/facebook/facebook_config.ts

@@ -34,6 +34,7 @@ export interface FacebookProviderConfig extends ProviderConfig {
     me?: string
     permissions?: string
     debugToken?: string
+    accounts?: string
   }
   fetch?: typeof fetch
 }
@@ -47,6 +48,7 @@ export function facebookEndpoints(version = DEFAULT_VERSION): {
   me: string
   permissions: string
   debugToken: string
+  accounts: string
 } {
   return {
     authorize: `https://www.facebook.com/${version}/dialog/oauth`,
@@ -54,6 +56,7 @@ export function facebookEndpoints(version = DEFAULT_VERSION): {
     me: `${GRAPH}/${version}/me`,
     permissions: `${GRAPH}/${version}/me/permissions`,
     debugToken: `${GRAPH}/${version}/debug_token`,
+    accounts: `${GRAPH}/${version}/me/accounts`,
   }
 }
 

package/src/drivers/facebook/facebook_driver.ts

@@ -107,6 +107,59 @@ interface DebugTokenResponse {
   }
 }
 
+/**
+ * Normalised view of a Facebook Page returned by `listPages()`.
+ * `accessToken` is the page-scoped long-lived token apps store +
+ * pass to publishing drivers (`@strav/herald/meta`) — the user token
+ * is short-lived and lacks page-level publish scopes by design.
+ */
+export interface FacebookPage {
+  id: string
+  name: string
+  category?: string
+  /** Page-scoped access token. Treat as a long-lived secret. */
+  accessToken: string
+  /** `tasks` field — the management surfaces this token can exercise (`CREATE_CONTENT`, `MODERATE`, …). */
+  tasks?: readonly string[]
+  raw: unknown
+}
+
+/**
+ * Instagram Business Account exposed through a connected Facebook
+ * Page. Returned by `listInstagramBusinessAccounts()` — the page's
+ * `instagram_business_account` field. Apps publishing to IG via
+ * `@strav/herald/meta` use this id as the `accountId`; the
+ * publishing access token is the parent page's `accessToken`.
+ */
+export interface FacebookIgBusinessAccount {
+  id: string
+  username?: string
+  name?: string
+  profilePictureUrl?: string
+  /** Parent Facebook Page id. */
+  pageId: string
+  /** Parent page access token — the credential the IG publishing driver expects. */
+  pageAccessToken: string
+  raw: unknown
+}
+
+interface AccountsResponse {
+  data?: Array<{
+    id?: string
+    name?: string
+    category?: string
+    access_token?: string
+    tasks?: string[]
+    instagram_business_account?: {
+      id?: string
+      username?: string
+      name?: string
+      profile_picture_url?: string
+    }
+  }>
+  paging?: { next?: string }
+}
+
 export class FacebookSocialDriver implements SocialDriver {
   readonly name = PROVIDER
   readonly instanceName: string
@@ -303,8 +356,112 @@ export class FacebookSocialDriver implements SocialDriver {
     return (await res.json()) as DebugTokenResponse
   }
 
+  // ─── Publishing-side enumeration helpers ───────────────────────────
+
+  /**
+   * List the Facebook Pages this user can publish to.
+   *
+   * Calls `GET /me/accounts?fields=id,name,category,access_token,tasks`
+   * — the same endpoint used to mint **page-scoped** access tokens
+   * after a user OAuth exchange. The returned `accessToken` on each
+   * page is the long-lived page token apps store + hand to
+   * `@strav/herald/meta` for FB publishing.
+   *
+   * The user token must carry `pages_show_list`. To actually publish,
+   * the user must also have approved `pages_manage_posts` +
+   * `pages_read_engagement` for the app.
+   *
+   * Pagination: this helper auto-follows `paging.next` and returns
+   * every page. Apps with thousands of pages (rare) trim themselves
+   * client-side.
+   */
+  async listPages(userAccessToken: string): Promise<FacebookPage[]> {
+    const url = `${this.endpoints.accounts}?${new URLSearchParams({
+      access_token: userAccessToken,
+      fields: 'id,name,category,access_token,tasks',
+      limit: '100',
+    }).toString()}`
+    const pages = await this.collectAccounts(url)
+    return pages
+      .filter((p) => p.id && p.name && p.access_token)
+      .map((p) => ({
+        id: p.id!,
+        name: p.name!,
+        accessToken: p.access_token!,
+        ...(p.category ? { category: p.category } : {}),
+        ...(p.tasks ? { tasks: p.tasks } : {}),
+        raw: p,
+      }))
+  }
+
+  /**
+   * List the Instagram Business accounts reachable through this
+   * user's Facebook Pages. Each IG Business account is "owned" by a
+   * Page; the `pageAccessToken` is the credential the IG publishing
+   * driver expects (IG-User tokens for content publishing are
+   * derived from the parent page token).
+   *
+   * Calls `/me/accounts?fields=id,access_token,instagram_business_account{id,username,name,profile_picture_url}`
+   * and flattens out Pages that don't have an IG Business account.
+   *
+   * Scopes required: `pages_show_list` + `instagram_basic`.
+   * Publishing additionally needs `instagram_content_publish` +
+   * `instagram_manage_comments`.
+   */
+  async listInstagramBusinessAccounts(
+    userAccessToken: string,
+  ): Promise<FacebookIgBusinessAccount[]> {
+    const url = `${this.endpoints.accounts}?${new URLSearchParams({
+      access_token: userAccessToken,
+      fields:
+        'id,access_token,instagram_business_account{id,username,name,profile_picture_url}',
+      limit: '100',
+    }).toString()}`
+    const pages = await this.collectAccounts(url)
+    const out: FacebookIgBusinessAccount[] = []
+    for (const p of pages) {
+      const ig = p.instagram_business_account
+      if (!ig?.id || !p.id || !p.access_token) continue
+      out.push({
+        id: ig.id,
+        ...(ig.username ? { username: ig.username } : {}),
+        ...(ig.name ? { name: ig.name } : {}),
+        ...(ig.profile_picture_url ? { profilePictureUrl: ig.profile_picture_url } : {}),
+        pageId: p.id,
+        pageAccessToken: p.access_token,
+        raw: p,
+      })
+    }
+    return out
+  }
+
   // ─── Internals ────────────────────────────────────────────────────────
 
+  private async collectAccounts(
+    url: string,
+  ): Promise<NonNullable<AccountsResponse['data']>> {
+    const out: NonNullable<AccountsResponse['data']> = []
+    let next: string | undefined = url
+    while (next) {
+      const res = await this.fetchFn(next)
+      if (!res.ok) {
+        const text = await res.text()
+        throw new SocialProviderError(
+          `FacebookSocialDriver.collectAccounts: Graph API returned ${res.status}.`,
+          {
+            provider: PROVIDER,
+            operation: 'list_accounts',
+            context: { status: res.status, body: text },
+          },
+        )
+      }
+      const body = (await res.json()) as AccountsResponse
+      if (body.data) out.push(...body.data)
+      next = body.paging?.next
+    }
+    return out
+  }
+
   private toOAuthTokens(t: TokenResponse): OAuthTokens {
     const expiresAt =
       typeof t.expires_in === 'number'

package/src/drivers/facebook/index.ts

@@ -6,7 +6,9 @@ export {
   type FacebookProviderConfig,
 } from './facebook_config.ts'
 export {
-  FacebookSocialDriver,
   type FacebookDriverOptions,
+  type FacebookIgBusinessAccount,
+  type FacebookPage,
+  FacebookSocialDriver,
 } from './facebook_driver.ts'
 export { FacebookSocialProvider } from './facebook_provider.ts'

package/src/drivers/google/google_driver.ts

@@ -94,6 +94,56 @@ interface JwtPayload {
   [k: string]: unknown
 }
 
+/**
+ * Normalised view of a Google Business Profile location returned by
+ * `listGbpLocations()`. The `name` field is the **full GBP resource
+ * path** (`accounts/{aid}/locations/{lid}`) — exactly what
+ * `@strav/herald/gbp` expects as `PublishTarget.accountId`.
+ */
+export interface GbpLocation {
+  /** Full resource path: `accounts/{accountId}/locations/{locationId}`. */
+  name: string
+  /** Account resource path the location belongs to. */
+  accountName: string
+  /** Display title — what the SME sees on their dashboard. */
+  title: string
+  /** Optional storefront address (when set on the listing). */
+  address?: string
+  /** Default language code for this location. */
+  languageCode?: string
+  /** Internal store code the SME assigned, if any. */
+  storeCode?: string
+  raw: unknown
+}
+
+interface GbpAccountsResponse {
+  accounts?: Array<{ name?: string; accountName?: string; type?: string }>
+  nextPageToken?: string
+}
+
+interface GbpLocationsResponse {
+  locations?: Array<{
+    name?: string
+    title?: string
+    languageCode?: string
+    storeCode?: string
+    storefrontAddress?: { addressLines?: string[]; locality?: string; regionCode?: string }
+  }>
+  nextPageToken?: string
+}
+
+function formatGbpAddress(addr: {
+  addressLines?: string[]
+  locality?: string
+  regionCode?: string
+}): string {
+  const parts: string[] = []
+  if (addr.addressLines) parts.push(...addr.addressLines.filter(Boolean))
+  if (addr.locality) parts.push(addr.locality)
+  if (addr.regionCode) parts.push(addr.regionCode)
+  return parts.join(', ')
+}
+
 export class GoogleSocialDriver implements SocialDriver {
   readonly name = PROVIDER
   readonly instanceName: string
@@ -262,8 +312,113 @@ export class GoogleSocialDriver implements SocialDriver {
     }
   }
 
+  // ─── Publishing-side enumeration helpers ───────────────────────────
+
+  /**
+   * List every Google Business Profile location this user can manage.
+   *
+   * Two-call walk (GBP splits accounts + locations across two APIs):
+   *
+   *   1. `mybusinessaccountmanagement.googleapis.com/v1/accounts` —
+   *      every account (personal or business group) the user has a
+   *      management role on.
+   *
+   *   2. For each account, `mybusinessbusinessinformation.googleapis.com
+   *      /v1/{account}/locations?readMask=name,title,storefrontAddress,
+   *      languageCode,storeCode` — every location attached to that
+   *      account.
+   *
+   * Returns one entry per location with the **full resource path**
+   * (`accounts/{aid}/locations/{lid}`) as `name` — the shape
+   * `@strav/herald/gbp` expects as `PublishTarget.accountId`.
+   *
+   * Scope required: `https://www.googleapis.com/auth/business.manage`.
+   * Pagination is auto-followed.
+   */
+  async listGbpLocations(accessToken: string): Promise<GbpLocation[]> {
+    const accounts = await this.collectGbpAccounts(accessToken)
+    const out: GbpLocation[] = []
+    for (const account of accounts) {
+      if (!account.name) continue
+      const locations = await this.collectGbpLocations(accessToken, account.name)
+      for (const loc of locations) {
+        if (!loc.name || !loc.title) continue
+        out.push({
+          name: loc.name,
+          accountName: account.name,
+          title: loc.title,
+          ...(loc.languageCode ? { languageCode: loc.languageCode } : {}),
+          ...(loc.storeCode ? { storeCode: loc.storeCode } : {}),
+          ...(loc.storefrontAddress ? { address: formatGbpAddress(loc.storefrontAddress) } : {}),
+          raw: loc,
+        })
+      }
+    }
+    return out
+  }
+
   // ─── Internals ────────────────────────────────────────────────────────
 
+  private async collectGbpAccounts(
+    accessToken: string,
+  ): Promise<NonNullable<GbpAccountsResponse['accounts']>> {
+    const base = 'https://mybusinessaccountmanagement.googleapis.com/v1/accounts'
+    return this.collectPaged<GbpAccountsResponse, NonNullable<GbpAccountsResponse['accounts']>[number]>(
+      base,
+      accessToken,
+      'list_gbp_accounts',
+      (body) => body.accounts ?? [],
+      (body) => body.nextPageToken,
+    )
+  }
+
+  private async collectGbpLocations(
+    accessToken: string,
+    accountName: string,
+  ): Promise<NonNullable<GbpLocationsResponse['locations']>> {
+    const base = `https://mybusinessbusinessinformation.googleapis.com/v1/${accountName}/locations?readMask=name,title,storefrontAddress,languageCode,storeCode&pageSize=100`
+    return this.collectPaged<
+      GbpLocationsResponse,
+      NonNullable<GbpLocationsResponse['locations']>[number]
+    >(
+      base,
+      accessToken,
+      'list_gbp_locations',
+      (body) => body.locations ?? [],
+      (body) => body.nextPageToken,
+    )
+  }
+
+  private async collectPaged<TBody, TItem>(
+    baseUrl: string,
+    accessToken: string,
+    operation: string,
+    pick: (body: TBody) => readonly TItem[],
+    nextToken: (body: TBody) => string | undefined,
+  ): Promise<TItem[]> {
+    const out: TItem[] = []
+    let pageToken: string | undefined
+    do {
+      const url = pageToken
+        ? `${baseUrl}${baseUrl.includes('?') ? '&' : '?'}pageToken=${encodeURIComponent(pageToken)}`
+        : baseUrl
+      const res = await this.fetchFn(url, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      })
+      if (!res.ok) {
+        const text = await res.text()
+        throw new SocialProviderError(
+          `GoogleSocialDriver.${operation}: GBP API returned ${res.status}.`,
+          { provider: PROVIDER, operation, context: { status: res.status, body: text } },
+        )
+      }
+      const body = (await res.json()) as TBody
+      for (const item of pick(body)) out.push(item)
+      pageToken = nextToken(body)
+    } while (pageToken)
+    return out
+  }
+
   private toOAuthTokens(t: TokenResponse): OAuthTokens {
     const expiresAt =
       typeof t.expires_in === 'number'

package/src/drivers/google/index.ts

@@ -6,7 +6,8 @@ export {
 } from './google_config.ts'
 export {
   emailFromGoogleIdToken,
-  GoogleSocialDriver,
+  type GbpLocation,
   type GoogleDriverOptions,
+  GoogleSocialDriver,
 } from './google_driver.ts'
 export { GoogleSocialProvider } from './google_provider.ts'