npm - @tamayrp14/fire-api - Versions diffs - 0.0.0-stage → 1.0.1 - Mend

@tamayrp14/fire-api 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (99) hide show

package/README.md +276 -2
package/bin/fire.js +139 -0
package/bin/fire.mjs +670 -0
package/bun.lock +20 -0
package/docs/GETTING_STARTED.md +150 -0
package/docs/LAUNCH_KIT.md +236 -0
package/docs/superpowers/plans/2026-11-14-fire-api-framework.md +144 -0
package/docs/superpowers/specs/fire-api-design-spec.md +111 -0
package/examples/basic-api/index.ts +177 -0
package/package.json +68 -4
package/src/ai/mcp.ts +140 -0
package/src/auth/auth.ts +110 -0
package/src/auth/crypto.ts +70 -0
package/src/auth/jwt.ts +105 -0
package/src/cache/cache.ts +72 -0
package/src/cli/bench.ts +118 -0
package/src/cli/compile.ts +29 -0
package/src/cli/create-app.ts +284 -0
package/src/cli/docker.ts +51 -0
package/src/cli/generator.ts +75 -0
package/src/cli/routes.ts +76 -0
package/src/client.ts +120 -0
package/src/compat/express.ts +139 -0
package/src/core/app.ts +723 -0
package/src/core/context.ts +218 -0
package/src/core/error.ts +42 -0
package/src/core/router.ts +262 -0
package/src/db/db-interface.ts +9 -0
package/src/db/hub.ts +256 -0
package/src/db/memory-adapter.ts +202 -0
package/src/db/migrator.ts +100 -0
package/src/db/sqlite-adapter.ts +58 -0
package/src/docs/collection.ts +57 -0
package/src/docs/scalar-ui.ts +25 -0
package/src/events/event-bus.ts +61 -0
package/src/index.ts +37 -0
package/src/jobs/cron.ts +77 -0
package/src/jobs/queue.ts +108 -0
package/src/logging/logger.ts +66 -0
package/src/metrics/metrics.ts +66 -0
package/src/modules/product/product.route.ts +36 -0
package/src/modules/product/product.schema.ts +10 -0
package/src/schema/mock.ts +60 -0
package/src/schema/openapi.ts +101 -0
package/src/schema/schema.ts +519 -0
package/src/schema/validator.ts +5 -0
package/src/shield/compress.ts +61 -0
package/src/shield/cors.ts +94 -0
package/src/shield/headers.ts +55 -0
package/src/shield/idempotency.ts +76 -0
package/src/shield/rate-limiter.ts +81 -0
package/src/shield/sanitizer.ts +23 -0
package/src/shield/webhook.ts +101 -0
package/src/static/serve.ts +51 -0
package/src/storage/storage.ts +176 -0
package/src/stream/sse.ts +89 -0
package/src/studio/studio.ts +221 -0
package/src/types.ts +241 -0
package/src/ws/ws.ts +118 -0
package/test/ai-mcp.test.ts +61 -0
package/test/auth.test.ts +108 -0
package/test/bench.test.ts +31 -0
package/test/cache.test.ts +36 -0
package/test/cli-create.test.ts +64 -0
package/test/client.test.ts +54 -0
package/test/collection-export.test.ts +52 -0
package/test/compat.test.ts +48 -0
package/test/compress.test.ts +48 -0
package/test/context.test.ts +48 -0
package/test/db.test.ts +62 -0
package/test/docker.test.ts +28 -0
package/test/events.test.ts +62 -0
package/test/file-upload.test.ts +116 -0
package/test/hooks.test.ts +77 -0
package/test/idempotency.test.ts +65 -0
package/test/integration.test.ts +111 -0
package/test/jobs.test.ts +60 -0
package/test/metrics.test.ts +40 -0
package/test/mock.test.ts +33 -0
package/test/multi-tenant.test.ts +80 -0
package/test/observability.test.ts +95 -0
package/test/openapi.test.ts +41 -0
package/test/orm-relations.test.ts +85 -0
package/test/orm-shortcuts.test.ts +52 -0
package/test/rbac.test.ts +85 -0
package/test/router-fastpath.test.ts +42 -0
package/test/router.test.ts +84 -0
package/test/schema.test.ts +49 -0
package/test/seeder-migrator.test.ts +78 -0
package/test/shield.test.ts +55 -0
package/test/shorthand-dx.test.ts +31 -0
package/test/sse.test.ts +43 -0
package/test/static-serve.test.ts +53 -0
package/test/storage.test.ts +31 -0
package/test/studio.test.ts +43 -0
package/test/tx.test.ts +92 -0
package/test/webhook.test.ts +113 -0
package/test/ws.test.ts +54 -0
package/tsconfig.json +19 -0

