@jskit-ai/http-runtime 0.1.4

package/src/shared/validators/typeboxFormats.js

@@ -0,0 +1,43 @@
+import { Format } from "typebox/format";
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const ISO_UTC_DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+function isStrictUuid(value) {
+  return typeof value === "string" && UUID_PATTERN.test(value);
+}
+
+function isStrictIsoUtcDateTime(value) {
+  if (typeof value !== "string" || !ISO_UTC_DATE_TIME_PATTERN.test(value)) {
+    return false;
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return false;
+  }
+
+  return parsed.toISOString() === value;
+}
+
+function registerTypeBoxFormats() {
+  return registerTypeBoxFormatsWith(Format);
+}
+
+function registerTypeBoxFormatsWith(formatRegistry) {
+  if (!formatRegistry.Has("uuid")) {
+    formatRegistry.Set("uuid", isStrictUuid);
+  }
+
+  if (!formatRegistry.Has("iso-utc-date-time")) {
+    formatRegistry.Set("iso-utc-date-time", isStrictIsoUtcDateTime);
+  }
+}
+
+const __testables = {
+  isStrictUuid,
+  isStrictIsoUtcDateTime,
+  registerTypeBoxFormatsWith
+};
+
+export { registerTypeBoxFormats, __testables };

package/test/client.test.js

