@automate.ax/integration-contracts 0.107.0 → 0.109.0

package/src/airtable/schemas.ts

@@ -34,7 +34,28 @@ const AIRTABLE_VIEW_CHANGE_SCHEMA = z.looseObject({
     .optional(),
   destroyedRecordIds: z.string().array().optional(),
 })
+const AIRTABLE_FIELD_DEFINITION_SCHEMA = z.object({
+  name: z.string(),
+  type: z.string(),
+})
+const AIRTABLE_FIELD_CHANGE_SCHEMA = z.looseObject({
+  current: AIRTABLE_FIELD_DEFINITION_SCHEMA.partial(),
+  previous: AIRTABLE_FIELD_DEFINITION_SCHEMA.partial().optional(),
+})
+const AIRTABLE_TABLE_METADATA_SCHEMA = z.object({
+  description: z.string().nullable(),
+  name: z.string(),
+})
 const AIRTABLE_TABLE_CHANGE_SCHEMA = z.looseObject({
+  changedFieldsById: z
+    .record(z.string(), AIRTABLE_FIELD_CHANGE_SCHEMA)
+    .optional(),
+  changedMetadata: z
+    .looseObject({
+      current: AIRTABLE_TABLE_METADATA_SCHEMA.partial(),
+      previous: AIRTABLE_TABLE_METADATA_SCHEMA.partial(),
+    })
+    .optional(),
   changedRecordsById: z
     .record(z.string(), AIRTABLE_CHANGED_RECORD_SCHEMA)
     .optional(),
@@ -44,8 +65,17 @@ const AIRTABLE_TABLE_CHANGE_SCHEMA = z.looseObject({
   createdRecordsById: z
     .record(z.string(), AIRTABLE_CREATED_RECORD_SCHEMA)
     .optional(),
+  createdFieldsById: z
+    .record(z.string(), AIRTABLE_FIELD_DEFINITION_SCHEMA)
+    .optional(),
+  destroyedFieldIds: z.string().array().optional(),
   destroyedRecordIds: z.string().array().optional(),
 })
+const AIRTABLE_CREATED_TABLE_SCHEMA = z.looseObject({
+  fieldsById: z.record(z.string(), AIRTABLE_FIELD_DEFINITION_SCHEMA).optional(),
+  metadata: AIRTABLE_TABLE_METADATA_SCHEMA.optional(),
+  recordsById: z.record(z.string(), AIRTABLE_CREATED_RECORD_SCHEMA).optional(),
+})
 
 /** One provider-native Airtable webhook transaction payload. */
 export const AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA = z
@@ -55,13 +85,84 @@ export const AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA = z
     changedTablesById: z
       .record(z.string(), AIRTABLE_TABLE_CHANGE_SCHEMA)
       .optional(),
+    createdTablesById: z
+      .record(z.string(), AIRTABLE_CREATED_TABLE_SCHEMA)
+      .optional(),
     code: z.string().optional(),
     error: z.literal(true).optional(),
+    destroyedTableIds: z.string().array().optional(),
     payloadFormat: z.string(),
     timestamp: z.iso.datetime({ offset: true }),
   })
   .catchall(z.json())
 
