@browserlessapi/inferlo 0.0.0-stage → 0.4.0

package/llms.txt

@@ -0,0 +1,27 @@
+# Inferlo
+
+> Inferlo is a batteries-included TypeScript backend framework with built-in AI model support (Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible providers with fallback, structured output, streaming, embeddings and usage tracking), plus routes, schemas, database (PostgreSQL and in-memory), auth, an MCP server and OpenAPI, with zero runtime dependencies. Runs on Node.js 22.18+, Bun, Deno and edge runtimes. Package: @browserlessapi/inferlo.
+
+Key rules: routes are private unless `auth: "public"`; validate input with `t.*` schemas; use `db.<table>` methods (never string-built SQL); every model has id, createdAt, updatedAt automatically; relative imports end in `.ts`; run `inferlo describe --json` to see an app and `inferlo check --json` after changes.
+
+## Docs
+
+- [Getting started](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/getting-started.md): install, project layout, minimal app
+- [Schemas](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/schema.md): t.* types, modifiers, validation, JSON Schema
+- [Models and database](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/database.md): model(), queries, adapters, db push, transactions
+- [Routes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/routes.md): options, handler context, return values, errors, middleware
+- [Auth](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/auth.md): auth.resolve, roles, bearer API keys, passwords
+- [AI](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/ai.md): providers, aliases and fallback, structured output, streaming, embeddings, usage and budgets
+- [MCP, OpenAPI and describe](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/mcp.md)
+- [CLI](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/cli.md)
+- [Testing](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/testing.md)
+- [Deployment](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/deploy.md)
+- [Error codes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/errors.md): every KRxxxx code with its fix
+
+## Full text
+
+- [llms-full.txt](https://raw.githubusercontent.com/BrowserlessAPI/Inferlo/main/llms-full.txt): all docs in one file
+
+## Example
+
+- [Helpdesk with AI triage](https://github.com/BrowserlessAPI/Inferlo/tree/main/examples/helpdesk)

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@browserlessapi/inferlo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "The TypeScript backend framework with built-in AI model support: Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible models, plus routing, database, validation, auth and MCP in one package.",
+  "type": "module",
+  "license": "MIT",
+  "author": "BrowserlessAPI",
+  "homepage": "https://github.com/BrowserlessAPI/Inferlo#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrowserlessAPI/Inferlo.git"
+  },
+  "bugs": "https://github.com/BrowserlessAPI/Inferlo/issues",
+  "keywords": [
+    "typescript",
+    "backend",
+    "framework",
+    "api",
+    "rest",
+    "orm",
+    "validation",
+    "ai",
+    "llm",
+    "mcp",
+    "ai-agents",
+    "bun",
+    "deno",
+    "edge"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./postgres": {
+      "types": "./dist/db/postgres.d.ts",
+      "default": "./dist/db/postgres.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "bin": {
+    "inferlo": "./dist/cli/main.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli/main.js",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/helpdesk",
+    "test": "node --test --test-reporter=spec \"test/**/*.test.ts\" \"examples/*/test/*.test.ts\"",
+    "test:bun": "bun test test/",
+    "llms": "node scripts/build-llms.ts",
+    "check": "npm run typecheck && npm test && node scripts/build-llms.ts --check",
+    "bench": "node bench/run.ts"
+  },
+  "peerDependencies": {
+    "pg": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "@types/pg": "^8.15.0",
+    "pg": "^8.16.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/app/AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+This is a [Inferlo](https://github.com/BrowserlessAPI/Inferlo) backend. Inferlo is a TypeScript backend framework designed so AI coding agents get things right the first time. Follow these rules.
+
+## Before you change anything
+
+```bash
+npx inferlo describe --json   # every model, field, route, auth rule and AI alias
+```
+
+Read that instead of searching the codebase. After every change run:
+
+```bash
+npx inferlo check --json      # typecheck + load the app + tests, machine-readable errors
+```
+
+Do not finish until `inferlo check` passes.
+
+## Layout
+
+| File | What goes there |
+|---|---|
+| `src/models.ts` | Every model (`model("table_name", { ... })`) and the `models` array |
+| `src/routes/<feature>.ts` | Routes for one feature, each one an exported `const` |
+| `src/app.ts` | `createApp({ models, routes, db, auth, ai })`. Import route modules with `import * as x` |
+| `src/server.ts` | Starts the server. Keep it small |
+| `test/<feature>.test.ts` | Tests using `app.request(path, { method, json, as: user })` |
+
+## Rules
+
+1. **One way to do each thing.** Routes: `route.get/post/put/patch/delete(path, options).handle(fn)`. Validation: `t.*` schemas. Database: `db.<table>.<method>`. AI: `ai.generate` / `ai.stream` / `ai.embed`.
+2. **Routes are private by default.** A route without `auth` needs a signed-in user. Use `auth: "public"` only for routes anyone may call, and `auth: "<role>"` for role checks.
+3. **Validate every input with a schema.** `body`, `query` and `params` options. Reuse model schemas: `Ticket.pick("title", "body")`, `Ticket.omit("ownerId")`, `.partial()` for PATCH.
+4. **Check ownership.** Fetch with `db.x.get(id)` (throws 404) and compare `ownerId` to `user.id`; throw `notFound()` when it does not match, so other users' ids are not revealed.
+5. **Related rows:** a `t.ref` field named `<name>Id` is a relation: `db.notes.findMany({ include: { owner: true } })` adds `note.owner` with one extra query, and `db.users.findMany({ include: { notes: true } })` adds `user.notes` (the rows that point to each user). Never load related rows in a loop.
+6. **Never write raw SQL with string concatenation.** Use the table methods. If you really need SQL, use `db.$sql(text, params)` with `$1` placeholders.
+7. **Model ids, timestamps:** every model already has `id`, `createdAt`, `updatedAt`. Never define them or send them as input.
+8. **New field?** Add it to the model in `src/models.ts`, then run `npx inferlo db push` in development, or `npx inferlo db migrate <name>` to write a migration file for production (applied with `npx inferlo db migrate --apply`). Use `.optional()` or `.default()` for new fields on existing tables. Never edit `migrations/snapshot.json`, and never edit a migration file that has been applied (`--apply` warns with IL4018 and does not run the change): put changes in a new migration. Removing a model or field needs `npx inferlo db migrate <name> --allow-drop` (it deletes that data); never use it for a rename. Changing a field's type or default, making it required or optional, or changing an enum's values needs `--allow-change`; give a newly required field a `.default()` so existing NULL rows get a value, and before removing an enum value add an `UPDATE` in the new migration file (before its `ADD CONSTRAINT`) that moves rows off it (IL4021).
+9. **New resource?** `npx inferlo add resource <plural_name>` generates the model and CRUD routes. Then edit them.
+10. **AI calls** use aliases from `src/app.ts` (`model: "fast"`), never hard-coded provider model ids in routes. Use `output: schema` for structured data and `for: user.id` so usage is tracked per user. To let the model act, pass routes as tools: `ai.generate({ prompt, tools: [createNote, getNote], for: user.id })`. Each tool call runs as the current user with that route's auth and validation. To send images: `ai.generate({ prompt, images: [{ url }] })` or `[{ base64, mediaType: "image/png" }]`. Give routes that call AI models, send email or check passwords a `rateLimit: { max, per, by }` (IL2005 is the 429 it returns).
+11. **Errors:** throw `notFound()`, `forbidden()`, `badRequest()` or `httpError(status, message)`. Every Inferlo error has a code (ILxxxx), a fix and a docs link: read the fix before changing code.
+12. **Imports:** relative imports end in `.ts` (`import { Note } from "../models.ts"`).
+13. **Expose to AI agents:** add `tool: true` to a route to make it an MCP tool at `/mcp`. Same auth applies.
+14. **Slow work after the response** (email, slow AI calls) is a background job: `export const x = job("send-email", { input: t.object({ ... }) }).handle(async ({ input, db, ai }) => { ... })` in `src/jobs.ts`, registered with `createApp({ jobs: [jobs] })`, queued with `await ctx.jobs.enqueue(x, { ... })`. Pass ids in the input, not rows. In tests, run queued jobs with `await app.jobs.runDue()`. Jobs run in the server process (`app.jobs.start()` in `src/server.ts`); with `createApp({ jobQueue: { store: "database" } })` they are kept in Postgres and `npm run worker` (`inferlo worker`) runs them in separate processes. Scheduled work is a cron next to its job: `export const nightly = cron("0 3 * * *", cleanupJob)` (UTC; the job's input must be `t.object({})`).
+
+## Testing
+
+```ts
+const res = await app.request("/notes", { method: "POST", json: { title: "Hi" }, as: user });
+const note = await readJson(res, 201);   // from "@browserlessapi/inferlo/testing"
+```
+
+Use `memory()` for the database and `mockProvider()` for AI in tests.
+
+Full docs: https://github.com/BrowserlessAPI/Inferlo/tree/main/docs

package/templates/app/CLAUDE.md

@@ -0,0 +1 @@
+Read AGENTS.md before making changes. Run `npx inferlo describe --json` to see the app, and `npx inferlo check --json` after every change.

package/templates/app/README.md

@@ -0,0 +1,16 @@
+# {{name}}
+
+Built with [Inferlo](https://github.com/BrowserlessAPI/Inferlo).
+
+```bash
+npm install
+npm run dev          # starts on http://localhost:3000 and prints a dev API key
+npm run check        # typecheck + tests
+npx inferlo describe   # routes, models and auth at a glance
+```
+
+Set `DATABASE_URL` in `.env` to use PostgreSQL, then run `npx inferlo db push`.
+
+Background jobs run in the server process. To run them in separate processes too, set `jobQueue: { store: "database" }` in `src/app.ts` (needs PostgreSQL) and start workers with `npm run worker`.
+
+AI coding agents: read `AGENTS.md`.

package/templates/app/_env.example

@@ -0,0 +1,5 @@
+# Leave DATABASE_URL empty to use the in-memory database (data resets on restart).
+DATABASE_URL=
+PORT=3000
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=

package/templates/app/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+.env
+dist

package/templates/app/package.json.tpl

@@ -0,0 +1,32 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "inferlo": {
+    "entry": "src/app.ts",
+    "server": "src/server.ts"
+  },
+  "scripts": {
+    "dev": "inferlo dev",
+    "start": "node src/server.ts",
+    "worker": "inferlo worker",
+    "check": "inferlo check",
+    "describe": "inferlo describe",
+    "db:push": "inferlo db push",
+    "db:migrate": "inferlo db migrate",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@browserlessapi/inferlo": "{{inferloDependency}}",
+    "pg": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/app/src/app.ts

@@ -0,0 +1,38 @@
+import { anthropic, bearer, createApp, env, hashToken, memory, openai } from "@browserlessapi/inferlo";
+import { postgres } from "@browserlessapi/inferlo/postgres";
+import { models } from "./models.ts";
+import * as health from "./routes/health.ts";
+import * as notes from "./routes/notes.ts";
+
+const databaseUrl = env("DATABASE_URL", { optional: true });
+
+export const app = createApp({
+  name: "{{name}}",
+  version: "0.1.0",
+  models,
+  // inferlo:routes
+  routes: [health, notes],
+  db: databaseUrl ? postgres({ url: databaseUrl }) : memory(),
+
+  // Requests send "Authorization: Bearer <api key>". Keys are stored as SHA-256 hashes.
+  auth: bearer(async (token, { db }) => {
+    const key = await db.api_keys.findOne({ hash: await hashToken(token) });
+    if (!key) return null;
+    const user = await db.users.find(key.userId);
+    return user ? { id: user.id, email: user.email, name: user.name, roles: [user.role] } : null;
+  }),
+
+  ai: {
+    providers: {
+      anthropic: anthropic({ apiKey: env("ANTHROPIC_API_KEY", { default: "" }) }),
+      openai: openai({ apiKey: env("OPENAI_API_KEY", { default: "" }) }),
+    },
+    // Aliases keep model ids in one place. A list means: try in order.
+    models: {
+      fast: ["anthropic:claude-haiku-4-5", "openai:gpt-5-mini"],
+      smart: ["anthropic:claude-sonnet-4-5", "openai:gpt-5"],
+    },
+  },
+});
+
+export default app;

package/templates/app/src/models.ts

@@ -0,0 +1,31 @@
+import { model, t } from "@browserlessapi/inferlo";
+
+export const User = model("users", {
+  email: t.email().unique(),
+  name: t.string().max(80),
+  role: t.enum(["member", "admin"]).default("member"),
+});
+
+export const ApiKey = model("api_keys", {
+  userId: t.ref("users", { onDelete: "cascade" }),
+  hash: t.string().max(64).unique(),
+  label: t.string().max(80).default("default"),
+});
+
+export const Note = model("notes", {
+  title: t.string().min(1).max(200),
+  body: t.text().default(""),
+  ownerId: t.ref("users", { onDelete: "cascade" }),
+});
+
+// inferlo:models
+export const models = [User, ApiKey, Note] as const;
+
+export type AppUser = { id: string; email: string; name: string; roles: string[] };
+
+declare module "@browserlessapi/inferlo" {
+  interface Register {
+    models: typeof models;
+    user: AppUser;
+  }
+}

package/templates/app/src/routes/health.ts

@@ -0,0 +1,3 @@
+import { route } from "@browserlessapi/inferlo";
+
+export const health = route.get("/health", { auth: "public", summary: "Health check" }).handle(() => ({ ok: true }));

package/templates/app/src/routes/notes.ts

@@ -0,0 +1,56 @@
+import { notFound, route, t } from "@browserlessapi/inferlo";
+import { Note } from "../models.ts";
+
+const IdParams = t.object({ id: t.uuid() });
+
+export const listNotes = route
+  .get("/notes", {
+    summary: "List my notes",
+    query: t.object({ limit: t.int().min(1).max(100).default(20), offset: t.int().min(0).default(0) }),
+    tool: true,
+  })
+  .handle(({ query, user, db }) =>
+    db.notes.findMany({ where: { ownerId: user.id }, orderBy: { createdAt: "desc" }, limit: query.limit, offset: query.offset }),
+  );
+
+export const getNote = route
+  .get("/notes/:id", { params: IdParams, summary: "Get one note", tool: true })
+  .handle(async ({ params, user, db }) => {
+    const note = await db.notes.get(params.id);
+    if (note.ownerId !== user.id) throw notFound();
+    return note;
+  });
+
+export const createNote = route
+  .post("/notes", { body: Note.pick("title", "body"), summary: "Create a note", tool: true })
+  .handle(({ body, user, db, status }) => {
+    status(201);
+    return db.notes.insert({ ...body, ownerId: user.id });
+  });
+
+export const updateNote = route
+  .patch("/notes/:id", { params: IdParams, body: Note.pick("title", "body").partial(), summary: "Update a note" })
+  .handle(async ({ params, body, user, db }) => {
+    const note = await db.notes.get(params.id);
+    if (note.ownerId !== user.id) throw notFound();
+    return db.notes.update(note.id, body);
+  });
+
+export const deleteNote = route
+  .delete("/notes/:id", { params: IdParams, summary: "Delete a note" })
+  .handle(async ({ params, user, db }) => {
+    const note = await db.notes.get(params.id);
+    if (note.ownerId !== user.id) throw notFound();
+    await db.notes.delete(note.id);
+  });
+
+const Summary = t.object({ summary: t.string().max(300).describe("One or two sentences") });
+
+export const summarizeNote = route
+  .post("/notes/:id/summary", { params: IdParams, summary: "Summarize a note with AI", rateLimit: { max: 20, per: "hour" } })
+  .handle(async ({ params, user, db, ai }) => {
+    const note = await db.notes.get(params.id);
+    if (note.ownerId !== user.id) throw notFound();
+    const { object } = await ai.generate({ model: "fast", prompt: `Summarize:\n\n${note.title}\n\n${note.body}`, output: Summary, for: user.id });
+    return object;
+  });

package/templates/app/src/server.ts

@@ -0,0 +1,26 @@
+import { createToken, env, hashToken } from "@browserlessapi/inferlo";
+import { app } from "./app.ts";
+
+await app.db.$sync();
+
+// In-memory database: create a demo user and print an API key so you can try the API.
+if (app.db.$adapter.dialect === "memory") {
+  const user = await app.db.users.insert({ email: "dev@example.com", name: "Developer", role: "admin" });
+  const token = createToken("dev");
+  await app.db.api_keys.insert({ userId: user.id, hash: await hashToken(token) });
+  console.log(`Dev API key: ${token}`);
+  console.log(`Try: curl -H "Authorization: Bearer ${token}" http://localhost:${env("PORT", { default: "3000" })}/notes`);
+}
+
+const server = await app.listen(env.int("PORT", { default: 3000 }));
+console.log(`{{name}} running on http://localhost:${server.port}`);
+
+// Background jobs run in this process. With jobQueue: { store: "database" } in src/app.ts they can
+// also run in separate processes: npm run worker.
+const jobs = app.jobs.start();
+
+process.on("SIGTERM", async () => {
+  await jobs.stop(); // waits for the running job
+  await server.close();
+  await app.db.$close();
+});

package/templates/app/test/notes.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createApp, memory, mockProvider } from "@browserlessapi/inferlo";
+import { readJson } from "@browserlessapi/inferlo/testing";
+import { models } from "../src/models.ts";
+import * as notes from "../src/routes/notes.ts";
+
+function makeApp() {
+  return createApp({
+    models,
+    routes: [notes],
+    db: memory(),
+    auth: { resolve: () => null },
+    ai: { providers: { mock: mockProvider({ respond: () => '{"summary":"A short note."}' }) }, models: { fast: "mock:test" } },
+  });
+}
+
+test("create, list, update and delete notes", async () => {
+  const app = makeApp();
+  const row = await app.db.users.insert({ email: "a@example.com", name: "A" });
+  const user = { id: row.id, email: row.email, name: row.name, roles: [] };
+
+  const note = await readJson(await app.request("/notes", { method: "POST", json: { title: "First" }, as: user }), 201);
+  assert.equal(note.title, "First");
+
+  const list = await readJson(await app.request("/notes", { as: user }), 200);
+  assert.equal(list.length, 1);
+
+  const updated = await readJson(await app.request(`/notes/${note.id}`, { method: "PATCH", json: { body: "Hello" }, as: user }), 200);
+  assert.equal(updated.body, "Hello");
+
+  const summary = await readJson(await app.request(`/notes/${note.id}/summary`, { method: "POST", as: user }), 200);
+  assert.equal(summary.summary, "A short note.");
+
+  assert.equal((await app.request(`/notes/${note.id}`, { method: "DELETE", as: user })).status, 204);
+});
+
+test("other users cannot read my notes", async () => {
+  const app = makeApp();
+  const a = await app.db.users.insert({ email: "a@example.com", name: "A" });
+  const b = await app.db.users.insert({ email: "b@example.com", name: "B" });
+  const note = await app.db.notes.insert({ title: "Private", ownerId: a.id });
+  const res = await app.request(`/notes/${note.id}`, { as: { id: b.id, email: b.email, name: b.name, roles: [] } });
+  assert.equal(res.status, 404);
+});
+
+test("requests without a key are rejected", async () => {
+  const res = await makeApp().request("/notes");
+  assert.equal(res.status, 401);
+});

package/templates/app/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test"]
+}