@opensaas/stack-core 0.1.0 → 0.1.2

package/src/config/types.ts

@@ -277,6 +277,18 @@ export type RelationshipField = BaseFieldConfig<string | string[], string | stri
   }
 }
 
+export type JsonField = BaseFieldConfig<unknown, unknown> & {
+  type: 'json'
+  validation?: {
+    isRequired?: boolean
+  }
+  ui?: {
+    placeholder?: string
+    rows?: number
+    formatted?: boolean
+  }
+}
+
 export type FieldConfig =
   | TextField
   | IntegerField
@@ -285,6 +297,7 @@ export type FieldConfig =
   | PasswordField
   | SelectField
   | RelationshipField
+  | JsonField
   | BaseFieldConfig // Allow any field extending BaseFieldConfig (for third-party fields)
 
 /**
@@ -351,6 +364,10 @@ export type ListConfig<T = any> = {
     operation?: OperationAccess<T>
   }
   hooks?: Hooks<T>
+  /**
+   * MCP server configuration for this list
+   */
+  mcp?: ListMcpConfig
 }
 
 /**
@@ -462,6 +479,226 @@ export type UIConfig = {
   theme?: ThemeConfig
 }
 
+/**
+ * MCP (Model Context Protocol) configuration
+ */
+
+/**
+ * Configuration for which CRUD tools to enable for a list
+ */
+export type McpToolsConfig = {
+  /**
+   * Enable read/query tool
+   * @default true
+   */
+  read?: boolean
+  /**
+   * Enable create tool
+   * @default true
+   */
+  create?: boolean
+  /**
+   * Enable update tool
+   * @default true
+   */
+  update?: boolean
+  /**
+   * Enable delete tool
+   * @default true
+   */
+  delete?: boolean
+}
+
+/**
+ * Custom MCP tool definition
+ * Allows developers to add custom tools for specific lists
+ */
+export type McpCustomTool = {
+  /**
+   * Unique name for the tool
+   */
+  name: string
+  /**
+   * Description of what the tool does
+   */
+  description: string
+  /**
+   * Input schema (Zod schema)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputSchema: any
+  /**
+   * Handler function that executes the tool
+   */
+  handler: (args: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input: any
+    context: import('../access/types.js').AccessContext
+  }) => Promise<unknown>
+}
+
+/**
+ * List-level MCP configuration
+ */
+export type ListMcpConfig = {
+  /**
+   * Enable MCP tools for this list
+   * @default true
+   */
+  enabled?: boolean
+  /**
+   * Configure which CRUD tools to enable
+   */
+  tools?: McpToolsConfig
+  /**
+   * Custom tools specific to this list
+   */
+  customTools?: McpCustomTool[]
+}
+
+/**
+ * Better Auth OAuth configuration for MCP
+ */
+export type McpAuthConfig = {
+  /**
+   * Authentication type - currently only Better Auth is supported
+   */
+  type: 'better-auth'
+  /**
+   * Path to login page for OAuth flow
+   */
+  loginPage: string
+  /**
+   * OAuth scopes to request
+   * @default ["openid", "profile", "email"]
+   */
+  scopes?: string[]
+  /**
+   * Optional OIDC configuration
+   */
+  oidcConfig?: {
+    /**
+     * Code expiration time in seconds
+     * @default 600
+     */
+    codeExpiresIn?: number
+    /**
+     * Access token expiration time in seconds
+     * @default 3600
+     */
+    accessTokenExpiresIn?: number
+    /**
+     * Refresh token expiration time in seconds
+     * @default 604800
+     */
+    refreshTokenExpiresIn?: number
+    /**
+     * Default scope for OAuth requests
+     * @default "openid"
+     */
+    defaultScope?: string
+    /**
+     * Additional scopes to support
+     */
+    scopes?: string[]
+  }
+}
+
+/**
+ * Global MCP server configuration
+ */
+export type McpConfig = {
+  /**
+   * Enable MCP server globally
+   * @default false
+   */
+  enabled?: boolean
+  /**
+   * Base path for MCP API routes
+   * @default "/api/mcp"
+   */
+  basePath?: string
+  /**
+   * Authentication configuration
+   * Required when MCP is enabled
+   */
+  auth?: McpAuthConfig
+  /**
+   * Default tool configuration for all lists
+   * Can be overridden per-list
+   */
+  defaultTools?: McpToolsConfig
+  /**
+   * Resource identifier for OAuth protected resource metadata
+   * @default "https://yourdomain.com"
+   */
+  resource?: string
+}
+
+/**
+ * Storage configuration for file uploads
+ * Maps storage provider names to their configurations
+ *
+ * @example
+ * ```typescript
+ * storage: {
+ *   avatars: s3Storage({ bucket: 'my-avatars', region: 'us-east-1' }),
+ *   documents: localStorage({ uploadDir: './uploads', serveUrl: '/api/files' })
+ * }
+ * ```
+ */
+/**
+ * File metadata stored in the database (as JSON)
+ * Used by file upload fields to track uploaded files
+ */
+export interface FileMetadata {
+  /** Generated filename in storage */
+  filename: string
+  /** Original filename from upload */
+  originalFilename: string
+  /** Public URL to access the file */
+  url: string
+  /** MIME type */
+  mimeType: string
+  /** File size in bytes */
+  size: number
+  /** Upload timestamp */
+  uploadedAt: string
+  /** Storage provider name */
+  storageProvider: string
+  /** Additional provider-specific metadata */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Image-specific metadata (extends FileMetadata)
+ * Includes dimensions and optional transformations
+ */
+export interface ImageMetadata extends FileMetadata {
+  /** Image width in pixels */
+  width: number
+  /** Image height in pixels */
+  height: number
+  /** Generated image transformations/variants */
+  transformations?: Record<string, ImageTransformationResult>
+}
+
+/**
+ * Result of an image transformation
+ */
+export interface ImageTransformationResult {
+  /** URL to the transformed image */
+  url: string
+  /** Width in pixels */
+  width: number
+  /** Height in pixels */
+  height: number
+  /** File size in bytes */
+  size: number
+}
+
+export type StorageConfig = Record<string, { type: string; [key: string]: unknown }>
+
 /**
  * Main configuration type
  */
@@ -470,6 +707,15 @@ export type OpenSaasConfig = {
   lists: Record<string, ListConfig>
   session?: SessionConfig
   ui?: UIConfig
+  /**
+   * MCP (Model Context Protocol) server configuration
+   */
+  mcp?: McpConfig
+  /**
+   * Storage configuration for file/image uploads
+   * Maps named storage providers to their configurations
+   */
+  storage?: StorageConfig
   /**
    * Path where OpenSaas generates files (context, types, patched Prisma client)
    * @default ".opensaas"

package/src/context/index.ts

@@ -1,5 +1,5 @@
 import type { OpenSaasConfig, ListConfig } from '../config/types.js'
-import type { Session, AccessContext, AccessControlledDB } from '../access/index.js'
+import type { Session, AccessContext, AccessControlledDB, StorageUtils } from '../access/index.js'
 import {
   checkAccess,
   mergeFilters,
@@ -126,44 +126,6 @@ async function executeFieldAfterOperationHooks(
   }
 }
 
-/**
- * Execute field-level resolveOutput hooks
- * Allows fields to transform their output values after database read
- */
-function executeFieldResolveOutputHooks(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  item: Record<string, any> | null,
-  fields: Record<string, FieldConfig>,
-  context: AccessContext,
-  listKey: string,
-): Record<string, unknown> | null {
-  if (!item) return null
-
-  const result = { ...item }
-
-  for (const [fieldName, fieldConfig] of Object.entries(fields)) {
-    // Skip if field not in result
-    if (!(fieldName in result)) continue
-
-    // Skip if no hooks defined
-    if (!fieldConfig.hooks?.resolveOutput) continue
-
-    // Execute field hook
-    // Type assertion is safe here because hooks are typed correctly in field definitions
-    const transformedValue = fieldConfig.hooks.resolveOutput({
-      value: result[fieldName],
-      operation: 'query',
-      fieldName,
-      listKey,
-      item,
-      context,
-    })
-
-    result[fieldName] = transformedValue
-  }
-
-  return result
-}
 export type ServerActionProps =
   | { listKey: string; action: 'create'; data: Record<string, unknown> }
   | { listKey: string; action: 'update'; id: string; data: Record<string, unknown> }
@@ -174,6 +136,7 @@ export type ServerActionProps =
  * @param config - OpenSaas configuration
  * @param prisma - Your Prisma client instance (pass as generic for type safety)
  * @param session - Current session object (or null if not authenticated)
+ * @param storage - Optional storage utilities (uploadFile, uploadImage, deleteFile, deleteImage)
  */
 export function getContext<
   TConfig extends OpenSaasConfig,
@@ -182,10 +145,12 @@ export function getContext<
   config: TConfig,
   prisma: TPrisma,
   session: Session,
+  storage?: StorageUtils,
 ): {
   db: AccessControlledDB<TPrisma>
   session: Session
   prisma: TPrisma
+  storage: StorageUtils
   serverAction: (props: ServerActionProps) => Promise<unknown>
 } {
   // Initialize db object - will be populated with access-controlled operations
@@ -193,10 +158,33 @@ export function getContext<
   const db: Record<string, unknown> = {}
 
   // Create context with db reference (will be populated below)
+  // Storage utilities can be provided via parameter or use default stubs
   const context: AccessContext<TPrisma> = {
     session,
     prisma: prisma as TPrisma,
     db: db as AccessControlledDB<TPrisma>,
+    storage: storage ?? {
+      uploadFile: async () => {
+        throw new Error(
+          'No storage providers configured. Add storage providers to your opensaas.config.ts',
+        )
+      },
+      uploadImage: async () => {
+        throw new Error(
+          'No storage providers configured. Add storage providers to your opensaas.config.ts',
+        )
+      },
+      deleteFile: async () => {
+        throw new Error(
+          'No storage providers configured. Add storage providers to your opensaas.config.ts',
+        )
+      },
+      deleteImage: async () => {
+        throw new Error(
+          'No storage providers configured. Add storage providers to your opensaas.config.ts',
+        )
+      },
+    },
   }
 
   // Create access-controlled operations for each list
@@ -242,6 +230,7 @@ export function getContext<
     db: db as AccessControlledDB<TPrisma>,
     session,
     prisma,
+    storage: context.storage,
     serverAction,
   }
 }