@@ -0,0 +1,246 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createHttpClient } from "../src/shared/clientRuntime/client.js";
+
+function mockResponse({ status = 200, data = {}, contentType = "application/json; charset=utf-8", text = "" } = {}) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: {
+      get(name) {
+        return String(name || "").toLowerCase() === "content-type" ? contentType : "";
+      }
+    },
+    async json() {
+      return data;
+    },
+    async text() {
+      return text;
+    }
+  };
+}
+
+test("request serializes json body and injects csrf token for unsafe methods", async () => {
+  const calls = [];
+  const fetchImpl = async (url, options) => {
+    calls.push([url, options]);
+    if (url === "/api/session") {
+      return mockResponse({
+        data: {
+          csrfToken: "csrf-a"
+        }
+      });
+    }
+
+    return mockResponse({
+      data: {
+        ok: true
+      }
+    });
+  };
+
+  const client = createHttpClient({ fetchImpl });
+  const payload = await client.request("/api/custom", {
+    method: "POST",
+    body: {
+      demo: true
+    }
+  });
+
+  assert.deepEqual(payload, { ok: true });
+  assert.equal(calls.length, 2);
+  assert.equal(calls[0][0], "/api/session");
+  assert.equal(calls[1][1].headers["csrf-token"], "csrf-a");
+  assert.equal(calls[1][1].headers["Content-Type"], "application/json");
+  assert.equal(calls[1][1].body, JSON.stringify({ demo: true }));
+});
+
+test("request retries once on retryable csrf failure and preserves stateful headers", async () => {
+  const calls = [];
+  const fetchImpl = async (url, options) => {
+    calls.push([url, options]);
+    if (url === "/api/session") {
+      return mockResponse({
+        data: {
+          csrfToken: calls.length < 3 ? "csrf-1" : "csrf-2"
+        }
+      });
+    }
+
+    if (calls.length === 2) {
+      return mockResponse({
+        status: 403,
+        data: {
+          error: "forbidden",
+          details: {
+            code: "FST_CSRF_INVALID_TOKEN"
+          }
+        }
+      });
+    }
+
+    return mockResponse({
+      data: {
+        ok: true
+      }
+    });
+  };
+
+  const client = createHttpClient({
+    fetchImpl,
+    hooks: {
+      decorateHeaders({ headers, state }) {
+        state.commandId = state.commandId || "cmd_shared";
+        headers["x-command-id"] = state.commandId;
+      }
+    }
+  });
+
+  const state = {};
+  const payload = await client.request(
+    "/api/workspace/projects/1",
+    {
+      method: "PATCH",
+      body: {
+        name: "Updated"
+      }
+    },
+    state
+  );
+
+  assert.deepEqual(payload, { ok: true });
+  assert.equal(calls.length, 4);
+  assert.equal(calls[1][1].headers["x-command-id"], "cmd_shared");
+  assert.equal(calls[3][1].headers["x-command-id"], "cmd_shared");
+  assert.equal(calls[1][1].headers["csrf-token"], "csrf-1");
+  assert.equal(calls[3][1].headers["csrf-token"], "csrf-2");
+});
+
+test("requestStream parses ndjson and supports fallback hook", async () => {
+  const encoder = new TextEncoder();
+  const response = {
+    ok: true,
+    status: 200,
+    headers: {
+      get(name) {
+        return String(name || "").toLowerCase() === "content-type" ? "text/plain; charset=utf-8" : "";
+      }
+    },
+    body: new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode('{"type":"delta","value":"he"}\n'));
+        controller.enqueue(encoder.encode('{"type":"done"}\n'));
+        controller.close();
+      }
+    })
+  };
+  const fetchImpl = async () => response;
+  const seenEvents = [];
+
+  const client = createHttpClient({
+    fetchImpl,
+    hooks: {
+      shouldTreatAsNdjsonStream() {
+        return true;
+      }
+    }
+  });
+
+  await client.requestStream(
+    "/api/stream",
+    {
+      method: "POST",
+      headers: {
+        "csrf-token": "provided"
+      }
+    },
+    {
+      onEvent(event) {
+        seenEvents.push(event);
+      }
+    }
+  );
+
+  assert.deepEqual(seenEvents, [
+    { type: "delta", value: "he" },
+    { type: "done" }
+  ]);
+});
+
+test("requestStream retries once on retryable csrf failure and preserves stateful headers", async () => {
+  const calls = [];
+  const seenEvents = [];
+  const fetchImpl = async (url, options) => {
+    calls.push([url, options]);
+    if (url === "/api/session") {
+      return mockResponse({
+        data: {
+          csrfToken: calls.length < 3 ? "csrf-stream-1" : "csrf-stream-2"
+        }
+      });
+    }
+
+    if (calls.length === 2) {
+      return mockResponse({
+        status: 403,
+        data: {
+          error: "forbidden",
+          details: {
+            code: "FST_CSRF_INVALID_TOKEN"
+          }
+        }
+      });
+    }
+
+    return mockResponse({
+      contentType: "application/x-ndjson",
+      text: '{"type":"done"}\n'
+    });
+  };
+
+  const client = createHttpClient({
+    fetchImpl,
+    hooks: {
+      decorateHeaders({ headers, state }) {
+        state.commandId = state.commandId || "cmd_stream";
+        headers["x-command-id"] = state.commandId;
+      }
+    }
+  });
+
+  const state = {};
+  await client.requestStream(
+    "/api/workspace/stream",
+    {
+      method: "POST"
+    },
+    {
+      onEvent(event) {
+        seenEvents.push(event);
+      }
+    },
+    state
+  );
+
+  assert.equal(calls.length, 4);
+  assert.equal(calls[1][1].headers["x-command-id"], "cmd_stream");
+  assert.equal(calls[3][1].headers["x-command-id"], "cmd_stream");
+  assert.equal(calls[1][1].headers["csrf-token"], "csrf-stream-1");
+  assert.equal(calls[3][1].headers["csrf-token"], "csrf-stream-2");
+  assert.deepEqual(seenEvents, [{ type: "done" }]);
+});
+
+test("request maps network errors to normalized transport error", async () => {
+  const networkFailure = new Error("offline");
+  const fetchImpl = async () => {
+    throw networkFailure;
+  };
+
+  const client = createHttpClient({ fetchImpl });
+
+  await assert.rejects(
+    () => client.request("/api/session"),
+    (error) => error.status === 0 && error.message === "Network request failed." && error.cause === networkFailure
+  );
+});

