@iann29/rastro 0.10.9 → 0.11.0

package/src/component/metaGraph.ts

@@ -82,6 +82,52 @@ export interface GraphSpendRow {
   campaignName: string | null;
 }
 
+/** A Facebook Page the token can act for, with the Page's own token. */
+export interface GraphPage {
+  pageId: string;
+  name: string;
+  /** The Page token Meta hands out with `me/accounts`; null when it did not. */
+  accessToken: string | null;
+  tasks: string[];
+}
+
+/** One question of an instant form. */
+export interface GraphFormQuestion {
+  key: string;
+  label: string;
+  type: string;
+  options?: Array<{ key: string; value: string }>;
+}
+
+export interface GraphForm {
+  formId: string;
+  name: string;
+  status: string;
+  questions: GraphFormQuestion[];
+  /** The end screen's WhatsApp button; null when Meta does not say. */
+  whatsappButton: boolean | null;
+  createdTime: number | null;
+}
+
+/** A form lead as Meta returns it. `fields` carries personal data. */
+export interface GraphLead {
+  leadgenId: string;
+  createdTime: number;
+  formId: string | null;
+  adId: string | null;
+  adsetId: string | null;
+  campaignId: string | null;
+  platform: string | null;
+  isOrganic: boolean;
+  fields: Array<{ name: string; values: string[] }>;
+}
+
+/**
+ * Which Pages a login may read leads from (`leads_retrieval`): every Page it
+ * reaches (`all`), or only `pageIds`. Null when Meta did not say.
+ */
+export type GraphLeadAccess = { all: boolean; pageIds: string[] } | null;
+
 /** How close the app is to Meta's rate limits, from the response headers. */
 export interface GraphUsage {
   /** The highest percentage any limit header reported, 0–100+. */
@@ -182,6 +228,37 @@ export interface MetaGraph {
     pixelId: string,
     payload: ConversionsPayload,
   ): Promise<{ eventsReceived: number; fbtraceId: string | null }>;
+  /**
+   * The Pages the token acts for (`me/accounts`), each with its own token.
+   * `complete` is false when the listing stopped at the page cap.
+   */
+  pages(token: string): Promise<{ pages: GraphPage[]; complete: boolean }>;
+  /**
+   * Which Pages the login may read leads from: `debug_token`'s granular
+   * scopes with `app`, else `me/permissions`. Null when Meta did not say.
+   */
+  leadAccess(token: string, app?: MetaApp | null): Promise<GraphLeadAccess>;
+  /** Subscribes the app to the Page's `leadgen` webhook (the Page token). */
+  subscribePage(pageToken: string, pageId: string): Promise<void>;
+  /** The Page's instant forms, every status. */
+  leadForms(
+    pageToken: string,
+    pageId: string,
+  ): Promise<{ forms: GraphForm[]; usage: GraphUsage; complete: boolean }>;
+  /** One lead, with its answers (personal data: never store `fields`). */
+  lead(pageToken: string, leadgenId: string): Promise<GraphLead>;
+  /**
+   * A form's leads created after `sinceSec` and, with `untilSec`, before it
+   * (Meta's seconds). Meta lists the newest first, so a listing that stopped
+   * at the cap (`complete: false`) holds the newest of the window: read a
+   * narrower window instead of trusting it to cover the older ones.
+   */
+  formLeads(
+    pageToken: string,
+    formId: string,
+    sinceSec: number,
+    untilSec?: number,
+  ): Promise<{ leads: GraphLead[]; usage: GraphUsage; complete: boolean }>;
 }
 
 /** One Conversions API event, user data already hashed by the host. */
@@ -427,6 +504,124 @@ function mapAccount(raw: unknown): GraphAdAccount | null {
   };
 }
 
