@haverstack/core 0.37.0 → 0.39.0

package/dist/wire-request.js

@@ -20,11 +20,12 @@
  *   `Stack`'s to judge, and judging it twice would let the two answers
  *   drift.
  *
- * Everything here throws `StackQueryError` on malformed input, which
+ * Everything here throws `StackBadRequestError` on malformed input, which
  * servers already map to 400 — see docs/spec/wire-format.md § Error
  * responses.
  */
-import { StackQueryError } from './errors.js';
+import { StackBadRequestError } from './errors.js';
+import { TARGET_KEYS } from './query-validation.js';
 import { NATIVE_SORT_FIELDS } from './types.js';
 // -------------------------------------------------------
 // Shared primitives
@@ -40,7 +41,70 @@ const POSITIVE_INTEGER = /^\d+$/;
 const SORT_FIELDS = new Set(NATIVE_SORT_FIELDS);
 const SORT_DIRECTIONS = new Set(['asc', 'desc']);
 const CHANGE_KINDS = new Set(['created', 'changed', 'deleted', 'purged']);
-const TARGET_SCOPES = new Set(['record', 'entity', 'external']);
+const ASSOCIATION_KINDS = new Set(['tag', 'attachment', 'relationship']);
+const TARGET_KINDS = new Set(['record', 'entity', 'external']);
+/** Every param `GET /records` defines. See docs/spec/wire-format.md § Records. */
+const RECORD_QUERY_PARAMS = [
+    'typeId',
+    'parentId',
+    'appId',
+    'createdBySubject',
+    'createdByPrincipal',
+    'tag',
+    'attachmentLabel',
+    'attachmentFileId',
+    'referencesFileId',
+    'relatedTo',
+    'relatedToStack',
+    'relatedToEntity',
+    'relatedToNs',
+    'relatedToId',
+    'relatedToLabel',
+    'search',
+    'createdBefore',
+    'createdAfter',
+    'updatedBefore',
+    'updatedAfter',
+    'includeDeleted',
+    'includeUnlisted',
+    'sort',
+    'sortContent',
+    'direction',
+    'limit',
+    'cursor',
+];
+const QUERY_BODY_FILTER_KEYS = [
+    'typeId',
+    'parentId',
+    'appId',
+    'createdBy',
+    'tags',
+    'attachment',
+    'referencesFileId',
+    'relatedTo',
+    'content',
+    'contentPresent',
+    'search',
+    'includeDeleted',
+    'includeUnlisted',
+    'createdAt',
+    'updatedAt',
+];
+/**
+ * Every param `GET /changes` defines. `since` is the resume cursor, which
+ * the server reads itself — see parseChangeParams().
+ */
+const CHANGE_PARAMS = [
+    'typeId',
+    'baseId',
+    'parentId',
+    'createdBySubject',
+    'createdByPrincipal',
+    'kind',
+    'include',
+    'includeUnlisted',
+    'since',
+];
 /**
  * Strict positive-integer parse for a URL param — rejects "1abc", "2.7",
  * "-5". Also serves the `:version` path params, which share this
@@ -48,18 +112,18 @@ const TARGET_SCOPES = new Set(['record', 'entity', 'external']);
  */
 export function parsePositiveInt(raw, label) {
     if (!POSITIVE_INTEGER.test(raw))
-        throw new StackQueryError(`Invalid ${label}: "${raw}"`);
+        throw new StackBadRequestError(`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)}`);
+        throw new StackBadRequestError(`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)}`);
+        throw new StackBadRequestError(`Invalid sort field: ${JSON.stringify(raw)}`);
     return raw;
 }
 /**
@@ -70,7 +134,7 @@ function requireSortField(raw) {
  */
 function buildSort(field, contentField, direction) {
     if (field !== undefined && field !== null && contentField !== undefined && contentField !== null)
-        throw new StackQueryError('A sort names either a native field or a content field, never both.');
+        throw new StackBadRequestError('A sort names either a native field or a content field, never both.');
     const dir = direction === undefined || direction === null ? undefined : requireSortDirection(direction);
     if (contentField !== undefined && contentField !== null) {
         return {
@@ -85,12 +149,12 @@ function buildSort(field, contentField, direction) {
 }
 function requireSortDirection(raw) {
     if (typeof raw !== 'string' || !SORT_DIRECTIONS.has(raw))
-        throw new StackQueryError(`Invalid sort direction: ${JSON.stringify(raw)}`);
+        throw new StackBadRequestError(`Invalid sort direction: ${JSON.stringify(raw)}`);
     return raw;
 }
 function requireString(raw, label) {
     if (typeof raw !== 'string')
-        throw new StackQueryError(`Invalid ${label}: expected a string`);
+        throw new StackBadRequestError(`Invalid ${label}: expected a string`);
     return raw;
 }
 function requireStringOrArray(raw, label) {
@@ -98,16 +162,67 @@ function requireStringOrArray(raw, label) {
         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`);
+    throw new StackBadRequestError(`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`);
+        throw new StackBadRequestError(`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`);
+        throw new StackBadRequestError(`Invalid ${label}: expected an object`);
+    return raw;
+}
+/**
+ * A plain object carrying only `keys`. An unrecognized key is refused
+ * rather than ignored, since ignoring it answers a different request than
+ * the one sent. See docs/spec/wire-format.md § Unrecognized input.
+ */
+function requireKnownKeys(raw, keys, label) {
+    const obj = requirePlainObject(raw, label);
+    const unknown = Object.keys(obj).filter((key) => !keys.includes(key));
+    if (unknown.length > 0)
+        throw new StackBadRequestError(`Unknown key${unknown.length > 1 ? 's' : ''} in ${label}: ${unknown.join(', ')}`);
+    return obj;
+}
+/**
+ * Params a filter repeats to name several values. Any other param names
+ * one value, so a repeat of it is refused rather than read as its first.
+ */
+const REPEATABLE_PARAMS = new Set([
+    'typeId',
+    'baseId',
+    'appId',
+    'createdBySubject',
+    'createdByPrincipal',
+    'tag',
+    'kind',
+]);
+/** The URL-param form of requireKnownKeys(), which also refuses a repeat. */
+function requireKnownParams(url, names) {
+    const present = [...new Set(url.searchParams.keys())];
+    const unknown = present.filter((name) => !names.includes(name));
+    if (unknown.length > 0)
+        throw new StackBadRequestError(`Unknown query param${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}`);
+    const repeated = present.filter((name) => !REPEATABLE_PARAMS.has(name) && url.searchParams.getAll(name).length > 1);
+    if (repeated.length > 0)
+        throw new StackBadRequestError(`Repeated query param${repeated.length > 1 ? 's' : ''}: ${repeated.join(', ')}`);
+}
+/** A boolean URL param: absent is false, and only `true`/`false` are values. */
+function booleanParam(url, name) {
+    const value = url.searchParams.get(name);
+    if (value === null || value === 'false')
+        return false;
+    if (value === 'true')
+        return true;
+    throw new StackBadRequestError(`Invalid ${name}: expected true or false, got "${value}"`);
+}
+function optionalBoolean(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'boolean')
+        throw new StackBadRequestError(`Invalid ${label}: expected a boolean`);
     return raw;
 }
 // -------------------------------------------------------
@@ -127,9 +242,9 @@ const PRESENT_AT_REFUSAL = 'presentAt applies migration functions, which are app
  */
 function assertNoUntravelableFields(hasBaseId, hasPresentAt) {
     if (hasBaseId)
-        throw new StackQueryError(BASE_ID_REFUSAL);
+        throw new StackBadRequestError(BASE_ID_REFUSAL);
     if (hasPresentAt)
-        throw new StackQueryError(PRESENT_AT_REFUSAL);
+        throw new StackBadRequestError(PRESENT_AT_REFUSAL);
 }
 /**
  * The client half of the same refusal, applied before a request is built
@@ -151,38 +266,40 @@ export function assertQueryTravels(query) {
 // 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.
+ * Route a `filter.relatedTo.target` by kind. Core validates the
+ * non-emptiness of whichever fields the kind names, so this only rejects
+ * a kind 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') {
+    const label = 'filter.relatedTo.target';
+    const kind = requirePlainObject(raw, label).kind;
+    if (typeof kind !== 'string' || !TARGET_KINDS.has(kind))
+        throw new StackBadRequestError(`Invalid filter.relatedTo.target.kind: ${JSON.stringify(kind)}`);
+    const t = requireKnownKeys(raw, TARGET_KEYS[kind], label);
+    if (t.kind === 'record') {
         return {
-            scope: 'record',
+            kind: 'record',
             recordId: requireString(t.recordId, 'filter.relatedTo.target.recordId'),
             ...(t.stackUrl !== undefined && {
                 stackUrl: requireString(t.stackUrl, 'filter.relatedTo.target.stackUrl'),
             }),
         };
     }
-    if (t.scope === 'entity') {
+    if (t.kind === 'entity') {
         return {
-            scope: 'entity',
+            kind: 'entity',
             entityId: requireString(t.entityId, 'filter.relatedTo.target.entityId'),
         };
     }
     return {
-        scope: 'external',
+        kind: '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 r = requireKnownKeys(raw, ['label', 'target'], 'filter.relatedTo');
     const label = r.label !== undefined ? requireString(r.label, 'filter.relatedTo.label') : undefined;
     const target = r.target !== undefined ? parseRelatedToTarget(r.target) : undefined;
     return {
@@ -206,26 +323,26 @@ function parseRelatedToParams(url) {
     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');
+        throw new StackBadRequestError('relatedTo, relatedToEntity and relatedToNs name different target kinds and are mutually exclusive');
     }
     if (hasStack && !hasRecord)
-        throw new StackQueryError('relatedToStack is only valid alongside relatedTo');
+        throw new StackBadRequestError('relatedToStack is only valid alongside relatedTo');
     if (hasId && !hasNs)
-        throw new StackQueryError('relatedToId is only valid alongside relatedToNs');
+        throw new StackBadRequestError('relatedToId is only valid alongside relatedToNs');
     let target;
     if (hasRecord) {
         target = {
-            scope: 'record',
+            kind: 'record',
             recordId: url.searchParams.get('relatedTo'),
             ...(hasStack && { stackUrl: url.searchParams.get('relatedToStack') }),
         };
     }
     else if (hasEntity) {
-        target = { scope: 'entity', entityId: url.searchParams.get('relatedToEntity') };
+        target = { kind: 'entity', entityId: url.searchParams.get('relatedToEntity') };
     }
     else if (hasNs) {
         target = {
-            scope: 'external',
+            kind: 'external',
             ns: url.searchParams.get('relatedToNs'),
             ...(hasId && { id: url.searchParams.get('relatedToId') }),
         };
@@ -237,9 +354,44 @@ function parseRelatedToParams(url) {
         ...(label && { label }),
     };
 }
+/**
+ * The `attachment*` URL params; both halves together match one association.
+ * An empty value passes through rather than reading as absent, so it
+ * narrows to nothing instead of silently widening the query.
+ */
+function parseAttachmentParams(url) {
+    const label = url.searchParams.get('attachmentLabel');
+    const fileId = url.searchParams.get('attachmentFileId');
+    if (label === null && fileId === null)
+        return undefined;
+    return {
+        ...(label !== null && { label }),
+        ...(fileId !== null && { fileId }),
+    };
+}
+function parseAttachmentBody(raw) {
+    const a = requireKnownKeys(raw, ['label', 'fileId'], 'filter.attachment');
+    return {
+        ...(a.label !== undefined && { label: requireString(a.label, 'filter.attachment.label') }),
+        ...(a.fileId !== undefined && { fileId: requireString(a.fileId, 'filter.attachment.fileId') }),
+    };
+}
 // -------------------------------------------------------
 // GET /records
 // -------------------------------------------------------
+/** The author filter, spelled the same on `GET /records` and `GET /changes`. */
+function parseCreatedByParams(url) {
+    const subjectIds = url.searchParams.getAll('createdBySubject');
+    const principalIds = url.searchParams.getAll('createdByPrincipal');
+    if (!subjectIds.length && !principalIds.length)
+        return undefined;
+    return {
+        ...(subjectIds.length && { subjectId: subjectIds.length === 1 ? subjectIds[0] : subjectIds }),
+        ...(principalIds.length && {
+            principalId: principalIds.length === 1 ? principalIds[0] : principalIds,
+        }),
+    };
+}
 /**
  * Build a `StackQuery` from `GET /records` search params — the inverse of
  * what `APIAdapter` encodes for a server that reaches no content.
@@ -249,6 +401,7 @@ function parseRelatedToParams(url) {
  */
 export function parseQueryParams(url) {
     assertNoUntravelableFields(url.searchParams.has('baseId'), url.searchParams.has('presentAt'));
+    requireKnownParams(url, RECORD_QUERY_PARAMS);
     const filter = {};
     const typeIds = url.searchParams.getAll('typeId');
     if (typeIds.length)
@@ -259,21 +412,18 @@ export function parseQueryParams(url) {
     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 createdBy = parseCreatedByParams(url);
+    if (createdBy)
+        filter.createdBy = createdBy;
     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 attachment = parseAttachmentParams(url);
+    if (attachment)
+        filter.attachment = attachment;
+    const referencesFileId = url.searchParams.get('referencesFileId');
+    if (referencesFileId)
+        filter.referencesFileId = referencesFileId;
     const relatedTo = parseRelatedToParams(url);
     if (relatedTo)
         filter.relatedTo = relatedTo;
@@ -296,9 +446,9 @@ export function parseQueryParams(url) {
             ...(updatedAfter && { after: requireDate(updatedAfter, 'updatedAfter') }),
         };
     }
-    if (url.searchParams.get('includeDeleted') === 'true')
+    if (booleanParam(url, 'includeDeleted'))
         filter.includeDeleted = true;
-    if (url.searchParams.get('includeUnlisted') === 'true')
+    if (booleanParam(url, 'includeUnlisted'))
         filter.includeUnlisted = true;
     const query = {};
     if (Object.keys(filter).length)
@@ -320,21 +470,26 @@ export function parseQueryParams(url) {
 /** 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)}`);
+        throw new StackBadRequestError(`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.
+ * `Date`. `undefined` is the absent body; `null` or any other non-object
+ * is refused, so a server hands over no body as `undefined`.
+ * See docs/spec/wire-format.md § Records.
  */
 export function parseQueryBody(raw) {
-    if (!raw || typeof raw !== 'object')
+    if (raw === undefined)
         return {};
-    const body = raw;
+    const body = requirePlainObject(raw, 'query body');
     const f = body.filter !== undefined ? requirePlainObject(body.filter, 'filter') : undefined;
     assertNoUntravelableFields(f !== undefined && 'baseId' in f, 'presentAt' in body);
+    requireKnownKeys(body, ['filter', 'sort', 'limit', 'cursor'], 'query body');
+    if (f)
+        requireKnownKeys(f, QUERY_BODY_FILTER_KEYS, 'filter');
     const query = {};
     if (f) {
         const filter = {};
@@ -344,16 +499,23 @@ export function parseQueryBody(raw) {
             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.createdBy !== undefined) {
+            const by = requireKnownKeys(f.createdBy, ['subjectId', 'principalId'], 'filter.createdBy');
+            filter.createdBy = {
+                ...(by.subjectId !== undefined && {
+                    subjectId: requireStringOrArray(by.subjectId, 'filter.createdBy.subjectId'),
+                }),
+                ...(by.principalId !== undefined && {
+                    principalId: requireStringOrArray(by.principalId, 'filter.createdBy.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.attachment !== undefined)
+            filter.attachment = parseAttachmentBody(f.attachment);
+        if (f.referencesFileId !== undefined)
+            filter.referencesFileId = requireString(f.referencesFileId, 'filter.referencesFileId');
         if (f.relatedTo !== undefined)
             filter.relatedTo = parseRelatedToBody(f.relatedTo);
         if (f.content !== undefined)
@@ -362,19 +524,19 @@ export function parseQueryBody(raw) {
             filter.contentPresent = requireStringArray(f.contentPresent, 'filter.contentPresent');
         if (f.search !== undefined)
             filter.search = requireString(f.search, 'filter.search');
-        if (f.includeDeleted)
+        if (optionalBoolean(f.includeDeleted, 'filter.includeDeleted'))
             filter.includeDeleted = true;
-        if (f.includeUnlisted)
+        if (optionalBoolean(f.includeUnlisted, 'filter.includeUnlisted'))
             filter.includeUnlisted = true;
-        if (f.createdAt) {
-            const r = requirePlainObject(f.createdAt, 'filter.createdAt');
+        if (f.createdAt !== undefined) {
+            const r = requireKnownKeys(f.createdAt, ['before', 'after'], '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');
+        if (f.updatedAt !== undefined) {
+            const r = requireKnownKeys(f.updatedAt, ['before', 'after'], 'filter.updatedAt');
             filter.updatedAt = {
                 ...(r.before !== undefined && { before: requireDate(r.before, 'filter.updatedAt.before') }),
                 ...(r.after !== undefined && { after: requireDate(r.after, 'filter.updatedAt.after') }),
@@ -382,17 +544,17 @@ export function parseQueryBody(raw) {
         }
         query.filter = filter;
     }
-    if (body.sort) {
-        const s = requirePlainObject(body.sort, 'sort');
+    if (body.sort !== undefined) {
+        const s = requireKnownKeys(body.sort, ['field', 'contentField', 'direction'], 'sort');
         const sort = buildSort(s.field, s.contentField, s.direction);
         if (!sort)
-            throw new StackQueryError('Invalid sort: expected a field or a contentField.');
+            throw new StackBadRequestError('Invalid sort: expected a field or a contentField.');
         query.sort = sort;
     }
     if (body.limit !== undefined)
         query.limit = parseLimitValue(body.limit);
-    if (typeof body.cursor === 'string')
-        query.cursor = body.cursor;
+    if (body.cursor !== undefined)
+        query.cursor = requireString(body.cursor, 'cursor');
     return query;
 }
 /**
@@ -401,31 +563,35 @@ export function parseQueryBody(raw) {
  * the server's own resumption machinery rather than request encoding.
  */
 export function parseChangeParams(url) {
+    requireKnownParams(url, CHANGE_PARAMS);
     const filter = {};
     const typeIds = url.searchParams.getAll('typeId');
     if (typeIds.length)
         filter.typeId = typeIds.length === 1 ? typeIds[0] : typeIds;
+    const baseIds = url.searchParams.getAll('baseId');
+    if (baseIds.length)
+        filter.baseId = baseIds.length === 1 ? baseIds[0] : baseIds;
     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 createdBy = parseCreatedByParams(url);
+    if (createdBy)
+        filter.createdBy = createdBy;
     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}"`);
+                throw new StackBadRequestError(`Invalid kind: "${kind}"`);
         }
         filter.kinds = kinds;
     }
     const include = url.searchParams.get('include');
     if (include !== null && include !== 'record')
-        throw new StackQueryError(`Invalid include: "${include}"`);
+        throw new StackBadRequestError(`Invalid include: "${include}"`);
     return {
         filter,
         includeRecords: include === 'record',
-        includeUnlisted: url.searchParams.get('includeUnlisted') === 'true',
+        includeUnlisted: booleanParam(url, 'includeUnlisted'),
     };
 }
 /**
@@ -434,20 +600,63 @@ export function parseChangeParams(url) {
  * omitting `limit` reads the whole log by contract, so supplying a page
  * size here would truncate exactly the caller that omitted it.
  *
- * `sinceSeq` is a journal `seq` — a dense per-record integer, never the
+ * `afterSeq` is a journal `seq` — a dense per-record integer, never the
  * change feed's opaque cursor. See docs/spec/wire-format.md § Journal.
  */
 export function parseJournalParams(url) {
+    requireKnownParams(url, ['afterSeq', 'limit']);
     const query = {};
-    const sinceSeq = url.searchParams.get('sinceSeq');
-    if (sinceSeq !== null)
-        query.sinceSeq = parsePositiveInt(sinceSeq, 'sinceSeq');
+    const afterSeq = url.searchParams.get('afterSeq');
+    if (afterSeq !== null)
+        query.afterSeq = parsePositiveInt(afterSeq, 'afterSeq');
     const limit = url.searchParams.get('limit');
     if (limit !== null)
         query.limit = parsePositiveInt(limit, 'limit');
     return query;
 }
 // -------------------------------------------------------
+// DELETE /records/:id
+// -------------------------------------------------------
+/**
+ * Parse `DELETE /records/:id`'s query params into the `purge` flag. A
+ * misspelled or non-boolean `purge` is refused rather than read as a soft
+ * delete. See docs/spec/wire-format.md § Records.
+ */
+export function parseDeleteParams(url) {
+    requireKnownParams(url, ['purge']);
+    return { purge: booleanParam(url, 'purge') };
+}
+/** Parse `GET /attachments/:fileId`'s query params. See docs/spec/wire-format.md § Download. */
+export function parseDownloadParams(url) {
+    requireKnownParams(url, ['contentType', 'filename']);
+    const contentType = url.searchParams.get('contentType');
+    const filename = url.searchParams.get('filename');
+    return {
+        ...(contentType !== null && { contentTypeParam: contentType }),
+        ...(filename !== null && { filenameParam: filename }),
+    };
+}
+/**
+ * Parse `GET /records/:id/associations`' query params. An unrecognized
+ * `kind` is refused, since reading it as absent would answer with every
+ * kind. `kind` repeats on `GET /changes` but names one value here, so a
+ * repeat is refused rather than read as its first.
+ * See docs/spec/wire-format.md § Associations.
+ */
+export function parseAssociationParams(url) {
+    requireKnownParams(url, ['kind', 'label']);
+    if (url.searchParams.getAll('kind').length > 1)
+        throw new StackBadRequestError('Repeated query param: kind');
+    const kind = url.searchParams.get('kind');
+    if (kind !== null && !ASSOCIATION_KINDS.has(kind))
+        throw new StackBadRequestError(`Invalid kind: "${kind}"`);
+    const label = url.searchParams.get('label');
+    return {
+        ...(kind !== null && { kind: kind }),
+        ...(label !== null && { label }),
+    };
+}
+// -------------------------------------------------------
 // Headers
 // -------------------------------------------------------
 /**