@tamayrp14/fire-api 0.0.0-stage → 1.0.1

package/examples/basic-api/index.ts

@@ -0,0 +1,177 @@
+import { createApp, createRouter, s, createAuth, enableStudio } from '../../src/index';
+
+// 1. Initialize FireAPI Application
+const app = createApp({
+  port: 3000,
+  database: {
+    driver: 'memory',
+    autoMock: true,
+  },
+  storage: {
+    driver: 'memory',
+    baseUrl: 'http://localhost:3000/uploads',
+  },
+  security: {
+    rateLimit: { max: 100, window: '1m' },
+    cors: true,
+    headers: true,
+  },
+  docs: '/docs',
+  openapiPath: '/openapi.json',
+  metricsPath: '/metrics', // Standard Prometheus scraping endpoint
+});
+
+// 2. Turnkey Authentication & Embedded Dev Studio
+app.use('/auth', createAuth({ jwtSecret: 'jwt-super-secret-key' }));
+enableStudio(app, { path: '/studio' });
+
+// 3. Background Job Worker & In-Process Typed Event Bus
+app.queue.handle('send-email', async (data) => {
+  console.log(`[Queue Worker] 📧 Sending email to ${data.to}: "${data.subject}"`);
+});
+
+app.on('order.*', async (order) => {
+  console.log(`[Event Bus] 📡 Order event captured: total=$${order.total}`);
+});
+
+// 4. Lifecycle Interceptor Hook
+app.hook('afterHandle', async (ctx, response) => {
+  response.headers.set('X-Powered-By', 'FireAPI Engine');
+  return response;
+});
+
+// 5. Scheduled Cron Task
+app.cron('@hourly', async (appInstance) => {
+  console.log('[FireCron] ⏰ Hourly background maintenance running...');
+});
+
+// 5. Define Book Validation Schema
+const BookSchema = s.object({
+  title: s.string().min(2).description('Title of the book'),
+  author: s.string().min(2).description('Author name'),
+  price: s.number().min(0).description('Price in USD'),
+  category: s.enum(['tech', 'fiction', 'science']).default('tech'),
+});
+
+const bookRouter = createRouter('/books');
+
+// GET /books - With route-level caching and eager-loaded relations
+bookRouter.get('/', {
+  cache: { ttl: 60, tags: ['books'] },
+  ai: { description: 'Retrieve all books from the store', tags: ['Books'] },
+  handler: async (ctx) => {
+    return ctx.db.books.include('reviews').find();
+  },
+});
+
+// POST /books/checkout - Idempotency Shield (Safe Replays with X-Idempotency-Key)
+bookRouter.post('/checkout', {
+  idempotent: true,
+  handler: async (ctx) => {
+    const order = await ctx.db.orders.insert({
+      items: ctx.body.items,
+      total: ctx.body.total,
+      orderedAt: new Date().toISOString(),
+    });
+    return ctx.created(order);
+  },
+});
+
+// POST /books/transfer - Atomic Transaction Scope with auto-rollback
+bookRouter.post('/transfer', async (ctx) => {
+  const result = await ctx.db.tx(async (trx) => {
+    await trx.inventories.update(ctx.body.warehouseA, { stock: 10 });
+    await trx.inventories.update(ctx.body.warehouseB, { stock: 90 });
+    await trx.transfers.insert({ from: ctx.body.warehouseA, to: ctx.body.warehouseB, qty: 40 });
+    return { success: true };
+  });
+  return ctx.ok(result);
+});
+
+// POST /webhooks/payment - Turnkey HMAC Webhook Verifier
+bookRouter.post('/webhooks/payment', async (ctx) => {
+  const valid = await ctx.webhook.verifyHMAC({
+    secret: 'whsec_sample_secret_key',
+  });
+  if (!valid) return ctx.unauthorized('Invalid webhook signature');
+  return ctx.ok({ received: true, event: ctx.body.event });
+});
+
+// POST /books - With validation, background email dispatch & cache invalidation
+bookRouter.post('/', {
+  schema: { body: BookSchema },
+  ai: { description: 'Add a new book to the library', tags: ['Books'] },
+  handler: async (ctx) => {
+    const newBook = await ctx.db.books.insert(ctx.body);
+    await ctx.cache.invalidate('books');
+
+    // Dispatch background email without blocking the HTTP response
+    await ctx.queue.dispatch('send-email', {
+      to: 'admin@fire.dev',
+      subject: `New book added: ${newBook.title}`,
+    });
+
+    return ctx.created(newBook);
+  },
+});
+
+// DELETE /books/:id - Ultra-simple 1-line delete
+bookRouter.delete('/:id', async (ctx) => {
+  await ctx.db.books.delete(ctx.params.id);
+  return { deleted: true };
+});
+
+// POST /books/cover - Universal Object Storage Upload
+bookRouter.post('/cover', {
+  ai: { description: 'Upload book cover image', tags: ['Storage'] },
+  handler: async (ctx) => {
+    const uploaded = await ctx.storage.put('covers/sample.png', 'fake_png_binary_data', {
+      contentType: 'image/png',
+    });
+    return ctx.created(uploaded);
+  },
+});
+
+// GET /books/stream/ai - Real-Time AI Token Streaming via Server-Sent Events (SSE)
+bookRouter.get('/stream/ai', {
+  ai: { description: 'Simulate streaming AI thoughts token-by-token', tags: ['AI'] },
+  handler: (ctx) => {
+    return ctx.stream.sse(async (stream) => {
+      const tokens = ['FireAPI', 'is', 'the', 'fastest', 'modern', 'TypeScript', 'framework!'];
+      for (const token of tokens) {
+        await stream.send(token, { event: 'token' });
+        await new Promise((r) => setTimeout(r, 100)); // Simulate LLM latency
+      }
+      await stream.send('[DONE]', { event: 'done' });
+      stream.close();
+    });
+  },
+});
+
+// 6. Native Real-Time WebSockets with Rooms
+app.ws('/chat/:room', {
+  open(ws, ctx) {
+    ws.join(ctx.params.room);
+    ws.publish(ctx.params.room, { notice: `User connected to room ${ctx.params.room}` });
+  },
+  message(ws, msg, ctx) {
+    ws.publish(ctx.params.room, { message: msg });
+  },
+});
+
+// 7. Mount Router & Enable Model Context Protocol (MCP) for AI Agents
+app.use(bookRouter);
+app.enableMCP({ name: 'BookStoreMCP', version: '1.0.0' });
+
+// 8. Start Server
+console.log('🔥 FireAPI server launching at http://localhost:3000');
+console.log('🖥️ FireStudio Dashboard: http://localhost:3000/studio');
+console.log('📖 Interactive Scalar API Docs: http://localhost:3000/docs');
+console.log('📊 Prometheus Metrics: http://localhost:3000/metrics');
+console.log('⚡ OpenAPI 3.1 Spec: http://localhost:3000/openapi.json');
+console.log('🤖 MCP AI Endpoint: http://localhost:3000/mcp');
+
+app.listen(3000);
+
+export type AppRouter = typeof app;
+export default app;

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@tamayrp14/fire-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Ultra-lightweight, blazing-fast, type-safe API framework with universal DB, security shield, turnkey auth, express compat, dev studio, and native AI/MCP integration",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "bin": {
+    "fire-api": "./bin/fire.mjs",
+    "fire": "./bin/fire.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yogarizyapratama/FIRE-API.git"
+  },
+  "homepage": "https://github.com/yogarizyapratama/FIRE-API#readme",
+  "bugs": {
+    "url": "https://github.com/yogarizyapratama/FIRE-API/issues"
+  },
+  "author": "Yoga Rizya Pratama",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    },
+    "./auth": {
+      "import": "./dist/auth/auth.js",
+      "types": "./dist/auth/auth.d.ts"
+    },
+    "./compat": {
+      "import": "./dist/compat/express.js",
+      "types": "./dist/compat/express.d.ts"
+    },
+    "./studio": {
+      "import": "./dist/studio/studio.js",
+      "types": "./dist/studio/studio.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build ./bin/fire.js --outfile ./bin/fire.mjs --target node --format esm && chmod +x ./bin/fire.mjs && bun build ./src/index.ts ./src/client.ts ./src/auth/auth.ts ./src/compat/express.ts ./src/studio/studio.ts --outdir ./dist --target node && tsc --module ESNext --moduleResolution bundler --declaration --emitDeclarationOnly --outDir dist",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "framework",
+    "api",
+    "typescript",
+    "fast",
+    "bun",
+    "node",
+    "mcp",
+    "sqlite",
+    "postgres",
+    "auth",
+    "studio",
+    "rest"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "typescript": "^5.7.3"
+  }
+}

