@browserlessapi/inferlo 0.5.0 → 0.6.0

package/dist/sveltekit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Inferlo inside SvelteKit (2 and 3) server routes, without a runtime dependency on SvelteKit:
+ *
+ *   // src/routes/api/[...path]/+server.ts
+ *   import { toSvelteKitHandlers } from "@browserlessapi/inferlo/sveltekit";
+ *   import { app } from "$lib/server/inferlo";
+ *
+ *   export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, fallback } = toSvelteKitHandlers(app, { prefix: "/api" });
+ *
+ *   // src/hooks.server.ts: event.locals.ai in load functions, form actions and +server.ts files
+ *   import { inferloAI } from "@browserlessapi/inferlo/sveltekit";
+ *   export const handle = inferloAI(ai);
+ *
+ * It never loads the router, database or jobs code.
+ */
+import type { AI } from "./ai/index.ts";
+import type { App as InferloApp } from "./app.ts";
+declare global {
+    namespace App {
+        interface Locals {
+            /** The AI client from the inferloAI() handle hook of @browserlessapi/inferlo/sveltekit. */
+            ai: AI;
+        }
+    }
+}
+/** The parts of a SvelteKit RequestEvent Inferlo uses. */
+export interface SvelteKitEventLike {
+    /** The incoming Web request. */
+    request: Request;
+    /** The client IP from the adapter; called once per request, and errors (some adapters have none) are ignored. */
+    getClientAddress?: () => string;
+    /** event.locals, where the inferloAI() hook puts ai. */
+    locals: object;
+}
+/** A SvelteKit request handler, to export from a +server.ts file. */
+export type SvelteKitRequestHandler = (event: SvelteKitEventLike) => Promise<Response>;
+/** One request handler per HTTP method and a fallback for every other method, to export from +server.ts. */
+export interface SvelteKitHandlers {
+    GET: SvelteKitRequestHandler;
+    POST: SvelteKitRequestHandler;
+    PUT: SvelteKitRequestHandler;
+    PATCH: SvelteKitRequestHandler;
+    DELETE: SvelteKitRequestHandler;
+    HEAD: SvelteKitRequestHandler;
+    OPTIONS: SvelteKitRequestHandler;
+    fallback: SvelteKitRequestHandler;
+}
+export interface SvelteKitHandlersOptions {
+    /**
+     * The URL path of the route folder, removed before the app routes the request: "/api" for
+     * src/routes/api/[...path]/+server.ts. Requests outside it keep their path. Include SvelteKit's paths.base if set.
+     */
+    prefix?: string;
+}
+/** A SvelteKit handle hook: export const handle = inferloAI(ai), or sequence(inferloAI(ai), ...) to combine it. */
+export type SvelteKitHandle = (input: {
+    event: {
+        locals: object;
+    };
+    resolve: (event: any, opts?: any) => Response | Promise<Response>;
+}) => Response | Promise<Response>;
+/**
+ * Request handlers that run a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP) from a
+ * SvelteKit rest route: export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, fallback } = toSvelteKitHandlers(app).
+ */
+export declare function toSvelteKitHandlers(app: Pick<InferloApp<any>, "fetch">, options?: SvelteKitHandlersOptions): SvelteKitHandlers;
+/**
+ * A SvelteKit handle hook that puts an AI client (createAI(...) or an Inferlo app's app.ai) on every request as
+ * event.locals.ai, for load functions, form actions and +server.ts files: export const handle = inferloAI(ai) in
+ * src/hooks.server.ts, or sequence(inferloAI(ai), yourHandle).
+ */
+export declare function inferloAI(ai: AI): SvelteKitHandle;

package/dist/sveltekit.js