package/test/command.test.js

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "@fastify/type-provider-typebox";
+import { createCommand } from "../src/shared/validators/command.js";
+
+test("createCommand requires input/output TypeBox schemas", () => {
+  assert.throws(() => createCommand({}), /input must be a TypeBox schema object/);
+
+  assert.throws(
+    () =>
+      createCommand({
+        input: Type.Object({}, { additionalProperties: false })
+      }),
+    /output must be a TypeBox schema object/
+  );
+});
+
+test("createCommand normalizes invalidates and preserves idempotent flag", () => {
+  const command = createCommand({
+    input: Type.Object(
+      {
+        token: Type.String({ minLength: 1 })
+      },
+      { additionalProperties: false }
+    ),
+    output: Type.Object(
+      {
+        ok: Type.Boolean()
+      },
+      { additionalProperties: false }
+    ),
+    idempotent: true,
+    invalidates: ["users-web", "users-web", "", "workspace.members"]
+  });
+
+  assert.equal(command.idempotent, true);
+  assert.deepEqual(command.invalidates, ["users-web", "workspace.members"]);
+  assert.equal(command.input.type, "object");
+  assert.equal(command.output.type, "object");
+});
+
+test("createCommand omits idempotent when not explicitly boolean", () => {
+  const command = createCommand({
+    input: Type.Object({}, { additionalProperties: false }),
+    output: Type.Object({}, { additionalProperties: false })
+  });
+
+  assert.equal(Object.hasOwn(command, "idempotent"), false);
+});

package/test/entrypoints.boundary.test.js

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+import * as clientApi from "../src/client/index.js";
+import * as sharedApi from "../src/shared/index.js";
+import { HttpValidatorsServiceProvider } from "../src/server/providers/HttpValidatorsServiceProvider.js";
+import { HttpClientRuntimeServiceProvider } from "../src/server/providers/HttpClientRuntimeServiceProvider.js";
+
+test("package exports include explicit shared entrypoint and no server barrel", async () => {
+  const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  const exportsMap = packageJson && typeof packageJson === "object" ? packageJson.exports : {};
+  assert.equal(exportsMap["./server"], undefined);
+  assert.equal(exportsMap["./shared"], "./src/shared/index.js");
+});
+
+test("client entrypoint exports client runtime and client providers only", () => {
+  assert.equal(typeof clientApi.createHttpClient, "function");
+  assert.equal(typeof clientApi.HttpValidatorsClientProvider, "function");
+  assert.equal(typeof clientApi.HttpClientRuntimeClientProvider, "function");
+  assert.equal(typeof clientApi.withStandardErrorResponses, "undefined");
+});
+
+test("server provider modules export server providers only", () => {
+  assert.equal(typeof HttpValidatorsServiceProvider, "function");
+  assert.equal(typeof HttpClientRuntimeServiceProvider, "function");
+});
+
+test("shared entrypoint exports shared validators only", () => {
+  assert.equal(typeof sharedApi.withStandardErrorResponses, "function");
+  assert.equal(typeof sharedApi.enumSchema, "function");
+  assert.equal(typeof sharedApi.createResource, "function");
+  assert.equal(typeof sharedApi.createCommand, "function");
+  assert.equal(typeof sharedApi.createHttpClient, "undefined");
+  assert.equal(typeof sharedApi.HttpValidatorsServiceProvider, "undefined");
+});

