@selvajs/server 1.1.0 → 1.3.0

package/dist/api/map-core-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The domain errors this package's own handlers raise, folded into the envelope.
+ *
+ * A host's `mapError` should call this first and add only its own error types.
+ * These rules cannot live solely in a host: the handler that throws them ships
+ * from here, so a host that forgot one would serve 500 where every other host
+ * serves 503 — the same API answering differently depending on who mounted it.
+ *
+ * Postgres surfaces a unique-constraint name verbatim, which is useless to an
+ * end user, so the constraints this package's handlers can trip are translated
+ * here rather than left to each host.
+ */
+import { ApiError } from './errors.js';
+/**
+ * Compute unreachable or serving an unreadable schema is operator-side (503); a
+ * schema the parser cannot read is the caller's file (422).
+ */
+export declare function mapCoreError(err: unknown): ApiError | undefined;
+//# sourceMappingURL=map-core-error.d.ts.map

package/dist/api/map-core-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-core-error.d.ts","sourceRoot":"","sources":["../../src/api/map-core-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAA+B,MAAM,aAAa,CAAC;AAmBpE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAc/D"}

package/dist/api/map-core-error.js

@@ -0,0 +1,49 @@
+/**
+ * The domain errors this package's own handlers raise, folded into the envelope.
+ *
+ * A host's `mapError` should call this first and add only its own error types.
+ * These rules cannot live solely in a host: the handler that throws them ships
+ * from here, so a host that forgot one would serve 500 where every other host
+ * serves 503 — the same API answering differently depending on who mounted it.
+ *
+ * Postgres surfaces a unique-constraint name verbatim, which is useless to an
+ * end user, so the constraints this package's handlers can trip are translated
+ * here rather than left to each host.
+ */
+import { ApiError, ApiErrorCode, codeForStatus } from './errors.js';
+import { ComputeServerUnconfiguredError } from '../compute/errors.js';
+import { SchemaExtractionError } from '../definitions/schema-extraction.js';
+import { ProviderError } from '@selvajs/platform';
+const UNIQUE_CONSTRAINT_MESSAGES = {
+    projects_org_name_unique: 'A project with that name already exists in this organization.',
+    projects_org_id_slug_key: 'A project with that name already exists in this organization.',
+    orgs_slug_key: 'An organization with that slug already exists.',
+    definitions_pkey: 'A definition with that ID already exists.'
+};
+function friendlyConstraintMessage(raw) {
+    for (const [name, msg] of Object.entries(UNIQUE_CONSTRAINT_MESSAGES)) {
+        if (raw.includes(name))
+            return msg;
+    }
+    return null;
+}
+/**
+ * Compute unreachable or serving an unreadable schema is operator-side (503); a
+ * schema the parser cannot read is the caller's file (422).
+ */
+export function mapCoreError(err) {
+    if (err instanceof SchemaExtractionError) {
+        return err.kind === 'unreachable' || err.kind === 'malformed'
+            ? new ApiError(503, ApiErrorCode.COMPUTE_UNAVAILABLE, err.message)
+            : new ApiError(422, ApiErrorCode.UNPROCESSABLE, err.message);
+    }
+    if (err instanceof ComputeServerUnconfiguredError) {
+        return new ApiError(503, ApiErrorCode.COMPUTE_UNAVAILABLE, err.message);
+    }
+    if (err instanceof ProviderError) {
+        const friendly = friendlyConstraintMessage(err.message);
+        return new ApiError(err.statusCode, codeForStatus(err.statusCode), friendly ?? err.message);
+    }
+    return undefined;
+}
+//# sourceMappingURL=map-core-error.js.map

