@crvouga/mockingbird-service-airtable

Local emulators. Real API contracts. Part of Mockingbird.

WIP Airtable OAuth and forms-integration emulator. Only synthetic fixtures belong here.

Install

bun add @crvouga/mockingbird-service-airtable

Usage

import { createServer } from "@crvouga/mockingbird-service-airtable/server"

const server = await createServer()

// The application's own HTTP call (airtable.js has no metadata API). Only the origin changes.
const response = await fetch(`${server.url}/v0/meta/bases`, {
  headers: { authorization: "Bearer mock_airtable_token" },
})
const { bases } = (await response.json()) as { bases: { id: string; name: string }[] }
console.log(bases.map((base) => base.id)) // ["appMockBase"]

await server.close()

Run mockingbird-airtable serve --port 12130. Inject its origin for both the API and OAuth origin in the optional integration; consumer endpoint wiring is separate.

Surface and state

• POST /oauth2/v1/token: form-encoded authorization-code and refresh grants. Confidential clients require Basic credentials; public clients use body client_id. Codes require S256 PKCE and exact redirect/client binding, expire by clock, and are consumed before verifier checks so even a rejected verifier cannot replay them. Refresh rotates both tokens; access lasts 60 minutes and refresh 60 days. Scope reduction is allowed. The documented trailing space in token_type: "Bearer " is retained.
• GET /v0/meta/whoami: user id and scopes, plus email only with user.email:read.
• GET /v0/meta/bases: accessible bases/permission levels and opaque offset pages (pageSize, default 1000).
• GET /v0/meta/bases/{baseId}/tables: table schemas/fields/views for accessible bases.
• POST /v0/meta/bases/{baseId}/tables/{tableId}/fields: add supported form-field schemas and retain options.
• POST /v0/{baseId}/{tableId}: up to ten records, or one top-level fields object. Accept field ids or names; persist only after every input record validates. Empty cells are omitted. returnFieldsByFieldId controls response keys. Table name aliases work.

Default bearer mock_airtable_token, refresh mock_airtable_refresh, client mock_client / mock_client_secret; base appMockBase, table tblMockTable, field fldMockName named Name. Default scopes permit schema reads/writes, record writes, and synthetic email. Grant scopes and base roles gate operations independently. Missing/inaccessible bases yield 403; invalid/expired access yields 401; invalid cells yield 422 without partial records.

Seed bases, tables, grants, clients, codes, and records using constructor options or standard admin state. Fields supported for typed form writes: singleLineText, multilineText, richText, email, url, phoneNumber, number, percent, currency, duration, rating, checkbox, date, dateTime, singleSelect and multipleSelects. Options for choices, precision and checkbox appearance are retained; select values must name a seeded choice. Scalar validation covers wire types rather than every vendor presentation constraint. Unknown field types fail instead of silently accepting arbitrary values.

Test controls

Standard relocatable /__admin health, state, reset, clock, Timeline checkpoints, request journal, metrics and faults. Header namespaces, /__admin/ns/<name> paths and bearer mappings isolate records/grants. Journals contain metadata only, not OAuth bodies or submitted form values. Presets: unauthorized, rate_limited (429, retry-after 30), invalid_schema (422), server_error, connection_drop. Generic fault rules add latency. No webhooks required.

Oracle and tests

Follows official Airtable OAuth, identity, bases, schema, field creation, record creation and errors references. No successful live OAuth or SaaS writes were performed; no credentials used.

bun test runs raw-fetch acceptance, every-operation self-parity and divergence detection. The consumer is a faithful wire-surface port, not inaccessible private source. bun run parity requires AIRTABLE_ACCESS_TOKEN; it performs only a read-only identity-envelope probe, never printing identifiers.

Deliberately not modelled

No actual SaaS writes, formulas/computed columns, linked records, attachments, collaborators, views editing, collaboration UI or production-integration activation. No typecast conversion, complete field-option/presentation validation, real quota accounting, exact error prose or internal offset format. Schema seeding may contain additional metadata; writes validate only the listed form-field types. OAuth retry grace/conflict timing, authorization UI and enterprise policy discovery are not simulated; fault controls can script these errors. Tokens/ids are local deterministic stand-ins.

API

Root runtime exports: AirtableAPI, AIRTABLE_NAMESPACE, createRuntime, AIRTABLE_PRESETS, document, operationIds, supportedOperationIds. Types: AirtableAPIOptions, Field, Table, Base, Grant, Client, OAuthCode, StoredRecord, AirtableRuntimeOptions, AirtableRuntime, OperationId, SupportedOperationId.

/server exports createServer, serveTarget, DEFAULT_PORT; types AirtableServerOptions, AirtableServer.