@assembly-js/app-foundation 0.0.13 → 0.0.15

package/dist/airtable.d.ts

@@ -0,0 +1,71 @@
+import { type IntegrationClient } from './nango.js';
+export interface AirtableFieldSchema {
+    id: string;
+    name: string;
+    type: string;
+    options?: Record<string, unknown>;
+}
+export interface AirtableTableSchema {
+    id: string;
+    name: string;
+    primaryFieldId: string;
+    fields: AirtableFieldSchema[];
+}
+export interface AirtableRecord {
+    id: string;
+    createdTime?: string;
+    fields: Record<string, unknown>;
+}
+export interface AirtableFormattedField {
+    raw: unknown;
+    display: string;
+}
+export interface AirtableFormattedRecord {
+    id: string;
+    createdTime?: string;
+    fields: Record<string, AirtableFormattedField>;
+}
+export type AirtableSchemaResult = {
+    ok: true;
+    schema: AirtableTableSchema;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        provider: string;
+    };
+};
+export interface FormatAirtableRecordsOpts {
+    /** The getIntegration('airtable') client. Required to resolve linked-record labels. */
+    client?: IntegrationClient;
+    /** Base the records came from. Required to resolve linked-record labels. */
+    baseId?: string;
+}
+/**
+ * One table's schema from `get-base-schema` (fields with id, name, type,
+ * options). Memoized on the client for the rest of this request so a render
+ * that formats several pages does not refetch the base. Failures come back as
+ * `{ ok: false, error }` — ConnectorError does not survive a Server Action
+ * boundary.
+ *
+ * Server-side only: pass the client from `getIntegration('airtable')`.
+ */
+export declare function getAirtableTableSchema(client: IntegrationClient, baseId: string, tableIdOrName: string): Promise<AirtableSchemaResult>;
+/**
+ * For each record, return raw + display per field so sorts/edits keep machine
+ * values. Formats percent / currency / number / date / dateTime / duration from
+ * field options; resolves `multipleRecordLinks` ID arrays to the linked table's
+ * primary-field labels (one `list-records` per linked table, chunked
+ * `RECORD_ID()` filter, primary field only). Computed fields (formula / rollup /
+ * multipleLookupValues) format by their `options.result` inner type, reusing the
+ * same typed formatters; arrays (lookups) format each element and join. A cell
+ * that comes back as an error-state object (`{state:"error",errorType:...}`,
+ * `{error:"#ERROR!"}`) or a numeric special value (`{specialValue:"NaN"|"Infinity"}`)
+ * never reaches display as raw JSON — display becomes an em dash, raw is untouched.
+ * Unknown types pass through; arrays join with ", ". Linked-table failures degrade
+ * to the raw ID and never throw the render.
+ *
+ * Server-side only when `opts.client` is set (label lookup goes through the
+ * broker). Omit client/baseId to format in-memory types only.
+ */
+export declare function formatAirtableRecords(records: AirtableRecord[], schema: AirtableTableSchema, opts?: FormatAirtableRecordsOpts): Promise<AirtableFormattedRecord[]>;

package/dist/airtable.js