@@ -300,7 +289,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       return null
     }
 
-    // Filter readable fields (now only handles field-level access, not array filtering)
+    // Filter readable fields and apply resolveOutput hooks (including nested relationships)
     const filtered = await filterReadableFields(
       item,
       listConfig.fields,
@@ -309,14 +298,13 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
         context,
       },
       config,
+      0,
+      listName,
     )
 
-    // Execute field resolveOutput hooks (e.g., wrap password with HashedPassword)
-    const resolved = executeFieldResolveOutputHooks(filtered, listConfig.fields, context, listName)
-
     // Execute field afterOperation hooks (side effects only)
     await executeFieldAfterOperationHooks(
-      resolved,
+      filtered,
       undefined,
       listConfig.fields,
       'query',
@@ -324,7 +312,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       listName,
     )
 
-    return resolved
+    return filtered
   }
 }
 
@@ -385,7 +373,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
       include,
     })
 
-    // Filter readable fields for each item (now only handles field-level access)
+    // Filter readable fields for each item and apply resolveOutput hooks (including nested relationships)
     const filtered = await Promise.all(
       items.map((item: Record<string, unknown>) =>
         filterReadableFields(
@@ -396,18 +384,15 @@ function createFindMany<TPrisma extends PrismaClientLike>(
             context,
           },
           config,
+          0,
+          listName,
         ),
       ),
     )
 