package/src/ai/mcp.ts

@@ -0,0 +1,140 @@
+import { Router } from '../core/router';
+import { createContext } from '../core/context';
+import { BaseSchema } from '../schema/schema';
+
+export interface MCPToolManifest {
+  name: string;
+  description: string;
+  inputSchema: Record<string, any>;
+}
+
+export interface MCPToolResult {
+  content: { type: 'text'; text: string }[];
+  isError?: boolean;
+}
+
+export interface MCPServerOptions {
+  name?: string;
+  version?: string;
+}
+
+export function routeToToolName(method: string, path: string): string {
+  const clean = path
+    .replace(/^\//, '')
+    .replace(/:([a-zA-Z0-9_]+)/g, '$1')
+    .replace(/[^a-zA-Z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/_$/, '');
+  return `${method.toLowerCase()}_${clean || 'root'}`;
+}
+
+export class MCPServer {
+  constructor(private router: Router, private options: MCPServerOptions = {}) {}
+
+  public listTools(): MCPToolManifest[] {
+    const tools: MCPToolManifest[] = [];
+
+    for (const route of this.router.routesList) {
+      if (!route.options.ai) continue;
+
+      const toolName = route.options.ai.operationId || routeToToolName(route.method, route.path);
+      const schema = route.options.schema;
+
+      let inputSchema: Record<string, any> = { type: 'object', properties: {} };
+
+      if (schema?.body && schema.body instanceof BaseSchema) {
+        inputSchema = schema.body.toOpenAPI();
+      } else if (schema?.params && schema.params instanceof BaseSchema) {
+        inputSchema = schema.params.toOpenAPI();
+      } else if (schema?.query && schema.query instanceof BaseSchema) {
+        inputSchema = schema.query.toOpenAPI();
+      }
+
+      tools.push({
+        name: toolName,
+        description: route.options.ai.description || `${route.method} ${route.path}`,
+        inputSchema,
+      });
+    }
+
+    return tools;
+  }
+
+  public async callTool(name: string, args: Record<string, any> = {}): Promise<MCPToolResult> {
+    for (const route of this.router.routesList) {
+      if (!route.options.ai) continue;
+      const toolName = route.options.ai.operationId || routeToToolName(route.method, route.path);
+
+      if (toolName === name) {
+        try {
+          // Construct simulated request and context
+          const req = new Request(`http://localhost${route.path}`, {
+            method: route.method,
+            headers: { 'Content-Type': 'application/json' },
+            body: route.method !== 'GET' && route.method !== 'HEAD' ? JSON.stringify(args) : undefined,
+          });
+
+          const ctx = createContext({
+            req,
+            params: args,
+            body: args,
+          });
+
+          const res = await route.options.handler(ctx);
+          let outputText = '';
+
+          if (res instanceof Response) {
+            outputText = await res.text();
+          } else {
+            outputText = typeof res === 'string' ? res : JSON.stringify(res);
+          }
+
+          return {
+            content: [{ type: 'text', text: outputText }],
+            isError: false,
+          };
+        } catch (err: any) {
+          return {
+            content: [{ type: 'text', text: err?.message || 'Error executing tool' }],
+            isError: true,
+          };
+        }
+      }
+    }
+
+    return {
+      content: [{ type: 'text', text: `Tool not found: ${name}` }],
+      isError: true,
+    };
+  }
+
+  public handleMCPProtocol(message: { method: string; params?: any; id?: any }): Promise<any> {
+    const { method, params, id } = message;
+
+    if (method === 'tools/list') {
+      return Promise.resolve({
+        jsonrpc: '2.0',
+        id,
+        result: { tools: this.listTools() },
+      });
+    }
+
+    if (method === 'tools/call') {
+      return this.callTool(params?.name, params?.arguments).then((res) => ({
+        jsonrpc: '2.0',
+        id,
+        result: res,
+      }));
+    }
+
+    return Promise.resolve({
+      jsonrpc: '2.0',
+      id,
+      error: { code: -32601, message: 'Method not found' },
+    });
+  }
+}
+
+export function createMCPServer(router: Router, options: MCPServerOptions = {}): MCPServer {
+  return new MCPServer(router, options);
+}

package/src/auth/auth.ts

@@ -0,0 +1,110 @@
+import { createRouter, Router } from '../core/router';
+import { Middleware } from '../types';
+import { s } from '../schema/schema';
+import { hashPassword, verifyPassword } from './crypto';
+import { signJWT, verifyJWT } from './jwt';
+
+export interface CreateAuthOptions {
+  jwtSecret: string;
+  tableName?: string;
+  tokenExpirySeconds?: number;
+}
+
+export function createAuth(options: CreateAuthOptions): Router {
+  const router = createRouter();
+  const tableName = options.tableName || 'users';
+  const secret = options.jwtSecret;
+  const expiry = options.tokenExpirySeconds || 86400; // 24 hours
+
+  // POST /register
+  router.post('/register', {
+    schema: {
+      body: s.object({
+        email: s.string().email(),
+        password: s.string().min(6),
+        name: s.string().optional(),
+      }),
+    },
+    ai: { description: 'Register a new user account with credentials', tags: ['Auth'] },
+    handler: async (ctx) => {
+      const { email, password, name } = ctx.body;
+
+      // Check if user already exists
+      const existing = await ctx.db.table(tableName).where('email', email).findOne();
+      if (existing) {
+        return ctx.badRequest('A user with this email already exists');
+      }
+
+      const hashedPassword = await hashPassword(password);
+      const newUser = await ctx.db.table(tableName).insert({
+        email,
+        password: hashedPassword,
+        name: name || email.split('@')[0],
+      });
+
+      // Strip password from returned user object
+      const safeUser = { id: newUser.id, email: newUser.email, name: newUser.name };
+      const token = await signJWT(safeUser, secret, expiry);
+
+      return ctx.created({ user: safeUser, token });
+    },
+  });
+
+  // POST /login
+  router.post('/login', {
+    schema: {
+      body: s.object({
+        email: s.string().email(),
+        password: s.string(),
+      }),
+    },
+    ai: { description: 'Authenticate user with email and password', tags: ['Auth'] },
+    handler: async (ctx) => {
+      const { email, password } = ctx.body;
+
+      const user = await ctx.db.table(tableName).where('email', email).findOne();
+      if (!user) {
+        return ctx.unauthorized('Invalid email or password');
+      }
+
+      const isValid = await verifyPassword(password, user.password);
+      if (!isValid) {
+        return ctx.unauthorized('Invalid email or password');
+      }
+
+      const safeUser = { id: user.id, email: user.email, name: user.name };
+      const token = await signJWT(safeUser, secret, expiry);
+
+      return ctx.ok({ user: safeUser, token });
+    },
+  });
+
+  // GET /me
+  router.get('/me', {
+    middlewares: [requireAuth(secret)],
+    ai: { description: 'Get authenticated user profile', tags: ['Auth'] },
+    handler: (ctx) => {
+      return ctx.ok({ user: ctx.user });
+    },
+  });
+
+  return router;
+}
+
+export function requireAuth(secret: string): Middleware {
+  return async (ctx, next) => {
+    const authHeader = ctx.req.headers.get('authorization') || ctx.req.headers.get('Authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return ctx.unauthorized('Missing or invalid Authorization header');
+    }
+
+    const token = authHeader.slice(7).trim();
+    try {
+      const payload = await verifyJWT(token, secret);
+      ctx.user = payload;
+      return next();
+    } catch {
+      return ctx.unauthorized('Invalid or expired token');
+    }
+  };
+}

package/src/auth/crypto.ts

@@ -0,0 +1,70 @@
+function bufferToHex(buffer: ArrayBuffer | Uint8Array): string {
+  return Array.from(new Uint8Array(buffer as any))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function hexToBuffer(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = new Uint8Array(16);
+  crypto.getRandomValues(salt);
+
+  const enc = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits', 'deriveKey']
+  );
+
+  const derived = await crypto.subtle.deriveBits(
+    {
+      name: 'PBKDF2',
+      salt: salt as any,
+      iterations: 100000,
+      hash: 'SHA-256',
+    },
+    keyMaterial,
+    256
+  );
+
+  return `${bufferToHex(salt)}:${bufferToHex(derived)}`;
+}
+
+export async function verifyPassword(password: string, storedHash: string): Promise<boolean> {
+  const parts = storedHash.split(':');
+  if (parts.length !== 2) return false;
+
+  const [saltHex, originalHashHex] = parts;
+  const salt = hexToBuffer(saltHex);
+
+  const enc = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits', 'deriveKey']
+  );
+
+  const derived = await crypto.subtle.deriveBits(
+    {
+      name: 'PBKDF2',
+      salt: salt as any,
+      iterations: 100000,
+      hash: 'SHA-256',
+    },
+    keyMaterial,
+    256
+  );
+
+  return bufferToHex(derived) === originalHashHex;
+}

package/src/auth/jwt.ts

@@ -0,0 +1,105 @@
+function base64UrlEncode(str: string): string {
+  const bytes = new TextEncoder().encode(str);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64UrlDecode(str: string): string {
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+  while (base64.length % 4) {
+    base64 += '=';
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new TextDecoder().decode(bytes);
+}
+
+function arrayBufferToBase64Url(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export async function signJWT(
+  payload: Record<string, any>,
+  secret: string,
+  expiresInSeconds = 86400
+): Promise<string> {
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const now = Math.floor(Date.now() / 1000);
+  const fullPayload = {
+    ...payload,
+    iat: now,
+    exp: now + expiresInSeconds,
+  };
+
+  const encodedHeader = base64UrlEncode(JSON.stringify(header));
+  const encodedPayload = base64UrlEncode(JSON.stringify(fullPayload));
+  const dataToSign = `${encodedHeader}.${encodedPayload}`;
+
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+
+  const signature = await crypto.subtle.sign('HMAC', key, enc.encode(dataToSign));
+  const encodedSignature = arrayBufferToBase64Url(signature);
+
+  return `${dataToSign}.${encodedSignature}`;
+}
+
+export async function verifyJWT<T = any>(token: string, secret: string): Promise<T> {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    throw new Error('Invalid JWT format');
+  }
+
+  const [encodedHeader, encodedPayload, encodedSignature] = parts;
+  const dataToVerify = `${encodedHeader}.${encodedPayload}`;
+
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['verify']
+  );
+
+  // Decode signature to ArrayBuffer
+  let base64Sig = encodedSignature.replace(/-/g, '+').replace(/_/g, '/');
+  while (base64Sig.length % 4) {
+    base64Sig += '=';
+  }
+  const binarySig = atob(base64Sig);
+  const sigBytes = new Uint8Array(binarySig.length);
+  for (let i = 0; i < binarySig.length; i++) {
+    sigBytes[i] = binarySig.charCodeAt(i);
+  }
+
+  const isValid = await crypto.subtle.verify('HMAC', key, sigBytes, enc.encode(dataToVerify));
+  if (!isValid) {
+    throw new Error('Invalid JWT signature');
+  }
+
+  const payload: any = JSON.parse(base64UrlDecode(encodedPayload));
+  const now = Math.floor(Date.now() / 1000);
+  if (payload.exp && payload.exp < now) {
+    throw new Error('JWT token has expired');
+  }
+
+  return payload as T;
+}