package/dist/api/map-core-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-core-error.js","sourceRoot":"","sources":["../../src/api/map-core-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,0BAA0B,GAA2B;IAC1D,wBAAwB,EAAE,+DAA+D;IACzF,wBAAwB,EAAE,+DAA+D;IACzF,aAAa,EAAE,gDAAgD;IAC/D,gBAAgB,EAAE,2CAA2C;CAC7D,CAAC;AAEF,SAAS,yBAAyB,CAAC,GAAW;IAC7C,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,0BAA0B,CAAC,EAAE,CAAC;QACtE,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,GAAG,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACxC,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;QAC1C,OAAO,GAAG,CAAC,IAAI,KAAK,aAAa,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW;YAC5D,CAAC,CAAC,IAAI,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC,mBAAmB,EAAE,GAAG,CAAC,OAAO,CAAC;YAClE,CAAC,CAAC,IAAI,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,GAAG,YAAY,8BAA8B,EAAE,CAAC;QACnD,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC,mBAAmB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,yBAAyB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACxD,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC"}

package/dist/api/pagination.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Query-param parsing for the list pagination contract:
+ * `?limit=&cursor=&orderBy=&orderDir=` → `{ items, nextCursor? }`.
+ *
+ * Every list endpoint parses these identically, so the clamping lives here
+ * rather than inline per handler — a handler that clamps differently publishes
+ * a different contract under the same documented one, and nothing fails at
+ * build time.
+ */
+import type { DefinitionListOptions, ListOptions } from '@selvajs/platform';
+/**
+ * An unparseable or out-of-range `limit` clamps rather than 400s: pagination
+ * params are plumbing, and failing a read over one is hostile to clients
+ * walking a cursor.
+ */
+export declare function parseListOptions(url: URL): ListOptions;
+/** `parseListOptions` plus the definition-only `solveCount` ordering. */
+export declare function parseDefinitionListOptions(url: URL): DefinitionListOptions;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/api/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/api/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,WAAW,CAkBtD;AAED,yEAAyE;AACzE,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,GAAG,GAAG,qBAAqB,CAM1E"}

package/dist/api/pagination.js

@@ -0,0 +1,40 @@
+/**
+ * Query-param parsing for the list pagination contract:
+ * `?limit=&cursor=&orderBy=&orderDir=` → `{ items, nextCursor? }`.
+ *
+ * Every list endpoint parses these identically, so the clamping lives here
+ * rather than inline per handler — a handler that clamps differently publishes
+ * a different contract under the same documented one, and nothing fails at
+ * build time.
+ */
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '@selvajs/platform';
+/**
+ * An unparseable or out-of-range `limit` clamps rather than 400s: pagination
+ * params are plumbing, and failing a read over one is hostile to clients
+ * walking a cursor.
+ */
+export function parseListOptions(url) {
+    const raw = Number(url.searchParams.get('limit') ?? DEFAULT_PAGE_LIMIT);
+    const limit = Number.isFinite(raw)
+        ? Math.min(Math.max(Math.trunc(raw), 1), MAX_PAGE_LIMIT)
+        : DEFAULT_PAGE_LIMIT;
+    const orderByRaw = url.searchParams.get('orderBy');
+    const orderBy = orderByRaw === 'createdAt' || orderByRaw === 'updatedAt' || orderByRaw === 'name'
+        ? orderByRaw
+        : undefined;
+    return {
+        limit,
+        cursor: url.searchParams.get('cursor') ?? undefined,
+        orderBy,
+        orderDir: url.searchParams.get('orderDir') === 'asc' ? 'asc' : undefined
+    };
+}
+/** `parseListOptions` plus the definition-only `solveCount` ordering. */
+export function parseDefinitionListOptions(url) {
+    const base = parseListOptions(url);
+    if (url.searchParams.get('orderBy') === 'solveCount') {
+        return { ...base, orderBy: 'solveCount' };
+    }
+    return base;
+}
+//# sourceMappingURL=pagination.js.map

