@automate.ax/integration-contracts 0.55.0

package/src/airtable/schemas.ts

@@ -0,0 +1,231 @@
+import { z } from "zod"
+
+const AIRTABLE_FIELDS_BY_ID_SCHEMA = z.record(z.string(), z.json())
+const AIRTABLE_ACTION_METADATA_SCHEMA = z
+  .looseObject({
+    /** Airtable system that caused the transaction. */
+    source: z.string(),
+
+    /** Provider-specific actor or source details. */
+    sourceMetadata: z.record(z.string(), z.json()).optional(),
+  })
+  .catchall(z.json())
+const AIRTABLE_CREATED_RECORD_SCHEMA = z.looseObject({
+  cellValuesByFieldId: AIRTABLE_FIELDS_BY_ID_SCHEMA,
+  createdTime: z.iso.datetime({ offset: true }),
+})
+const AIRTABLE_CHANGED_RECORD_SCHEMA = z.looseObject({
+  current: z.looseObject({
+    cellValuesByFieldId: AIRTABLE_FIELDS_BY_ID_SCHEMA,
+  }),
+  previous: z
+    .looseObject({ cellValuesByFieldId: AIRTABLE_FIELDS_BY_ID_SCHEMA })
+    .optional(),
+  unchanged: z
+    .looseObject({ cellValuesByFieldId: AIRTABLE_FIELDS_BY_ID_SCHEMA })
+    .optional(),
+})
+const AIRTABLE_VIEW_CHANGE_SCHEMA = z.looseObject({
+  changedRecordsById: z
+    .record(z.string(), AIRTABLE_CHANGED_RECORD_SCHEMA)
+    .optional(),
+  createdRecordsById: z
+    .record(z.string(), AIRTABLE_CREATED_RECORD_SCHEMA)
+    .optional(),
+  destroyedRecordIds: z.string().array().optional(),
+})
+const AIRTABLE_TABLE_CHANGE_SCHEMA = z.looseObject({
+  changedRecordsById: z
+    .record(z.string(), AIRTABLE_CHANGED_RECORD_SCHEMA)
+    .optional(),
+  changedViewsById: z
+    .record(z.string(), AIRTABLE_VIEW_CHANGE_SCHEMA)
+    .optional(),
+  createdRecordsById: z
+    .record(z.string(), AIRTABLE_CREATED_RECORD_SCHEMA)
+    .optional(),
+  destroyedRecordIds: z.string().array().optional(),
+})
+
+/** One provider-native Airtable webhook transaction payload. */
+export const AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA = z
+  .looseObject({
+    actionMetadata: AIRTABLE_ACTION_METADATA_SCHEMA,
+    baseTransactionNumber: z.number().int().nonnegative(),
+    changedTablesById: z
+      .record(z.string(), AIRTABLE_TABLE_CHANGE_SCHEMA)
+      .optional(),
+    code: z.string().optional(),
+    error: z.literal(true).optional(),
+    payloadFormat: z.string(),
+    timestamp: z.iso.datetime({ offset: true }),
+  })
+  .catchall(z.json())
+
+const AIRTABLE_RECORD_EVENT_SCHEMA = z.object({
+  /** Airtable base containing the affected record. */
+  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 }),
+
+  /** Stable Airtable record ID. */
+  recordId: z.string(),
+
+  /** Airtable system that caused the transaction. */
+  source: z.string(),
+
+  /** Provider-specific actor or source details. */
+  sourceMetadata: z.record(z.string(), z.json()).optional(),
+
+  /** Stable Airtable table ID. */
+  tableId: z.string(),
+
+  /** Base-scoped transaction number assigned by Airtable. */
+  transactionNumber: z.number().int().nonnegative(),
+})
+
+export const AIRTABLE_RECORD_CREATED_EVENT_SCHEMA =
+  AIRTABLE_RECORD_EVENT_SCHEMA.extend({
+    /** Time at which Airtable originally created the record. */
+    createdAt: z.iso.datetime({ offset: true }),
+
+    /** Current cell values keyed by stable field ID. */
+    fields: AIRTABLE_FIELDS_BY_ID_SCHEMA,
+  })
+
+export const AIRTABLE_RECORD_UPDATED_EVENT_SCHEMA =
+  AIRTABLE_RECORD_EVENT_SCHEMA.extend({
+    /** Stable IDs of fields changed by this transaction. */
+    changedFieldIds: z.string().array(),
+
+    /** Current cell values keyed by stable field ID. */
+    fields: AIRTABLE_FIELDS_BY_ID_SCHEMA,
+
+    /** Cell values before this transaction, keyed by stable field ID. */
+    previousFields: AIRTABLE_FIELDS_BY_ID_SCHEMA,
+  })
+
+export const AIRTABLE_RECORD_DELETED_EVENT_SCHEMA = AIRTABLE_RECORD_EVENT_SCHEMA
+
+export const AIRTABLE_RECORD_MOVED_INTO_VIEW_EVENT_SCHEMA =
+  AIRTABLE_RECORD_CREATED_EVENT_SCHEMA.extend({
+    /** Stable ID of the view the record entered. */
+    viewId: z.string(),
+  })
+
+export const AIRTABLE_RECORD_MOVED_OUT_OF_VIEW_EVENT_SCHEMA =
+  AIRTABLE_RECORD_EVENT_SCHEMA.extend({
+    /** Stable ID of the view the record exited. */
+    viewId: z.string(),
+  })
+
+export const AIRTABLE_RECORD_EVENT_TYPES = [
+  "airtable.record.created",
+  "airtable.record.updated",
+  "airtable.record.deleted",
+  "airtable.record.movedIntoView",
+  "airtable.record.movedOutOfView",
+] as const
+
+export type AirtableRecordEventType =
+  (typeof AIRTABLE_RECORD_EVENT_TYPES)[number]
+
+/**
+ * Expands one Airtable webhook transaction into semantic record 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) {
+  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,
+          }),
+        }),
+      ),
+      ...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 normalized Airtable record event.
+ *
+ * @param event - Parsed provider transaction.
+ * @param baseId - Base containing the changed record.
+ * @param tableId - Table containing the changed record.
+ * @param recordId - Stable ID of the changed record.
+ */
+function recordEventBase(
+  event: z.output<typeof AIRTABLE_WEBHOOK_PAYLOAD_SCHEMA>,
+  baseId: string,
+  tableId: string,
+  recordId: string,
+) {
+  return {
+    baseId,
+    event,
+    occurredAt: event.timestamp,
+    recordId,
+    source: event.actionMetadata.source,
+    sourceMetadata: event.actionMetadata.sourceMetadata,
+    tableId,
+    transactionNumber: event.baseTransactionNumber,
+  }
+}

