@automate.ax/integration-contracts 0.55.0

package/src/whatsapp/api.ts

@@ -0,0 +1,171 @@
+import type { JsonObject } from "type-fest"
+import { z } from "zod"
+
+export const WHATSAPP_GRAPH_API_VERSION = "v26.0"
+const WHATSAPP_GRAPH_API_ORIGIN = "https://graph.facebook.com"
+const WHATSAPP_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+  businessId: z.string().min(1),
+  phoneNumberId: z.string().min(1),
+  wabaId: z.string().min(1),
+})
+const WHATSAPP_ERROR_SCHEMA = z.looseObject({
+  code: z.number().int().optional(),
+  error_data: z
+    .looseObject({
+      details: z.string().optional(),
+      messaging_product: z.string().optional(),
+    })
+    .optional(),
+  error_subcode: z.number().int().optional(),
+  fbtrace_id: z.string().optional(),
+  message: z.string().optional(),
+  type: z.string().optional(),
+})
+
+/** Options for one authenticated WhatsApp Graph API request. */
+export interface WhatsAppApiRequestOptions<TSchema extends z.ZodType> {
+  /** JSON request body. */
+  body?: JsonObject
+
+  /** HTTP verb. */
+  method?: "DELETE" | "GET" | "POST"
+
+  /** Schema that validates and types the successful response. */
+  responseSchema: TSchema
+}
+
+/** Authenticated WhatsApp Business Platform helper for custom actions. */
+export interface WhatsAppApi {
+  /** Meta Business Portfolio ID that owns the connected assets. */
+  businessId: string
+
+  /** Connected WhatsApp business phone-number ID. */
+  phoneNumberId: string
+
+  /** Connected WhatsApp Business Account ID. */
+  wabaId: string
+
+  /** Calls a Graph API path under the pinned platform version. */
+  request<TSchema extends z.ZodType>(
+    path: string,
+    options: WhatsAppApiRequestOptions<TSchema>,
+  ): Promise<z.output<TSchema>>
+}
+
+/** Structured error returned by Meta's Graph API. */
+export class WhatsAppApiError extends Error {
+  readonly code?: number
+  readonly details?: string
+  readonly fbtraceId?: string
+  readonly retryAfter?: number
+  readonly status: number
+  readonly subcode?: number
+  readonly type?: string
+
+  /**
+   * Creates a structured Graph API error.
+   *
+   * @param options - Provider and transport error details.
+   * @param options.code - Meta Graph API error code.
+   * @param options.details - WhatsApp-specific failure details.
+   * @param options.fbtraceId - Meta trace identifier.
+   * @param options.message - Human-readable provider message.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP response status.
+   * @param options.subcode - Meta Graph API error subcode.
+   * @param options.type - Meta error type.
+   */
+  constructor(options: {
+    code?: number
+    details?: string
+    fbtraceId?: string
+    message: string
+    retryAfter?: number
+    status: number
+    subcode?: number
+    type?: string
+  }) {
+    super(options.message)
+    this.name = "WhatsAppApiError"
+    this.code = options.code
+    this.details = options.details
+    this.fbtraceId = options.fbtraceId
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+    this.subcode = options.subcode
+    this.type = options.type
+  }
+}
+
+/**
+ * Creates an authenticated WhatsApp Business Platform client.
+ *
+ * @param secret - Resolved WhatsApp integration secret.
+ */
+export function getWhatsAppApi(secret: Record<string, unknown>): WhatsAppApi {
+  const { accessToken, businessId, phoneNumberId, wabaId } =
+    WHATSAPP_SECRET_SCHEMA.parse(secret)
+
+  return {
+    businessId,
+    phoneNumberId,
+    wabaId,
+    request: async (path, options) => {
+      if (!/^\/[A-Za-z0-9_.,?=&/-]+$/.test(path)) {
+        throw new Error("WhatsApp Graph API paths must be relative.")
+      }
+      const response = await fetch(
+        `${WHATSAPP_GRAPH_API_ORIGIN}/${WHATSAPP_GRAPH_API_VERSION}${path}`,
+        {
+          body: options.body ? JSON.stringify(options.body) : undefined,
+          headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${accessToken}`,
+            ...(options.body && { "Content-Type": "application/json" }),
+          },
+          method: options.method ?? (options.body ? "POST" : "GET"),
+        },
+      )
+      const payload: unknown = await response.json()
+      if (!response.ok) throw toWhatsAppApiError(response, payload)
+      return options.responseSchema.parse(payload)
+    },
+  }
+}
+
+/**
+ * Converts an unsuccessful Graph response into a structured error.
+ *
+ * @param response - Unsuccessful HTTP response.
+ * @param payload - Parsed Graph API payload.
+ */
+function toWhatsAppApiError(response: Response, payload: unknown) {
+  const error = z
+    .looseObject({ error: WHATSAPP_ERROR_SCHEMA.optional() })
+    .safeParse(payload)
+  const providerError = error.success ? error.data.error : undefined
+  return new WhatsAppApiError({
+    code: providerError?.code,
+    details: providerError?.error_data?.details,
+    fbtraceId: providerError?.fbtrace_id,
+    message:
+      providerError?.message ??
+      `WhatsApp Graph API request failed (${response.status}).`,
+    retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+    status: response.status,
+    subcode: providerError?.error_subcode,
+    type: providerError?.type,
+  })
+}
+
+/**
+ * Parses Meta's integer retry delay header.
+ *
+ * @param value - Raw `Retry-After` value.
+ */
+function parseRetryAfter(value: string | null) {
+  if (value === null) return undefined
+  const seconds = Number(value)
+  return Number.isFinite(seconds) ? seconds : undefined
+}

package/src/whatsapp/index.ts

@@ -0,0 +1,46 @@
+import { z } from "zod"
+import {
+  WHATSAPP_MESSAGE_DELIVERED_EVENT_SCHEMA,
+  WHATSAPP_MESSAGE_FAILED_EVENT_SCHEMA,
+  WHATSAPP_MESSAGE_PLAYED_EVENT_SCHEMA,
+  WHATSAPP_MESSAGE_READ_EVENT_SCHEMA,
+  WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA,
+  WHATSAPP_MESSAGE_SENT_EVENT_SCHEMA,
+  WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./api"
+export * from "./schemas"
+
+export const WHATSAPP_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const whatsappTriggerContracts = {
+  "whatsapp.message.delivered": {
+    configSchema: WHATSAPP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: WHATSAPP_MESSAGE_DELIVERED_EVENT_SCHEMA,
+  },
+  "whatsapp.message.failed": {
+    configSchema: WHATSAPP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: WHATSAPP_MESSAGE_FAILED_EVENT_SCHEMA,
+  },
+  "whatsapp.message.played": {
+    configSchema: WHATSAPP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: WHATSAPP_MESSAGE_PLAYED_EVENT_SCHEMA,
+  },
+  "whatsapp.message.read": {
+    configSchema: WHATSAPP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: WHATSAPP_MESSAGE_READ_EVENT_SCHEMA,
+  },
+  "whatsapp.message.received": {
+    configSchema: WHATSAPP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA,
+  },
+  "whatsapp.message.sent": {
+    configSchema: WHATSAPP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: WHATSAPP_MESSAGE_SENT_EVENT_SCHEMA,
+  },
+  "whatsapp.message.statusEvent": {
+    configSchema: WHATSAPP_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA,
+  },
+} as const

package/src/whatsapp/schemas.ts

@@ -0,0 +1,341 @@
+import { z } from "zod"
+
+const WHATSAPP_ERROR_SCHEMA = z.object({
+  code: z.number().int(),
+  error_data: z
+    .object({
+      details: z.string().optional(),
+      messaging_product: z.string().optional(),
+    })
+    .optional(),
+  error_subcode: z.number().int().optional(),
+  fbtrace_id: z.string().optional(),
+  message: z.string(),
+  title: z.string().optional(),
+})
+const WHATSAPP_MESSAGE_SCHEMA = z.object({
+  audio: z
+    .object({ id: z.string(), mime_type: z.string().optional() })
+    .optional(),
+  button: z.object({ payload: z.string(), text: z.string() }).optional(),
+  contacts: z.json().array().optional(),
+  context: z
+    .object({
+      forwarded: z.boolean().optional(),
+      from: z.string().optional(),
+      id: z.string(),
+    })
+    .optional(),
+  document: z
+    .object({
+      caption: z.string().optional(),
+      filename: z.string().optional(),
+      id: z.string(),
+      mime_type: z.string().optional(),
+    })
+    .optional(),
+  errors: WHATSAPP_ERROR_SCHEMA.array().optional(),
+  from: z.string(),
+  id: z.string(),
+  image: z
+    .object({
+      caption: z.string().optional(),
+      id: z.string(),
+      mime_type: z.string().optional(),
+    })
+    .optional(),
+  interactive: z
+    .object({
+      button_reply: z.object({ id: z.string(), title: z.string() }).optional(),
+      list_reply: z
+        .object({
+          description: z.string().optional(),
+          id: z.string(),
+          title: z.string(),
+        })
+        .optional(),
+      type: z.enum(["button_reply", "list_reply"]),
+    })
+    .optional(),
+  location: z
+    .object({
+      address: z.string().optional(),
+      latitude: z.number(),
+      longitude: z.number(),
+      name: z.string().optional(),
+      url: z.string().optional(),
+    })
+    .optional(),
+  order: z.json().optional(),
+  reaction: z.object({ emoji: z.string(), message_id: z.string() }).optional(),
+  referral: z.json().optional(),
+  sticker: z
+    .object({ id: z.string(), mime_type: z.string().optional() })
+    .optional(),
+  system: z.json().optional(),
+  text: z.object({ body: z.string() }).optional(),
+  timestamp: z.string(),
+  type: z.enum([
+    "audio",
+    "button",
+    "contacts",
+    "document",
+    "image",
+    "interactive",
+    "location",
+    "order",
+    "reaction",
+    "sticker",
+    "system",
+    "text",
+    "unknown",
+    "unsupported",
+    "video",
+  ]),
+  unknown: z.json().optional(),
+  unsupported: z.json().optional(),
+  video: z
+    .object({
+      caption: z.string().optional(),
+      id: z.string(),
+      mime_type: z.string().optional(),
+    })
+    .optional(),
+})
+const WHATSAPP_STATUS_SCHEMA = z.object({
+  biz_opaque_callback_data: z.string().optional(),
+  conversation: z
+    .object({
+      expiration_timestamp: z.string().optional(),
+      id: z.string(),
+      origin: z.object({ type: z.string() }),
+    })
+    .optional(),
+  errors: WHATSAPP_ERROR_SCHEMA.array().optional(),
+  id: z.string(),
+  pricing: z
+    .object({
+      billable: z.boolean().optional(),
+      category: z.string(),
+      pricing_model: z.enum(["CBP", "PMP"]),
+      type: z
+        .enum(["regular", "free_customer_service", "free_entry_point"])
+        .optional(),
+    })
+    .optional(),
+  recipient_id: z.string(),
+  status: z.enum(["sent", "delivered", "read", "failed", "played"]),
+  timestamp: z.string(),
+})
+const WHATSAPP_NORMALIZED_ERROR_SCHEMA = z.object({
+  code: z.number().int(),
+  details: z.string().optional(),
+  message: z.string(),
+  subcode: z.number().int().optional(),
+  title: z.string().optional(),
+  traceId: z.string().optional(),
+})
+const WHATSAPP_CHANGE_VALUE_SCHEMA = z.object({
+  contacts: z
+    .object({
+      profile: z.object({ name: z.string().optional() }),
+      wa_id: z.string(),
+    })
+    .array()
+    .optional(),
+  messages: WHATSAPP_MESSAGE_SCHEMA.array().optional(),
+  messaging_product: z.literal("whatsapp"),
+  metadata: z.object({
+    display_phone_number: z.string(),
+    phone_number_id: z.string(),
+  }),
+  statuses: WHATSAPP_STATUS_SCHEMA.array().optional(),
+})
+
+/** Provider-native WhatsApp webhook envelope. */
+export const WHATSAPP_WEBHOOK_SCHEMA = z.object({
+  entry: z
+    .object({
+      changes: z
+        .object({
+          field: z.literal("messages"),
+          value: WHATSAPP_CHANGE_VALUE_SCHEMA,
+        })
+        .array(),
+      id: z.string(),
+    })
+    .array(),
+  object: z.literal("whatsapp_business_account"),
+})
+
+/** Normalized incoming WhatsApp message event. */
+export const WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA = z.object({
+  businessAccountId: z.string(),
+  displayPhoneNumber: z.string(),
+  message: z.object({
+    content: z.json().optional(),
+    context: z
+      .object({
+        forwarded: z.boolean().optional(),
+        from: z.string().optional(),
+        messageId: z.string(),
+      })
+      .optional(),
+    id: z.string(),
+    timestamp: z.string(),
+    type: WHATSAPP_MESSAGE_SCHEMA.shape.type,
+  }),
+  phoneNumberId: z.string(),
+  providerEvent: WHATSAPP_MESSAGE_SCHEMA,
+  sender: z.object({ id: z.string(), name: z.string().optional() }),
+})
+
+/** Normalized WhatsApp message status event. */
+export const WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA = z.object({
+  businessAccountId: z.string(),
+  callbackData: z.string().optional(),
+  conversation: z
+    .object({
+      expirationTimestamp: z.string().optional(),
+      id: z.string(),
+      originType: z.string(),
+    })
+    .optional(),
+  errors: WHATSAPP_NORMALIZED_ERROR_SCHEMA.array().optional(),
+  messageId: z.string(),
+  phoneNumberId: z.string(),
+  pricing: z
+    .object({
+      billable: z.boolean().optional(),
+      category: z.string(),
+      model: z.enum(["CBP", "PMP"]),
+      type: z
+        .enum(["regular", "free_customer_service", "free_entry_point"])
+        .optional(),
+    })
+    .optional(),
+  providerEvent: WHATSAPP_STATUS_SCHEMA,
+  recipientId: z.string(),
+  status: WHATSAPP_STATUS_SCHEMA.shape.status,
+  timestamp: z.string(),
+})
+
+export const WHATSAPP_MESSAGE_SENT_EVENT_SCHEMA =
+  WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA.extend({
+    providerEvent: WHATSAPP_STATUS_SCHEMA.extend({ status: z.literal("sent") }),
+    status: z.literal("sent"),
+  })
+export const WHATSAPP_MESSAGE_DELIVERED_EVENT_SCHEMA =
+  WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA.extend({
+    providerEvent: WHATSAPP_STATUS_SCHEMA.extend({
+      status: z.literal("delivered"),
+    }),
+    status: z.literal("delivered"),
+  })
+export const WHATSAPP_MESSAGE_READ_EVENT_SCHEMA =
+  WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA.extend({
+    providerEvent: WHATSAPP_STATUS_SCHEMA.extend({ status: z.literal("read") }),
+    status: z.literal("read"),
+  })
+export const WHATSAPP_MESSAGE_FAILED_EVENT_SCHEMA =
+  WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA.extend({
+    providerEvent: WHATSAPP_STATUS_SCHEMA.extend({
+      status: z.literal("failed"),
+    }),
+    status: z.literal("failed"),
+  })
+export const WHATSAPP_MESSAGE_PLAYED_EVENT_SCHEMA =
+  WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA.extend({
+    providerEvent: WHATSAPP_STATUS_SCHEMA.extend({
+      status: z.literal("played"),
+    }),
+    status: z.literal("played"),
+  })
+
+/**
+ * Flattens one verified provider callback into independently ingestible events.
+ *
+ * @param input - Untrusted WhatsApp webhook envelope.
+ */
+export function normalizeWhatsAppWebhook(input: unknown) {
+  // Parse once before flattening every entry and change in the delivery batch.
+  const webhook = WHATSAPP_WEBHOOK_SCHEMA.parse(input)
+  const messages: z.output<typeof WHATSAPP_MESSAGE_RECEIVED_EVENT_SCHEMA>[] = []
+  const statuses: z.output<typeof WHATSAPP_MESSAGE_STATUS_EVENT_SCHEMA>[] = []
+
+  for (const entry of webhook.entry) {
+    for (const { value } of entry.changes) {
+      for (const message of value.messages ?? []) {
+        // Meta supplies contacts separately, so match the sender for its profile.
+        const sender = value.contacts?.find(
+          ({ wa_id }) => wa_id === message.from,
+        )
+        messages.push({
+          businessAccountId: entry.id,
+          displayPhoneNumber: value.metadata.display_phone_number,
+          message: {
+            content: message[message.type],
+            ...(message.context && {
+              context: {
+                forwarded: message.context.forwarded,
+                from: message.context.from,
+                messageId: message.context.id,
+              },
+            }),
+            id: message.id,
+            timestamp: message.timestamp,
+            type: message.type,
+          },
+          phoneNumberId: value.metadata.phone_number_id,
+          providerEvent: message,
+          sender: { id: message.from, name: sender?.profile.name },
+        })
+      }
+      for (const status of value.statuses ?? []) {
+        statuses.push({
+          businessAccountId: entry.id,
+          callbackData: status.biz_opaque_callback_data,
+          ...(status.conversation && {
+            conversation: {
+              expirationTimestamp: status.conversation.expiration_timestamp,
+              id: status.conversation.id,
+              originType: status.conversation.origin.type,
+            },
+          }),
+          errors: status.errors?.map(normalizeWhatsAppError),
+          messageId: status.id,
+          phoneNumberId: value.metadata.phone_number_id,
+          ...(status.pricing && {
+            pricing: {
+              billable: status.pricing.billable,
+              category: status.pricing.category,
+              model: status.pricing.pricing_model,
+              type: status.pricing.type,
+            },
+          }),
+          providerEvent: status,
+          recipientId: status.recipient_id,
+          status: status.status,
+          timestamp: status.timestamp,
+        })
+      }
+    }
+  }
+  return { messages, statuses }
+}
+
+/**
+ * Converts one provider-native Meta error to the public event shape.
+ *
+ * @param error - Provider-native webhook error.
+ */
+function normalizeWhatsAppError(error: z.output<typeof WHATSAPP_ERROR_SCHEMA>) {
+  return {
+    code: error.code,
+    details: error.error_data?.details,
+    message: error.message,
+    subcode: error.error_subcode,
+    title: error.title,
+    traceId: error.fbtrace_id,
+  }
+}