@automate.ax/integration-contracts 0.139.1 → 0.141.0

package/src/meta-ads/api.ts

@@ -0,0 +1,327 @@
+import type { Encodable } from "@automate.ax/codec"
+import * as z from "zod"
+import { META_ADS_PAGE_INFO_SCHEMA } from "./schemas"
+
+export const META_ADS_GRAPH_API_VERSION = "v26.0"
+const META_ADS_API_BASE_URL = `https://graph.facebook.com/${META_ADS_GRAPH_API_VERSION}/`
+const META_ADS_API_ORIGIN = new URL(META_ADS_API_BASE_URL).origin
+export const META_ADS_OAUTH_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+  expiresAt: z.number().nullable(),
+  tokenType: z.string(),
+})
+const META_ERROR_SCHEMA = z.looseObject({
+  code: z.number().optional(),
+  errorSubcode: z.number().optional(),
+  errorUserMessage: z.string().optional(),
+  fbtraceId: z.string().optional(),
+  isTransient: z.boolean().optional(),
+  message: z.string(),
+  type: z.string().optional(),
+})
+const ERROR_ENVELOPE_SCHEMA = z.looseObject({ error: META_ERROR_SCHEMA })
+const PAGE_SCHEMA = z.looseObject({
+  data: z.unknown(),
+  paging: z
+    .looseObject({
+      cursors: z
+        .looseObject({
+          after: z.string().optional(),
+          before: z.string().optional(),
+        })
+        .optional(),
+      next: z.string().optional(),
+      previous: z.string().optional(),
+    })
+    .optional(),
+})
+
+/** Query values serialized by the shared Graph client. */
+type QueryValue = boolean | number | string | string[] | undefined
+
+export interface MetaAdsResolvedAccount {
+  connectionMethodId: string
+  secret: Record<string, unknown>
+  serviceId: "meta-ads"
+}
+
+export interface MetaAdsRequestOptions<TSchema extends z.ZodType> {
+  body?: Encodable
+  method?: "DELETE" | "GET" | "PATCH" | "POST"
+  query?: Record<string, QueryValue>
+  responseSchema: TSchema
+}
+
+export interface MetaAdsPage<T> {
+  items: T
+  pageInfo?: z.output<typeof META_ADS_PAGE_INFO_SCHEMA>
+}
+
+/** Structured Graph API failure with Meta quota and trace diagnostics. */
+export class MetaAdsApiError extends Error {
+  readonly appUsage?: string
+  readonly businessUseCaseUsage?: string
+  readonly code?: number
+  readonly fbtraceId?: string
+  readonly isTransient: boolean
+  readonly adAccountUsage?: string
+  readonly errorSubcode?: number
+  readonly retryAfter?: number
+  readonly status: number
+
+  /**
+   * Creates a structured Meta Ads failure.
+   *
+   * @param options - Transport, provider, and quota details.
+   * @param options.adAccountUsage - Raw ad-account usage header.
+   * @param options.appUsage - Raw app usage header.
+   * @param options.businessUseCaseUsage - Raw business-use-case usage header.
+   * @param options.error - Parsed provider error.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP response status.
+   */
+  constructor(options: {
+    adAccountUsage?: string
+    appUsage?: string
+    businessUseCaseUsage?: string
+    error?: z.output<typeof META_ERROR_SCHEMA>
+    retryAfter?: number
+    status: number
+  }) {
+    const providerError = options.error
+    super(
+      providerError?.message
+        ? `Meta Ads API error (${providerError.code ?? options.status}): ${providerError.message}`
+        : `Meta Ads API request failed with status ${options.status}.`,
+    )
+    this.name = "MetaAdsApiError"
+    this.adAccountUsage = options.adAccountUsage
+    this.appUsage = options.appUsage
+    this.businessUseCaseUsage = options.businessUseCaseUsage
+    this.code = providerError?.code
+    this.errorSubcode = providerError?.errorSubcode
+    this.fbtraceId = providerError?.fbtraceId
+    this.isTransient = providerError?.isTransient ?? false
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates the authenticated Graph API helper used by packaged and custom
+ * actions.
+ *
+ * @param account - Resolved Meta Ads OAuth account.
+ * @throws When the connection method or stored credential is invalid.
+ */
+export function getMetaAdsApi(account: MetaAdsResolvedAccount) {
+  if (account.connectionMethodId !== "oauth") {
+    throw new Error(
+      `Unsupported Meta Ads connection method: ${account.connectionMethodId}`,
+    )
+  }
+  const { accessToken } = META_ADS_OAUTH_SECRET_SCHEMA.parse(account.secret)
+
+  /**
+   * Calls one Graph endpoint and validates its normalized result.
+   *
+   * @param path - Path relative to the pinned Graph root.
+   * @param options - Request options and response schema.
+   */
+  async function call<TSchema extends z.ZodType>(
+    path: string,
+    options: MetaAdsRequestOptions<TSchema>,
+  ): Promise<z.output<TSchema>> {
+    return options.responseSchema.parse(
+      fromMeta(await rawRequest(path, options)),
+    )
+  }
+
+  /**
+   * Calls one Graph edge and preserves cursor metadata.
+   *
+   * @param path - Path relative to the pinned Graph root.
+   * @param options - Request options and item schema.
+   */
+  async function page<TSchema extends z.ZodType>(
+    path: string,
+    options: MetaAdsRequestOptions<TSchema>,
+  ): Promise<MetaAdsPage<z.output<TSchema>>> {
+    const parsed = PAGE_SCHEMA.parse(await rawRequest(path, options))
+    const paging = parsed.paging
+    return {
+      items: options.responseSchema.parse(fromMeta(parsed.data)),
+      ...(paging && {
+        pageInfo: META_ADS_PAGE_INFO_SCHEMA.parse({
+          after: paging.cursors?.after,
+          before: paging.cursors?.before,
+          next: paging.next,
+          previous: paging.previous,
+        }),
+      }),
+    }
+  }
+
+  /**
+   * Executes one authenticated request and returns its raw JSON value.
+   *
+   * @param path - Path relative to the pinned Graph root.
+   * @param options - Request method, query, and body.
+   */
+  async function rawRequest<TSchema extends z.ZodType>(
+    path: string,
+    options: MetaAdsRequestOptions<TSchema>,
+  ) {
+    const url = new URL(path.replace(/^\/+/, ""), META_ADS_API_BASE_URL)
+    if (
+      url.origin !== META_ADS_API_ORIGIN ||
+      !url.pathname.startsWith(`/${META_ADS_GRAPH_API_VERSION}/`)
+    ) {
+      throw new Error(
+        `Meta Ads API paths must remain under /${META_ADS_GRAPH_API_VERSION}.`,
+      )
+    }
+    for (const [name, value] of Object.entries(options.query ?? {})) {
+      if (value !== undefined) {
+        url.searchParams.set(
+          toSnakeCase(name),
+          Array.isArray(value) ? value.join(",") : String(value),
+        )
+      }
+    }
+    const body =
+      options.body === undefined ? undefined : toFormData(options.body)
+    const response = await fetch(url, {
+      body,
+      headers: { Authorization: `Bearer ${accessToken}` },
+      method: options.method ?? (body ? "POST" : "GET"),
+    })
+    const payload = parseJson(await response.text())
+    if (!response.ok) {
+      const error = ERROR_ENVELOPE_SCHEMA.safeParse(fromMeta(payload))
+      throw new MetaAdsApiError({
+        adAccountUsage: response.headers.get("X-Ad-Account-Usage") ?? undefined,
+        appUsage: response.headers.get("X-App-Usage") ?? undefined,
+        businessUseCaseUsage:
+          response.headers.get("X-Business-Use-Case-Usage") ?? undefined,
+        error: error.success ? error.data.error : undefined,
+        retryAfter: numberOrUndefined(response.headers.get("Retry-After")),
+        status: response.status,
+      })
+    }
+    return payload
+  }
+
+  return { call, page }
+}
+
+/**
+ * Encodes one public request body for Graph's form boundary.
+ *
+ * @param value - Codec-safe public request body.
+ * @throws When the body is not an object.
+ */
+function toFormData(value: Encodable) {
+  if (!isRecord(value))
+    throw new Error("Meta Ads request bodies must be objects.")
+  const form = new URLSearchParams()
+  for (const [name, item] of Object.entries(value)) {
+    if (item === undefined) continue
+    form.set(
+      toSnakeCase(name),
+      typeof item === "string" ||
+        typeof item === "number" ||
+        typeof item === "boolean"
+        ? String(item)
+        : item instanceof Date
+          ? item.toISOString()
+          : JSON.stringify(toMeta(item)),
+    )
+  }
+  return form
+}
+
+/**
+ * Converts public camelCase object keys to Meta wire keys recursively.
+ *
+ * @param value - Codec-safe public value.
+ */
+export function toMeta(value: Encodable): Encodable {
+  if (value instanceof Date) return value.toISOString()
+  if (Array.isArray(value)) return value.map(toMeta)
+  if (!isRecord(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toSnakeCase(key),
+      toMeta(item),
+    ]),
+  )
+}
+
+/**
+ * Converts Meta wire keys to public camelCase keys recursively.
+ *
+ * @param value - Provider value.
+ */
+export function fromMeta(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(fromMeta)
+  if (!isRecord(value)) return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      toCamelCase(key),
+      fromMeta(item),
+    ]),
+  )
+}
+
+/**
+ * Converts one camelCase key to snake_case.
+ *
+ * @param value - Public key.
+ */
+function toSnakeCase(value: string) {
+  return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+}
+
+/**
+ * Converts one snake_case key to camelCase.
+ *
+ * @param value - Provider key.
+ */
+function toCamelCase(value: string) {
+  return value.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase())
+}
+
+/**
+ * Parses a response body while retaining non-JSON provider failures.
+ *
+ * @param text - Raw response body.
+ */
+function parseJson(text: string): unknown {
+  if (text === "") return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+/**
+ * Parses an optional finite numeric header.
+ *
+ * @param value - Raw header value.
+ */
+function numberOrUndefined(value: string | null) {
+  if (value === null) return undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+/**
+ * Narrows one codec-safe object value.
+ *
+ * @param value - Unknown value.
+ */
+function isRecord(value: unknown): value is Record<string, Encodable> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/meta-ads/events.ts

@@ -0,0 +1,218 @@
+import { encodableSchema } from "@automate.ax/codec"
+import * as z from "zod"
+import { fromMeta } from "./api"
+import { META_ADS_ID_SCHEMA, META_ADS_WEBHOOK_ENVELOPE_SCHEMA } from "./schemas"
+
+export const META_ADS_AD_ACCOUNT_FIELDS = [
+  "ad_recommendations",
+  "creative_fatigue",
+  "effective_status",
+  "in_process_ad_objects",
+  "subscriptions",
+  "with_issues_ad_objects",
+] as const
+
+const META_ADS_EVENT_BASE_SCHEMA = z.object({
+  accountId: META_ADS_ID_SCHEMA,
+  field: z.string(),
+  occurredAt: z.number().int().nonnegative(),
+})
+
+export const META_ADS_EVENT_SCHEMA = META_ADS_EVENT_BASE_SCHEMA.extend({
+  value: encodableSchema,
+})
+
+export const META_ADS_EFFECTIVE_STATUS_EVENT_SCHEMA =
+  META_ADS_EVENT_BASE_SCHEMA.extend({
+    field: z.literal("field_changed"),
+    value: z.object({
+      changedFields: z.literal("effective_status").array(),
+      objectId: META_ADS_ID_SCHEMA,
+      objectType: z.enum(["ad", "adset", "campaign"]),
+    }),
+  })
+
+export const META_ADS_SUBSCRIPTION_EVENT_SCHEMA =
+  META_ADS_EVENT_BASE_SCHEMA.extend({
+    field: z.literal("subscriptions"),
+    value: z.object({
+      accountId: z.union([META_ADS_ID_SCHEMA, z.number()]).transform(String),
+      currentValue: z.string().optional(),
+      field: z.string().optional(),
+      objectId: z.union([META_ADS_ID_SCHEMA, z.number()]).transform(String),
+      objectType: z.enum(["ad", "adset", "campaign"]),
+      subscriptionId: z
+        .union([META_ADS_ID_SCHEMA, z.number()])
+        .transform(String),
+    }),
+  })
+
+export const META_ADS_CREATIVE_FATIGUE_EVENT_SCHEMA =
+  META_ADS_EVENT_BASE_SCHEMA.extend({
+    field: z.literal("creative_fatigue"),
+    value: z.object({
+      adAccountId: META_ADS_ID_SCHEMA,
+      adgroupId: META_ADS_ID_SCHEMA,
+      creativeFatigueLevel: z.enum(["HIGH", "LOW", "MEDIUM"]),
+      creativeFatigueMessage: z.string(),
+    }),
+  })
+
+export const META_ADS_RECOMMENDATION_EVENT_SCHEMA =
+  META_ADS_EVENT_BASE_SCHEMA.extend({
+    field: z.literal("ad_recommendations"),
+    value: z.object({
+      adAccountId: META_ADS_ID_SCHEMA,
+      adObjectIds: META_ADS_ID_SCHEMA.array(),
+      recommendationHash: z.string(),
+      recommendationMessage: z.string(),
+      recommendationSignature: z.string(),
+      recommendationStage: z.string(),
+      recommendationType: z.string(),
+    }),
+  })
+
+export const META_ADS_PROCESSING_EVENT_SCHEMA =
+  META_ADS_EVENT_BASE_SCHEMA.extend({
+    field: z.literal("in_process_ad_objects"),
+    value: z.object({
+      id: META_ADS_ID_SCHEMA,
+      level: z.enum(["AD", "AD_SET", "CAMPAIGN", "CREATIVE"]),
+      statusName: z.string(),
+    }),
+  })
+
+export const META_ADS_ISSUES_EVENT_SCHEMA = META_ADS_EVENT_BASE_SCHEMA.extend({
+  field: z.literal("with_issues_ad_objects"),
+  value: z.object({
+    errorCode: z.string(),
+    errorMessage: z.string(),
+    errorSummary: z.string(),
+    id: META_ADS_ID_SCHEMA,
+    level: z.enum(["AD", "AD_SET", "CAMPAIGN", "CREATIVE"]),
+  }),
+})
+
+export const META_ADS_LEAD_CREATED_EVENT_SCHEMA = z.object({
+  adId: z.string().optional(),
+  adgroupId: z.string().optional(),
+  createdTime: z.number().int().nonnegative(),
+  formId: META_ADS_ID_SCHEMA,
+  leadgenId: META_ADS_ID_SCHEMA,
+  pageId: META_ADS_ID_SCHEMA,
+})
+
+export const META_ADS_TRIGGER_CONFIG_SCHEMA = z.object({
+  account: z.string().optional(),
+  adAccountId: META_ADS_ID_SCHEMA,
+})
+
+export const META_ADS_LEAD_TRIGGER_CONFIG_SCHEMA = z.object({
+  account: z.string().optional(),
+  pageId: META_ADS_ID_SCHEMA,
+})
+
+export interface NormalizedMetaAdsWebhook {
+  adAccountEvents: z.output<typeof META_ADS_EVENT_SCHEMA>[]
+  leadEvents: z.output<typeof META_ADS_LEAD_CREATED_EVENT_SCHEMA>[]
+}
+
+export const metaAdsTriggerContracts = {
+  "meta-ads.ad.effectiveStatusChanged": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_EFFECTIVE_STATUS_EVENT_SCHEMA,
+  },
+  "meta-ads.ad.recommendation": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_RECOMMENDATION_EVENT_SCHEMA,
+  },
+  "meta-ads.adObject.issuesChanged": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_ISSUES_EVENT_SCHEMA,
+  },
+  "meta-ads.adObject.processingCompleted": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_PROCESSING_EVENT_SCHEMA,
+  },
+  "meta-ads.adSet.effectiveStatusChanged": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_EFFECTIVE_STATUS_EVENT_SCHEMA,
+  },
+  "meta-ads.campaign.effectiveStatusChanged": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_EFFECTIVE_STATUS_EVENT_SCHEMA,
+  },
+  "meta-ads.creativeFatigue.changed": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_CREATIVE_FATIGUE_EVENT_SCHEMA,
+  },
+  "meta-ads.event": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_EVENT_SCHEMA,
+  },
+  "meta-ads.insights.milestoneReached": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
+  },
+  "meta-ads.insights.updated": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
+  },
+  "meta-ads.lead.created": {
+    configSchema: META_ADS_LEAD_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_LEAD_CREATED_EVENT_SCHEMA,
+  },
+  "meta-ads.object.created": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
+  },
+  "meta-ads.object.updated": {
+    configSchema: META_ADS_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: META_ADS_SUBSCRIPTION_EVENT_SCHEMA,
+  },
+} as const
+
+/**
+ * Normalizes Meta's Page and ad-account envelopes into stable public events.
+ *
+ * @param input - Untrusted provider webhook envelope.
+ */
+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)),
+        })
+      }
+    }
+  }
+  return { adAccountEvents, leadEvents }
+}

package/src/meta-ads/index.ts

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