@browserlessapi/inferlo 0.4.0 → 0.6.0

package/dist/metrics.js

@@ -0,0 +1,184 @@
+/**
+ * Metrics: request, job and AI counters and histograms in the Prometheus text format.
+ *
+ *   createApp({ metrics: { token: settings.METRICS_TOKEN } })
+ *
+ * serves GET /metrics for Prometheus, Grafana Agent, the OpenTelemetry Collector, Datadog and others.
+ */
+import { InferloError } from "./errors.js";
+/** Default histogram buckets in seconds, the same as the Prometheus client libraries. */
+export const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+/** Methods outside this list are counted as "OTHER", so clients cannot create unlimited series. */
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+/** Checks createApp({ metrics }) and returns it with defaults, or undefined when metrics are off. */
+export function resolveMetrics(option, taken) {
+    if (option === undefined || option === false)
+        return undefined;
+    const problems = [];
+    let path = "/metrics";
+    let token;
+    let buckets = DEFAULT_BUCKETS;
+    if (option !== true) {
+        if (!option || typeof option !== "object" || Array.isArray(option))
+            problems.push("metrics must be true or an object such as { token: settings.METRICS_TOKEN }");
+        else {
+            const { path: p, token: tk, buckets: b, ...rest } = option;
+            if (p !== undefined) {
+                if (typeof p !== "string" || !p.startsWith("/"))
+                    problems.push(`path must start with "/", got ${JSON.stringify(p)}`);
+                else
+                    path = p;
+            }
+            // { token: settings.METRICS_TOKEN } with the variable unset must not make the endpoint public.
+            if (tk === undefined && "token" in option)
+                problems.push("token is undefined (is the variable it comes from set?); leave token out only for a public endpoint");
+            else if (tk !== undefined) {
+                if (typeof tk !== "string" || tk.length < 16)
+                    problems.push("token must be a string of at least 16 characters (a random secret from configuration)");
+                else
+                    token = tk;
+            }
+            if (b !== undefined) {
+                const ok = Array.isArray(b) && b.length > 0 && b.every((n, i) => typeof n === "number" && Number.isFinite(n) && n > 0 && (i === 0 || n > b[i - 1]));
+                if (!ok)
+                    problems.push("buckets must be increasing positive numbers of seconds, such as [0.1, 0.5, 1, 5]");
+                else
+                    buckets = [...b];
+            }
+            for (const key of Object.keys(rest))
+                problems.push(`unknown option "${key}"`);
+        }
+    }
+    for (const { path: other, what } of taken)
+        if (!problems.length && other && other.replace(/\/+$/, "") === path.replace(/\/+$/, ""))
+            problems.push(`path ${path} is also ${what}`);
+    if (problems.length) {
+        throw new InferloError("IL6020", `Invalid metrics options: ${problems.join("; ")}.`, {
+            fix: 'Use createApp({ metrics: true }) or createApp({ metrics: { path: "/metrics", token: settings.METRICS_TOKEN } }).',
+        });
+    }
+    return { path, token, buckets };
+}
+/** True when the request carries Authorization: Bearer <token>, compared in constant time. */
+export function hasMetricsToken(req, token) {
+    const header = req.headers.get("authorization") ?? "";
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    if (!match)
+        return false;
+    const a = new TextEncoder().encode(match[1]);
+    const b = new TextEncoder().encode(token);
+    let diff = a.length ^ b.length;
+    for (let i = 0; i < b.length; i++)
+        diff |= (a[i] ?? 0) ^ b[i];
+    return diff === 0;
+}
+function key(labels) {
+    return JSON.stringify(Object.entries(labels));
+}
+function escape(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function labelText(labels) {
+    const parts = Object.entries(labels).map(([k, v]) => `${k}="${escape(v)}"`);
+    return parts.length ? `{${parts.join(",")}}` : "";
+}
+function number(n) {
+    if (n === Infinity)
+        return "+Inf";
+    return String(Math.round(n * 1e9) / 1e9);
+}
+export function createMetrics(info, buckets) {
+    const counters = new Map();
+    const histograms = new Map();
+    let inFlight = 0;
+    const add = (name, labels, value) => {
+        let series = counters.get(name);
+        if (!series)
+            counters.set(name, (series = new Map()));
+        const k = key(labels);
+        const entry = series.get(k);
+        if (entry)
+            entry.value += value;
+        else
+            series.set(k, { labels, value });
+    };
+    const observe = (name, labels, value) => {
+        let series = histograms.get(name);
+        if (!series)
+            histograms.set(name, (series = new Map()));
+        const k = key(labels);
+        let h = series.get(k);
+        if (!h)
+            series.set(k, (h = { labels, counts: buckets.map(() => 0), sum: 0, count: 0 }));
+        for (let i = 0; i < buckets.length; i++)
+            if (value <= buckets[i])
+                h.counts[i]++;
+        h.sum += value;
+        h.count++;
+    };
+    const help = {
+        inferlo_info: ["gauge", "The app's name and version and the Inferlo version (always 1)."],
+        inferlo_http_requests_total: ["counter", "HTTP requests by method, route pattern and status."],
+        inferlo_http_request_duration_seconds: ["histogram", "Time until the response headers were ready, by method and route pattern."],
+        inferlo_http_requests_in_flight: ["gauge", "HTTP requests being handled now."],
+        inferlo_job_runs_total: ["counter", "Job attempts run in this process, by job and outcome (done, retried or failed)."],
+        inferlo_job_duration_seconds: ["histogram", "Time each job attempt took, by job."],
+        inferlo_ai_calls_total: ["counter", "AI calls by requested alias or model, the model that answered, and kind (generate, stream or embed)."],
+        inferlo_ai_tokens_total: ["counter", "AI tokens by requested alias or model, the model that answered, and type (input or output)."],
+        inferlo_ai_cost_usd_total: ["counter", "AI cost in US dollars from ai.pricing, by requested alias or model and the model that answered."],
+        inferlo_ai_call_duration_seconds: ["histogram", "Time each AI call took, by requested alias or model and the model that answered."],
+    };
+    return {
+        request(method, route, status, seconds) {
+            const m = method.toUpperCase();
+            const labels = { method: METHODS.has(m) ? m : "OTHER", route };
+            add("inferlo_http_requests_total", { ...labels, status: String(status) }, 1);
+            observe("inferlo_http_request_duration_seconds", labels, seconds);
+        },
+        inFlight(delta) {
+            inFlight += delta;
+        },
+        job(name, outcome, seconds) {
+            add("inferlo_job_runs_total", { job: name, outcome }, 1);
+            observe("inferlo_job_duration_seconds", { job: name }, seconds);
+        },
+        ai(usage) {
+            const labels = { requested: usage.requested, model: usage.model };
+            add("inferlo_ai_calls_total", { ...labels, kind: usage.kind }, 1);
+            add("inferlo_ai_tokens_total", { ...labels, type: "input" }, usage.inputTokens);
+            add("inferlo_ai_tokens_total", { ...labels, type: "output" }, usage.outputTokens);
+            add("inferlo_ai_cost_usd_total", labels, usage.cost);
+            observe("inferlo_ai_call_duration_seconds", labels, usage.durationMs / 1000);
+        },
+        render() {
+            const lines = [];
+            const header = (name) => {
+                const [type, text] = help[name];
+                lines.push(`# HELP ${name} ${text}`, `# TYPE ${name} ${type}`);
+            };
+            header("inferlo_info");
+            lines.push(`inferlo_info${labelText(info)} 1`);
+            header("inferlo_http_requests_in_flight");
+            lines.push(`inferlo_http_requests_in_flight ${inFlight}`);
+            for (const name of Object.keys(help)) {
+                const series = counters.get(name);
+                if (series) {
+                    header(name);
+                    for (const { labels, value } of series.values())
+                        lines.push(`${name}${labelText(labels)} ${number(value)}`);
+                }
+                const hist = histograms.get(name);
+                if (hist) {
+                    header(name);
+                    for (const h of hist.values()) {
+                        buckets.forEach((le, i) => lines.push(`${name}_bucket${labelText({ ...h.labels, le: number(le) })} ${h.counts[i]}`));
+                        lines.push(`${name}_bucket${labelText({ ...h.labels, le: "+Inf" })} ${h.count}`);
+                        lines.push(`${name}_sum${labelText(h.labels)} ${number(h.sum)}`, `${name}_count${labelText(h.labels)} ${h.count}`);
+                    }
+                }
+            }
+            return lines.join("\n") + "\n";
+        },
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/dist/module.d.ts

@@ -0,0 +1,52 @@
+import type { JobSource } from "./jobs.ts";
+import type { AnyModel } from "./model.ts";
+import type { RouteSource } from "./app.ts";
+export interface ModuleOptions<Models extends readonly AnyModel[] = readonly AnyModel[], Provides extends Record<string, unknown> = Record<string, unknown>> {
+    /** One sentence about what the module does, shown in describe() and as the OpenAPI tag description. */
+    description?: string;
+    /** Modules this module depends on. Each must also be passed to createApp({ modules }). */
+    imports?: readonly AnyModule[];
+    /** The models (tables) this module owns. */
+    models?: Models;
+    /** The module's routes: routes, arrays or route files (import * as invoices from "./routes/invoices.ts"). */
+    routes?: readonly RouteSource[];
+    /** The module's background jobs and crons. */
+    jobs?: readonly JobSource[];
+    /** What other modules may use, by name: plain functions and values, read as billing.provides.createInvoice. */
+    provides?: Provides;
+}
+export interface Module<Name extends string = string, Models extends readonly AnyModel[] = readonly AnyModel[], Provides extends Record<string, unknown> = Record<string, unknown>> {
+    readonly kind: "inferlo.module";
+    readonly name: Name;
+    readonly description?: string;
+    readonly imports: readonly AnyModule[];
+    readonly models: Models;
+    readonly routes: readonly RouteSource[];
+    readonly jobs: readonly JobSource[];
+    readonly provides: Readonly<Provides>;
+}
+export type AnyModule = Module<string, readonly AnyModel[], any>;
+/** The models of a list of modules, in order: ModuleModels<[typeof users, typeof billing]>. */
+export type ModuleModels<M extends readonly AnyModule[]> = M extends readonly [infer H extends AnyModule, ...infer R extends readonly AnyModule[]] ? [...H["models"], ...ModuleModels<R>] : M extends readonly [] ? [] : M[number]["models"][number][];
+/**
+ * Define a feature module: module("billing", { imports, models, routes, jobs, provides }).
+ * Register it with createApp({ modules: [billing] }).
+ */
+export declare function module<const Name extends string, const Models extends readonly AnyModel[] = [], const Provides extends Record<string, unknown> = {}>(name: Name, options?: ModuleOptions<Models, Provides>): Module<Name, Models, Provides>;
+export declare function isModule(value: unknown): value is AnyModule;
+/**
+ * Checks createApp({ modules }) and returns the modules with each model's owner. Every imported
+ * module must be registered, names are unique, and a model may only reference models of its own
+ * module, of a module it imports, or of the app itself (createApp({ models })).
+ */
+export declare function resolveModules(option: unknown, appModels: readonly AnyModel[]): {
+    modules: readonly AnyModule[];
+    modelOwner: Map<string, string>;
+};
+/** Which module each route, model and job came from (for describe() and OpenAPI). */
+export interface ModuleInfo {
+    modules: readonly AnyModule[];
+    routeModule: ReadonlyMap<unknown, string>;
+    modelOwner: ReadonlyMap<string, string>;
+    jobModule: ReadonlyMap<string, string>;
+}

package/dist/module.js

@@ -0,0 +1,152 @@
+/**
+ * Feature modules split a large app into parts with explicit dependencies. A module is a plain value:
+ * its models, routes and jobs, the modules it depends on, and what it offers other modules.
+ *
+ *   export const billing = module("billing", {
+ *     imports: [users],                       // modules this one uses
+ *     models: [invoices],
+ *     routes: [invoiceRoutes],                // import * as invoiceRoutes from "./routes.ts"
+ *     jobs: [sendInvoice],
+ *     provides: { createInvoice },            // what other modules may use: billing.provides.createInvoice
+ *   });
+ *
+ *   createApp({ modules: [users, billing] })
+ *
+ * No decorators, no container, no injection: other modules import the module value and call
+ * billing.provides.createInvoice(...) directly. createApp checks that every imported module is
+ * registered and that models only reference models of their own module, an imported module or the
+ * app itself, and describe() shows each module with what it contains.
+ */
+import { InferloError, didYouMean } from "./errors.js";
+const MODULE_NAME = /^[a-z][a-z0-9-]{0,62}$/;
+const OPTION_KEYS = new Set(["description", "imports", "models", "routes", "jobs", "provides"]);
+function invalid(message, fix) {
+    return new InferloError("IL6022", message, { fix });
+}
+function isList(value) {
+    return Array.isArray(value);
+}
+/**
+ * Define a feature module: module("billing", { imports, models, routes, jobs, provides }).
+ * Register it with createApp({ modules: [billing] }).
+ */
+export function module(name, options = {}) {
+    if (typeof name !== "string" || !MODULE_NAME.test(name)) {
+        throw invalid(`Module name ${JSON.stringify(name)} is not valid.`, 'Use lowercase letters, digits and dashes, starting with a letter: module("billing", { ... }).');
+    }
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        throw invalid(`module("${name}") options must be an object.`, `Use module("${name}", { models, routes, jobs, imports, provides }).`);
+    }
+    for (const key of Object.keys(options)) {
+        if (!OPTION_KEYS.has(key)) {
+            throw invalid(`module("${name}") has an unknown option "${key}".${didYouMean(key, OPTION_KEYS)}`, "A module takes description, imports, models, routes, jobs and provides.");
+        }
+    }
+    for (const key of ["imports", "models", "routes", "jobs"]) {
+        if (options[key] !== undefined && !isList(options[key])) {
+            throw invalid(`module("${name}") ${key} must be an array.`, `Use module("${name}", { ${key}: [...] }).`);
+        }
+    }
+    if (options.description !== undefined && typeof options.description !== "string") {
+        throw invalid(`module("${name}") description must be a string.`, "Describe the module in one sentence.");
+    }
+    const imports = options.imports ?? [];
+    for (const [i, dep] of imports.entries()) {
+        if (!isModule(dep)) {
+            throw invalid(`module("${name}") imports[${i}] is not a module.`, "List module values created with module(), for example imports: [users].");
+        }
+        if (dep.name === name)
+            throw invalid(`module("${name}") imports itself.`, `Remove "${name}" from its own imports.`);
+    }
+    if (new Set(imports.map((m) => m.name)).size !== imports.length) {
+        throw invalid(`module("${name}") imports the same module twice.`, "List each module once in imports.");
+    }
+    for (const [i, m] of (options.models ?? []).entries()) {
+        if (typeof m !== "object" || m === null || typeof m.name !== "string" || typeof m.fields !== "object") {
+            throw invalid(`module("${name}") models[${i}] is not a model.`, 'List models created with model("table", { ... }).');
+        }
+    }
+    const provides = options.provides ?? {};
+    if (typeof provides !== "object" || provides === null || Array.isArray(provides)) {
+        throw invalid(`module("${name}") provides must be an object.`, `Use provides: { createInvoice } and call ${name}.provides.createInvoice(...) from other modules.`);
+    }
+    return Object.freeze({
+        kind: "inferlo.module",
+        name,
+        ...(options.description !== undefined ? { description: options.description } : {}),
+        imports: Object.freeze([...imports]),
+        models: Object.freeze([...(options.models ?? [])]),
+        routes: Object.freeze([...(options.routes ?? [])]),
+        jobs: Object.freeze([...(options.jobs ?? [])]),
+        provides: Object.freeze({ ...provides }),
+    });
+}
+export function isModule(value) {
+    return typeof value === "object" && value !== null && value.kind === "inferlo.module";
+}
+function wiring(message, fix) {
+    return new InferloError("IL6023", message, { fix });
+}
+/**
+ * Checks createApp({ modules }) and returns the modules with each model's owner. Every imported
+ * module must be registered, names are unique, and a model may only reference models of its own
+ * module, of a module it imports, or of the app itself (createApp({ models })).
+ */
+export function resolveModules(option, appModels) {
+    if (option === undefined)
+        return { modules: [], modelOwner: new Map() };
+    if (!isList(option))
+        throw wiring("createApp({ modules }) must be an array of modules.", "Use createApp({ modules: [users, billing] }).");
+    const byName = new Map();
+    for (const [i, m] of option.entries()) {
+        if (!isModule(m))
+            throw wiring(`createApp({ modules }) item ${i} is not a module.`, 'Create modules with module("name", { ... }) and pass the values: modules: [users, billing].');
+        const existing = byName.get(m.name);
+        if (existing === m)
+            throw wiring(`The module "${m.name}" is listed twice in createApp({ modules }).`, "List each module once.");
+        if (existing)
+            throw wiring(`Two modules are named "${m.name}".`, "Module names must be unique.");
+        byName.set(m.name, m);
+    }
+    for (const m of byName.values()) {
+        for (const dep of m.imports) {
+            const registered = byName.get(dep.name);
+            if (!registered) {
+                throw wiring(`The module "${m.name}" imports "${dep.name}", which is not in createApp({ modules }).`, `Add ${dep.name} to createApp({ modules: [...] }).`);
+            }
+            if (registered !== dep)
+                throw wiring(`The module "${m.name}" imports a different module also named "${dep.name}".`, "Import the same module value that is passed to createApp({ modules }).");
+        }
+    }
+    const modelOwner = new Map();
+    for (const m of byName.values()) {
+        for (const model of m.models) {
+            const owner = modelOwner.get(model.name);
+            if (owner !== undefined) {
+                throw wiring(`The model "${model.name}" is in the modules "${owner}" and "${m.name}".`, "A model belongs to one module; other modules import that module to use it.");
+            }
+            modelOwner.set(model.name, m.name);
+        }
+    }
+    for (const model of appModels) {
+        const owner = modelOwner.get(model.name);
+        if (owner !== undefined)
+            throw wiring(`The model "${model.name}" is in createApp({ models }) and in the module "${owner}".`, "List the model in one place only.");
+    }
+    for (const m of byName.values()) {
+        const allowed = new Set([m.name, ...m.imports.map((d) => d.name)]);
+        for (const model of m.models) {
+            for (const [field, schema] of Object.entries(model.fields)) {
+                const ref = schema.def.refTable;
+                const owner = ref ? modelOwner.get(ref) : undefined;
+                if (owner !== undefined && !allowed.has(owner)) {
+                    throw new InferloError("IL6024", `${model.name}.${field} in the module "${m.name}" references "${ref}" from the module "${owner}", which "${m.name}" does not import.`, {
+                        fix: `Add ${owner} to the imports of the "${m.name}" module: module("${m.name}", { imports: [${owner}], ... }).`,
+                    });
+                }
+            }
+        }
+    }
+    return { modules: [...byName.values()], modelOwner };
+}
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

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

package/dist/nestjs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Inferlo inside NestJS (11 and later), without a runtime dependency on NestJS:
+ *
+ *   import { INFERLO_AI, InferloModule } from "@browserlessapi/inferlo/nestjs";
+ *
+ *   @Module({ imports: [InferloModule.forRoot({ ai })] })   // or forRootAsync({ inject, useFactory })
+ *   export class AppModule {}
+ *
+ *   @Injectable()
+ *   export class TicketsService {
+ *     constructor(@Inject(INFERLO_AI) private readonly ai: AI) {}
+ *   }
+ *
+ * A whole Inferlo app mounts with app.use("/api", toNodeHandler(inferloApp)) on the Express platform.
+ * This entry point never loads the router, database or jobs code.
+ */
+import type { DynamicModule } from "@nestjs/common";
+import type { AI } from "./ai/index.ts";
+/** Injection token for the AI client: constructor(@Inject(INFERLO_AI) private readonly ai: AI) {}. */
+export declare const INFERLO_AI = "INFERLO_AI";
+export interface InferloModuleOptions {
+    /** The AI client: createAI(...) from @browserlessapi/inferlo/ai, or an Inferlo app's app.ai. */
+    ai: AI;
+    /** Make INFERLO_AI injectable in every module without importing InferloModule again. Default true. */
+    global?: boolean;
+}
+export interface InferloModuleAsyncOptions {
+    /** Modules whose providers useFactory needs, for example ConfigModule. */
+    imports?: DynamicModule["imports"];
+    /** Providers passed to useFactory, in order, for example [ConfigService]. */
+    inject?: unknown[];
+    /** Returns the AI client, for example from configuration: (config) => createAI({ ... }). */
+    useFactory: (...args: any[]) => AI | Promise<AI>;
+    /** Default true, as in forRoot. */
+    global?: boolean;
+}
+/** A NestJS module that provides the AI client as INFERLO_AI. Use InferloModule.forRoot({ ai }) in imports. */
+export declare class InferloModule {
+    /** Provide an AI client you already have. */
+    static forRoot(options: InferloModuleOptions): DynamicModule;
+    /** Create the AI client when Nest starts, from other providers (for example ConfigService). */
+    static forRootAsync(options: InferloModuleAsyncOptions): DynamicModule;
+}

package/dist/nestjs.js

@@ -0,0 +1,47 @@
+import { assertAIClient } from "./ai-client.js";
+import { InferloError } from "./errors.js";
+/** Injection token for the AI client: constructor(@Inject(INFERLO_AI) private readonly ai: AI) {}. */
+export const INFERLO_AI = "INFERLO_AI";
+const fix = 'Pass createAI({ providers, models }) from "@browserlessapi/inferlo/ai", or an Inferlo app\'s app.ai: InferloModule.forRoot({ ai }).';
+/** A NestJS module that provides the AI client as INFERLO_AI. Use InferloModule.forRoot({ ai }) in imports. */
+export class InferloModule {
+    /** Provide an AI client you already have. */
+    static forRoot(options) {
+        if (!options || typeof options !== "object")
+            throw new InferloError("IL5016", "InferloModule.forRoot() needs options with ai.", { fix });
+        assertAIClient(options.ai, fix);
+        return {
+            module: InferloModule,
+            global: options.global ?? true,
+            providers: [{ provide: INFERLO_AI, useValue: options.ai }],
+            exports: [INFERLO_AI],
+        };
+    }
+    /** Create the AI client when Nest starts, from other providers (for example ConfigService). */
+    static forRootAsync(options) {
+        if (!options || typeof options.useFactory !== "function") {
+            throw new InferloError("IL5016", "InferloModule.forRootAsync() needs a useFactory function.", {
+                fix: "Use InferloModule.forRootAsync({ inject: [ConfigService], useFactory: (config) => createAI({ ... }) }).",
+            });
+        }
+        const { useFactory } = options;
+        return {
+            module: InferloModule,
+            global: options.global ?? true,
+            imports: options.imports ?? [],
+            providers: [
+                {
+                    provide: INFERLO_AI,
+                    inject: (options.inject ?? []),
+                    useFactory: async (...args) => {
+                        const ai = await useFactory(...args);
+                        assertAIClient(ai, "useFactory must return createAI({ providers, models }) or an Inferlo app's app.ai.");
+                        return ai;
+                    },
+                },
+            ],
+            exports: [INFERLO_AI],
+        };
+    }
+}
+//# sourceMappingURL=nestjs.js.map

package/dist/nestjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestjs.js","sourceRoot":"","sources":["../src/nestjs.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,sGAAsG;AACtG,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AAoBvC,MAAM,GAAG,GAAG,qIAAqI,CAAC;AAElJ,+GAA+G;AAC/G,MAAM,OAAO,aAAa;IACxB,6CAA6C;IAC7C,MAAM,CAAC,OAAO,CAAC,OAA6B;QAC1C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,gDAAgD,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QACzI,cAAc,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAChC,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;YAC9B,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;YAC1D,OAAO,EAAE,CAAC,UAAU,CAAC;SACtB,CAAC;IACJ,CAAC;IAED,+FAA+F;IAC/F,MAAM,CAAC,YAAY,CAAC,OAAkC;QACpD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;YACzD,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,2DAA2D,EAAE;gBAC5F,GAAG,EAAE,yGAAyG;aAC/G,CAAC,CAAC;QACL,CAAC;QACD,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;QAC/B,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;YAC9B,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;YAC9B,SAAS,EAAE;gBACT;oBACE,OAAO,EAAE,UAAU;oBACnB,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAY;oBACzC,UAAU,EAAE,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;wBACvC,MAAM,EAAE,GAAG,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;wBACrC,cAAc,CAAC,EAAE,EAAE,oFAAoF,CAAC,CAAC;wBACzG,OAAO,EAAE,CAAC;oBACZ,CAAC;iBACF;aACF;YACD,OAAO,EAAE,CAAC,UAAU,CAAC;SACtB,CAAC;IACJ,CAAC;CACF"}

package/dist/nextjs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Inferlo inside Next.js App Router route handlers (Next.js 15 and 16), without a runtime dependency on Next.js:
+ *
+ *   // app/api/[[...path]]/route.ts
+ *   import { toNextHandlers } from "@browserlessapi/inferlo/nextjs";
+ *   import { app } from "@/inferlo/app";
+ *
+ *   export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = toNextHandlers(app, { prefix: "/api" });
+ *
+ * Every request under /api runs through the Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP)
+ * with /api removed from the path. In server actions and other server code, use @browserlessapi/inferlo/ai.
+ * It never loads the router, database or jobs code.
+ */
+import type { App } from "./app.ts";
+/** A Next.js route handler: it takes the Request (a NextRequest in Next.js) and returns a Response. */
+export type NextRouteHandler = (request: Request, context?: unknown) => Promise<Response>;
+/** One route handler per HTTP method, to export from an app/.../route.ts file. */
+export interface NextHandlers {
+    GET: NextRouteHandler;
+    POST: NextRouteHandler;
+    PUT: NextRouteHandler;
+    PATCH: NextRouteHandler;
+    DELETE: NextRouteHandler;
+    HEAD: NextRouteHandler;
+    OPTIONS: NextRouteHandler;
+}
+export interface NextHandlersOptions {
+    /**
+     * The URL path of the route.ts folder, removed before the app routes the request: "/api" for
+     * app/api/[[...path]]/route.ts. Requests outside it keep their path. Include Next.js's basePath if one is set.
+     */
+    prefix?: string;
+}
+/** Route handlers that run a whole Inferlo app from a Next.js catch-all route: export const { GET, POST } = toNextHandlers(app). */
+export declare function toNextHandlers(app: Pick<App<any>, "fetch">, options?: NextHandlersOptions): NextHandlers;

package/dist/nextjs.js

@@ -0,0 +1,33 @@
+import { InferloError } from "./errors.js";
+const fix = 'Pass the app from createApp and a path prefix: export const { GET, POST } = toNextHandlers(app, { prefix: "/api" }).';
+/** Route handlers that run a whole Inferlo app from a Next.js catch-all route: export const { GET, POST } = toNextHandlers(app). */
+export function toNextHandlers(app, options = {}) {
+    if (!app || typeof app.fetch !== "function") {
+        throw new InferloError("IL5020", "toNextHandlers() 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("IL5020", "toNextHandlers() prefix must be a path that starts with /, such as \"/api\".", { fix });
+    }
+    const prefix = (options.prefix ?? "").replace(/\/+$/, "").replace(/\/{2,}/g, "/");
+    const handle = async (request) => {
+        if (!prefix)
+            return app.fetch(request);
+        const url = new URL(request.url);
+        if (url.pathname !== prefix && !url.pathname.startsWith(prefix + "/"))
+            return app.fetch(request);
+        url.pathname = url.pathname.slice(prefix.length) || "/";
+        const hasBody = request.body !== null && request.method !== "GET" && request.method !== "HEAD";
+        const init = {
+            method: request.method,
+            headers: request.headers,
+            body: hasBody ? request.body : undefined,
+            signal: request.signal,
+            redirect: request.redirect,
+        };
+        if (hasBody)
+            init.duplex = "half";
+        return app.fetch(new Request(url, init));
+    };
+    return Object.freeze({ GET: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle, HEAD: handle, OPTIONS: handle });
+}
+//# sourceMappingURL=nextjs.js.map

package/dist/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.js","sourceRoot":"","sources":["../src/nextjs.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAwB3C,MAAM,GAAG,GAAG,sHAAsH,CAAC;AAEnI,oIAAoI;AACpI,MAAM,UAAU,cAAc,CAAC,GAA4B,EAAE,UAA+B,EAAE;IAC5F,IAAI,CAAC,GAAG,IAAI,OAAQ,GAA2B,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACrE,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,0EAA0E,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACxH,CAAC;IACD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACjK,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,8EAA8E,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC5H,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAElF,MAAM,MAAM,GAAqB,KAAK,EAAE,OAAO,EAAE,EAAE;QACjD,IAAI,CAAC,MAAM;YAAE,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC;QACxD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC;QAC/F,MAAM,IAAI,GAAsC;YAC9C,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YACxC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC;QACF,IAAI,OAAO;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAClC,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;AACjI,CAAC"}

package/dist/openapi.d.ts

@@ -1,6 +1,8 @@
-/** OpenAPI 3.1 document generated from routes. Served at /openapi.json by default. */
 import type { App } from "./app.ts";
+import type { ModuleInfo } from "./module.ts";
 export declare function buildOpenAPI(app: App<any>, options: {
     description?: string;
     auth: boolean;
+    modules?: ModuleInfo;
+    version?: string;
 }): Record<string, unknown>;