@haverstack/core 0.22.0 → 0.24.0

package/dist/wire-entry.js.map

@@ -1 +1 @@
-{"version":3,"file":"wire-entry.js","sourceRoot":"","sources":["../src/wire-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,eAAe,GAChB,MAAM,WAAW,CAAC;AAGnB,0EAA0E;AAC1E,0EAA0E;AAC1E,qBAAqB;AACrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,6DAA6D;AAC7D,gEAAgE;AAChE,oDAAoD;AACpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,oCAAoC,EACpC,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,kEAAkE;AAClE,yEAAyE;AACzE,wEAAwE;AACxE,6EAA6E;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"wire-entry.js","sourceRoot":"","sources":["../src/wire-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,eAAe,GAChB,MAAM,WAAW,CAAC;AAGnB,0EAA0E;AAC1E,0EAA0E;AAC1E,qBAAqB;AACrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,6DAA6D;AAC7D,gEAAgE;AAChE,oDAAoD;AACpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,oCAAoC,EACpC,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,kEAAkE;AAClE,yEAAyE;AACzE,wEAAwE;AACxE,6EAA6E;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAMnE,wEAAwE;AACxE,oEAAoE;AACpE,wEAAwE;AACxE,sEAAsE;AACtE,gEAAgE;AAChE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B,wEAAwE;AACxE,sCAAsC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,4EAA4E;AAC5E,oEAAoE;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,uEAAuE;AACvE,yEAAyE;AACzE,0DAA0D;AAC1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAG/D,4EAA4E;AAC5E,wEAAwE;AACxE,6CAA6C;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/wire-record.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stack — Wire Record Bodies
+ * -------------------------------------------------------
+ * `POST /records` is the one endpoint where a client sends a whole record
+ * and the server may trust only part of it. This module turns that body
+ * into the arguments `ScopedStack.create()` takes, so the disposition of
+ * each field — stamped, conditionally dropped, forwarded — is structural
+ * rather than a property of how carefully a route was written. Which field
+ * gets which is not derivable from its name, and the rules are normative
+ * for servers in other languages, so they live in the spec rather than
+ * here: docs/spec/wire-format.md § Records.
+ */
+import type { BackdatableCreateRecordOptions } from './stack.js';
+import type { EntityId, TokenSession, TypeId } from './types.js';
+/**
+ * A `POST /records` body as the three arguments `ScopedStack.create()`
+ * takes. Not spread-ready, so a call site reads as three deliberate things.
+ */
+export type WireCreateRequest = {
+    typeId: TypeId;
+    content: Record<string, unknown>;
+    /** Omitted, not optional: a caller cannot forward what the type lacks. */
+    options: Omit<BackdatableCreateRecordOptions, 'entityId' | 'principalId'>;
+};
+/**
+ * Read a `POST /records` body as a create. Takes the session rather than a
+ * pre-computed boolean so the owner-acting-alone determination stays with
+ * the rule that needs it.
+ *
+ * Beyond shape, values are `Stack`'s to judge — an id's legality, a
+ * permission's contents, the content's schema — since judging them twice
+ * would let the two answers drift.
+ */
+export declare function createOptionsFromWireRecord(body: unknown, session: TokenSession, ownerEntityId: EntityId): WireCreateRequest;
+//# sourceMappingURL=wire-record.d.ts.map

package/dist/wire-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-record.d.ts","sourceRoot":"","sources":["../src/wire-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,KAAK,EAAe,QAAQ,EAAc,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAE1F;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,0EAA0E;IAC1E,OAAO,EAAE,IAAI,CAAC,8BAA8B,EAAE,UAAU,GAAG,aAAa,CAAC,CAAC;CAC3E,CAAC;AA8CF;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,YAAY,EACrB,aAAa,EAAE,QAAQ,GACtB,iBAAiB,CAoCnB"}

package/dist/wire-record.js

@@ -0,0 +1,107 @@
+/**
+ * Stack — Wire Record Bodies
+ * -------------------------------------------------------
+ * `POST /records` is the one endpoint where a client sends a whole record
+ * and the server may trust only part of it. This module turns that body
+ * into the arguments `ScopedStack.create()` takes, so the disposition of
+ * each field — stamped, conditionally dropped, forwarded — is structural
+ * rather than a property of how carefully a route was written. Which field
+ * gets which is not derivable from its name, and the rules are normative
+ * for servers in other languages, so they live in the spec rather than
+ * here: docs/spec/wire-format.md § Records.
+ */
+import { isOwnerActingAlone } from './access.js';
+import { StackQueryError, StackValidationError } from './stack.js';
+function requireBody(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new StackQueryError('Invalid record body: expected an object');
+    return body;
+}
+/**
+ * The refusal a present field earns when its value is the wrong shape.
+ * `StackValidationError` because the failure names a field of the record
+ * being written, and only that class carries the path.
+ */
+function fieldError(path, message) {
+    throw new StackValidationError([{ path, message }]);
+}
+function optionalString(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        fieldError(key, `${key} must be a string`);
+    return value;
+}
+function optionalArray(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        fieldError(key, `${key} must be an array`);
+    return value;
+}
+/**
+ * A wire date for one of the owner-only clock fields. An `Invalid Date`
+ * must not reach `create()`: its `NaN` timestamp switches the id-skew
+ * check off instead of failing it.
+ */
+function ownerDate(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' && typeof value !== 'number')
+        fieldError(key, `${key} must be a date string`);
+    const date = new Date(value);
+    if (isNaN(date.getTime()))
+        fieldError(key, `Invalid ${key}: ${JSON.stringify(value)}`);
+    return date;
+}
+/**
+ * Read a `POST /records` body as a create. Takes the session rather than a
+ * pre-computed boolean so the owner-acting-alone determination stays with
+ * the rule that needs it.
+ *
+ * Beyond shape, values are `Stack`'s to judge — an id's legality, a
+ * permission's contents, the content's schema — since judging them twice
+ * would let the two answers drift.
+ */
+export function createOptionsFromWireRecord(body, session, ownerEntityId) {
+    const record = requireBody(body);
+    const typeId = record.typeId;
+    if (typeof typeId !== 'string' || typeId === '')
+        throw new StackQueryError('Invalid record body: typeId is required');
+    const content = record.content;
+    if (typeof content !== 'object' || content === null || Array.isArray(content))
+        throw new StackQueryError('Invalid record body: content is required');
+    const options = {};
+    const id = optionalString(record, 'id');
+    if (id !== undefined)
+        options.id = id;
+    const parentId = optionalString(record, 'parentId');
+    if (parentId !== undefined)
+        options.parentId = parentId;
+    const appId = optionalString(record, 'appId');
+    if (appId !== undefined)
+        options.appId = appId;
+    const permissions = optionalArray(record, 'permissions');
+    if (permissions !== undefined)
+        options.permissions = permissions;
+    const associations = optionalArray(record, 'associations');
+    if (associations !== undefined)
+        options.associations = associations;
+    // Presence is the whole signal: an unlisted record is unlisted from
+    // birth, so the timestamp a client sends has nothing to say.
+    if (optionalString(record, 'unlistedAt') !== undefined)
+        options.unlisted = true;
+    if (isOwnerActingAlone(session, ownerEntityId)) {
+        const createdAt = ownerDate(record, 'createdAt');
+        if (createdAt !== undefined)
+            options.createdAt = createdAt;
+        const updatedAt = ownerDate(record, 'updatedAt');
+        if (updatedAt !== undefined)
+            options.updatedAt = updatedAt;
+    }
+    return { typeId, content: content, options };
+}
+//# sourceMappingURL=wire-record.js.map

package/dist/wire-record.js.map

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

package/dist/wire-request.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Stack — Wire Request Parsing
+ * -------------------------------------------------------
+ * The parse half of the request encoding `adapter-api` builds: URL search
+ * params and JSON bodies in, the core types `Stack` takes out. Core has no
+ * HTTP server of its own — this module exists so every server
+ * implementation shares one decoding of the query grammar rather than
+ * transcribing docs/spec/wire-format.md § Records' parameter table and
+ * re-deriving its rules, which is where a miss produces a query that
+ * silently widens rather than one that fails.
+ *
+ * Three things this deliberately does not do:
+ *
+ * - **No clamping.** A `limit` ceiling is deployment policy, not wire
+ *   contract, so the requested limit is reported as asked and the server
+ *   applies its own cap afterwards.
+ * - **No capability gating.** `assertQueryCapabilities()` in
+ *   `@haverstack/core/adapter` stays a separate, deliberate call.
+ * - **No value validation beyond shape.** An ID's or a cursor's legality is
+ *   `Stack`'s to judge, and judging it twice would let the two answers
+ *   drift.
+ *
+ * Everything here throws `StackQueryError` on malformed input, which
+ * servers already map to 400 — see docs/spec/wire-format.md § Error
+ * responses.
+ */
+import type { ChangeFilter, StackQuery } from './types.js';
+/** Parse an ISO date string from a wire body; undefined if absent or invalid. */
+export declare function parseDate(val: unknown): Date | undefined;
+/**
+ * Strict positive-integer parse for a URL param — rejects "1abc", "2.7",
+ * "-5". Also serves the `:version` path params, which share this
+ * "malformed, don't silently coerce" requirement.
+ */
+export declare function parsePositiveInt(raw: string, label: string): number;
+/**
+ * Build a `StackQuery` from `GET /records` search params — the inverse of
+ * what `APIAdapter` encodes for a server without `contentFieldQuery`.
+ * `parentId=null` is the literal string, the sentinel for "top level":
+ * Crockford base-32 excludes `u` and `l`, so no record ID can collide
+ * with it. See docs/spec/wire-format.md § Records.
+ */
+export declare function parseQueryParams(url: URL): StackQuery;
+/**
+ * Build a `StackQuery` from a `POST /records/query` JSON body — the
+ * superset form, which additionally carries `filter.content`. Dates arrive
+ * as the ISO strings `JSON.stringify` made of them and are decoded back to
+ * `Date`. See docs/spec/wire-format.md § Records.
+ */
+export declare function parseQueryBody(raw: unknown): StackQuery;
+/**
+ * What `GET /changes`' query params carry. One object rather than three
+ * exports because `includeUnlisted` sits on `SubscribeOptions` rather than
+ * `ChangeFilter`, and a server needs it before the stream opens to answer
+ * the owner-only 403. See docs/spec/change-feed.md.
+ */
+export type ParsedChangeParams = {
+    filter: ChangeFilter;
+    includeRecords: boolean;
+    includeUnlisted: boolean;
+};
+/**
+ * Parse `GET /changes`' query params. The resume cursor is deliberately
+ * absent: `Last-Event-ID` outranks `?since=`, and reconciling the two is
+ * the server's own resumption machinery rather than request encoding.
+ */
+export declare function parseChangeParams(url: URL): ParsedChangeParams;
+/**
+ * Parse an `If-Match: "5"` header into the version for `ifVersion`.
+ * A value that is not a bare, optionally quoted version is refused rather
+ * than read as absent: the header exists to fence a write, so degrading a
+ * malformed one to an unconditional last-writer-wins mutation defeats the
+ * only thing it was sent to do. Weak comparators (`W/"5"`) are refused for
+ * the same reason — a version match is exact or it is nothing.
+ * See docs/spec/wire-format.md § Records.
+ */
+export declare function parseIfMatch(header: string | undefined): number | undefined;
+/**
+ * Read an upload's filename from its `Content-Disposition`. Prefers the
+ * RFC 5987 extended form (`filename*=UTF-8''name.txt`), which is what a
+ * client carrying a non-ASCII name sends, and falls back to the plain
+ * quoted form. See docs/spec/wire-format.md § Upload.
+ */
+export declare function parseUploadFilename(header: string | undefined): string | undefined;
+//# sourceMappingURL=wire-request.d.ts.map

package/dist/wire-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-request.d.ts","sourceRoot":"","sources":["../src/wire-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EACV,YAAY,EAMZ,UAAU,EACX,MAAM,YAAY,CAAC;AAMpB,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAIxD;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnE;AAwKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CA2ErD;AAaD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CA4DvD;AAMD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,kBAAkB,CA8B9D;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAK3E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAYlF"}