@@ -0,0 +1,561 @@
+import { ConnectorError } from './nango.js';
+// Airtable GET list-records puts filterByFormula on the query string. ~40
+// RECORD_ID() clauses stay comfortably under typical URL/formula limits
+// (a page of records can easily collect more linked IDs than that).
+const AIRTABLE_LINKED_ID_CHUNK = 40;
+// Keyed by the per-request client object so a warm serverless isolate cannot
+// serve another invocation's schema. Repeated calls in one render (same client)
+// share the in-flight get-base-schema promise.
+const baseSchemaByClient = new WeakMap();
+/**
+ * One table's schema from `get-base-schema` (fields with id, name, type,
+ * options). Memoized on the client for the rest of this request so a render
+ * that formats several pages does not refetch the base. Failures come back as
+ * `{ ok: false, error }` — ConnectorError does not survive a Server Action
+ * boundary.
+ *
+ * Server-side only: pass the client from `getIntegration('airtable')`.
+ */
+export async function getAirtableTableSchema(client, baseId, tableIdOrName) {
+    const wanted = tableIdOrName.trim();
+    if (!baseId.trim() || !wanted) {
+        return { ok: false, error: { code: 'invalid_request', provider: 'airtable' } };
+    }
+    const loaded = await loadBaseSchema(client, baseId);
+    if (!loaded.ok)
+        return loaded;
+    const table = loaded.tables.find((t) => t.id === wanted || t.name === wanted);
+    if (!table) {
+        return { ok: false, error: { code: 'table_not_found', provider: 'airtable' } };
+    }
+    return { ok: true, schema: table };
+}
+/**
+ * For each record, return raw + display per field so sorts/edits keep machine
+ * values. Formats percent / currency / number / date / dateTime / duration from
+ * field options; resolves `multipleRecordLinks` ID arrays to the linked table's
+ * primary-field labels (one `list-records` per linked table, chunked
+ * `RECORD_ID()` filter, primary field only). Computed fields (formula / rollup /
+ * multipleLookupValues) format by their `options.result` inner type, reusing the
+ * same typed formatters; arrays (lookups) format each element and join. A cell
+ * that comes back as an error-state object (`{state:"error",errorType:...}`,
+ * `{error:"#ERROR!"}`) or a numeric special value (`{specialValue:"NaN"|"Infinity"}`)
+ * never reaches display as raw JSON — display becomes an em dash, raw is untouched.
+ * Unknown types pass through; arrays join with ", ". Linked-table failures degrade
+ * to the raw ID and never throw the render.
+ *
+ * Server-side only when `opts.client` is set (label lookup goes through the
+ * broker). Omit client/baseId to format in-memory types only.
+ */
+export async function formatAirtableRecords(records, schema, opts = {}) {
+    const list = Array.isArray(records) ? records : [];
+    const fieldsByKey = indexFields(schema);
+    let labelsByTable = new Map();
+    try {
+        labelsByTable = await loadLinkedLabels(list, schema, opts);
+    }
+    catch {
+        // Linked-table I/O is best-effort; typed-column formatting still runs.
+    }
+    return list.map((record) => {
+        const fields = {};
+        for (const [key, raw] of Object.entries(record.fields ?? {})) {
+            const field = fieldsByKey.get(key);
+            fields[key] = {
+                raw,
+                display: displayForField(raw, field, labelsByTable),
+            };
+        }
+        return {
+            id: record.id,
+            ...(record.createdTime !== undefined ? { createdTime: record.createdTime } : {}),
+            fields,
+        };
+    });
+}
+function loadBaseSchema(client, baseId) {
+    let byBase = baseSchemaByClient.get(client);
+    if (!byBase) {
+        byBase = new Map();
+        baseSchemaByClient.set(client, byBase);
+    }
+    const cached = byBase.get(baseId);
+    if (cached)
+        return cached;
+    const pending = fetchBaseSchema(client, baseId).then((result) => {
+        if (!result.ok)
+            byBase.delete(baseId);
+        return result;
+    }, (err) => {
+        byBase.delete(baseId);
+        throw err;
+    });
+    byBase.set(baseId, pending);
+    return pending;
+}
+async function fetchBaseSchema(client, baseId) {
+    try {
+        const raw = await client.action('get-base-schema', { baseId });
+        return { ok: true, tables: parseTables(raw?.tables) };
+    }
+    catch (err) {
+        if (err instanceof ConnectorError) {
+            return { ok: false, error: { code: err.code, provider: err.provider } };
+        }
+        throw err;
+    }
+}
+function parseTables(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const tables = [];
+    for (const item of raw) {
+        const table = asTable(item);
+        if (table)
+            tables.push(table);
+    }
+    return tables;
+}
+function asTable(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const t = raw;
+    if (typeof t.id !== 'string' || typeof t.name !== 'string')
+        return null;
+    const fields = [];
+    if (Array.isArray(t.fields)) {
+        for (const item of t.fields) {
+            const field = asField(item);
+            if (field)
+                fields.push(field);
+        }
+    }
+    return {
+        id: t.id,
+        name: t.name,
+        primaryFieldId: typeof t.primaryFieldId === 'string' ? t.primaryFieldId : '',
+        fields,
+    };
+}
+function asField(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const f = raw;
+    if (typeof f.id !== 'string' || typeof f.name !== 'string' || typeof f.type !== 'string') {
+        return null;
+    }
+    const options = f.options && typeof f.options === 'object' && !Array.isArray(f.options)
+        ? f.options
+        : undefined;
+    return { id: f.id, name: f.name, type: f.type, ...(options ? { options } : {}) };
+}
+function indexFields(schema) {
+    const map = new Map();
+    for (const field of schema?.fields ?? []) {
+        map.set(field.name, field);
+        map.set(field.id, field);
+    }
+    return map;
+}
+async function loadLinkedLabels(records, schema, opts) {
+    const byTable = new Map();
+    const client = opts.client;
+    const baseId = opts.baseId?.trim();
+    if (!client || !baseId)
+        return byTable;
+    const linkFields = (schema.fields ?? []).filter((field) => field.type === 'multipleRecordLinks' && linkedTableIdOf(field));
+    if (linkFields.length === 0)
+        return byTable;
+    const idsByTable = new Map();
+    for (const field of linkFields) {
+        const tableId = linkedTableIdOf(field);
+        if (!tableId)
+            continue;
+        let ids = idsByTable.get(tableId);
+        if (!ids) {
+            ids = new Set();
+            idsByTable.set(tableId, ids);
+        }
+        for (const record of records) {
+            for (const id of recordIdsIn(record.fields?.[field.name] ?? record.fields?.[field.id])) {
+                ids.add(id);
+            }
+        }
+    }
+    await Promise.all([...idsByTable.entries()].map(async ([tableId, ids]) => {
+        if (ids.size === 0)
+            return;
+        const labels = await fetchLinkedLabels(client, baseId, tableId, [...ids]);
+        byTable.set(tableId, labels);
+    }));
+    return byTable;
+}
+async function fetchLinkedLabels(client, baseId, tableId, ids) {
+    const labels = new Map();
+    let primaryName;
+    try {
+        const linked = await getAirtableTableSchema(client, baseId, tableId);
+        if (linked.ok)
+            primaryName = primaryFieldName(linked.schema);
+    }
+    catch {
+        // Without the primary field name a successful list-records would still
+        // guess a column — keep raw IDs instead.
+    }
+    if (!primaryName)
+        return labels;
+    const safeIds = ids.filter((id) => AIRTABLE_RECORD_ID_RE.test(id));
+    for (const chunk of chunkIds(safeIds, AIRTABLE_LINKED_ID_CHUNK)) {
+        try {
+            let offset;
+            do {
+                const page = await client.action('list-records', {
+                    baseId,
+                    tableIdOrName: tableId,
+                    filterByFormula: recordIdFormula(chunk),
+                    fields: [primaryName],
+                    pageSize: 100,
+                    ...(offset ? { offset } : {}),
+                });
+                for (const rec of page.records ?? []) {
+                    const label = labelFromPrimary(rec.fields?.[primaryName]);
+                    if (label)
+                        labels.set(rec.id, label);
+                }
+                offset = typeof page.offset === 'string' && page.offset ? page.offset : undefined;
+            } while (offset);
+        }
+        catch {
+            // Rate-limit / ConnectorError / a deleted-table 404: keep labels from
+            // earlier chunks and leave the rest as raw IDs. Never fail the render.
+        }
+    }
+    return labels;
+}
+// Cell-level shapes Airtable's computed fields (formula/lookup/rollup) can
+// return instead of a value: an error state, or a numeric special value.
+// Never let one of these reach display as a raw JSON blob — the guard runs
+// ahead of every field-type branch, including types this file never learns.
+const EM_DASH = '—';
+function isErrorCell(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const obj = value;
+    if (obj.state === 'error')
+        return true;
+    if (typeof obj.errorType === 'string' && obj.errorType)
+        return true;
+    // Airtable's classic `{error: "#ERROR!"}` cell shape.
+    if (typeof obj.error === 'string' && obj.error)
+        return true;
+    return false;
+}
+function isSpecialValueCell(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const obj = value;
+    return obj.specialValue === 'NaN' || obj.specialValue === 'Infinity';
+}
+function isGuardedCell(value) {
+    return isErrorCell(value) || isSpecialValueCell(value);
+}
+/** The `options.result` a formula/rollup/lookup field carries: what its computed value looks like. */
+function resultTypeOf(options) {
+    const result = options?.result;
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        return undefined;
+    const r = result;
+    if (typeof r.type !== 'string' || !r.type)
+        return undefined;
+    const nestedOptions = r.options && typeof r.options === 'object' && !Array.isArray(r.options)
+        ? r.options
+        : undefined;
+    return { type: r.type, ...(nestedOptions ? { options: nestedOptions } : {}) };
+}
+/**
+ * Formats a formula/rollup/lookup value by its inner result type, reusing the
+ * typed formatters below. Arrays (lookups, array-valued rollups) format each
+ * element and join for display. Guards error/special-value cells at every
+ * level so one bad element never blanks the whole row.
+ */
+function formatByResultType(raw, result) {
+    if (isGuardedCell(raw))
+        return EM_DASH;
+    if (Array.isArray(raw)) {
+        return raw
+            .map((item) => formatByResultType(item, result))
+            .filter((s) => s !== '')
+            .join(', ');
+    }
+    if (!result)
+        return displayUnknown(raw);
+    switch (result.type) {
+        case 'percent':
+            return formatPercent(raw, optionInt(result.options, 'precision') ?? 0);
+        case 'currency':
+            return formatCurrency(raw, optionString(result.options, 'symbol') ?? '', optionInt(result.options, 'precision') ?? 2);
+        case 'number':
+            return formatNumber(raw, optionInt(result.options, 'precision') ?? 0);
+        case 'date':
+            return formatDateValue(raw, dateFormatName(result.options), undefined);
+        case 'dateTime':
+            return formatDateValue(raw, dateFormatName(result.options), timeFormatName(result.options));
+        case 'duration':
+            return formatDuration(raw, optionString(result.options, 'durationFormat') ?? 'h:mm');
+        default:
+            return displayUnknown(raw);
+    }
+}
+function displayForField(raw, field, labelsByTable) {
+    // Value-shape guard first — applies regardless of field type or whether
+    // the field is even in the schema.
+    if (isGuardedCell(raw))
+        return EM_DASH;
+    if (!field)
+        return displayUnknown(raw);
+    switch (field.type) {
+        case 'percent':
+            return formatPercent(raw, optionInt(field.options, 'precision') ?? 0);
+        case 'currency':
+            return formatCurrency(raw, optionString(field.options, 'symbol') ?? '', optionInt(field.options, 'precision') ?? 2);
+        case 'number':
+            return formatNumber(raw, optionInt(field.options, 'precision') ?? 0);
+        case 'date':
+            return formatDateValue(raw, dateFormatName(field.options), undefined);
+        case 'dateTime':
+            return formatDateValue(raw, dateFormatName(field.options), timeFormatName(field.options));
+        case 'duration':
+            return formatDuration(raw, optionString(field.options, 'durationFormat') ?? 'h:mm');
+        case 'multipleRecordLinks': {
+            const tableId = linkedTableIdOf(field);
+            const labels = tableId ? labelsByTable.get(tableId) : undefined;
+            const ids = recordIdsIn(raw);
+            if (ids.length === 0)
+                return displayUnknown(raw);
+            return ids.map((id) => labels?.get(id) ?? id).join(', ');
+        }
+        case 'formula':
+        case 'rollup':
+        case 'multipleLookupValues':
+        case 'lookup':
+            return formatByResultType(raw, resultTypeOf(field.options));
+        default:
+            return displayUnknown(raw);
+    }
+}
+function formatPercent(raw, precision) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    return `${formatFixed(n * 100, precision)}%`;
+}
+function formatCurrency(raw, symbol, precision) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    const abs = formatFixed(Math.abs(n), precision);
+    const sign = n < 0 ? '-' : '';
+    return `${sign}${symbol}${abs}`;
+}
+function formatNumber(raw, precision) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    return formatFixed(n, precision);
+}
+function formatDateValue(raw, dateName, timeName) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return displayUnknown(raw);
+    const parts = parseAirtableDate(raw);
+    if (!parts)
+        return raw;
+    const date = formatDateParts(parts, dateName ?? 'local');
+    if (!timeName || parts.hours === undefined)
+        return date;
+    return `${date} ${formatTimeParts(parts, timeName)}`;
+}
+function formatDuration(raw, durationFormat) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    const negative = n < 0;
+    const abs = Math.abs(n);
+    const hours = Math.floor(abs / 3600);
+    const minutes = Math.floor((abs % 3600) / 60);
+    const seconds = abs % 60;
+    let body;
+    switch (durationFormat) {
+        case 'h:mm:ss':
+            body = `${hours}:${pad2(minutes)}:${pad2(Math.floor(seconds))}`;
+            break;
+        case 'h:mm:ss.s':
+            body = `${hours}:${pad2(minutes)}:${formatFixed(seconds, 1).padStart(4, '0')}`;
+            break;
+        case 'h:mm:ss.ss':
+            body = `${hours}:${pad2(minutes)}:${formatFixed(seconds, 2).padStart(5, '0')}`;
+            break;
+        case 'h:mm:ss.sss':
+            body = `${hours}:${pad2(minutes)}:${formatFixed(seconds, 3).padStart(6, '0')}`;
+            break;
+        case 'h:mm':
+        default:
+            body = `${hours}:${pad2(minutes)}`;
+            break;
+    }
+    return negative ? `-${body}` : body;
+}
+function displayUnknown(raw) {
+    if (raw == null || raw === '')
+        return '';
+    if (Array.isArray(raw)) {
+        return raw.map(displayUnknown).filter(Boolean).join(', ');
+    }
+    if (typeof raw === 'string')
+        return raw;
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return String(raw);
+    if (typeof raw === 'boolean')
+        return raw ? 'checked' : '';
+    if (typeof raw === 'object') {
+        const obj = raw;
+        if (typeof obj.name === 'string' && obj.name)
+            return obj.name;
+        if (typeof obj.filename === 'string' && obj.filename)
+            return obj.filename;
+        if (typeof obj.url === 'string' && obj.url)
+            return obj.url;
+    }
+    return '';
+}
+function recordIdsIn(raw) {
+    if (typeof raw === 'string' && raw.startsWith('rec'))
+        return [raw];
+    if (!Array.isArray(raw))
+        return [];
+    const ids = [];
+    for (const item of raw) {
+        if (typeof item === 'string' && item.startsWith('rec'))
+            ids.push(item);
+    }
+    return ids;
+}
+function labelFromPrimary(raw) {
+    const text = displayUnknown(raw).trim();
+    return text;
+}
+function primaryFieldName(schema) {
+    const match = schema.fields.find((f) => f.id === schema.primaryFieldId);
+    return match?.name;
+}
+function linkedTableIdOf(field) {
+    return optionString(field.options, 'linkedTableId');
+}
+// Airtable record IDs are strictly alphanumeric (rec + 14+ chars). Rather than
+// escape quotes/backslashes for formula interpolation, reject anything else —
+// a non-conforming id keeps its raw value like every other lookup failure.
+const AIRTABLE_RECORD_ID_RE = /^[A-Za-z0-9]+$/;
+function recordIdClause(id) {
+    return `RECORD_ID()='${id}'`;
+}
+function recordIdFormula(ids) {
+    if (ids.length === 1)
+        return recordIdClause(ids[0]);
+    return `OR(${ids.map(recordIdClause).join(',')})`;
+}
+function chunkIds(ids, size) {
+    const chunks = [];
+    for (let i = 0; i < ids.length; i += size) {
+        chunks.push(ids.slice(i, i + size));
+    }
+    return chunks;
+}
+function optionString(options, key) {
+    const value = options?.[key];
+    return typeof value === 'string' && value ? value : undefined;
+}
+function optionInt(options, key) {
+    const value = options?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nestedFormatName(options, key) {
+    const nested = options?.[key];
+    if (!nested || typeof nested !== 'object' || Array.isArray(nested))
+        return undefined;
+    const name = nested.name;
+    return typeof name === 'string' && name ? name : undefined;
+}
+function dateFormatName(options) {
+    return nestedFormatName(options, 'dateFormat');
+}
+function timeFormatName(options) {
+    return nestedFormatName(options, 'timeFormat');
+}
+function asFiniteNumber(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+}
+function formatFixed(n, precision) {
+    const digits = Number.isInteger(precision) && precision >= 0 ? precision : 0;
+    const factor = 10 ** digits;
+    return (Math.round(n * factor) / factor).toFixed(digits);
+}
+const MONTHS = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+function parseAirtableDate(value) {
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (dateOnly) {
+        return {
+            year: Number(dateOnly[1]),
+            month: Number(dateOnly[2]),
+            day: Number(dateOnly[3]),
+        };
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime()))
+        return null;
+    return {
+        year: parsed.getUTCFullYear(),
+        month: parsed.getUTCMonth() + 1,
+        day: parsed.getUTCDate(),
+        hours: parsed.getUTCHours(),
+        minutes: parsed.getUTCMinutes(),
+        seconds: parsed.getUTCSeconds(),
+    };
+}
+function formatDateParts(parts, name) {
+    switch (name) {
+        case 'iso':
+            return `${parts.year}-${pad2(parts.month)}-${pad2(parts.day)}`;
+        case 'european':
+            return `${parts.day}/${parts.month}/${parts.year}`;
+        case 'friendly':
+            return `${MONTHS[parts.month - 1] ?? parts.month} ${parts.day}, ${parts.year}`;
+        case 'us':
+        case 'local':
+        default:
+            return `${parts.month}/${parts.day}/${parts.year}`;
+    }
+}
+function formatTimeParts(parts, name) {
+    const hours = parts.hours ?? 0;
+    const minutes = pad2(parts.minutes ?? 0);
+    if (name === '24hour')
+        return `${pad2(hours)}:${minutes}`;
+    const suffix = hours >= 12 ? 'pm' : 'am';
+    const hour12 = hours % 12 === 0 ? 12 : hours % 12;
+    return `${hour12}:${minutes}${suffix}`;
+}
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}