-    // Execute field resolveOutput hooks for each item
-    const resolved = filtered.map((item) =>
-      executeFieldResolveOutputHooks(item, listConfig.fields, context, listName),
-    )
-
     // Execute field afterOperation hooks for each item (side effects only)
     await Promise.all(
-      resolved.map((item) =>
+      filtered.map((item) =>
         executeFieldAfterOperationHooks(
           item,
           undefined,
@@ -419,7 +404,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
       ),
     )
 
-    return resolved
+    return filtered
   }
 }
 
@@ -523,7 +508,7 @@ function createCreate<TPrisma extends PrismaClientLike>(
       listName,
     )
 
-    // 11. Filter readable fields
+    // 11. Filter readable fields and apply resolveOutput hooks (including nested relationships)
     const filtered = await filterReadableFields(
       item,
       listConfig.fields,
@@ -532,12 +517,11 @@ function createCreate<TPrisma extends PrismaClientLike>(
         context,
       },
       config,
+      0,
+      listName,
     )
 
-    // 12. Execute field resolveOutput hooks (e.g., wrap password with HashedPassword)
-    const resolved = executeFieldResolveOutputHooks(filtered, listConfig.fields, context, listName)
-
-    return resolved
+    return filtered
   }
 }
 
@@ -675,7 +659,7 @@ function createUpdate<TPrisma extends PrismaClientLike>(
       listName,
     )
 
