@infuro/cms-core 1.0.34 → 1.0.36

package/dist/api.d.ts

@@ -1,3 +1,633 @@
-export { A as AnalyticsHandlerConfig, a as AuthHandlersConfig, B as BlogBySlugConfig, C as ChangePasswordConfig, b as ChatPublicConfig, c as CmsApiHandlerConfig, d as CmsGetter, f as CrudHandlerOptions, D as DashboardStatsConfig, E as EcommerceAnalyticsConfig, i as EntityMap, F as ForgotPasswordConfig, j as FormBySlugConfig, G as GetPublicSettingsGroupConfig, k as GetPublicSettingsGroupDataSource, I as InviteAcceptConfig, J as JobScheduleApiConfig, L as LlmAgentKnowledgeApiConfig, l as LlmAgentValidationRulesJson, P as ParsedLlmAgentValidation, S as SetPasswordConfig, m as SettingsApiConfig, p as StorefrontApiConfig, q as StorefrontOtpFlags, U as UploadHandlerConfig, r as UserAuthApiConfig, s as UserAvatarConfig, t as UserProfileConfig, u as UsersApiConfig, V as VendorOnboardHandlersConfig, v as VendorOwnerActivation, w as createAnalyticsHandlers, x as createBlogBySlugHandler, y as createChangePasswordHandler, z as createCmsApiHandler, H as createCrudByIdHandler, K as createCrudHandler, M as createDashboardStatsHandler, N as createEcommerceAnalyticsHandler, Q as createForgotPasswordHandler, R as createFormBySlugHandler, W as createInviteAcceptHandler, X as createJobScheduleHandlers, Y as createLlmAgentKnowledgeHandlers, Z as createMediaZipExtractHandler, _ as createSetPasswordHandler, $ as createSettingsApiHandlers, a0 as createStorefrontApiHandler, a1 as createUploadHandler, a2 as createUserAuthApiRouter, a3 as createUserAvatarHandler, a4 as createUserProfileHandler, a5 as createUsersApiHandlers, a6 as createVendorOnboardHandlers, a8 as getPublicSettingsGroup, aa as mergeGuardrailsIntoSystemPrompt, ab as parseLlmAgentValidationRules, ac as simpleDecrypt, ad as simpleEncrypt, ae as validateUserMessageAgainstAgentRules, af as validateUserMessageAgainstStructuredRules } from './index-DOiJuMQA.js';
-export { k as createCmsAuthBundle } from './vendor-scope-DTYhJk_I.js';
-import 'typeorm';
+import * as typeorm from 'typeorm';
+import { DataSource } from 'typeorm';
+
+type EntityCrudAction = 'create' | 'read' | 'update' | 'delete';
+type EntityPermissionFlags = {
+    c: boolean;
+    r: boolean;
+    u: boolean;
+    d: boolean;
+};
+
+interface SessionUser {
+    id?: string;
+    email?: string | null;
+    name?: string | null;
+    groupId?: number;
+    /** User group display name (from login). */
+    groupName?: string | null;
+    /** @deprecated use entityPerms / isRBACAdmin */
+    permissions?: string[];
+    /** Administrator group: bypasses entity-level RBAC on all resources */
+    isRBACAdmin?: boolean;
+    entityPerms?: Record<string, EntityPermissionFlags>;
+    /** When false and not isRBACAdmin, admin API/UI is denied. */
+    adminAccess?: boolean;
+    /** Vendor stores this user can access (from vendor_users). */
+    vendorIds?: number[];
+    /** Active vendor for scoped CRUD (vendor staff). */
+    activeVendorId?: number | null;
+    /** Role for the active vendor link (`vendor_users.role`). */
+    vendorRole?: 'owner' | 'staff' | null;
+    /** Active vendor-scoped role id (`vendor_users.vendorRoleId`). */
+    vendorRoleId?: number | null;
+    vendorRoleName?: string | null;
+    /** True when active vendor role has `isOwnerRole`. */
+    isVendorRoleOwner?: boolean;
+    /** Permissions from active vendor role (`vendor_role_permissions`). */
+    vendorEntityPerms?: Record<string, EntityPermissionFlags>;
+    /** Set at login: vendor store portal (not platform admin). */
+    isVendorPortal?: boolean;
+    /** Set at login: vendor store owner (team + permissions). */
+    isVendorOwner?: boolean;
+}
+type GetSession = () => Promise<{
+    user?: SessionUser;
+} | null>;
+/** Pass return value into `createCmsApiHandler` (includes `getSessionUser` for vendor store APIs). */
+declare function createCmsAuthBundle(getSession: GetSession, NextResponse: {
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+}): {
+    requireAuth: (req: Request) => Promise<Response | null>;
+    requireAdminAccess: (req: Request) => Promise<Response | null>;
+    requireEntityPermission: (req: Request, entity: string, action: EntityCrudAction) => Promise<Response | null>;
+    getSessionUser: () => Promise<SessionUser | null>;
+    getAuthenticatedUser: () => Promise<SessionUser | null>;
+};
+
+type VendorScope = {
+    type: 'all';
+} | {
+    type: 'vendor';
+    vendorId: number;
+    vendorIds: number[];
+} | {
+    type: 'deny';
+};
+
+type EntityMap = Record<string, typeorm.EntityTarget<typeorm.ObjectLiteral>>;
+interface CrudHandlerOptions {
+    requireAuth: (req: Request) => Promise<Response | null>;
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+    requireEntityPermission?: (req: Request, entity: string, action: EntityCrudAction) => Promise<Response | null>;
+    /** When set, contact create/update enqueues ERP `create-contact` (non-fatal). */
+    getCms?: () => Promise<{
+        getPlugin: (name: string) => unknown;
+    }>;
+    /** When set, soft-delete sets `deletedBy` from the current admin user. */
+    getDeletedByUserId?: (req: Request) => Promise<number | null>;
+    /** When set, store rows are filtered by session vendor (platform admin bypasses). */
+    getVendorScope?: () => Promise<VendorScope>;
+    /** Hydrated session (group + vendor context) for vendorId resolution on create. */
+    getHydratedSessionUser?: () => Promise<SessionUser | null>;
+}
+declare function createCrudHandler(dataSource: DataSource, entityMap: EntityMap, options: CrudHandlerOptions): {
+    GET(req: Request, resource: string): Promise<Response>;
+    POST(req: Request, resource: string): Promise<Response>;
+    GET_METADATA(req: Request, resource: string): Promise<Response>;
+    BULK_POST(req: Request, resource: string): Promise<Response>;
+    GET_EXPORT(req: Request, resource: string): Promise<Response>;
+};
+declare function createCrudByIdHandler(dataSource: DataSource, entityMap: EntityMap, options: CrudHandlerOptions): {
+    GET(req: Request, resource: string, id: string): Promise<Response>;
+    PUT(req: Request, resource: string, id: string): Promise<Response>;
+    DELETE(req: Request, resource: string, id: string): Promise<Response>;
+};
+
+/**
+ * Auth API handler factories. Inject dataSource + entityMap, sendEmail, hash/compare; optional hooks to customize.
+ */
+
+interface AuthHandlersConfig {
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+    baseUrl: string;
+    hashPassword: (plain: string) => Promise<string>;
+    comparePassword: (plain: string, hash: string) => Promise<boolean>;
+}
+interface ForgotPasswordConfig extends AuthHandlersConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    sendEmail?: (opts: {
+        to: string;
+        subject: string;
+        html: string;
+        text?: string;
+        /** Plain reset URL for templated emails (preferred over parsing html). */
+        resetLink?: string;
+    }) => Promise<void>;
+    resetExpiryHours?: number;
+    afterCreateToken?: (email: string, resetLink: string) => Promise<void>;
+}
+declare function createForgotPasswordHandler(config: ForgotPasswordConfig): (request: Request) => Promise<Response>;
+interface SetPasswordConfig extends AuthHandlersConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    minPasswordLength?: number;
+    beforeUpdate?: (email: string, userId: number) => Promise<void>;
+}
+declare function createSetPasswordHandler(config: SetPasswordConfig): (request: Request) => Promise<Response>;
+interface InviteAcceptConfig extends AuthHandlersConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    beforeActivate?: (email: string, userId: number) => Promise<void>;
+}
+/** Decode invite token (base64 email) and set password + unblock user */
+declare function createInviteAcceptHandler(config: InviteAcceptConfig): (request: Request) => Promise<Response>;
+interface ChangePasswordConfig extends AuthHandlersConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    getSession: () => Promise<{
+        user?: {
+            email?: string | null;
+        };
+    } | null>;
+    minPasswordLength?: number;
+    beforeUpdate?: (email: string) => Promise<void>;
+}
+declare function createChangePasswordHandler(config: ChangePasswordConfig): (request: Request) => Promise<Response>;
+interface UserAuthApiConfig extends ForgotPasswordConfig, Omit<SetPasswordConfig, 'dataSource' | 'entityMap' | 'json' | 'baseUrl' | 'hashPassword' | 'comparePassword'>, Omit<InviteAcceptConfig, 'dataSource' | 'entityMap' | 'json' | 'baseUrl' | 'hashPassword' | 'comparePassword'>, Omit<ChangePasswordConfig, 'dataSource' | 'entityMap' | 'json' | 'baseUrl' | 'hashPassword' | 'comparePassword' | 'beforeUpdate' | 'getSession'> {
+    getSession?: () => Promise<{
+        user?: {
+            email?: string | null;
+        };
+    } | null>;
+    beforeChangePasswordUpdate?: (email: string) => Promise<void>;
+}
+/**
+ * Single router for all user-auth APIs. Mount in the app once.
+ * Use when you have no users/[id] route (else Next.js gives [id] precedence and "forgot-password" would match as id).
+ * Path is the segment after the mount (e.g. "forgot-password"). Returns 404 for unknown paths.
+ */
+declare function createUserAuthApiRouter(config: UserAuthApiConfig): {
+    POST(req: Request, pathname: string): Promise<Response>;
+};
+
+/** Social entry: use `iconUrl` for an image, or `icon` (emoji/text) as fallback when no image. */
+interface SocialLinkItem {
+    url: string;
+    iconUrl?: string;
+    icon?: string;
+}
+interface CompanyDetails {
+    logoUrl?: string;
+    companyName?: string;
+    supportEmail?: string;
+    supportPhone?: string;
+    socialLinks?: SocialLinkItem[];
+    /** Shown below footer rows; from email plugin settings */
+    footerDisclaimer?: string;
+    /** Heading above social icons (default "Follow Us") */
+    followUsTitle?: string;
+}
+
+/**
+ * Storage plugin contract: upload a file and return its public URL.
+ */
+interface StorageService {
+    upload(buffer: Buffer, key: string, contentType: string): Promise<string>;
+}
+
+/**
+ * CMS API handlers: dashboard, analytics, upload, blog/form by slug, users (list/create/get/update/delete/regenerate-invite/avatar/profile).
+ * All accept injectable deps; upload supports S3 or local.
+ */
+
+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;
+    }) => Response;
+    requireAuth: (req: Request) => Promise<Response | null>;
+    requireEntityPermission?: RequireEntityPermissionFn;
+}
+interface DashboardStatsConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    requirePermission?: (req: Request, permission: string) => Promise<Response | null>;
+}
+declare function createDashboardStatsHandler(config: DashboardStatsConfig): (req: Request) => Promise<Response>;
+interface EcommerceAnalyticsConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+}
+declare function createEcommerceAnalyticsHandler(config: EcommerceAnalyticsConfig): (req: Request) => Promise<Response>;
+interface VendorDashboardConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    getSessionUser: () => Promise<SessionUser | null>;
+}
+declare function createVendorDashboardHandler(config: VendorDashboardConfig): (req: Request) => Promise<Response>;
+interface AnalyticsHandlerConfig extends CmsHandlersBase {
+    getAnalyticsData?: (days: number) => Promise<unknown>;
+    getPropertyId?: () => ({
+        currentViewId?: string;
+        [k: string]: unknown;
+    });
+    getPermissions?: () => ({
+        serviceAccountEmail?: string;
+        currentViewId?: string;
+        [k: string]: unknown;
+    });
+}
+declare function createAnalyticsHandlers(config: AnalyticsHandlerConfig): {
+    GET(req: Request): Promise<Response>;
+    propertyId: () => Promise<Response>;
+    permissions: () => Promise<Response>;
+};
+
+interface UploadHandlerConfig extends CmsHandlersBase {
+    /** Storage plugin instance or getter (e.g. () => getCms().then(c => c.getPlugin('storage'))). If not set, uses local fallback. */
+    storage?: StorageService | (() => StorageService | undefined) | (() => Promise<StorageService | undefined>);
+    /** Fallback when storage not set: dir relative to cwd (e.g. "public/uploads") */
+    localUploadDir?: string;
+    allowedTypes?: string[];
+    maxSizeBytes?: number;
+    /** Resolve folder chain for `parentId` (merged from createCmsApiHandler when omitted). */
+    dataSource?: DataSource;
+    entityMap?: EntityMap;
+}
+declare function createUploadHandler(config: UploadHandlerConfig): (req: Request) => Promise<Response>;
+/** POST /api/media/extract/:id — expand a zip media row into folders/files under the zip’s parent folder. */
+declare function createMediaZipExtractHandler(config: UploadHandlerConfig): (_req: Request, zipMediaId: string) => Promise<Response>;
+interface BlogBySlugConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+}
+declare function createBlogBySlugHandler(config: BlogBySlugConfig): (_req: Request, slug: string) => Promise<Response>;
+interface FormBySlugConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+}
+declare function createFormBySlugHandler(config: FormBySlugConfig): (_req: Request, slug: string) => Promise<Response>;
+interface FormSaveHandlersConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+}
+interface FormSubmissionHandlerConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+    /** When set, form submission notification email is queued (CRM recipient). */
+    getCms?: () => Promise<{
+        getPlugin: (name: string) => unknown;
+    }>;
+    getCompanyDetails?: () => Promise<CompanyDetails>;
+    getRecipientForChannel?: (channel: 'crm' | 'sales' | 'fulfilment') => Promise<string | null>;
+}
+interface FormSubmissionGetByIdConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+}
+interface UsersApiConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    baseUrl: string;
+    /** When set with email queue/plugin, invite emails are sent on user create and regenerate-invite. */
+    getCms?: () => Promise<{
+        getPlugin: (name: string) => unknown;
+    }>;
+    getCompanyDetails?: () => Promise<CompanyDetails>;
+    /** When set, soft-delete sets `deletedBy` on the user row. */
+    getSessionUser?: () => Promise<SessionUser | null>;
+}
+declare function createUsersApiHandlers(config: UsersApiConfig): {
+    list(req: Request): Promise<Response>;
+    create(req: Request): Promise<Response>;
+    getById(_req: Request, id: string): Promise<Response>;
+    update(req: Request, id: string): Promise<Response>;
+    delete(_req: Request, id: string): Promise<Response>;
+    regenerateInvite(_req: Request, id: string): Promise<Response>;
+};
+interface UserAvatarConfig extends CmsHandlersBase {
+    getSession: () => Promise<{
+        user?: {
+            email?: string | null;
+        };
+    } | null>;
+    /** Save avatar (buffer, fileName) => publicUrl. Default: local public/uploads/avatars */
+    saveAvatar?: (buffer: Buffer, fileName: string) => Promise<string>;
+}
+declare function createUserAvatarHandler(config: UserAvatarConfig): (req: Request) => Promise<Response>;
+interface UserProfileConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    getSession: () => Promise<{
+        user?: {
+            id?: string;
+            email?: string | null;
+            name?: string | null;
+        };
+    } | null>;
+    /** Optional hook after a successful profile PUT (e.g. audit logging). */
+    onProfileUpdated?: (req: Request, user: {
+        id: number;
+        name: string;
+        email: string;
+        phone: string | null;
+    }) => Promise<void>;
+}
+/**
+ * GET / PUT handlers for `/api/users/profile` (current session user).
+ * GET merges DB fields with the session; PUT updates the user row and callers should refresh the client session (e.g. `useSession().update()`).
+ */
+declare function createUserProfileHandler(config: UserProfileConfig): {
+    GET(_req: Request): Promise<Response>;
+    PUT(req: Request): Promise<Response>;
+};
+interface SettingsApiConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    encryptionKey?: string;
+    /** Groups in this list are readable without auth (GET returns all keys for the group). */
+    publicGetGroups?: string[];
+}
+declare function simpleEncrypt(text: string, key: string): string;
+declare function simpleDecrypt(encoded: string, key: string): string;
+/**
+ * Structural types so apps with their own `typeorm` install (e.g. npm link) typecheck without duplicate-package errors.
+ */
+type GetPublicSettingsGroupDataSource = {
+    getRepository(entity: unknown): {
+        find(options: object): Promise<unknown[]>;
+    };
+};
+interface GetPublicSettingsGroupConfig {
+    dataSource: GetPublicSettingsGroupDataSource;
+    entityMap: Record<string, unknown>;
+    encryptionKey?: string;
+}
+/** Same rows as unauthenticated GET /api/settings/:group when the group is in publicGetGroups. */
+declare function getPublicSettingsGroup(config: GetPublicSettingsGroupConfig, group: string): Promise<Record<string, string>>;
+declare function createSettingsApiHandlers(config: SettingsApiConfig): {
+    GET(req: Request, group: string): Promise<Response>;
+    PUT(req: Request, group: string): Promise<Response>;
+};
+interface ChatApiConfig extends CmsHandlersBase {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    getCms: () => Promise<{
+        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 chatbot-scoped agent (`llm_agents.scope = chatbot`). */
+    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).
+ */
+
+/** CMS instance with getPlugin; when provided, analytics and userAuth.sendEmail can be resolved from plugins when not passed. */
+type CmsGetter = () => Promise<{
+    getPlugin: (name: string) => unknown;
+}>;
+interface CmsApiHandlerConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    requireAuth: (req: Request) => Promise<Response | null>;
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+    pathToModel?: (segment: string) => string;
+    crudResources?: string[];
+    /** When set, analytics and userAuth.sendEmail can be derived from getPlugin('analytics') and getPlugin('email') when not provided. */
+    getCms?: CmsGetter;
+    /** Optional: used when deriving userAuth.sendEmail to pass company details into email templates (e.g. from settings). */
+    getCompanyDetails?: () => Promise<CompanyDetails>;
+    /** Optional: used for form submission and other channel-based email recipients (from settings group "email"). */
+    getRecipientForChannel?: (channel: 'crm' | 'sales' | 'fulfilment') => Promise<string | null>;
+    userAuth?: UserAuthApiConfig;
+    /** GET /api/dashboard/stats */
+    dashboard?: DashboardStatsConfig;
+    /** GET /api/dashboard/ecommerce */
+    ecommerceAnalytics?: EcommerceAnalyticsConfig;
+    /** GET /api/analytics. If omitted and getCms is set, uses getCms().getPlugin('analytics'). */
+    analytics?: AnalyticsHandlerConfig;
+    /** POST /api/upload (S3 or local) */
+    upload?: UploadHandlerConfig;
+    /** GET /api/blogs/slug/:slug (public) */
+    blogBySlug?: BlogBySlugConfig;
+    /** GET /api/forms/slug/:slug (public) */
+    formBySlug?: FormBySlugConfig;
+    /** POST/PUT /api/forms (save form + fields; when set, overrides CRUD for forms) */
+    formSave?: FormSaveHandlersConfig;
+    /** POST /api/form-submissions (public, no auth) */
+    formSubmission?: FormSubmissionHandlerConfig;
+    /** GET /api/form-submissions/:id (auth) with form + contact relations */
+    formSubmissionGetById?: FormSubmissionGetByIdConfig;
+    /** GET/POST /api/users, GET/PUT/DELETE /api/users/:id, POST /api/users/:id/regenerate-invite */
+    usersApi?: UsersApiConfig;
+    /** POST /api/users/avatar */
+    userAvatar?: UserAvatarConfig;
+    /** GET/PUT /api/users/profile (current session user) */
+    userProfile?: UserProfileConfig;
+    /** GET/PUT /api/settings/:group */
+    settings?: SettingsApiConfig;
+    /** 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.
+     */
+    requireEntityPermission?: (req: Request, entity: string, action: EntityCrudAction) => Promise<Response | null>;
+    /** Required for vendor store RBAC + scoping. Alias: `getAuthenticatedUser`. */
+    getSessionUser?: () => Promise<SessionUser | null>;
+    /** Same as `getSessionUser` (from `createAuthHelpers().getAuthenticatedUser`). */
+    getAuthenticatedUser?: () => Promise<SessionUser | null>;
+}
+declare function createCmsApiHandler(config: CmsApiHandlerConfig): {
+    handle(method: string, pathInput: string[], req: Request): Promise<Response>;
+};
+
+type VendorOwnerActivation = 'invite' | 'password';
+interface VendorOnboardHandlersConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    json: (body: unknown, init?: {
+        status?: number;
+    }) => Response;
+    getSessionUser: () => Promise<SessionUser | null>;
+    baseUrl: string;
+    getCms?: () => Promise<{
+        getPlugin: (name: string) => unknown;
+    }>;
+    hashPassword?: (plain: string) => Promise<string>;
+    minPasswordLength?: number;
+}
+declare function createVendorOnboardHandlers(config: VendorOnboardHandlersConfig): {
+    /** POST /api/admin/vendors/onboard — create vendor + owner user + vendor_users + invite */
+    onboard(req: Request): Promise<Response>;
+    /** POST /api/admin/vendor/switch — set active vendor in session (JWT update via client) */
+    switchVendor(req: Request): Promise<Response>;
+    /** GET /api/admin/vendor/team */
+    listTeam(): Promise<Response>;
+    /** POST /api/admin/vendor/team — add staff to vendor */
+    addTeamMember(req: Request): Promise<Response>;
+    /** PATCH /api/admin/vendor/team/:userId — change member store role */
+    updateTeamMemberRole(req: Request, userIdStr: string): Promise<Response>;
+    /** DELETE /api/admin/vendor/team/:userId */
+    removeTeamMember(_req: Request, userIdStr: string): Promise<Response>;
+};
+
+interface JobScheduleApiConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    json: (body: unknown, init?: ResponseInit) => Response;
+    requireAuth: (req: Request) => Promise<Response | null>;
+    requireEntityPermission?: (req: Request, entity: string, action: 'read' | 'create' | 'update' | 'delete') => Promise<Response | null>;
+    getCms?: CmsGetter;
+    config?: Record<string, string>;
+}
+declare function createJobScheduleHandlers(apiConfig: JobScheduleApiConfig): {
+    list(req: Request): Promise<Response>;
+    getById(req: Request, id: string): Promise<Response>;
+    create(req: Request): Promise<Response>;
+    update(req: Request, id: string): Promise<Response>;
+    remove(req: Request, id: string): Promise<Response>;
+    runNow(req: Request, id: string): Promise<Response>;
+    listRuns(req: Request, id: string): Promise<Response>;
+};
+
+interface StorefrontOtpFlags {
+    login?: boolean;
+    verifyEmail?: boolean;
+    verifyPhone?: boolean;
+}
+interface StorefrontApiConfig {
+    dataSource: DataSource;
+    entityMap: EntityMap;
+    json: (body: unknown, init?: {
+        status?: number;
+        headers?: HeadersInit;
+    }) => Response;
+    getSessionUser: () => Promise<SessionUser | null>;
+    guestCookieName?: string;
+    /** Required for POST storefront/register */
+    hashPassword?: (plain: string) => Promise<string>;
+    /** When set, new registrations are blocked until email is verified and a signup email is sent. */
+    getCms?: () => Promise<{
+        getPlugin: (name: string) => unknown;
+    }>;
+    getCompanyDetails?: () => Promise<CompanyDetails>;
+    /** Origin for verify links (e.g. process.env.NEXTAUTH_URL). Required with getCms for verification URLs. */
+    publicSiteUrl?: string;
+    /** When a flag is true, the corresponding OTP storefront route is enabled. */
+    otpFlags?: StorefrontOtpFlags;
+    /** Defaults to OTP_PEPPER or NEXTAUTH_SECRET. */
+    otpPepper?: string;
+    defaultPhoneCountryCode?: string;
+    /** When false, login OTP send accepts email only (no phone). Default true. */
+    otpAllowPhoneLogin?: boolean;
+}
+declare function createStorefrontApiHandler(config: StorefrontApiConfig): {
+    handle(method: string, path: string[], req: Request): Promise<Response>;
+};
+
+export { type AnalyticsHandlerConfig, type AuthHandlersConfig, type BlogBySlugConfig, type ChangePasswordConfig, type ChatPublicConfig, type CmsApiHandlerConfig, type CmsGetter, type CrudHandlerOptions, type DashboardStatsConfig, type EcommerceAnalyticsConfig, type EntityMap, type ForgotPasswordConfig, type FormBySlugConfig, type GetPublicSettingsGroupConfig, type GetPublicSettingsGroupDataSource, type InviteAcceptConfig, type JobScheduleApiConfig, type LlmAgentKnowledgeApiConfig, type LlmAgentValidationRulesJson, type ParsedLlmAgentValidation, type SetPasswordConfig, type SettingsApiConfig, type StorefrontApiConfig, type StorefrontOtpFlags, type UploadHandlerConfig, type UserAuthApiConfig, type UserAvatarConfig, type UserProfileConfig, type UsersApiConfig, type VendorDashboardConfig, type VendorOnboardHandlersConfig, type VendorOwnerActivation, createAnalyticsHandlers, createBlogBySlugHandler, createChangePasswordHandler, createCmsApiHandler, createCmsAuthBundle, createCrudByIdHandler, createCrudHandler, createDashboardStatsHandler, createEcommerceAnalyticsHandler, createForgotPasswordHandler, createFormBySlugHandler, createInviteAcceptHandler, createJobScheduleHandlers, createLlmAgentKnowledgeHandlers, createMediaZipExtractHandler, createSetPasswordHandler, createSettingsApiHandlers, createStorefrontApiHandler, createUploadHandler, createUserAuthApiRouter, createUserAvatarHandler, createUserProfileHandler, createUsersApiHandlers, createVendorDashboardHandler, createVendorOnboardHandlers, getPublicSettingsGroup, mergeGuardrailsIntoSystemPrompt, parseLlmAgentValidationRules, simpleDecrypt, simpleEncrypt, validateUserMessageAgainstAgentRules, validateUserMessageAgainstStructuredRules };