@cosmicdrift/kumiko-dispatcher-live 0.362.0 → 0.363.0

package/dist/csrf.js

@@ -14,6 +14,7 @@
 // cannot READ `document.cookie` of our origin — so they can't populate the
 // header with the matching value.
 import { CSRF_COOKIE_BASE, sessionCookieNameCandidates, } from "@cosmicdrift/kumiko-types/session-cookies";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 // Kept here as a literal rather than imported from @cosmicdrift/kumiko-framework because this
 // package must remain server-dep-free (runs in browsers and React Native).
 // The framework's csrf-constants-sync test guards against drift.
@@ -54,6 +55,6 @@ function readDocumentCookie() {
     // Guard for non-browser environments. Avoid `typeof document` on the
     // left so a bundler that const-folds to "document is defined" still
     // compiles — the actual runtime check is what matters.
-    const g = globalThis;
-    return g.document?.cookie;
+    const cookie = propertyOf(propertyOf(globalThis, "document"), "cookie");
+    return typeof cookie === "string" ? cookie : undefined;
 }

package/dist/dispatcher-live.js

@@ -1,5 +1,7 @@
 import { createStore, } from "@cosmicdrift/kumiko-headless";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { CSRF_HEADER_NAME, readCsrfToken } from "./csrf.js";
