outlet-orm 6.0.0 → 7.0.0

package/types/index.d.ts

@@ -153,6 +153,20 @@ declare module 'outlet-orm' {
     to: number;
   }
 
+  /** Observer interface for model lifecycle events */
+  export interface ModelObserver<T extends Model = Model> {
+    creating?(model: T): boolean | void | Promise<boolean | void>;
+    created?(model: T): void | Promise<void>;
+    updating?(model: T): boolean | void | Promise<boolean | void>;
+    updated?(model: T): void | Promise<void>;
+    saving?(model: T): boolean | void | Promise<boolean | void>;
+    saved?(model: T): void | Promise<void>;
+    deleting?(model: T): boolean | void | Promise<boolean | void>;
+    deleted?(model: T): void | Promise<void>;
+    restoring?(model: T): boolean | void | Promise<boolean | void>;
+    restored?(model: T): void | Promise<void>;
+  }
+
   export class QueryBuilder<T extends Model> {
     constructor(model: typeof Model);
 
@@ -204,6 +218,12 @@ declare module 'outlet-orm' {
     get(): Promise<T[]>;
     first(): Promise<T | null>;
     firstOrFail(): Promise<T>;
+    /** Get the first record matching current wheres or create a new one */
+    firstOrCreate(values?: Record<string, any>): Promise<T>;
+    /** Get the first record matching current wheres or return a new unsaved instance */
+    firstOrNew(values?: Record<string, any>): Promise<T>;
+    /** Find a record matching current wheres and update it, or create a new one */
+    updateOrCreate(values?: Record<string, any>): Promise<T>;
     paginate(page?: number, perPage?: number): Promise<PaginationResult<T>>;
     count(): Promise<number>;
     exists(): Promise<boolean>;
@@ -214,6 +234,8 @@ declare module 'outlet-orm' {
     delete(): Promise<any>;
     increment(column: string, amount?: number): Promise<any>;
     decrement(column: string, amount?: number): Promise<any>;
+    /** Lazily iterate over matching records using an async generator */
+    cursor(chunkSize?: number): AsyncGenerator<T, void, unknown>;
 
     clone(): QueryBuilder<T>;
   }
@@ -344,6 +366,25 @@ declare module 'outlet-orm' {
     static whereNull<T extends Model>(this: new () => T, column: string): QueryBuilder<T>;
     static whereNotNull<T extends Model>(this: new () => T, column: string): QueryBuilder<T>;
     static count(): Promise<number>;
+
+    // Convenience query methods
+    /** Find the first record matching conditions or create a new one */
+    static firstOrCreate<T extends Model>(this: new () => T, conditions: Record<string, any>, values?: Record<string, any>): Promise<T>;
+    /** Find the first record matching conditions or return a new unsaved instance */
+    static firstOrNew<T extends Model>(this: new () => T, conditions: Record<string, any>, values?: Record<string, any>): Promise<T>;
+    /** Find a record matching conditions and update it, or create a new one */
+    static updateOrCreate<T extends Model>(this: new () => T, conditions: Record<string, any>, values?: Record<string, any>): Promise<T>;
+    /** Insert or update multiple records in bulk (ON CONFLICT / ON DUPLICATE KEY) */
+    static upsert(rows: Record<string, any>[], uniqueBy: string | string[], update?: string[]): Promise<any>;
+
+    // Observer
+    /** Register an observer class that listens to model lifecycle events */
+    static observe(observer: ModelObserver | (new () => ModelObserver)): void;
+
+    // Cursor / Stream
+    /** Lazily iterate over all matching records using an async generator */
+    static cursor<T extends Model>(this: new () => T, chunkSize?: number): AsyncGenerator<T, void, unknown>;
+
     static with<T extends Model>(this: new () => T, ...relations: string[] | [Record<string, (qb: QueryBuilder<any>) => void> | string[]]): QueryBuilder<T>;
     /** Include hidden attributes in query results */
     static withHidden<T extends Model>(this: new () => T): QueryBuilder<T>;
@@ -896,4 +937,110 @@ declare module 'outlet-orm' {
     on(event: 'serverEvent', listener: (payload: Record<string, any>) => void): this;
     on(event: string,        listener: (...args: any[]) => void): this;
   }
+
+  // ==================== AI Integration (v7.0.0) ====================
+
+  /** MCP tool definition */
+  export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+      type: 'object';
+      properties: Record<string, any>;
+      required: string[];
+    };
+  }
+
+  /** MCP server options */
+  export interface MCPServerOptions {
+    /** DatabaseConnection instance (optional, auto-loaded from project) */
+    connection?: DatabaseConnection;
+    /** Project root directory (default: process.cwd()) */
+    projectDir?: string;
+    /** Enable AI safety guardrails (default: true) */
+    safetyGuardrails?: boolean;
+  }
+
+  /** JSON-RPC 2.0 message */
+  export interface JSONRPCMessage {
+    jsonrpc: '2.0';
+    id?: number | string;
+    method?: string;
+    params?: Record<string, any>;
+    result?: any;
+    error?: { code: number; message: string };
+  }
+
+  /** MCP Server — exposes ORM capabilities to AI agents via JSON-RPC 2.0 */
+  export class MCPServer {
+    constructor(options?: MCPServerOptions);
+
+    /** Project root directory */
+    projectDir: string;
+    /** Whether safety guardrails are enabled */
+    safetyGuardrails: boolean;
+
+    /** Start the MCP server on stdio */
+    start(): void;
+    /** Get a programmatic handler function (for testing/embedding) */
+    handler(): (message: JSONRPCMessage) => Promise<JSONRPCMessage | null>;
+    /** Graceful shutdown */
+    close(): Promise<void>;
+
+    on(event: 'started',     listener: () => void): this;
+    on(event: 'initialized', listener: () => void): this;
+    on(event: 'response',    listener: (response: JSONRPCMessage) => void): this;
+    on(event: 'close',       listener: () => void): this;
+    on(event: string,        listener: (...args: any[]) => void): this;
+  }
+
+  /** Agent detection result */
+  export interface AgentDetectionResult {
+    /** Whether an AI agent was detected */
+    detected: boolean;
+    /** Name of the detected agent (null if not detected) */
+    agentName: string | null;
+  }
+
+  /** Destructive action validation result */
+  export interface DestructiveActionResult {
+    /** Whether the action is allowed */
+    allowed: boolean;
+    /** Message explaining why action was blocked (empty if allowed) */
+    message: string;
+  }
+
+  /** AI Safety Guardrails — detects AI agents and protects against destructive operations */
+  export class AISafetyGuardrails {
+    /** Detect if the current process is invoked by an AI agent */
+    static detectAgent(): AgentDetectionResult;
+    /** Check if a CLI command is destructive */
+    static isDestructiveCommand(command: string): boolean;
+    /** Validate whether user consent is present for a destructive operation */
+    static validateDestructiveAction(command: string, flags?: { consent?: string; yes?: boolean; force?: boolean }): DestructiveActionResult;
+    /** The environment variable name for AI consent */
+    static readonly CONSENT_ENV_VAR: string;
+  }
+
+  /** Prompt blueprint — parsed from a natural language description */
+  export interface PromptBlueprint {
+    /** Detected domain (e.g. 'blog', 'e-commerce', 'saas') */
+    domain: string;
+    /** Table definitions */
+    tables: Record<string, { columns: string[]; pivot?: boolean }>;
+    /** Match confidence score */
+    score: number;
+  }
+
+  /** Prompt Generator — generates projects from natural language descriptions */
+  export class PromptGenerator {
+    /** Parse a natural language prompt into a project blueprint */
+    static parse(prompt: string): PromptBlueprint;
+    /** Generate model files from a blueprint */
+    static generateModels(blueprint: PromptBlueprint, outputDir: string): string[];
+    /** Generate migration files from a blueprint */
+    static generateMigrations(blueprint: PromptBlueprint, outputDir: string): string[];
+    /** Generate a seeder file from a blueprint */
+    static generateSeeder(blueprint: PromptBlueprint, outputDir: string): string;
+  }
 }