-    // 12. Filter readable fields
+    // 12. Filter readable fields and apply resolveOutput hooks (including nested relationships)
     const filtered = await filterReadableFields(
       updated,
       listConfig.fields,
@@ -684,12 +668,11 @@ function createUpdate<TPrisma extends PrismaClientLike>(
         context,
       },
       config,
+      0,
+      listName,
     )
 
-    // 13. Execute field resolveOutput hooks (e.g., wrap password with HashedPassword)
-    const resolved = executeFieldResolveOutputHooks(filtered, listConfig.fields, context, listName)
-
-    return resolved
+    return filtered
   }
 }
 

package/src/context/nested-operations.ts

@@ -9,6 +9,45 @@ import {
 } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
 
+/**
+ * Execute field-level resolveInput hooks
+ * Allows fields to transform their input values before database write
+ */
+async function executeFieldResolveInputHooks(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data: Record<string, any>,
+  fields: Record<string, FieldConfig>,
+  operation: 'create' | 'update',
+  context: AccessContext,
+  listKey: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  item?: any,
+): Promise<Record<string, unknown>> {
+  const result = { ...data }
+
+  for (const [fieldName, fieldConfig] of Object.entries(fields)) {
+    // Skip if field not in data
+    if (!(fieldName in result)) continue
+
+    // Skip if no hooks defined
+    if (!fieldConfig.hooks?.resolveInput) continue
+
+    // Execute field hook
+    const transformedValue = await fieldConfig.hooks.resolveInput({
+      inputValue: result[fieldName],
+      operation,
+      fieldName,
+      listKey,
+      item,
+      context,
+    })
+
+    result[fieldName] = transformedValue
+  }
+
+  return result
+}
+
 /**
  * Check if a field config is a relationship field
  */
@@ -41,13 +80,32 @@ async function processNestedCreate(
         throw new Error('Access denied: Cannot create related item')
       }
 
-      // 2. Execute resolveInput hook
+      // 2. Execute list-level resolveInput hook
       let resolvedData = await executeResolveInput(relatedListConfig.hooks, {
         operation: 'create',
         resolvedData: item,
         context,
       })
 