+export const AIRTABLE_BASE_EVENT_SCHEMA = z.object({
+  /** Airtable base that emitted the transaction. */
+  baseId: z.string(),
+
+  /** Complete provider webhook transaction. */
+  event: AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA,
+
+  /** Time at which Airtable committed the transaction. */
+  occurredAt: z.iso.datetime({ offset: true }),
+
+  /** Airtable system that caused the transaction. */
+  source: z.string(),
+
+  /** Provider-specific actor or source details. */
+  sourceMetadata: z.record(z.string(), z.json()).optional(),
+
+  /** Base-scoped transaction number assigned by Airtable. */
+  transactionNumber: z.number().int().nonnegative(),
+})
+
+const AIRTABLE_TABLE_EVENT_SCHEMA = AIRTABLE_BASE_EVENT_SCHEMA.extend({
+  /** Stable Airtable table ID. */
+  tableId: z.string(),
+})
+
+export const AIRTABLE_TABLE_CREATED_EVENT_SCHEMA =
+  AIRTABLE_TABLE_EVENT_SCHEMA.extend({
+    /** Field definitions keyed by stable field ID. */
+    fields: z.record(z.string(), AIRTABLE_FIELD_DEFINITION_SCHEMA),
+
+    /** Created table metadata when included by Airtable. */
+    metadata: AIRTABLE_TABLE_METADATA_SCHEMA.optional(),
+  })
+
+export const AIRTABLE_TABLE_UPDATED_EVENT_SCHEMA =
+  AIRTABLE_TABLE_EVENT_SCHEMA.extend({
+    /** Current table metadata fields changed by the transaction. */
+    current: AIRTABLE_TABLE_METADATA_SCHEMA.partial(),
+
+    /** Previous table metadata fields changed by the transaction. */
+    previous: AIRTABLE_TABLE_METADATA_SCHEMA.partial(),
+  })
+
+export const AIRTABLE_TABLE_DELETED_EVENT_SCHEMA = AIRTABLE_TABLE_EVENT_SCHEMA
+
+const AIRTABLE_FIELD_EVENT_SCHEMA = AIRTABLE_TABLE_EVENT_SCHEMA.extend({
+  /** Stable Airtable field ID. */
+  fieldId: z.string(),
+})
+
+export const AIRTABLE_FIELD_CREATED_EVENT_SCHEMA =
+  AIRTABLE_FIELD_EVENT_SCHEMA.extend({
+    /** Created field definition. */
+    field: AIRTABLE_FIELD_DEFINITION_SCHEMA,
+  })
+
+export const AIRTABLE_FIELD_UPDATED_EVENT_SCHEMA =
+  AIRTABLE_FIELD_EVENT_SCHEMA.extend({
+    /** Current field definition values changed by the transaction. */
+    current: AIRTABLE_FIELD_DEFINITION_SCHEMA.partial(),
+
+    /** Previous field definition values changed by the transaction. */
+    previous: AIRTABLE_FIELD_DEFINITION_SCHEMA.partial().optional(),
+  })
+
+export const AIRTABLE_FIELD_DELETED_EVENT_SCHEMA = AIRTABLE_FIELD_EVENT_SCHEMA
+
 const AIRTABLE_RECORD_EVENT_SCHEMA = z.object({
   /** Airtable base containing the affected record. */
   baseId: z.string(),
@@ -123,7 +224,14 @@ export const AIRTABLE_RECORD_MOVED_OUT_OF_VIEW_EVENT_SCHEMA =
     viewId: z.string(),
   })
 
