@opensaas/stack-core 0.1.7 → 0.3.0

package/src/access/engine.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest'
+import { filterWritableFields } from './engine.js'
+
+describe('filterWritableFields', () => {
+  it('should filter out foreign key fields when their corresponding relationship field exists', async () => {
+    // Setup: Define field configs with a relationship field
+    const fieldConfigs = {
+      title: {
+        type: 'text',
+      },
+      author: {
+        type: 'relationship',
+        many: false,
+      },
+      tags: {
+        type: 'relationship',
+        many: true, // Many-to-many relationships don't have foreign keys
+      },
+    }
+
+    // Data that includes both the foreign key (authorId) and other fields
+    const data = {
+      title: 'Test Post',
+      authorId: 'user-123', // This should be filtered out
+      tagsId: 'tag-456', // This should NOT be filtered (tags is many:true)
+      author: {
+        connect: { id: 'user-123' },
+      },
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: {
+        session: null,
+        _isSudo: true, // Use sudo to bypass access control checks
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    // authorId should be filtered out
+    expect(filtered).not.toHaveProperty('authorId')
+
+    // title should remain
+    expect(filtered).toHaveProperty('title', 'Test Post')
+
+    // author relationship should remain
+    expect(filtered).toHaveProperty('author')
+    expect(filtered.author).toEqual({ connect: { id: 'user-123' } })
+
+    // tagsId should remain (tags is many:true, so no foreign key is created)
+    expect(filtered).toHaveProperty('tagsId', 'tag-456')
+  })
+
+  it('should filter out system fields', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+    }
+
+    const data = {
+      id: 'post-123',
+      title: 'Test',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: {
+        session: null,
+        _isSudo: true,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    // System fields should be filtered out
+    expect(filtered).not.toHaveProperty('id')
+    expect(filtered).not.toHaveProperty('createdAt')
+    expect(filtered).not.toHaveProperty('updatedAt')
+
+    // Regular fields should remain
+    expect(filtered).toHaveProperty('title', 'Test')
+  })
+
+  it('should handle update operation', async () => {
+    const fieldConfigs = {
+      title: { type: 'text' },
+      author: {
+        type: 'relationship',
+        many: false,
+      },
+    }
+
+    const data = {
+      title: 'Updated Title',
+      authorId: 'user-456', // Should be filtered out
+      author: {
+        connect: { id: 'user-456' },
+      },
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'update', {
+      session: null,
+      item: { id: 'post-123' },
+      context: {
+        session: null,
+        _isSudo: true,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    expect(filtered).not.toHaveProperty('authorId')
+    expect(filtered).toHaveProperty('title', 'Updated Title')
+    expect(filtered).toHaveProperty('author')
+  })
+
+  it('should not filter fields that happen to end with "Id" but are not foreign keys', async () => {
+    const fieldConfigs = {
+      trackingId: { type: 'text' }, // Regular field that happens to end with "Id"
+      author: {
+        type: 'relationship',
+        many: false,
+      },
+    }
+
+    const data = {
+      trackingId: 'track-123', // Should NOT be filtered (it's a regular field)
+      authorId: 'user-456', // SHOULD be filtered (it's a foreign key)
+    }
+
+    const filtered = await filterWritableFields(data, fieldConfigs, 'create', {
+      session: null,
+      context: {
+        session: null,
+        _isSudo: true,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any,
+    })
+
+    // trackingId is a defined field, so it should remain
+    expect(filtered).toHaveProperty('trackingId', 'track-123')
+
+    // authorId is a foreign key for author relationship, so it should be filtered
+    expect(filtered).not.toHaveProperty('authorId')
+  })
+})

package/src/access/engine.ts

@@ -63,7 +63,7 @@ export function getRelatedListConfig(
 export async function checkAccess<T = Record<string, unknown>>(
   accessControl: AccessControl<T> | undefined,
   args: {
-    session: Session
+    session: Session | null
     item?: T
     context: AccessContext
   },
@@ -114,7 +114,7 @@ export async function checkFieldAccess(
   fieldAccess: FieldAccess | undefined,
   operation: 'read' | 'create' | 'update',
   args: {
-    session: Session
+    session: Session | null
     item?: Record<string, unknown>
     context: AccessContext & { _isSudo?: boolean }
   },
@@ -190,7 +190,7 @@ function matchesFilter(item: Record<string, unknown>, filter: Record<string, unk
 export async function buildIncludeWithAccessControl(
   fieldConfigs: Record<string, FieldConfig>,
   args: {
-    session: Session
+    session: Session | null
     context: AccessContext
   },
   config: OpenSaasConfig,
@@ -261,7 +261,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   item: T,
   fieldConfigs: Record<string, FieldConfig>,
   args: {
-    session: Session
+    session: Session | null
     context: AccessContext & { _isSudo?: boolean }
   },
   config?: OpenSaasConfig,
@@ -365,16 +365,29 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
  */
 export async function filterWritableFields<T extends Record<string, unknown>>(
   data: T,
-  fieldConfigs: Record<string, { access?: FieldAccess }>,
+  fieldConfigs: Record<string, { access?: FieldAccess; type?: string }>,
   operation: 'create' | 'update',
   args: {
-    session: Session
+    session: Session | null
     item?: Record<string, unknown>
     context: AccessContext & { _isSudo?: boolean }
   },
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
+  // Build a set of foreign key field names to exclude
+  // Foreign keys should not be in the data when using Prisma's relation syntax
+  const foreignKeyFields = new Set<string>()
+  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+    if (fieldConfig.type === 'relationship') {
+      // For non-many relationships, Prisma creates a foreign key field named `${fieldName}Id`
+      const relConfig = fieldConfig as { many?: boolean }
+      if (!relConfig.many) {
+        foreignKeyFields.add(`${fieldName}Id`)
+      }
+    }
+  }
+
   for (const [fieldName, value] of Object.entries(data)) {
     const fieldConfig = fieldConfigs[fieldName]
 
@@ -383,6 +396,12 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
       continue
     }
 
+    // Skip foreign key fields (e.g., authorId) when their corresponding relationship field exists
+    // This prevents conflicts when using Prisma's relation syntax (e.g., author: { connect: { id } })
+    if (foreignKeyFields.has(fieldName)) {
+      continue
+    }
+
     // Check field access (checkFieldAccess already handles sudo mode)
     const canWrite = await checkFieldAccess(fieldConfig?.access, operation, {
       ...args,

package/src/access/types.ts

@@ -1,10 +1,39 @@
 /**
- * Session type - can be extended by users
+ * Session interface - can be augmented by developers to add custom fields
+ *
+ * By default, Session is a permissive object that can contain any properties.
+ * To get type safety and autocomplete, use module augmentation:
+ *
+ * @example
+ * ```typescript
+ * // types/session.d.ts
+ * import '@opensaas/stack-core'
+ *
+ * declare module '@opensaas/stack-core' {
+ *   interface Session {
+ *     userId: string
+ *     email: string
+ *     role: 'admin' | 'user'
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, session will be fully typed everywhere:
+ * - Access control functions
+ * - Hooks (resolveInput, validateInput, etc.)
+ * - Context object
+ *
+ * @example
+ * ```typescript
+ * // With augmentation, this is fully typed:
+ * const isAdmin: AccessControl = ({ session }) => {
+ *   return session?.role === 'admin'  // ✅ Autocomplete works
+ * }
+ * ```
  */
-export type Session = {
-  userId?: string
+export interface Session {
   [key: string]: unknown
-} | null
+}
 
 /**
  * Generic Prisma model delegate type
@@ -113,14 +142,15 @@ export type StorageUtils = {
 
 /**
  * Context type (simplified for access control)
+ * Using interface instead of type to allow module augmentation
  */
-export type AccessContext<TPrisma extends PrismaClientLike = PrismaClientLike> = {
-  session: Session
+export interface AccessContext<TPrisma extends PrismaClientLike = PrismaClientLike> {
+  session: Session | null
   prisma: TPrisma
   db: AccessControlledDB<TPrisma>
   storage: StorageUtils
+  plugins: Record<string, unknown>
   _isSudo: boolean
-  [key: string]: unknown
 }
 
 /**
@@ -136,7 +166,7 @@ export type PrismaFilter<T = Record<string, unknown>> = Partial<Record<keyof T,
  * - PrismaFilter: Prisma where clause to filter results
  */
 export type AccessControl<T = Record<string, unknown>> = (args: {
-  session: Session
+  session: Session | null
   item?: T // Present for update/delete operations
   context: AccessContext
 }) => boolean | PrismaFilter<T> | Promise<boolean | PrismaFilter<T>>

package/src/config/index.ts

@@ -21,40 +21,66 @@ export function config(userConfig: OpenSaasConfig): OpenSaasConfig | Promise<Ope
 /**
  * Helper function to define a list with type safety
  *
- * Accepts raw field configs and transforms them to inject the item type T
- * This enables proper typing in field hooks where item: T
+ * Accepts raw field configs and transforms them to inject the item type
+ * This enables proper typing in field hooks where item is typed correctly
  *
  * @example
  * ```typescript
- * import type { User } from './.opensaas/types'
+ * // Basic usage (before generation)
+ * Post: list({
+ *   fields: { title: text() },
+ *   hooks: {
+ *     resolveInput: async ({ resolvedData }) => {
+ *       // resolvedData: Record<string, unknown>
+ *       return resolvedData
+ *     }
+ *   }
+ * })
+ *
+ * // With TypeInfo (after generation)
+ * import type { Lists } from './.opensaas/lists'
  *
- * User: list<User>({
- *   fields: {
- *     password: password({
- *       hooks: {
- *         resolveInput: async ({ inputValue, item }) => {
- *           // item is typed as User | undefined
- *           // inputValue is typed as string | undefined
- *           return hashPassword(inputValue)
- *         }
+ * Post: list<Lists.Post.TypeInfo>({
+ *   fields: { title: text() },
+ *   hooks: {
+ *     resolveInput: async ({ operation, resolvedData, item }) => {
+ *       if (operation === 'create') {
+ *         // resolvedData: Prisma.PostCreateInput
+ *         // item: undefined
+ *       } else {
+ *         // resolvedData: Prisma.PostUpdateInput
+ *         // item: Post
  *       }
- *     })
+ *       return resolvedData
+ *     }
  *   }
  * })
+ *
+ * // Or as a typed constant
+ * const Post: Lists.Post = list({
+ *   fields: { title: text() },
+ *   hooks: { ... }
+ * })
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function list<T = any>(config: {
+export function list<
+  TTypeInfo extends import('./types.js').TypeInfo = import('./types.js').TypeInfo,
+>(config: {
   fields: Record<string, FieldConfig>
   access?: {
-    operation?: OperationAccess<T>
+    operation?: OperationAccess<TTypeInfo['item']>
   }
-  hooks?: Hooks<T>
+  hooks?: Hooks<TTypeInfo['item'], TTypeInfo['inputs']['create'], TTypeInfo['inputs']['update']>
   mcp?: import('./types.js').ListMcpConfig
-}): ListConfig<T> {
+}): ListConfig<TTypeInfo['item'], TTypeInfo['inputs']['create'], TTypeInfo['inputs']['update']> {
   // At runtime, field configs are unchanged
-  // At type level, they're transformed to inject T as the item type
-  return config as ListConfig<T>
+  // At type level, they're transformed to inject TypeInfo types
+  return config as ListConfig<
+    TTypeInfo['item'],
+    TTypeInfo['inputs']['create'],
+    TTypeInfo['inputs']['update']
+  >
 }
 
 // Re-export all types
@@ -70,6 +96,7 @@ export type {
   PasswordField,
   SelectField,
   RelationshipField,
+  TypeInfo,
   OperationAccess,
   Hooks,
   FieldHooks,

package/src/config/plugin-engine.ts

@@ -257,6 +257,13 @@ export async function executePlugins(config: OpenSaasConfig): Promise<OpenSaasCo
     currentConfig._pluginData.__mcpTools = mcpToolsRegistry
   }
 
+  // Store plugin instances in config for runtime access
+  // This allows context creation to call plugin.runtime() functions
+  if (!currentConfig._plugins) {
+    currentConfig._plugins = []
+  }
+  currentConfig._plugins = sortedPlugins
+
   return currentConfig
 }
 

package/src/config/types.ts

@@ -345,6 +345,42 @@ export type FieldsWithItemType<TFields extends Record<string, FieldConfig>, TIte
   [K in keyof TFields]: WithItemType<TFields[K], TItem>
 }
 
+/**
+ * TypeInfo interface for list type information
+ * Provides a structured way to pass all type information for a list
+ * Inspired by Keystone's TypeInfo pattern
+ *
+ * @template TKey - The list key/name (e.g., 'Post', 'User')
+ * @template TItem - The output type (Prisma model type)
+ * @template TCreateInput - The Prisma create input type
+ * @template TUpdateInput - The Prisma update input type
+ *
+ * @example
+ * ```typescript
+ * type PostTypeInfo = {
+ *   key: 'Post'
+ *   item: Post
+ *   inputs: {
+ *     create: Prisma.PostCreateInput
+ *     update: Prisma.PostUpdateInput
+ *   }
+ * }
+ * ```
+ */
+export interface TypeInfo<
+  TKey extends string = string,
+  TItem = any, // eslint-disable-line @typescript-eslint/no-explicit-any
+  TCreateInput = any, // eslint-disable-line @typescript-eslint/no-explicit-any
+  TUpdateInput = any, // eslint-disable-line @typescript-eslint/no-explicit-any
+> {
+  key: TKey
+  item: TItem
+  inputs: {
+    create: TCreateInput
+    update: TUpdateInput
+  }
+}
+
 // Generic `any` default allows OperationAccess to work with any list item type
 // This is needed because the item type varies per list and is inferred from Prisma models
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -355,36 +391,74 @@ export type OperationAccess<T = any> = {
   delete?: AccessControl<T>
 }
 
-export type HookArgs<T = Record<string, unknown>> = {
+/**
+ * Hook arguments for resolveInput hook
+ * Uses discriminated union to provide proper types based on operation
+ * - create: resolvedData is CreateInput, item is undefined
+ * - update: resolvedData is UpdateInput, item is the existing record
+ */
+export type ResolveInputHookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> =
+  | {
+      operation: 'create'
+      resolvedData: TCreateInput
+      item: undefined
+      context: import('../access/types.js').AccessContext
+    }
+  | {
+      operation: 'update'
+      resolvedData: TUpdateInput
+      item: TOutput
+      context: import('../access/types.js').AccessContext
+    }
+
+/**
+ * Hook arguments for other hooks (validateInput, beforeOperation, afterOperation)
+ * These hooks receive the same structure regardless of operation
+ */
+export type HookArgs<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> = {
   operation: 'create' | 'update' | 'delete'
-  resolvedData?: Partial<T>
-  item?: T
+  resolvedData?: TCreateInput | TUpdateInput
+  item?: TOutput
   context: import('../access/types.js').AccessContext
 }
 
-export type Hooks<T = Record<string, unknown>> = {
-  resolveInput?: (args: HookArgs<T> & { operation: 'create' | 'update' }) => Promise<Partial<T>>
+export type Hooks<
+  TOutput = Record<string, unknown>,
+  TCreateInput = Record<string, unknown>,
+  TUpdateInput = Record<string, unknown>,
+> = {
+  resolveInput?: (
+    args: ResolveInputHookArgs<TOutput, TCreateInput, TUpdateInput>,
+  ) => Promise<TCreateInput | TUpdateInput>
   validateInput?: (
-    args: HookArgs<T> & {
+    args: HookArgs<TOutput, TCreateInput, TUpdateInput> & {
       operation: 'create' | 'update'
       addValidationError: (msg: string) => void
     },
   ) => Promise<void>
-  beforeOperation?: (args: HookArgs<T>) => Promise<void>
-  afterOperation?: (args: HookArgs<T>) => Promise<void>
+  beforeOperation?: (args: HookArgs<TOutput, TCreateInput, TUpdateInput>) => Promise<void>
+  afterOperation?: (args: HookArgs<TOutput, TCreateInput, TUpdateInput>) => Promise<void>
 }
 
 // Generic `any` default allows ListConfig to work with any list item type
 // This is needed because the item type varies per list and is inferred from Prisma models
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ListConfig<T = any> = {
+export type ListConfig<TOutput = any, TCreateInput = any, TUpdateInput = any> = {
   // Field configs are automatically transformed to inject the item type T
   // This enables proper typing in field hooks where item: TItem
-  fields: FieldsWithItemType<Record<string, FieldConfig>, T>
+  fields: FieldsWithItemType<Record<string, FieldConfig>, TOutput>
   access?: {
-    operation?: OperationAccess<T>
+    operation?: OperationAccess<TOutput>
   }
-  hooks?: Hooks<T>
+  hooks?: Hooks<TOutput, TCreateInput, TUpdateInput>
   /**
    * MCP server configuration for this list
    */
@@ -396,12 +470,37 @@ export type ListConfig<T = any> = {
  */
 export type DatabaseConfig = {
   provider: 'postgresql' | 'mysql' | 'sqlite'
-  url: string
   /**
-   * Optional factory function to create a custom Prisma client instance
-   * Receives the PrismaClient class and returns a configured instance
+   * Factory function to create a Prisma client instance with a database adapter
+   * Required in Prisma 7+ - receives the PrismaClient class and returns a configured instance
    *
-   * @example
+   * The connection URL is passed directly to the adapter, not to the config.
+   *
+   * @example SQLite with better-sqlite3
+   * ```typescript
+   * import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3'
+   * import Database from 'better-sqlite3'
+   *
+   * prismaClientConstructor: (PrismaClient) => {
+   *   const db = new Database(process.env.DATABASE_URL || './dev.db')
+   *   const adapter = new PrismaBetterSQLite3(db)
+   *   return new PrismaClient({ adapter })
+   * }
+   * ```
+   *
+   * @example PostgreSQL with pg
+   * ```typescript
+   * import { PrismaPg } from '@prisma/adapter-pg'
+   * import pg from 'pg'
+   *
+   * prismaClientConstructor: (PrismaClient) => {
+   *   const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
+   *   const adapter = new PrismaPg(pool)
+   *   return new PrismaClient({ adapter })
+   * }
+   * ```
+   *
+   * @example Neon serverless (PostgreSQL)
    * ```typescript
    * import { PrismaNeon } from '@prisma/adapter-neon'
    * import { neonConfig } from '@neondatabase/serverless'
@@ -419,7 +518,7 @@ export type DatabaseConfig = {
   // Uses `any` for maximum flexibility with Prisma client constructors and adapters
   // Different database adapters have varying type signatures that are hard to unify
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  prismaClientConstructor?: (PrismaClientClass: any) => any
+  prismaClientConstructor: (PrismaClientClass: any) => any
 }
 
 /**
@@ -846,12 +945,38 @@ export type Plugin = {
    * Return value is stored in context.plugins[pluginName]
    */
   runtime?: (context: import('../access/types.js').AccessContext) => unknown
+
+  /**
+   * Optional: Type metadata for runtime services
+   * Enables type-safe code generation for context.plugins
+   *
+   * @example
+   * ```typescript
+   * {
+   *   import: "import type { AuthRuntimeServices } from '@opensaas/stack-auth/runtime'",
+   *   typeName: "AuthRuntimeServices"
+   * }
+   * ```
+   */
+  runtimeServiceTypes?: {
+    /**
+     * Import statement to include in generated types file
+     * Must be a complete import statement with 'import type' and quotes
+     */
+    import: string
+    /**
+     * TypeScript type name to use in PluginServices interface
+     * Should match the exported type from the import
+     */
+    typeName: string
+  }
 }
 
 /**
  * Main configuration type
+ * Using interface instead of type to allow module augmentation
  */
-export type OpenSaasConfig = {
+export interface OpenSaasConfig {
   db: DatabaseConfig
   lists: Record<string, ListConfig>
   session?: SessionConfig
@@ -881,4 +1006,10 @@ export type OpenSaasConfig = {
    * @internal
    */
   _pluginData?: Record<string, unknown>
+  /**
+   * Sorted plugin instances (stored after plugin execution)
+   * Used at runtime to call plugin.runtime() functions
+   * @internal
+   */
+  _plugins?: Plugin[]
 }