package/src/studio/studio.ts ADDED Viewed

@@ -0,0 +1,221 @@
+import { FireApp } from '../core/app';
+import { createRouter } from '../core/router';
+export interface StudioOptions {
+  path?: string;
+  title?: string;
+}
+export function renderStudioHTML(basePath = '/studio', title = 'FireStudio Dashboard'): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${title}</title>
+  <style>
+    :root {
+      --bg: #0f172a;
+      --card: #1e293b;
+      --border: #334155;
+      --primary: #f97316;
+      --primary-hover: #ea580c;
+      --text: #f8fafc;
+      --text-muted: #94a3b8;
+      --accent: #38bdf8;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+    body { background: var(--bg); color: var(--text); padding: 24px; }
+    header { display: flex; align-items: center; justify-content: space-between; padding-bottom: 20px; border-bottom: 1px solid var(--border); margin-bottom: 24px; }
+    .logo { font-size: 22px; font-weight: 800; display: flex; align-items: center; gap: 8px; color: var(--primary); }
+    .badge { background: #3b82f620; color: #60a5fa; font-size: 12px; padding: 4px 10px; border-radius: 999px; border: 1px solid #3b82f640; }
+    nav { display: flex; gap: 12px; margin-bottom: 24px; }
+    button.tab-btn { background: var(--card); border: 1px solid var(--border); color: var(--text-muted); padding: 8px 18px; border-radius: 8px; cursor: pointer; font-size: 14px; font-weight: 600; transition: all 0.2s; }
+    button.tab-btn.active, button.tab-btn:hover { background: var(--primary); color: white; border-color: var(--primary); }
+    .card { background: var(--card); border: 1px solid var(--border); border-radius: 12px; padding: 20px; margin-bottom: 24px; }
+    h2 { font-size: 18px; margin-bottom: 16px; color: var(--text); }
+    table { width: 100%; border-collapse: collapse; margin-top: 12px; }
+    th, td { text-align: left; padding: 12px; border-bottom: 1px solid var(--border); font-size: 14px; }
+    th { color: var(--text-muted); font-weight: 600; text-transform: uppercase; font-size: 12px; }
+    tr:hover { background: rgba(255, 255, 255, 0.02); }
+    pre { background: #090d16; padding: 12px; border-radius: 8px; overflow-x: auto; font-size: 13px; color: #a5f3fc; }
+    .table-pills { display: flex; gap: 8px; margin-bottom: 16px; flex-wrap: wrap; }
+    .table-pill { background: #334155; padding: 6px 14px; border-radius: 6px; cursor: pointer; font-size: 13px; border: 1px solid transparent; }
+    .table-pill.active { background: var(--accent); color: #0f172a; font-weight: 700; }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="logo">🔥 FireStudio <span>Engine</span></div>
+    <div class="badge">Live Connected</div>
+  </header>
+  <nav>
+    <button class="tab-btn active" onclick="switchTab('db')">🗄️ Database Explorer</button>
+    <button class="tab-btn" onclick="switchTab('routes')">⚡ Routes & Endpoints</button>
+  </nav>
+  <div id="tab-db" class="card">
+    <h2>Database Tables</h2>
+    <div id="tables-list" class="table-pills">Loading tables...</div>
+    <div id="table-content">
+      <p style="color: var(--text-muted)">Select a table above to view rows.</p>
+    </div>
+  </div>
+  <div id="tab-routes" class="card" style="display: none;">
+    <h2>Registered Routes</h2>
+    <div id="routes-content">Loading route definitions...</div>
+  </div>
+  <script>
+    const basePath = '${basePath}';
+    function switchTab(tab) {
+      document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
+      event.target.classList.add('active');
+      document.getElementById('tab-db').style.display = tab === 'db' ? 'block' : 'none';
+      document.getElementById('tab-routes').style.display = tab === 'routes' ? 'block' : 'none';
+      if (tab === 'routes') loadRoutes();
+    }
+    async function loadOverview() {
+      try {
+        const res = await fetch(basePath + '/api/overview');
+        const data = await res.json();
+        const pillsContainer = document.getElementById('tables-list');
+        pillsContainer.innerHTML = '';
+        if (data.tables.length === 0) {
+          pillsContainer.innerHTML = '<span style="color:var(--text-muted)">No tables found in database.</span>';
+          return;
+        }
+        data.tables.forEach((t, i) => {
+          const pill = document.createElement('div');
+          pill.className = 'table-pill ' + (i === 0 ? 'active' : '');
+          pill.innerText = t;
+          pill.onclick = () => {
+            document.querySelectorAll('.table-pill').forEach(p => p.classList.remove('active'));
+            pill.classList.add('active');
+            loadTableRows(t);
+          };
+          pillsContainer.appendChild(pill);
+        });
+        if (data.tables[0]) loadTableRows(data.tables[0]);
+      } catch (e) {
+        document.getElementById('tables-list').innerHTML = 'Error loading tables: ' + e.message;
+      }
+    }
+    async function loadTableRows(tableName) {
+      const container = document.getElementById('table-content');
+      container.innerHTML = '<p style="color: var(--text-muted)">Loading rows for <b>' + tableName + '</b>...</p>';
+      try {
+        const res = await fetch(basePath + '/api/tables/' + encodeURIComponent(tableName));
+        const rows = await res.json();
+        if (rows.length === 0) {
+          container.innerHTML = '<p style="color: var(--text-muted)">Table <b>' + tableName + '</b> is currently empty.</p>';
+          return;
+        }
+        const keys = Object.keys(rows[0]);
+        let html = '<table><thead><tr>' + keys.map(k => '<th>' + k + '</th>').join('') + '</tr></thead><tbody>';
+        rows.forEach(r => {
+          html += '<tr>' + keys.map(k => '<td>' + (typeof r[k] === 'object' ? JSON.stringify(r[k]) : r[k]) + '</td>').join('') + '</tr>';
+        });
+        html += '</tbody></table>';
+        container.innerHTML = html;
+      } catch (e) {
+        container.innerHTML = 'Error loading rows: ' + e.message;
+      }
+    }
+    async function loadRoutes() {
+      const container = document.getElementById('routes-content');
+      try {
+        const res = await fetch(basePath + '/api/overview');
+        const data = await res.json();
+        let html = '<table><thead><tr><th>Method</th><th>Path</th><th>Security</th></tr></thead><tbody>';
+        data.routes.forEach(r => {
+          html += '<tr><td><b style="color:var(--primary)">' + r.method + '</b></td><td>' + r.path + '</td><td>' + (r.security || 'None') + '</td></tr>';
+        });
+        html += '</tbody></table>';
+        container.innerHTML = html;
+      } catch (e) {
+        container.innerHTML = 'Error loading routes: ' + e.message;
+      }
+    }
+    loadOverview();
+  </script>
+</body>
+</html>`;
+}
+export function enableStudio(app: FireApp, options: StudioOptions = {}): void {
+  const basePath = options.path || '/studio';
+  const cleanBase = basePath.replace(/\/+$/, '');
+  const studioRouter = createRouter(cleanBase);
+  // 1. Studio Dashboard Web UI
+  studioRouter.get('/', {
+    handler: (ctx) => {
+      const html = renderStudioHTML(cleanBase, options.title);
+      return ctx.html(html);
+    },
+  });
+  // 2. Overview JSON API
+  studioRouter.get('/api/overview', {
+    handler: async (ctx) => {
+      // Introspect tables if in-memory database
+      let tables: string[] = [];
+      const dbStorage = (ctx.db as any).storage;
+      if (dbStorage instanceof Map) {
+        tables = Array.from(dbStorage.keys());
+      } else {
+        tables = ['users', 'products', 'logs'];
+      }
+      const routes = app.router.routesList.map((r) => ({
+        method: r.method,
+        path: r.path,
+        security: r.options.security ? JSON.stringify(r.options.security) : undefined,
+      }));
+      return ctx.ok({
+        status: 'online',
+        routesCount: routes.length,
+        tables,
+        routes,
+      });
+    },
+  });
+  // 3. Table Rows API
+  studioRouter.get('/api/tables/:name', {
+    handler: async (ctx) => {
+      const tableName = ctx.params.name;
+      const rows = await ctx.db.table(tableName).find();
+      return ctx.ok(rows);
+    },
+  });
+  // 4. Insert Row API
+  studioRouter.post('/api/tables/:name', {
+    handler: async (ctx) => {
+      const tableName = ctx.params.name;
+      const inserted = await ctx.db.table(tableName).insert(ctx.body || {});
+      return ctx.created(inserted);
+    },
+  });
+  // 5. Delete Row API
+  studioRouter.delete('/api/tables/:name/:id', {
+    handler: async (ctx) => {
+      const { name, id } = ctx.params;
+      const result = await ctx.db.table(name).where('id', id).delete();
+      return ctx.ok(result);
+    },
+  });
+  app.use(studioRouter);
+}

package/src/types.ts ADDED Viewed

@@ -0,0 +1,241 @@
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+export interface TableModel<T = any> extends Omit<QueryBuilder, 'find' | 'findOne' | 'findById' | 'insert' | 'update' | 'delete' | 'include'> {
+  find(filter?: Record<string, any>): Promise<T[]>;
+  findOne(filter?: Record<string, any>): Promise<T | null>;
+  findById(id: string | number): Promise<T | null>;
+  insert(data: Record<string, any> | Record<string, any>[]): Promise<T>;
+  update(idOrFilter: string | number | Record<string, any>, data?: Record<string, any>): Promise<T>;
+  delete(idOrFilter?: string | number | Record<string, any>): Promise<{ count: number }>;
+  include(relation: string | string[]): TableModel<T>;
+}
+export interface FireDatabase {
+  table(name: string): QueryBuilder;
+  raw<T = any>(sql: string, params?: any[]): Promise<T>;
+  transaction<T>(fn: (trx: FireDatabase) => Promise<T>): Promise<T>;
+  tx<T>(fn: (trx: FireDatabase) => Promise<T>): Promise<T>;
+  seed?(tableName: string, schema: any, count?: number): Promise<any[]>;
+  [table: string]: any;
+}
+export interface QueryBuilder {
+  find<T = any>(): Promise<T[]>;
+  findOne<T = any>(): Promise<T | null>;
+  findById<T = any>(id: string | number): Promise<T | null>;
+  where(field: string, operatorOrValue: any, value?: any): QueryBuilder;
+  limit(count: number): QueryBuilder;
+  offset(count: number): QueryBuilder;
+  orderBy(field: string, direction?: 'asc' | 'desc'): QueryBuilder;
+  include(relation: string | string[]): QueryBuilder;
+  insert<T = any>(data: Record<string, any> | Record<string, any>[]): Promise<T>;
+  update<T = any>(data: Record<string, any>): Promise<T>;
+  delete(): Promise<{ count: number }>;
+}
+export interface FireCacheManager {
+  get<T = any>(key: string): Promise<T | null>;
+  set(key: string, value: any, ttlSeconds?: number, tags?: string[]): Promise<void>;
+  invalidate(tag: string): Promise<void>;
+  clear(): Promise<void>;
+}
+export interface FireQueueJob<T = any> {
+  id: string;
+  name: string;
+  data: T;
+  attempts: number;
+  maxAttempts: number;
+  createdAt: number;
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+}
+export interface FireQueue {
+  dispatch<T = any>(name: string, data: T, options?: { maxAttempts?: number; delayMs?: number; retryDelayMs?: number }): Promise<FireQueueJob<T>>;
+  handle<T = any>(name: string, worker: (data: T, job: FireQueueJob<T>) => Promise<void> | void): void;
+}
+export interface FireStorage {
+  put(filePath: string, content: string | Uint8Array | ArrayBuffer, options?: { contentType?: string; access?: 'public' | 'private' }): Promise<{ path: string; url: string; size: number }>;
+  get(filePath: string): Promise<Uint8Array | null>;
+  getText(filePath: string): Promise<string | null>;
+  delete(filePath: string): Promise<boolean>;
+  exists(filePath: string): Promise<boolean>;
+  url(filePath: string): string;
+}
+export interface UploadedFile {
+  name: string;
+  size: number;
+  type: string;
+  bytes(): Promise<Uint8Array>;
+  text(): Promise<string>;
+  store(destinationDir?: string, options?: { fileName?: string }): Promise<{ path: string; url: string; size: number }>;
+}
+export interface FireContext<
+  TParams = Record<string, string>,
+  TQuery = Record<string, string | string[]>,
+  TBody = any,
+  TUser = any
+> {
+  req: Request;
+  params: TParams;
+  query: TQuery;
+  body: TBody;
+  files: Record<string, UploadedFile>;
+  user: TUser;
+  db: FireDatabase;
+  cache: FireCacheManager;
+  queue: FireQueue;
+  storage: FireStorage;
+  state: Record<string, any>;
+  rawBody: string;
+  requestId: string;
+  traceId?: string;
+  log: any;
+  tenant?: { id: string; [key: string]: any };
+  // Event Emitter
+  emit<T = any>(event: string, payload?: T): Promise<void>;
+  // Turnkey Webhook Verifier
+  webhook: {
+    verifyHMAC(options: {
+      secret: string;
+      header?: string;
+      signature?: string;
+      algorithm?: 'SHA-256' | 'SHA-1' | 'SHA-512';
+    }): Promise<boolean>;
+  };
+  // Streaming helpers
+  stream: {
+    sse(handler: (stream: { send(data: any, options?: { event?: string; id?: string; retry?: number }): Promise<void>; close(): void }) => Promise<void> | void): Response;
+  };
+  // Modern HTTP helpers
+  earlyHints(links: string[]): void;
+  // Response helpers
+  json<T = any>(data: T, status?: number, headers?: HeadersInit): Response;
+  ok<T = any>(data: T): Response;
+  created<T = any>(data: T): Response;
+  noContent(): Response;
+  badRequest(errors: any): Response;
+  unauthorized(message?: string): Response;
+  forbidden(message?: string): Response;
+  notFound(message?: string): Response;
+  internalError(message?: string): Response;
+  text(content: string, status?: number, headers?: HeadersInit): Response;
+  html(content: string, status?: number, headers?: HeadersInit): Response;
+}
+export type Handler<
+  TParams = any,
+  TQuery = any,
+  TBody = any,
+  TRes = any
+> = (ctx: FireContext<TParams, TQuery, TBody>) => Promise<Response | TRes> | Response | TRes;
+export type Middleware = (
+  ctx: FireContext,
+  next: () => Promise<Response>
+) => Promise<Response>;
+export interface RouteSchema {
+  params?: any;
+  query?: any;
+  body?: any;
+  response?: any;
+}
+export interface RouteAIMetadata {
+  description: string;
+  operationId?: string;
+  tags?: string[];
+}
+export interface RouteSecurityConfig {
+  auth?: 'bearer' | 'apiKey' | 'basic' | boolean;
+  rateLimit?: string | { max: number; window: string };
+  roles?: string[];
+}
+export interface RouteOptions<TParams = any, TQuery = any, TBody = any, TRes = any> {
+  schema?: RouteSchema;
+  security?: (string | RouteSecurityConfig)[];
+  cache?: { ttl: string | number; swr?: string | number; tags?: string[] };
+  idempotent?: boolean | { ttl?: number };
+  ai?: RouteAIMetadata;
+  roles?: string[];
+  can?: (user: any, ctx: FireContext) => boolean | Promise<boolean>;
+  middlewares?: Middleware[];
+  handler: Handler<TParams, TQuery, TBody, TRes>;
+}
+export interface RouteMatch {
+  handler: Handler;
+  routeOptions: RouteOptions;
+  params: Record<string, string>;
+  middlewares: Middleware[];
+}
+export interface FireSecurityOptions {
+  enabled?: boolean;
+  cors?: boolean | {
+    origin?: string | string[] | ((origin: string) => boolean);
+    methods?: string[];
+    allowedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+  };
+  rateLimit?: {
+    max: number;
+    window: string; // e.g. '1m', '15m', '1h'
+  };
+  headers?: boolean | {
+    contentSecurityPolicy?: boolean | string;
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | string;
+    nosniff?: boolean;
+    hsts?: boolean | { maxAge: number; includeSubDomains?: boolean };
+  };
+  prototypePollutionGuard?: boolean;
+  maxBodySize?: number; // In bytes (default 1MB)
+}
+export interface FireDatabaseOptions {
+  driver?: 'memory' | 'sqlite' | 'postgres' | 'mysql';
+  url?: string;
+  autoMock?: boolean;
+}
+export interface FireCacheOptions {
+  enabled?: boolean;
+  defaultTTL?: number | string;
+}
+export type HookType = 'onRequest' | 'beforeHandle' | 'afterHandle' | 'onError';
+export interface FireHealthOptions {
+  livenessPath?: string; // default '/healthz'
+  readinessPath?: string; // default '/readyz'
+  checkDatabase?: boolean;
+  checkStorage?: boolean;
+  customChecks?: Array<() => Promise<{ name: string; status: 'ok' | 'degraded' | 'down'; message?: string }>>;
+}
+export interface FireAppOptions {
+  port?: number;
+  security?: FireSecurityOptions;
+  database?: FireDatabaseOptions;
+  cache?: FireCacheOptions;
+  storage?: { driver?: 'memory' | 'local'; rootDir?: string; baseUrl?: string };
+  compression?: boolean | { threshold?: number };
+  docs?: string | false; // default '/docs'
+  openapiPath?: string | false; // default '/openapi.json'
+  metricsPath?: string | false; // default '/metrics'
+  health?: boolean | FireHealthOptions;
+  multiTenant?: { header?: string; query?: string; autoScopeDB?: boolean };
+  prefix?: string;
+}

package/src/ws/ws.ts ADDED Viewed

@@ -0,0 +1,118 @@
+import { FireContext } from '../types';
+export interface FireWebSocket {
+  id: string;
+  data: Record<string, any>;
+  send(message: any): void;
+  close(code?: number, reason?: string): void;
+  join(room: string): void;
+  leave(room: string): void;
+  publish(room: string, message: any, excludeSelf?: boolean): void;
+  broadcast(message: any, excludeSelf?: boolean): void;
+}
+export interface FireWebSocketHandler {
+  open?(ws: FireWebSocket, ctx: FireContext): void | Promise<void>;
+  message?(ws: FireWebSocket, message: any, ctx: FireContext): void | Promise<void>;
+  close?(ws: FireWebSocket, code: number, reason: string, ctx: FireContext): void | Promise<void>;
+}
+export class MockWebSocket {
+  public receivedMessages: string[] = [];
+  public isClosed = false;
+  constructor(public id: string) {}
+  public send(msg: string): void {
+    if (!this.isClosed) {
+      this.receivedMessages.push(msg);
+    }
+  }
+  public close(): void {
+    this.isClosed = true;
+  }
+}
+export class WebSocketHub {
+  private clients: Map<string, FireWebSocket> = new Map();
+  private rooms: Map<string, Set<string>> = new Map(); // room -> Set of client IDs
+  public register(rawSocket: any, id?: string): FireWebSocket {
+    const socketId = id || rawSocket.id || `ws_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+    const joinedRooms: Set<string> = new Set();
+    const data: Record<string, any> = {};
+    const fireWs: FireWebSocket = {
+      id: socketId,
+      data,
+      send(message: any) {
+        const payload = typeof message === 'string' ? message : JSON.stringify(message);
+        rawSocket.send(payload);
+      },
+      close(code = 1000, reason = '') {
+        rawSocket.close(code, reason);
+      },
+      join: (room: string) => {
+        joinedRooms.add(room);
+        if (!this.rooms.has(room)) {
+          this.rooms.set(room, new Set());
+        }
+        this.rooms.get(room)!.add(socketId);
+      },
+      leave: (room: string) => {
+        joinedRooms.delete(room);
+        const roomClients = this.rooms.get(room);
+        if (roomClients) {
+          roomClients.delete(socketId);
+          if (roomClients.size === 0) {
+            this.rooms.delete(room);
+          }
+        }
+      },
+      publish: (room: string, message: any, excludeSelf = true) => {
+        const targetIds = this.rooms.get(room);
+        if (!targetIds) return;
+        const payload = typeof message === 'string' ? message : JSON.stringify(message);
+        for (const targetId of targetIds) {
+          if (excludeSelf && targetId === socketId) continue;
+          const targetClient = this.clients.get(targetId);
+          if (targetClient) {
+            targetClient.send(payload);
+          }
+        }
+      },
+      broadcast: (message: any, excludeSelf = false) => {
+        const payload = typeof message === 'string' ? message : JSON.stringify(message);
+        for (const [targetId, targetClient] of this.clients.entries()) {
+          if (excludeSelf && targetId === socketId) continue;
+          targetClient.send(payload);
+        }
+      },
+    };
+    this.clients.set(socketId, fireWs);
+    return fireWs;
+  }
+  public unregister(socketId: string): void {
+    this.clients.delete(socketId);
+    for (const [room, clientSet] of this.rooms.entries()) {
+      clientSet.delete(socketId);
+      if (clientSet.size === 0) {
+        this.rooms.delete(room);
+      }
+    }
+  }
+  public getClient(id: string): FireWebSocket | undefined {
+    return this.clients.get(id);
+  }
+}

package/test/ai-mcp.test.ts ADDED Viewed

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'bun:test';
+import { Router } from '../src/core/router';
+import { s } from '../src/schema/schema';
+import { createMCPServer } from '../src/ai/mcp';
+describe('FireAPI FireAI & Model Context Protocol (MCP) Adapter', () => {
+  it('discovers all routes flagged with ai metadata and builds MCP tool manifests', () => {
+    const router = new Router();
+    router.get('/users/:id', {
+      ai: { description: 'Fetch user account profile by unique ID' },
+      schema: {
+        params: s.object({ id: s.string().min(1) }),
+      },
+      handler: (ctx) => ctx.ok({ id: ctx.params.id, name: 'Alice' }),
+    });
+    router.post('/users', {
+      ai: { description: 'Create a new user account' },
+      schema: {
+        body: s.object({
+          name: s.string(),
+          email: s.string().email(),
+        }),
+      },
+      handler: (ctx) => ctx.created({ id: 'new_user', ...ctx.body }),
+    });
+    const mcp = createMCPServer(router, { name: 'UserServer', version: '1.0.0' });
+    const tools = mcp.listTools();
+    expect(tools.length).toBe(2);
+    expect(tools[0].name).toBe('get_users_id');
+    expect(tools[0].description).toBe('Fetch user account profile by unique ID');
+    expect(tools[0].inputSchema.type).toBe('object');
+    expect(tools[1].name).toBe('post_users');
+    expect(tools[1].inputSchema.properties.name).toBeDefined();
+  });
+  it('executes tool calls via callTool and invokes the route handler cleanly', async () => {
+    const router = new Router();
+    router.post('/calc/add', {
+      ai: { description: 'Add two numbers' },
+      schema: {
+        body: s.object({
+          a: s.number(),
+          b: s.number(),
+        }),
+      },
+      handler: (ctx) => ctx.ok({ result: ctx.body.a + ctx.body.b }),
+    });
+    const mcp = createMCPServer(router);
+    const result = await mcp.callTool('post_calc_add', { a: 15, b: 27 });
+    expect(result.isError).toBe(false);
+    expect(result.content[0].type).toBe('text');
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.result).toBe(42);
+  });
+});