@nixxie-cms/core 1.0.0 → 1.0.2

package/src/types/context.ts

@@ -1,530 +1,700 @@
-import type { IncomingMessage, ServerResponse } from 'http'
-import type { DocumentNode, ExecutionResult, GraphQLSchema } from 'graphql'
-import type { TypedDocumentNode } from '@graphql-typed-document-node/core'
-import type { InitialisedList } from '../lib/core/initialise-lists'
-import type { SessionStrategy } from './session'
-import type { BaseNixxieTypeInfo, BaseListTypeInfo } from './type-info'
-import type { MaybePromise } from './utils'
-
-// ── Email service types (defined here so @nixxie-cms/email can implement without circular deps) ──
-
-export type NixxieEmailRecipient = string | { name?: string; address: string }
-
-export type NixxieEmailAttachment = {
-  filename?: string
-  content?: string | Buffer
-  path?: string
-  href?: string
-  contentType?: string
-  encoding?: string
-  contentDisposition?: 'attachment' | 'inline'
-  /** Content ID for inline embedded images (used with src="cid:…") */
-  cid?: string
-}
-
-export type NixxieEmailSendOptions = {
-  to: NixxieEmailRecipient | NixxieEmailRecipient[]
-  cc?: NixxieEmailRecipient | NixxieEmailRecipient[]
-  bcc?: NixxieEmailRecipient | NixxieEmailRecipient[]
-  from?: NixxieEmailRecipient
-  replyTo?: NixxieEmailRecipient | NixxieEmailRecipient[]
-  subject: string
-  /** Name of a template file (without extension) to render */
-  template?: string
-  /** Data passed to the template engine */
-  data?: Record<string, unknown>
-  /** Raw HTML body — used when not using a template */
-  html?: string
-  /** Plain-text body */
-  text?: string
-  attachments?: NixxieEmailAttachment[]
-  headers?: Record<string, string>
-  /** Skip the suppression-list check for this send */
-  skipSuppressionCheck?: boolean
-}
-
-export type NixxieEmailQueueOptions = NixxieEmailSendOptions & {
-  /** Schedule delivery for a future date */
-  sendAt?: Date
-  priority?: 'high' | 'normal' | 'low'
-}
-
-export type NixxieEmailSentInfo = {
-  messageId: string
-  accepted: string[]
-  rejected: string[]
-  response?: string
-  timestamp: Date
-}
-
-export type NixxieEmailQueueStats = {
-  pending: number
-  processing: number
-  failed: number
-  completed: number
-}
-
-/**
- * Interface that @nixxie-cms/email's EmailService implements.
- * Defined in core so it can be referenced in NixxieContext without a circular dependency.
- */
-export type NixxieEmailService = {
-  /** Send an email immediately. Resolves when the transport accepts the message. */
-  send(options: NixxieEmailSendOptions): Promise<NixxieEmailSentInfo>
-  /** Send the same email to multiple recipients individually. */
-  bulk(
-    recipients: NixxieEmailRecipient[],
-    options: Omit<NixxieEmailSendOptions, 'to'>
-  ): Promise<NixxieEmailSentInfo[]>
-  /** Add an email to the outbound queue (non-blocking). Returns the job ID. */
-  queue(options: NixxieEmailQueueOptions): string
-  /** Add an address to the suppression list. */
-  addToSuppressionList(email: string): void
-  /** Remove an address from the suppression list. */
-  removeFromSuppressionList(email: string): void
-  /** Returns true if the address is suppressed. */
-  isSuppressed(email: string): boolean
-  /** Returns all currently suppressed addresses. */
-  getSuppressionList(): string[]
-  /** Returns live queue statistics. */
-  getQueueStats(): NixxieEmailQueueStats
-  /** Wait for the queue to drain, then stop processing. */
-  flushQueue(): Promise<void>
-  /** Gracefully shut down the service and close transport connections. */
-  close(): Promise<void>
-}
-
-// ── Jobs service ──
-
-export type NixxieJobDefinition = {
-  name: string
-  /** Cron expression or interval in milliseconds */
-  schedule: string | number
-  /** Handler function invoked on each tick */
-  handler: (ctx: { jobId: string; scheduledAt: Date }) => Promise<void> | void
-  /** Immediately run the job once on registration */
-  runImmediately?: boolean
-  /** Disable job without removing the definition */
-  enabled?: boolean
-  /** Milliseconds before a running job is considered stuck */
-  timeout?: number
-}
-
-export type NixxieJobStatus = 'idle' | 'running' | 'error' | 'disabled'
-
-export type NixxieJobInfo = {
-  name: string
-  status: NixxieJobStatus
-  lastRun?: Date
-  lastError?: string
-  nextRun?: Date
-  runs: number
-}
-
-export type NixxieJobsService = {
-  /** Register a job definition. Call before start() or at any time for hot-registration. */
-  define(job: NixxieJobDefinition): void
-  /** Remove a registered job by name. */
-  remove(name: string): void
-  /** Manually trigger a job by name, regardless of its schedule. */
-  trigger(name: string): Promise<void>
-  /** List all registered jobs with their current status. */
-  list(): NixxieJobInfo[]
-  /** Get info for a specific job. */
-  get(name: string): NixxieJobInfo | undefined
-  /** Gracefully stop all running jobs. */
-  close(): Promise<void>
-}
-
-// ── Cache service ──
-
-export type NixxieCacheSetOptions = {
-  /** Time-to-live in milliseconds. Omit for no expiry. */
-  ttl?: number
-  /** Tags for group invalidation */
-  tags?: string[]
-}
-
-export type NixxieCacheService = {
-  /** Get a cached value. Returns undefined on miss. */
-  get<T = unknown>(key: string): Promise<T | undefined>
-  /** Set a cached value. */
-  set(key: string, value: unknown, options?: NixxieCacheSetOptions): Promise<void>
-  /** Delete a single key. */
-  delete(key: string): Promise<void>
-  /** Delete all keys matching a glob pattern. */
-  deletePattern(pattern: string): Promise<void>
-  /** Delete all keys with a given tag. */
-  deleteByTag(tag: string): Promise<void>
-  /** Returns true if the key exists and has not expired. */
-  has(key: string): Promise<boolean>
-  /**
-   * Cache-aside helper. Returns the cached value if present,
-   * otherwise calls fn(), caches the result, and returns it.
-   */
-  wrap<T>(key: string, fn: () => Promise<T>, options?: NixxieCacheSetOptions): Promise<T>
-  /** Flush the entire cache. */
-  clear(): Promise<void>
-  /** Gracefully close cache connections. */
-  close(): Promise<void>
-}
-
-// ── Audit service ──
-
-export type NixxieAuditAction =
-  | 'create'
-  | 'update'
-  | 'delete'
-  | 'read'
-  | 'login'
-  | 'logout'
-  | (string & {})
-
-export type NixxieAuditEntry = {
-  action: NixxieAuditAction
-  /** List name (e.g. 'User', 'Post') */
-  resource?: string
-  /** Item ID that was acted upon */
-  resourceId?: string
-  /** Session / user who performed the action */
-  actor?: {
-    id?: string
-    label?: string
-    ip?: string
-  }
-  /** Fields that changed: { field: { from, to } } */
-  changes?: Record<string, { from: unknown; to: unknown }>
-  /** Arbitrary extra context */
-  meta?: Record<string, unknown>
-  timestamp?: Date
-}
-
-export type NixxieAuditQuery = {
-  action?: NixxieAuditAction
-  resource?: string
-  resourceId?: string
-  actorId?: string
-  from?: Date
-  to?: Date
-  take?: number
-  skip?: number
-}
-
-export type NixxieAuditRecord = NixxieAuditEntry & {
-  id: string
-  timestamp: Date
-}
-
-export type NixxieAuditService = {
-  /** Log an audit event. */
-  log(entry: NixxieAuditEntry): Promise<NixxieAuditRecord>
-  /** Query the audit log. */
-  query(filters?: NixxieAuditQuery): Promise<NixxieAuditRecord[]>
-  /** Count matching entries. */
-  count(filters?: NixxieAuditQuery): Promise<number>
-  /** Delete entries older than a given date. Returns the number of deleted records. */
-  purge(before: Date): Promise<number>
-  /** Gracefully shut down (flush pending writes). */
-  close(): Promise<void>
-}
-
-// ── Webhooks service ──
-
-export type NixxieWebhookSubscription = {
-  id: string
-  event: string
-  url: string
-  secret?: string
-  enabled: boolean
-  createdAt: Date
-}
-
-export type NixxieWebhookDelivery = {
-  id: string
-  subscriptionId: string
-  event: string
-  payload: unknown
-  status: 'pending' | 'delivered' | 'failed'
-  attempts: number
-  lastAttemptAt?: Date
-  responseStatus?: number
-  responseBody?: string
-  error?: string
-}
-
-export type NixxieWebhookSubscribeOptions = {
-  /** Optional signing secret — if provided, each request gets an `X-Nixxie-Signature` header */
-  secret?: string
-  /** Custom headers to send with every delivery */
-  headers?: Record<string, string>
-  /** Max delivery retries (default: 3) */
-  retries?: number
-}
-
-export type NixxieWebhooksService = {
-  /** Register a webhook endpoint for an event. Returns the subscription ID. */
-  subscribe(event: string, url: string, options?: NixxieWebhookSubscribeOptions): Promise<NixxieWebhookSubscription>
-  /** Remove a subscription by ID. */
-  unsubscribe(id: string): Promise<void>
-  /** Fire an event, delivering to all matching subscribers. */
-  trigger(event: string, payload: unknown): Promise<void>
-  /** List all registered subscriptions. */
-  list(event?: string): NixxieWebhookSubscription[]
-  /** Get delivery history for a subscription. */
-  deliveries(subscriptionId: string, take?: number): NixxieWebhookDelivery[]
-  /** Enable or disable a subscription. */
-  setEnabled(id: string, enabled: boolean): void
-  /** Gracefully stop delivery workers. */
-  close(): Promise<void>
-}
-
-// ── Rate limit service ──
-
-export type NixxieRateLimitResult = {
-  allowed: boolean
-  remaining: number
-  resetAt: Date
-  /** Total limit for the window */
-  limit: number
-}
-
-export type NixxieRateLimitOptions = {
-  /** Maximum number of requests in the window */
-  limit: number
-  /** Window duration in milliseconds */
-  window: number
-  /** Cost of this operation (default: 1) */
-  cost?: number
-}
-
-export type NixxieRateLimitService = {
-  /**
-   * Check without consuming — returns whether the key is within the limit.
-   * Does NOT decrement the counter.
-   */
-  check(key: string, options: NixxieRateLimitOptions): Promise<NixxieRateLimitResult>
-  /**
-   * Consume from the limit. Returns the updated result.
-   * Does NOT throw on exceeded limits — callers should check `result.allowed`.
-   */
-  consume(key: string, options: NixxieRateLimitOptions): Promise<NixxieRateLimitResult>
-  /** Reset the counter for a key. */
-  reset(key: string): Promise<void>
-  /** Gracefully shut down (close Redis connections etc.). */
-  close(): Promise<void>
-}
-
-// ── Health service ──
-
-export type NixxieHealthCheckFn = () => Promise<{ ok: boolean; message?: string; details?: unknown }>
-
-export type NixxieHealthCheckResult = {
-  name: string
-  status: 'healthy' | 'unhealthy'
-  /** Whether this check failing marks the whole system unhealthy (true) or just degraded (false) */
-  critical: boolean
-  message?: string
-  details?: unknown
-  /** How long the check took in milliseconds */
-  latency: number
-}
-
-export type NixxieHealthReport = {
-  /** Overall system status */
-  status: 'healthy' | 'degraded' | 'unhealthy'
-  timestamp: string
-  /** process.uptime() in seconds */
-  uptime: number
-  /** process.memoryUsage().heapUsed in MB */
-  memoryMb: number
-  checks: NixxieHealthCheckResult[]
-}
-
-export type NixxieHealthService = {
-  /**
-   * Register a named health check.
-   * @param critical If true (default), failure marks the system 'unhealthy'. If false, 'degraded'.
-   */
-  register(name: string, check: NixxieHealthCheckFn, options?: { critical?: boolean }): void
-  /** Remove a registered check by name. */
-  unregister(name: string): void
-  /** Run all registered checks and return the full health report. */
-  check(): Promise<NixxieHealthReport>
-  /**
-   * Returns an Express Router with two routes:
-   * - GET /live  — liveness (process is up, returns 200 immediately)
-   * - GET /ready — readiness (runs all checks, returns 200 or 503)
-   *
-   * Mount in extendExpressApp: `app.use('/health', context.services.health.router())`
-   */
-  router(options?: { livePath?: string; readyPath?: string }): unknown
-}
-
-// ── Context ──
-
-export type NixxieContext<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInfo> = {
-  db: NixxieDbAPI<TypeInfo['lists']>
-  query: NixxieListsAPI<TypeInfo['lists']>
-  graphql: NixxieGraphQLAPI
-  prisma: TypeInfo['prisma']
-  /** Runtime services configured in nixxie.ts — available everywhere context is available */
-  services: {
-    email: NixxieEmailService | null
-    jobs: NixxieJobsService | null
-    cache: NixxieCacheService | null
-    audit: NixxieAuditService | null
-    webhooks: NixxieWebhooksService | null
-    rateLimit: NixxieRateLimitService | null
-    health: NixxieHealthService | null
-  }
-  transaction: <T>(
-    f: (context: NixxieContext<TypeInfo>) => MaybePromise<T>,
-    options?: {
-      maxWait?: number
-      timeout?: number
-      isolationLevel?: {
-        Serializable: 'Serializable'
-      }
-    }
-  ) => Promise<T>
-
-  req?: IncomingMessage
-  res?: ServerResponse
-  sessionStrategy?: SessionStrategy<TypeInfo['session'], TypeInfo>
-  session?: TypeInfo['session']
-  withRequest: (req: IncomingMessage, res?: ServerResponse) => Promise<NixxieContext<TypeInfo>>
-  withSession: (session?: TypeInfo['session']) => NixxieContext<TypeInfo>
-
-  // privilege escalation
-  internal: () => NixxieContext<TypeInfo> // WARNING: name may change
-  sudo: () => NixxieContext<TypeInfo>
-
-  /**
-   * WARNING: may change in patch
-   */
-  __internal: {
-    sudo: boolean
-    lists: Record<string, InitialisedList>
-    prisma: {
-      DbNull: unknown
-      JsonNull: unknown
-    }
-  }
-}
-
-// List item API
-
-type UniqueWhereInput<ListTypeInfo extends BaseListTypeInfo> =
-  false extends ListTypeInfo['isSingleton']
-    ? { readonly where: ListTypeInfo['inputs']['uniqueWhere'] }
-    : { readonly where?: ListTypeInfo['inputs']['uniqueWhere'] }
-
-type ListAPI<ListTypeInfo extends BaseListTypeInfo> = {
-  findMany(
-    args?: {
-      readonly where?: ListTypeInfo['inputs']['where']
-      readonly take?: number
-      readonly skip?: number
-      readonly orderBy?:
-        | ListTypeInfo['inputs']['orderBy']
-        | readonly ListTypeInfo['inputs']['orderBy'][]
-      readonly cursor?: ListTypeInfo['inputs']['uniqueWhere']
-    } & ResolveFields
-  ): Promise<readonly Record<string, any>[]>
-  findOne(args: UniqueWhereInput<ListTypeInfo> & ResolveFields): Promise<Record<string, any>>
-  count(args?: { readonly where?: ListTypeInfo['inputs']['where'] }): Promise<number>
-  updateOne(
-    args: UniqueWhereInput<ListTypeInfo> & {
-      readonly data: ListTypeInfo['inputs']['update']
-    } & ResolveFields
-  ): Promise<Record<string, any>>
-  updateMany(
-    args: {
-      readonly data: readonly (UniqueWhereInput<ListTypeInfo> & {
-        readonly data: ListTypeInfo['inputs']['update']
-      })[]
-    } & ResolveFields
-  ): Promise<Record<string, any>[]>
-  createOne(
-    args: { readonly data: ListTypeInfo['inputs']['create'] } & ResolveFields
-  ): Promise<Record<string, any>>
-  createMany(
-    args: {
-      readonly data: readonly ListTypeInfo['inputs']['create'][]
-    } & ResolveFields
-  ): Promise<Record<string, any>[]>
-  deleteOne(
-    args: UniqueWhereInput<ListTypeInfo> & ResolveFields
-  ): Promise<Record<string, any> | null>
-  deleteMany(
-    args: {
-      readonly where: readonly ListTypeInfo['inputs']['uniqueWhere'][]
-    } & ResolveFields
-  ): Promise<Record<string, any>[]>
-}
-
-export type NixxieListsAPI<ListsTypeInfo extends Record<string, BaseListTypeInfo>> = {
-  [Key in keyof ListsTypeInfo]: ListAPI<ListsTypeInfo[Key]>
-}
-
-type ResolveFields = {
-  /**
-   * @default 'id'
-   */
-  readonly query?: string
-}
-
-type DbAPI<ListTypeInfo extends BaseListTypeInfo> = {
-  findMany(args?: {
-    readonly where?: ListTypeInfo['inputs']['where']
-    readonly take?: number
-    readonly skip?: number
-    readonly orderBy?:
-      | ListTypeInfo['inputs']['orderBy']
-      | readonly ListTypeInfo['inputs']['orderBy'][]
-    readonly cursor?: ListTypeInfo['inputs']['uniqueWhere']
-  }): Promise<readonly ListTypeInfo['item'][]>
-  findOne(args: UniqueWhereInput<ListTypeInfo>): Promise<ListTypeInfo['item'] | null>
-  count(args?: { readonly where?: ListTypeInfo['inputs']['where'] }): Promise<number>
-  updateOne(
-    args: UniqueWhereInput<ListTypeInfo> & {
-      readonly data: ListTypeInfo['inputs']['update']
-    }
-  ): Promise<ListTypeInfo['item']>
-  updateMany(args: {
-    readonly data: readonly (UniqueWhereInput<ListTypeInfo> & {
-      readonly data: ListTypeInfo['inputs']['update']
-    })[]
-  }): Promise<ListTypeInfo['item'][]>
-  createOne(args: {
-    readonly data: ListTypeInfo['inputs']['create']
-  }): Promise<ListTypeInfo['item']>
-  createMany(args: {
-    readonly data: readonly ListTypeInfo['inputs']['create'][]
-  }): Promise<ListTypeInfo['item'][]>
-  deleteOne(args: UniqueWhereInput<ListTypeInfo>): Promise<ListTypeInfo['item']>
-  deleteMany(args: {
-    readonly where: readonly ListTypeInfo['inputs']['uniqueWhere'][]
-  }): Promise<ListTypeInfo['item'][]>
-}
-
-export type NixxieDbAPI<ListsTypeInfo extends Record<string, BaseListTypeInfo>> = {
-  [Key in keyof ListsTypeInfo]: DbAPI<ListsTypeInfo[Key]>
-}
-
-// GraphQL API
-
-export type NixxieGraphQLAPI = {
-  schema: GraphQLSchema
-  run: <TData, TVariables extends Record<string, any>>(
-    args: GraphQLExecutionArguments<TData, TVariables>
-  ) => Promise<TData>
-  raw: <TData, TVariables extends Record<string, any>>(
-    args: GraphQLExecutionArguments<TData, TVariables>
-  ) => Promise<ExecutionResult<TData>>
-}
-
-type GraphQLExecutionArguments<TData, TVariables> = {
-  query: string | DocumentNode | TypedDocumentNode<TData, TVariables>
-  variables?: TVariables
-}
+import type { IncomingMessage, ServerResponse } from 'http'
+import type { DocumentNode, ExecutionResult, GraphQLSchema } from 'graphql'
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core'
+import type { InitialisedList } from '../lib/core/initialise-lists'
+import type { SessionStrategy } from './session'
+import type { BaseNixxieTypeInfo, BaseListTypeInfo } from './type-info'
+import type { MaybePromise } from './utils'
+
+// ── Email service types (defined here so @nixxie-cms/email can implement without circular deps) ──
+
+export type NixxieEmailRecipient = string | { name?: string; address: string }
+
+export type NixxieEmailAttachment = {
+  filename?: string
+  content?: string | Buffer
+  path?: string
+  href?: string
+  contentType?: string
+  encoding?: string
+  contentDisposition?: 'attachment' | 'inline'
+  /** Content ID for inline embedded images (used with src="cid:…") */
+  cid?: string
+}
+
+export type NixxieEmailSendOptions = {
+  to: NixxieEmailRecipient | NixxieEmailRecipient[]
+  cc?: NixxieEmailRecipient | NixxieEmailRecipient[]
+  bcc?: NixxieEmailRecipient | NixxieEmailRecipient[]
+  from?: NixxieEmailRecipient
+  replyTo?: NixxieEmailRecipient | NixxieEmailRecipient[]
+  subject: string
+  /** Name of a template file (without extension) to render */
+  template?: string
+  /** Data passed to the template engine */
+  data?: Record<string, unknown>
+  /** Raw HTML body — used when not using a template */
+  html?: string
+  /** Plain-text body */
+  text?: string
+  attachments?: NixxieEmailAttachment[]
+  headers?: Record<string, string>
+  /** Skip the suppression-list check for this send */
+  skipSuppressionCheck?: boolean
+}
+
+export type NixxieEmailQueueOptions = NixxieEmailSendOptions & {
+  /** Schedule delivery for a future date */
+  sendAt?: Date
+  priority?: 'high' | 'normal' | 'low'
+}
+
+export type NixxieEmailSentInfo = {
+  messageId: string
+  accepted: string[]
+  rejected: string[]
+  response?: string
+  timestamp: Date
+}
+
+export type NixxieEmailQueueStats = {
+  pending: number
+  processing: number
+  failed: number
+  completed: number
+}
+
+/**
+ * Interface that @nixxie-cms/email's EmailService implements.
+ * Defined in core so it can be referenced in NixxieContext without a circular dependency.
+ */
+export type NixxieEmailService = {
+  /** Send an email immediately. Resolves when the transport accepts the message. */
+  send(options: NixxieEmailSendOptions): Promise<NixxieEmailSentInfo>
+  /** Send the same email to multiple recipients individually. */
+  bulk(
+    recipients: NixxieEmailRecipient[],
+    options: Omit<NixxieEmailSendOptions, 'to'>
+  ): Promise<NixxieEmailSentInfo[]>
+  /** Add an email to the outbound queue (non-blocking). Returns the job ID. */
+  queue(options: NixxieEmailQueueOptions): string
+  /** Add an address to the suppression list. */
+  addToSuppressionList(email: string): void
+  /** Remove an address from the suppression list. */
+  removeFromSuppressionList(email: string): void
+  /** Returns true if the address is suppressed. */
+  isSuppressed(email: string): boolean
+  /** Returns all currently suppressed addresses. */
+  getSuppressionList(): string[]
+  /** Returns live queue statistics. */
+  getQueueStats(): NixxieEmailQueueStats
+  /** Wait for the queue to drain, then stop processing. */
+  flushQueue(): Promise<void>
+  /** Gracefully shut down the service and close transport connections. */
+  close(): Promise<void>
+}
+
+// ── Jobs service ──
+
+export type NixxieJobDefinition = {
+  name: string
+  /** Cron expression or interval in milliseconds */
+  schedule: string | number
+  /** Handler function invoked on each tick */
+  handler: (ctx: { jobId: string; scheduledAt: Date }) => Promise<void> | void
+  /** Immediately run the job once on registration */
+  runImmediately?: boolean
+  /** Disable job without removing the definition */
+  enabled?: boolean
+  /** Milliseconds before a running job is considered stuck */
+  timeout?: number
+}
+
+export type NixxieJobStatus = 'idle' | 'running' | 'error' | 'disabled'
+
+export type NixxieJobInfo = {
+  name: string
+  status: NixxieJobStatus
+  lastRun?: Date
+  lastError?: string
+  nextRun?: Date
+  runs: number
+}
+
+export type NixxieJobsService = {
+  /** Register a job definition. Call before start() or at any time for hot-registration. */
+  define(job: NixxieJobDefinition): void
+  /** Remove a registered job by name. */
+  remove(name: string): void
+  /** Manually trigger a job by name, regardless of its schedule. */
+  trigger(name: string): Promise<void>
+  /** List all registered jobs with their current status. */
+  list(): NixxieJobInfo[]
+  /** Get info for a specific job. */
+  get(name: string): NixxieJobInfo | undefined
+  /** Gracefully stop all running jobs. */
+  close(): Promise<void>
+}
+
+// ── Cache service ──
+
+export type NixxieCacheSetOptions = {
+  /** Time-to-live in milliseconds. Omit for no expiry. */
+  ttl?: number
+  /** Tags for group invalidation */
+  tags?: string[]
+}
+
+export type NixxieCacheService = {
+  /** Get a cached value. Returns undefined on miss. */
+  get<T = unknown>(key: string): Promise<T | undefined>
+  /** Set a cached value. */
+  set(key: string, value: unknown, options?: NixxieCacheSetOptions): Promise<void>
+  /** Delete a single key. */
+  delete(key: string): Promise<void>
+  /** Delete all keys matching a glob pattern. */
+  deletePattern(pattern: string): Promise<void>
+  /** Delete all keys with a given tag. */
+  deleteByTag(tag: string): Promise<void>
+  /** Returns true if the key exists and has not expired. */
+  has(key: string): Promise<boolean>
+  /**
+   * Cache-aside helper. Returns the cached value if present,
+   * otherwise calls fn(), caches the result, and returns it.
+   */
+  wrap<T>(key: string, fn: () => Promise<T>, options?: NixxieCacheSetOptions): Promise<T>
+  /** Flush the entire cache. */
+  clear(): Promise<void>
+  /** Gracefully close cache connections. */
+  close(): Promise<void>
+}
+
+// ── Audit service ──
+
+export type NixxieAuditAction =
+  | 'create'
+  | 'update'
+  | 'delete'
+  | 'read'
+  | 'login'
+  | 'logout'
+  | (string & {})
+
+export type NixxieAuditEntry = {
+  action: NixxieAuditAction
+  /** List name (e.g. 'User', 'Post') */
+  resource?: string
+  /** Item ID that was acted upon */
+  resourceId?: string
+  /** Session / user who performed the action */
+  actor?: {
+    id?: string
+    label?: string
+    ip?: string
+  }
+  /** Fields that changed: { field: { from, to } } */
+  changes?: Record<string, { from: unknown; to: unknown }>
+  /** Arbitrary extra context */
+  meta?: Record<string, unknown>
+  timestamp?: Date
+}
+
+export type NixxieAuditQuery = {
+  action?: NixxieAuditAction
+  resource?: string
+  resourceId?: string
+  actorId?: string
+  from?: Date
+  to?: Date
+  take?: number
+  skip?: number
+}
+
+export type NixxieAuditRecord = NixxieAuditEntry & {
+  id: string
+  timestamp: Date
+}
+
+export type NixxieAuditService = {
+  /** Log an audit event. */
+  log(entry: NixxieAuditEntry): Promise<NixxieAuditRecord>
+  /** Query the audit log. */
+  query(filters?: NixxieAuditQuery): Promise<NixxieAuditRecord[]>
+  /** Count matching entries. */
+  count(filters?: NixxieAuditQuery): Promise<number>
+  /** Delete entries older than a given date. Returns the number of deleted records. */
+  purge(before: Date): Promise<number>
+  /** Gracefully shut down (flush pending writes). */
+  close(): Promise<void>
+}
+
+// ── Webhooks service ──
+
+export type NixxieWebhookSubscription = {
+  id: string
+  event: string
+  url: string
+  secret?: string
+  enabled: boolean
+  createdAt: Date
+}
+
+export type NixxieWebhookDelivery = {
+  id: string
+  subscriptionId: string
+  event: string
+  payload: unknown
+  status: 'pending' | 'delivered' | 'failed'
+  attempts: number
+  lastAttemptAt?: Date
+  responseStatus?: number
+  responseBody?: string
+  error?: string
+}
+
+export type NixxieWebhookSubscribeOptions = {
+  /** Optional signing secret — if provided, each request gets an `X-Nixxie-Signature` header */
+  secret?: string
+  /** Custom headers to send with every delivery */
+  headers?: Record<string, string>
+  /** Max delivery retries (default: 3) */
+  retries?: number
+}
+
+export type NixxieWebhooksService = {
+  /** Register a webhook endpoint for an event. Returns the subscription ID. */
+  subscribe(event: string, url: string, options?: NixxieWebhookSubscribeOptions): Promise<NixxieWebhookSubscription>
+  /** Remove a subscription by ID. */
+  unsubscribe(id: string): Promise<void>
+  /** Fire an event, delivering to all matching subscribers. */
+  trigger(event: string, payload: unknown): Promise<void>
+  /** List all registered subscriptions. */
+  list(event?: string): NixxieWebhookSubscription[]
+  /** Get delivery history for a subscription. */
+  deliveries(subscriptionId: string, take?: number): NixxieWebhookDelivery[]
+  /** Enable or disable a subscription. */
+  setEnabled(id: string, enabled: boolean): void
+  /** Gracefully stop delivery workers. */
+  close(): Promise<void>
+}
+
+// ── Rate limit service ──
+
+export type NixxieRateLimitResult = {
+  allowed: boolean
+  remaining: number
+  resetAt: Date
+  /** Total limit for the window */
+  limit: number
+}
+
+export type NixxieRateLimitOptions = {
+  /** Maximum number of requests in the window */
+  limit: number
+  /** Window duration in milliseconds */
+  window: number
+  /** Cost of this operation (default: 1) */
+  cost?: number
+}
+
+export type NixxieRateLimitService = {
+  /**
+   * Check without consuming — returns whether the key is within the limit.
+   * Does NOT decrement the counter.
+   */
+  check(key: string, options: NixxieRateLimitOptions): Promise<NixxieRateLimitResult>
+  /**
+   * Consume from the limit. Returns the updated result.
+   * Does NOT throw on exceeded limits — callers should check `result.allowed`.
+   */
+  consume(key: string, options: NixxieRateLimitOptions): Promise<NixxieRateLimitResult>
+  /** Reset the counter for a key. */
+  reset(key: string): Promise<void>
+  /** Gracefully shut down (close Redis connections etc.). */
+  close(): Promise<void>
+}
+
+// ── Health service ──
+
+export type NixxieHealthCheckFn = () => Promise<{ ok: boolean; message?: string; details?: unknown }>
+
+export type NixxieHealthCheckResult = {
+  name: string
+  status: 'healthy' | 'unhealthy'
+  /** Whether this check failing marks the whole system unhealthy (true) or just degraded (false) */
+  critical: boolean
+  message?: string
+  details?: unknown
+  /** How long the check took in milliseconds */
+  latency: number
+}
+
+export type NixxieHealthReport = {
+  /** Overall system status */
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  timestamp: string
+  /** Application version, if configured */
+  version?: string
+  /** process.uptime() in seconds */
+  uptime: number
+  /** process.memoryUsage().heapUsed in MB */
+  memoryMb: number
+  checks: NixxieHealthCheckResult[]
+}
+
+export type NixxieHealthService = {
+  /**
+   * Register a named health check.
+   * @param critical If true (default), failure marks the system 'unhealthy'. If false, 'degraded'.
+   */
+  register(name: string, check: NixxieHealthCheckFn, options?: { critical?: boolean }): void
+  /** Remove a registered check by name. */
+  unregister(name: string): void
+  /** Run all registered checks and return the full health report. */
+  check(): Promise<NixxieHealthReport>
+  /**
+   * Returns an Express Router with two routes:
+   * - GET /live  — liveness (process is up, returns 200 immediately)
+   * - GET /ready — readiness (runs all checks, returns 200 or 503)
+   *
+   * Mount in extendExpressApp: `app.use('/health', context.services.health.router())`
+   */
+  router(options?: { livePath?: string; readyPath?: string }): unknown
+}
+
+// ── Storage service ──
+
+export type NixxieStoredFile = {
+  /** Storage key / path the file is stored under */
+  key: string
+  /** Public or signed URL for retrieving the file */
+  url: string
+  /** Size in bytes, if known */
+  size?: number
+  /** Detected or provided content type */
+  contentType?: string
+}
+
+export type NixxiePutOptions = {
+  /** MIME type to store alongside the object */
+  contentType?: string
+  /** Whether the object should be publicly readable (driver permitting). Default: false */
+  public?: boolean
+  /** Arbitrary metadata stored with the object */
+  metadata?: Record<string, string>
+}
+
+export type NixxieSignedUrlOptions = {
+  /** Expiry in seconds. Default: 900 (15 minutes) */
+  expiresIn?: number
+  /** 'get' for download URLs, 'put' for direct browser uploads. Default: 'get' */
+  operation?: 'get' | 'put'
+  /** Content type required on the upload when operation is 'put' */
+  contentType?: string
+}
+
+/** Pluggable blob storage. Implemented by @nixxie-cms/storage (local, S3, GCS, Azure). */
+export type NixxieStorageService = {
+  /** Store a file and return its key + URL. */
+  put(key: string, data: Buffer | Uint8Array | string, options?: NixxiePutOptions): Promise<NixxieStoredFile>
+  /** Read a file's bytes. Resolves undefined when the key does not exist. */
+  get(key: string): Promise<Buffer | undefined>
+  /** Delete a file. No-op if it does not exist. */
+  delete(key: string): Promise<void>
+  /** Whether a key exists. */
+  has(key: string): Promise<boolean>
+  /** Public URL for a key (may be unsigned and require the object to be public). */
+  url(key: string): string
+  /** Create a time-limited signed URL for download or direct upload. */
+  signedUrl(key: string, options?: NixxieSignedUrlOptions): Promise<string>
+  /** List keys under a prefix. */
+  list(prefix?: string): Promise<string[]>
+}
+
+// ── Search service ──
+
+export type NixxieSearchDocument = Record<string, unknown> & { id: string }
+
+export type NixxieSearchQuery = {
+  /** Free-text query string. */
+  q: string
+  /** Maximum results to return. Default: 20 */
+  limit?: number
+  /** Number of results to skip (pagination). */
+  offset?: number
+  /** Equality filters applied to indexed attributes. */
+  filter?: Record<string, string | number | boolean>
+  /** Attributes to sort by, e.g. ['createdAt:desc']. */
+  sort?: string[]
+}
+
+export type NixxieSearchHit<T = NixxieSearchDocument> = {
+  document: T
+  /** Relevance score (driver-specific scale), when available. */
+  score?: number
+}
+
+export type NixxieSearchResults<T = NixxieSearchDocument> = {
+  hits: NixxieSearchHit<T>[]
+  /** Total matches, when the backend reports it. */
+  total: number
+  /** Query processing time in milliseconds, when available. */
+  tookMs?: number
+}
+
+/** Pluggable full-text search. Implemented by @nixxie-cms/search (memory, Meilisearch, Typesense, Algolia, Elasticsearch). */
+export type NixxieSearchService = {
+  /** Create or update one or more documents in an index. */
+  index(indexName: string, documents: NixxieSearchDocument | NixxieSearchDocument[]): Promise<void>
+  /** Remove a document from an index by id. */
+  remove(indexName: string, id: string): Promise<void>
+  /** Run a search against an index. */
+  search<T = NixxieSearchDocument>(indexName: string, query: NixxieSearchQuery): Promise<NixxieSearchResults<T>>
+  /** Delete every document in an index. */
+  clear(indexName: string): Promise<void>
+  /** Gracefully close any open connections. */
+  close(): Promise<void>
+}
+
+// ── Notifications service ──
+
+export type NixxieNotificationChannel = string
+
+export type NixxieNotification = {
+  /** Channel(s) to deliver on. Omit to use every configured channel. */
+  channel?: NixxieNotificationChannel | NixxieNotificationChannel[]
+  /** Recipient address — meaning depends on the channel (Slack channel id, phone number, etc.). */
+  to?: string
+  /** Short title / subject. */
+  title?: string
+  /** Body of the notification. */
+  body: string
+  /** Arbitrary structured data forwarded to the channel. */
+  data?: Record<string, unknown>
+}
+
+export type NixxieNotificationResult = {
+  channel: NixxieNotificationChannel
+  ok: boolean
+  /** Provider message id when delivery succeeded. */
+  id?: string
+  /** Error message when delivery failed. */
+  error?: string
+}
+
+/** Multi-channel notifications (Slack, Discord, SMS, webhook, custom). Implemented by @nixxie-cms/notifications. */
+export type NixxieNotificationsService = {
+  /** Send a notification across the requested (or all configured) channels. */
+  send(notification: NixxieNotification): Promise<NixxieNotificationResult[]>
+  /** List the names of the configured channels. */
+  channels(): NixxieNotificationChannel[]
+}
+
+// ── AI service ──
+
+export type NixxieAiMessage = {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+export type NixxieAiCompleteOptions = {
+  /** Override the configured model for this call. */
+  model?: string
+  /** System prompt prepended to the conversation. */
+  system?: string
+  /** Sampling temperature. */
+  temperature?: number
+  /** Maximum tokens to generate. */
+  maxTokens?: number
+}
+
+export type NixxieAiCompletion = {
+  text: string
+  model: string
+  usage?: { inputTokens?: number; outputTokens?: number }
+}
+
+/** Pluggable LLM + embeddings access. Implemented by @nixxie-cms/ai (Anthropic, OpenAI). */
+export type NixxieAiService = {
+  /** Complete a single prompt. */
+  complete(prompt: string, options?: NixxieAiCompleteOptions): Promise<NixxieAiCompletion>
+  /** Complete a multi-turn conversation. */
+  chat(messages: NixxieAiMessage[], options?: NixxieAiCompleteOptions): Promise<NixxieAiCompletion>
+  /** Produce an embedding vector for a string. */
+  embed(text: string): Promise<number[]>
+  /** Produce embedding vectors for many strings in one call. */
+  embedMany(texts: string[]): Promise<number[][]>
+}
+
+// ── Context ──
+
+export type NixxieContext<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInfo> = {
+  db: NixxieDbAPI<TypeInfo['lists']>
+  query: NixxieListsAPI<TypeInfo['lists']>
+  graphql: NixxieGraphQLAPI
+  prisma: TypeInfo['prisma']
+  /** Runtime services configured in nixxie.ts — available everywhere context is available */
+  services: {
+    email: NixxieEmailService | null
+    jobs: NixxieJobsService | null
+    cache: NixxieCacheService | null
+    audit: NixxieAuditService | null
+    webhooks: NixxieWebhooksService | null
+    rateLimit: NixxieRateLimitService | null
+    health: NixxieHealthService | null
+    storage: NixxieStorageService | null
+    search: NixxieSearchService | null
+    notifications: NixxieNotificationsService | null
+    ai: NixxieAiService | null
+  }
+  transaction: <T>(
+    f: (context: NixxieContext<TypeInfo>) => MaybePromise<T>,
+    options?: {
+      maxWait?: number
+      timeout?: number
+      isolationLevel?: {
+        Serializable: 'Serializable'
+      }
+    }
+  ) => Promise<T>
+
+  req?: IncomingMessage
+  res?: ServerResponse
+  sessionStrategy?: SessionStrategy<TypeInfo['session'], TypeInfo>
+  session?: TypeInfo['session']
+  withRequest: (req: IncomingMessage, res?: ServerResponse) => Promise<NixxieContext<TypeInfo>>
+  withSession: (session?: TypeInfo['session']) => NixxieContext<TypeInfo>
+
+  // privilege escalation
+  internal: () => NixxieContext<TypeInfo> // WARNING: name may change
+  sudo: () => NixxieContext<TypeInfo>
+
+  /**
+   * WARNING: may change in patch
+   */
+  __internal: {
+    sudo: boolean
+    lists: Record<string, InitialisedList>
+    prisma: {
+      DbNull: unknown
+      JsonNull: unknown
+    }
+  }
+}
+
+// List item API
+
+type UniqueWhereInput<ListTypeInfo extends BaseListTypeInfo> =
+  false extends ListTypeInfo['isSingleton']
+    ? { readonly where: ListTypeInfo['inputs']['uniqueWhere'] }
+    : { readonly where?: ListTypeInfo['inputs']['uniqueWhere'] }
+
+type ListAPI<ListTypeInfo extends BaseListTypeInfo> = {
+  findMany(
+    args?: {
+      readonly where?: ListTypeInfo['inputs']['where']
+      readonly take?: number
+      readonly skip?: number
+      readonly orderBy?:
+        | ListTypeInfo['inputs']['orderBy']
+        | readonly ListTypeInfo['inputs']['orderBy'][]
+      readonly cursor?: ListTypeInfo['inputs']['uniqueWhere']
+    } & ResolveFields
+  ): Promise<readonly Record<string, any>[]>
+  findOne(args: UniqueWhereInput<ListTypeInfo> & ResolveFields): Promise<Record<string, any>>
+  count(args?: { readonly where?: ListTypeInfo['inputs']['where'] }): Promise<number>
+  updateOne(
+    args: UniqueWhereInput<ListTypeInfo> & {
+      readonly data: ListTypeInfo['inputs']['update']
+    } & ResolveFields
+  ): Promise<Record<string, any>>
+  updateMany(
+    args: {
+      readonly data: readonly (UniqueWhereInput<ListTypeInfo> & {
+        readonly data: ListTypeInfo['inputs']['update']
+      })[]
+    } & ResolveFields
+  ): Promise<Record<string, any>[]>
+  createOne(
+    args: { readonly data: ListTypeInfo['inputs']['create'] } & ResolveFields
+  ): Promise<Record<string, any>>
+  createMany(
+    args: {
+      readonly data: readonly ListTypeInfo['inputs']['create'][]
+    } & ResolveFields
+  ): Promise<Record<string, any>[]>
+  deleteOne(
+    args: UniqueWhereInput<ListTypeInfo> & ResolveFields
+  ): Promise<Record<string, any> | null>
+  deleteMany(
+    args: {
+      readonly where: readonly ListTypeInfo['inputs']['uniqueWhere'][]
+    } & ResolveFields
+  ): Promise<Record<string, any>[]>
+}
+
+export type NixxieListsAPI<ListsTypeInfo extends Record<string, BaseListTypeInfo>> = {
+  [Key in keyof ListsTypeInfo]: ListAPI<ListsTypeInfo[Key]>
+}
+
+type ResolveFields = {
+  /**
+   * @default 'id'
+   */
+  readonly query?: string
+}
+
+type DbAPI<ListTypeInfo extends BaseListTypeInfo> = {
+  findMany(args?: {
+    readonly where?: ListTypeInfo['inputs']['where']
+    readonly take?: number
+    readonly skip?: number
+    readonly orderBy?:
+      | ListTypeInfo['inputs']['orderBy']
+      | readonly ListTypeInfo['inputs']['orderBy'][]
+    readonly cursor?: ListTypeInfo['inputs']['uniqueWhere']
+  }): Promise<readonly ListTypeInfo['item'][]>
+  findOne(args: UniqueWhereInput<ListTypeInfo>): Promise<ListTypeInfo['item'] | null>
+  count(args?: { readonly where?: ListTypeInfo['inputs']['where'] }): Promise<number>
+  updateOne(
+    args: UniqueWhereInput<ListTypeInfo> & {
+      readonly data: ListTypeInfo['inputs']['update']
+    }
+  ): Promise<ListTypeInfo['item']>
+  updateMany(args: {
+    readonly data: readonly (UniqueWhereInput<ListTypeInfo> & {
+      readonly data: ListTypeInfo['inputs']['update']
+    })[]
+  }): Promise<ListTypeInfo['item'][]>
+  createOne(args: {
+    readonly data: ListTypeInfo['inputs']['create']
+  }): Promise<ListTypeInfo['item']>
+  createMany(args: {
+    readonly data: readonly ListTypeInfo['inputs']['create'][]
+  }): Promise<ListTypeInfo['item'][]>
+  deleteOne(args: UniqueWhereInput<ListTypeInfo>): Promise<ListTypeInfo['item']>
+  deleteMany(args: {
+    readonly where: readonly ListTypeInfo['inputs']['uniqueWhere'][]
+  }): Promise<ListTypeInfo['item'][]>
+}
+
+export type NixxieDbAPI<ListsTypeInfo extends Record<string, BaseListTypeInfo>> = {
+  [Key in keyof ListsTypeInfo]: DbAPI<ListsTypeInfo[Key]>
+}
+
+// GraphQL API
+
+export type NixxieGraphQLAPI = {
+  schema: GraphQLSchema
+  run: <TData, TVariables extends Record<string, any>>(
+    args: GraphQLExecutionArguments<TData, TVariables>
+  ) => Promise<TData>
+  raw: <TData, TVariables extends Record<string, any>>(
+    args: GraphQLExecutionArguments<TData, TVariables>
+  ) => Promise<ExecutionResult<TData>>
+}
+
+type GraphQLExecutionArguments<TData, TVariables> = {
+  query: string | DocumentNode | TypedDocumentNode<TData, TVariables>
+  variables?: TVariables
+}