package/dist/nango.d.ts

@@ -1,5 +1,5 @@
 import { type ResourceFieldMap, type ResourcePage } from './resource-resolution.js';
-export type Provider = 'slack' | 'gmail' | 'google-calendar' | 'google-drive' | 'google-sheet' | 'hubspot' | 'salesforce' | 'notion' | 'linear' | 'stripe' | 'github';
+export type Provider = 'slack' | 'airtable' | 'gmail' | 'google-calendar' | 'google-drive' | 'google-sheet' | 'hubspot' | 'salesforce' | 'notion' | 'linear' | 'stripe' | 'github';
 export type ConnectorErrorCode = 'app_key_required' | 'provider_not_declared' | 'connection_required' | 'needs_reauth' | 'needs_reauth_scope' | 'connection_throttled' | 'connector_unavailable' | 'action_failed' | 'invalid_request';
 export interface ConnectionStatus {
     provider: string;

package/dist/server.d.ts

@@ -4,6 +4,7 @@ export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
+export * from './airtable.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';

package/dist/server.js

@@ -8,6 +8,7 @@ export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
+export * from './airtable.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-integrations/providers/airtable.md

@@ -1,9 +1,24 @@
 # Airtable
 
-Pagination keys and the `fields` param disagree across actions — copy the signature below, do not reuse a neighbour's names.
+`list-records` JSON cells are machine values: a linked-record field is an array of `rec…` IDs (not the primary-field label), and a percent is a 0–1 fraction (`0.42`, not `42%`). Currency, date, dateTime, and duration are similarly unformatted. Never render a field value without reading that field's `type` and `options` from `get-base-schema`.
 
+- **Display (prefer the helper):** `getAirtableTableSchema` + `formatAirtableRecords` from `@assembly-js/app-foundation/server` return raw + display per field so sorts and writes keep machine values. They format percent / currency / number / date / dateTime / duration from field options, and resolve linked IDs to the linked table's primary field. A missing linked record stays the raw ID. Server-side only — pass the `getIntegration` client.
+- **Computed-field errors:** formula/lookup/rollup cells can come back as an error-state object (`{state:"error",errorType:"emptyDependency"}`) or a numeric special value (`{specialValue:"NaN"}`) instead of a real value — never render a cell object raw. The helper guards this (`display` becomes `—`, `raw` stays untouched); code that skips the helper must guard for it itself.
+- **Display without the helper, or a display-only table:** pass `cellFormat: "string"` on `list-records` to get Airtable's formatted strings. Trade-off: values come back as display strings, so you lose machine-readable raw numbers/IDs for sorting and writes — don't use this when you also edit or sort those cells. Otherwise do the schema path yourself: format percent as `(value * 100)` + `%` (precision from field options); for each `multipleRecordLinks` field, `list-records` on `options.linkedTableId` with `filterByFormula` `OR(RECORD_ID()='rec…',…)` (chunk the OR — one page can collect more IDs than a safe formula length), `fields` set to only the linked table's primary field, and substitute labels. Failures keep the raw ID.
 - **Pagination:** `list-bases` takes `cursor` and returns `nextOffset`. `list-records` takes `offset` and returns `offset`. Passing the wrong key silently drops the next page.
 - **`fields` is overloaded:** on `list-records` it is an array of field names to return; on `create-record` / `update-record` it is a name-or-id-keyed map of values to write. An array on a write, or a map on a read, is rejected.
 - Resolve `baseId` with `list-bases` and table/field names with `get-base-schema` before writes. `tableIdOrName` accepts either; schema field ids survive a user renaming the column.
 
+```typescript
+import { getIntegration, getAirtableTableSchema, formatAirtableRecords } from '@assembly-js/app-foundation/server';
+
+const airtable = await getIntegration('airtable');
+const { records } = await airtable.action('list-records', { baseId, tableIdOrName });
+const table = await getAirtableTableSchema(airtable, baseId, tableIdOrName);
+if (!table.ok) return;
+const rows = await formatAirtableRecords(records, table.schema, { client: airtable, baseId });
+// rows[i].fields.Engagement.raw === 0.42
+// rows[i].fields.Engagement.display === "42%"
+```
+
 <!-- ASSEMBLY_ACTIONS:airtable -->

package/skills/assembly-integrations/providers/slack.md

@@ -24,4 +24,6 @@ const history = await slack.action('get-conversation-history', {
 
 For an operation no action covers, relay through the proxy — e.g. `slack.post({ endpoint: '/chat.update', data: { channel: channelId, ts, text } })`.
 
+- **DMs are not supported.** The integration does not grant `im:write`, and `conversations.open` is not vendored. A Slack user ID (`U…`) or DM channel ID (`D…`) also fails `slackPostMessage`'s channel-ID check, so it falls through to a channel-name lookup and returns `channel_not_found` instead of opening the DM. If a user asks for DMs, say so up front and offer `createNotification` (in-product + email) or posting to a channel instead.
+
 <!-- ASSEMBLY_ACTIONS:slack -->