@nixxie-cms/core 1.0.0

package/src/types/context.ts

@@ -0,0 +1,530 @@
+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
+}

package/src/types/core.ts

@@ -0,0 +1,16 @@
+import type { GraphQLResolveInfo } from 'graphql'
+import type { NixxieContext } from './context'
+
+export type DatabaseProvider = 'sqlite' | 'postgresql' | 'mysql'
+
+export type GraphQLResolver<Context extends NixxieContext> = (
+  root: any,
+  args: any,
+  context: Context,
+  info: GraphQLResolveInfo
+) => any
+
+export type GraphQLSchemaExtension<Context extends NixxieContext> = {
+  typeDefs: string
+  resolvers: Record<string, Record<string, GraphQLResolver<Context>>>
+}

package/src/types/index.ts

@@ -0,0 +1,8 @@
+export * from './core'
+export * from './config'
+export * from './utils'
+export * from './session'
+export * from './admin-meta'
+export * from './context'
+export * from './next-fields'
+export * from './type-info'