@nixxie-cms/core 1.0.3 → 2.0.0

package/src/types/config/index.ts

@@ -10,27 +10,33 @@ import type { GraphQLSchema } from 'graphql'
 import type {
   BaseNixxieTypeInfo,
   DatabaseProvider,
+  NixxieAiRagService,
   NixxieAiService,
+  NixxieApiKeysService,
   NixxieAuditService,
+  NixxieBackupService,
   NixxieCacheService,
   NixxieContext,
   NixxieEmailService,
   NixxieHealthService,
   NixxieJobsService,
+  NixxieLoggerService,
   NixxieNotificationsService,
   NixxieRateLimitService,
   NixxieSearchService,
   NixxieStorageService,
+  NixxieVersioningService,
   NixxieWebhooksService,
+  NixxieWorkflowService,
 } from '..'
 import type { SessionStrategy } from '../session'
 import type { MaybePromise } from '../utils'
-import type { FieldAccessControl, ListAccessControl } from './access-control'
+import type { FieldAccessControl, CollectionAccessControl } from './access-control'
 import type { BaseFields } from './fields'
-import type { FieldHooks, ListHooks } from './hooks'
+import type { FieldHooks, CollectionHooks } from './hooks'
 import type {
   IdFieldConfig,
-  ListConfig,
+  CollectionConfig,
   MaybeItemFunctionWithFilter,
   MaybeSessionFunction,
 } from './lists'
@@ -46,11 +52,95 @@ type PrismaLogDefinition = {
   emit: 'stdout' | 'event'
 }
 
