@emulates/airtable 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — @emulates/airtable
+
+## 0.1.1 (2026-10-06)
+
+Initial release.
+
+### Dependencies
+
+- `@emulates/sqlite`

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/airtable discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/airtable/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `emulates.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **OAuth, base metadata, fields and record creation**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- airtable`.
+- Evidence model: Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Emulates
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-emulates-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/emulators/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `airtable`.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @emulates/airtable
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Emulates](https://github.com/crvouga/emulators): high-fidelity, in-process emulators for APIs and databases.
+
+WIP Airtable OAuth and forms-integration emulator. Only synthetic fixtures belong here.
+
+## Install
+
+`bun add @emulates/airtable`
+
+## Usage
+
+```ts
+import { createRuntime } from "@emulates/airtable"
+const runtime = createRuntime()
+const response = await runtime.fetch(new Request("http://airtable.test/v0/meta/bases", {
+  headers: { authorization: "Bearer mock_airtable_token" },
+}))
+```
+
+Run `emulates-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](https://airtable.com/developers/web/api/oauth-reference), [identity](https://airtable.com/developers/web/api/get-user-id-scopes), [bases](https://airtable.com/developers/web/api/list-bases), [schema](https://airtable.com/developers/web/api/get-base-schema), [field creation](https://airtable.com/developers/web/api/create-field), [record creation](https://airtable.com/developers/web/api/create-records) and [errors](https://airtable.com/developers/web/api/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`.

package/SUPPORT.md

@@ -0,0 +1,16 @@
+# Airtable mock — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **6**
+- supported by the emulator: **6**
+- parity enabled: **6**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `Whoami` | `GET /v0/meta/whoami` | ✅ supported | ✅ |  |
+| `ListBases` | `GET /v0/meta/bases` | ✅ supported | ✅ |  |
+| `ListTables` | `GET /v0/meta/bases/{baseId}/tables` | ✅ supported | ✅ |  |
+| `CreateField` | `POST /v0/meta/bases/{baseId}/tables/{tableId}/fields` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `CreateRecords` | `POST /v0/{baseId}/{tableId}` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `OAuthToken` | `POST /oauth2/v1/token` | ✅ supported | ⚠️ unsafe (opt-in) |  |