@relayfile/adapter-airtable 0.1.0

package/dist/airtable-adapter.js

@@ -0,0 +1,705 @@
+import { airtableBasePath, airtableRecordPath, airtableTablePath, computeAirtablePath, normalizeAirtableObjectType, } from './path-mapper.js';
+import { AIRTABLE_WEBHOOK_OBJECT_TYPES } from './types.js';
+export class IntegrationAdapter {
+    client;
+    provider;
+    constructor(client, provider) {
+        this.client = client;
+        this.provider = provider;
+    }
+}
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+const SUPPORTED_EVENTS = AIRTABLE_WEBHOOK_OBJECT_TYPES;
+const AIRTABLE_PROVIDER_NAME = 'airtable';
+export class AirtableAdapter extends IntegrationAdapter {
+    name = AIRTABLE_PROVIDER_NAME;
+    version = '0.1.0';
+    config;
+    constructor(client, provider, config = {}) {
+        super(client, provider);
+        this.config = config;
+    }
+    supportedEvents() {
+        return SUPPORTED_EVENTS.flatMap((objectType) => [
+            `${objectType}.create`,
+            `${objectType}.update`,
+            `${objectType}.delete`,
+        ]);
+    }
+    async ingestWebhook(workspaceId, event) {
+        try {
+            const normalized = this.normalizeEvent(event);
+            const context = this.resolveContext(normalized.payload);
+            const path = computeAirtablePath(normalized.objectType, normalized.objectId, context);
+            const semantics = this.computeSemantics(normalized.objectType, normalized.objectId, normalized.payload);
+            if (this.isDeleteEvent(normalized)) {
+                if (this.client.deleteFile) {
+                    await this.client.deleteFile({ workspaceId, path });
+                    return {
+                        errors: [],
+                        filesDeleted: 1,
+                        filesUpdated: 0,
+                        filesWritten: 0,
+                        paths: [path],
+                    };
+                }
+                const deleteResult = await this.client.writeFile({
+                    workspaceId,
+                    path,
+                    content: this.renderContent(workspaceId, normalized, true),
+                    contentType: JSON_CONTENT_TYPE,
+                    semantics,
+                });
+                const counts = inferWriteCounts(deleteResult, true);
+                return {
+                    errors: [],
+                    filesDeleted: counts.filesDeleted,
+                    filesUpdated: counts.filesUpdated,
+                    filesWritten: counts.filesWritten,
+                    paths: [path],
+                };
+            }
+            const writeResult = await this.client.writeFile({
+                workspaceId,
+                path,
+                content: this.renderContent(workspaceId, normalized, false),
+                contentType: JSON_CONTENT_TYPE,
+                semantics,
+            });
+            const counts = inferWriteCounts(writeResult, false);
+            return {
+                errors: [],
+                filesDeleted: 0,
+                filesUpdated: counts.filesUpdated,
+                filesWritten: counts.filesWritten,
+                paths: [path],
+            };
+        }
+        catch (error) {
+            const fallbackPath = inferFallbackPath(event);
+            return {
+                errors: [
+                    {
+                        error: toErrorMessage(error),
+                        path: fallbackPath,
+                    },
+                ],
+                filesDeleted: 0,
+                filesUpdated: 0,
+                filesWritten: 0,
+                paths: fallbackPath ? [fallbackPath] : [],
+            };
+        }
+    }
+    computePath(objectType, objectId, context = {}) {
+        return computeAirtablePath(objectType, objectId, mergeContext(context, this.config));
+    }
+    computeSemantics(objectType, objectId, payload) {
+        const normalizedType = normalizeAirtableObjectType(objectType);
+        const context = this.resolveContext(payload);
+        const properties = {
+            provider: AIRTABLE_PROVIDER_NAME,
+            'provider.object_id': objectId,
+            'provider.object_type': normalizedType,
+            'airtable.id': objectId,
+            'airtable.object_type': normalizedType,
+        };
+        const relations = new Set();
+        const comments = [];
+        addStringProperty(properties, 'airtable.base_id', context.baseId);
+        addStringProperty(properties, 'airtable.table_id', context.tableId);
+        const webhook = getRecord(payload._webhook);
+        if (webhook) {
+            addStringProperty(properties, 'airtable.webhook.action', webhook.action);
+            addStringProperty(properties, 'airtable.webhook.delivery_id', webhook.deliveryId);
+            addStringProperty(properties, 'airtable.webhook.event_type', webhook.eventType);
+            addStringProperty(properties, 'airtable.webhook.object_id', webhook.objectId);
+            addStringProperty(properties, 'airtable.webhook.object_type', webhook.objectType);
+            addNumberProperty(properties, 'airtable.webhook.timestamp', webhook.webhookTimestamp);
+        }
+        if (context.baseId && normalizedType !== 'base') {
+            relations.add(airtableBasePath(context.baseId));
+        }
+        if (context.baseId && context.tableId && normalizedType === 'record') {
+            relations.add(airtableTablePath(context.baseId, context.tableId));
+        }
+        switch (normalizedType) {
+            case 'record':
+                applyRecordSemantics(properties, relations, comments, payload, context);
+                break;
+            case 'table':
+                applyTableSemantics(properties, relations, comments, payload, context);
+                break;
+            case 'base':
+                applyBaseSemantics(properties, relations, payload);
+                break;
+        }
+        const semantics = {
+            properties,
+            relations: sortStrings(relations),
+        };
+        if (comments.length > 0) {
+            semantics.comments = comments;
+        }
+        return compactSemantics(semantics);
+    }
+    normalizeEvent(event) {
+        if (isNormalizedWebhook(event)) {
+            const normalized = {
+                provider: event.provider || this.config.provider || AIRTABLE_PROVIDER_NAME,
+                eventType: canonicalEventType(event.eventType, event.objectType),
+                objectType: normalizeAirtableObjectType(event.objectType),
+                objectId: event.objectId.trim(),
+                payload: event.payload,
+            };
+            const connectionId = event.connectionId || this.config.connectionId;
+            if (connectionId) {
+                normalized.connectionId = connectionId;
+            }
+            return normalized;
+        }
+        const objectType = normalizeAirtableObjectType(readPayloadObjectType(event));
+        const payload = mergeAirtablePayload(event, objectType, this.config);
+        const objectId = readObjectId(payload, objectType);
+        if (!objectId) {
+            throw new Error(`Airtable ${objectType} webhook is missing object id`);
+        }
+        const action = normalizeAction(asString(event.action) ??
+            asString(event.eventType)?.split('.').at(-1) ??
+            'update');
+        const normalized = {
+            provider: this.config.provider || AIRTABLE_PROVIDER_NAME,
+            eventType: `${objectType}.${action}`,
+            objectType,
+            objectId,
+            payload,
+        };
+        if (this.config.connectionId) {
+            normalized.connectionId = this.config.connectionId;
+        }
+        return normalized;
+    }
+    resolveContext(payload) {
+        const base = getRecord(payload.base);
+        const table = getRecord(payload.table);
+        const data = getRecord(payload.data);
+        const dataBase = getRecord(data?.base);
+        const dataTable = getRecord(data?.table);
+        const context = {};
+        const baseId = asString(payload.baseId) ??
+            asString(payload.base_id) ??
+            asString(base?.id) ??
+            asString(data?.baseId) ??
+            asString(data?.base_id) ??
+            asString(dataBase?.id) ??
+            this.config.baseId;
+        if (baseId) {
+            context.baseId = baseId;
+        }
+        const tableId = asString(payload.tableId) ??
+            asString(payload.table_id) ??
+            asString(table?.id) ??
+            asString(data?.tableId) ??
+            asString(data?.table_id) ??
+            asString(dataTable?.id) ??
+            this.config.tableId;
+        if (tableId) {
+            context.tableId = tableId;
+        }
+        return context;
+    }
+    isDeleteEvent(event) {
+        const action = getWebhookAction(event.payload) ?? getEventAction(event.eventType);
+        return action === 'delete';
+    }
+    renderContent(workspaceId, event, deleted) {
+        return stableJson({
+            provider: event.provider,
+            connectionId: event.connectionId ?? null,
+            workspaceId,
+            eventType: event.eventType,
+            objectType: normalizeAirtableObjectType(event.objectType),
+            objectId: event.objectId,
+            deleted,
+            payload: event.payload,
+        });
+    }
+}
+function applyRecordSemantics(properties, relations, comments, payload, context) {
+    const record = payload;
+    const fields = getRecord(record.fields);
+    addFirstStringProperty(properties, 'airtable.created_time', record.createdTime, record.created_time);
+    addFirstStringProperty(properties, 'airtable.updated_time', record.updatedTime, record.updated_time);
+    addFirstStringProperty(properties, 'airtable.table_name', record.tableName, record.table_name);
+    addNumberProperty(properties, 'airtable.comment_count', record.commentCount);
+    if (fields) {
+        const fieldEntries = Object.entries(fields)
+            .filter(([, value]) => value !== undefined && value !== null)
+            .sort(([left], [right]) => left.localeCompare(right));
+        properties['airtable.field_count'] = String(fieldEntries.length);
+        for (const [fieldName, value] of fieldEntries) {
+            const key = slugPropertyKey(fieldName);
+            const propertyValue = stringifyFieldValue(value);
+            if (propertyValue) {
+                properties[`airtable.field.${key}`] = propertyValue;
+            }
+            collectFieldRelations(relations, value, context);
+        }
+        const recordTitle = firstNonEmptyString(fields.Name, fields.name, fields.Title, fields.title, fields.Subject, fields.subject);
+        addStringProperty(properties, 'airtable.record_title', recordTitle);
+        const notes = firstNonEmptyString(fields.Notes, fields.notes, fields.Description, fields.description);
+        if (notes) {
+            comments.push(notes);
+            properties['airtable.notes_length'] = String(notes.length);
+        }
+    }
+}
+function applyTableSemantics(properties, relations, comments, payload, context) {
+    const table = payload;
+    addStringProperty(properties, 'airtable.name', table.name);
+    addStringProperty(properties, 'airtable.primary_field_id', table.primaryFieldId);
+    addFirstStringProperty(properties, 'airtable.description', table.description);
+    addFirstStringProperty(properties, 'airtable.created_time', table.createdTime, table.created_time);
+    addFirstStringProperty(properties, 'airtable.updated_time', table.updatedTime, table.updated_time);
+    const base = table.base;
+    const baseId = asString(base?.id) ?? context.baseId;
+    if (baseId) {
+        relations.add(airtableBasePath(baseId));
+        addStringProperty(properties, 'airtable.base_id', baseId);
+    }
+    addStringProperty(properties, 'airtable.base_name', base?.name);
+    const fields = asFields(table.fields);
+    if (fields.length > 0) {
+        properties['airtable.field_count'] = String(fields.length);
+        addStringListProperty(properties, 'airtable.field_ids', fields.map((field) => field.id));
+        addStringListProperty(properties, 'airtable.field_names', fields.map((field) => field.name));
+        addStringListProperty(properties, 'airtable.field_types', uniqueStrings(fields.map((field) => field.type).filter(isString)));
+        for (const field of fields) {
+            const key = slugPropertyKey(field.name);
+            addStringProperty(properties, `airtable.schema.${key}.id`, field.id);
+            addStringProperty(properties, `airtable.schema.${key}.type`, field.type);
+            addStringProperty(properties, `airtable.schema.${key}.description`, field.description);
+        }
+    }
+    const views = asViews(table.views);
+    if (views.length > 0) {
+        properties['airtable.view_count'] = String(views.length);
+        addStringListProperty(properties, 'airtable.view_ids', views.map((view) => view.id));
+        addStringListProperty(properties, 'airtable.view_names', views.map((view) => view.name));
+    }
+    const description = asString(table.description);
+    if (description) {
+        comments.push(description);
+        properties['airtable.description_length'] = String(description.length);
+    }
+}
+function applyBaseSemantics(properties, relations, payload) {
+    const base = payload;
+    addStringProperty(properties, 'airtable.name', base.name);
+    addStringProperty(properties, 'airtable.permission_level', base.permissionLevel);
+    addFirstStringProperty(properties, 'airtable.created_time', base.createdTime, base.created_time);
+    const workspace = base.workspace;
+    addStringProperty(properties, 'airtable.workspace_id', workspace?.id);
+    addStringProperty(properties, 'airtable.workspace_name', workspace?.name);
+    const tables = asTables(base.tables);
+    if (tables.length > 0) {
+        properties['airtable.table_count'] = String(tables.length);
+        addStringListProperty(properties, 'airtable.table_ids', tables.map((table) => table.id));
+        addStringListProperty(properties, 'airtable.table_names', tables.map((table) => table.name).filter(isString));
+        const baseId = asString(base.id);
+        if (baseId) {
+            for (const table of tables) {
+                relations.add(airtableTablePath(baseId, table.id));
+            }
+        }
+    }
+}
+function collectFieldRelations(relations, value, context) {
+    if (!context.baseId || !context.tableId) {
+        return;
+    }
+    if (typeof value === 'string' && /^rec[a-zA-Z0-9_-]+$/u.test(value)) {
+        relations.add(airtableRecordPath(context.baseId, context.tableId, value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectFieldRelations(relations, item, context);
+        }
+    }
+}
+function mergeAirtablePayload(event, objectType, config) {
+    const data = getRecord(event.data);
+    const payload = getRecord(event.payload);
+    const typedPayload = objectType === 'record'
+        ? getRecord(event.record) ?? data
+        : objectType === 'table'
+            ? getRecord(event.table) ?? data
+            : getRecord(event.base) ?? data;
+    const merged = {
+        ...(payload ?? {}),
+        ...(typedPayload ?? {}),
+        ...(data ?? {}),
+    };
+    const explicitId = asString(event.objectId) ?? asString(event.object_id);
+    if (explicitId && !asString(merged.id)) {
+        merged.id = explicitId;
+    }
+    const base = getRecord(event.base);
+    if (base) {
+        merged.base = base;
+    }
+    const table = getRecord(event.table);
+    if (table) {
+        merged.table = table;
+    }
+    const baseId = asString(event.baseId) ?? asString(event.base_id) ?? asString(base?.id) ?? config.baseId;
+    if (baseId) {
+        merged.baseId = baseId;
+    }
+    const tableId = asString(event.tableId) ?? asString(event.table_id) ?? asString(table?.id) ?? config.tableId;
+    if (tableId) {
+        merged.tableId = tableId;
+    }
+    merged.objectType = objectType;
+    merged._webhook = compactObject({
+        action: normalizeAction(asString(event.action) ?? asString(event.eventType)?.split('.').at(-1) ?? 'update'),
+        eventType: asString(event.eventType),
+        objectId: explicitId ?? asString(merged.id),
+        objectType,
+        webhookTimestamp: asNumber(event.webhookTimestamp) ?? asNumber(event.timestamp),
+    });
+    return merged;
+}
+function readPayloadObjectType(event) {
+    const data = getRecord(event.data);
+    const explicit = asString(event.objectType) ??
+        asString(event.object_type) ??
+        asString(event.type) ??
+        asString(event.eventType)?.split('.').at(0) ??
+        asString(data?.objectType) ??
+        asString(data?.object_type) ??
+        asString(data?.type);
+    if (explicit) {
+        return explicit;
+    }
+    if (getRecord(event.record) || (data && getRecord(data.fields))) {
+        return 'record';
+    }
+    if (getRecord(event.table) || (data && Array.isArray(data.fields))) {
+        return 'table';
+    }
+    if (getRecord(event.base) || (data && Array.isArray(data.tables))) {
+        return 'base';
+    }
+    throw new Error('Airtable webhook payload is missing object type');
+}
+function readObjectId(payload, objectType) {
+    const normalizedType = normalizeAirtableObjectType(objectType);
+    const data = getRecord(payload.data);
+    const typed = normalizedType === 'record'
+        ? getRecord(payload.record) ?? data
+        : normalizedType === 'table'
+            ? getRecord(payload.table) ?? data
+            : getRecord(payload.base) ?? data;
+    return (asString(typed?.id) ??
+        asString(payload.id) ??
+        asString(payload.objectId) ??
+        asString(payload.object_id));
+}
+function isNormalizedWebhook(event) {
+    return (typeof event.eventType === 'string' &&
+        typeof event.objectType === 'string' &&
+        typeof event.objectId === 'string' &&
+        isRecord(event.payload));
+}
+function canonicalEventType(eventType, objectType) {
+    const parts = eventType.trim().toLowerCase().split(/[.:]/u).filter(Boolean);
+    if (parts.length >= 2) {
+        return `${normalizeAirtableObjectType(parts[0] ?? objectType)}.${normalizeAction(parts[1] ?? 'update')}`;
+    }
+    return `${normalizeAirtableObjectType(objectType)}.${normalizeAction(eventType)}`;
+}
+function normalizeAction(action) {
+    const normalized = action.trim().toLowerCase();
+    switch (normalized) {
+        case 'add':
+        case 'added':
+        case 'create':
+        case 'created':
+        case 'insert':
+            return 'create';
+        case 'delete':
+        case 'deleted':
+        case 'destroy':
+        case 'remove':
+        case 'removed':
+            return 'delete';
+        case 'change':
+        case 'changed':
+        case 'modify':
+        case 'modified':
+        case 'update':
+        case 'updated':
+            return 'update';
+        default:
+            return normalized || 'update';
+    }
+}
+function getWebhookAction(payload) {
+    const webhook = getRecord(payload._webhook);
+    return normalizeOptionalAction(webhook?.action) ?? normalizeOptionalAction(payload.action);
+}
+function getEventAction(eventType) {
+    const action = eventType.split(/[.:]/u).filter(Boolean).at(-1);
+    return action ? normalizeAction(action) : undefined;
+}
+function normalizeOptionalAction(value) {
+    const string = asString(value);
+    return string ? normalizeAction(string) : undefined;
+}
+function inferWriteCounts(result, deleted) {
+    if (deleted) {
+        return {
+            filesDeleted: 1,
+            filesUpdated: 0,
+            filesWritten: result ? 1 : 0,
+        };
+    }
+    if (!result) {
+        return {
+            filesDeleted: 0,
+            filesUpdated: 0,
+            filesWritten: 1,
+        };
+    }
+    if (result.created || result.status === 'created') {
+        return {
+            filesDeleted: 0,
+            filesUpdated: 0,
+            filesWritten: 1,
+        };
+    }
+    if (result.updated || result.status === 'updated') {
+        return {
+            filesDeleted: 0,
+            filesUpdated: 1,
+            filesWritten: 0,
+        };
+    }
+    return {
+        filesDeleted: 0,
+        filesUpdated: 0,
+        filesWritten: 1,
+    };
+}
+function inferFallbackPath(event) {
+    try {
+        if (isNormalizedWebhook(event)) {
+            const objectType = normalizeAirtableObjectType(event.objectType);
+            return computeAirtablePath(objectType, event.objectId, contextFromPayload(event.payload));
+        }
+        const objectType = normalizeAirtableObjectType(readPayloadObjectType(event));
+        const payload = mergeAirtablePayload(event, objectType, {});
+        const objectId = readObjectId(payload, objectType) ?? 'unknown';
+        return computeAirtablePath(objectType, objectId, contextFromPayload(payload));
+    }
+    catch {
+        return '/airtable/unmapped-webhook.json';
+    }
+}
+function asFields(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(isAirtableField);
+}
+function mergeContext(context, config) {
+    const merged = {};
+    const baseId = context.baseId ?? config.baseId;
+    if (baseId) {
+        merged.baseId = baseId;
+    }
+    const tableId = context.tableId ?? config.tableId;
+    if (tableId) {
+        merged.tableId = tableId;
+    }
+    return merged;
+}
+function contextFromPayload(payload) {
+    const context = {};
+    const baseId = asString(payload.baseId);
+    if (baseId) {
+        context.baseId = baseId;
+    }
+    const tableId = asString(payload.tableId);
+    if (tableId) {
+        context.tableId = tableId;
+    }
+    return context;
+}
+function isAirtableField(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return Boolean(asString(value.id) && asString(value.name));
+}
+function asViews(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(isAirtableView);
+}
+function isAirtableView(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return Boolean(asString(value.id) && asString(value.name));
+}
+function asTables(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(isAirtableTable);
+}
+function isAirtableTable(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return Boolean(asString(value.id));
+}
+function addStringProperty(properties, key, value) {
+    const string = asString(value);
+    if (string) {
+        properties[key] = string;
+    }
+}
+function addFirstStringProperty(properties, key, ...values) {
+    for (const value of values) {
+        const string = asString(value);
+        if (string) {
+            properties[key] = string;
+            return;
+        }
+    }
+}
+function addNumberProperty(properties, key, value) {
+    const number = asNumber(value);
+    if (number !== undefined) {
+        properties[key] = String(number);
+    }
+}
+function addStringListProperty(properties, key, values) {
+    const cleaned = uniqueStrings(values);
+    if (cleaned.length > 0) {
+        properties[key] = cleaned.join(', ');
+    }
+}
+function compactSemantics(semantics) {
+    const compacted = {};
+    if (semantics.properties && Object.keys(semantics.properties).length > 0) {
+        compacted.properties = semantics.properties;
+    }
+    if (semantics.relations && semantics.relations.length > 0) {
+        compacted.relations = semantics.relations;
+    }
+    if (semantics.permissions && semantics.permissions.length > 0) {
+        compacted.permissions = semantics.permissions;
+    }
+    if (semantics.comments && semantics.comments.length > 0) {
+        compacted.comments = semantics.comments;
+    }
+    return compacted;
+}
+function compactObject(object) {
+    const compacted = {};
+    for (const [key, value] of Object.entries(object)) {
+        if (value !== undefined && value !== null) {
+            compacted[key] = value;
+        }
+    }
+    return compacted;
+}
+function sortStrings(values) {
+    return Array.from(new Set(values)).sort((left, right) => left.localeCompare(right));
+}
+function uniqueStrings(values) {
+    return sortStrings(values.filter(isString).map((value) => value.trim()).filter(Boolean));
+}
+function stringifyFieldValue(value) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'string') {
+        return value.trim() || undefined;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        const simpleValues = value.map(stringifyFieldValue).filter(isString);
+        return simpleValues.length > 0 ? simpleValues.join(', ') : undefined;
+    }
+    if (isRecord(value)) {
+        return stableJson(value);
+    }
+    return String(value);
+}
+function stableJson(value) {
+    return JSON.stringify(sortJson(value), null, 2);
+}
+function sortJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJson);
+    }
+    if (isRecord(value)) {
+        const sorted = {};
+        for (const key of Object.keys(value).sort((left, right) => left.localeCompare(right))) {
+            sorted[key] = sortJson(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function slugPropertyKey(value) {
+    const slug = value
+        .replace(/[^a-zA-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+    return slug || 'unnamed';
+}
+function firstNonEmptyString(...values) {
+    for (const value of values) {
+        const string = asString(value);
+        if (string) {
+            return string;
+        }
+    }
+    return undefined;
+}
+function asString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function asNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function isString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function getRecord(value) {
+    return isRecord(value) ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=airtable-adapter.js.map