package/test/errorResponses.test.js

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  STANDARD_ERROR_STATUS_CODES,
+  apiErrorResponseSchema,
+  apiValidationErrorResponseSchema,
+  fastifyDefaultErrorResponseSchema,
+  enumSchema,
+  withStandardErrorResponses
+} from "../src/shared/validators/errorResponses.js";
+
+test("withStandardErrorResponses includes standard statuses", () => {
+  const success = {
+    200: {
+      schema: {
+        type: "string"
+      }
+    }
+  };
+
+  const responses = withStandardErrorResponses(success);
+
+  assert.equal(responses[200].schema.type, "string");
+  for (const statusCode of STANDARD_ERROR_STATUS_CODES) {
+    assert.ok(responses[statusCode], `missing status ${statusCode}`);
+  }
+  assert.equal(responses[400].schema.anyOf.length, 2);
+});
+
+test("withStandardErrorResponses uses validation union for 400 when enabled", () => {
+  const responses = withStandardErrorResponses(
+    {
+      201: {
+        schema: {
+          type: "null"
+        }
+      }
+    },
+    { includeValidation400: true }
+  );
+
+  assert.equal(responses[400].schema.anyOf.length, 3);
+  assert.deepEqual(
+    responses[400].schema.anyOf.map((schema) => schema.type),
+    [apiValidationErrorResponseSchema.type, apiErrorResponseSchema.type, fastifyDefaultErrorResponseSchema.type]
+  );
+});
+
+test("withStandardErrorResponses does not override existing error schemas", () => {
+  const custom400 = {
+    type: "object",
+    properties: {
+      error: {
+        type: "string"
+      }
+    }
+  };
+  const responses = withStandardErrorResponses(
+    {
+      200: {
+        schema: {
+          type: "string"
+        }
+      },
+      400: {
+        schema: custom400
+      }
+    },
+    { includeValidation400: true }
+  );
+
+  assert.equal(responses[400].schema, custom400);
+});
+
+test("enumSchema creates a literal union", () => {
+  const schema = enumSchema(["one", "two", "three"]);
+
+  assert.equal(schema.anyOf.length, 3);
+  assert.deepEqual(
+    schema.anyOf.map((entry) => entry.const),
+    ["one", "two", "three"]
+  );
+});

package/test/operationMessages.test.js

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "@fastify/type-provider-typebox";
+import { Errors } from "typebox/value";
+import {
+  mapOperationIssues,
+  resolveFieldSchema,
+  resolveIssueField,
+  resolveMissingRequiredFields,
+  resolveSchemaMessages
+} from "../src/shared/validators/operationMessages.js";
+
+const sampleSchema = Type.Object(
+  {
+    name: Type.String({
+      minLength: 1,
+      messages: {
+        required: "Workspace name is required.",
+        minLength: "Workspace name is required.",
+        default: "Invalid workspace name."
+      }
+    }),
+    color: Type.String({
+      pattern: "^#[0-9A-Fa-f]{6}$",
+      messages: {
+        pattern: "Workspace color must be a hex value."
+      }
+    }),
+    invitesEnabled: Type.Boolean({
+      messages: {
+        default: "invitesEnabled must be true or false."
+      }
+    })
+  },
+  {
+    additionalProperties: false,
+    messages: {
+      additionalProperties: "Unexpected field."
+    }
+  }
+);
+
+test("resolveIssueField resolves missing and nested fields", () => {
+  const missingIssues = [...Errors(sampleSchema, { color: "#0F6B54", invitesEnabled: true })];
+  const requiredIssue = missingIssues.find((entry) => entry.keyword === "required");
+
+  assert.equal(resolveIssueField(requiredIssue), "name");
+  assert.deepEqual(resolveMissingRequiredFields(requiredIssue), ["name"]);
+
+  const nestedSchema = Type.Object(
+    {
+      profile: Type.Object(
+        {
+          displayName: Type.String({ minLength: 1 })
+        },
+        { additionalProperties: false }
+      )
+    },
+    { additionalProperties: false }
+  );
+
+  const nestedIssues = [...Errors(nestedSchema, { profile: { displayName: "" } })];
+  const minLengthIssue = nestedIssues.find((entry) => entry.keyword === "minLength");
+  assert.equal(resolveIssueField(minLengthIssue), "profile");
+});
+
+test("mapOperationIssues applies field message overrides by keyword", () => {
+  const issues = [...Errors(sampleSchema, { name: "", color: "oops", invitesEnabled: "yes" })];
+  const mapped = mapOperationIssues(issues, sampleSchema);
+
+  assert.equal(mapped.fieldErrors.name, "Workspace name is required.");
+  assert.equal(mapped.fieldErrors.color, "Workspace color must be a hex value.");
+  assert.equal(mapped.fieldErrors.invitesEnabled, "invitesEnabled must be true or false.");
+  assert.deepEqual(mapped.globalErrors, []);
+});
+
+test("mapOperationIssues falls back to keyword/global messages", () => {
+  const issues = [...Errors(sampleSchema, { color: "#0F6B54", invitesEnabled: true, extra: "x" })];
+  const mapped = mapOperationIssues(issues, sampleSchema);
+
+  assert.equal(mapped.fieldErrors.extra, "Unexpected field.");
+});
+
+test("schema message helpers resolve field and root messages", () => {
+  const nameSchema = resolveFieldSchema(sampleSchema, "name");
+  assert.equal(typeof nameSchema, "object");
+
+  const nameMessages = resolveSchemaMessages(nameSchema);
+  const rootMessages = resolveSchemaMessages(sampleSchema);
+
+  assert.equal(nameMessages.minLength, "Workspace name is required.");
+  assert.equal(rootMessages.additionalProperties, "Unexpected field.");
+});

