@yunsoft/yuncms-api 0.1.8 → 0.1.10

package/src/ai/tools.js

@@ -0,0 +1,304 @@
+import {
+  readManyWithRelations,
+  readOneWithRelations,
+} from '@yunsoft/yuncms-core';
+import * as z from 'zod/v4';
+
+import {
+  describeReadableCollection,
+  listReadableCollections,
+} from '../mcp.js';
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+const SAFE_TOOL_ERROR_CODES = new Set([
+  'FORBIDDEN',
+  'FORBIDDEN_FIELD',
+  'COLLECTION_NOT_FOUND',
+  'INVALID_QUERY',
+  'QUERY_COST_LIMIT',
+  'QUERY_RELATION_DEPTH_LIMIT',
+  'QUERY_RELATION_ROW_LIMIT',
+  'INVALID_PAYLOAD',
+  'REQUIRED_FIELD_MISSING',
+  'FIELD_READ_ONLY',
+  'FILTER_REQUIRED',
+  'VALIDATION_FAILED',
+  'VALIDATION_BULK_LIMIT',
+  'FOREIGN_KEY_MISSING',
+  'FOREIGN_KEY_RESTRICTED',
+  'DUPLICATE_KEY',
+]);
+
+const collectionSchema = z.string()
+  .min(1)
+  .max(64)
+  .regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+const idSchema = z.union([z.string().min(1).max(191), z.number().finite()]);
+const delimitedSchema = z.union([
+  z.string().min(1).max(2_000),
+  z.array(z.string().min(1).max(191)).max(100),
+]);
+const filterSchema = z.record(z.string(), z.unknown());
+const aggregateSchema = z.record(
+  z.string(),
+  z.union([z.string().min(1), z.array(z.string().min(1)).max(20)]),
+);
+
+function toolError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function parseArguments(schema, args) {
+  const result = schema.safeParse(args ?? {});
+  if (result.success) return result.data;
+  throw toolError('AI_TOOL_ARGUMENTS_INVALID', 'The assistant generated invalid tool arguments');
+}
+
+function itemService(req, collection) {
+  const Service = req.context.services.ItemsService;
+  return new Service(collection, serviceOptionsFromRequest(req));
+}
+
+function readManySchema(maxItems) {
+  return z.object({
+    collection: collectionSchema,
+    fields: delimitedSchema.optional(),
+    expand: delimitedSchema.optional(),
+    filter: filterSchema.optional(),
+    search: z.string().max(200).optional(),
+    sort: delimitedSchema.optional(),
+    aggregate: aggregateSchema.optional(),
+    groupBy: delimitedSchema.optional(),
+    limit: z.number().int().min(1).max(maxItems).optional(),
+    offset: z.number().int().min(0).max(1_000_000).optional(),
+  }).strict();
+}
+
+const describeSchema = z.object({ collection: collectionSchema }).strict();
+const readOneSchema = z.object({
+  collection: collectionSchema,
+  id: idSchema,
+  fields: delimitedSchema.optional(),
+  expand: delimitedSchema.optional(),
+}).strict();
+const createSchema = z.object({
+  collection: collectionSchema,
+  data: z.record(z.string(), z.unknown()),
+}).strict();
+const updateSchema = z.object({
+  collection: collectionSchema,
+  id: idSchema,
+  data: z.record(z.string(), z.unknown()),
+}).strict();
+const deleteSchema = z.object({
+  collection: collectionSchema,
+  id: idSchema,
+}).strict();
+
+function toolDefinition(name, description, parameters) {
+  return {
+    type: 'function',
+    function: {
+      name,
+      description,
+      parameters: {
+        additionalProperties: false,
+        ...parameters,
+      },
+    },
+  };
+}
+
+function readToolDefinitions(maxItems) {
+  return [
+    toolDefinition(
+      'schema_list_collections',
+      'List project collections the current YunCMS user is allowed to read. Use this before guessing collection names.',
+      { type: 'object', properties: {}, required: [] },
+    ),
+    toolDefinition(
+      'schema_describe_collection',
+      'Describe readable fields, direct relations and CRUD capabilities for one collection using the current user permissions.',
+      {
+        type: 'object',
+        properties: { collection: { type: 'string' } },
+        required: ['collection'],
+      },
+    ),
+    toolDefinition(
+      'items_read_many',
+      'Read collection rows with YunCMS filtering, search, sorting, aggregates and relation-aware fields. Normal RBAC and query limits always apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          fields: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          expand: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          filter: { type: 'object' },
+          search: { type: 'string', maxLength: 200 },
+          sort: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          aggregate: { type: 'object' },
+          groupBy: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          limit: { type: 'integer', minimum: 1, maximum: maxItems },
+          offset: { type: 'integer', minimum: 0, maximum: 1_000_000 },
+        },
+        required: ['collection'],
+      },
+    ),
+    toolDefinition(
+      'items_read_one',
+      'Read one item by id with optional field and relation selection. Normal YunCMS read permissions apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          id: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+          fields: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          expand: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+        },
+        required: ['collection', 'id'],
+      },
+    ),
+  ];
+}
+
+function writeToolDefinitions({ deletesEnabled = false } = {}) {
+  const tools = [
+    toolDefinition(
+      'items_create',
+      'Create one YunCMS item. Use only when the user clearly asks to create data. Field permissions, validation, hooks and auditing apply.',
+      {
+        type: 'object',
+        properties: { collection: { type: 'string' }, data: { type: 'object' } },
+        required: ['collection', 'data'],
+      },
+    ),
+    toolDefinition(
+      'items_update',
+      'Update one YunCMS item by id. Use only when the user clearly asks to change data. Normal permissions and validation apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          id: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+          data: { type: 'object' },
+        },
+        required: ['collection', 'id', 'data'],
+      },
+    ),
+  ];
+  if (deletesEnabled) tools.push(toolDefinition(
+      'items_delete',
+      'Delete one YunCMS item by id. Use only when the user explicitly asks to delete that item. Normal delete permissions and hooks apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          id: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+        },
+        required: ['collection', 'id'],
+      },
+    ));
+  return tools;
+}
+
+export function aiToolDefinitions({
+  writesEnabled = false,
+  deletesEnabled = false,
+  maxItems = 100,
+} = {}) {
+  return writesEnabled
+    ? [...readToolDefinitions(maxItems), ...writeToolDefinitions({ deletesEnabled })]
+    : readToolDefinitions(maxItems);
+}
+
+export async function executeAiTool(req, name, args, {
+  writesEnabled = false,
+  deletesEnabled = false,
+  maxItems = 100,
+} = {}) {
+  if (name === 'schema_list_collections') {
+    parseArguments(z.object({}).strict(), args);
+    return { collections: await listReadableCollections(req, { maxItems }) };
+  }
+  if (name === 'schema_describe_collection') {
+    const input = parseArguments(describeSchema, args);
+    return describeReadableCollection(req, input.collection);
+  }
+  if (name === 'items_read_many') {
+    const { collection, ...query } = parseArguments(readManySchema(maxItems), args);
+    return readManyWithRelations({
+      collection,
+      query: { ...query, limit: query.limit ?? Math.min(100, maxItems) },
+      options: serviceOptionsFromRequest(req),
+      ItemsServiceClass: req.context.services.ItemsService,
+    });
+  }
+  if (name === 'items_read_one') {
+    const input = parseArguments(readOneSchema, args);
+    return readOneWithRelations({
+      collection: input.collection,
+      id: input.id,
+      query: {
+        ...(input.fields ? { fields: input.fields } : {}),
+        ...(input.expand ? { expand: input.expand } : {}),
+      },
+      options: serviceOptionsFromRequest(req),
+      ItemsServiceClass: req.context.services.ItemsService,
+    });
+  }
+
+  if (!writesEnabled) throw toolError('AI_TOOL_FORBIDDEN', 'Data-changing assistant tools are disabled');
+
+  if (name === 'items_create') {
+    const input = parseArguments(createSchema, args);
+    return itemService(req, input.collection).createOne(input.data);
+  }
+  if (name === 'items_update') {
+    const input = parseArguments(updateSchema, args);
+    return itemService(req, input.collection).updateOne(input.id, input.data);
+  }
+  if (name === 'items_delete') {
+    if (!deletesEnabled) throw toolError('AI_TOOL_FORBIDDEN', 'Assistant delete tools are disabled');
+    const input = parseArguments(deleteSchema, args);
+    return { deleted: await itemService(req, input.collection).deleteOne(input.id) };
+  }
+
+  throw toolError('AI_TOOL_UNKNOWN', 'The assistant requested an unknown tool');
+}
+
+export function safeAiToolError(error) {
+  const code = SAFE_TOOL_ERROR_CODES.has(error?.code)
+    || ['AI_TOOL_ARGUMENTS_INVALID', 'AI_TOOL_FORBIDDEN', 'AI_TOOL_UNKNOWN'].includes(error?.code)
+    ? error.code
+    : 'INTERNAL_ERROR';
+  return {
+    error: {
+      code,
+      message: code === 'INTERNAL_ERROR'
+        ? 'Tool execution failed'
+        : String(error?.message ?? 'Tool execution failed'),
+    },
+  };
+}
+
+export function serializeAiToolResult(value, maxBytes = 250_000) {
+  const text = JSON.stringify({ data: value });
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return text;
+  return JSON.stringify({
+    error: {
+      code: 'AI_TOOL_RESULT_TOO_LARGE',
+      message: `Tool result exceeds the configured ${maxBytes} byte limit. Narrow the query and try again.`,
+    },
+  });
+}
+
+export function operationSummary(name, args = {}, success = true) {
+  return {
+    operation: name,
+    collection: typeof args.collection === 'string' ? args.collection : null,
+    success,
+  };
+}

