@oddington/sdk 0.1.1 → 0.1.2

package/README.md

@@ -13,6 +13,37 @@ import { defineHandler, resolveAsk, routinePublicationClient } from '@oddington/
 const inbox = routinePublicationClient();
 ```
 
+Bind a declared Airtable connection with `connections.airtable('project-management')`
+from the package root. Import and binding perform no network or credential work.
+The client exposes `tables.list()` and `records.list`, `get`, `create`, `update`
+and `delete`. Reads allow table names or stable IDs and return all ordered pages;
+writes require a stable table ID and one nonempty batch of at most ten records.
+Operations cannot select another workspace, base, token or provider URL.
+
+```ts
+import { connections } from '@oddington/sdk';
+
+const airtable = connections.airtable('project-management');
+const changed = await airtable.records.update({ table: 'tblContacts', records: [{
+  id: 'recRetained', expected: { Email: 'james@example.com', Company: null },
+  set: { Company: ['recCompany'] },
+}] });
+```
+
+Preserve original reviewed `expected` values. Non-null values must match exactly;
+`null` requires an omitted field key and cannot be used as an update value. Reads
+preserve Airtable's omitted-field shape. Create requires nonempty `fields`, update
+requires nonempty `set`, and untouched fields remain unchanged. Guarded methods
+read before a single batch write; this leaves a concurrency race and provides no
+atomic compare-and-swap, rollback or implicit retry.
+
+Success returns a safe Airtable `receipt` with the connection, configured base,
+table, operation and acknowledged IDs. Create/update also return acknowledged
+records separately. `AirtableOperationError` reports `unapplied`, `partial` or
+`uncertain` effects and known safe `receipts`. Stop after partial or uncertain
+work; never repeat the whole change blindly. Credentials must never be retained
+in files, publication, logs, handler input, errors or receipts.
+
 Managed routine launches supply workspace, scoped capability and working root.
 The defaults read `ODDINGTON_ROUTINE_WORKSPACE`, `ODDINGTON_ROUTINE_RUN` and
 `ODDINGTON_INBOX_WORKING_ROOT` (or the current directory). Callers may supply the