@haverstack/wire-types 0.40.0 → 0.41.0

package/dist/auth.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Authentication handshake
+ * -------------------------------------------------------
+ * How a server advertises token issuance, the challenge–response bodies,
+ * and the handshake's own error vocabulary.
+ * See docs/spec/wire-format.md § Authentication.
+ */
+/**
+ * How a token can be earned here. Absent means only a scheme arranged out
+ * of band, which a client learns at open() rather than as a 404 partway
+ * through a handshake. An object so a consent flow can arrive as another
+ * entry. See docs/spec/wire-format.md § Advertising it.
+ */
+export type DiscoveryAuth = {
+    methods: AuthMethod[];
+};
+/** The challenge–response handshake of docs/spec/wire-format.md § Authentication. */
+export declare const AUTH_METHOD_DID_CHALLENGE = "did-challenge";
+export type AuthMethod = typeof AUTH_METHOD_DID_CHALLENGE;
+/** Whether a server advertises the DID challenge–response handshake. */
+export declare function supportsDidChallenge(discovery: {
+    auth?: DiscoveryAuth;
+}): boolean;
+/**
+ * The two request bodies, re-exported from `@haverstack/core/wire`, whose
+ * parsers return them — one definition, as with `parseDate`.
+ */
+export type { WireAuthChallengeRequest, WireAuthTokenRequest } from '@haverstack/core/wire';
+/** POST /auth/challenge response. */
+export type WireAuthChallengeResponse = {
+    /** Opaque, single-use, base64url-charset. Bound to the requested DID. */
+    nonce: string;
+    expiresAt: string;
+};
+/**
+ * POST /auth/token response. Both identities are always present, and this
+ * endpoint always reports them equal — a handshake proves key possession,
+ * which says nothing about whom that key may act for. The pair is reported
+ * anyway so an issuance path that does delegate needs no new shape.
+ * See docs/spec/wire-format.md § Authentication.
+ */
+export type WireAuthTokenResponse = {
+    token: string;
+    expiresAt?: string;
+    principalId: string;
+    subjectId: string;
+};
+/**
+ * Auth failures have their own vocabulary, deliberately outside
+ * WireErrorCode: no Stack operation has begun, so none of them is a
+ * StackError and none has a class to reconstruct. The split a client acts
+ * on is retryable versus fatal — a stale nonce warrants a fresh handshake,
+ * a rejected signature never will.
+ */
+export type WireAuthErrorCode = 'invalid_did' | 'unknown_nonce' | 'expired_nonce' | 'invalid_signature';
+export type WireAuthError = {
+    error: {
+        code: WireAuthErrorCode;
+        message: string;
+    };
+};
+export declare const WIRE_AUTH_ERROR_STATUS: Record<WireAuthErrorCode, number>;
+/** Type guard: does this parsed JSON body look like a WireAuthError? */
+export declare function isWireAuthError(body: unknown): body is WireAuthError;
+/** Whether retrying the handshake from a fresh nonce could succeed. */
+export declare function isRetryableAuthError(code: WireAuthErrorCode): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD,MAAM,MAAM,UAAU,GAAG,OAAO,yBAAyB,CAAC;AAE1D,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,SAAS,EAAE;IAAE,IAAI,CAAC,EAAE,aAAa,CAAA;CAAE,GAAG,OAAO,CAEjF;AAED;;;GAGG;AACH,YAAY,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE5F,qCAAqC;AACrC,MAAM,MAAM,yBAAyB,GAAG;IACtC,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,eAAe,GACf,eAAe,GACf,mBAAmB,CAAC;AAExB,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE;QACL,IAAI,EAAE,iBAAiB,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAOpE,CAAC;AAOF,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,aAAa,CAEpE;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAErE"}

package/dist/auth.js