@@ -0,0 +1,68 @@
+import { assertAIClient } from "./ai-client.js";
+import { clientIps } from "./client-ip.js";
+import { InferloError } from "./errors.js";
+import { normalizePrefix, stripPrefix } from "./serve.js";
+const fix = 'Pass the app from createApp and the route folder\'s path: export const { GET, POST, fallback } = toSvelteKitHandlers(app, { prefix: "/api" }).';
+/**
+ * Request handlers that run a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP) from a
+ * SvelteKit rest route: export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, fallback } = toSvelteKitHandlers(app).
+ */
+export function toSvelteKitHandlers(app, options = {}) {
+    if (!app || typeof app.fetch !== "function") {
+        throw new InferloError("IL5022", "toSvelteKitHandlers() needs an Inferlo app (the value returned by createApp).", { fix });
+    }
+    if (options === null || typeof options !== "object" || (options.prefix !== undefined && (typeof options.prefix !== "string" || !options.prefix.startsWith("/")))) {
+        throw new InferloError("IL5022", 'toSvelteKitHandlers() prefix must be a path that starts with /, such as "/api".', { fix });
+    }
+    const prefix = normalizePrefix(options.prefix);
+    const handle = async (event) => {
+        const incoming = event?.request;
+        if (!(incoming instanceof Request)) {
+            throw new InferloError("IL5022", "toSvelteKitHandlers()'s handlers were called with something that is not a SvelteKit request event.", {
+                fix: "Export them from a +server.ts file so SvelteKit calls them: export const { GET, POST, fallback } = toSvelteKitHandlers(app, { prefix: \"/api\" }).",
+            });
+        }
+        let request = incoming;
+        if (prefix) {
+            const url = new URL(incoming.url);
+            const stripped = stripPrefix(url.pathname, prefix);
+            if (stripped !== null) {
+                url.pathname = stripped;
+                const hasBody = incoming.body !== null && incoming.method !== "GET" && incoming.method !== "HEAD";
+                const init = {
+                    method: incoming.method,
+                    headers: incoming.headers,
+                    body: hasBody ? incoming.body : undefined,
+                    signal: incoming.signal,
+                    redirect: incoming.redirect,
+                };
+                if (hasBody)
+                    init.duplex = "half";
+                request = new Request(url, init);
+            }
+        }
+        try {
+            const ip = event.getClientAddress?.();
+            if (typeof ip === "string" && ip)
+                clientIps.set(request, ip);
+        }
+        catch {
+            // The adapter cannot tell the client address (for example while prerendering).
+        }
+        return app.fetch(request);
+    };
+    return Object.freeze({ GET: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle, HEAD: handle, OPTIONS: handle, fallback: handle });
+}
+/**
+ * A SvelteKit handle hook that puts an AI client (createAI(...) or an Inferlo app's app.ai) on every request as
+ * event.locals.ai, for load functions, form actions and +server.ts files: export const handle = inferloAI(ai) in
+ * src/hooks.server.ts, or sequence(inferloAI(ai), yourHandle).
+ */
+export function inferloAI(ai) {
+    assertAIClient(ai, 'Pass createAI({ providers, models }) from "@browserlessapi/inferlo/ai", or an Inferlo app\'s app.ai: export const handle = inferloAI(ai).');
+    return ({ event, resolve }) => {
+        event.locals.ai = ai;
+        return resolve(event);
+    };
+}
+//# sourceMappingURL=sveltekit.js.map

package/dist/sveltekit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sveltekit.js","sourceRoot":"","sources":["../src/sveltekit.ts"],"names":[],"mappings":"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"}

package/dist/tracing.d.ts