package/dist/api/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/api/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGvE;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAQ;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,kBAAkB,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QACjC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,CAAC;QACxD,CAAC,CAAC,kBAAkB,CAAC;IAEtB,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,OAAO,GACZ,UAAU,KAAK,WAAW,IAAI,UAAU,KAAK,WAAW,IAAI,UAAU,KAAK,MAAM;QAChF,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO;QACN,KAAK;QACL,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,SAAS;QACnD,OAAO;QACP,QAAQ,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;KACxE,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,0BAA0B,CAAC,GAAQ;IAClD,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,YAAY,EAAE,CAAC;QACtD,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/api/request.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Reading a request: path params, JSON bodies, multipart uploads.
+ *
+ * Every helper here fails by throwing `ApiError`, so a handler using them names
+ * no web framework. They were written against SvelteKit's `error()` and moved
+ * once the handlers themselves became transport-free — the logic never depended
+ * on the framework, only the throw did.
+ *
+ * `requireCaller` reads identity off `ApiRequest`, never off a host's `locals`
+ * — a host maps its own session shape onto `ctx`/`user` when it builds the
+ * request, and nothing below this line knows how it did that.
+ */
+import type { AuthUser, RequestContext } from '@selvajs/platform';
+import type { ZodError, ZodType } from 'zod';
+import type { ApiRequest } from './types.js';
+/**
+ * The authenticated caller, or a 401.
+ *
+ * `ctx` and `user` are optional on `ApiRequest` because a host builds one for
+ * anonymous requests too (share-token solves reach handlers with a `ctx` and no
+ * `user`). Every handler that needs an identity narrows it here rather than
+ * asserting the fields non-null, so the unauthenticated path fails as a denial
+ * instead of a crash.
+ */
+export declare function requireCaller(req: ApiRequest): {
+    ctx: RequestContext;
+    user: AuthUser;
+};
+/**
+ * Fail with a Zod error's messages, one per field.
+ *
+ * The top-level `message` names the first problem so a human reading the
+ * response learns something without parsing `fields`.
+ */
+export declare function throwZodError(err: ZodError): never;
+/**
+ * Read required path params, 400ing on any that is missing or blank.
+ *
+ * A router types every param as `string`, but a route can be reached with an
+ * empty segment — this catches that instead of letting a stale non-null
+ * assertion paper over it.
+ *
+ * Does **not** validate format — a guid-shaped param still goes through a
+ * schema where the route cares. Replaces the `if (!id) apiError(...)` preamble,
+ * not the schema check.
+ */
+export declare function requireParams<K extends string>(params: Partial<Record<string, string>>, ...names: K[]): Record<K, string>;
+/**
+ * Read a path param through a Zod schema, 400ing on a bad value.
+ *
+ * The format-checking counterpart to `requireParams` — for guids, enum-shaped
+ * segments, anything where "present" isn't the same as "valid".
+ */
+export declare function parseParam<T>(value: string | undefined, schema: ZodType<T>, name: string): T;
+/**
+ * Parse and validate a JSON body. A malformed body becomes `null` rather than
+ * throwing, so it fails the schema as a validation error — broken JSON gets a
+ * 400 naming the problem, not a 500 from `request.json()`.
+ *
+ * `missingAs` covers endpoints whose fields are all optional: passing `{}` lets
+ * an empty body mean "no changes" instead of a validation failure.
+ */
+export declare function parseBody<T>(request: Request, schema: ZodType<T>, { missingAs }?: {
+    missingAs?: unknown;
+}): Promise<T>;
+/**
+ * Pull a required file out of a multipart body and check its size and, where
+ * given, its extension.
+ *
+ * A second line of defence, not the first: a host's body-size guard should
+ * reject an oversized request before it is buffered. This catches a file that
+ * is individually too large inside a request that isn't.
+ *
+ * Caps are passed in rather than read here — they are deployment config, and a
+ * package that resolved them would pin every host to one source of truth.
+ */
+export declare function requireUpload(form: FormData, field: string, { maxBytes, extensions, contentTypes, label }: {
+    maxBytes: number;
+    extensions?: readonly string[];
+    contentTypes?: {
+        allowed: ReadonlySet<string>;
+        message: string;
+    };
+    label?: string;
+}): {
+    file: File;
+    extension: string;
+};
+/** A multipart text field, trimmed and length-capped. Absent stays `undefined`. */
+export declare function formText(form: FormData, field: string, { maxLength }?: {
+    maxLength?: number;
+}): string | undefined;
+//# sourceMappingURL=request.d.ts.map