+/** Meta's times (`2026-10-09T12:34:56+0000`) in milliseconds, or null. */
+export function graphTime(value: unknown): number | null {
+  const raw = text(value);
+  if (!raw) return null;
+  const parsed = Date.parse(raw.replace(/([+-]\d{2})(\d{2})$/u, "$1:$2"));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+const GRAPH_ID = /^\d{1,32}$/u;
+
+function mapPage(raw: unknown): GraphPage | null {
+  if (!isRecord(raw)) return null;
+  const pageId = text(raw.id);
+  if (!pageId || !GRAPH_ID.test(pageId)) return null;
+  return {
+    pageId,
+    name: text(raw.name) ?? pageId,
+    accessToken: text(raw.access_token),
+    tasks: Array.isArray(raw.tasks)
+      ? raw.tasks.filter((task): task is string => typeof task === "string")
+      : [],
+  };
+}
+
+function mapQuestion(raw: unknown): GraphFormQuestion | null {
+  if (!isRecord(raw)) return null;
+  const key = text(raw.key);
+  if (!key) return null;
+  const options = Array.isArray(raw.options)
+    ? raw.options.flatMap((option) => {
+        if (!isRecord(option)) return [];
+        const optionKey = text(option.key) ?? text(option.value);
+        const value = text(option.value) ?? optionKey;
+        return optionKey && value ? [{ key: optionKey, value }] : [];
+      })
+    : [];
+  return {
+    key,
+    label: text(raw.label) ?? key,
+    type: text(raw.type) ?? "CUSTOM",
+    ...(options.length > 0 ? { options } : {}),
+  };
+}
+
+/**
+ * Whether the form's end screen sends the lead to WhatsApp, from its button
+ * type; null when Meta does not describe the end screen's button.
+ */
+export function whatsappButtonOf(thankYouPage: unknown): boolean | null {
+  if (!isRecord(thankYouPage)) return null;
+  const type = text(thankYouPage.button_type);
+  if (!type) return null;
+  return /WHATSAPP/iu.test(type);
+}
+
+function mapForm(raw: unknown): GraphForm | null {
+  if (!isRecord(raw)) return null;
+  const formId = text(raw.id);
+  if (!formId || !GRAPH_ID.test(formId)) return null;
+  return {
+    formId,
+    name: text(raw.name) ?? formId,
+    status: text(raw.status)?.toUpperCase() ?? "ACTIVE",
+    questions: Array.isArray(raw.questions)
+      ? raw.questions.flatMap((question) => {
+          const mapped = mapQuestion(question);
+          return mapped ? [mapped] : [];
+        })
+      : [],
+    whatsappButton: whatsappButtonOf(raw.thank_you_page),
+    createdTime: graphTime(raw.created_time),
+  };
+}
+
+function mapLead(raw: unknown): GraphLead | null {
+  if (!isRecord(raw)) return null;
+  const leadgenId = text(raw.id);
+  const createdTime = graphTime(raw.created_time);
+  if (!leadgenId || !GRAPH_ID.test(leadgenId) || createdTime === null) {
+    return null;
+  }
+  const id = (value: unknown) => {
+    const found = text(typeof value === "number" ? String(value) : value);
+    return found && GRAPH_ID.test(found) ? found : null;
+  };
+  return {
+    leadgenId,
+    createdTime,
+    formId: id(raw.form_id),
+    adId: id(raw.ad_id),
+    adsetId: id(raw.adset_id),
+    campaignId: id(raw.campaign_id),
+    platform: text(raw.platform)?.slice(0, 16) ?? null,
+    isOrganic: raw.is_organic === true,
+    fields: Array.isArray(raw.field_data)
+      ? raw.field_data.flatMap((field) => {
+          if (!isRecord(field)) return [];
+          const name = text(field.name);
+          if (!name) return [];
+          const values = Array.isArray(field.values)
+            ? field.values.filter(
+                (value): value is string => typeof value === "string",
+              )
+            : [];
+          return [{ name, values }];
+        })
+      : [],
+  };
+}
+
+const FORM_FIELDS =
+  "id,name,status,questions,thank_you_page{button_type},created_time";
+const LEAD_FIELDS =
+  "id,created_time,field_data,ad_id,adset_id,campaign_id,form_id,platform,is_organic";
+const MAX_GRAPH_PAGES = 200;
+const MAX_FORMS = 500;
+const MAX_FORM_LEADS = 2_000;
+
 export function actId(adAccountId: string): string {
   return adAccountId.startsWith("act_") ? adAccountId : `act_${adAccountId}`;
 }
@@ -908,6 +1103,138 @@ function realMetaGraph(fetchImpl: Fetch): MetaGraph {
         fbtraceId: text(body.fbtrace_id),
       };
     },
