@automate.ax/integration-contracts 0.55.0

package/dist/whatsapp/schemas.js

@@ -0,0 +1,326 @@
+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) {
+    // Parse once before flattening every entry and change in the delivery batch.
+    const webhook = WHATSAPP_WEBHOOK_SCHEMA.parse(input);
+    const messages = [];
+    const statuses = [];
+    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) {
+    return {
+        code: error.code,
+        details: error.error_data?.details,
+        message: error.message,
+        subcode: error.error_subcode,
+        title: error.title,
+        traceId: error.fbtrace_id,
+    };
+}

package/package.json

@@ -0,0 +1,169 @@
+{
+  "name": "@automate.ax/integration-contracts",
+  "version": "0.55.0",
+  "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zachsents/automate.ax.git",
+    "directory": "packages/integration-contracts"
+  },
+  "homepage": "https://automate.ax",
+  "bugs": {
+    "url": "https://github.com/zachsents/automate.ax/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "zshy": {
+    "exports": {
+      "./airtable": "./src/airtable/index.ts",
+      "./asana": "./src/asana/index.ts",
+      "./brevo": "./src/brevo/index.ts",
+      "./gmail": "./src/gmail/index.ts",
+      "./google-calendar": "./src/google-calendar/index.ts",
+      "./google-forms": "./src/google-forms/index.ts",
+      "./github": "./src/github/index.ts",
+      "./linear": "./src/linear/index.ts",
+      "./outlook": "./src/outlook/index.ts",
+      "./resend": "./src/resend/index.ts",
+      "./slack": "./src/slack/index.ts",
+      "./teams": "./src/teams/index.ts",
+      "./trello": "./src/trello/index.ts",
+      "./triggers": "./src/triggers.ts",
+      "./vercel": "./src/vercel/index.ts",
+      "./whatsapp": "./src/whatsapp/index.ts"
+    },
+    "cjs": false,
+    "conditions": {
+      "bun": "src"
+    }
+  },
+  "dependencies": {
+    "@automate.ax/codec": "0.55.0",
+    "@googleapis/calendar": "^15.0.0",
+    "@googleapis/forms": "^6.0.1",
+    "@googleapis/gmail": "^12.0.0",
+    "@octokit/openapi-webhooks-types": "^12.1.0",
+    "@octokit/rest": "^22.0.1",
+    "html-to-text": "^10.0.0",
+    "nodemailer": "^9.0.3",
+    "postal-mime": "^2.7.5",
+    "type-fest": "^5.6.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@internal/config": "0.0.0",
+    "@types/bun": "latest",
+    "@types/html-to-text": "^9.0.4",
+    "@types/nodemailer": "^8.0.1",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "@zachsents/oxlint-config": "^0.4.1",
+    "concurrently": "^10.0.4",
+    "eslint": "^9.39.5",
+    "oxlint": "^1.76.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "zshy": "^0.7.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "concurrently --success all --kill-others-on-fail \"oxlint --type-aware\" \"bun --bun eslint .\"",
+    "lint:fix": "concurrently --success all --kill-others-on-fail \"oxlint --type-aware --fix --fix-suggestions\" \"bun --bun eslint . --fix\"",
+    "check": "bun run typecheck && bun run lint",
+    "build": "zshy",
+    "prepublishOnly": "bun run check && bun run build"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    "./airtable": {
+      "bun": "./src/airtable/index.ts",
+      "types": "./dist/airtable/index.d.ts",
+      "default": "./dist/airtable/index.js"
+    },
+    "./asana": {
+      "bun": "./src/asana/index.ts",
+      "types": "./dist/asana/index.d.ts",
+      "default": "./dist/asana/index.js"
+    },
+    "./brevo": {
+      "bun": "./src/brevo/index.ts",
+      "types": "./dist/brevo/index.d.ts",
+      "default": "./dist/brevo/index.js"
+    },
+    "./gmail": {
+      "bun": "./src/gmail/index.ts",
+      "types": "./dist/gmail/index.d.ts",
+      "default": "./dist/gmail/index.js"
+    },
+    "./google-calendar": {
+      "bun": "./src/google-calendar/index.ts",
+      "types": "./dist/google-calendar/index.d.ts",
+      "default": "./dist/google-calendar/index.js"
+    },
+    "./google-forms": {
+      "bun": "./src/google-forms/index.ts",
+      "types": "./dist/google-forms/index.d.ts",
+      "default": "./dist/google-forms/index.js"
+    },
+    "./github": {
+      "bun": "./src/github/index.ts",
+      "types": "./dist/github/index.d.ts",
+      "default": "./dist/github/index.js"
+    },
+    "./linear": {
+      "bun": "./src/linear/index.ts",
+      "types": "./dist/linear/index.d.ts",
+      "default": "./dist/linear/index.js"
+    },
+    "./outlook": {
+      "bun": "./src/outlook/index.ts",
+      "types": "./dist/outlook/index.d.ts",
+      "default": "./dist/outlook/index.js"
+    },
+    "./resend": {
+      "bun": "./src/resend/index.ts",
+      "types": "./dist/resend/index.d.ts",
+      "default": "./dist/resend/index.js"
+    },
+    "./slack": {
+      "bun": "./src/slack/index.ts",
+      "types": "./dist/slack/index.d.ts",
+      "default": "./dist/slack/index.js"
+    },
+    "./teams": {
+      "bun": "./src/teams/index.ts",
+      "types": "./dist/teams/index.d.ts",
+      "default": "./dist/teams/index.js"
+    },
+    "./trello": {
+      "bun": "./src/trello/index.ts",
+      "types": "./dist/trello/index.d.ts",
+      "default": "./dist/trello/index.js"
+    },
+    "./triggers": {
+      "bun": "./src/triggers.ts",
+      "types": "./dist/triggers.d.ts",
+      "default": "./dist/triggers.js"
+    },
+    "./vercel": {
+      "bun": "./src/vercel/index.ts",
+      "types": "./dist/vercel/index.d.ts",
+      "default": "./dist/vercel/index.js"
+    },
+    "./whatsapp": {
+      "bun": "./src/whatsapp/index.ts",
+      "types": "./dist/whatsapp/index.d.ts",
+      "default": "./dist/whatsapp/index.js"
+    }
+  }
+}