package/dist/api/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/api/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG;IAAE,GAAG,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAKtF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,KAAK,CAWlD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC7C,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACvC,GAAG,KAAK,EAAE,CAAC,EAAE,GACX,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAqBnB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAM5F;AAMD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAChC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,EAAE,SAAS,EAAE,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACzC,OAAO,CAAC,CAAC,CAAC,CAKZ;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,EACb,EACC,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,KAAc,EACd,EAAE;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,GACC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CA4BnC;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CACvB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,EACb,EAAE,SAAS,EAAE,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,MAAM,GAAG,SAAS,CAMpB"}

package/dist/api/request.js

@@ -0,0 +1,150 @@
+/**
+ * Reading a request: path params, JSON bodies, multipart uploads.
+ *
+ * Every helper here fails by throwing `ApiError`, so a handler using them names
+ * no web framework. They were written against SvelteKit's `error()` and moved
+ * once the handlers themselves became transport-free — the logic never depended
+ * on the framework, only the throw did.
+ *
+ * `requireCaller` reads identity off `ApiRequest`, never off a host's `locals`
+ * — a host maps its own session shape onto `ctx`/`user` when it builds the
+ * request, and nothing below this line knows how it did that.
+ */
+import { apiError, ApiErrorCode } from './errors.js';
+/**
+ * The authenticated caller, or a 401.
+ *
+ * `ctx` and `user` are optional on `ApiRequest` because a host builds one for
+ * anonymous requests too (share-token solves reach handlers with a `ctx` and no
+ * `user`). Every handler that needs an identity narrows it here rather than
+ * asserting the fields non-null, so the unauthenticated path fails as a denial
+ * instead of a crash.
+ */
+export function requireCaller(req) {
+    if (!req.ctx || !req.user) {
+        apiError(401, ApiErrorCode.UNAUTHORIZED, 'Unauthorized');
+    }
+    return { ctx: req.ctx, user: req.user };
+}
+/**
+ * Fail with a Zod error's messages, one per field.
+ *
+ * The top-level `message` names the first problem so a human reading the
+ * response learns something without parsing `fields`.
+ */
+export function throwZodError(err) {
+    const fields = {};
+    for (const issue of err.issues) {
+        const key = issue.path.length ? issue.path.join('.') : '_';
+        // First message per field wins; later issues on the same path are
+        // usually redundant refinements.
+        if (!(key in fields))
+            fields[key] = issue.message;
+    }
+    const first = err.issues[0];
+    const path = first.path.length ? `${first.path.join('.')}: ` : '';
+    apiError(400, ApiErrorCode.VALIDATION_FAILED, `${path}${first.message}`, fields);
+}
+// ============================================================================
+// Path params
+// ============================================================================
+/**
+ * Read required path params, 400ing on any that is missing or blank.
+ *
+ * A router types every param as `string`, but a route can be reached with an
+ * empty segment — this catches that instead of letting a stale non-null
+ * assertion paper over it.
+ *
+ * Does **not** validate format — a guid-shaped param still goes through a
+ * schema where the route cares. Replaces the `if (!id) apiError(...)` preamble,
+ * not the schema check.
+ */
+export function requireParams(params, ...names) {
+    const out = {};
+    const missing = [];
+    for (const name of names) {
+        const value = params[name];
+        if (!value) {
+            missing.push(name);
+            continue;
+        }
+        out[name] = value;
+    }
+    if (missing.length) {
+        apiError(400, ApiErrorCode.VALIDATION_FAILED, `Missing path parameter${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+    }
+    return out;
+}
+/**
+ * Read a path param through a Zod schema, 400ing on a bad value.
+ *
+ * The format-checking counterpart to `requireParams` — for guids, enum-shaped
+ * segments, anything where "present" isn't the same as "valid".
+ */
+export function parseParam(value, schema, name) {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+        apiError(400, ApiErrorCode.VALIDATION_FAILED, `Invalid or missing ${name}`);
+    }
+    return parsed.data;
+}
+// ============================================================================
+// Request bodies
+// ============================================================================
+/**
+ * Parse and validate a JSON body. A malformed body becomes `null` rather than
+ * throwing, so it fails the schema as a validation error — broken JSON gets a
+ * 400 naming the problem, not a 500 from `request.json()`.
+ *
+ * `missingAs` covers endpoints whose fields are all optional: passing `{}` lets
+ * an empty body mean "no changes" instead of a validation failure.
+ */
+export async function parseBody(request, schema, { missingAs } = {}) {
+    const raw = await request.json().catch(() => null);
+    const parsed = schema.safeParse(raw ?? missingAs ?? null);
+    if (!parsed.success)
+        throwZodError(parsed.error);
+    return parsed.data;
+}
+// ============================================================================
+// Uploads
+// ============================================================================
+/**
+ * Pull a required file out of a multipart body and check its size and, where
+ * given, its extension.
+ *
+ * A second line of defence, not the first: a host's body-size guard should
+ * reject an oversized request before it is buffered. This catches a file that
+ * is individually too large inside a request that isn't.
+ *
+ * Caps are passed in rather than read here — they are deployment config, and a
+ * package that resolved them would pin every host to one source of truth.
+ */
+export function requireUpload(form, field, { maxBytes, extensions, contentTypes, label = 'File' }) {
+    const file = form.get(field);
+    if (!(file instanceof File) || file.size === 0) {
+        apiError(400, ApiErrorCode.VALIDATION_FAILED, `A ${label.toLowerCase()} is required`);
+    }
+    const extension = file.name.slice(file.name.lastIndexOf('.')).toLowerCase();
+    if (extensions && !extensions.includes(extension)) {
+        apiError(400, ApiErrorCode.VALIDATION_FAILED, `File type not allowed. Allowed: ${extensions.join(', ')}`);
+    }
+    if (contentTypes && !contentTypes.allowed.has(file.type)) {
+        apiError(400, ApiErrorCode.VALIDATION_FAILED, contentTypes.message);
+    }
+    if (file.size > maxBytes) {
+        apiError(400, ApiErrorCode.VALIDATION_FAILED, `${label} too large. Max size: ${maxBytes / (1024 * 1024)} MB`);
+    }
+    return { file, extension };
+}
+/** A multipart text field, trimmed and length-capped. Absent stays `undefined`. */
+export function formText(form, field, { maxLength } = {}) {
+    const raw = form.get(field);
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    return maxLength ? trimmed.slice(0, maxLength) : trimmed;
+}
+//# sourceMappingURL=request.js.map

package/dist/api/request.js.map

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

package/dist/api/respond.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Turn a handler result — or a thrown `ApiError` — into a web-standard
+ * `Response`.
+ *
+ * This is the whole serialization boundary. A host framework that speaks
+ * `Request`/`Response` (SvelteKit, Next route handlers, Hono, Remix) needs only
+ * to build an `ApiRequest` and call `runHandler`; one that does not can reuse
+ * `toErrorBody` and serialize itself.
+ */
+import { ApiError, ApiErrorCode } from './errors.js';
+import type { ApiHandler, ApiRequest } from './types.js';
+export interface ApiErrorBody {
+    message: string;
+    code: ApiErrorCode;
+    fields?: Record<string, string>;
+}
+export declare function toErrorBody(err: ApiError): ApiErrorBody;
+/**
+ * Run a handler and serialize whatever comes out, including failures.
+ *
+ * `mapError` lets a host fold its own domain errors into the envelope before
+ * the 500 fallback — the Selva app maps `ProviderError`, `SchemaExtractionError`
+ * and `ComputeServerUnconfiguredError` this way, none of which belong here.
+ */
+export declare function runHandler(handler: ApiHandler, req: ApiRequest, { fallback, mapError }: {
+    fallback: string;
+    mapError?: (err: unknown) => ApiError | undefined;
+}): Promise<Response>;
+//# sourceMappingURL=respond.d.ts.map

package/dist/api/respond.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../src/api/respond.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAe,MAAM,YAAY,CAAC;AAEtE,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,YAAY,CAIvD;AAcD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC/B,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,UAAU,EACf,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,SAAS,CAAA;CAAE,GAC7F,OAAO,CAAC,QAAQ,CAAC,CA0BnB"}

package/dist/api/respond.js

@@ -0,0 +1,59 @@
+/**
+ * Turn a handler result — or a thrown `ApiError` — into a web-standard
+ * `Response`.
+ *
+ * This is the whole serialization boundary. A host framework that speaks
+ * `Request`/`Response` (SvelteKit, Next route handlers, Hono, Remix) needs only
+ * to build an `ApiRequest` and call `runHandler`; one that does not can reuse
+ * `toErrorBody` and serialize itself.
+ */
+import { ApiErrorCode, isApiError } from './errors.js';
+export function toErrorBody(err) {
+    return err.fields
+        ? { message: err.message, code: err.code, fields: err.fields }
+        : { message: err.message, code: err.code };
+}
+function toResponse(result) {
+    if (result instanceof Response)
+        return result;
+    const { status, body, headers } = result;
+    if (body === undefined)
+        return new Response(null, { status: status ?? 204, headers });
+    return new Response(JSON.stringify(body), {
+        status: status ?? 200,
+        headers: { 'content-type': 'application/json', ...headers }
+    });
+}
+/**
+ * Run a handler and serialize whatever comes out, including failures.
+ *
+ * `mapError` lets a host fold its own domain errors into the envelope before
+ * the 500 fallback — the Selva app maps `ProviderError`, `SchemaExtractionError`
+ * and `ComputeServerUnconfiguredError` this way, none of which belong here.
+ */
+export async function runHandler(handler, req, { fallback, mapError }) {
+    try {
+        return toResponse(await handler(req));
+    }
+    catch (err) {
+        if (isApiError(err)) {
+            return toResponse({ status: err.status, body: toErrorBody(err) });
+        }
+        const mapped = mapError?.(err);
+        if (mapped) {
+            return toResponse({ status: mapped.status, body: toErrorBody(mapped) });
+        }
+        // Never `console.error(…, err)`: provider adapters stash connection
+        // details on `cause`, and a raw console call hands the whole object to
+        // stdout where redaction never runs.
+        req.log.error(`[API] ${fallback}`, {
+            component: 'api',
+            err: err instanceof Error ? (err.stack ?? err.message) : String(err)
+        });
+        return toResponse({
+            status: 500,
+            body: { message: fallback, code: ApiErrorCode.INTERNAL }
+        });
+    }
+}
+//# sourceMappingURL=respond.js.map

package/dist/api/respond.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond.js","sourceRoot":"","sources":["../../src/api/respond.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAY,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASjE,MAAM,UAAU,WAAW,CAAC,GAAa;IACxC,OAAO,GAAG,CAAC,MAAM;QAChB,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;QAC9D,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED,SAAS,UAAU,CAAC,MAA8B;IACjD,IAAI,MAAM,YAAY,QAAQ;QAAE,OAAO,MAAM,CAAC;IAE9C,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAEtF,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;QACzC,MAAM,EAAE,MAAM,IAAI,GAAG;QACrB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE;KAC3D,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC/B,OAAmB,EACnB,GAAe,EACf,EAAE,QAAQ,EAAE,QAAQ,EAA2E;IAE/F,IAAI,CAAC;QACJ,OAAO,UAAU,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,MAAM,EAAE,CAAC;YACZ,OAAO,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,oEAAoE;QACpE,uEAAuE;QACvE,qCAAqC;QACrC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,QAAQ,EAAE,EAAE;YAClC,SAAS,EAAE,KAAK;YAChB,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACpE,CAAC,CAAC;QAEH,OAAO,UAAU,CAAC;YACjB,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE;SACxD,CAAC,CAAC;IACJ,CAAC;AACF,CAAC"}