+import { batchEnvelopeSchema, errorOnlyEnvelopeSchema, queryEnvelopeSchema, writeEnvelopeSchema, } from "./envelopes.js";
 import { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping.js";
 import { LOCALE_HEADER_NAME, readActiveLocale } from "./locale.js";
 import { iterateSseChunks } from "./sse-stream.js";
@@ -153,9 +155,9 @@ export function createLiveDispatcher(options = {}) {
                 catch (e) {
                     throw buildNetworkError(`invalid stream response (${response.status}): ${e instanceof Error ? e.message : String(e)}`);
                 }
-                const body = parsed;
-                if (body?.error) {
-                    throw mapServerErrorWithStatus(body.error, response.status);
+                const gateFailure = errorOnlyEnvelopeSchema.safeParse(parsed);
+                if (gateFailure.success) {
+                    throw mapServerErrorWithStatus(gateFailure.data.error, response.status);
                 }
                 throw buildNetworkError(`unexpected non-SSE stream response (${response.status})`);
             }
@@ -191,34 +193,67 @@ const EMPTY_PENDING_FILES = Object.freeze([]);
 // Uniqueness only needs to hold per user within the server's dedup window —
 // this is an idempotency key, not a security token.
 function generateRequestId() {
-    const c = globalThis.crypto;
-    if (typeof c?.randomUUID === "function")
-        return c.randomUUID();
+    const webCrypto = propertyOf(globalThis, "crypto");
+    const randomUUID = propertyOf(webCrypto, "randomUUID");
+    if (typeof randomUUID === "function") {
+        const id = Reflect.apply(randomUUID, webCrypto, []);
+        if (typeof id === "string")
+            return id;
+    }
     return `req-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
 }
+function buildUnexpectedShapeError(status) {
+    return buildNetworkError(`unexpected response shape (${status})`);
+}
+// Middleware gates (csrf, origin, auth, rate limits) answer write and batch
+// calls with a bare `{ error }`, without the isSuccess envelope.
+function gateOrShapeError(body, status) {
+    const gateFailure = errorOnlyEnvelopeSchema.safeParse(body);
+    return gateFailure.success
+        ? mapServerErrorWithStatus(gateFailure.data.error, status)
+        : buildUnexpectedShapeError(status);
+}
 // Write / Batch share the same envelope: `{ isSuccess: true, data }` on
 // success, `{ isSuccess: false, error: ServerErrorInfo, ... }` on failure.
 // Query uses a different envelope (see normalizeQueryResponse).
 function normalizeWriteResult(call) {
     if (!call.ok)
         return { isSuccess: false, error: call.networkFailure };
-    const body = call.body;
+    const envelope = writeEnvelopeSchema.safeParse(call.body);
+    if (!envelope.success) {
+        return { isSuccess: false, error: gateOrShapeError(call.body, call.status) };
+    }
+    const body = envelope.data;
     if (body.isSuccess)
-        return body;
+        return { isSuccess: true, data: body.data };
     return { isSuccess: false, error: mapServerErrorWithStatus(body.error, call.status) };
 }
 function normalizeBatchResponse(call) {
     if (!call.ok) {
         return { isSuccess: false, error: call.networkFailure, failedIndex: -1, results: [] };
     }
-    const body = call.body;
+    const envelope = batchEnvelopeSchema.safeParse(call.body);
+    if (!envelope.success) {
+        return {
+            isSuccess: false,
+            error: gateOrShapeError(call.body, call.status),
+            failedIndex: -1,
+            results: [],
+        };
+    }
+    const body = envelope.data;
+    const results = body.results.map((item) => {
+        if (item.isSuccess)
+            return { isSuccess: true, data: item.data };
+        return { isSuccess: false, error: mapServerErrorWithStatus(item.error, call.status) };
+    });
     if (body.isSuccess)
-        return body;
+        return { isSuccess: true, results };
     return {
         isSuccess: false,
         error: mapServerErrorWithStatus(body.error, call.status),
         failedIndex: body.failedIndex,
-        results: body.results,
+        results,
     };
 }
 // Query envelope: Kumiko's /api/query returns `{ data: ... }` on success
@@ -228,11 +263,15 @@ function normalizeBatchResponse(call) {
 function normalizeQueryResponse(call) {
     if (!call.ok)
         return { isSuccess: false, error: call.networkFailure };
-    const body = call.body;
-    if (body && "error" in body && body.error) {
+    const envelope = queryEnvelopeSchema.safeParse(call.body);
+    if (!envelope.success) {
+        return { isSuccess: false, error: buildUnexpectedShapeError(call.status) };
+    }
+    const body = envelope.data;
+    if (body.error) {
         return { isSuccess: false, error: mapServerErrorWithStatus(body.error, call.status) };
     }
-    return { isSuccess: true, data: body?.data };
+    return { isSuccess: true, data: body.data };
 }
 // The HTTP status carries the failure-status; the error body itself
 // doesn't repeat it (serializeError drops httpStatus to keep the wire
@@ -242,8 +281,5 @@ function mapServerErrorWithStatus(error, responseStatus) {
     return mapServerError({ ...error, httpStatus: error.httpStatus ?? responseStatus });
 }
 function isAbortError(e) {
-    return (!!e &&
-        typeof e === "object" &&
-        "name" in e && // @cast-boundary error-details
-        e.name === "AbortError");
+    return !!e && typeof e === "object" && "name" in e && e.name === "AbortError";
 }

package/dist/envelopes.d.ts

@@ -0,0 +1,101 @@
+import * as z from "zod";
+export declare const serverErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    httpStatus: z.ZodOptional<z.ZodNumber>;
+    i18nKey: z.ZodDefault<z.ZodString>;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodUnknown>;
+    i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    docsUrl: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ServerErrorLike = z.infer<typeof serverErrorSchema>;
+export declare const writeEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    isSuccess: z.ZodLiteral<true>;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    isSuccess: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "isSuccess">;
+export declare const batchEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    isSuccess: z.ZodLiteral<true>;
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        isSuccess: z.ZodLiteral<true>;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        isSuccess: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: z.ZodString;
+            httpStatus: z.ZodOptional<z.ZodNumber>;
+            i18nKey: z.ZodDefault<z.ZodString>;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+            i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            docsUrl: z.ZodOptional<z.ZodString>;
+            requestId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "isSuccess">>;
+}, z.core.$strip>, z.ZodObject<{
+    isSuccess: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    failedIndex: z.ZodNumber;
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        isSuccess: z.ZodLiteral<true>;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        isSuccess: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: z.ZodString;
+            httpStatus: z.ZodOptional<z.ZodNumber>;
+            i18nKey: z.ZodDefault<z.ZodString>;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+            i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            docsUrl: z.ZodOptional<z.ZodString>;
+            requestId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "isSuccess">>;
+}, z.core.$strip>], "isSuccess">;
+export declare const queryEnvelopeSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const errorOnlyEnvelopeSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/envelopes.js

@@ -0,0 +1,35 @@
+import * as z from "zod";
+// Wire envelopes of /api/{write,query,batch,stream}. Only the envelope is
+// validated; `data` payloads stay unknown and are typed by the caller.
+export const serverErrorSchema = z.object({
+    code: z.string(),
+    httpStatus: z.number().optional(),
+    // Some gates (bad-request helper in server.ts, pii-leak-guard) send no
+    // i18nKey; keeping their `code` beats collapsing them into network_error.
+    i18nKey: z.string().default("errors.unknown"),
+    message: z.string(),
+    details: z.unknown().optional(),
+    i18nParams: z.record(z.string(), z.unknown()).optional(),
+    docsUrl: z.string().optional(),
+    requestId: z.string().optional(),
+});
+const writeItemSchema = z.discriminatedUnion("isSuccess", [
+    z.object({ isSuccess: z.literal(true), data: z.unknown().optional() }),
+    z.object({ isSuccess: z.literal(false), error: serverErrorSchema }),
+]);
+export const writeEnvelopeSchema = writeItemSchema;
+export const batchEnvelopeSchema = z.discriminatedUnion("isSuccess", [
+    z.object({ isSuccess: z.literal(true), results: z.array(writeItemSchema) }),
+    z.object({
+        isSuccess: z.literal(false),
+        error: serverErrorSchema,
+        failedIndex: z.number(),
+        results: z.array(writeItemSchema),
+    }),
+]);
+// `error` is nullish: a null/absent error means success, as before.
+export const queryEnvelopeSchema = z.object({
+    data: z.unknown().optional(),
+    error: serverErrorSchema.nullish(),
+});
+export const errorOnlyEnvelopeSchema = z.object({ error: serverErrorSchema });

package/dist/error-mapping.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 // Narrow cast into the DispatcherError shape. Pass-through for everything
 // except `details.fields`, which we normalize: the server uses
 // ValidationFieldIssue (path/code/i18nKey/params), which is structurally
@@ -17,27 +18,25 @@ export function mapServerError(serverError) {
     };
 }
 function normalizeDetails(details) {
-    if (!details || typeof details !== "object")
+    if (!isPlainObject(details))
         return undefined;
-    const d = details; // @cast-boundary error-details — generic über alle DispatcherError-shapes
-    const fields = d["fields"];
+    const { fields, ...otherDetails } = details;
     if (!Array.isArray(fields)) {
         // Details without fields still pass through — non-validation errors
         // (rate-limit, version-conflict, ...) carry their own structured
         // payload here.
-        return d;
+        return otherDetails;
     }
     const mappedFields = [];
-    for (const f of fields) {
-        if (!f || typeof f !== "object") {
+    for (const r of fields) {
+        if (!isPlainObject(r)) {
             // Server sent a non-object entry in details.fields — contract
             // breach (ValidationFieldIssue shape is required). Warn so the
             // skip doesn't hide a broken server build.
             // biome-ignore lint/suspicious/noConsole: ops-visible warning when the server breaks the validation-error contract
-            console.warn("[dispatcher-live] dropping malformed field issue (not an object):", f);
+            console.warn("[dispatcher-live] dropping malformed field issue (not an object):", r);
             continue;
         }
-        const r = f; // @cast-boundary error-details
         if (typeof r["path"] !== "string" ||
             typeof r["code"] !== "string" ||
             typeof r["i18nKey"] !== "string") {
@@ -50,12 +49,10 @@ function normalizeDetails(details) {
             path: r["path"],
             code: r["code"],
             i18nKey: r["i18nKey"],
-            ...(r["params"] !== undefined && {
-                params: r["params"],
-            }),
+            ...(isPlainObject(r["params"]) && { params: r["params"] }),
         });
     }
-    return { ...d, fields: mappedFields };
+    return { ...otherDetails, fields: mappedFields };
 }
 // Builds a DispatcherError for a failure that never reached the server —
 // network dropped, DNS error, CORS block, fetch() threw. The UI should

package/dist/locale.js

@@ -5,6 +5,7 @@
 // LocaleResolver. This module reads that marker back so every outgoing
 // request carries the language the user is ACTUALLY using — not a static
 // <html lang> — with zero app-side wiring.
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 // Kept in sync with LOCALE_HEADER_NAME in api-constants.ts by hand rather
 // than imported from @cosmicdrift/kumiko-framework — this package must
 // remain server-dep-free (runs in browsers and React Native).
@@ -16,9 +17,9 @@ const LOCALE_TAG = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
 // the value is not a safe language tag — callers skip the header and the
 // server falls back to Accept-Language, then its boot default.
 export function readActiveLocale() {
-    const g = globalThis;
-    const lang = g.document?.documentElement?.dataset?.kumikoLocale;
-    if (lang === undefined || lang.length === 0)
+    const dataset = propertyOf(propertyOf(propertyOf(globalThis, "document"), "documentElement"), "dataset");
+    const lang = propertyOf(dataset, "kumikoLocale");
+    if (typeof lang !== "string" || lang.length === 0)
         return undefined;
     return LOCALE_TAG.test(lang) ? lang : undefined;
 }

package/dist/sse-stream.js

@@ -1,4 +1,5 @@
 import { StreamFrame } from "@cosmicdrift/kumiko-headless";
+import { serverErrorSchema } from "./envelopes.js";
 import { mapServerError } from "./error-mapping.js";
 export function parseSseBlock(block) {
     const trimmed = block.trim();
@@ -104,19 +105,24 @@ function frameDataToDispatcherError(data) {
         parsed = JSON.parse(data);
     }
     catch {
-        return {
-            code: "stream_error",
-            httpStatus: 200,
-            i18nKey: "errors.unknown",
-            message: data.length > 0 ? data : "stream error frame",
-        };
+        return unparsableErrorFrame(data);
     }
     // Server serializeError shape — mapServerError expects the same fields
     // as /api/query failures (httpStatus may be absent; reinject 200 for
     // mid-stream gates that flush SSE headers first).
-    const err = parsed;
+    const envelope = serverErrorSchema.safeParse(parsed);
+    if (!envelope.success)
+        return unparsableErrorFrame(data);
     return mapServerError({
-        ...err,
-        httpStatus: err.httpStatus ?? 200,
+        ...envelope.data,
+        httpStatus: envelope.data.httpStatus ?? 200,
     });
 }
+function unparsableErrorFrame(data) {
+    return {
+        code: "stream_error",
+        httpStatus: 200,
+        i18nKey: "errors.unknown",
+        message: data.length > 0 ? data : "stream error frame",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dispatcher-live",
-  "version": "0.362.0",
+  "version": "0.363.0",
   "description": "HTTP-only Dispatcher for Kumiko UIs. Always-online; failures surface immediately. Default client for web admin/cockpit apps.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -24,8 +24,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-headless": "0.362.0",
-    "@cosmicdrift/kumiko-types": "0.362.0"
+    "@cosmicdrift/kumiko-headless": "0.363.0",
+    "@cosmicdrift/kumiko-types": "0.363.0",
+    "zod": "^4.4.3"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "dispatcher-live validates server envelopes with Zod",
+    "detail": "Query, write, batch and stream responses are parsed against Zod schemas for the envelope (isSuccess, error, failedIndex, results); the data payload stays typed by the caller. A malformed envelope now yields the network_error fallback (\"unexpected response shape\") instead of passing wrongly typed fields through; bare gate errors ({ error } from csrf, origin, auth or rate limits) keep their code, and a missing i18nKey defaults to errors.unknown; a malformed SSE error frame yields stream_error, and failing batch items get httpStatus filled from the response like top-level errors. renderer-web types CSS custom properties on React's CSSProperties instead of casting style objects."
+  },
   {
     "version": "0.338.0",
     "type": "fix",