@automate.ax/integration-contracts 0.55.0

package/dist/airtable/schemas.js

@@ -0,0 +1,184 @@
+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",
+];
+/**
+ * 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, baseId) {
+    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",
+            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",
+            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",
+            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",
+                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",
+                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, baseId, tableId, recordId) {
+    return {
+        baseId,
+        event,
+        occurredAt: event.timestamp,
+        recordId,
+        source: event.actionMetadata.source,
+        sourceMetadata: event.actionMetadata.sourceMetadata,
+        tableId,
+        transactionNumber: event.baseTransactionNumber,
+    };
+}

package/dist/asana/api.d.ts

@@ -0,0 +1,70 @@
+import type { JsonObject } from "type-fest";
+import { z } from "zod";
+/** 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 declare 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;
+    });
+}
+/**
+ * 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 declare function getAsanaApi(secret: Record<string, unknown>): AsanaApi;
+export {};

package/dist/asana/api.js

@@ -0,0 +1,119 @@
+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(),
+});
+/** Structured error returned by an authenticated Asana API request. */
+export class AsanaApiError extends Error {
+    /** Asana troubleshooting link, when supplied. */
+    help;
+    /** API path that failed. */
+    path;
+    /** Asana support phrase for provider-side errors. */
+    phrase;
+    /** Retry delay from Asana's `Retry-After` header, in seconds. */
+    retryAfter;
+    /** HTTP status returned by Asana. */
+    status;
+    /**
+     * 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) {
+        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) {
+    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;
+            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) {
+    if (value === null)
+        return undefined;
+    const seconds = Number(value);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}