@@ -0,0 +1,118 @@
+/**
+ * OpenTelemetry tracing, with no dependency: pass the OpenTelemetry API you already use.
+ *
+ *   import * as otel from "@opentelemetry/api";
+ *   createApp({ tracing: { api: otel } })
+ *
+ * Every request gets a server span ("GET /tickets/:id") that continues the caller's trace (W3C traceparent, through
+ * the propagator your OpenTelemetry SDK registers), runs the handler inside it so spans you or instrumentations
+ * start nest under it, and puts traceId and spanId on the request's log entries. AI calls get client spans with the
+ * model, tokens and cost (also with createAI({ tracing }) on its own), and database queries made while a request
+ * or job is traced get client spans with the table and operation. Without an SDK, the API's no-op tracer is used
+ * and nothing is recorded.
+ */
+import type { Adapter } from "./db/types.ts";
+/** The parts of a span Inferlo uses (an @opentelemetry/api Span). */
+export interface OtelSpan {
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+        traceFlags: number;
+    };
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: unknown): void;
+    updateName(name: string): unknown;
+    end(): void;
+    isRecording(): boolean;
+}
+/** The parts of @opentelemetry/api Inferlo uses: import * as otel from "@opentelemetry/api", then { api: otel }. */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string, version?: string): {
+            startSpan(name: string, options?: {
+                kind?: number;
+                attributes?: Record<string, string | number | boolean>;
+            }, context?: unknown): OtelSpan;
+        };
+        setSpan(context: unknown, span: OtelSpan): unknown;
+        /** The span of a context. Database spans are only started inside one (a request or a job). */
+        getSpan?(context: unknown): OtelSpan | undefined;
+    };
+    context: {
+        active(): unknown;
+        with<T>(context: unknown, fn: () => T): T;
+    };
+    propagation: {
+        extract(context: unknown, carrier: unknown, getter?: unknown): unknown;
+        /** Writes the trace of a context into a carrier (traceparent), so a queued job continues it. */
+        inject?(context: unknown, carrier: unknown, setter?: unknown): void;
+    };
+    SpanKind: {
+        SERVER: number;
+        CLIENT?: number;
+        CONSUMER?: number;
+    };
+    SpanStatusCode: {
+        ERROR: number;
+    };
+}
+export interface TracingConfig {
+    /** The OpenTelemetry API: import * as otel from "@opentelemetry/api", then createApp({ tracing: { api: otel } }). */
+    api: OtelApi;
+    /** The tracer name. Default: the app's name (createApp), or "inferlo" (createAI on its own). */
+    tracerName?: string;
+}
+type Attributes = Record<string, string | number | boolean>;
+export interface RequestTracing {
+    /** Starts the server span of a request and runs fn inside it. */
+    run<T>(req: Request, url: URL, fn: (span: OtelSpan) => Promise<T>): Promise<T>;
+}
+/** Checks a tracing option (createApp or createAI) and returns it, or undefined without tracing. */
+export declare function checkTracing(option: unknown, where: "createApp" | "createAI"): TracingConfig | undefined;
+/** Checks createApp({ tracing }) and returns the request tracer, or undefined without tracing. */
+export declare function requestTracing(option: unknown, appName: string, appVersion: string): RequestTracing | undefined;
+/** Client spans for calls Inferlo makes: AI models and the database. */
+export interface ClientTracing {
+    /** Starts a client span under the active one. The caller ends it (with end or fail). */
+    start(name: string, attributes: Attributes): OtelSpan;
+    /** Runs fn inside a client span that is active while fn runs, and ends it; errors are recorded on it. */
+    run<T>(name: string, attributes: Attributes, fn: (span: OtelSpan) => Promise<T>): Promise<T>;
+    /** Records an error on a span and ends it. */
+    fail(span: OtelSpan, error: unknown): void;
+    /** True while a span (a request's or a job's) is active. */
+    inSpan(): boolean;
+}
+export declare function clientTracing(config: TracingConfig, defaultName: string, version?: string): ClientTracing;
+/**
+ * Wraps a database adapter so its queries get client spans ("SELECT tickets") while a request or job is traced.
+ * Queries outside a trace (startup, the job worker polling for work) are not traced. Values are never recorded,
+ * only the parameterised SQL of raw queries.
+ */
+export declare function traceAdapter(adapter: Adapter, tracing: ClientTracing): Adapter;
+/** traceId and spanId for log entries, when the span belongs to a real trace. */
+export declare function traceFields(span: OtelSpan | undefined): {
+    traceId?: string;
+    spanId?: string;
+};
+/** The trace a queued job carries from where it was enqueued (W3C trace context). */
+export interface JobTraceContext {
+    traceparent?: string;
+    tracestate?: string;
+}
+export interface JobTracing {
+    /** The trace of the active span, to store with a job that is enqueued now. Empty outside a trace. */
+    capture(): JobTraceContext;
+    /** Runs one attempt of a job in a span that continues the trace it was enqueued in (cron jobs start a new trace). */
+    run<T extends string>(job: {
+        id: string;
+        name: string;
+        attempts: number;
+        trace?: JobTraceContext;
+    }, fn: (fail: (error: unknown) => void) => Promise<T>): Promise<T>;
+}
+export declare function jobTracing(config: TracingConfig, defaultName: string, version?: string): JobTracing;
+export {};