package/src/airtable/api.ts

@@ -0,0 +1,66 @@
+import { z } from "zod"
+
+export const AIRTABLE_API_ORIGIN = "https://api.airtable.com/v0/"
+
+const AIRTABLE_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+const AIRTABLE_ERROR_SCHEMA = z.object({
+  error: z.union([
+    z.string(),
+    z.object({
+      message: z.string().optional(),
+      type: z.string().optional(),
+    }),
+  ]),
+})
+
+/** Authenticated raw Airtable Web API client for custom actions. */
+export interface AirtableApi {
+  /**
+   * Sends a request relative to `https://api.airtable.com/v0/`.
+   *
+   * Non-successful responses throw with Airtable's provider error message.
+   *
+   * @param path - API path relative to the v0 root.
+   * @param init - Standard Fetch request options.
+   */
+  request(path: string, init?: RequestInit): Promise<Response>
+}
+
+/**
+ * Creates an authenticated raw Airtable Web API client.
+ *
+ * @param secret - Refreshed Airtable integration secret.
+ */
+export function getAirtableApi(secret: Record<string, unknown>): AirtableApi {
+  const { accessToken } = AIRTABLE_SECRET_SCHEMA.parse(secret)
+
+  return {
+    request: async (path, init) => {
+      const headers = new Headers(init?.headers)
+      headers.set("Authorization", `Bearer ${accessToken}`)
+      if (init?.body !== undefined && !headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json")
+      }
+
+      const response = await fetch(new URL(path, AIRTABLE_API_ORIGIN), {
+        ...init,
+        headers,
+      })
+      if (!response.ok) {
+        const result = AIRTABLE_ERROR_SCHEMA.safeParse(
+          await response.json().catch(() => undefined),
+        )
+        const providerError = result.success ? result.data.error : undefined
+        throw new Error(
+          (typeof providerError === "string"
+            ? providerError
+            : (providerError?.message ?? providerError?.type)) ??
+            `Airtable request failed with status ${response.status}.`,
+        )
+      }
+      return response
+    },
+  }
+}

package/src/airtable/index.ts

@@ -0,0 +1,41 @@
+import { z } from "zod"
+import {
+  AIRTABLE_RECORD_CREATED_EVENT_SCHEMA,
+  AIRTABLE_RECORD_DELETED_EVENT_SCHEMA,
+  AIRTABLE_RECORD_MOVED_INTO_VIEW_EVENT_SCHEMA,
+  AIRTABLE_RECORD_MOVED_OUT_OF_VIEW_EVENT_SCHEMA,
+  AIRTABLE_RECORD_UPDATED_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./api"
+export * from "./schemas"
+
+/** Canonical Airtable webhook scope shared by authoring and ingestion. */
+export const AIRTABLE_TRIGGER_CONFIG_SCHEMA = z.object({
+  baseId: z.string(),
+  scopeId: z.string(),
+  scopeType: z.enum(["table", "view"]),
+})
+
+export const airtableTriggerContracts = {
+  "airtable.record.created": {
+    configSchema: AIRTABLE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AIRTABLE_RECORD_CREATED_EVENT_SCHEMA,
+  },
+  "airtable.record.deleted": {
+    configSchema: AIRTABLE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AIRTABLE_RECORD_DELETED_EVENT_SCHEMA,
+  },
+  "airtable.record.movedIntoView": {
+    configSchema: AIRTABLE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AIRTABLE_RECORD_MOVED_INTO_VIEW_EVENT_SCHEMA,
+  },
+  "airtable.record.movedOutOfView": {
+    configSchema: AIRTABLE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AIRTABLE_RECORD_MOVED_OUT_OF_VIEW_EVENT_SCHEMA,
+  },
+  "airtable.record.updated": {
+    configSchema: AIRTABLE_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: AIRTABLE_RECORD_UPDATED_EVENT_SCHEMA,
+  },
+} as const