+
+    async pages(token) {
+      const { items, complete } = await pages(
+        url("me/accounts", {
+          fields: "id,name,access_token,tasks",
+          limit: "100",
+        }),
+        token,
+        mapPage,
+        MAX_GRAPH_PAGES,
+      );
+      return { pages: items, complete };
+    },
+
+    async leadAccess(token, app) {
+      // A login's granular scopes say which Pages `leads_retrieval` covers;
+      // without the app's token, the token's own permissions say whether
+      // it has it at all.
+      if (app) {
+        try {
+          const { body } = await call(
+            url("debug_token", { input_token: token }),
+            `${app.appId}|${app.appSecret}`,
+          );
+          const data = isRecord(body.data) ? body.data : {};
+          const granular = Array.isArray(data.granular_scopes)
+            ? data.granular_scopes.filter(isRecord)
+            : [];
+          const leads = granular.find(
+            (scope) => scope.scope === "leads_retrieval",
+          );
+          if (leads) {
+            const targets = Array.isArray(leads.target_ids)
+              ? leads.target_ids.map(String).filter((id) => GRAPH_ID.test(id))
+              : null;
+            return targets === null || targets.length === 0
+              ? { all: true, pageIds: [] }
+              : { all: false, pageIds: targets };
+          }
+          const scopes = Array.isArray(data.scopes) ? data.scopes : null;
+          if (scopes) {
+            return { all: scopes.includes("leads_retrieval"), pageIds: [] };
+          }
+        } catch (error) {
+          if (!(error instanceof MetaGraphError)) throw error;
+        }
+      }
+      try {
+        const { body } = await call(url("me/permissions", {}), token);
+        const rows = Array.isArray(body.data) ? body.data.filter(isRecord) : [];
+        if (rows.length === 0) return null;
+        return {
+          all: rows.some(
+            (row) =>
+              row.permission === "leads_retrieval" && row.status === "granted",
+          ),
+          pageIds: [],
+        };
+      } catch (error) {
+        if (error instanceof MetaGraphError) return null;
+        throw error;
+      }
+    },
+
+    async subscribePage(pageToken, pageId) {
+      const { body } = await call(
+        url(`${pageId}/subscribed_apps`, { subscribed_fields: "leadgen" }),
+        pageToken,
+        { subscribed_fields: "leadgen" },
+      );
+      // A 200 is not enough: Meta says `success: true` when it subscribed.
+      if (body.success !== true) {
+        throw new MetaGraphError(
+          "other",
+          "Meta did not confirm the Page's leadgen subscription",
+        );
+      }
+    },
+
+    async leadForms(pageToken, pageId) {
+      const { items, usage, complete } = await pages(
+        url(`${pageId}/leadgen_forms`, {
+          fields: FORM_FIELDS,
+          limit: "100",
+        }),
+        pageToken,
+        mapForm,
+        MAX_FORMS,
+      );
+      return { forms: items, usage, complete };
+    },
+
+    async lead(pageToken, leadgenId) {
+      const { body } = await call(
+        url(leadgenId, { fields: LEAD_FIELDS }),
+        pageToken,
+      );
+      const lead = mapLead(body);
+      if (!lead) {
+        throw new MetaGraphError("other", "Meta returned an unreadable lead");
+      }
+      return lead;
+    },
+
+    async formLeads(pageToken, formId, sinceSec, untilSec) {
+      const { items, usage, complete } = await pages(
+        url(`${formId}/leads`, {
+          fields: LEAD_FIELDS,
+          filtering: JSON.stringify([
+            {
+              field: "time_created",
+              operator: "GREATER_THAN",
+              value: Math.max(Math.floor(sinceSec), 0),
+            },
+            ...(untilSec === undefined
+              ? []
+              : [
+                  {
+                    field: "time_created",
+                    operator: "LESS_THAN",
+                    value: Math.max(Math.floor(untilSec), 0),
+                  },
+                ]),
+          ]),
+          limit: String(PAGE_LIMIT),
+        }),
+        pageToken,
+        mapLead,
+        MAX_FORM_LEADS,
+      );
+      return { leads: items, usage, complete };
+    },
   };
 }