+/**
+ * A Nixxie plugin — one object that can contribute collections, transform the config,
+ * and run setup once the database connects. Register via `config({ plugins: [...] })`.
+ *
+ * Plugins are applied in array order: collections are merged first (a key conflict with
+ * the user's collections or an earlier plugin throws), then `extendConfig` runs, then at
+ * boot every plugin's `onConnect` runs (in order) before `db.onConnect`.
+ *
+ * @example
+ * export function myPlugin(): NixxiePlugin {
+ *   return {
+ *     name: 'my-plugin',
+ *     collections: { MyPluginLog: collection({ fields: { ... } }) },
+ *     extendConfig: config => ({
+ *       ...config,
+ *       server: {
+ *         ...config.server,
+ *         extendExpressApp: async (app, context) => {
+ *           await config.server?.extendExpressApp?.(app, context)
+ *           app.get('/my-plugin/ping', (_, res) => res.send('pong'))
+ *         },
+ *       },
+ *     }),
+ *     onConnect: async context => { ... },
+ *   }
+ * }
+ */
+export type NixxiePlugin<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInfo> = {
+  /** Unique name, used in error messages. */
+  name: string
+  /** Collections contributed by this plugin. A key conflict throws at config build time. */
+  collections?: Record<string, CollectionConfig<any>>
+  /**
+   * Transform the (pre-normalisation) config — register services, wrap hooks, extend
+   * the Express app, etc. Must return the new config.
+   */
+  extendConfig?: (config: NixxieConfigPre<TypeInfo>) => NixxieConfigPre<TypeInfo>
+  /** Run once the database has connected, before the user's `db.onConnect`. */
+  onConnect?: (context: NixxieContext<TypeInfo>) => MaybePromise<void>
+}
+
+/** Requirements for a single environment variable (see `NixxieConfigPre['env']`). */
+export type NixxieEnvVarSpec = {
+  /**
+   * Fail at boot when the variable is unset (and no `default` is given).
+   * @default true
+   */
+  required?: boolean
+  /** Regex the value must match (checked when the variable is set). */
+  pattern?: RegExp
+  /** Applied to `process.env` when the variable is unset. */
+  default?: string
+  /** Shown in the boot error to explain what the variable is for. */
+  description?: string
+}
+
+/**
+ * Environment validation spec: either a list of required variable names, or a record of
+ * per-variable requirements. Validated when the config is built, so a misconfigured
+ * deployment fails immediately with one aggregated, readable error instead of a
+ * confusing crash later.
+ */
+export type NixxieEnvSpec = readonly string[] | Record<string, NixxieEnvVarSpec>
+
 export type NixxieConfigPre<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInfo> = {
   types?: {
     path: string
   }
 
+  /**
+   * Plugins to apply to this config (collections + config transforms + boot hooks).
+   * See `NixxiePlugin`.
+   */
+  plugins?: NixxiePlugin<TypeInfo>[]
+
+  /**
+   * Environment variables this app needs. Validated at config build time —
+   * missing or malformed variables fail the boot with one aggregated error.
+   *
+   * @example
+   * env: ['DATABASE_URL', 'SESSION_SECRET']
+   * @example
+   * env: {
+   *   DATABASE_URL: { description: 'Postgres connection string' },
+   *   SMTP_PORT: { required: false, pattern: /^\d+$/, default: '587' },
+   * }
+   */
+  env?: NixxieEnvSpec
+
   db: {
     provider: DatabaseProvider
     url: string
@@ -133,7 +223,7 @@ export type NixxieConfigPre<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieType
     extendGraphqlSchema?: (schema: GraphQLSchema) => GraphQLSchema
   }
 
-  lists: Record<string, ListConfig<any>>
+  collections: Record<string, CollectionConfig<any>>
   server?: {
     /** Configuration options for the cors middleware. Set to `true` to use Nixxie's defaults */
     cors?: boolean | CorsOptions
@@ -331,6 +421,109 @@ export type NixxieConfigPre<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieType
    */
   ai?: NixxieAiService
 
+  /**
+   * Custom RAG assistant created with `createAiRag()` from `@nixxie-cms/ai-rag`.
+   * Available as `context.services.aiRag`. Stores a knowledge base, indexes it into
+   * embeddings, and answers questions grounded in that content with citations and
+   * hallucination guarding. Prefer registering it via `ragPlugin()` so the knowledge-base
+   * collections, HTTP routes and scheduled indexing are wired automatically.
+   *
+   * @example
+   * ```ts
+   * import { createAiRag, ragPlugin } from '@nixxie-cms/ai-rag'
+   * const aiRag = createAiRag({
+   *   generation: { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY! },
+   *   embedding: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+   * })
+   * export default config({ aiRag, plugins: [ragPlugin({ service: aiRag })] })
+   * ```
+   */
+  aiRag?: NixxieAiRagService
+
+  /**
+   * Content revision history created with `createVersioning()` from
+   * `@nixxie-cms/versioning`. Available as `context.services.versioning`.
+   * Snapshots item data so changes can be listed, diffed and rolled back.
+   *
+   * @example
+   * ```ts
+   * import { createVersioning } from '@nixxie-cms/versioning'
+   * export default config({
+   *   versioning: createVersioning({ store: 'memory' }),
+   * })
+   * ```
+   */
+  versioning?: NixxieVersioningService
+
+  /**
+   * Editorial state machine created with `createWorkflow()` from
+   * `@nixxie-cms/workflow`. Available as `context.services.workflow`.
+   * Enforces allowed transitions (e.g. draft → review → published).
+   *
+   * @example
+   * ```ts
+   * import { createWorkflow } from '@nixxie-cms/workflow'
+   * export default config({
+   *   workflow: createWorkflow({
+   *     name: 'editorial',
+   *     initial: 'draft',
+   *     states: ['draft', 'review', 'published'],
+   *     transitions: [
+   *       { from: 'draft', to: 'review', name: 'submit' },
+   *       { from: 'review', to: 'published', name: 'publish' },
+   *       { from: 'review', to: 'draft', name: 'reject' },
+   *     ],
+   *   }),
+   * })
+   * ```
+   */
+  workflow?: NixxieWorkflowService
+
+  /**
+   * Machine-to-machine API keys created with `createApiKeys()` from
+   * `@nixxie-cms/api-keys`. Available as `context.services.apiKeys`.
+   * Issues scoped, revocable tokens; only key hashes are stored.
+   *
+   * @example
+   * ```ts
+   * import { createApiKeys } from '@nixxie-cms/api-keys'
+   * export default config({
+   *   apiKeys: createApiKeys({ store: 'memory', prefix: 'nxk' }),
+   * })
+   * ```
+   */
+  apiKeys?: NixxieApiKeysService
+
+  /**
+   * Structured logger created with `createLogger()` from `@nixxie-cms/logger`.
+   * Available as `context.services.logger`. Level-aware with bound child loggers
+   * and pluggable sinks.
+   *
+   * @example
+   * ```ts
+   * import { createLogger } from '@nixxie-cms/logger'
+   * export default config({
+   *   logger: createLogger({ level: 'info', pretty: process.env.NODE_ENV !== 'production' }),
+   * })
+   * ```
+   */
+  logger?: NixxieLoggerService
+
+  /**
+   * Content export / import / seed created with `createBackup()` from
+   * `@nixxie-cms/backup`. Available as `context.services.backup`.
+   *
+   * @example
+   * ```ts
+   * import { createBackup, nixxieDataSource } from '@nixxie-cms/backup'
+   * // `getContext()` returns a long-lived context (see createNixxieContext)
+   * export default config({
+   *   backup: createBackup({ source: () => nixxieDataSource(getContext().sudo()) }),
+   * })
+   * ```
+   */
+  backup?: NixxieBackupService
+
   /** Telemetry boolean to disable telemetry for this project */
   telemetry?: boolean
 
@@ -369,7 +562,7 @@ export type NixxieConfig<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInf
   lists: {
     [listKey: string]: {
       listKey: string
-    } & Required<NixxieConfigPre<TypeInfo>['lists'][string]>
+    } & Required<NixxieConfigPre<TypeInfo>['collections'][string]>
   }
   server: Omit<Required<NonNullable<NixxieConfigPre<TypeInfo>['server']>>, 'cors' | 'port'> & {
     cors: CorsOptions | null
@@ -387,14 +580,20 @@ export type NixxieConfig<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInf
   search: NixxieSearchService | undefined
   notifications: NixxieNotificationsService | undefined
   ai: NixxieAiService | undefined
+  aiRag: NixxieAiRagService | undefined
+  versioning: NixxieVersioningService | undefined
+  workflow: NixxieWorkflowService | undefined
+  apiKeys: NixxieApiKeysService | undefined
+  logger: NixxieLoggerService | undefined
+  backup: NixxieBackupService | undefined
   telemetry: boolean
   ui: NonNullable<Required<NixxieConfigPre<TypeInfo>['ui']>>
 }
 
-export type { BaseFields, ListConfig, MaybeItemFunctionWithFilter, MaybeSessionFunction }
+export type { BaseFields, CollectionConfig, MaybeItemFunctionWithFilter, MaybeSessionFunction }
 
 export type AdminFileToWrite =
   | { mode: 'write'; src: string; outputPath: string }
   | { mode: 'copy'; inputPath: string; outputPath: string }
 
-export type { FieldAccessControl, FieldHooks, ListAccessControl, ListHooks }
+export type { FieldAccessControl, FieldHooks, CollectionAccessControl, CollectionHooks }