@jskit-ai/http-runtime 0.1.54 → 0.1.55

package/src/shared/validators/paginationQuery.js

@@ -1,4 +1,4 @@
-import { Type } from "@fastify/type-provider-typebox";
+import { createSchema } from "json-rest-schema";
 
 function createPaginationQuerySchema({
   defaultPage = 1,
@@ -7,26 +7,21 @@ function createPaginationQuerySchema({
   minPageSize = 1,
   maxPageSize = 100
 } = {}) {
-  return Type.Object(
-    {
-      page: Type.Optional(
-        Type.Integer({
-          minimum: minPage,
-          default: defaultPage
-        })
-      ),
-      pageSize: Type.Optional(
-        Type.Integer({
-          minimum: minPageSize,
-          maximum: maxPageSize,
-          default: defaultPageSize
-        })
-      )
+  return createSchema({
+    page: {
+      type: "integer",
+      required: false,
+      min: minPage,
+      default: defaultPage
     },
-    {
-      additionalProperties: false
+    pageSize: {
+      type: "integer",
+      required: false,
+      min: minPageSize,
+      max: maxPageSize,
+      default: defaultPageSize
     }
-  );
+  });
 }
 
 export { createPaginationQuerySchema };

package/src/shared/validators/resource.js

@@ -1,15 +1,9 @@
-import { Type } from "@fastify/type-provider-typebox";
-import { asSchema } from "./schemaUtils.js";
+import { asSchemaDefinition } from "./schemaUtils.js";
+import { createCursorListValidator } from "@jskit-ai/kernel/shared/validators";
+import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
 
 function createCursorPagedListResponseSchema(itemSchema) {
-  const normalizedItemSchema = asSchema(itemSchema, "itemSchema");
-  return Type.Object(
-    {
-      items: Type.Array(normalizedItemSchema),
-      nextCursor: Type.Union([Type.String({ minLength: 1 }), Type.Null()])
-    },
-    { additionalProperties: false }
-  );
+  return createCursorListValidator(itemSchema);
 }
 
 function createResource({
@@ -20,14 +14,18 @@ function createResource({
   list = null,
   listItem = null
 } = {}) {
-  const normalizedRecordSchema = asSchema(record, "record");
-  const normalizedCreateSchema = asSchema(create, "create");
-  const normalizedReplaceSchema = asSchema(replace, "replace");
-  const normalizedPatchSchema = asSchema(patch, "patch");
-  const normalizedListItemSchema = listItem ? asSchema(listItem, "listItem") : normalizedRecordSchema;
-  const normalizedListSchema = list ? asSchema(list, "list") : createCursorPagedListResponseSchema(normalizedListItemSchema);
+  const normalizedRecordSchema = asSchemaDefinition(record, "record", "replace");
+  const normalizedCreateSchema = asSchemaDefinition(create, "create", "create");
+  const normalizedReplaceSchema = asSchemaDefinition(replace, "replace", "replace");
+  const normalizedPatchSchema = asSchemaDefinition(patch, "patch", "patch");
+  const normalizedListItemSchema = listItem
+    ? asSchemaDefinition(listItem, "listItem", "replace")
+    : normalizedRecordSchema;
+  const normalizedListSchema = list
+    ? asSchemaDefinition(list, "list", "replace")
+    : createCursorPagedListResponseSchema(normalizedListItemSchema);
 
-  return Object.freeze({
+  return deepFreeze({
     record: normalizedRecordSchema,
     create: normalizedCreateSchema,
     replace: normalizedReplaceSchema,

package/src/shared/validators/schemaUtils.js

@@ -1,9 +1,22 @@
-function asSchema(value, label) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError(`${label} must be a TypeBox schema object.`);
+import { normalizeSingleSchemaDefinition } from "@jskit-ai/kernel/shared/validators";
+
+function asSchemaDefinition(value, label, defaultMode, { required = true } = {}) {
+  if (value == null) {
+    if (!required) {
+      return null;
+    }
+
+    throw new TypeError(`${label} is required.`);
   }
 
-  return value;
+  try {
+    return normalizeSingleSchemaDefinition(value, {
+      context: label,
+      defaultMode
+    });
+  } catch (error) {
+    throw new TypeError(error?.message || `${label} must be a schema definition object.`);
+  }
 }
 
-export { asSchema };
+export { asSchemaDefinition };

package/src/shared/validators/transportSchemaEmbedding.js

@@ -0,0 +1,81 @@
+function rewriteEmbeddedTransportSchemaRefs(value, {
+  rootRef = "#",
+  definitionRefByName = {}
+} = {}) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => rewriteEmbeddedTransportSchemaRefs(entry, {
+      rootRef,
+      definitionRefByName
+    }));
+  }
+
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const rewritten = {};
+
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "$ref" && typeof entry === "string") {
+      if (entry === "#") {
+        rewritten[key] = rootRef;
+        continue;
+      }
+
+      if (entry.startsWith("#/definitions/")) {
+        const definitionName = entry.slice("#/definitions/".length);
+        rewritten[key] = definitionRefByName[definitionName] || entry;
+        continue;
+      }
+    }
+
+    rewritten[key] = rewriteEmbeddedTransportSchemaRefs(entry, {
+      rootRef,
+      definitionRefByName
+    });
+  }
+
+  return rewritten;
+}
+
+function createEmbeddableTransportSchemaDocument(schemaDocument = {}, rootDefinitionName = "TransportSchema") {
+  const {
+    $schema: _jsonSchemaDraft,
+    definitions: sourceDefinitions = {},
+    ...rootSchema
+  } = schemaDocument || {};
+
+  const rootRef = `#/definitions/${rootDefinitionName}`;
+  const definitionRefByName = {};
+  const definitions = {};
+
+  for (const definitionName of Object.keys(sourceDefinitions)) {
+    definitionRefByName[definitionName] = `#/definitions/${rootDefinitionName}__${definitionName}`;
+  }
+
+  definitions[rootDefinitionName] = rewriteEmbeddedTransportSchemaRefs(rootSchema, {
+    rootRef,
+    definitionRefByName
+  });
+
+  for (const [definitionName, definitionSchema] of Object.entries(sourceDefinitions)) {
+    definitions[`${rootDefinitionName}__${definitionName}`] = rewriteEmbeddedTransportSchemaRefs(definitionSchema, {
+      rootRef,
+      definitionRefByName
+    });
+  }
+
+  return {
+    schema: {
+      allOf: [{
+        $ref: rootRef
+      }]
+    },
+    definitions
+  };
+}
+
+export {
+  rewriteEmbeddedTransportSchemaRefs,
+  createEmbeddableTransportSchemaDocument
+};

package/test/client.test.js

@@ -56,6 +56,285 @@ test("request serializes json body and injects csrf token for unsafe methods", a
   assert.equal(calls[1][1].body, JSON.stringify({ demo: true }));
 });
 
+test("request parses json:api responses as json payloads", async () => {
+  const fetchImpl = async () =>
+    mockResponse({
+      contentType: "application/vnd.api+json",
+      data: {
+        data: {
+          type: "contacts",
+          id: "2",
+          attributes: {
+            name: "ddd"
+          }
+        }
+      }
+    });
+
+  const client = createHttpClient({ fetchImpl });
+  const payload = await client.request("/api/contacts/2");
+
+  assert.deepEqual(payload, {
+    data: {
+      type: "contacts",
+      id: "2",
+      attributes: {
+        name: "ddd"
+      }
+    }
+  });
+});
+
+test("request encodes and decodes json:api resource transport for records", async () => {
+  const calls = [];
+  const fetchImpl = async (url, options) => {
+    calls.push([url, options]);
+    if (url === "/api/session") {
+      return mockResponse({
+        data: {
+          csrfToken: "csrf-jsonapi"
+        }
+      });
+    }
+
+    return mockResponse({
+      contentType: "application/vnd.api+json",
+      data: {
+        data: {
+          type: "contacts",
+          id: "2",
+          attributes: {
+            name: "ddd",
+            subscribed: false
+          }
+        }
+      }
+    });
+  };
+
+  const client = createHttpClient({ fetchImpl });
+  const payload = await client.request("/api/contacts/2", {
+    method: "PATCH",
+    body: {
+      name: "ddd",
+      subscribed: false
+    },
+    transport: {
+      kind: "jsonapi-resource",
+      requestType: "contact-updates",
+      responseType: "contacts",
+      responseKind: "record"
+    }
+  });
+
+  assert.deepEqual(payload, {
+    id: "2",
+    name: "ddd",
+    subscribed: false
+  });
+  assert.equal(calls[1][1].headers.Accept, "application/vnd.api+json");
+  assert.equal(calls[1][1].headers["Content-Type"], "application/vnd.api+json");
+  assert.equal(
+    calls[1][1].body,
+    JSON.stringify({
+      data: {
+        type: "contact-updates",
+        attributes: {
+          name: "ddd",
+          subscribed: false
+        }
+      }
+    })
+  );
+});
+
+test("request decodes json:api collection responses into JSKIT paged-list shape", async () => {
+  const fetchImpl = async () =>
+    mockResponse({
+      contentType: "application/vnd.api+json",
+      data: {
+        data: [
+          {
+            type: "contacts",
+            id: "2",
+            attributes: {
+              name: "ddd"
+            }
+          }
+        ],
+        meta: {
+          page: {
+            nextCursor: "cursor_2"
+          }
+        },
+        links: {
+          next: "/api/contacts?page[cursor]=cursor_2"
+        }
+      }
+    });
+
+  const client = createHttpClient({ fetchImpl });
+  const payload = await client.request("/api/contacts", {
+    method: "GET",
+    transport: {
+      kind: "jsonapi-resource",
+      responseType: "contacts",
+      responseKind: "collection"
+    }
+  });
+
+  assert.deepEqual(payload, {
+    items: [
+      {
+        id: "2",
+        name: "ddd"
+      }
+    ],
+    nextCursor: "cursor_2",
+    meta: {
+      page: {
+        nextCursor: "cursor_2"
+      }
+    },
+    links: {
+      next: "/api/contacts?page[cursor]=cursor_2"
+    }
+  });
+});
+
+test("request decodes native json-rest-api collection pagination metadata into JSKIT nextCursor", async () => {
+  const fetchImpl = async () =>
+    mockResponse({
+      contentType: "application/vnd.api+json",
+      data: {
+        data: [
+          {
+            type: "contacts",
+            id: "2",
+            attributes: {
+              name: "ddd"
+            }
+          }
+        ],
+        meta: {
+          pagination: {
+            cursor: {
+              next: "cursor_2"
+            }
+          }
+        },
+        links: {
+          next: "/api/contacts?page[after]=cursor_2&page[size]=20"
+        }
+      }
+    });
+
+  const client = createHttpClient({ fetchImpl });
+  const payload = await client.request("/api/contacts", {
+    method: "GET",
+    transport: {
+      kind: "jsonapi-resource",
+      responseType: "contacts",
+      responseKind: "collection"
+    }
+  });
+
+  assert.deepEqual(payload, {
+    items: [
+      {
+        id: "2",
+        name: "ddd"
+      }
+    ],
+    nextCursor: "cursor_2",
+    meta: {
+      pagination: {
+        cursor: {
+          next: "cursor_2"
+        }
+      }
+    },
+    links: {
+      next: "/api/contacts?page[after]=cursor_2&page[size]=20"
+    }
+  });
+});
+
+test("request encodes JSON:API query params for resource collections", async () => {
+  const calls = [];
+  const fetchImpl = async (url) => {
+    calls.push(url);
+    return mockResponse({
+      contentType: "application/vnd.api+json",
+      data: {
+        data: [],
+        meta: {
+          page: {
+            nextCursor: null
+          }
+        }
+      }
+    });
+  };
+
+  const client = createHttpClient({ fetchImpl });
+  await client.request("/api/contacts", {
+    method: "GET",
+    query: {
+      cursor: "cursor_2",
+      limit: 10,
+      q: "Merc",
+      include: "workspace,user",
+      workspaceId: "7"
+    },
+    transport: {
+      kind: "jsonapi-resource",
+      responseType: "contacts",
+      responseKind: "collection"
+    }
+  });
+
+  assert.equal(
+    calls[0],
+    "/api/contacts?page%5Bcursor%5D=cursor_2&page%5Blimit%5D=10&filter%5Bq%5D=Merc&include=workspace%2Cuser&filter%5BworkspaceId%5D=7"
+  );
+});
+
+test("request rejects json:api responses whose primary data type does not match the transport contract", async () => {
+  const fetchImpl = async () =>
+    mockResponse({
+      contentType: "application/vnd.api+json",
+      data: {
+        data: {
+          type: "user-settings",
+          id: "2",
+          attributes: {
+            name: "ddd"
+          }
+        }
+      }
+    });
+
+  const client = createHttpClient({ fetchImpl });
+
+  await assert.rejects(
+    () =>
+      client.request("/api/contacts/2", {
+        method: "GET",
+        transport: {
+          kind: "jsonapi-resource",
+          responseType: "contacts",
+          responseKind: "record"
+        }
+      }),
+    (error) => {
+      assert.equal(error?.message, "JSON:API response decoding failed.");
+      assert.equal(error?.cause?.message, "Expected JSON:API resource type contacts, received user-settings.");
+      return true;
+    }
+  );
+});
+
 test("request retries once on retryable csrf failure and preserves stateful headers", async () => {
   const calls = [];
   const fetchImpl = async (url, options) => {

package/test/command.test.js

@@ -1,48 +1,65 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { Type } from "@fastify/type-provider-typebox";
+import { createSchema } from "json-rest-schema";
 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/);
+test("createCommand requires input/output schema definitions", () => {
+  assert.throws(() => createCommand({}), /input is required/);
 
   assert.throws(
     () =>
       createCommand({
-        input: Type.Object({}, { additionalProperties: false })
+        input: {
+          schema: createSchema({})
+        }
       }),
-    /output must be a TypeBox schema object/
+    /output is required/
+  );
+
+  assert.throws(
+    () =>
+      createCommand({
+        input: createSchema({}),
+        output: {
+          schema: createSchema({})
+        }
+      }),
+    /input must be a schema definition 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 }
-    ),
+    input: {
+      schema: createSchema({
+        token: { type: "string", required: true, minLength: 1 }
+      })
+    },
+    output: {
+      schema: createSchema({
+        ok: { type: "boolean", required: true }
+      })
+    },
     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");
+  assert.equal(command.input.mode, "patch");
+  assert.equal(command.output.mode, "replace");
+  assert.equal(typeof command.input.schema.toJsonSchema, "function");
+  assert.equal(typeof command.output.schema.toJsonSchema, "function");
 });
 
 test("createCommand omits idempotent when not explicitly boolean", () => {
   const command = createCommand({
-    input: Type.Object({}, { additionalProperties: false }),
-    output: Type.Object({}, { additionalProperties: false })
+    input: {
+      schema: createSchema({})
+    },
+    output: {
+      schema: createSchema({})
+    }
   });
 
   assert.equal(Object.hasOwn(command, "idempotent"), false);

package/test/entrypoints.boundary.test.js

@@ -32,6 +32,14 @@ test("shared entrypoint exports shared validators only", () => {
   assert.equal(typeof sharedApi.enumSchema, "function");
   assert.equal(typeof sharedApi.createResource, "function");
   assert.equal(typeof sharedApi.createCommand, "function");
+  assert.equal(typeof sharedApi.createJsonApiDocument, "function");
+  assert.equal(typeof sharedApi.createJsonApiErrorDocumentFromFailure, "function");
+  assert.equal(typeof sharedApi.normalizeJsonApiDocument, "function");
+  assert.equal(typeof sharedApi.returnJsonApiDocument, "function");
+  assert.equal(typeof sharedApi.returnJsonApiData, "function");
+  assert.equal(typeof sharedApi.returnJsonApiMeta, "function");
+  assert.equal(typeof sharedApi.createJsonApiResourceRouteContract, "function");
+  assert.equal(typeof sharedApi.withJsonApiErrorResponses, "function");
   assert.equal(typeof sharedApi.createHttpClient, "undefined");
   assert.equal(typeof sharedApi.HttpValidatorsServiceProvider, "undefined");
 });

package/test/errorResponses.test.js

@@ -3,10 +3,13 @@ import test from "node:test";
 
 import {
   STANDARD_ERROR_STATUS_CODES,
-  apiErrorResponseSchema,
-  apiValidationErrorResponseSchema,
-  fastifyDefaultErrorResponseSchema,
+  apiErrorOutputValidator,
+  apiValidationErrorOutputValidator,
+  apiErrorTransportSchema,
+  apiValidationErrorTransportSchema,
+  fastifyDefaultErrorTransportSchema,
   enumSchema,
+  createTransportResponseSchema,
   withStandardErrorResponses
 } from "../src/shared/validators/errorResponses.js";
 
@@ -25,7 +28,17 @@ test("withStandardErrorResponses includes standard statuses", () => {
   for (const statusCode of STANDARD_ERROR_STATUS_CODES) {
     assert.ok(responses[statusCode], `missing status ${statusCode}`);
   }
-  assert.equal(responses[400].schema.anyOf.length, 2);
+  assert.equal(responses[400].transportSchema.anyOf.length, 2);
+  assert.deepEqual(responses[400].transportSchema.anyOf[0], {
+    allOf: [{
+      $ref: "#/definitions/ApiErrorOutput"
+    }]
+  });
+  assert.equal(responses[400].transportSchema.definitions.ApiErrorOutput.type, "object");
+  assert.equal(
+    responses[400].transportSchema.definitions.ApiErrorOutput.properties.details.allOf[0].$ref,
+    "#/definitions/ApiErrorOutput__SchemaNode_1_replace"
+  );
 });
 
 test("withStandardErrorResponses uses validation union for 400 when enabled", () => {
@@ -40,11 +53,20 @@ test("withStandardErrorResponses uses validation union for 400 when enabled", ()
     { 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]
-  );
+  assert.equal(responses[400].transportSchema.anyOf.length, 3);
+  assert.deepEqual(responses[400].transportSchema.anyOf[0], {
+    allOf: [{
+      $ref: "#/definitions/ApiValidationErrorOutput"
+    }]
+  });
+  assert.deepEqual(responses[400].transportSchema.anyOf[1], {
+    allOf: [{
+      $ref: "#/definitions/ApiErrorOutput"
+    }]
+  });
+  assert.equal(responses[400].transportSchema.anyOf[2].type, fastifyDefaultErrorTransportSchema.type);
+  assert.equal(responses[400].transportSchema.definitions.ApiValidationErrorOutput.type, "object");
+  assert.equal(responses[400].transportSchema.definitions.ApiErrorOutput.type, "object");
 });
 
 test("withStandardErrorResponses does not override existing error schemas", () => {
@@ -63,14 +85,12 @@ test("withStandardErrorResponses does not override existing error schemas", () =
           type: "string"
         }
       },
-      400: {
-        schema: custom400
-      }
+      400: createTransportResponseSchema(custom400)
     },
     { includeValidation400: true }
   );
 
-  assert.equal(responses[400].schema, custom400);
+  assert.equal(responses[400].transportSchema, custom400);
 });
 
 test("enumSchema creates a literal union", () => {
@@ -82,3 +102,19 @@ test("enumSchema creates a literal union", () => {
     ["one", "two", "three"]
   );
 });
+
+test("error response validators export transport schemas from the same contracts", () => {
+  assert.equal(apiErrorOutputValidator.mode, "replace");
+  assert.equal(apiValidationErrorOutputValidator.mode, "replace");
+  assert.equal(apiErrorTransportSchema.type, "object");
+  assert.equal(apiValidationErrorTransportSchema.type, "object");
+  assert.equal(apiErrorTransportSchema.properties.details.allOf[0].$ref, "#/definitions/SchemaNode_1_replace");
+  assert.equal(
+    apiValidationErrorTransportSchema.properties.details.allOf[0].$ref,
+    "#/definitions/SchemaNode_1_replace"
+  );
+  assert.equal(
+    apiValidationErrorTransportSchema.definitions.SchemaNode_1_replace.required.includes("fieldErrors"),
+    true
+  );
+});