package/test/operationValidation.test.js

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "@fastify/type-provider-typebox";
+import {
+  validateOperationInput,
+  validateOperationSection
+} from "../src/shared/validators/operationValidation.js";
+
+const patchSchema = Type.Object(
+  {
+    name: Type.Optional(
+      Type.String({
+        minLength: 1,
+        maxLength: 160,
+        messages: {
+          minLength: "Workspace name is required."
+        }
+      })
+    ),
+    color: Type.Optional(
+      Type.String({
+        pattern: "^#[0-9A-Fa-f]{6}$",
+        messages: {
+          pattern: "Workspace color must be a hex value."
+        }
+      })
+    ),
+    invitesEnabled: Type.Optional(Type.Boolean())
+  },
+  {
+    additionalProperties: false,
+    minProperties: 1,
+    messages: {
+      additionalProperties: "Unexpected field."
+    }
+  }
+);
+
+const patchOperation = Object.freeze({
+  method: "PATCH",
+  bodyValidator: {
+    schema: patchSchema,
+    normalize: (value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+      }
+
+      const normalized = {
+        ...value
+      };
+
+      if (Object.hasOwn(normalized, "name")) {
+        normalized.name = String(normalized.name || "").trim();
+      }
+
+      return normalized;
+    }
+  }
+});
+
+test("validateOperationSection normalizes and validates one section", () => {
+  const parsed = validateOperationSection({
+    operation: patchOperation,
+    section: "bodyValidator",
+    value: {
+      name: "  Acme  ",
+      color: "#0F6B54"
+    }
+  });
+
+  assert.equal(parsed.ok, true);
+  assert.deepEqual(parsed.fieldErrors, {});
+  assert.equal(parsed.value.name, "Acme");
+});
+
+test("validateOperationSection returns shared field errors", () => {
+  const parsed = validateOperationSection({
+    operation: patchOperation,
+    section: "bodyValidator",
+    value: {
+      name: "",
+      color: "bad",
+      rogueField: true
+    }
+  });
+
+  assert.equal(parsed.ok, false);
+  assert.equal(parsed.fieldErrors.name, "Workspace name is required.");
+  assert.equal(parsed.fieldErrors.color, "Workspace color must be a hex value.");
+  assert.equal(parsed.fieldErrors.rogueField, "Unexpected field.");
+});
+
+test("validateOperationInput validates params/query/body together", () => {
+  const viewOperation = Object.freeze({
+    method: "GET",
+    paramsValidator: {
+      schema: Type.Object(
+        {
+          workspaceSlug: Type.String({ minLength: 1 })
+        },
+        { additionalProperties: false }
+      )
+    },
+    queryValidator: {
+      schema: Type.Object(
+        {
+          includeArchived: Type.Optional(Type.Boolean())
+        },
+        { additionalProperties: false }
+      ),
+      normalize: (value) => {
+        if (!value || typeof value !== "object") {
+          return {};
+        }
+
+        return {
+          includeArchived: value.includeArchived === true
+        };
+      }
+    }
+  });
+
+  const parsed = validateOperationInput({
+    operation: viewOperation,
+    input: {
+      params: {
+        workspaceSlug: "acme"
+      },
+      query: {}
+    }
+  });
+
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.value.params.workspaceSlug, "acme");
+  assert.equal(parsed.value.query.includeArchived, false);
+  assert.equal(parsed.value.body, undefined);
+});