@jskit-ai/crud-core 0.1.176 → 0.1.178

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.176",
+  "version": "0.1.178",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -23,11 +23,11 @@
     "./server/routeContracts": "./src/server/routeContracts.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.165",
-    "@jskit-ai/http-runtime": "0.1.163",
-    "@jskit-ai/json-rest-api-core": "0.1.109",
-    "@jskit-ai/kernel": "0.1.165",
-    "@jskit-ai/resource-crud-core": "0.1.107",
+    "@jskit-ai/database-runtime": "0.1.167",
+    "@jskit-ai/http-runtime": "0.1.165",
+    "@jskit-ai/json-rest-api-core": "0.1.111",
+    "@jskit-ai/kernel": "0.1.167",
+    "@jskit-ai/resource-crud-core": "0.1.109",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Shared server-side CRUD service, repository, route, and query helpers.",

package/patterns/json-api-resource-package/example/packages/books/package.json

@@ -8,8 +8,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.176",
-    "@jskit-ai/resource-crud-core": "0.1.107"
+    "@jskit-ai/crud-core": "0.1.178",
+    "@jskit-ai/resource-crud-core": "0.1.109"
   },
   "jskit": {
     "kind": "runtime",

package/src/server/jsonApiModule/actions.js

@@ -3,6 +3,11 @@ import {
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
 import { createEntityChangedActionEvent } from "@jskit-ai/kernel/server/actions";
+import {
+  normalizeJsonApiDocument,
+  simplifyJsonApiDocument,
+  unwrapJsonApiResult
+} from "@jskit-ai/http-runtime/shared";
 import { resolveCrudRecordChangedEvent } from "@jskit-ai/resource-crud-core/shared/crudNamespaceSupport";
 import {
   createStandardCrudListQueryValidators,
@@ -12,6 +17,104 @@ import {
 const CRUD_OPERATION_NAMES = Object.freeze(["list", "view", "create", "update", "delete"]);
 const CRUD_MUTATION_NAMES = new Set(["create", "update", "delete"]);
 const CRUD_LIFECYCLE_PHASES = Object.freeze(["before", "execute", "after", "afterCommit"]);
+const CRUD_ASSISTANT_RESOURCE_OPERATION = Object.freeze({
+  list: "list",
+  view: "view",
+  create: "create",
+  update: "patch",
+  delete: "delete"
+});
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeOptionalCursor(value) {
+  if (value == null) {
+    return null;
+  }
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+function resolveDocumentNextCursor(document = {}) {
+  return normalizeOptionalCursor(
+    document?.meta?.page?.nextCursor ?? document?.meta?.pagination?.cursor?.next
+  );
+}
+
+function resolveAssistantResultValue(result) {
+  const taggedResult = unwrapJsonApiResult(result);
+  const value = taggedResult ? taggedResult.value : result;
+  const document = normalizeJsonApiDocument(value);
+  return {
+    value,
+    document
+  };
+}
+
+function transformCrudAssistantResult(operation, result, { input = {} } = {}) {
+  if (operation === "delete") {
+    const resolved = resolveAssistantResultValue(result);
+    if (isRecord(resolved.value) && resolved.value.deleted === true && resolved.value.id != null) {
+      return resolved.value;
+    }
+    return {
+      id: String(input.recordId || ""),
+      deleted: true
+    };
+  }
+
+  const resolved = resolveAssistantResultValue(result);
+  if (operation === "list") {
+    if (resolved.document.kind === "collection") {
+      return {
+        items: simplifyJsonApiDocument(resolved.value),
+        nextCursor: resolveDocumentNextCursor(resolved.document)
+      };
+    }
+    if (Array.isArray(resolved.value)) {
+      return {
+        items: resolved.value,
+        nextCursor: null
+      };
+    }
+    if (isRecord(resolved.value) && Array.isArray(resolved.value.items)) {
+      return {
+        items: resolved.value.items,
+        nextCursor: normalizeOptionalCursor(resolved.value.nextCursor)
+      };
+    }
+    return resolved.value;
+  }
+
+  if (resolved.document.kind === "resource") {
+    return simplifyJsonApiDocument(resolved.value);
+  }
+  return resolved.value;
+}
+
+function createCrudAssistantExtension(resource, namespace, operation) {
+  const resourceOperation = CRUD_ASSISTANT_RESOURCE_OPERATION[operation];
+  const output = resource?.operations?.[resourceOperation]?.output || null;
+  const actionLabel = operation === "list"
+    ? `List ${namespace} records.`
+    : operation === "view"
+      ? `View a ${namespace} record.`
+      : operation === "create"
+        ? `Create a ${namespace} record.`
+        : operation === "update"
+          ? `Update a ${namespace} record.`
+          : `Delete a ${namespace} record.`;
+
+  return Object.freeze({
+    description: actionLabel,
+    output,
+    transformResult(result, context) {
+      return transformCrudAssistantResult(operation, result, context);
+    }
+  });
+}
 
 function createActionInput(
   resource,
@@ -303,6 +406,9 @@ function createCrudJsonApiActions({
       permission: permission(definition.operation),
       input: input(definition.operation),
       output: null,
+      extensions: Object.freeze({
+        assistant: createCrudAssistantExtension(resource, namespace, definition.operation)
+      }),
       idempotency: definition.idempotency,
       audit: { actionName: id },
       observability: {},

package/test/defineCrudJsonApiFeature.test.js

@@ -4,6 +4,8 @@ import { createSchema } from "json-rest-schema";
 
 import { createActionProvider } from "@jskit-ai/kernel/server/actions";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { returnJsonApiDocument } from "@jskit-ai/http-runtime/shared";
 import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
 import { defineCrudJsonApiFeature } from "../src/server/defineCrudJsonApiFeature.js";
 import { createCrudJsonApiActions } from "../src/server/jsonApiModule/actions.js";
@@ -187,6 +189,84 @@ test("defineCrudJsonApiFeature makes workspace scope and permissions explicit",
   await runtime.shutdown();
 });
 
+test("generated CRUD actions expose truthful assistant contracts without changing native results", async () => {
+  const resource = createBookResource();
+  const document = (id, title) => ({
+    data: {
+      type: "books",
+      id,
+      attributes: { title }
+    }
+  });
+  const actions = createCrudJsonApiActions({
+    namespace: "books",
+    resource,
+    service: {
+      async queryDocuments() {
+        return returnJsonApiDocument({
+          data: [document("1", "Kindred").data],
+          meta: { page: { nextCursor: "cursor-2" } }
+        });
+      },
+      async getDocumentById() {
+        return returnJsonApiDocument(document("1", "Kindred"));
+      },
+      async createDocument() {
+        return returnJsonApiDocument(document("2", "Parable of the Sower"));
+      },
+      async patchDocumentById() {
+        return returnJsonApiDocument(document("1", "Kindred (updated)"));
+      },
+      async deleteDocumentById() {
+        return null;
+      }
+    },
+    surface: "admin",
+    permissionForOperation: () => ({ require: "authenticated" })
+  });
+  const byOperation = new Map(actions.map((entry) => [entry.id.split(".").at(-1), entry]));
+
+  assert.ok(actions.every((entry) => entry.output === null));
+  assert.equal(byOperation.get("list").extensions.assistant.output, resource.operations.list.output);
+  assert.equal(byOperation.get("view").extensions.assistant.output, resource.operations.view.output);
+  assert.equal(byOperation.get("create").extensions.assistant.output, resource.operations.create.output);
+  assert.equal(byOperation.get("update").extensions.assistant.output, resource.operations.patch.output);
+  assert.equal(byOperation.get("delete").extensions.assistant.output, resource.operations.delete.output);
+
+  const transform = async (operation, input = {}) => {
+    const definition = byOperation.get(operation);
+    const nativeResult = await definition.execute(input, {});
+    const assistantResult = await definition.extensions.assistant.transformResult(nativeResult, { input });
+    return validateSchemaPayload(definition.extensions.assistant.output, assistantResult, {
+      phase: "output"
+    });
+  };
+
+  assert.deepEqual(await transform("list"), {
+    items: [{ id: "1", title: "Kindred" }],
+    nextCursor: "cursor-2"
+  });
+  assert.deepEqual(await transform("view", { recordId: "1" }), {
+    id: "1",
+    title: "Kindred"
+  });
+  assert.deepEqual(await transform("create", { title: "Parable of the Sower" }), {
+    id: "2",
+    title: "Parable of the Sower"
+  });
+  assert.deepEqual(await transform("update", { recordId: "1", title: "Kindred (updated)" }), {
+    id: "1",
+    title: "Kindred (updated)"
+  });
+  assert.deepEqual(await transform("delete", { recordId: "1" }), {
+    id: "1",
+    deleted: true
+  });
+
+  assert.deepEqual(await byOperation.get("view").execute({ recordId: "1" }, {}),
+    returnJsonApiDocument(document("1", "Kindred")));
+});
+
 test("defineCrudJsonApiFeature lets product services name exact capability dependencies", async () => {
   const routes = [];
   const access = {