@automate.ax/integration-contracts 0.161.0 → 0.163.1

package/src/highlevel/events.ts

@@ -85,7 +85,7 @@ const MESSAGE_FIELDS = {
   from: z.string().optional(),
   messageId: z.string().optional(),
   messageType: z.string().optional(),
-  messageTypeId: z.string().optional(),
+  messageTypeId: z.number().optional(),
   messageTypeString: z.string().optional(),
   provider: z.string().optional(),
   source: z.string().optional(),

package/src/meta-ads/events.ts

@@ -102,6 +102,122 @@ export const META_ADS_LEAD_CREATED_EVENT_SCHEMA = z.object({
   pageId: META_ADS_ID_SCHEMA,
 })
 
+const META_ADS_MESSAGE_ATTACHMENT_SCHEMA = z.object({
+  /** Provider attachment payload, such as `url`, `title`, or `stickerId`. */
+  payload: z.record(z.string(), encodableSchema).optional(),
+
+  /**
+   * Provider attachment type, such as `image`, `video`, `ig_reel`, or
+   * `story_mention`.
+   */
+  type: z.string(),
+})
+
+const META_ADS_MESSAGE_REFERRAL_SCHEMA = z.object({
+  adId: z.string().optional(),
+  adsContextData: z
+    .object({
+      adTitle: z.string().optional(),
+      flowId: z.string().optional(),
+      photoUrl: z.string().optional(),
+      postId: z.string().optional(),
+      productId: z.string().optional(),
+      videoUrl: z.string().optional(),
+    })
+    .optional(),
+  ref: z.string().optional(),
+  source: z.string().optional(),
+  type: z.string().optional(),
+})
+
+const META_ADS_RECEIVED_MESSAGE_BASE_SCHEMA = z.object({
+  attachments: META_ADS_MESSAGE_ATTACHMENT_SCHEMA.array(),
+  messageId: META_ADS_ID_SCHEMA,
+  quickReplyPayload: z.string().optional(),
+  recipientId: META_ADS_ID_SCHEMA,
+  referral: META_ADS_MESSAGE_REFERRAL_SCHEMA.optional(),
+  senderId: META_ADS_ID_SCHEMA,
+  text: z.string().optional(),
+  timestamp: z.number().int().nonnegative(),
+})
+
+export const META_ADS_PAGE_COMMENT_CREATED_EVENT_SCHEMA = z.object({
+  commentId: META_ADS_ID_SCHEMA,
+  createdTime: z.number().int().nonnegative(),
+  from: z.object({ id: z.string(), name: z.string().optional() }).optional(),
+  message: z.string().optional(),
+  pageId: META_ADS_ID_SCHEMA,
+  parentId: z.string().optional(),
+  photo: z.string().optional(),
+  post: z
+    .object({
+      id: z.string().optional(),
+      isPublished: z.boolean().optional(),
+      permalinkUrl: z.string().optional(),
+      promotionStatus: z.string().optional(),
+      statusType: z.string().optional(),
+      updatedTime: z.string().optional(),
+    })
+    .optional(),
+  postId: META_ADS_ID_SCHEMA,
+  video: z.string().optional(),
+})
+
+export const META_ADS_MESSENGER_MESSAGE_RECEIVED_EVENT_SCHEMA =
+  META_ADS_RECEIVED_MESSAGE_BASE_SCHEMA.extend({
+    pageId: META_ADS_ID_SCHEMA,
+    replyToMessageId: z.string().optional(),
+  })
+
+export const META_ADS_INSTAGRAM_COMMENT_CREATED_EVENT_SCHEMA = z.object({
+  commentId: META_ADS_ID_SCHEMA,
+  from: z.object({ id: z.string(), username: z.string().optional() }),
+  instagramAccountId: META_ADS_ID_SCHEMA,
+  media: z.object({
+    adId: z.string().optional(),
+    adTitle: z.string().optional(),
+    id: META_ADS_ID_SCHEMA,
+    mediaProductType: z.string().optional(),
+    originalMediaId: z.string().optional(),
+  }),
+  occurredAt: z.number().int().nonnegative(),
+  parentId: z.string().optional(),
+  text: z.string().optional(),
+})
+
+export const META_ADS_INSTAGRAM_MENTION_CREATED_EVENT_SCHEMA = z.object({
+  commentId: z.string().optional(),
+  instagramAccountId: META_ADS_ID_SCHEMA,
+  kind: z.enum(["caption", "comment"]),
+  mediaId: META_ADS_ID_SCHEMA,
+  occurredAt: z.number().int().nonnegative(),
+})
+
+export const META_ADS_INSTAGRAM_MESSAGE_RECEIVED_EVENT_SCHEMA =
+  META_ADS_RECEIVED_MESSAGE_BASE_SCHEMA.extend({
+    instagramAccountId: META_ADS_ID_SCHEMA,
+    isUnsupported: z.boolean(),
+    replyTo: z
+      .object({
+        messageId: z.string().optional(),
+        story: z
+          .object({
+            id: z.string(),
+            linkStickerUrl: z.string().optional(),
+            url: z.string().optional(),
+          })
+          .optional(),
+      })
+      .optional(),
+  })
+
+export const META_ADS_INSTAGRAM_MESSAGE_DELETED_EVENT_SCHEMA = z.object({
+  instagramAccountId: META_ADS_ID_SCHEMA,
+  messageId: META_ADS_ID_SCHEMA,
+  senderId: META_ADS_ID_SCHEMA,
+  timestamp: z.number().int().nonnegative(),
+})
+
 export const META_ADS_TRIGGER_CONFIG_SCHEMA = z.object({
   account: z.string().optional(),
   adAccountId: META_ADS_ID_SCHEMA,
@@ -112,9 +228,37 @@ export const META_ADS_LEAD_TRIGGER_CONFIG_SCHEMA = z.object({
   pageId: META_ADS_ID_SCHEMA,
 })
 
+export const META_ADS_PAGE_TRIGGER_CONFIG_SCHEMA = z.object({
+  account: z.string().optional(),
+  pageId: META_ADS_ID_SCHEMA,
+})
+
+export const META_ADS_INSTAGRAM_TRIGGER_CONFIG_SCHEMA = z.object({
+  account: z.string().optional(),
+  instagramAccountId: META_ADS_ID_SCHEMA,
+})
+
 export interface NormalizedMetaAdsWebhook {
   adAccountEvents: z.output<typeof META_ADS_EVENT_SCHEMA>[]
+  instagramCommentEvents: z.output<
+    typeof META_ADS_INSTAGRAM_COMMENT_CREATED_EVENT_SCHEMA
+  >[]
+  instagramMentionEvents: z.output<
+    typeof META_ADS_INSTAGRAM_MENTION_CREATED_EVENT_SCHEMA
+  >[]
+  instagramMessageDeletedEvents: z.output<
+    typeof META_ADS_INSTAGRAM_MESSAGE_DELETED_EVENT_SCHEMA
+  >[]
+  instagramMessageEvents: z.output<
+    typeof META_ADS_INSTAGRAM_MESSAGE_RECEIVED_EVENT_SCHEMA
+  >[]
   leadEvents: z.output<typeof META_ADS_LEAD_CREATED_EVENT_SCHEMA>[]
+  messengerMessageEvents: z.output<
+    typeof META_ADS_MESSENGER_MESSAGE_RECEIVED_EVENT_SCHEMA
+  >[]
+  pageCommentEvents: z.output<
+    typeof META_ADS_PAGE_COMMENT_CREATED_EVENT_SCHEMA
+  >[]
 }
 
 export const metaAdsTriggerContracts = {
@@ -154,6 +298,22 @@ export const metaAdsTriggerContracts = {
     configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
     eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
   },
+  "meta-ads.instagramComment.created": {
+    configSchema: META_ADS_INSTAGRAM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_INSTAGRAM_COMMENT_CREATED_EVENT_SCHEMA,
+  },
+  "meta-ads.instagramMention.created": {
+    configSchema: META_ADS_INSTAGRAM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_INSTAGRAM_MENTION_CREATED_EVENT_SCHEMA,
+  },
+  "meta-ads.instagramMessage.deleted": {
+    configSchema: META_ADS_INSTAGRAM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_INSTAGRAM_MESSAGE_DELETED_EVENT_SCHEMA,
+  },
+  "meta-ads.instagramMessage.received": {
+    configSchema: META_ADS_INSTAGRAM_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_INSTAGRAM_MESSAGE_RECEIVED_EVENT_SCHEMA,
+  },
   "meta-ads.insights.updated": {
     configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
     eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
@@ -162,6 +322,10 @@ export const metaAdsTriggerContracts = {
     configSchema: META_ADS_LEAD_TRIGGER_CONFIG_SCHEMA,
     eventSchema: META_ADS_LEAD_CREATED_EVENT_SCHEMA,
   },
+  "meta-ads.messengerMessage.received": {
+    configSchema: META_ADS_PAGE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_MESSENGER_MESSAGE_RECEIVED_EVENT_SCHEMA,
+  },
   "meta-ads.object.created": {
     configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
     eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
@@ -170,10 +334,94 @@ export const metaAdsTriggerContracts = {
     configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
     eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
   },
+  "meta-ads.pageComment.created": {
+    configSchema: META_ADS_PAGE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_PAGE_COMMENT_CREATED_EVENT_SCHEMA,
+  },
 } as const
 
+const LEADGEN_VALUE_SCHEMA = z.object({
+  ad_id: z.string().optional(),
+  adgroup_id: z.string().optional(),
+  created_time: z.number().int().nonnegative(),
+  form_id: z.string(),
+  leadgen_id: z.string(),
+  page_id: z.string(),
+})
+
+const FEED_COMMENT_ADD_SCHEMA = z.object({
+  item: z.literal("comment"),
+  verb: z.literal("add"),
+})
+
+const FEED_COMMENT_VALUE_SCHEMA =
+  META_ADS_PAGE_COMMENT_CREATED_EVENT_SCHEMA.omit({ pageId: true }).extend({
+    createdTime: z.union([
+      META_ADS_PAGE_COMMENT_CREATED_EVENT_SCHEMA.shape.createdTime,
+      z
+        .string()
+        .transform((value) => Math.floor(Date.parse(value) / 1_000))
+        .pipe(META_ADS_PAGE_COMMENT_CREATED_EVENT_SCHEMA.shape.createdTime),
+    ]),
+  })
+
+const INSTAGRAM_COMMENT_VALUE_SCHEMA = z.object({
+  commentId: z.string().optional(),
+  from: META_ADS_INSTAGRAM_COMMENT_CREATED_EVENT_SCHEMA.shape.from.extend({
+    selfIgScopedId: z.string().optional(),
+  }),
+  id: z.string().optional(),
+  media: META_ADS_INSTAGRAM_COMMENT_CREATED_EVENT_SCHEMA.shape.media,
+  parentId: z.string().optional(),
+  text: z.string().optional(),
+})
+
+const INSTAGRAM_MENTION_VALUE_SCHEMA = z.object({
+  commentId: z.string().optional(),
+  mediaId: META_ADS_ID_SCHEMA,
+})
+
+const MESSAGING_EVENT_SCHEMA = z.object({
+  message: z.object({
+    attachments: META_ADS_MESSAGE_ATTACHMENT_SCHEMA.extend({
+      payload: META_ADS_MESSAGE_ATTACHMENT_SCHEMA.shape.payload.nullable(),
+    })
+      .array()
+      .optional(),
+    isDeleted: z.boolean().optional(),
+    isEcho: z.boolean().optional(),
+    isUnsupported: z.boolean().optional(),
+    mid: META_ADS_ID_SCHEMA,
+    quickReply: z.object({ payload: z.string() }).optional(),
+    referral: META_ADS_MESSAGE_REFERRAL_SCHEMA.optional(),
+    replyTo: z
+      .object({
+        mid: z.string().optional(),
+        story: z
+          .object({
+            id: z.string(),
+            linkStickerUrl: z.string().optional(),
+            url: z.string().optional(),
+          })
+          .optional(),
+      })
+      .optional(),
+    text: z.string().optional(),
+  }),
+  recipient: z.object({ id: META_ADS_ID_SCHEMA }),
+  sender: z.object({ id: META_ADS_ID_SCHEMA }),
+  timestamp: z.number().int().nonnegative(),
+})
+
 /**
- * Normalizes Meta's Page and ad-account envelopes into stable public events.
+ * Normalizes Meta's Page, Instagram, and ad-account envelopes into stable
+ * public events.
+ *
+ * Classification happens here: only new comments, inbound messages, and
+ * mentions become semantic events. The Page's own comments, Instagram's own
+ * comments and message echoes are dropped, and unsent Instagram messages become
+ * deletion events. Malformed comment, mention, and message items are dropped so
+ * they can't reject a delivery that also carries leads.
  *
  * @param input - Untrusted provider webhook envelope.
  */
@@ -181,38 +429,231 @@ export function normalizeMetaAdsWebhook(
   input: unknown,
 ): NormalizedMetaAdsWebhook {
   const envelope = META_ADS_WEBHOOK_ENVELOPE_SCHEMA.parse(input)
-  const adAccountEvents: z.output<typeof META_ADS_EVENT_SCHEMA>[] = []
-  const leadEvents: z.output<typeof META_ADS_LEAD_CREATED_EVENT_SCHEMA>[] = []
-  for (const entry of envelope.entry) {
-    for (const change of entry.changes) {
-      if (envelope.object === "page" && change.field === "leadgen") {
-        const value = z
-          .object({
-            ad_id: z.string().optional(),
-            adgroup_id: z.string().optional(),
-            created_time: z.number().int().nonnegative(),
-            form_id: z.string(),
-            leadgen_id: z.string(),
-            page_id: z.string(),
-          })
-          .parse(change.value)
-        leadEvents.push({
-          adId: value.ad_id,
-          adgroupId: value.adgroup_id,
-          createdTime: value.created_time,
-          formId: value.form_id,
-          leadgenId: value.leadgen_id,
-          pageId: value.page_id,
-        })
-      } else if (envelope.object === "ad_account") {
-        adAccountEvents.push({
-          accountId: entry.id,
-          field: change.field,
-          occurredAt: entry.time,
-          value: encodableSchema.parse(fromMeta(change.value)),
-        })
-      }
-    }
+  const entries = envelope.entry.map((entry) => ({
+    ...entry,
+    changes: entry.changes ?? [],
+    messaging: entry.messaging ?? [],
+  }))
+  const pageEntries = envelope.object === "page" ? entries : []
+  const instagramEntries = envelope.object === "instagram" ? entries : []
+  return {
+    adAccountEvents:
+      envelope.object === "ad_account"
+        ? entries.flatMap((entry) =>
+            entry.changes.map((change) => ({
+              accountId: entry.id,
+              field: change.field,
+              occurredAt: entry.time,
+              value: encodableSchema.parse(fromMeta(change.value)),
+            })),
+          )
+        : [],
+    instagramCommentEvents: instagramEntries.flatMap((entry) =>
+      entry.changes
+        .filter(({ field }) => field === "comments")
+        .flatMap(({ value }) => parseInstagramComment(entry, value) ?? []),
+    ),
+    instagramMentionEvents: instagramEntries.flatMap((entry) =>
+      entry.changes
+        .filter(({ field }) => field === "mentions")
+        .flatMap(({ value }) => parseInstagramMention(entry, value) ?? []),
+    ),
+    instagramMessageDeletedEvents: instagramEntries.flatMap((entry) =>
+      entry.messaging.flatMap((event) => {
+        const message = parseReceivedMessage(event)
+        if (!message?.isDeleted || message.isEcho) return []
+        return [
+          {
+            instagramAccountId: message.common.recipientId,
+            messageId: message.common.messageId,
+            senderId: message.common.senderId,
+            timestamp: message.common.timestamp,
+          },
+        ]
+      }),
+    ),
+    instagramMessageEvents: instagramEntries.flatMap((entry) =>
+      entry.messaging.flatMap((event) => {
+        const message = parseReceivedMessage(event)
+        if (!message || message.isEcho || message.isDeleted) return []
+        return [
+          {
+            ...message.common,
+            instagramAccountId: message.common.recipientId,
+            isUnsupported: message.isUnsupported,
+            ...(message.replyTo && {
+              replyTo: {
+                messageId: message.replyTo.mid,
+                story: message.replyTo.story,
+              },
+            }),
+          },
+        ]
+      }),
+    ),
+    leadEvents: pageEntries.flatMap((entry) =>
+      entry.changes
+        .filter(({ field }) => field === "leadgen")
+        .map(({ value }) => {
+          const lead = LEADGEN_VALUE_SCHEMA.parse(value)
+          return {
+            adId: lead.ad_id,
+            adgroupId: lead.adgroup_id,
+            createdTime: lead.created_time,
+            formId: lead.form_id,
+            leadgenId: lead.leadgen_id,
+            pageId: lead.page_id,
+          }
+        }),
+    ),
+    messengerMessageEvents: pageEntries.flatMap((entry) =>
+      entry.messaging.flatMap((event) => {
+        const message = parseReceivedMessage(event)
+        if (!message || message.isEcho) return []
+        return [
+          {
+            ...message.common,
+            pageId: entry.id,
+            replyToMessageId: message.replyTo?.mid,
+          },
+        ]
+      }),
+    ),
+    pageCommentEvents: pageEntries.flatMap((entry) =>
+      entry.changes.flatMap(({ field, value }) => {
+        if (
+          field !== "feed" ||
+          !FEED_COMMENT_ADD_SCHEMA.safeParse(value).success
+        )
+          return []
+        const comment = parsePageComment(entry.id, value)
+        return !comment || comment.from?.id === entry.id ? [] : [comment]
+      }),
+    ),
+  }
+}
+
+/**
+ * Normalizes one Page `feed` comment-add change, or returns `undefined` when
+ * the item is malformed so one bad item can't reject a whole delivery.
+ *
+ * Meta documents `created_time` only as a datetime, so both Unix seconds and
+ * ISO strings are accepted. Top-level comments may carry the post ID as
+ * `parent_id`; only a distinct parent identifies a reply.
+ *
+ * @param pageId - Page that owns the feed.
+ * @param input - Raw feed change value.
+ */
+function parsePageComment(
+  pageId: string,
+  input: unknown,
+): z.output<typeof META_ADS_PAGE_COMMENT_CREATED_EVENT_SCHEMA> | undefined {
+  const parsed = FEED_COMMENT_VALUE_SCHEMA.safeParse(fromMeta(input))
+  if (!parsed.success) return undefined
+  const { parentId, ...value } = parsed.data
+  return {
+    ...value,
+    pageId,
+    ...(parentId && parentId !== value.postId && { parentId }),
+  }
+}
+
+/**
+ * Normalizes one Instagram `comments` change, or returns `undefined` when the
+ * item is malformed or the account wrote it.
+ *
+ * Meta's reference schema names the comment `id`, while its Facebook Login
+ * samples name it `comment_id`; both are accepted. The account's own comments
+ * match either the entry ID or the commenter's `self_ig_scoped_id`; dropping
+ * them keeps reply automations from triggering themselves.
+ *
+ * @param entry - Instagram webhook entry.
+ * @param entry.id - Instagram professional account ID.
+ * @param entry.time - Delivery time in Unix seconds.
+ * @param input - Raw comments change value.
+ */
+function parseInstagramComment(
+  entry: { id: string; time: number },
+  input: unknown,
+):
+  | z.output<typeof META_ADS_INSTAGRAM_COMMENT_CREATED_EVENT_SCHEMA>
+  | undefined {
+  const parsed = INSTAGRAM_COMMENT_VALUE_SCHEMA.safeParse(fromMeta(input))
+  if (!parsed.success) return undefined
+  const {
+    commentId,
+    from: { selfIgScopedId, ...from },
+    id,
+    ...value
+  } = parsed.data
+  const resolvedId = id ?? commentId
+  if (!resolvedId || from.id === entry.id || from.id === selfIgScopedId) {
+    return undefined
+  }
+  return {
+    ...value,
+    commentId: resolvedId,
+    from,
+    instagramAccountId: entry.id,
+    occurredAt: entry.time,
+  }
+}
+
+/**
+ * Normalizes one Instagram `mentions` change into a caption or comment mention,
+ * or returns `undefined` when the item is malformed.
+ *
+ * @param entry - Instagram webhook entry.
+ * @param entry.id - Instagram professional account ID.
+ * @param entry.time - Delivery time in Unix seconds.
+ * @param input - Raw mentions change value.
+ */
+function parseInstagramMention(
+  entry: { id: string; time: number },
+  input: unknown,
+):
+  | z.output<typeof META_ADS_INSTAGRAM_MENTION_CREATED_EVENT_SCHEMA>
+  | undefined {
+  const parsed = INSTAGRAM_MENTION_VALUE_SCHEMA.safeParse(fromMeta(input))
+  if (!parsed.success) return undefined
+  return {
+    ...parsed.data,
+    instagramAccountId: entry.id,
+    kind: parsed.data.commentId ? "comment" : "caption",
+    occurredAt: entry.time,
+  }
+}
+
+/**
+ * Parses one Messenger or Instagram `messaging` event that carries a message.
+ *
+ * Returns `undefined` for other event kinds, such as reads, reactions,
+ * postbacks, referrals, and handoff `admin_text` notices without a message ID,
+ * and for malformed messages.
+ *
+ * @param input - Raw messaging event.
+ */
+function parseReceivedMessage(input: unknown) {
+  const parsed = MESSAGING_EVENT_SCHEMA.safeParse(fromMeta(input))
+  if (!parsed.success) return undefined
+  const { message, recipient, sender, timestamp } = parsed.data
+  return {
+    common: {
+      attachments: (message.attachments ?? []).map(({ payload, type }) => ({
+        type,
+        ...(payload && { payload }),
+      })),
+      messageId: message.mid,
+      quickReplyPayload: message.quickReply?.payload,
+      recipientId: recipient.id,
+      referral: message.referral,
+      senderId: sender.id,
+      text: message.text,
+      timestamp,
+    },
+    isDeleted: message.isDeleted === true,
+    isEcho: message.isEcho === true,
+    isUnsupported: message.isUnsupported === true,
+    replyTo: message.replyTo,
   }
-  return { adAccountEvents, leadEvents }
 }

package/src/meta-ads/index.ts

@@ -1,3 +1,4 @@
 export * from "./api"
 export * from "./events"
+export * from "./pages"
 export * from "./schemas"

package/src/meta-ads/pages.ts

@@ -0,0 +1,98 @@
+import * as z from "zod"
+import { getMetaAdsApi, type MetaAdsResolvedAccount } from "./api"
+
+const PAGE_TOKEN_SCHEMA = z.object({ accessToken: z.string().min(1) })
+const LINKED_PAGE_SCHEMA = z
+  .object({
+    accessToken: z.string().min(1),
+    id: z.string(),
+    instagramBusinessAccount: z.object({ id: z.string() }).optional(),
+  })
+  .array()
+
+/**
+ * Creates a Graph client authenticated as one Page.
+ *
+ * Page comment, messaging, conversation, and `subscribed_apps` endpoints need a
+ * Page access token. The token is derived from the connected user token on each
+ * call and never persisted.
+ *
+ * @param account - Resolved Meta Ads OAuth account.
+ * @param pageId - Facebook Page the connected identity manages.
+ */
+export async function getMetaAdsPageApi(
+  account: MetaAdsResolvedAccount,
+  pageId: string,
+) {
+  const { accessToken } = await getMetaAdsApi(account).call(pageId, {
+    query: { fields: ["access_token"] },
+    responseSchema: PAGE_TOKEN_SCHEMA,
+  })
+  return pageClient(accessToken)
+}
+
+/**
+ * Finds the managed Facebook Page linked to one Instagram professional account
+ * and creates a Graph client authenticated as that Page.
+ *
+ * Instagram messaging with Facebook Login sends through the linked Page, and
+ * Instagram webhooks are enabled by installing the app on that Page.
+ *
+ * @param account - Resolved Meta Ads OAuth account.
+ * @param instagramAccountId - Instagram professional account ID.
+ * @throws When no managed Page links to the Instagram account.
+ */
+export async function getMetaAdsInstagramPageApi(
+  account: MetaAdsResolvedAccount,
+  instagramAccountId: string,
+) {
+  const page = await findLinkedPage(account, instagramAccountId)
+  if (!page) {
+    throw new Error(
+      `Instagram account ${instagramAccountId} is not linked to a Facebook Page this Meta Ads account manages.`,
+    )
+  }
+  return { api: pageClient(page.accessToken), pageId: page.id }
+}
+
+/**
+ * Walks the connected identity's Pages until one links to the Instagram
+ * account.
+ *
+ * @param account - Resolved Meta Ads OAuth account.
+ * @param instagramAccountId - Instagram professional account ID.
+ * @param after - Cursor for the next `me/accounts` page.
+ */
+async function findLinkedPage(
+  account: MetaAdsResolvedAccount,
+  instagramAccountId: string,
+  after?: string,
+): Promise<z.output<typeof LINKED_PAGE_SCHEMA>[number] | undefined> {
+  const { items, pageInfo } = await getMetaAdsApi(account).page("me/accounts", {
+    query: {
+      after,
+      fields: ["id", "access_token", "instagram_business_account"],
+      limit: 100,
+    },
+    responseSchema: LINKED_PAGE_SCHEMA,
+  })
+  const page = items.find(
+    ({ instagramBusinessAccount }) =>
+      instagramBusinessAccount?.id === instagramAccountId,
+  )
+  if (page || !pageInfo?.next || !pageInfo.after) return page
+  return findLinkedPage(account, instagramAccountId, pageInfo.after)
+}
+
+/**
+ * Wraps one Page access token in the shared Graph client.
+ *
+ * @param accessToken - Page access token.
+ */
+function pageClient(accessToken: string) {
+  return getMetaAdsApi({
+    connectionMethodId: "oauth",
+    secret: { accessToken, expiresAt: null, tokenType: "bearer" },
+    serviceId: "meta-ads",
+  })
+}