-export const AIRTABLE_RECORD_EVENT_TYPES = [
+export const AIRTABLE_EVENT_TYPES = [
+  "airtable.base.event",
+  "airtable.table.created",
+  "airtable.table.updated",
+  "airtable.table.deleted",
+  "airtable.field.created",
+  "airtable.field.updated",
+  "airtable.field.deleted",
   "airtable.record.created",
   "airtable.record.updated",
   "airtable.record.deleted",
@@ -131,77 +239,206 @@ export const AIRTABLE_RECORD_EVENT_TYPES = [
   "airtable.record.movedOutOfView",
 ] as const
 
-export type AirtableRecordEventType =
-  (typeof AIRTABLE_RECORD_EVENT_TYPES)[number]
+export type AirtableEventType = (typeof AIRTABLE_EVENT_TYPES)[number]
 
 /**
- * Expands one Airtable webhook transaction into semantic record events.
+ * Expands one Airtable webhook transaction into broad and semantic events.
  *
  * @param value - Untrusted provider payload returned by Airtable.
  * @param baseId - Stable ID of the base that owns the webhook.
  */
-export function normalizeAirtableRecordEvents(value: unknown, baseId: string) {
+export function normalizeAirtableEvents(value: unknown, baseId: string) {
   const event = AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA.parse(value)
 
-  return Object.entries(event.changedTablesById ?? {}).flatMap(
-    ([tableId, table]) => [
-      ...Object.entries(table.createdRecordsById ?? {}).map(
-        ([recordId, record]) => ({
-          eventType: "airtable.record.created" as const,
-          payload: AIRTABLE_RECORD_CREATED_EVENT_SCHEMA.parse({
-            ...recordEventBase(event, baseId, tableId, recordId),
-            createdAt: record.createdTime,
-            fields: record.cellValuesByFieldId,
+  return [
+    {
+      eventType: "airtable.base.event" as const,
+      payload: AIRTABLE_BASE_EVENT_SCHEMA.parse(baseEventBase(event, baseId)),
+    },
+    ...Object.entries(event.createdTablesById ?? {}).flatMap(
+      ([tableId, table]) => [
+        {
+          eventType: "airtable.table.created" as const,
+          payload: AIRTABLE_TABLE_CREATED_EVENT_SCHEMA.parse({
+            ...tableEventBase(event, baseId, tableId),
+            fields: table.fieldsById ?? {},
+            metadata: table.metadata,
           }),
-        }),
-      ),
-      ...Object.entries(table.changedRecordsById ?? {}).map(
-        ([recordId, record]) => ({
-          eventType: "airtable.record.updated" as const,
-          payload: AIRTABLE_RECORD_UPDATED_EVENT_SCHEMA.parse({
-            ...recordEventBase(event, baseId, tableId, recordId),
-            changedFieldIds: Object.keys(record.current.cellValuesByFieldId),
-            fields: {
-              ...record.unchanged?.cellValuesByFieldId,
-              ...record.current.cellValuesByFieldId,
-            },
-            previousFields: {
-              ...record.unchanged?.cellValuesByFieldId,
-              ...record.previous?.cellValuesByFieldId,
-            },
+        },
+        ...Object.entries(table.fieldsById ?? {}).map(([fieldId, field]) => ({
+          eventType: "airtable.field.created" as const,
+          payload: AIRTABLE_FIELD_CREATED_EVENT_SCHEMA.parse({
+            ...fieldEventBase(event, baseId, tableId, fieldId),
+            field,
           }),
-        }),
+        })),
+        ...Object.entries(table.recordsById ?? {}).map(
+          ([recordId, record]) => ({
+            eventType: "airtable.record.created" as const,
+            payload: AIRTABLE_RECORD_CREATED_EVENT_SCHEMA.parse({
+              ...recordEventBase(event, baseId, tableId, recordId),
+              createdAt: record.createdTime,
+              fields: record.cellValuesByFieldId,
+            }),
+          }),
+        ),
+      ],
+    ),
+    ...(event.destroyedTableIds ?? []).map((tableId) => ({
+      eventType: "airtable.table.deleted" as const,
+      payload: AIRTABLE_TABLE_DELETED_EVENT_SCHEMA.parse(
+        tableEventBase(event, baseId, tableId),
       ),
-      ...(table.destroyedRecordIds ?? []).map((recordId) => ({
-        eventType: "airtable.record.deleted" as const,
-        payload: AIRTABLE_RECORD_DELETED_EVENT_SCHEMA.parse(
-          recordEventBase(event, baseId, tableId, recordId),
+    })),
+    ...Object.entries(event.changedTablesById ?? {}).flatMap(
+      ([tableId, table]) => [
+        ...(table.changedMetadata
+          ? [
+              {
+                eventType: "airtable.table.updated" as const,
+                payload: AIRTABLE_TABLE_UPDATED_EVENT_SCHEMA.parse({
+                  ...tableEventBase(event, baseId, tableId),
+                  current: table.changedMetadata.current,
+                  previous: table.changedMetadata.previous,
+                }),
+              },
+            ]
+          : []),
+        ...Object.entries(table.createdFieldsById ?? {}).map(
+          ([fieldId, field]) => ({
+            eventType: "airtable.field.created" as const,
+            payload: AIRTABLE_FIELD_CREATED_EVENT_SCHEMA.parse({
+              ...fieldEventBase(event, baseId, tableId, fieldId),
+              field,
+            }),
+          }),
         ),
-      })),
-      ...Object.entries(table.changedViewsById ?? {}).flatMap(
-        ([viewId, view]) => [
-          ...Object.entries(view.createdRecordsById ?? {}).map(
-            ([recordId, record]) => ({
-              eventType: "airtable.record.movedIntoView" as const,
-              payload: AIRTABLE_RECORD_MOVED_INTO_VIEW_EVENT_SCHEMA.parse({
-                ...recordEventBase(event, baseId, tableId, recordId),
-                createdAt: record.createdTime,
-                fields: record.cellValuesByFieldId,
-                viewId,
-              }),
+        ...Object.entries(table.changedFieldsById ?? {}).map(
+          ([fieldId, field]) => ({
+            eventType: "airtable.field.updated" as const,
+            payload: AIRTABLE_FIELD_UPDATED_EVENT_SCHEMA.parse({
+              ...fieldEventBase(event, baseId, tableId, fieldId),
+              current: field.current,
+              previous: field.previous,
             }),
+          }),
+        ),
+        ...(table.destroyedFieldIds ?? []).map((fieldId) => ({
+          eventType: "airtable.field.deleted" as const,
+          payload: AIRTABLE_FIELD_DELETED_EVENT_SCHEMA.parse(
+            fieldEventBase(event, baseId, tableId, fieldId),
           ),
-          ...(view.destroyedRecordIds ?? []).map((recordId) => ({
-            eventType: "airtable.record.movedOutOfView" as const,
-            payload: AIRTABLE_RECORD_MOVED_OUT_OF_VIEW_EVENT_SCHEMA.parse({
+        })),
+        ...Object.entries(table.createdRecordsById ?? {}).map(
+          ([recordId, record]) => ({
+            eventType: "airtable.record.created" as const,
+            payload: AIRTABLE_RECORD_CREATED_EVENT_SCHEMA.parse({
               ...recordEventBase(event, baseId, tableId, recordId),
-              viewId,
+              createdAt: record.createdTime,
+              fields: record.cellValuesByFieldId,
             }),
-          })),
-        ],
-      ),
-    ],
-  )
+          }),
+        ),
+        ...Object.entries(table.changedRecordsById ?? {}).map(
+          ([recordId, record]) => ({
+            eventType: "airtable.record.updated" as const,
+            payload: AIRTABLE_RECORD_UPDATED_EVENT_SCHEMA.parse({
+              ...recordEventBase(event, baseId, tableId, recordId),
+              changedFieldIds: Object.keys(record.current.cellValuesByFieldId),
+              fields: {
+                ...record.unchanged?.cellValuesByFieldId,
+                ...record.current.cellValuesByFieldId,
+              },
+              previousFields: {
+                ...record.unchanged?.cellValuesByFieldId,
+                ...record.previous?.cellValuesByFieldId,
+              },
+            }),
+          }),
+        ),
+        ...(table.destroyedRecordIds ?? []).map((recordId) => ({
+          eventType: "airtable.record.deleted" as const,
+          payload: AIRTABLE_RECORD_DELETED_EVENT_SCHEMA.parse(
+            recordEventBase(event, baseId, tableId, recordId),
+          ),
+        })),
+        ...Object.entries(table.changedViewsById ?? {}).flatMap(
+          ([viewId, view]) => [
+            ...Object.entries(view.createdRecordsById ?? {}).map(
+              ([recordId, record]) => ({
+                eventType: "airtable.record.movedIntoView" as const,
+                payload: AIRTABLE_RECORD_MOVED_INTO_VIEW_EVENT_SCHEMA.parse({
+                  ...recordEventBase(event, baseId, tableId, recordId),
+                  createdAt: record.createdTime,
+                  fields: record.cellValuesByFieldId,
+                  viewId,
+                }),
+              }),
+            ),
+            ...(view.destroyedRecordIds ?? []).map((recordId) => ({
+              eventType: "airtable.record.movedOutOfView" as const,
+              payload: AIRTABLE_RECORD_MOVED_OUT_OF_VIEW_EVENT_SCHEMA.parse({
+                ...recordEventBase(event, baseId, tableId, recordId),
+                viewId,
+              }),
+            })),
+          ],
+        ),
+      ],
+    ),
+  ]
+}
+
+/**
+ * Builds fields shared by every event in one Airtable transaction.
+ *
+ * @param event - Parsed provider transaction.
+ * @param baseId - Stable Airtable base ID.
+ */
+function baseEventBase(
+  event: z.output<typeof AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA>,
+  baseId: string,
+) {
+  return {
+    baseId,
+    event,
+    occurredAt: event.timestamp,
+    source: event.actionMetadata.source,
+    sourceMetadata: event.actionMetadata.sourceMetadata,
+    transactionNumber: event.baseTransactionNumber,
+  }
+}
+
+/**
+ * Adds a stable table ID to the shared Airtable event fields.
+ *
+ * @param event - Parsed provider transaction.
+ * @param baseId - Stable Airtable base ID.
+ * @param tableId - Stable Airtable table ID.
+ */
+function tableEventBase(
+  event: z.output<typeof AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA>,
+  baseId: string,
+  tableId: string,
+) {
+  return { ...baseEventBase(event, baseId), tableId }
+}
+
+/**
+ * Adds stable table and field IDs to the shared Airtable event fields.
+ *
+ * @param event - Parsed provider transaction.
+ * @param baseId - Stable Airtable base ID.
+ * @param tableId - Stable Airtable table ID.
+ * @param fieldId - Stable Airtable field ID.
+ */
+function fieldEventBase(
+  event: z.output<typeof AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA>,
+  baseId: string,
+  tableId: string,
+  fieldId: string,
+) {
+  return { ...tableEventBase(event, baseId, tableId), fieldId }
 }
 
 /**
@@ -219,13 +456,7 @@ function recordEventBase(
   recordId: string,
 ) {
   return {
-    baseId,
-    event,
-    occurredAt: event.timestamp,
+    ...tableEventBase(event, baseId, tableId),
     recordId,
-    source: event.actionMetadata.source,
-    sourceMetadata: event.actionMetadata.sourceMetadata,
-    tableId,
-    transactionNumber: event.baseTransactionNumber,
   }
 }

package/src/brevo/api.ts

@@ -10,6 +10,64 @@ const BREVO_ERROR_SCHEMA = z.looseObject({
   message: z.string().optional(),
 })
 
+/** Provider rate-limit values returned with a Brevo response. */
+export interface BrevoRateLimitMetadata {
+  /** Maximum requests allowed in the current window. */
+  limit?: number
+
+  /** Requests remaining in the current window. */
+  remaining?: number
+
+  /** Seconds until the current window resets. */
+  reset?: number
+}
+
+/** Structured failure returned by the Brevo API. */
+export class BrevoApiError extends Error {
+  /** Provider error classification. */
+  readonly code?: string
+
+  /** API path that failed. */
+  readonly path: string
+
+  /** Provider rate-limit metadata. */
+  readonly rateLimit: BrevoRateLimitMetadata
+
+  /** Delay in seconds before the request should be retried. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by Brevo. */
+  readonly status: number
+
+  /**
+   * Creates a structured Brevo provider error.
+   *
+   * @param options - Provider and transport failure details.
+   * @param options.code - Provider error classification.
+   * @param options.message - Human-readable provider failure.
+   * @param options.path - API path that failed.
+   * @param options.rateLimit - Provider rate-limit metadata.
+   * @param options.retryAfter - Provider retry delay in seconds.
+   * @param options.status - HTTP status.
+   */
+  constructor(options: {
+    code?: string
+    message: string
+    path: string
+    rateLimit: BrevoRateLimitMetadata
+    retryAfter?: number
+    status: number
+  }) {
+    super(`Brevo ${options.path} failed: ${options.message}`)
+    this.name = "BrevoApiError"
+    this.code = options.code
+    this.path = options.path
+    this.rateLimit = options.rateLimit
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
 /** Options accepted by the authenticated Brevo request helper. */
 export interface BrevoRequestOptions extends RequestInit {
   /** Query parameters appended to the request URL. */
@@ -63,14 +121,25 @@ export function getBrevoApi(secret: Record<string, unknown>) {
       const response = await fetch(url, { ...requestInit, headers })
       if (response.ok) return response
 
-      const error = BREVO_ERROR_SCHEMA.safeParse(
-        await response.json().catch(() => ({})),
-      )
-      throw new Error(
-        error.success && error.data.message
-          ? `Brevo API error (${response.status}): ${error.data.message}`
-          : `Brevo API request failed with status ${response.status}.`,
-      )
+      const responseText = await response.text()
+      const error = BREVO_ERROR_SCHEMA.safeParse(parseJson(responseText))
+      throw new BrevoApiError({
+        code: error.success ? error.data.code : undefined,
+        message:
+          (error.success ? error.data.message : undefined) ??
+          (responseText.trim() || `HTTP ${response.status}`),
+        path: `${url.pathname}${url.search}`,
+        rateLimit: {
+          limit: parseNumberHeader(response.headers, "x-sib-ratelimit-limit"),
+          remaining: parseNumberHeader(
+            response.headers,
+            "x-sib-ratelimit-remaining",
+          ),
+          reset: parseNumberHeader(response.headers, "x-sib-ratelimit-reset"),
+        },
+        retryAfter: parseNumberHeader(response.headers, "retry-after"),
+        status: response.status,
+      })
     },
   }
 }
@@ -87,3 +156,29 @@ export async function parseBrevoResponse<T extends z.ZodType>(
 ): Promise<z.output<T>> {
   return schema.parse(await response.json())
 }
+
+/**
+ * Parses provider JSON without hiding non-JSON error bodies.
+ *
+ * @param value - Provider response text.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Parses an optional numeric HTTP header.
+ *
+ * @param headers - Provider response headers.
+ * @param name - Case-insensitive header name.
+ */
+function parseNumberHeader(headers: Headers, name: string) {
+  const value = headers.get(name)
+  if (value === null) return undefined
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}