+      // 2.5. Execute field-level resolveInput hooks
+      // We need to get the list name for this related config
+      // Since we don't have it directly, we'll need to find it from the config
+      let relatedListName = ''
+      for (const [listKey, listCfg] of Object.entries(config.lists)) {
+        if (listCfg === relatedListConfig) {
+          relatedListName = listKey
+          break
+        }
+      }
+
+      resolvedData = await executeFieldResolveInputHooks(
+        resolvedData,
+        relatedListConfig.fields,
+        'create',
+        context,
+        relatedListName,
+      )
+
       // 3. Execute validateInput hook
       await executeValidateInput(relatedListConfig.hooks, {
         operation: 'create',
@@ -185,7 +243,7 @@ async function processNestedUpdate(
         throw new Error('Access denied: Cannot update related item')
       }
 
-      // Execute resolveInput hook
+      // Execute list-level resolveInput hook
       const updateData = (update as Record<string, unknown>).data as Record<string, unknown>
       let resolvedData = await executeResolveInput(relatedListConfig.hooks, {
         operation: 'update',
@@ -194,6 +252,16 @@ async function processNestedUpdate(
         context,
       })
 
+      // Execute field-level resolveInput hooks
+      resolvedData = await executeFieldResolveInputHooks(
+        resolvedData,
+        relatedListConfig.fields,
+        'update',
+        context,
+        relatedListName,
+        item,
+      )
+
       // Execute validateInput hook
       await executeValidateInput(relatedListConfig.hooks, {
         operation: 'update',

package/src/fields/index.ts

@@ -7,6 +7,7 @@ import type {
   PasswordField,
   SelectField,
   RelationshipField,
+  JsonField,
 } from '../config/types.js'
 import { hashPassword, isHashedPassword, HashedPassword } from '../utils/password.js'
 
@@ -436,3 +437,87 @@ export function relationship(options: Omit<RelationshipField, 'type'>): Relation
     ...options,
   }
 }
+
+/**
+ * JSON field for storing arbitrary JSON data
+ *
+ * **Features:**
+ * - Stores any valid JSON data (objects, arrays, primitives)
+ * - Stored as JSON type in database (PostgreSQL/MySQL) or TEXT in SQLite
+ * - Optional validation for required fields
+ * - UI options for formatting and display
+ *
+ * **Usage Example:**
+ * ```typescript
+ * // In opensaas.config.ts
+ * fields: {
+ *   metadata: json({
+ *     validation: { isRequired: false },
+ *     ui: {
+ *       placeholder: 'Enter JSON data...',
+ *       rows: 10,
+ *       formatted: true
+ *     }
+ *   }),
+ *   settings: json({
+ *     validation: { isRequired: true }
+ *   })
+ * }
+ *
+ * // Creating with JSON data
+ * const item = await context.db.item.create({
+ *   data: {
+ *     metadata: { key: 'value', nested: { data: [1, 2, 3] } }
+ *   }
+ * })
+ *
+ * // Querying returns parsed JSON
+ * const item = await context.db.item.findUnique({
+ *   where: { id: '...' }
+ * })
+ * console.log(item.metadata.key) // 'value'
+ * ```
+ *
+ * @param options - Field configuration options
+ * @returns JSON field configuration
+ */
+export function json(options?: Omit<JsonField, 'type'>): JsonField {
+  return {
+    type: 'json',
+    ...options,
+    getZodSchema: (fieldName: string, operation: 'create' | 'update') => {
+      const validation = options?.validation
+      const isRequired = validation?.isRequired
+
+      // Accept any valid JSON value
+      const baseSchema = z.unknown()
+
+      if (isRequired && operation === 'create') {
+        // Required in create mode: value must be provided
+        return baseSchema
+      } else if (isRequired && operation === 'update') {
+        // Required in update mode: can be undefined for partial updates
+        return z.union([baseSchema, z.undefined()])
+      } else {
+        // Not required: can be undefined
+        return baseSchema.optional()
+      }
+    },
+    getPrismaType: () => {
+      const isRequired = options?.validation?.isRequired
+
+      return {
+        type: 'Json',
+        modifiers: isRequired ? undefined : '?',
+      }
+    },
+    getTypeScriptType: () => {
+      const isRequired = options?.validation?.isRequired
+
+      return {
+        type: 'unknown',
+        optional: !isRequired,
+      }
+    },
+  }
+}