@infuro/cms-core 1.0.19 → 1.0.21

package/dist/{index-D2C1O9b4.d.cts → index-BGAh4fPQ.d.cts}

@@ -153,6 +153,47 @@ declare function createUserAuthApiRouter(config: UserAuthApiConfig): {
  */
 
 type RequireEntityPermissionFn = (req: Request, entity: string, action: EntityCrudAction) => Promise<Response | null>;
+/**
+ * Optional JSON in `LlmAgent.validationRules`. Used for programmatic checks before the LLM call.
+ * For natural-language output rules, use `guardrails` / `outputRules` / `outputInstructions` (merged into system prompt).
+ */
+type LlmAgentValidationRulesJson = {
+    maxUserChars?: number;
+    maxMessageLength?: number;
+    minUserChars?: number;
+    minMessageLength?: number;
+    blockedSubstrings?: string[];
+    /** Shown to the model as output guardrails (first non-empty of guardrails | outputRules | outputInstructions wins). */
+    guardrails?: string;
+    outputRules?: string;
+    outputInstructions?: string;
+};
+type ParsedLlmAgentValidation = {
+    /** Subset used for length / substring checks only. */
+    structured: Pick<LlmAgentValidationRulesJson, 'maxUserChars' | 'maxMessageLength' | 'minUserChars' | 'minMessageLength' | 'blockedSubstrings'>;
+    /** Appended to system prompt so the model follows output guardrails. */
+    guardrailsForPrompt: string | null;
+};
+/**
+ * - Valid JSON object: structural keys → validation; `guardrails` / `outputRules` / `outputInstructions` → prompt suffix.
+ * - Not JSON: entire string is treated as prose guardrails for the prompt (no programmatic rules unless you use JSON).
+ */
+declare function parseLlmAgentValidationRules(validationRulesText: string | null | undefined): ParsedLlmAgentValidation;
+declare function validateUserMessageAgainstStructuredRules(message: string, structured: ParsedLlmAgentValidation['structured']): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Parses `validationRules` then runs programmatic checks only. */
+declare function validateUserMessageAgainstAgentRules(message: string, validationRulesText: string | null | undefined): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Merges guardrails prose into the system instruction sent to the model. */
+declare function mergeGuardrailsIntoSystemPrompt(baseSystem: string | undefined, guardrailsForPrompt: string | null): string;
 interface CmsHandlersBase {
     json: (body: unknown, init?: {
         status?: number;
@@ -311,6 +352,59 @@ interface ChatApiConfig extends CmsHandlersBase {
         getPlugin: (name: string) => unknown;
     }>;
 }
+/** Safe subset of `llm` settings for the storefront chat widget (`GET /api/chat/config`). */
+interface ChatPublicConfig {
+    enabled: boolean;
+    chatMode: 'whatsapp' | 'external' | 'llm';
+    /** When `chatMode === 'llm'`, slug of the attached agent (from `attachedAgentSlug` setting). */
+    agentSlug: string;
+    botName: string;
+    icon: string;
+    iconImageUrl: string;
+    iconBackgroundColor: string;
+    headerColor: string;
+    whatsappPhone: string;
+}
+
+/**
+ * Admin API: attach knowledge base documents to an LLM agent, ingest text into chunks + embeddings.
+ * Routes: GET/POST /api/llm_agents/:slug/knowledge, DELETE /api/llm_agents/:slug/knowledge/:documentId
+ *
+ * Pipeline logs (grep `[llm-agent-knowledge] pipeline`):
+ * - 01_request — incoming POST, content-type preview
+ * - 02_agent_loaded — agent id for slug
+ * - 03_body_parsed — JSON vs multipart, sizes / documentId
+ * - 04_* — file decode or PDF extract (multipart)
+ * - 05_branch — link_existing_document | new_upload_ingest
+ * - 06_* — KB row + junction (link create / exists)
+ * - 06b_chunks_existing_count — link path: existing chunk rows
+ * - 06_knowledge_document_saved — new ingest: document row id
+ * - 07_chunk_split — split stats
+ * - 07b_chunks_persisted — chunk rows saved
+ * - 07_query_chunks_missing_embedding — link path: rows with NULL embedding
+ * - 08_* — resolve LLM plugin, embed availability or skip
+ * - 09_embedding_workers_start / 10_embedding_workers_finished — concurrent embed+DB update
+ * - 11_response — final outcome summary
+ * - 99_pipeline_error — uncaught exception
+ */
+
+interface LlmAgentKnowledgeApiConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    getCms: () => Promise<{
+        getPlugin: (name: string) => unknown;
+    }>;
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+    requireAuth: (req: Request) => Promise<Response | null>;
+    requireEntityPermission?: RequireEntityPermissionFn;
+}
+declare function createLlmAgentKnowledgeHandlers(config: LlmAgentKnowledgeApiConfig): {
+    list(req: Request, slug: string): Promise<Response>;
+    post(req: Request, slug: string): Promise<Response>;
+    unlink(req: Request, slug: string, documentIdStr: string): Promise<Response>;
+} | null;
 
 /**
  * Single CMS API handler: dashboard, analytics, upload, media zip extract, blog/form by slug, users API, user auth, CRUD. Mount once (e.g. app/api/[[...path]]/route.ts).
@@ -362,8 +456,13 @@ interface CmsApiHandlerConfig {
     userProfile?: UserProfileConfig;
     /** GET/PUT /api/settings/:group */
     settings?: SettingsApiConfig;
-    /** POST /api/chat/identify, GET /api/chat/conversations/:id/messages, POST /api/chat/messages */
+    /** GET /api/chat/config (public); POST /api/chat/identify; GET /api/chat/conversations/:id/messages; POST /api/chat/messages */
     chat?: ChatApiConfig;
+    /**
+     * GET/POST /api/llm_agents/:slug/knowledge; DELETE …/knowledge/:documentId — agent KB ingest + links.
+     * When omitted but `chat` is set, the same dataSource / entityMap / getCms / json / requireAuth are reused automatically.
+     */
+    llmAgentKnowledge?: LlmAgentKnowledgeApiConfig;
     /**
      * Entity-level RBAC (session `entityPerms` / Administrator). When omitted, admin routes that need it respond with 403
      * (`entity_rbac_required`) so CRUD cannot run as auth-only. Pass `createAuthHelpers(...).requireEntityPermission` from the app.
@@ -373,7 +472,7 @@ interface CmsApiHandlerConfig {
     getSessionUser?: () => Promise<SessionUser | null>;
 }
 declare function createCmsApiHandler(config: CmsApiHandlerConfig): {
-    handle(method: string, path: string[], req: Request): Promise<Response>;
+    handle(method: string, pathInput: string[], req: Request): Promise<Response>;
 };
 
 interface StorefrontOtpFlags {
@@ -411,4 +510,4 @@ declare function createStorefrontApiHandler(config: StorefrontApiConfig): {
     handle(method: string, path: string[], req: Request): Promise<Response>;
 };
 
-export { mergeEmailLayoutCompanyDetails as $, type AnalyticsHandlerConfig as A, type BlogBySlugConfig as B, type CompanyDetails as C, type DashboardStatsConfig as D, type EmailTemplateResult as E, type ForgotPasswordConfig as F, type GetPublicSettingsGroupConfig as G, createEcommerceAnalyticsHandler as H, type InviteAcceptConfig as I, createForgotPasswordHandler as J, createFormBySlugHandler as K, createInviteAcceptHandler as L, createMediaZipExtractHandler as M, createSetPasswordHandler as N, type OrderPlacedLineItem as O, createSettingsApiHandlers as P, createStorefrontApiHandler as Q, createUploadHandler as R, type StorageService as S, type TemplateContext as T, type UploadHandlerConfig as U, createUserAuthApiRouter as V, createUserAvatarHandler as W, createUserProfileHandler as X, createUsersApiHandlers as Y, getCompanyDetailsFromSettings as Z, getPublicSettingsGroup as _, type EmailTemplateName as a, type EntityMap as b, type AuthHandlersConfig as c, type ChangePasswordConfig as d, type CmsApiHandlerConfig as e, type CmsGetter as f, type CrudHandlerOptions as g, type EcommerceAnalyticsConfig as h, type FormBySlugConfig as i, type GetPublicSettingsGroupDataSource as j, type SetPasswordConfig as k, type SettingsApiConfig as l, type SocialLinkItem as m, type StorefrontApiConfig as n, type StorefrontOtpFlags as o, type UserAuthApiConfig as p, type UserAvatarConfig as q, type UserProfileConfig as r, type UsersApiConfig as s, createAnalyticsHandlers as t, createBlogBySlugHandler as u, createChangePasswordHandler as v, createCmsApiHandler as w, createCrudByIdHandler as x, createCrudHandler as y, createDashboardStatsHandler as z };
+export { createUserAvatarHandler as $, type AnalyticsHandlerConfig as A, type BlogBySlugConfig as B, type CompanyDetails as C, type DashboardStatsConfig as D, type EmailTemplateResult as E, type ForgotPasswordConfig as F, type GetPublicSettingsGroupConfig as G, createCrudHandler as H, type InviteAcceptConfig as I, createDashboardStatsHandler as J, createEcommerceAnalyticsHandler as K, type LlmAgentKnowledgeApiConfig as L, createForgotPasswordHandler as M, createFormBySlugHandler as N, type OrderPlacedLineItem as O, type ParsedLlmAgentValidation as P, createInviteAcceptHandler as Q, createLlmAgentKnowledgeHandlers as R, type StorageService as S, type TemplateContext as T, type UploadHandlerConfig as U, createMediaZipExtractHandler as V, createSetPasswordHandler as W, createSettingsApiHandlers as X, createStorefrontApiHandler as Y, createUploadHandler as Z, createUserAuthApiRouter as _, type EmailTemplateName as a, createUserProfileHandler as a0, createUsersApiHandlers as a1, getCompanyDetailsFromSettings as a2, getPublicSettingsGroup as a3, mergeEmailLayoutCompanyDetails as a4, mergeGuardrailsIntoSystemPrompt as a5, parseLlmAgentValidationRules as a6, validateUserMessageAgainstAgentRules as a7, validateUserMessageAgainstStructuredRules as a8, type EntityMap as b, type AuthHandlersConfig as c, type ChangePasswordConfig as d, type ChatPublicConfig as e, type CmsApiHandlerConfig as f, type CmsGetter as g, type CrudHandlerOptions as h, type EcommerceAnalyticsConfig as i, type FormBySlugConfig as j, type GetPublicSettingsGroupDataSource as k, type LlmAgentValidationRulesJson as l, type SetPasswordConfig as m, type SettingsApiConfig as n, type SocialLinkItem as o, type StorefrontApiConfig as p, type StorefrontOtpFlags as q, type UserAuthApiConfig as r, type UserAvatarConfig as s, type UserProfileConfig as t, type UsersApiConfig as u, createAnalyticsHandlers as v, createBlogBySlugHandler as w, createChangePasswordHandler as x, createCmsApiHandler as y, createCrudByIdHandler as z };

package/dist/{index-GMn7-9PX.d.ts → index-Cnwh7B3r.d.ts}

@@ -153,6 +153,47 @@ declare function createUserAuthApiRouter(config: UserAuthApiConfig): {
  */
 
 type RequireEntityPermissionFn = (req: Request, entity: string, action: EntityCrudAction) => Promise<Response | null>;
+/**
+ * Optional JSON in `LlmAgent.validationRules`. Used for programmatic checks before the LLM call.
+ * For natural-language output rules, use `guardrails` / `outputRules` / `outputInstructions` (merged into system prompt).
+ */
+type LlmAgentValidationRulesJson = {
+    maxUserChars?: number;
+    maxMessageLength?: number;
+    minUserChars?: number;
+    minMessageLength?: number;
+    blockedSubstrings?: string[];
+    /** Shown to the model as output guardrails (first non-empty of guardrails | outputRules | outputInstructions wins). */
+    guardrails?: string;
+    outputRules?: string;
+    outputInstructions?: string;
+};
+type ParsedLlmAgentValidation = {
+    /** Subset used for length / substring checks only. */
+    structured: Pick<LlmAgentValidationRulesJson, 'maxUserChars' | 'maxMessageLength' | 'minUserChars' | 'minMessageLength' | 'blockedSubstrings'>;
+    /** Appended to system prompt so the model follows output guardrails. */
+    guardrailsForPrompt: string | null;
+};
+/**
+ * - Valid JSON object: structural keys → validation; `guardrails` / `outputRules` / `outputInstructions` → prompt suffix.
+ * - Not JSON: entire string is treated as prose guardrails for the prompt (no programmatic rules unless you use JSON).
+ */
+declare function parseLlmAgentValidationRules(validationRulesText: string | null | undefined): ParsedLlmAgentValidation;
+declare function validateUserMessageAgainstStructuredRules(message: string, structured: ParsedLlmAgentValidation['structured']): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Parses `validationRules` then runs programmatic checks only. */
+declare function validateUserMessageAgainstAgentRules(message: string, validationRulesText: string | null | undefined): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Merges guardrails prose into the system instruction sent to the model. */
+declare function mergeGuardrailsIntoSystemPrompt(baseSystem: string | undefined, guardrailsForPrompt: string | null): string;
 interface CmsHandlersBase {
     json: (body: unknown, init?: {
         status?: number;
@@ -311,6 +352,59 @@ interface ChatApiConfig extends CmsHandlersBase {
         getPlugin: (name: string) => unknown;
     }>;
 }
+/** Safe subset of `llm` settings for the storefront chat widget (`GET /api/chat/config`). */
+interface ChatPublicConfig {
+    enabled: boolean;
+    chatMode: 'whatsapp' | 'external' | 'llm';
+    /** When `chatMode === 'llm'`, slug of the attached agent (from `attachedAgentSlug` setting). */
+    agentSlug: string;
+    botName: string;
+    icon: string;
+    iconImageUrl: string;
+    iconBackgroundColor: string;
+    headerColor: string;
+    whatsappPhone: string;
+}
+
+/**
+ * Admin API: attach knowledge base documents to an LLM agent, ingest text into chunks + embeddings.
+ * Routes: GET/POST /api/llm_agents/:slug/knowledge, DELETE /api/llm_agents/:slug/knowledge/:documentId
+ *
+ * Pipeline logs (grep `[llm-agent-knowledge] pipeline`):
+ * - 01_request — incoming POST, content-type preview
+ * - 02_agent_loaded — agent id for slug
+ * - 03_body_parsed — JSON vs multipart, sizes / documentId
+ * - 04_* — file decode or PDF extract (multipart)
+ * - 05_branch — link_existing_document | new_upload_ingest
+ * - 06_* — KB row + junction (link create / exists)
+ * - 06b_chunks_existing_count — link path: existing chunk rows
+ * - 06_knowledge_document_saved — new ingest: document row id
+ * - 07_chunk_split — split stats
+ * - 07b_chunks_persisted — chunk rows saved
+ * - 07_query_chunks_missing_embedding — link path: rows with NULL embedding
+ * - 08_* — resolve LLM plugin, embed availability or skip
+ * - 09_embedding_workers_start / 10_embedding_workers_finished — concurrent embed+DB update
+ * - 11_response — final outcome summary
+ * - 99_pipeline_error — uncaught exception
+ */
+
+interface LlmAgentKnowledgeApiConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    getCms: () => Promise<{
+        getPlugin: (name: string) => unknown;
+    }>;
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+    requireAuth: (req: Request) => Promise<Response | null>;
+    requireEntityPermission?: RequireEntityPermissionFn;
+}
+declare function createLlmAgentKnowledgeHandlers(config: LlmAgentKnowledgeApiConfig): {
+    list(req: Request, slug: string): Promise<Response>;
+    post(req: Request, slug: string): Promise<Response>;
+    unlink(req: Request, slug: string, documentIdStr: string): Promise<Response>;
+} | null;
 
 /**
  * Single CMS API handler: dashboard, analytics, upload, media zip extract, blog/form by slug, users API, user auth, CRUD. Mount once (e.g. app/api/[[...path]]/route.ts).
@@ -362,8 +456,13 @@ interface CmsApiHandlerConfig {
     userProfile?: UserProfileConfig;
     /** GET/PUT /api/settings/:group */
     settings?: SettingsApiConfig;
-    /** POST /api/chat/identify, GET /api/chat/conversations/:id/messages, POST /api/chat/messages */
+    /** GET /api/chat/config (public); POST /api/chat/identify; GET /api/chat/conversations/:id/messages; POST /api/chat/messages */
     chat?: ChatApiConfig;
+    /**
+     * GET/POST /api/llm_agents/:slug/knowledge; DELETE …/knowledge/:documentId — agent KB ingest + links.
+     * When omitted but `chat` is set, the same dataSource / entityMap / getCms / json / requireAuth are reused automatically.
+     */
+    llmAgentKnowledge?: LlmAgentKnowledgeApiConfig;
     /**
      * Entity-level RBAC (session `entityPerms` / Administrator). When omitted, admin routes that need it respond with 403
      * (`entity_rbac_required`) so CRUD cannot run as auth-only. Pass `createAuthHelpers(...).requireEntityPermission` from the app.
@@ -373,7 +472,7 @@ interface CmsApiHandlerConfig {
     getSessionUser?: () => Promise<SessionUser | null>;
 }
 declare function createCmsApiHandler(config: CmsApiHandlerConfig): {
-    handle(method: string, path: string[], req: Request): Promise<Response>;
+    handle(method: string, pathInput: string[], req: Request): Promise<Response>;
 };
 
 interface StorefrontOtpFlags {
@@ -411,4 +510,4 @@ declare function createStorefrontApiHandler(config: StorefrontApiConfig): {
     handle(method: string, path: string[], req: Request): Promise<Response>;
 };
 
-export { mergeEmailLayoutCompanyDetails as $, type AnalyticsHandlerConfig as A, type BlogBySlugConfig as B, type CompanyDetails as C, type DashboardStatsConfig as D, type EmailTemplateResult as E, type ForgotPasswordConfig as F, type GetPublicSettingsGroupConfig as G, createEcommerceAnalyticsHandler as H, type InviteAcceptConfig as I, createForgotPasswordHandler as J, createFormBySlugHandler as K, createInviteAcceptHandler as L, createMediaZipExtractHandler as M, createSetPasswordHandler as N, type OrderPlacedLineItem as O, createSettingsApiHandlers as P, createStorefrontApiHandler as Q, createUploadHandler as R, type StorageService as S, type TemplateContext as T, type UploadHandlerConfig as U, createUserAuthApiRouter as V, createUserAvatarHandler as W, createUserProfileHandler as X, createUsersApiHandlers as Y, getCompanyDetailsFromSettings as Z, getPublicSettingsGroup as _, type EmailTemplateName as a, type EntityMap as b, type AuthHandlersConfig as c, type ChangePasswordConfig as d, type CmsApiHandlerConfig as e, type CmsGetter as f, type CrudHandlerOptions as g, type EcommerceAnalyticsConfig as h, type FormBySlugConfig as i, type GetPublicSettingsGroupDataSource as j, type SetPasswordConfig as k, type SettingsApiConfig as l, type SocialLinkItem as m, type StorefrontApiConfig as n, type StorefrontOtpFlags as o, type UserAuthApiConfig as p, type UserAvatarConfig as q, type UserProfileConfig as r, type UsersApiConfig as s, createAnalyticsHandlers as t, createBlogBySlugHandler as u, createChangePasswordHandler as v, createCmsApiHandler as w, createCrudByIdHandler as x, createCrudHandler as y, createDashboardStatsHandler as z };
+export { createUserAvatarHandler as $, type AnalyticsHandlerConfig as A, type BlogBySlugConfig as B, type CompanyDetails as C, type DashboardStatsConfig as D, type EmailTemplateResult as E, type ForgotPasswordConfig as F, type GetPublicSettingsGroupConfig as G, createCrudHandler as H, type InviteAcceptConfig as I, createDashboardStatsHandler as J, createEcommerceAnalyticsHandler as K, type LlmAgentKnowledgeApiConfig as L, createForgotPasswordHandler as M, createFormBySlugHandler as N, type OrderPlacedLineItem as O, type ParsedLlmAgentValidation as P, createInviteAcceptHandler as Q, createLlmAgentKnowledgeHandlers as R, type StorageService as S, type TemplateContext as T, type UploadHandlerConfig as U, createMediaZipExtractHandler as V, createSetPasswordHandler as W, createSettingsApiHandlers as X, createStorefrontApiHandler as Y, createUploadHandler as Z, createUserAuthApiRouter as _, type EmailTemplateName as a, createUserProfileHandler as a0, createUsersApiHandlers as a1, getCompanyDetailsFromSettings as a2, getPublicSettingsGroup as a3, mergeEmailLayoutCompanyDetails as a4, mergeGuardrailsIntoSystemPrompt as a5, parseLlmAgentValidationRules as a6, validateUserMessageAgainstAgentRules as a7, validateUserMessageAgainstStructuredRules as a8, type EntityMap as b, type AuthHandlersConfig as c, type ChangePasswordConfig as d, type ChatPublicConfig as e, type CmsApiHandlerConfig as f, type CmsGetter as g, type CrudHandlerOptions as h, type EcommerceAnalyticsConfig as i, type FormBySlugConfig as j, type GetPublicSettingsGroupDataSource as k, type LlmAgentValidationRulesJson as l, type SetPasswordConfig as m, type SettingsApiConfig as n, type SocialLinkItem as o, type StorefrontApiConfig as p, type StorefrontOtpFlags as q, type UserAuthApiConfig as r, type UserAvatarConfig as s, type UserProfileConfig as t, type UsersApiConfig as u, createAnalyticsHandlers as v, createBlogBySlugHandler as w, createChangePasswordHandler as x, createCmsApiHandler as y, createCrudByIdHandler as z };