@@ -0,0 +1,34 @@
+/**
+ * Authentication handshake
+ * -------------------------------------------------------
+ * How a server advertises token issuance, the challenge–response bodies,
+ * and the handshake's own error vocabulary.
+ * See docs/spec/wire-format.md § Authentication.
+ */
+import { hasErrorBody } from './errors.js';
+/** The challenge–response handshake of docs/spec/wire-format.md § Authentication. */
+export const AUTH_METHOD_DID_CHALLENGE = 'did-challenge';
+/** Whether a server advertises the DID challenge–response handshake. */
+export function supportsDidChallenge(discovery) {
+    return discovery.auth?.methods?.includes(AUTH_METHOD_DID_CHALLENGE) ?? false;
+}
+export const WIRE_AUTH_ERROR_STATUS = {
+    // Malformed input, not a rejected credential — there is nothing here to
+    // authenticate yet.
+    invalid_did: 400,
+    unknown_nonce: 401,
+    expired_nonce: 401,
+    invalid_signature: 401,
+};
+/** Codes a fresh handshake can resolve. Anything else is fatal to retry. */
+const RETRYABLE_AUTH_CODES = new Set(['unknown_nonce', 'expired_nonce']);
+const KNOWN_AUTH_CODES = new Set(Object.keys(WIRE_AUTH_ERROR_STATUS));
+/** Type guard: does this parsed JSON body look like a WireAuthError? */
+export function isWireAuthError(body) {
+    return hasErrorBody(body, KNOWN_AUTH_CODES);
+}
+/** Whether retrying the handshake from a fresh nonce could succeed. */
+export function isRetryableAuthError(code) {
+    return RETRYABLE_AUTH_CODES.has(code);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY3C,qFAAqF;AACrF,MAAM,CAAC,MAAM,yBAAyB,GAAG,eAAe,CAAC;AAIzD,wEAAwE;AACxE,MAAM,UAAU,oBAAoB,CAAC,SAAmC;IACtE,OAAO,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,yBAAyB,CAAC,IAAI,KAAK,CAAC;AAC/E,CAAC;AAiDD,MAAM,CAAC,MAAM,sBAAsB,GAAsC;IACvE,wEAAwE;IACxE,oBAAoB;IACpB,WAAW,EAAE,GAAG;IAChB,aAAa,EAAE,GAAG;IAClB,aAAa,EAAE,GAAG;IAClB,iBAAiB,EAAE,GAAG;CACvB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAoB,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC;AAE5F,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC;AAE9E,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,YAAY,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;AAC9C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,oBAAoB,CAAC,IAAuB;IAC1D,OAAO,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC"}

package/dist/change-feed.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Change feed
+ * -------------------------------------------------------
+ * How a server advertises the feed, and the frames it streams.
+ * See docs/spec/change-feed.md.
+ */
+import type { ChangeKind, ChangeOp, DataAssociation, RecordChange } from '@haverstack/core';
+import { type WireChangeActor, type WireRecord } from './records.js';
+/**
+ * The change feed a server offers, absent when it offers none. An object
+ * rather than a boolean for the same reason `auth` is one: this surface
+ * grows entries. See docs/spec/change-feed.md.
+ */
+export type DiscoveryChanges = {
+    transports: ChangeTransport[];
+    /**
+     * Whether a resume cursor is honored. `false` is conformant and means
+     * every reconnect is answered with a `reset` frame.
+     */
+    resume: boolean;
+    /** Whether `?include=record` is honored. Never honored for a purge. */
+    records: boolean;
+};
+/** Server→client streaming over `fetch`. The only transport in this version. */
+export declare const CHANGE_TRANSPORT_SSE = "sse";
+export type ChangeTransport = typeof CHANGE_TRANSPORT_SSE;
+/**
+ * Whether a server offers a change feed this client can consume. A client
+ * checks this and fails locally rather than learning it as a 404 partway
+ * through a connection — the same reason `auth.methods` exists.
+ */
+export declare function supportsChangeFeed(discovery: {
+    changes?: DiscoveryChanges;
+}): boolean;
+/**
+ * One change, as a `record` frame carries it. The envelope describes the
+ * change and nothing else: the record's own provenance rides `record`,
+ * where a consumer that wants it asks for it. See docs/spec/events.md
+ * § Attribution.
+ */
+export type WireRecordChange = {
+    kind: ChangeKind;
+    /** Every aspect this version moved; never empty. See RecordChange.ops. */
+    ops: ChangeOp[];
+    recordId: string;
+    typeId: string;
+    version: number;
+    updatedAt: string;
+    parentId?: string;
+    actor?: WireChangeActor;
+    /** Present when `ops` includes `associate`. See RecordChange.associationsAdded. */
+    associationsAdded?: DataAssociation[];
+    /** Present when `ops` includes `dissociate`. See RecordChange.associationsRemoved. */
+    associationsRemoved?: DataAssociation[];
+    record?: WireRecord;
+    cursor?: string;
+};
+/**
+ * A change as a server frames it. A purge carries neither the record nor
+ * its parent, whatever was asked for: purge is the erasure primitive, and
+ * the rule lives here because a server still holds the purged record at
+ * emission. See docs/spec/events.md § Purged records carry nothing.
+ */
+export declare function serializeChange(c: RecordChange): WireRecordChange;
+/**
+ * Frame names. Every frame carries one, and a client MUST ignore a name it
+ * does not recognize — which is what makes a new frame an additive, minor
+ * change rather than a break. See docs/spec/change-feed.md.
+ */
+export declare const CHANGE_FRAME_READY = "ready";
+export declare const CHANGE_FRAME_RECORD = "record";
+export declare const CHANGE_FRAME_RESET = "reset";
+/**
+ * Sent first on every connection, before any change. It is what makes
+ * subscribe-then-query gap-free: everything after it is in the stream.
+ */
+export type WireReadyFrame = {
+    /** The head cursor. Absent from a server that mints none (`resume: false`). */
+    cursor?: string;
+};
+/**
+ * Why a cursor could not be honored. Informational — a client's repair is
+ * the same for all three, and it is reconciling by query.
+ */
+export type ChangeResetReason = 'cursor_expired' | 'not_supported' | 'overflow';
+/** Your cursor cannot be honored; resynchronize by query. */
+export type WireResetFrame = {
+    reason: ChangeResetReason;
+};
+/** Whether a cursor is framable: unreserved base64url characters only. */
+export declare function isValidCursor(cursor: string): boolean;
+//# sourceMappingURL=change-feed.d.ts.map

package/dist/change-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-feed.d.ts","sourceRoot":"","sources":["../src/change-feed.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,QAAQ,CAAC;AAE1C,MAAM,MAAM,eAAe,GAAG,OAAO,oBAAoB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE;IAAE,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAAE,GAAG,OAAO,CAErF;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,0EAA0E;IAC1E,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC;IACtC,sFAAsF;IACtF,mBAAmB,CAAC,EAAE,eAAe,EAAE,CAAC;IACxC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAmBjE;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAC1C,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAC5C,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,eAAe,GAAG,UAAU,CAAC;AAEhF,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AASF,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/change-feed.js

@@ -0,0 +1,69 @@
+/**
+ * Change feed
+ * -------------------------------------------------------
+ * How a server advertises the feed, and the frames it streams.
+ * See docs/spec/change-feed.md.
+ */
+import { serializeChangeActor, serializeRecord, } from './records.js';
+/** Server→client streaming over `fetch`. The only transport in this version. */
+export const CHANGE_TRANSPORT_SSE = 'sse';
+/**
+ * Whether a server offers a change feed this client can consume. A client
+ * checks this and fails locally rather than learning it as a 404 partway
+ * through a connection — the same reason `auth.methods` exists.
+ */
+export function supportsChangeFeed(discovery) {
+    return discovery.changes?.transports?.includes(CHANGE_TRANSPORT_SSE) ?? false;
+}
+/**
+ * A change as a server frames it. A purge carries neither the record nor
+ * its parent, whatever was asked for: purge is the erasure primitive, and
+ * the rule lives here because a server still holds the purged record at
+ * emission. See docs/spec/events.md § Purged records carry nothing.
+ */
+export function serializeChange(c) {
+    const w = {
+        kind: c.kind,
+        // Copied, not aliased: a frame is serialized once and delivered to
+        // every subscriber, and the array it came from belongs to the emission.
+        ops: [...c.ops],
+        recordId: c.recordId,
+        typeId: c.typeId,
+        version: c.version,
+        updatedAt: c.updatedAt.toISOString(),
+    };
+    if (c.actor !== undefined)
+        w.actor = serializeChangeActor(c.actor);
+    if (c.cursor !== undefined)
+        w.cursor = c.cursor;
+    if (c.kind === 'purged')
+        return w;
+    if (c.parentId !== undefined)
+        w.parentId = c.parentId;
+    if (c.associationsAdded !== undefined)
+        w.associationsAdded = c.associationsAdded;
+    if (c.associationsRemoved !== undefined)
+        w.associationsRemoved = c.associationsRemoved;
+    if (c.record !== undefined)
+        w.record = serializeRecord(c.record);
+    return w;
+}
+/**
+ * Frame names. Every frame carries one, and a client MUST ignore a name it
+ * does not recognize — which is what makes a new frame an additive, minor
+ * change rather than a break. See docs/spec/change-feed.md.
+ */
+export const CHANGE_FRAME_READY = 'ready';
+export const CHANGE_FRAME_RECORD = 'record';
+export const CHANGE_FRAME_RESET = 'reset';
+/**
+ * A cursor travels in an SSE `id:` field, so a value spanning a line would
+ * truncate the frame carrying it. Same charset and same reason as the auth
+ * nonce — see docs/spec/wire-format.md § The handshake.
+ */
+const CURSOR_FORMAT = /^[A-Za-z0-9_-]+$/;
+/** Whether a cursor is framable: unreserved base64url characters only. */
+export function isValidCursor(cursor) {
+    return CURSOR_FORMAT.test(cursor);
+}
+//# sourceMappingURL=change-feed.js.map

package/dist/change-feed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-feed.js","sourceRoot":"","sources":["../src/change-feed.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,oBAAoB,EACpB,eAAe,GAGhB,MAAM,cAAc,CAAC;AAkBtB,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAI1C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAyC;IAC1E,OAAO,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC;AAChF,CAAC;AA0BD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,CAAe;IAC7C,MAAM,CAAC,GAAqB;QAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,mEAAmE;QACnE,wEAAwE;QACxE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE;KACrC,CAAC;IACF,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;QAAE,CAAC,CAAC,KAAK,GAAG,oBAAoB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACnE,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;QAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;QAAE,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;IACtD,IAAI,CAAC,CAAC,iBAAiB,KAAK,SAAS;QAAE,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC,iBAAiB,CAAC;IACjF,IAAI,CAAC,CAAC,mBAAmB,KAAK,SAAS;QAAE,CAAC,CAAC,mBAAmB,GAAG,CAAC,CAAC,mBAAmB,CAAC;IACvF,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;QAAE,CAAC,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjE,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAC1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC;AAC5C,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAsB1C;;;;GAIG;AACH,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEzC,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/dist/discovery.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Discovery
+ * -------------------------------------------------------
+ * `GET /.well-known/stack` and the protocol version it negotiates. Each
+ * optional surface's advertisement lives with that surface — `auth`,
+ * `changes`, `installs` — and is only assembled here.
+ * See docs/spec/wire-format.md § Discovery.
+ */
+import type { StackCapabilities } from '@haverstack/core';
+import type { DiscoveryAuth } from './auth.js';
+import type { DiscoveryChanges } from './change-feed.js';
+import type { DiscoveryInstalls } from './installs.js';
+/**
+ * The wire protocol this package describes. Bump the major when a change
+ * would make an older client read a response wrongly; bump the minor for
+ * additions an older client can ignore. See docs/spec/wire-format.md
+ * § Version negotiation.
+ */
+export declare const WIRE_PROTOCOL_VERSION = "1.0";
+/** GET /.well-known/stack. See docs/spec/wire-format.md § Discovery. */
+export type DiscoveryResponse = {
+    version: string;
+    entityId: string;
+    timezone?: string;
+    capabilities?: DiscoveryCapabilities;
+    auth?: DiscoveryAuth;
+    changes?: DiscoveryChanges;
+    installs?: DiscoveryInstalls;
+};
+/**
+ * `capabilities` as it arrives: a foreign server may omit any part, or name
+ * a reach or sort field this client has never heard of. Typed loosely on
+ * exactly those fields, so the checks normalizeCapabilities() makes read as
+ * checks rather than casts. See docs/spec/wire-format.md § Discovery.
+ */
+export type DiscoveryCapabilities = {
+    filter?: {
+        content?: string;
+        contentPresent?: boolean;
+        contentByType?: number;
+        search?: boolean;
+    };
+    sort?: {
+        fields?: string[];
+        contentField?: boolean;
+        contentFieldByType?: number;
+    };
+    limits?: {
+        attachmentBytes?: number | null;
+        contentBytes?: number | null;
+    };
+};
+/**
+ * Resolves anything absent, malformed or unrecognized to the least capable
+ * value it could stand for — one rule, applied once, rather than a default
+ * per key at each call site. A `null` limit is the one permissive reading,
+ * since the server's own ceiling still answers 413. See
+ * docs/spec/adapters.md § Adapter capabilities.
+ */
+export declare function normalizeCapabilities(capabilities: DiscoveryCapabilities | undefined): StackCapabilities;
+/** Splits a MAJOR.MINOR protocol version. Returns null if it isn't one. */
+export declare function parseProtocolVersion(version: string): {
+    major: number;
+    minor: number;
+} | null;
+/**
+ * Majors must match; minors never have to. A higher server minor is additive
+ * fields this client ignores, and a higher client minor is optional fields
+ * the server may omit — neither can make a response read wrongly, which is
+ * the only thing a major bump signals.
+ */
+export declare function isProtocolCompatible(version: string, against?: string): boolean;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAuC,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAClG,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,MAAM,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC5E,CAAC;AAKF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,qBAAqB,GAAG,SAAS,GAC9C,iBAAiB,CA2BnB;AAUD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAG7F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,SAAwB,GAAG,OAAO,CAI9F"}

package/dist/discovery.js

@@ -0,0 +1,74 @@
+/**
+ * Discovery
+ * -------------------------------------------------------
+ * `GET /.well-known/stack` and the protocol version it negotiates. Each
+ * optional surface's advertisement lives with that surface — `auth`,
+ * `changes`, `installs` — and is only assembled here.
+ * See docs/spec/wire-format.md § Discovery.
+ */
+import { NATIVE_SORT_FIELDS } from '@haverstack/core';
+/**
+ * The wire protocol this package describes. Bump the major when a change
+ * would make an older client read a response wrongly; bump the minor for
+ * additions an older client can ignore. See docs/spec/wire-format.md
+ * § Version negotiation.
+ */
+export const WIRE_PROTOCOL_VERSION = '1.0';
+const CONTENT_FILTER_REACHES = new Set(['none', 'field', 'path']);
+const SORT_FIELDS = new Set(NATIVE_SORT_FIELDS);
+/**
+ * Resolves anything absent, malformed or unrecognized to the least capable
+ * value it could stand for — one rule, applied once, rather than a default
+ * per key at each call site. A `null` limit is the one permissive reading,
+ * since the server's own ceiling still answers 413. See
+ * docs/spec/adapters.md § Adapter capabilities.
+ */
+export function normalizeCapabilities(capabilities) {
+    const filter = capabilities?.filter;
+    const sort = capabilities?.sort;
+    const limits = capabilities?.limits;
+    const reach = CONTENT_FILTER_REACHES.has(filter?.content)
+        ? filter?.content
+        : 'none';
+    // The per-Type shapes travel in the POST /records/query body, which a
+    // server reaching no content does not serve.
+    const cap = (value) => (reach === 'none' ? 0 : capOrZero(value));
+    return {
+        filter: {
+            content: reach,
+            contentPresent: filter?.contentPresent === true,
+            contentByType: cap(filter?.contentByType),
+            search: filter?.search === true,
+        },
+        sort: {
+            fields: (sort?.fields ?? []).filter((f) => SORT_FIELDS.has(f)),
+            contentField: sort?.contentField === true,
+            contentFieldByType: cap(sort?.contentFieldByType),
+        },
+        limits: {
+            attachmentBytes: finiteOrNull(limits?.attachmentBytes),
+            contentBytes: finiteOrNull(limits?.contentBytes),
+        },
+    };
+}
+/** A cap on keys, or 0 — declined — for anything but a non-negative integer. */
+const capOrZero = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : 0;
+/** A ceiling this client can compare against, or null for "cannot pre-check". */
+const finiteOrNull = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+/** Splits a MAJOR.MINOR protocol version. Returns null if it isn't one. */
+export function parseProtocolVersion(version) {
+    const match = /^(\d+)\.(\d+)$/.exec(version);
+    return match ? { major: Number(match[1]), minor: Number(match[2]) } : null;
+}
+/**
+ * Majors must match; minors never have to. A higher server minor is additive
+ * fields this client ignores, and a higher client minor is optional fields
+ * the server may omit — neither can make a response read wrongly, which is
+ * the only thing a major bump signals.
+ */
+export function isProtocolCompatible(version, against = WIRE_PROTOCOL_VERSION) {
+    const server = parseProtocolVersion(version);
+    const client = parseProtocolVersion(against);
+    return server !== null && client !== null && server.major === client.major;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Error responses
+ * -------------------------------------------------------
+ * The round-trip contract for core's typed error taxonomy: a server
+ * serializes a caught core error via serializeError(), and APIAdapter
+ * reconstructs the same class via deserializeError(). `code` is the
+ * authoritative discriminator; status is a transport hint. See
+ * docs/spec/wire-format.md § Error responses.
+ */
+import type { SchemaDriftViolation, StackErrorCode, ValidationError } from '@haverstack/core';
+/**
+ * Alias of core's StackErrorCode: the vocabulary belongs with the classes
+ * that carry it, and StackError.code is typed by it, so re-declaring the
+ * union here would be a second copy to drift.
+ */
+export type WireErrorCode = StackErrorCode;
+export type WireError = {
+    error: {
+        code: WireErrorCode;
+        message: string;
+        /** Field-level validation failures. Only present for code: 'validation'. */
+        details?: ValidationError[];
+        /** ifVersion/If-Match precondition state. Only present for code: 'version_conflict'. */
+        versionConflict?: {
+            recordId: string;
+            expectedVersion: number;
+            actualVersion: number;
+        };
+        /** The rejected defineType() call's target and violations. Only present for code: 'schema_drift'. */
+        schemaDrift?: {
+            typeId: string;
+            violations: SchemaDriftViolation[];
+        };
+    };
+};
+/** Canonical HTTP status for each wire error code. */
+export declare const WIRE_ERROR_STATUS: Record<WireErrorCode, number>;
+/**
+ * Statuses that unambiguously imply a wire error code, for reconstructing
+ * an error from status alone when a response has no parseable wire error
+ * body. 500 is deliberately excluded — it would misclassify ordinary
+ * server bugs as StackMigrationError. See docs/spec/wire-format.md
+ * § Wire error body.
+ */
+export declare const STATUS_TO_CODE: Partial<Record<number, WireErrorCode>>;
+/** Whether `body` is `{ error: { code, message } }` with a code from `codes`. */
+export declare function hasErrorBody(body: unknown, codes: ReadonlySet<string>): boolean;
+/** Type guard: does this parsed JSON body look like a WireError? */
+export declare function isWireError(body: unknown): body is WireError;
+/**
+ * Convert a thrown core error into its wire response. Used by server
+ * implementations. Returns null for anything that isn't a StackError —
+ * callers fall back to their own generic error handling, so an ordinary bug
+ * stays a bare 500 rather than being dressed as a protocol error.
+ */
+export declare function serializeError(err: unknown): {
+    status: number;
+    body: WireError;
+} | null;
+/** Reconstruct the core error a WireError body describes. */
+export declare function deserializeError(body: WireError): Error;
+/**
+ * Reconstruct a core error from an HTTP status alone (no usable wire error
+ * body). Returns null for statuses with no unambiguous code — callers
+ * should fall back to a generic adapter-level error.
+ */
+export declare function errorForStatus(status: number, message: string): Error | null;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE9F;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAE3C,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE;QACL,IAAI,EAAE,aAAa,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,4EAA4E;QAC5E,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;QAC5B,wFAAwF;QACxF,eAAe,CAAC,EAAE;YAChB,QAAQ,EAAE,MAAM,CAAC;YACjB,eAAe,EAAE,MAAM,CAAC;YACxB,aAAa,EAAE,MAAM,CAAC;SACvB,CAAC;QACF,qGAAqG;QACrG,WAAW,CAAC,EAAE;YACZ,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,oBAAoB,EAAE,CAAC;SACpC,CAAC;KACH,CAAC;CACH,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAoC3D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAajE,CAAC;AAIF,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAO/E;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,SAAS,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,IAAI,CAkBvF;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CA+BvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAG5E"}