package/src/app.js

@@ -16,6 +16,7 @@ import { createItemsRouter } from './routes/items.js';
 import { createPermissionsRouter } from './routes/permissions.js';
 import { createRolesRouter } from './routes/roles.js';
 import { createSchemaRouter } from './routes/schema.js';
+import { createStudioNavigationRouter } from './routes/studio-navigation.js';
 import { createStudioSettingsRouter } from './routes/studio-settings.js';
 import { createSystemSchemaRouter } from './routes/system-schema.js';
 import { createUsersRouter } from './routes/users.js';
@@ -127,6 +128,7 @@ export function createApp({
   redisClient = null,
   externalAuthRegistry = null,
   endpointExtensions = [],
+  aiRouter = null,
   mcpRouter = null,
   studioRoot = undefined,
 }) {
@@ -187,7 +189,9 @@ export function createApp({
   const requestEvents = createRequestEvents(emitter);
   if (requestEvents) app.use(requestEvents);
 
+  if (aiRouter) app.use('/ai', aiRouter);
   if (mcpRouter) app.use('/mcp', mcpRouter);
+  app.use('/studio-navigation', createStudioNavigationRouter());
   app.use('/studio-settings', createStudioSettingsRouter());
   app.use('/auth', createAuthRouter({ mailer, config, logger, rateLimitStore, externalAuthRegistry }));
   app.use('/items', createItemsRouter());

package/src/error-response.js

@@ -15,6 +15,7 @@ const STATUS_BY_CODE = new Map([
   ['ROLE_NOT_FOUND', 404],
   ['PERMISSION_NOT_FOUND', 404],
   ['FILE_NOT_FOUND', 404],
+  ['NAVIGATION_GROUP_NOT_FOUND', 404],
   ['NOT_FOUND', 404],
   ['COLLECTION_EXISTS', 409],
   ['FIELD_EXISTS', 409],
@@ -28,6 +29,9 @@ const STATUS_BY_CODE = new Map([
   ['DUPLICATE_KEY', 409],
   ['FOREIGN_KEY_MISSING', 409],
   ['FOREIGN_KEY_RESTRICTED', 409],
+  ['SINGLETON_ITEM_EXISTS', 409],
+  ['SINGLETON_MULTIPLE_ITEMS', 409],
+  ['SINGLETON_BULK_CREATE_FORBIDDEN', 409],
   ['RATE_LIMITED', 429],
   ['PAYLOAD_TOO_LARGE', 413],
   ['INVALID_QUERY', 400],
@@ -43,6 +47,9 @@ const STATUS_BY_CODE = new Map([
   ['INVALID_FILE_CONTENT', 400],
   ['FILE_MIME_MISMATCH', 400],
   ['INVALID_MAIL_MESSAGE', 400],
+  ['INVALID_AI_REQUEST', 400],
+  ['INVALID_AI_CONFIG', 400],
+  ['AI_TOOL_ARGUMENTS_INVALID', 400],
   ['STORAGE_NOT_FOUND', 400],
   ['STORAGE_INVENTORY_UNSUPPORTED', 400],
   ['UNSUPPORTED_SCHEMA_UPDATE', 400],
@@ -58,6 +65,14 @@ const STATUS_BY_CODE = new Map([
   ['FILTER_REQUIRED', 400],
   ['VALIDATION_FAILED', 400],
   ['VALIDATION_BULK_LIMIT', 400],
+  ['AI_PROVIDER_UNAVAILABLE', 502],
+  ['AI_PROVIDER_RESPONSE_INVALID', 502],
+  ['AI_TOOL_ROUND_LIMIT', 502],
+  ['AI_TOOL_CALL_LIMIT', 502],
+  ['AI_PROVIDER_TIMEOUT', 504],
+  ['AI_NOT_CONFIGURED', 503],
+  ['AI_SETTINGS_KEY_INVALID', 503],
+  ['AI_SECRET_DECRYPT_FAILED', 503],
   ['MAIL_NOT_CONFIGURED', 503],
   ['STORAGE_INVENTORY_FAILED', 503],
   ['DATABASE_MIGRATION_REQUIRED', 503],

package/src/routes/ai.js

@@ -0,0 +1,80 @@
+import express from 'express';
+
+function authError() {
+  const error = new Error('Yapay Zeka requires an authenticated YunCMS account');
+  error.code = 'UNAUTHORIZED';
+  return error;
+}
+
+function requireAuthenticated(req) {
+  if (req?.authMethod === 'public' || !req?.accountability?.user) throw authError();
+}
+
+function requireAdministrator(req) {
+  requireAuthenticated(req);
+  if (req.accountability?.admin === true || req.accountability?.system === true) return;
+  const error = new Error('Yapay Zeka settings require administrator access');
+  error.code = 'FORBIDDEN';
+  throw error;
+}
+
+export function aiRequestAccess(body = {}) {
+  const allowWrites = body?.allow_writes === true;
+  return {
+    allowWrites,
+    allowDeletes: allowWrites && body?.allow_deletes === true,
+  };
+}
+
+export function createAiRouter({ assistant, settingsStore } = {}) {
+  if (!assistant) throw new Error('AI assistant service is required');
+  if (!settingsStore) throw new Error('AI settings store is required');
+  const router = express.Router();
+
+  router.get('/status', async (req, res, next) => {
+    try {
+      requireAuthenticated(req);
+      return res.json({ data: await assistant.status(), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.get('/settings', async (req, res, next) => {
+    try {
+      requireAdministrator(req);
+      return res.json({ data: await settingsStore.readAdmin(), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.patch('/settings', async (req, res, next) => {
+    try {
+      requireAdministrator(req);
+      const data = await settingsStore.update(req.body ?? {});
+      return res.json({ data, request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.post('/chat', async (req, res, next) => {
+    try {
+      requireAuthenticated(req);
+      const access = aiRequestAccess(req.body);
+      const result = await assistant.chat(req, {
+        messages: req.body?.messages,
+        locale: req.body?.locale,
+        ...access,
+      });
+      return res.json({ data: result, request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  return router;
+}
+
+export { requireAdministrator, requireAuthenticated };

package/src/routes/studio-navigation.js

@@ -0,0 +1,59 @@
+import express from 'express';
+
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+function navigationService(req) {
+  const Service = req.context.services.NavigationGroupsService;
+  return new Service(serviceOptionsFromRequest(req));
+}
+
+function requireStudioUser(req) {
+  if (req?.authMethod !== 'public' && req?.accountability?.user) return;
+  const error = new Error('Studio navigation requires an authenticated YunCMS account');
+  error.code = 'UNAUTHORIZED';
+  throw error;
+}
+
+export function createStudioNavigationRouter() {
+  const router = express.Router();
+
+  router.get('/groups', async (req, res, next) => {
+    try {
+      requireStudioUser(req);
+      return res.json({ data: await navigationService(req).readMany(), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.post('/groups', async (req, res, next) => {
+    try {
+      requireStudioUser(req);
+      return res.status(201).json({ data: await navigationService(req).createOne(req.body ?? {}), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.patch('/groups/:id', async (req, res, next) => {
+    try {
+      requireStudioUser(req);
+      return res.json({ data: await navigationService(req).updateOne(req.params.id, req.body ?? {}), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.delete('/groups/:id', async (req, res, next) => {
+    try {
+      requireStudioUser(req);
+      return res.json({ data: await navigationService(req).deleteOne(req.params.id), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  return router;
+}
+
+export { requireStudioUser };

package/src/server.js

@@ -20,11 +20,15 @@ import {
   SmtpMailer,
 } from '@yunsoft/yuncms-core';
 import { createApp } from './app.js';
+import { AiAssistantService } from './ai/service.js';
+import { loadOrCreateAiSettingsKey } from './ai/secret-key.js';
+import { AiSettingsStore } from './ai/settings-store.js';
 import { INTERNAL_AUDIT_EVENTS } from './audit-events.js';
 import { loadExternalAuthConfig } from './external-auth/config.js';
 import { ExternalAuthProviderRegistry } from './external-auth/providers.js';
 import { loadExtensionRuntime } from './extensions/runtime.js';
 import { createMcpRouter } from './mcp.js';
+import { createAiRouter } from './routes/ai.js';
 
 loadEnvFileIfPresent();
 await assertMaintenanceStartupAllowed({ cwd: process.cwd(), env: process.env });
@@ -103,6 +107,10 @@ function registerInternalAudit({ emitter, services }) {
 
 async function start() {
   await assertDatabaseCompatible(pool);
+  const aiKey = await loadOrCreateAiSettingsKey();
+  const aiSettingsStore = new AiSettingsStore({ database: pool, key: aiKey.key });
+  if (aiKey.created) logger.info('YunCMS AI settings encryption key created');
+
   if (redisClient) {
     try {
       await redisClient.connect();
@@ -124,6 +132,8 @@ async function start() {
     database: pool,
     logger,
   });
+  const aiAssistant = new AiAssistantService({ settingsStore: aiSettingsStore, logger });
+  const aiRouter = createAiRouter({ assistant: aiAssistant, settingsStore: aiSettingsStore });
   const mcpRouter = createMcpRouter({ config, logger });
   mailer?.setEmitter(emitter);
   registerInternalAudit({ emitter, services });
@@ -152,6 +162,7 @@ async function start() {
     redisClient,
     externalAuthRegistry,
     endpointExtensions: extensionRuntime.endpointExtensions,
+    aiRouter,
     mcpRouter,
   });
 
@@ -208,4 +219,4 @@ start().catch(async (error) => {
   await redisClient?.close().catch(() => {});
   await closeDatabasePool(pool).catch(() => {});
   process.exit(1);
-});
+});