package/dist/tracing.js

@@ -0,0 +1,204 @@
+import { InferloError } from "./errors.js";
+/** CLIENT and CONSUMER in @opentelemetry/api's SpanKind (the same in every 1.x release). */
+const CLIENT_KIND = 2;
+const CONSUMER_KIND = 4;
+/** Reads incoming trace headers (traceparent, tracestate, baggage) for the propagator. */
+const headerGetter = {
+    get(carrier, key) {
+        return carrier.get(key) ?? undefined;
+    },
+    keys(carrier) {
+        return [...carrier.keys()];
+    },
+};
+const INVALID_TRACE = "00000000000000000000000000000000";
+/** Checks a tracing option (createApp or createAI) and returns it, or undefined without tracing. */
+export function checkTracing(option, where) {
+    if (option === undefined || option === false)
+        return undefined;
+    const config = option;
+    const api = config?.api;
+    const valid = config !== null &&
+        typeof config === "object" &&
+        typeof api?.trace?.getTracer === "function" &&
+        typeof api.trace.setSpan === "function" &&
+        typeof api.context?.with === "function" &&
+        typeof api.context.active === "function" &&
+        typeof api.propagation?.extract === "function" &&
+        typeof api.SpanKind?.SERVER === "number" &&
+        typeof api.SpanStatusCode?.ERROR === "number" &&
+        (config.tracerName === undefined || (typeof config.tracerName === "string" && config.tracerName.length > 0));
+    if (!valid) {
+        throw new InferloError("IL6030", "Invalid tracing options: tracing needs { api } with the OpenTelemetry API.", {
+            fix: `Install @opentelemetry/api (and an OpenTelemetry SDK that exports the spans), then: import * as otel from "@opentelemetry/api"; ${where}({ tracing: { api: otel } }).`,
+        });
+    }
+    return config;
+}
+/** Checks createApp({ tracing }) and returns the request tracer, or undefined without tracing. */
+export function requestTracing(option, appName, appVersion) {
+    const config = checkTracing(option, "createApp");
+    if (!config)
+        return undefined;
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? appName, appVersion);
+    return {
+        run(req, url, fn) {
+            const method = req.method.toUpperCase();
+            const parent = api.propagation.extract(api.context.active(), req.headers, headerGetter);
+            const attributes = {
+                "http.request.method": method,
+                "url.path": url.pathname,
+                "url.scheme": url.protocol.replace(/:$/, ""),
+                "server.address": url.hostname,
+            };
+            if (url.port)
+                attributes["server.port"] = Number(url.port);
+            const agent = req.headers.get("user-agent");
+            if (agent)
+                attributes["user_agent.original"] = agent;
+            const span = tracer.startSpan(method, { kind: api.SpanKind.SERVER, attributes }, parent);
+            return api.context.with(api.trace.setSpan(parent, span), () => fn(span));
+        },
+    };
+}
+export function clientTracing(config, defaultName, version) {
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? defaultName, version);
+    const kind = api.SpanKind.CLIENT ?? CLIENT_KIND;
+    const fail = (span, error) => {
+        span.recordException(error instanceof Error ? error : String(error));
+        const code = error?.code;
+        if (typeof code === "string")
+            span.setAttribute("error.type", code);
+        else
+            span.setAttribute("error.type", error instanceof Error ? error.name : "Error");
+        span.setStatus({ code: api.SpanStatusCode.ERROR });
+        span.end();
+    };
+    const start = (name, attributes) => tracer.startSpan(name, { kind, attributes }, api.context.active());
+    return {
+        start,
+        fail,
+        async run(name, attributes, fn) {
+            const span = start(name, attributes);
+            let result;
+            try {
+                result = await api.context.with(api.trace.setSpan(api.context.active(), span), () => fn(span));
+            }
+            catch (error) {
+                fail(span, error);
+                throw error;
+            }
+            span.end();
+            return result;
+        },
+        inSpan() {
+            if (!api.trace.getSpan)
+                return true;
+            const active = api.trace.getSpan(api.context.active());
+            return active !== undefined && active.spanContext().traceId !== INVALID_TRACE;
+        },
+    };
+}
+const SQL_OPERATION = /^\s*([a-z]+)/i;
+/**
+ * Wraps a database adapter so its queries get client spans ("SELECT tickets") while a request or job is traced.
+ * Queries outside a trace (startup, the job worker polling for work) are not traced. Values are never recorded,
+ * only the parameterised SQL of raw queries.
+ */
+export function traceAdapter(adapter, tracing) {
+    const system = adapter.dialect === "postgres" ? "postgresql" : adapter.dialect;
+    const traced = (operation, table, query, fn) => {
+        if (!tracing.inSpan())
+            return fn();
+        const attributes = { "db.system.name": system, "db.operation.name": operation };
+        if (table)
+            attributes["db.collection.name"] = table;
+        if (query)
+            attributes["db.query.text"] = query;
+        return tracing.run(table ? `${operation} ${table}` : operation, attributes, fn);
+    };
+    const wrapped = {
+        ...adapter,
+        insert: (model, row) => traced("INSERT", model.name, undefined, () => adapter.insert(model, row)),
+        select: (model, query) => traced("SELECT", model.name, undefined, () => adapter.select(model, query)),
+        update: (model, where, patch) => traced("UPDATE", model.name, undefined, () => adapter.update(model, where, patch)),
+        delete: (model, where) => traced("DELETE", model.name, undefined, () => adapter.delete(model, where)),
+        count: (model, where) => traced("COUNT", model.name, undefined, () => adapter.count(model, where)),
+    };
+    if (adapter.transaction)
+        wrapped.transaction = (fn) => adapter.transaction((tx) => fn(traceAdapter(tx, tracing)));
+    if (adapter.sql) {
+        wrapped.sql = (text, params) => traced((SQL_OPERATION.exec(text)?.[1] ?? "SQL").toUpperCase(), undefined, text, () => adapter.sql(text, params));
+    }
+    return wrapped;
+}
+/** traceId and spanId for log entries, when the span belongs to a real trace. */
+export function traceFields(span) {
+    const context = span?.spanContext();
+    if (!context || context.traceId === INVALID_TRACE)
+        return {};
+    return { traceId: context.traceId, spanId: context.spanId };
+}
+const carrierGetter = {
+    get(carrier, key) {
+        return key === "traceparent" || key === "tracestate" ? carrier[key] : undefined;
+    },
+    keys(carrier) {
+        return Object.keys(carrier);
+    },
+};
+const TRACEPARENT = /^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+export function jobTracing(config, defaultName, version) {
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? defaultName, version);
+    const kind = api.SpanKind.CONSUMER ?? CONSUMER_KIND;
+    return {
+        capture() {
+            if (!api.propagation.inject)
+                return {};
+            const carrier = {};
+            api.propagation.inject(api.context.active(), carrier);
+            const trace = {};
+            if (typeof carrier.traceparent === "string" && TRACEPARENT.test(carrier.traceparent)) {
+                trace.traceparent = carrier.traceparent;
+                if (typeof carrier.tracestate === "string" && carrier.tracestate.length <= 512)
+                    trace.tracestate = carrier.tracestate;
+            }
+            return trace;
+        },
+        async run(job, fn) {
+            const parent = job.trace?.traceparent ? api.propagation.extract(api.context.active(), job.trace, carrierGetter) : api.context.active();
+            const span = tracer.startSpan(`process ${job.name}`, {
+                kind,
+                attributes: {
+                    "messaging.system": "inferlo",
+                    "messaging.operation.type": "process",
+                    "messaging.destination.name": job.name,
+                    "messaging.message.id": job.id,
+                    "inferlo.job.attempt": job.attempts,
+                },
+            }, parent);
+            const fail = (error) => {
+                span.recordException(error instanceof Error ? error : String(error));
+                const code = error?.code;
+                span.setAttribute("error.type", typeof code === "string" ? code : error instanceof Error ? error.name : "Error");
+                span.setStatus({ code: api.SpanStatusCode.ERROR });
+            };
+            try {
+                const outcome = await api.context.with(api.trace.setSpan(parent, span), () => fn(fail));
+                span.setAttribute("inferlo.job.outcome", outcome);
+                return outcome;
+            }
+            catch (error) {
+                fail(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        },
+    };
+}
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -10,14 +10,18 @@ Key rules: routes are private unless `auth: "public"`; validate input with `t.*`
 - [Configuration](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/config.md): config({ schema, secrets, environments }), typed settings validated at startup, secrets redacted
 - [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, deprecated routes (Deprecation and Sunset headers)
-- [Auth](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/auth.md): auth.resolve, roles, bearer API keys, passwords
+- [Routes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/routes.md): options, handler context, return values, errors, middleware, deprecated routes (Deprecation and Sunset headers), API versions with apiVersion("v1", routes) and an OpenAPI document per version
+- [Auth](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/auth.md): auth.resolve, roles, permissions() with can() and authorize() and the route permission option, 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
+- [Modules](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/modules.md): module("billing", { imports, models, routes, jobs, provides }) splits a large app into feature modules with explicit dependencies, createApp({ modules }), checked at startup and shown in describe
 - [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)
-- [Use with other frameworks](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/integrations.md): the AI module in any framework, toNodeHandler and fromNodeRequest to mount an app in Express, Fastify, NestJS or node:http, inferloAI() middleware for Hono (c.var.ai), Express (req.ai), Elysia (ai) and tRPC (ctx.ai), inferloPlugin for Fastify (request.ai, app under a prefix), InferloModule for NestJS, an AdonisJS provider (ctx.ai, config/ai.ts), InferloAI and inferloAI() for Ts.ED injection, trpcTools() for tRPC procedures as AI tools
+- [Use with other frameworks](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/integrations.md): the AI module in any framework, toNodeHandler and fromNodeRequest to mount an app in Express, Fastify, NestJS or node:http (fallthrough: true passes unmatched requests to the host), inferloAI() middleware for Hono (c.var.ai), Express (req.ai), Koa (ctx.ai), Elysia (ai) and tRPC (ctx.ai), toKoaMiddleware() to mount an app in Koa, inferloPlugin for Fastify (request.ai, app under a prefix), InferloModule for NestJS, an AdonisJS provider (ctx.ai, config/ai.ts), InferloAI and inferloAI() for Ts.ED injection, trpcTools() for tRPC procedures as AI tools, toNextHandlers() for Next.js App Router route handlers, an Encore.ts raw endpoint serving the app with toNodeHandler(app, { prefix }) and createAI in Encore services
 - [Migrate from Express](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-express.md): move an Express app to Inferlo route by route at the same URLs, with a concept mapping table, shared auth and tests
+- [Migrate from NestJS](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-nestjs.md): move a NestJS app to Inferlo route by route at the same URLs with toNodeHandler(app, { fallthrough: true }), Nest modules, providers, guards, pipes and DTOs mapped to Inferlo modules, plain functions, auth and schemas
+- [Migrate from Hono](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-hono.md): move a Hono app to Inferlo route by route at the same URLs with hono.all("*", (c) => inferlo.fetch(c.req.raw)), Hono validators, middleware, sub-apps and basePath mapped to Inferlo schemas, createApp options, modules and apiVersion
+- [Migrate from Koa](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-koa.md): move a Koa app to Inferlo route by route at the same URLs with toKoaMiddleware(app, { fallthrough: true }) before the Koa router, @koa/router routes, ctx.throw, body parsers and Koa middleware mapped to Inferlo routes, schemas, errors and createApp options
 - [Security](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/security.md): secure defaults and security headers (createApp({ secureHeaders }))
 - [Observability](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/observability.md): request ids (X-Request-Id, ctx.requestId), request logs and JSON logs with createApp({ logging: { format: "json", requests: true } }), your own logger, Prometheus metrics with createApp({ metrics: { token } })
 - [Deployment](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/deploy.md): Node, Bun, Deno, edge, health and readiness endpoints, graceful shutdown with app.close()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserlessapi/inferlo",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The enterprise-ready TypeScript backend framework, with AI models built in: routing, validation, PostgreSQL and migrations, auth, rate limiting, jobs, OpenAPI and MCP, plus Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible models.",
   "type": "module",
   "license": "MIT",
@@ -55,14 +55,42 @@
       "types": "./dist/fastify.d.ts",
       "default": "./dist/fastify.js"
     },
+    "./h3": {
+      "types": "./dist/h3.d.ts",
+      "default": "./dist/h3.js"
+    },
+    "./hapi": {
+      "types": "./dist/hapi.d.ts",
+      "default": "./dist/hapi.js"
+    },
     "./hono": {
       "types": "./dist/hono.d.ts",
       "default": "./dist/hono.js"
     },
+    "./lambda": {
+      "types": "./dist/lambda.d.ts",
+      "default": "./dist/lambda.js"
+    },
+    "./koa": {
+      "types": "./dist/koa.d.ts",
+      "default": "./dist/koa.js"
+    },
+    "./nextjs": {
+      "types": "./dist/nextjs.d.ts",
+      "default": "./dist/nextjs.js"
+    },
     "./nestjs": {
       "types": "./dist/nestjs.d.ts",
       "default": "./dist/nestjs.js"
     },
+    "./react-router": {
+      "types": "./dist/react-router.d.ts",
+      "default": "./dist/react-router.js"
+    },
+    "./sveltekit": {
+      "types": "./dist/sveltekit.d.ts",
+      "default": "./dist/sveltekit.js"
+    },
     "./tsed": {
       "types": "./dist/tsed.d.ts",
       "default": "./dist/tsed.js"
@@ -93,7 +121,7 @@
   "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 && tsc --noEmit -p examples/with-hono && tsc --noEmit -p examples/with-express && tsc --noEmit -p examples/with-fastify && tsc --noEmit -p examples/with-elysia && tsc --noEmit -p examples/with-nestjs && tsc --noEmit -p examples/with-trpc && tsc --noEmit -p examples/with-adonisjs && tsc --noEmit -p examples/with-tsed",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/helpdesk && tsc --noEmit -p examples/with-hono && tsc --noEmit -p examples/with-express && tsc --noEmit -p examples/with-fastify && tsc --noEmit -p examples/with-elysia && tsc --noEmit -p examples/with-nestjs && tsc --noEmit -p examples/with-trpc && tsc --noEmit -p examples/with-adonisjs && tsc --noEmit -p examples/with-tsed && tsc --noEmit -p examples/with-encore && tsc --noEmit -p examples/with-koa && tsc --noEmit -p examples/with-nextjs && tsc --noEmit -p examples/with-nitro && tsc --noEmit -p examples/with-sveltekit && tsc --noEmit -p examples/with-react-router && tsc --noEmit -p examples/with-lambda && tsc --noEmit -p examples/with-hapi",
     "test": "node --test --test-reporter=spec \"test/**/*.test.ts\" \"examples/*/test/*.test.ts\"",
     "test:bun": "bun test test/",
     "llms": "node scripts/build-llms.ts",
@@ -101,18 +129,25 @@
     "bench": "node bench/run.ts"
   },
   "peerDependencies": {
+    "@opentelemetry/api": ">=1.3.0",
     "pg": ">=8"
   },
   "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     }
   },
   "devDependencies": {
     "@adonisjs/core": "^6.21.0",
+    "@hapi/hapi": "^21.4.13",
     "@nestjs/common": "^12.3.3",
     "@nestjs/core": "^12.3.3",
     "@nestjs/platform-express": "^12.3.3",
+    "@opentelemetry/api": "^1.10.0",
+    "@sveltejs/kit": "^2.70.3",
     "@trpc/server": "^11.24.0",
     "@tsed/core": "^8.45.0",
     "@tsed/di": "^8.45.0",
@@ -121,13 +156,20 @@
     "@tsed/platform-params": "^8.45.0",
     "@tsed/schema": "^8.45.0",
     "@types/express": "^5.0.6",
+    "@types/koa": "^3.0.3",
     "@types/node": "^22.18.0",
     "@types/pg": "^8.15.0",
     "elysia": "^1.4.30",
+    "encore.dev": "^1.58.8",
     "express": "^5.3.0",
     "fastify": "^5.12.8",
+    "h3": "^2.0.8",
     "hono": "^4.13.16",
+    "koa": "^3.3.0",
+    "next": "^16.4.5",
     "pg": "^8.16.0",
+    "react": "^19.3.1",
+    "react-router": "^8.5.1",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "typescript": "^5.9.3"