@iann29/rastro 0.9.0 → 0.10.1

package/src/component/metaGraph.ts

@@ -0,0 +1,722 @@
+import { fakeMetaGraph } from "./metaFake.js";
+
+/*
+ * The only module that talks to Meta. Everything else goes through the
+ * `MetaGraph` interface, which `RASTRO_META_FAKE=true` swaps for the
+ * deterministic fixtures in metaFake.ts (the example host, demos, tests).
+ * Tests of the real client stub `fetch`.
+ */
+
+/** The Graph API version every call pins. Bump it here and nowhere else. */
+export const META_GRAPH_VERSION = "v25.0";
+export const META_GRAPH_ORIGIN = "https://graph.facebook.com";
+
+const PAGE_LIMIT = 500;
+const MAX_PIXELS = 200;
+const MAX_PAGES = 40;
+const MAX_ACCOUNTS = 2_000;
+const THUMBNAIL_SIZE = 320;
+const MAX_THUMBNAIL_BYTES = 2_000_000;
+const CONVERSATIONS_ACTION =
+  "onsite_conversion.messaging_conversation_started_7d";
+
+// Every status an ad can have, the two Meta hides by default included: an ad
+// archived or deleted after it spent still has spend, a name and a status.
+const ALL_STATUSES = [
+  "ACTIVE",
+  "PAUSED",
+  "PENDING_REVIEW",
+  "DISAPPROVED",
+  "PREAPPROVED",
+  "PENDING_BILLING_INFO",
+  "CAMPAIGN_PAUSED",
+  "ADSET_PAUSED",
+  "IN_PROCESS",
+  "WITH_ISSUES",
+  "ARCHIVED",
+  "DELETED",
+];
+
+export type MetaCreativeType = "video" | "image" | "carousel" | "other";
+
+export interface GraphAdAccount {
+  adAccountId: string;
+  name: string;
+  currency: string;
+  timezone: string;
+  /** Meta's `account_status`: 1 is active. */
+  accountStatus: number;
+}
+
+export interface GraphPixel {
+  pixelId: string;
+  name: string;
+}
+
+export interface GraphAd {
+  adId: string;
+  name: string | null;
+  effectiveStatus: string | null;
+  adsetId: string | null;
+  adsetName: string | null;
+  campaignId: string | null;
+  campaignName: string | null;
+  creativeType: MetaCreativeType | null;
+  thumbnailUrl: string | null;
+}
+
+/** One ad on one account-local date, spend already in integer cents. */
+export interface GraphSpendRow {
+  adId: string;
+  /** The account-local date, `YYYY-MM-DD`. */
+  date: string;
+  spendCents: number;
+  impressions: number;
+  clicks: number;
+  /** Conversations Meta counted for the ad that day (0 when it lists none). */
+  conversations: number;
+  adName: string | null;
+  adsetId: string | null;
+  adsetName: string | null;
+  campaignId: string | null;
+  campaignName: 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+. */
+  pct: number;
+  /** Meta's own estimate of when a throttled limit lifts, if it gave one. */
+  regainMs: number | null;
+}
+
+/** `app`: Meta refused the app's own id or secret (the host's env). */
+export type MetaErrorKind =
+  "token" | "throttled" | "permission" | "app" | "other";
+
+export class MetaGraphError extends Error {
+  constructor(
+    readonly kind: MetaErrorKind,
+    message: string,
+    readonly code: number | null = null,
+    readonly regainMs: number | null = null,
+  ) {
+    super(message);
+    this.name = "MetaGraphError";
+  }
+}
+
+/** The Meta app Facebook Login for Business authorizes against. */
+export interface MetaApp {
+  appId: string;
+  appSecret: string;
+}
+
+export interface MetaGraph {
+  /**
+   * Trades a Facebook Login for Business authorization code for its access
+   * token, with how long it lives when Meta says (`expires_in`). A refused
+   * code is a `token` error, like an expired token; a refused app id or
+   * secret, an `app` error.
+   */
+  exchangeCode(
+    app: MetaApp,
+    code: string,
+    redirectUri: string,
+  ): Promise<{ accessToken: string; expiresInMs: number | null }>;
+  /**
+   * What Meta knows of a token (`GET /debug_token`, with the app's token):
+   * its kind (`USER`, `SYSTEM_USER`, ...) and when it expires, null for
+   * never. A token not valid for this app is a `token` error.
+   */
+  debugToken(
+    app: MetaApp,
+    token: string,
+  ): Promise<{ type: string | null; expiresAt: number | null }>;
+  /** Trades a short-lived user token for a long-lived one (about 60 days). */
+  exchangeLongLived(
+    app: MetaApp,
+    token: string,
+  ): Promise<{ accessToken: string; expiresInMs: number | null }>;
+  me(token: string): Promise<{ id: string; name: string | null }>;
+  adAccounts(token: string): Promise<GraphAdAccount[]>;
+  /** The pixels (datasets) an ad account owns. */
+  adPixels(token: string, adAccountId: string): Promise<GraphPixel[]>;
+  /**
+   * The account's ads in any status, or only `adIds` among them. `complete`
+   * is false when the listing stopped at the page cap.
+   */
+  ads(
+    token: string,
+    adAccountId: string,
+    adIds?: string[],
+  ): Promise<{ ads: GraphAd[]; usage: GraphUsage; complete: boolean }>;
+  /**
+   * Spend per ad per account-local day, `since`/`until` inclusive, for ads in
+   * any status. `complete` is false when Meta had more pages than the cap:
+   * the rows are then a part of the range, never the whole of it.
+   */
+  insights(
+    token: string,
+    adAccountId: string,
+    since: string,
+    until: string,
+  ): Promise<{ rows: GraphSpendRow[]; usage: GraphUsage; complete: boolean }>;
+  /** Checks the token can reach the pixel (dataset). */
+  pixel(token: string, pixelId: string): Promise<{ id: string }>;
+  /** A creative's thumbnail, or null when it cannot be fetched. */
+  thumbnail(url: string): Promise<Blob | null>;
+  /** Sends server events to the pixel (dataset) through the Conversions API. */
+  conversions(
+    token: string,
+    pixelId: string,
+    payload: ConversionsPayload,
+  ): Promise<{ eventsReceived: number; fbtraceId: string | null }>;
+}
+
+/** One Conversions API event, user data already hashed by the host. */
+export interface ConversionEvent {
+  event_name: string;
+  event_time: number;
+  event_id: string;
+  action_source: "chat";
+  user_data: { ph?: string[]; external_id?: string[]; country: string[] };
+  custom_data?: { value: number; currency: string };
+}
+
+export interface ConversionsPayload {
+  data: ConversionEvent[];
+  test_event_code?: string;
+}
+
+type Json = Record<string, unknown>;
+type Fetch = typeof fetch;
+
+const isRecord = (value: unknown): value is Json =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value: unknown): string | null =>
+  typeof value === "string" && value.length > 0 ? value : null;
+const count = (value: unknown): number => {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : 0;
+};
+
+/** Meta's `expires_in` (seconds) in milliseconds; null when absent or 0. */
+function expiresInMs(value: unknown): number | null {
+  const seconds = Number(value);
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : null;
+}
+
+/** Meta's spend is a decimal string in the account currency. */
+export function spendToCents(value: unknown): number {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed * 100) : 0;
+}
+
+/** The kind of a Graph error body, by Meta's documented codes. */
+export function classifyGraphError(error: Json): MetaErrorKind {
+  const code = typeof error.code === "number" ? error.code : null;
+  if (code === 190 || code === 102 || code === 463 || code === 467) {
+    return "token";
+  }
+  if (
+    code === 4 ||
+    code === 17 ||
+    code === 32 ||
+    code === 613 ||
+    (code !== null && code >= 80000 && code <= 80014)
+  ) {
+    return "throttled";
+  }
+  // 100/33: the object does not exist or the token cannot see it.
+  if (
+    code === 10 ||
+    (code !== null && code >= 200 && code <= 299) ||
+    (code === 100 && error.error_subcode === 33)
+  ) {
+    return "permission";
+  }
+  return "other";
+}
+
+function parseJsonHeader(value: string | null): unknown {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+/** Reads the three usage headers Meta sends on Marketing API calls. */
+export function readUsage(headers: Headers): GraphUsage {
+  let pct = 0;
+  let regainMinutes = 0;
+  const bump = (value: unknown) => {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (Number.isFinite(parsed)) pct = Math.max(pct, parsed);
+  };
+  const business = parseJsonHeader(headers.get("x-business-use-case-usage"));
+  if (isRecord(business)) {
+    for (const entries of Object.values(business)) {
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        if (!isRecord(entry)) continue;
+        bump(entry.call_count);
+        bump(entry.total_cputime);
+        bump(entry.total_time);
+        const regain = Number(entry.estimated_time_to_regain_access);
+        if (Number.isFinite(regain)) {
+          regainMinutes = Math.max(regainMinutes, regain);
+        }
+      }
+    }
+  }
+  const account = parseJsonHeader(headers.get("x-ad-account-usage"));
+  if (isRecord(account)) bump(account.acc_id_util_pct);
+  const insights = parseJsonHeader(headers.get("x-fb-ads-insights-throttle"));
+  if (isRecord(insights)) {
+    bump(insights.app_id_util_pct);
+    bump(insights.acc_id_util_pct);
+  }
+  return {
+    pct,
+    regainMs: regainMinutes > 0 ? regainMinutes * 60_000 : null,
+  };
+}
+
+const mergeUsage = (left: GraphUsage, right: GraphUsage): GraphUsage => ({
+  pct: Math.max(left.pct, right.pct),
+  regainMs:
+    left.regainMs === null
+      ? right.regainMs
+      : right.regainMs === null
+        ? left.regainMs
+        : Math.max(left.regainMs, right.regainMs),
+});
+
+const NO_USAGE: GraphUsage = { pct: 0, regainMs: null };
+
+/** What Meta calls the creative, reduced to the four kinds the screens use. */
+export function creativeTypeOf(creative: unknown): MetaCreativeType | null {
+  if (!isRecord(creative)) return null;
+  const story = isRecord(creative.object_story_spec)
+    ? creative.object_story_spec
+    : {};
+  const link = isRecord(story.link_data) ? story.link_data : {};
+  if (Array.isArray(link.child_attachments) && link.child_attachments.length) {
+    return "carousel";
+  }
+  const objectType = text(creative.object_type)?.toUpperCase();
+  if (
+    objectType === "VIDEO" ||
+    text(creative.video_id) ||
+    isRecord(story.video_data)
+  ) {
+    return "video";
+  }
+  if (objectType === "PHOTO" || objectType === "SHARE" || link.picture) {
+    return "image";
+  }
+  return "other";
+}
+
+function toAd(raw: unknown): GraphAd | null {
+  if (!isRecord(raw)) return null;
+  const adId = text(raw.id);
+  if (!adId) return null;
+  const adset = isRecord(raw.adset) ? raw.adset : {};
+  const campaign = isRecord(raw.campaign) ? raw.campaign : {};
+  const creative = isRecord(raw.creative) ? raw.creative : null;
+  return {
+    adId,
+    name: text(raw.name),
+    effectiveStatus: text(raw.effective_status),
+    adsetId: text(adset.id) ?? text(raw.adset_id),
+    adsetName: text(adset.name),
+    campaignId: text(campaign.id) ?? text(raw.campaign_id),
+    campaignName: text(campaign.name),
+    creativeType: creativeTypeOf(creative),
+    thumbnailUrl: creative ? text(creative.thumbnail_url) : null,
+  };
+}
+
+function toSpendRow(raw: unknown): GraphSpendRow | null {
+  if (!isRecord(raw)) return null;
+  const adId = text(raw.ad_id);
+  const date = text(raw.date_start);
+  if (!adId || !date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  let conversations = 0;
+  if (Array.isArray(raw.actions)) {
+    for (const action of raw.actions) {
+      if (isRecord(action) && action.action_type === CONVERSATIONS_ACTION) {
+        conversations = count(action.value);
+      }
+    }
+  }
+  return {
+    adId,
+    date,
+    spendCents: spendToCents(raw.spend),
+    impressions: count(raw.impressions),
+    clicks: count(raw.clicks),
+    conversations,
+    adName: text(raw.ad_name),
+    adsetId: text(raw.adset_id),
+    adsetName: text(raw.adset_name),
+    campaignId: text(raw.campaign_id),
+    campaignName: text(raw.campaign_name),
+  };
+}
+
+const AD_FIELDS = [
+  "id",
+  "name",
+  "effective_status",
+  "adset{id,name}",
+  "campaign{id,name}",
+  "creative{thumbnail_url,object_type,video_id,object_story_spec{link_data{picture,child_attachments{link}},video_data{video_id}}}",
+].join(",");
+
+const INSIGHT_FIELDS = [
+  "date_start",
+  "ad_id",
+  "ad_name",
+  "adset_id",
+  "adset_name",
+  "campaign_id",
+  "campaign_name",
+  "spend",
+  "impressions",
+  "clicks",
+  "actions",
+].join(",");
+
+/** An `act_…` id as Meta names it, whatever form the host stored. */
+export function actId(adAccountId: string): string {
+  return adAccountId.startsWith("act_") ? adAccountId : `act_${adAccountId}`;
+}
+
+function realMetaGraph(fetchImpl: Fetch): MetaGraph {
+  const url = (path: string, params: Record<string, string>) => {
+    const target = new URL(
+      `${META_GRAPH_ORIGIN}/${META_GRAPH_VERSION}/${path}`,
+    );
+    for (const [key, value] of Object.entries(params)) {
+      target.searchParams.set(key, value);
+    }
+    return target.toString();
+  };
+
+  // The token rides in the Authorization header, never in a URL that could
+  // end up in a log.
+  async function call(target: string, token: string, payload?: unknown) {
+    const parsed = new URL(target);
+    if (parsed.origin !== META_GRAPH_ORIGIN) {
+      throw new MetaGraphError("other", "Meta returned a foreign paging URL");
+    }
+    parsed.searchParams.delete("access_token");
+    let response: Response;
+    try {
+      response = await fetchImpl(
+        parsed.toString(),
+        payload === undefined
+          ? { headers: { Authorization: `Bearer ${token}` } }
+          : {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify(payload),
+            },
+      );
+    } catch {
+      throw new MetaGraphError("other", "Meta Graph API unreachable");
+    }
+    const usage = readUsage(response.headers);
+    let body: unknown = null;
+    try {
+      body = await response.json();
+    } catch {
+      body = null;
+    }
+    if (!response.ok || (isRecord(body) && isRecord(body.error))) {
+      const error = isRecord(body) && isRecord(body.error) ? body.error : {};
+      const kind = classifyGraphError(error);
+      const message =
+        text(error.message) ?? `Meta Graph API answered ${response.status}`;
+      throw new MetaGraphError(
+        kind,
+        message.slice(0, 300),
+        typeof error.code === "number" ? error.code : null,
+        usage.regainMs,
+      );
+    }
+    return { body: isRecord(body) ? body : {}, usage };
+  }
+
+  // The two token exchanges, the only calls that carry the app secret, and
+  // the code or the short-lived token: a POST with a form body, so none of
+  // it sits in a URL a proxy could log. Never echoed back in an error.
+  async function oauth(params: Record<string, string>): Promise<Json> {
+    let response: Response;
+    try {
+      response = await fetchImpl(url("oauth/access_token", {}), {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params).toString(),
+      });
+    } catch {
+      throw new MetaGraphError("other", "Meta Graph API unreachable");
+    }
+    let body: unknown = null;
+    try {
+      body = await response.json();
+    } catch {
+      body = null;
+    }
+    const error = isRecord(body) && isRecord(body.error) ? body.error : null;
+    if (!response.ok || error) {
+      const code = typeof error?.code === "number" ? error.code : null;
+      const kind =
+        // 1 and 101: the client secret or the app id is wrong (the env).
+        code === 1 || code === 101
+          ? "app"
+          : error
+            ? classifyGraphError(error)
+            : "other";
+      // An OAuth failure on a code or a token (used, expired, another
+      // redirect) is the caller's to fix by logging in again.
+      throw new MetaGraphError(
+        kind === "other" && error?.type === "OAuthException" ? "token" : kind,
+        (text(error?.message) ?? `Meta answered ${response.status}`).slice(
+          0,
+          300,
+        ),
+        typeof error?.code === "number" ? error.code : null,
+      );
+    }
+    return isRecord(body) ? body : {};
+  }
+
+  async function pages<T>(
+    first: string,
+    token: string,
+    map: (raw: unknown) => T | null,
+    cap: number,
+  ) {
+    const items: T[] = [];
+    let usage = NO_USAGE;
+    let next: string | null = first;
+    for (
+      let page = 0;
+      next && page < MAX_PAGES && items.length <= cap;
+      page++
+    ) {
+      const result = await call(next, token);
+      usage = mergeUsage(usage, result.usage);
+      const data = Array.isArray(result.body.data) ? result.body.data : [];
+      for (const raw of data) {
+        const item = map(raw);
+        if (item) items.push(item);
+      }
+      const paging = isRecord(result.body.paging) ? result.body.paging : {};
+      next = text(paging.next);
+    }
+    // Stopped with a next page or over the cap: a part, not the whole.
+    return {
+      items: items.slice(0, cap),
+      usage,
+      complete: next === null && items.length <= cap,
+    };
+  }
+
+  return {
+    async exchangeCode(app, code, redirectUri) {
+      const body = await oauth({
+        client_id: app.appId,
+        client_secret: app.appSecret,
+        redirect_uri: redirectUri,
+        code,
+      });
+      const accessToken = text(body.access_token);
+      if (!accessToken) {
+        throw new MetaGraphError("token", "Meta returned no access token");
+      }
+      return { accessToken, expiresInMs: expiresInMs(body.expires_in) };
+    },
+
+    async debugToken(app, token) {
+      // The app's own token authorizes the inspection, in the header like
+      // any other; Meta takes the inspected token only in the query.
+      const { body } = await call(
+        url("debug_token", { input_token: token }),
+        `${app.appId}|${app.appSecret}`,
+      );
+      const data = isRecord(body.data) ? body.data : {};
+      if (data.is_valid === false || String(data.app_id ?? "") !== app.appId) {
+        throw new MetaGraphError(
+          "token",
+          "Meta says the token is not valid for this app",
+        );
+      }
+      const expiresAt = Number(data.expires_at);
+      return {
+        type: text(data.type),
+        // 0 (or nothing) is Meta's "never expires".
+        expiresAt:
+          Number.isFinite(expiresAt) && expiresAt > 0 ? expiresAt * 1000 : null,
+      };
+    },
+
+    async exchangeLongLived(app, token) {
+      const body = await oauth({
+        grant_type: "fb_exchange_token",
+        client_id: app.appId,
+        client_secret: app.appSecret,
+        fb_exchange_token: token,
+      });
+      const accessToken = text(body.access_token);
+      if (!accessToken) {
+        throw new MetaGraphError("token", "Meta returned no access token");
+      }
+      return { accessToken, expiresInMs: expiresInMs(body.expires_in) };
+    },
+
+    async me(token) {
+      const { body } = await call(url("me", { fields: "id,name" }), token);
+      const id = text(body.id);
+      if (!id) throw new MetaGraphError("token", "Meta did not name the token");
+      return { id, name: text(body.name) };
+    },
+
+    async adAccounts(token) {
+      const { items } = await pages(
+        url("me/adaccounts", {
+          fields: "id,name,currency,timezone_name,account_status",
+          limit: String(PAGE_LIMIT),
+        }),
+        token,
+        (raw) => {
+          if (!isRecord(raw)) return null;
+          const adAccountId = text(raw.id);
+          if (!adAccountId) return null;
+          return {
+            adAccountId: actId(adAccountId),
+            name: text(raw.name) ?? adAccountId,
+            currency: text(raw.currency)?.toUpperCase() ?? "USD",
+            timezone: text(raw.timezone_name) ?? "UTC",
+            accountStatus: count(raw.account_status),
+          };
+        },
+        MAX_ACCOUNTS,
+      );
+      return items;
+    },
+
+    async adPixels(token, adAccountId) {
+      const { items } = await pages(
+        url(`${actId(adAccountId)}/adspixels`, {
+          fields: "id,name",
+          limit: String(PAGE_LIMIT),
+        }),
+        token,
+        (raw) => {
+          if (!isRecord(raw)) return null;
+          const pixelId = text(raw.id);
+          if (!pixelId) return null;
+          return { pixelId, name: text(raw.name) ?? pixelId };
+        },
+        MAX_PIXELS,
+      );
+      return items;
+    },
+
+    async ads(token, adAccountId, adIds) {
+      const filtering = [
+        ...(adIds ? [{ field: "id", operator: "IN", value: adIds }] : []),
+        { field: "effective_status", operator: "IN", value: ALL_STATUSES },
+      ];
+      const { items, usage, complete } = await pages(
+        url(`${actId(adAccountId)}/ads`, {
+          fields: AD_FIELDS,
+          filtering: JSON.stringify(filtering),
+          thumbnail_width: String(THUMBNAIL_SIZE),
+          thumbnail_height: String(THUMBNAIL_SIZE),
+          limit: String(adIds ? Math.max(adIds.length, 1) : PAGE_LIMIT),
+        }),
+        token,
+        toAd,
+        adIds ? adIds.length : PAGE_LIMIT * MAX_PAGES,
+      );
+      return { ads: items, usage, complete };
+    },
+
+    async insights(token, adAccountId, since, until) {
+      const { items, usage, complete } = await pages(
+        url(`${actId(adAccountId)}/insights`, {
+          level: "ad",
+          time_increment: "1",
+          time_range: JSON.stringify({ since, until }),
+          fields: INSIGHT_FIELDS,
+          // Insights leave archived and deleted ads out unless asked.
+          filtering: JSON.stringify([
+            {
+              field: "ad.effective_status",
+              operator: "IN",
+              value: ALL_STATUSES,
+            },
+          ]),
+          limit: String(PAGE_LIMIT),
+        }),
+        token,
+        toSpendRow,
+        PAGE_LIMIT * MAX_PAGES,
+      );
+      return { rows: items, usage, complete };
+    },
+
+    async pixel(token, pixelId) {
+      const { body } = await call(url(pixelId, { fields: "id" }), token);
+      const id = text(body.id);
+      if (!id) throw new MetaGraphError("permission", "pixel not reachable");
+      return { id };
+    },
+
+    async thumbnail(target) {
+      let parsed: URL;
+      try {
+        parsed = new URL(target);
+      } catch {
+        return null;
+      }
+      if (parsed.protocol !== "https:") return null;
+      try {
+        const response = await fetchImpl(parsed.toString());
+        const type = response.headers.get("content-type") ?? "";
+        if (!response.ok || !type.startsWith("image/")) return null;
+        const blob = await response.blob();
+        return blob.size > 0 && blob.size <= MAX_THUMBNAIL_BYTES ? blob : null;
+      } catch {
+        return null;
+      }
+    },
+
+    async conversions(token, pixelId, payload) {
+      const { body } = await call(url(`${pixelId}/events`, {}), token, payload);
+      return {
+        eventsReceived: count(body.events_received),
+        fbtraceId: text(body.fbtrace_id),
+      };
+    },
+  };
+}
+
+/** The Graph client for this deployment: the fake under RASTRO_META_FAKE. */
+export function metaGraph(
+  options: { fake?: boolean; fetch?: Fetch } = {},
+): MetaGraph {
+  if (options.fake) return fakeMetaGraph();
+  return realMetaGraph(options.fetch ?? ((...args) => fetch(...args)));
+}