Build `@haverstack/adapter-api`

[cuibonobo]

The API adapter is the primary app-facing adapter. Apps should never import local adapters directly — they connect to a stack server via a URL and bearer token. The API adapter is what makes this possible.

Package details

• Package name: @haverstack/adapter-api
• Location: packages/adapter-api/ in this monorepo
• Depends on: @haverstack/core

Public API

App initialization requires only a URL and bearer token issued by the stack owner:

APIAdapter.open({ url, token? }) → Promise<APIAdapter>

Implementation requirements

Connection

• APIAdapter.open() calls GET /.well-known/stack to verify the server and populate AdapterCapabilities
• Stores the URL and token for subsequent requests
• Surfaces clear errors for 401 (invalid/missing token) and unreachable server

Request handling

• All requests include Authorization: Bearer <token>
• Maps StackAdapter interface methods to HTTP endpoints as defined in the spec
• Handles standard HTTP error codes and surfaces them as typed errors

Offline queue

• Writes (createRecord, updateRecord, deleteRecord, associate, dissociate, putAttachment) are queued locally when the server is unreachable
• Queue is flushed when connectivity returns or when stack.flush() is called
• Queue is persisted across restarts (format TBD — likely a local SQLite file or IndexedDB in browser contexts)

Conflict detection

• On flush, if the server returns a conflict (version mismatch), the adapter surfaces a ConflictRecord to the caller rather than silently overwriting
• See spec for ConflictRecord shape

Notes

• The offline queue and conflict detection can be deferred to a v2 — a v1 that requires connectivity is still useful and unblocks @haverstack/server development.
• Tests will require a mock server — consider using msw (Mock Service Worker) or a lightweight in-process HTTP server.
• Depends on issue Separate stack administration from app access #1 (close() and flush() lifecycle methods) being resolved first.