@automate.ax/integration-contracts 0.160.0 → 0.163.0

package/dist/meta-ads/events.js

@@ -86,6 +86,110 @@ export const META_ADS_LEAD_CREATED_EVENT_SCHEMA = z.object({
     leadgenId: META_ADS_ID_SCHEMA,
     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,
@@ -94,6 +198,14 @@ export const META_ADS_LEAD_TRIGGER_CONFIG_SCHEMA = z.object({
     account: z.string().optional(),
     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 const metaAdsTriggerContracts = {
     "meta-ads.ad.effectiveStatusChanged": {
         configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
@@ -131,6 +243,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,
@@ -139,6 +267,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,
@@ -147,47 +279,282 @@ 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,
+    },
 };
+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.
  */
 export function normalizeMetaAdsWebhook(input) {
     const envelope = META_ADS_WEBHOOK_ENVELOPE_SCHEMA.parse(input);
-    const adAccountEvents = [];
-    const leadEvents = [];
-    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, input) {
+    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, input) {
+    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 { adAccountEvents, leadEvents };
+    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, input) {
+    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) {
+    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,
+    };
 }

package/dist/meta-ads/index.d.ts

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

package/dist/meta-ads/index.js

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

package/dist/meta-ads/pages.d.ts

@@ -0,0 +1,34 @@
+import * as z from "zod";
+import { type MetaAdsResolvedAccount } from "./api.js";
+/**
+ * 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 declare function getMetaAdsPageApi(account: MetaAdsResolvedAccount, pageId: string): Promise<{
+    call: <TSchema extends z.ZodType>(path: string, options: import("./api").MetaAdsRequestOptions<TSchema>) => Promise<z.core.output<TSchema>>;
+    page: <TSchema extends z.ZodType>(path: string, options: import("./api").MetaAdsRequestOptions<TSchema>) => Promise<import("./api").MetaAdsPage<z.core.output<TSchema>>>;
+}>;
+/**
+ * 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 declare function getMetaAdsInstagramPageApi(account: MetaAdsResolvedAccount, instagramAccountId: string): Promise<{
+    api: {
+        call: <TSchema extends z.ZodType>(path: string, options: import("./api").MetaAdsRequestOptions<TSchema>) => Promise<z.core.output<TSchema>>;
+        page: <TSchema extends z.ZodType>(path: string, options: import("./api").MetaAdsRequestOptions<TSchema>) => Promise<import("./api").MetaAdsPage<z.core.output<TSchema>>>;
+    };
+    pageId: string;
+}>;

package/dist/meta-ads/pages.js

@@ -0,0 +1,79 @@
+import * as z from "zod";
+import { getMetaAdsApi } from "./api.js";
+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, pageId) {
+    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, instagramAccountId) {
+    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, instagramAccountId, after) {
+    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) {
+    return getMetaAdsApi({
+        connectionMethodId: "oauth",
+        secret: { accessToken, expiresAt: null, tokenType: "bearer" },
+        serviceId: "meta-ads",
+    });
+}