@haverstack/core 0.22.0 → 0.23.0

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"}

package/dist/wire-request.js

@@ -0,0 +1,435 @@
+/**
+ * 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 { StackQueryError } from './stack.js';
+// -------------------------------------------------------
+// Shared primitives
+// -------------------------------------------------------
+/** Parse an ISO date string from a wire body; undefined if absent or invalid. */
+export function parseDate(val) {
+    if (typeof val !== 'string')
+        return undefined;
+    const d = new Date(val);
+    return isNaN(d.getTime()) ? undefined : d;
+}
+const POSITIVE_INTEGER = /^\d+$/;
+const SORT_FIELDS = new Set(['createdAt', 'updatedAt', 'version']);
+const SORT_DIRECTIONS = new Set(['asc', 'desc']);
+const CHANGE_KINDS = new Set(['created', 'changed', 'deleted', 'purged']);
+const TARGET_SCOPES = new Set(['record', 'entity', 'external']);
+/**
+ * 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 function parsePositiveInt(raw, label) {
+    if (!POSITIVE_INTEGER.test(raw))
+        throw new StackQueryError(`Invalid ${label}: "${raw}"`);
+    return parseInt(raw, 10);
+}
+function requireDate(raw, label) {
+    const d = parseDate(raw);
+    if (!d)
+        throw new StackQueryError(`Invalid ${label}: ${JSON.stringify(raw)}`);
+    return d;
+}
+function requireSortField(raw) {
+    if (typeof raw !== 'string' || !SORT_FIELDS.has(raw))
+        throw new StackQueryError(`Invalid sort field: ${JSON.stringify(raw)}`);
+    return raw;
+}
+function requireSortDirection(raw) {
+    if (typeof raw !== 'string' || !SORT_DIRECTIONS.has(raw))
+        throw new StackQueryError(`Invalid sort direction: ${JSON.stringify(raw)}`);
+    return raw;
+}
+function requireString(raw, label) {
+    if (typeof raw !== 'string')
+        throw new StackQueryError(`Invalid ${label}: expected a string`);
+    return raw;
+}
+function requireStringOrArray(raw, label) {
+    if (typeof raw === 'string')
+        return raw;
+    if (Array.isArray(raw) && raw.every((v) => typeof v === 'string'))
+        return raw;
+    throw new StackQueryError(`Invalid ${label}: expected a string or array of strings`);
+}
+function requireStringArray(raw, label) {
+    if (!Array.isArray(raw) || !raw.every((v) => typeof v === 'string'))
+        throw new StackQueryError(`Invalid ${label}: expected an array of strings`);
+    return raw;
+}
+function requirePlainObject(raw, label) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw new StackQueryError(`Invalid ${label}: expected an object`);
+    return raw;
+}
+// -------------------------------------------------------
+// Filter fields that never travel
+// -------------------------------------------------------
+const BASE_ID_REFUSAL = 'baseId is resolved client-side against registered Types and never travels — send the ' +
+    'concrete typeId set it resolves to. See docs/spec/data-model.md § Filter.';
+const PRESENT_AT_REFUSAL = 'presentAt applies migration functions, which are app code rather than server code, so no ' +
+    'server can honor it — read records as stored and migrate them client-side. See ' +
+    'docs/spec/data-model.md § Type migrations.';
+/**
+ * Refuse the two `StackQuery` fields with no wire encoding, rather than
+ * dropping them. Both would otherwise return a result the caller believes
+ * is narrower (`baseId`) or migrated (`presentAt`) than what it holds —
+ * the same silent degradation `assertQueryCapabilities()` refuses for a
+ * capability-gated filter. See docs/spec/wire-format.md § Records.
+ */
+function assertNoUntravelableFields(hasBaseId, hasPresentAt) {
+    if (hasBaseId)
+        throw new StackQueryError(BASE_ID_REFUSAL);
+    if (hasPresentAt)
+        throw new StackQueryError(PRESENT_AT_REFUSAL);
+}
+// -------------------------------------------------------
+// Relationship filter
+// -------------------------------------------------------
+/**
+ * Route a `filter.relatedTo.target` by scope. Core validates the
+ * non-emptiness of whichever fields the scope names, so this only rejects
+ * a scope it does not recognize.
+ */
+function parseRelatedToTarget(raw) {
+    const t = requirePlainObject(raw, 'filter.relatedTo.target');
+    if (typeof t.scope !== 'string' || !TARGET_SCOPES.has(t.scope))
+        throw new StackQueryError(`Invalid filter.relatedTo.target.scope: ${JSON.stringify(t.scope)}`);
+    if (t.scope === 'record') {
+        return {
+            scope: 'record',
+            recordId: requireString(t.recordId, 'filter.relatedTo.target.recordId'),
+            ...(t.stackUrl !== undefined && {
+                stackUrl: requireString(t.stackUrl, 'filter.relatedTo.target.stackUrl'),
+            }),
+        };
+    }
+    if (t.scope === 'entity') {
+        return {
+            scope: 'entity',
+            entityId: requireString(t.entityId, 'filter.relatedTo.target.entityId'),
+        };
+    }
+    return {
+        scope: 'external',
+        ns: requireString(t.ns, 'filter.relatedTo.target.ns'),
+        ...(t.id !== undefined && { id: requireString(t.id, 'filter.relatedTo.target.id') }),
+    };
+}
+/** A label, a target, or both — the body form of the same filter. */
+function parseRelatedToBody(raw) {
+    const r = requirePlainObject(raw, 'filter.relatedTo');
+    const label = r.label !== undefined ? requireString(r.label, 'filter.relatedTo.label') : undefined;
+    const target = r.target !== undefined ? parseRelatedToTarget(r.target) : undefined;
+    return {
+        ...(label !== undefined && { label }),
+        ...(target !== undefined && { target }),
+    };
+}
+/**
+ * The `relatedTo*` URL params. Scope is implied by which of them appear and
+ * the three are mutually exclusive. An empty value passes through raw
+ * rather than as absent — that is what lets core's target validation tell
+ * "omitted" from "empty" for `relatedToStack` and `relatedToId`, where the
+ * two mean different things and neither is a wildcard.
+ * See docs/spec/wire-format.md § Records.
+ */
+function parseRelatedToParams(url) {
+    const hasRecord = url.searchParams.has('relatedTo');
+    const hasStack = url.searchParams.has('relatedToStack');
+    const hasEntity = url.searchParams.has('relatedToEntity');
+    const hasNs = url.searchParams.has('relatedToNs');
+    const hasId = url.searchParams.has('relatedToId');
+    const label = url.searchParams.get('relatedToLabel');
+    if ([hasRecord, hasEntity, hasNs].filter(Boolean).length > 1) {
+        throw new StackQueryError('relatedTo, relatedToEntity and relatedToNs name different target scopes and are mutually exclusive');
+    }
+    if (hasStack && !hasRecord)
+        throw new StackQueryError('relatedToStack is only valid alongside relatedTo');
+    if (hasId && !hasNs)
+        throw new StackQueryError('relatedToId is only valid alongside relatedToNs');
+    let target;
+    if (hasRecord) {
+        target = {
+            scope: 'record',
+            recordId: url.searchParams.get('relatedTo'),
+            ...(hasStack && { stackUrl: url.searchParams.get('relatedToStack') }),
+        };
+    }
+    else if (hasEntity) {
+        target = { scope: 'entity', entityId: url.searchParams.get('relatedToEntity') };
+    }
+    else if (hasNs) {
+        target = {
+            scope: 'external',
+            ns: url.searchParams.get('relatedToNs'),
+            ...(hasId && { id: url.searchParams.get('relatedToId') }),
+        };
+    }
+    if (target === undefined && !label)
+        return undefined;
+    return {
+        ...(target !== undefined && { target }),
+        ...(label && { label }),
+    };
+}
+// -------------------------------------------------------
+// GET /records
+// -------------------------------------------------------
+/**
+ * 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 function parseQueryParams(url) {
+    assertNoUntravelableFields(url.searchParams.has('baseId'), url.searchParams.has('presentAt'));
+    const filter = {};
+    const typeIds = url.searchParams.getAll('typeId');
+    if (typeIds.length)
+        filter.typeId = typeIds.length === 1 ? typeIds[0] : typeIds;
+    const parentId = url.searchParams.get('parentId');
+    if (parentId !== null)
+        filter.parentId = parentId === 'null' ? null : parentId;
+    const appIds = url.searchParams.getAll('appId');
+    if (appIds.length)
+        filter.appId = appIds.length === 1 ? appIds[0] : appIds;
+    const entityIds = url.searchParams.getAll('entityId');
+    if (entityIds.length)
+        filter.entityId = entityIds.length === 1 ? entityIds[0] : entityIds;
+    const principalIds = url.searchParams.getAll('principalId');
+    if (principalIds.length)
+        filter.principalId = principalIds.length === 1 ? principalIds[0] : principalIds;
+    const tags = url.searchParams.getAll('tag');
+    if (tags.length)
+        filter.tags = tags;
+    const hasAttachment = url.searchParams.get('hasAttachment');
+    if (hasAttachment)
+        filter.hasAttachment = hasAttachment;
+    const attachmentFileId = url.searchParams.get('attachmentFileId');
+    if (attachmentFileId)
+        filter.attachmentFileId = attachmentFileId;
+    const relatedTo = parseRelatedToParams(url);
+    if (relatedTo)
+        filter.relatedTo = relatedTo;
+    const search = url.searchParams.get('search');
+    if (search)
+        filter.search = search;
+    const createdBefore = url.searchParams.get('createdBefore');
+    const createdAfter = url.searchParams.get('createdAfter');
+    if (createdBefore || createdAfter) {
+        filter.createdAt = {
+            ...(createdBefore && { before: requireDate(createdBefore, 'createdBefore') }),
+            ...(createdAfter && { after: requireDate(createdAfter, 'createdAfter') }),
+        };
+    }
+    const updatedBefore = url.searchParams.get('updatedBefore');
+    const updatedAfter = url.searchParams.get('updatedAfter');
+    if (updatedBefore || updatedAfter) {
+        filter.updatedAt = {
+            ...(updatedBefore && { before: requireDate(updatedBefore, 'updatedBefore') }),
+            ...(updatedAfter && { after: requireDate(updatedAfter, 'updatedAfter') }),
+        };
+    }
+    if (url.searchParams.get('includeDeleted') === 'true')
+        filter.includeDeleted = true;
+    if (url.searchParams.get('includeUnlisted') === 'true')
+        filter.includeUnlisted = true;
+    const query = {};
+    if (Object.keys(filter).length)
+        query.filter = filter;
+    const sort = url.searchParams.get('sort');
+    const direction = url.searchParams.get('direction');
+    if (sort)
+        query.sort = {
+            field: requireSortField(sort),
+            ...(direction && { direction: requireSortDirection(direction) }),
+        };
+    const limit = url.searchParams.get('limit');
+    if (limit)
+        query.limit = parsePositiveInt(limit, 'limit');
+    const cursor = url.searchParams.get('cursor');
+    if (cursor)
+        query.cursor = cursor;
+    return query;
+}
+// -------------------------------------------------------
+// POST /records/query
+// -------------------------------------------------------
+/** Validate a limit that already arrived as a JSON number. */
+function parseLimitValue(raw) {
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw <= 0)
+        throw new StackQueryError(`Invalid limit: ${JSON.stringify(raw)}`);
+    return raw;
+}
+/**
+ * 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 function parseQueryBody(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const body = raw;
+    const f = body.filter !== undefined ? requirePlainObject(body.filter, 'filter') : undefined;
+    assertNoUntravelableFields(f !== undefined && 'baseId' in f, 'presentAt' in body);
+    const query = {};
+    if (f) {
+        const filter = {};
+        if (f.typeId !== undefined)
+            filter.typeId = requireStringOrArray(f.typeId, 'filter.typeId');
+        if (f.parentId !== undefined)
+            filter.parentId = f.parentId === null ? null : requireString(f.parentId, 'filter.parentId');
+        if (f.appId !== undefined)
+            filter.appId = requireStringOrArray(f.appId, 'filter.appId');
+        if (f.entityId !== undefined)
+            filter.entityId = requireStringOrArray(f.entityId, 'filter.entityId');
+        if (f.principalId !== undefined)
+            filter.principalId = requireStringOrArray(f.principalId, 'filter.principalId');
+        if (f.tags !== undefined)
+            filter.tags = requireStringArray(f.tags, 'filter.tags');
+        if (f.hasAttachment !== undefined)
+            filter.hasAttachment = requireString(f.hasAttachment, 'filter.hasAttachment');
+        if (f.attachmentFileId !== undefined)
+            filter.attachmentFileId = requireString(f.attachmentFileId, 'filter.attachmentFileId');
+        if (f.relatedTo !== undefined)
+            filter.relatedTo = parseRelatedToBody(f.relatedTo);
+        if (f.content !== undefined)
+            filter.content = requirePlainObject(f.content, 'filter.content');
+        if (f.search !== undefined)
+            filter.search = requireString(f.search, 'filter.search');
+        if (f.includeDeleted)
+            filter.includeDeleted = true;
+        if (f.includeUnlisted)
+            filter.includeUnlisted = true;
+        if (f.createdAt) {
+            const r = requirePlainObject(f.createdAt, 'filter.createdAt');
+            filter.createdAt = {
+                ...(r.before !== undefined && { before: requireDate(r.before, 'filter.createdAt.before') }),
+                ...(r.after !== undefined && { after: requireDate(r.after, 'filter.createdAt.after') }),
+            };
+        }
+        if (f.updatedAt) {
+            const r = requirePlainObject(f.updatedAt, 'filter.updatedAt');
+            filter.updatedAt = {
+                ...(r.before !== undefined && { before: requireDate(r.before, 'filter.updatedAt.before') }),
+                ...(r.after !== undefined && { after: requireDate(r.after, 'filter.updatedAt.after') }),
+            };
+        }
+        query.filter = filter;
+    }
+    if (body.sort) {
+        const s = requirePlainObject(body.sort, 'sort');
+        query.sort = {
+            field: requireSortField(s.field),
+            ...(s.direction !== undefined && { direction: requireSortDirection(s.direction) }),
+        };
+    }
+    if (body.limit !== undefined)
+        query.limit = parseLimitValue(body.limit);
+    if (typeof body.cursor === 'string')
+        query.cursor = body.cursor;
+    return query;
+}
+/**
+ * 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 function parseChangeParams(url) {
+    const filter = {};
+    const typeIds = url.searchParams.getAll('typeId');
+    if (typeIds.length)
+        filter.typeId = typeIds.length === 1 ? typeIds[0] : typeIds;
+    const parentId = url.searchParams.get('parentId');
+    if (parentId !== null)
+        filter.parentId = parentId === 'null' ? null : parentId;
+    const entityId = url.searchParams.get('entityId');
+    if (entityId !== null)
+        filter.entityId = entityId;
+    const kinds = url.searchParams.getAll('kind');
+    if (kinds.length) {
+        for (const kind of kinds) {
+            if (!CHANGE_KINDS.has(kind))
+                throw new StackQueryError(`Invalid kind: "${kind}"`);
+        }
+        filter.kinds = kinds;
+    }
+    const include = url.searchParams.get('include');
+    if (include !== null && include !== 'record')
+        throw new StackQueryError(`Invalid include: "${include}"`);
+    return {
+        filter,
+        includeRecords: include === 'record',
+        includeUnlisted: url.searchParams.get('includeUnlisted') === 'true',
+    };
+}
+// -------------------------------------------------------
+// Headers
+// -------------------------------------------------------
+/**
+ * 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 function parseIfMatch(header) {
+    if (header === undefined)
+        return undefined;
+    const trimmed = header.trim();
+    const unquoted = /^"(.*)"$/.exec(trimmed)?.[1] ?? trimmed;
+    return parsePositiveInt(unquoted, 'If-Match');
+}
+/**
+ * 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 function parseUploadFilename(header) {
+    if (!header)
+        return undefined;
+    const extended = /filename\*\s*=\s*[^']*'[^']*'([^;]+)/i.exec(header);
+    if (extended) {
+        try {
+            return decodeURIComponent(extended[1].trim());
+        }
+        catch {
+            // Malformed percent-encoding — fall through to the plain form.
+        }
+    }
+    const plain = /filename\s*=\s*"([^"]+)"/i.exec(header);
+    return plain ? plain[1] : undefined;
+}
+//# sourceMappingURL=wire-request.js.map