package/src/asana/api.ts

@@ -0,0 +1,171 @@
+import type { JsonObject } from "type-fest"
+import { z } from "zod"
+
+const ASANA_API_BASE_URL = "https://app.asana.com/api/1.0"
+const ASANA_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+const ASANA_ERROR_RESPONSE_SCHEMA = z.looseObject({
+  errors: z
+    .looseObject({
+      help: z.string().optional(),
+      message: z.string(),
+      phrase: z.string().optional(),
+    })
+    .array()
+    .optional(),
+})
+
+/** Scalar value serialized into one Asana query parameter. */
+type AsanaQueryValue = boolean | number | string | undefined
+
+/** Options for an authenticated Asana REST API request. */
+export interface AsanaApiCallOptions<TSchema extends z.ZodType> {
+  /**
+   * Provider-native JSON body. Automatically wrapped in Asana's `data`
+   * envelope.
+   */
+  body?: JsonObject
+
+  /** HTTP method. Defaults to `POST` with a body and `GET` otherwise. */
+  httpMethod?: "DELETE" | "GET" | "POST" | "PUT"
+
+  /** Provider-native URL query parameters. */
+  query?: Record<string, AsanaQueryValue>
+
+  /** Schema for the complete successful Asana response envelope. */
+  responseSchema: TSchema
+}
+
+/** Authenticated Asana REST API helper for custom actions. */
+export interface AsanaApi {
+  /**
+   * Calls an Asana REST endpoint and validates its successful response.
+   *
+   * @param path - API path such as `/tasks/123`.
+   * @param options - Request data and response schema.
+   */
+  call<TSchema extends z.ZodType>(
+    path: string,
+    options: AsanaApiCallOptions<TSchema>,
+  ): Promise<z.output<TSchema>>
+}
+
+/** Structured error returned by an authenticated Asana API request. */
+export class AsanaApiError extends Error {
+  /** Asana troubleshooting link, when supplied. */
+  readonly help?: string
+
+  /** API path that failed. */
+  readonly path: string
+
+  /** Asana support phrase for provider-side errors. */
+  readonly phrase?: string
+
+  /** Retry delay from Asana's `Retry-After` header, in seconds. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by Asana. */
+  readonly status: number
+
+  /**
+   * Creates a structured Asana API error.
+   *
+   * @param options - Provider and transport error details.
+   * @param options.help - Provider troubleshooting link.
+   * @param options.message - Human-readable error message.
+   * @param options.path - API path that failed.
+   * @param options.phrase - Asana support phrase.
+   * @param options.retryAfter - Retry delay in seconds.
+   * @param options.status - HTTP response status.
+   */
+  constructor(options: {
+    help?: string
+    message: string
+    path: string
+    phrase?: string
+    retryAfter?: number
+    status: number
+  }) {
+    super(`Asana ${options.path} failed: ${options.message}`)
+    this.name = "AsanaApiError"
+    this.help = options.help
+    this.path = options.path
+    this.phrase = options.phrase
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates a raw authenticated Asana REST API helper.
+ *
+ * Use this escape hatch for endpoints without packaged actions. Callers provide
+ * a Zod schema so custom responses remain validated at the provider boundary.
+ *
+ * @param secret - Resolved Asana integration secret.
+ */
+export function getAsanaApi(secret: Record<string, unknown>): AsanaApi {
+  const { accessToken } = ASANA_SECRET_SCHEMA.parse(secret)
+
+  return {
+    call: async (path, options) => {
+      const normalizedPath = path.startsWith("/") ? path : `/${path}`
+      const url = new URL(`${ASANA_API_BASE_URL}${normalizedPath}`)
+      for (const [name, value] of Object.entries(options.query ?? {})) {
+        if (value !== undefined) url.searchParams.set(name, String(value))
+      }
+
+      const response = await fetch(url, {
+        body: options.body ? JSON.stringify({ data: options.body }) : undefined,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${accessToken}`,
+          ...(options.body && { "Content-Type": "application/json" }),
+        },
+        method:
+          options.httpMethod ?? (options.body === undefined ? "GET" : "POST"),
+      })
+      const responseBody = await response.text()
+      let payload: unknown
+      try {
+        payload = JSON.parse(responseBody)
+      } catch (cause) {
+        if (response.ok) throw cause
+        throw new AsanaApiError({
+          message: responseBody.trim() || `HTTP ${response.status}`,
+          path: normalizedPath,
+          retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+          status: response.status,
+        })
+      }
+      if (!response.ok) {
+        const errorResult = ASANA_ERROR_RESPONSE_SCHEMA.safeParse(payload)
+        const error = errorResult.success
+          ? errorResult.data.errors?.[0]
+          : undefined
+        throw new AsanaApiError({
+          help: error?.help,
+          message: error?.message ?? `HTTP ${response.status}`,
+          path: normalizedPath,
+          phrase: error?.phrase,
+          retryAfter: parseRetryAfter(response.headers.get("Retry-After")),
+          status: response.status,
+        })
+      }
+
+      return options.responseSchema.parse(payload)
+    },
+  }
+}
+
+/**
+ * Parses Asana's integer retry delay header.
+ *
+ * @param value - Raw `Retry-After` header.
+ */
+function parseRetryAfter(value: string | null) {
+  if (value === null) return undefined
+  const seconds = Number(value)
+  return Number.isFinite(seconds) ? seconds : undefined
+}

package/src/asana/index.ts

@@ -0,0 +1,49 @@
+import { z } from "zod"
+import {
+  ASANA_COMMENT_ADDED_EVENT_SCHEMA,
+  ASANA_EVENT_SCHEMA,
+  ASANA_TASK_ADDED_EVENT_SCHEMA,
+  ASANA_TASK_CHANGED_EVENT_SCHEMA,
+  ASANA_TASK_COMPLETED_EVENT_SCHEMA,
+  ASANA_TASK_DELETED_EVENT_SCHEMA,
+  ASANA_TASK_REMOVED_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./api"
+export * from "./schemas"
+
+/** Asana resource selected for one webhook subscription. */
+export const ASANA_TRIGGER_CONFIG_SCHEMA = z.object({
+  resourceId: z.string(),
+})
+
+export const asanaTriggerContracts = {
+  "asana.comment.added": {
+    configSchema: ASANA_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: ASANA_COMMENT_ADDED_EVENT_SCHEMA,
+  },
+  "asana.event": {
+    configSchema: ASANA_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: ASANA_EVENT_SCHEMA,
+  },
+  "asana.task.added": {
+    configSchema: ASANA_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: ASANA_TASK_ADDED_EVENT_SCHEMA,
+  },
+  "asana.task.changed": {
+    configSchema: ASANA_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: ASANA_TASK_CHANGED_EVENT_SCHEMA,
+  },
+  "asana.task.completed": {
+    configSchema: ASANA_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: ASANA_TASK_COMPLETED_EVENT_SCHEMA,
+  },
+  "asana.task.deleted": {
+    configSchema: ASANA_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: ASANA_TASK_DELETED_EVENT_SCHEMA,
+  },
+  "asana.task.removed": {
+    configSchema: ASANA_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: ASANA_TASK_REMOVED_EVENT_SCHEMA,
+  },
+} as const