@browserlessapi/inferlo 0.5.0 → 0.7.0

package/dist/events.d.ts

@@ -0,0 +1,134 @@
+import { InferloError } from "./errors.ts";
+import type { JobDef, JobInput } from "./jobs.ts";
+import { type AnySchema, type Infer, type InferInput } from "./schema.ts";
+import type { JobTraceContext } from "./tracing.ts";
+export interface EventOptions<P extends AnySchema> {
+    /** Schema of the payload. Checked when the event is published. */
+    payload: P;
+    /** One line shown in describe. */
+    summary?: string;
+}
+export interface EventDef<Input = any, Payload = any, S extends AnySchema = AnySchema> {
+    readonly kind: "inferlo.event";
+    /** Lowercase words separated by dots: "order.paid". */
+    readonly name: string;
+    /** The payload schema, also usable as a subscribed job's input: job("send-receipt", { input: orderPaid.payload }). */
+    readonly payload: S;
+    readonly summary?: string;
+    /** Type only: what publish accepts. */
+    readonly $input?: Input;
+    /** Type only: the payload after validation, which subscribed jobs receive. */
+    readonly $payload?: Payload;
+}
+/** What publish accepts for an event. */
+export type EventPayload<E> = E extends EventDef<infer I, any, any> ? I : never;
+/** A subscription: on(event, job) in createApp({ jobs }) queues the job with the payload of every published event. */
+export interface OnDef<E extends EventDef = EventDef, J extends JobDef = JobDef> {
+    readonly kind: "inferlo.on";
+    readonly event: E;
+    readonly job: J;
+}
+export interface PublishOptions {
+    /** The event id. Default: a new UUID. Publishing the same id again queues no job twice (for outboxes and redelivery). */
+    id?: string;
+    /**
+     * The tenant the event belongs to: the subscribed jobs get it (their ctx.db is scoped to it). Default: the tenant
+     * of the request or job that publishes it, none from app.events. Pass null to publish it without a tenant.
+     */
+    tenantId?: string | null;
+}
+export interface PublishedEvent {
+    id: string;
+    name: string;
+    publishedAt: Date;
+    /**
+     * Ids of the jobs for it, one per subscription in this app. Without a transport they are queued now; with one,
+     * they are queued with these ids when this app receives the event.
+     */
+    jobs: string[];
+}
+export interface Events {
+    /** Validate the payload and queue every job subscribed to the event with on(event, job). */
+    publish<E extends EventDef>(event: E, payload: EventPayload<E>, options?: PublishOptions): Promise<PublishedEvent>;
+}
+/** app.events: publish events and see the subscriptions. */
+export interface AppEvents extends Events {
+    /** Events with at least one subscription in this app, in the order they were registered. */
+    readonly list: readonly EventDef[];
+    /** The subscriptions: on(event, job) values in createApp({ jobs }) and in modules. */
+    readonly subscriptions: readonly OnDef[];
+    /** The transport that carries events between services (createApp({ events: { transport } })), or undefined: events stay in this app. */
+    readonly transport: string | undefined;
+    /**
+     * With a transport: take the events waiting for this app's subscriptions and queue their jobs, then return how
+     * many events were received. app.jobs.start() and inferlo worker call it on every poll; call it yourself in tests.
+     * Without a transport it returns 0.
+     */
+    receive(): Promise<number>;
+}
+/** One published event as a transport carries it. */
+export interface EventMessage {
+    /** The event id: the same id queues each subscribed job once, also when the transport delivers it twice. */
+    id: string;
+    name: string;
+    /** The validated payload, as JSON. */
+    payload: unknown;
+    publishedAt: Date;
+    /** With createApp({ tracing }): the trace the event was published in, which the subscribed jobs continue. */
+    trace?: JobTraceContext;
+    /** The tenant the event belongs to (multi-tenancy), which the subscribed jobs get. */
+    tenantId?: string;
+}
+/**
+ * Carries events between services: createApp({ events: { transport } }). Inferlo has a Redis Streams transport
+ * built in (transport: "redis"); other brokers implement this interface.
+ */
+export interface EventTransport {
+    /** Shown as app.events.transport and in describe: "redis". */
+    readonly name: string;
+    /** Send one event to every service subscribed to its name. */
+    send(message: EventMessage): Promise<void>;
+    /**
+     * Deliver the waiting events with these names to deliver(), one at a time, and acknowledge each after deliver()
+     * resolves; an event whose deliver() rejects is delivered again later. Returns how many events were delivered.
+     */
+    receive(names: readonly string[], deliver: (message: EventMessage) => Promise<void>): Promise<number>;
+}
+export interface EventsConfig {
+    /**
+     * How events reach other services. Default: none, publishing queues the subscribed jobs of this app only.
+     * "redis": Redis Streams in the Redis of createApp({ redis }), one consumer group per app name, so every
+     * service subscribed to an event gets it once (at least once, with each job queued once).
+     */
+    transport?: "redis" | EventTransport;
+}
+/** Define an event: event("order.paid", { payload: t.object({ ... }) }). */
+export declare function event<P extends AnySchema>(name: string, options: EventOptions<P>): EventDef<InferInput<P>, Infer<P>, P>;
+export declare function isEvent(value: unknown): value is EventDef;
+export declare function isOn(value: unknown): value is OnDef;
+/**
+ * Subscribe a job to an event: on(orderPaid, sendReceipt) in createApp({ jobs }). Every published event queues the
+ * job with the payload as its input (use input: orderPaid.payload); a job whose input is an object with fewer fields
+ * gets only those fields.
+ */
+export declare function on<E extends EventDef, J extends JobDef>(event: E, job: J & (NonNullable<E["$payload"]> extends JobInput<J> ? unknown : never)): OnDef<E, J>;
+/** Checks the subscriptions of an app: one definition per event name, and each job subscribed once per event. */
+export declare function checkSubscriptions(subscriptions: readonly OnDef[]): EventDef[];
+/** The id of the job queued for one subscription of one event: the same for the same event id, so it is queued once. */
+export declare function eventJobId(eventId: string, jobName: string): Promise<string>;
+export interface EventsRuntime {
+    /** Queue one job with a fixed id (returning its id), continuing the given trace or the active one. */
+    enqueue(job: JobDef, input: unknown, id: string, trace?: JobTraceContext, tenantId?: string): Promise<string>;
+    transport?: EventTransport;
+    /** The active trace when an event is published, sent with it. */
+    capture?(): JobTraceContext | undefined;
+    logger?: {
+        error(message: string, data?: unknown): void;
+    };
+}
+/** IL6033: an invalid events option or transport. */
+export declare function invalidTransport(message: string): InferloError;
+/** Checks createApp({ events }) and returns the custom transport, "redis", or undefined. */
+export declare function checkEventsConfig(config: EventsConfig | undefined): EventsConfig["transport"];
+/** app.events, built by createJobs. */
+export declare function createEvents(subscriptions: readonly OnDef[], runtime: EventsRuntime): AppEvents;

package/dist/events.js

@@ -0,0 +1,196 @@
+/**
+ * Events: something that happened, published once and handled by any number of jobs.
+ *
+ *   export const orderPaid = event("order.paid", { payload: t.object({ orderId: t.uuid(), amount: t.int() }) });
+ *   export const sendReceipt = job("send-receipt", { input: orderPaid.payload }).handle(async ({ input }) => { ... });
+ *
+ *   createApp({ jobs: [on(orderPaid, sendReceipt), on(orderPaid, addPoints)] })
+ *   await ctx.events.publish(orderPaid, { orderId, amount });   // in a route handler or job, validated
+ *
+ * An event is delivered through the job queue: publishing queues every subscribed job with the payload, so
+ * retries, the memory, database and Redis stores, the worker and tracing work as for any job. The queued jobs get
+ * ids derived from the event id, so publishing the same event id again (a repeated delivery) queues nothing new.
+ */
+import { checkTenantId } from "./db/table.js";
+import { InferloError } from "./errors.js";
+import { ValidationError } from "./schema.js";
+const EVENT_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
+const FIX = 'Use event("order.paid", { payload: t.object({ orderId: t.uuid() }) }) and subscribe jobs in createApp({ jobs: [on(orderPaid, sendReceipt)] }).';
+function invalid(message, fix = FIX) {
+    return new InferloError("IL6032", message, { fix });
+}
+/** Define an event: event("order.paid", { payload: t.object({ ... }) }). */
+export function event(name, options) {
+    if (typeof name !== "string" || name.length > 100 || !EVENT_NAME.test(name)) {
+        throw invalid(`Invalid event name ${JSON.stringify(name)}: the name must be lowercase words of letters, digits and dashes, separated by dots, such as "order.paid".`);
+    }
+    if (!options || typeof options !== "object" || !options.payload || typeof options.payload.safeParse !== "function") {
+        throw invalid(`Invalid event "${name}": it needs a payload schema such as t.object({ ... }).`);
+    }
+    for (const key of Object.keys(options)) {
+        if (key !== "payload" && key !== "summary")
+            throw invalid(`Invalid event "${name}": unknown option "${key}". An event takes payload and summary; retries belong to the subscribed jobs.`);
+    }
+    if (options.summary !== undefined && typeof options.summary !== "string")
+        throw invalid(`Invalid event "${name}": summary must be a string.`);
+    const def = { kind: "inferlo.event", name, payload: options.payload, ...(options.summary ? { summary: options.summary } : {}) };
+    return Object.freeze(def);
+}
+export function isEvent(value) {
+    return typeof value === "object" && value !== null && value.kind === "inferlo.event";
+}
+export function isOn(value) {
+    return typeof value === "object" && value !== null && value.kind === "inferlo.on";
+}
+/**
+ * Subscribe a job to an event: on(orderPaid, sendReceipt) in createApp({ jobs }). Every published event queues the
+ * job with the payload as its input (use input: orderPaid.payload); a job whose input is an object with fewer fields
+ * gets only those fields.
+ */
+export function on(event, job) {
+    if (!isEvent(event))
+        throw invalid("on() needs an event made with event(name, { payload }) as its first argument.");
+    const j = job;
+    if (typeof j !== "object" || j === null || j.kind !== "inferlo.job")
+        throw invalid(`on("${event.name}") needs a job made with job(name, { input }).handle(fn) as its second argument.`);
+    // The payload must have every field the job requires (checked on the JSON Schemas; publish validates again).
+    const payload = event.payload.toJSONSchema();
+    const input = j.options.input.toJSONSchema();
+    const missing = payload.type === "object" && input.type === "object" ? (input.required ?? []).filter((key) => !(key in (payload.properties ?? {}))) : [];
+    if (missing.length) {
+        throw invalid(`Job "${j.name}" cannot handle event "${event.name}": its input requires ${missing.map((k) => `"${k}"`).join(", ")}, which the payload does not have.`, `Use the event's payload as the job's input: job("${j.name}", { input: ${event.name.replace(/\W(\w)/g, (_, c) => c.toUpperCase())}.payload }).`);
+    }
+    return Object.freeze({ kind: "inferlo.on", event, job: job });
+}
+/** Checks the subscriptions of an app: one definition per event name, and each job subscribed once per event. */
+export function checkSubscriptions(subscriptions) {
+    const events = new Map();
+    const pairs = new Set();
+    for (const s of subscriptions) {
+        const known = events.get(s.event.name);
+        if (known && known !== s.event) {
+            throw invalid(`Two different events are named "${s.event.name}".`, "Define each event once (export const orderPaid = event(...)) and import it wherever it is published or subscribed to.");
+        }
+        events.set(s.event.name, s.event);
+        const pair = `${s.event.name}\u0000${s.job.name}`;
+        if (pairs.has(pair))
+            throw invalid(`Job "${s.job.name}" is subscribed to event "${s.event.name}" twice.`, "Keep one on(event, job) for each pair.");
+        pairs.add(pair);
+    }
+    return [...events.values()];
+}
+/** The id of the job queued for one subscription of one event: the same for the same event id, so it is queued once. */
+export async function eventJobId(eventId, jobName) {
+    const data = new TextEncoder().encode(`inferlo.event:${eventId}:${jobName}`);
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", data)).slice(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x80; // version 8 (custom)
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+    const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** IL6033: an invalid events option or transport. */
+export function invalidTransport(message) {
+    return new InferloError("IL6033", message, {
+        fix: 'Use createApp({ name: "billing", redis, events: { transport: "redis" } }), or pass an object with name, send(message) and receive(names, deliver).',
+    });
+}
+/** Checks createApp({ events }) and returns the custom transport, "redis", or undefined. */
+export function checkEventsConfig(config) {
+    if (config === undefined)
+        return undefined;
+    if (typeof config !== "object" || config === null)
+        throw invalidTransport("createApp({ events }) must be an object such as { transport: \"redis\" }.");
+    for (const key of Object.keys(config))
+        if (key !== "transport")
+            throw invalidTransport(`Unknown events option "${key}". createApp({ events }) takes transport.`);
+    const t = config.transport;
+    if (t === undefined || t === "redis")
+        return t;
+    if (typeof t !== "object" || t === null || typeof t.name !== "string" || !t.name || typeof t.send !== "function" || typeof t.receive !== "function") {
+        throw invalidTransport(`Invalid events transport ${typeof t === "string" ? JSON.stringify(t) : "object"}: use "redis" or an object with name, send(message) and receive(names, deliver).`);
+    }
+    return t;
+}
+/** app.events, built by createJobs. */
+export function createEvents(subscriptions, runtime) {
+    const { enqueue, transport } = runtime;
+    const list = checkSubscriptions(subscriptions);
+    const byName = new Map(list.map((e) => [e.name, e]));
+    const names = list.map((e) => e.name);
+    // A job may take part of the payload (input: t.object({ orderId })): it gets only the fields its input has.
+    const fields = new Map();
+    for (const s of subscriptions) {
+        const input = s.job.options.input.toJSONSchema();
+        fields.set(s, input.type === "object" && input.properties ? Object.keys(input.properties) : undefined);
+    }
+    const inputFor = (s, payload) => {
+        const keys = fields.get(s);
+        if (!keys || typeof payload !== "object" || payload === null || Array.isArray(payload))
+            return payload;
+        return Object.fromEntries(keys.filter((k) => k in payload).map((k) => [k, payload[k]]));
+    };
+    /** Queue the jobs subscribed to one event in this app. */
+    const queueJobs = async (name, id, payload, trace, tenantId) => {
+        const jobs = [];
+        for (const s of subscriptions) {
+            if (s.event.name !== name)
+                continue;
+            jobs.push(await enqueue(s.job, inputFor(s, payload), await eventJobId(id, s.job.name), trace, tenantId));
+        }
+        return jobs;
+    };
+    /** An event from the transport: checked against this app's definition, then its jobs are queued. */
+    const deliver = async (message) => {
+        const def = byName.get(message.name);
+        if (!def)
+            return; // not subscribed here (a transport may deliver more than it was asked for)
+        const parsed = def.payload.safeParse(message.payload);
+        if (!parsed.ok) {
+            // Delivering it again cannot help: log it (without the payload, which may hold personal data) and acknowledge it.
+            const error = new InferloError("IL6034", `Received event "${message.name}" (id ${message.id}) does not match this service's payload schema and was dropped: ${new ValidationError(parsed.issues, "payload").message}`, {
+                fix: "Publish and subscribe with the same event definition, from a shared package, and change payloads compatibly (add optional fields only).",
+            });
+            runtime.logger?.error(`event "${message.name}" dropped`, error);
+            return;
+        }
+        // A tenant id that is not valid is dropped rather than trusted: the jobs then run without a tenant.
+        const tenantId = typeof message.tenantId === "string" && message.tenantId.length > 0 && message.tenantId.length <= 200 ? message.tenantId : undefined;
+        await queueJobs(message.name, message.id, parsed.value, message.trace, tenantId);
+    };
+    return {
+        list,
+        subscriptions,
+        transport: transport?.name,
+        async receive() {
+            if (!transport || !names.length)
+                return 0;
+            return transport.receive(names, deliver);
+        },
+        async publish(def, payload, options = {}) {
+            if (!isEvent(def))
+                throw invalid("events.publish() needs an event made with event(name, { payload }).", "Pass the event and its payload: await events.publish(orderPaid, { orderId }).");
+            if (options.id !== undefined && (typeof options.id !== "string" || options.id.length === 0 || options.id.length > 200)) {
+                throw invalid(`The id for event "${def.name}" must be a non-empty string of at most 200 characters.`, "Leave it out for a new UUID, or pass the id of the record the event comes from (an outbox row).");
+            }
+            const tenantId = options.tenantId === undefined || options.tenantId === null ? undefined : checkTenantId(options.tenantId);
+            const parsed = def.payload.safeParse(payload);
+            if (!parsed.ok)
+                throw new ValidationError(parsed.issues, `payload for event "${def.name}"`);
+            const id = options.id ?? crypto.randomUUID();
+            const publishedAt = new Date();
+            if (transport) {
+                // Every service (this one too) queues its jobs when it receives the event; their ids are known already.
+                const trace = runtime.capture?.();
+                const json = JSON.parse(JSON.stringify(parsed.value ?? null));
+                await transport.send({ id, name: def.name, payload: json, publishedAt, ...(trace?.traceparent ? { trace } : {}), ...(tenantId ? { tenantId } : {}) });
+                const jobs = [];
+                for (const s of subscriptions)
+                    if (s.event.name === def.name)
+                        jobs.push(await eventJobId(id, s.job.name));
+                return { id, name: def.name, publishedAt, jobs };
+            }
+            return { id, name: def.name, publishedAt, jobs: await queueJobs(def.name, id, parsed.value, undefined, tenantId) };
+        },
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

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

package/dist/fastify.d.ts

@@ -8,6 +8,7 @@
  *   const fastify = Fastify();
  *   await fastify.register(inferloPlugin, { ai });                         // fastify.ai and request.ai
  *   await fastify.register(inferloPlugin, { app: inferloApp, prefix: "/api" }); // or a whole Inferlo app under /api
+ *   await fastify.register(inferloPlugin, { app: inferloApp, fallthrough: true }); // or only the app's routes, at their own URLs
  *
  * Importing this entry point adds `ai` to Fastify's instance and request types. It never loads the router,
  * database or jobs code.
@@ -32,13 +33,20 @@ export interface InferloPluginOptions {
         fetch(req: Request, ...rest: unknown[]): Promise<Response>;
         ai?: AI;
     };
-    /** Path the app is served under, for example "/api". Required with app. */
+    /** Path the app is served under, for example "/api". Required with app, unless fallthrough is true. */
     prefix?: string;
+    /**
+     * Answer only the requests the app has a route for (method and path) and its own endpoints (OpenAPI, MCP,
+     * health, metrics, CORS preflights), and leave every other request to Fastify's routes and 404 handler.
+     * With it, routes move from Fastify to Inferlo one at a time at the same URLs. Default false.
+     */
+    fallthrough?: boolean;
 }
 /** A Fastify plugin, registered with fastify.register(inferloPlugin, options). */
 export type InferloPlugin = FastifyPluginAsync<InferloPluginOptions>;
 /**
  * Fastify plugin. { ai } decorates fastify.ai and request.ai everywhere in the Fastify app; { app, prefix }
- * serves a whole Inferlo app (routes, auth, validation, OpenAPI, MCP) under prefix. Both can be combined.
+ * serves a whole Inferlo app (routes, auth, validation, OpenAPI, MCP) under prefix; { app, fallthrough: true }
+ * answers only the app's routes and leaves every other request to Fastify. They can be combined.
  */
 export declare const inferloPlugin: InferloPlugin;

package/dist/fastify.js

@@ -1,6 +1,6 @@
 import { assertAIClient } from "./ai-client.js";
 import { InferloError } from "./errors.js";
-import { toNodeHandler } from "./serve.js";
+import { answersNodeRequest, toNodeHandler } from "./serve.js";
 const bad = (message, fix) => new InferloError("IL5015", message, { fix });
 async function plugin(fastify, options) {
     const { app, prefix } = options ?? {};
@@ -18,8 +18,25 @@ async function plugin(fastify, options) {
     }
     if (!app)
         return;
-    if (typeof prefix !== "string" || !/^\/[^*?#]*[^/*?#]$/.test(prefix)) {
-        throw bad(`inferloPlugin needs a prefix such as "/api" to serve an app, got ${JSON.stringify(prefix)}.`, 'Use fastify.register(inferloPlugin, { app, prefix: "/api" }).');
+    const { fallthrough } = options;
+    if (fallthrough !== undefined && typeof fallthrough !== "boolean") {
+        throw bad("inferloPlugin's fallthrough must be true or false.", "Use fastify.register(inferloPlugin, { app, fallthrough: true }).");
+    }
+    const validPrefix = typeof prefix === "string" && /^\/[^*?#]*[^/*?#]$/.test(prefix);
+    if (fallthrough ? prefix !== undefined && !validPrefix : !validPrefix) {
+        throw bad(`inferloPlugin needs a prefix such as "/api" to serve an app, got ${JSON.stringify(prefix)}.`, 'Use fastify.register(inferloPlugin, { app, prefix: "/api" }), or { app, fallthrough: true } to serve the app\'s routes at their own URLs.');
+    }
+    if (fallthrough) {
+        const handler = toNodeHandler(app, { prefix, fallthrough: true }); // also checks that app comes from createApp
+        // onRequest runs before Fastify reads the body, for Fastify's routes and its 404 handler alike, so the app
+        // can take over the requests it answers and Fastify keeps everything else, also other methods on a path.
+        fastify.addHook("onRequest", async (request, reply) => {
+            if (!answersNodeRequest(app, request.raw, prefix))
+                return;
+            reply.hijack();
+            await handler(request.raw, reply.raw);
+        });
+        return;
     }
     const handler = toNodeHandler(app, { prefix });
     // In a child context, so the catch-all body parser applies to the app's routes only: Inferlo reads the
@@ -37,7 +54,8 @@ async function plugin(fastify, options) {
 }
 /**
  * Fastify plugin. { ai } decorates fastify.ai and request.ai everywhere in the Fastify app; { app, prefix }
- * serves a whole Inferlo app (routes, auth, validation, OpenAPI, MCP) under prefix. Both can be combined.
+ * serves a whole Inferlo app (routes, auth, validation, OpenAPI, MCP) under prefix; { app, fallthrough: true }
+ * answers only the app's routes and leaves every other request to Fastify. They can be combined.
  */
 export const inferloPlugin = Object.assign(plugin, {
     // Like fastify-plugin: the decorators are visible to the whole Fastify app, not only inside this plugin.

package/dist/fastify.js.map

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

package/dist/h3.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Inferlo inside h3 (1 and 2), Nitro and Nuxt server routes, without a runtime dependency on h3:
+ *
+ *   // server/routes/api/[...path].ts (Nitro or Nuxt)
+ *   import { toH3Handler } from "@browserlessapi/inferlo/h3";
+ *   import { app } from "../../inferlo/app";
+ *
+ *   export default toH3Handler(app, { prefix: "/api" });
+ *
+ *   // server/plugins/ai.ts: event.context.ai in every server route
+ *   import { inferloAI } from "@browserlessapi/inferlo/h3";
+ *   export default defineNitroPlugin(inferloAI(ai));
+ *
+ * It never loads the router, database or jobs code.
+ */
+import type { H3EventContext } from "h3";
+import type { AI } from "./ai/index.ts";
+import type { App } from "./app.ts";
+declare module "h3" {
+    interface H3EventContext {
+        /** The AI client from the inferloAI() Nitro plugin of @browserlessapi/inferlo/h3. */
+        ai: AI;
+    }
+}
+/** The parts of an h3 1 or h3 2 event Inferlo uses. */
+export interface H3EventLike {
+    /** h3 2: the Web request (and event.url, the parsed URL). */
+    req?: {
+        url: string;
+        method: string;
+        headers: HeadersInit;
+        body?: ReadableStream<Uint8Array> | null;
+        signal?: AbortSignal;
+        ip?: string;
+    };
+    url?: URL;
+    /** h3 1: the Node request and response, and event.path (after an app.use() prefix). h3 2 has node on Node.js too. */
+    node?: {
+        req: unknown;
+        res: {
+            on(event: "close", listener: () => void): unknown;
+            writableFinished?: boolean;
+        };
+    };
+    path?: string;
+    /** event.context, where the inferloAI() plugin puts ai. */
+    context: H3EventContext | Record<string, unknown>;
+}
+/** An h3 event handler: export it from a Nitro server route, or pass it to app.use() or router.add(). */
+export type H3Handler = ((event: H3EventLike) => Promise<Response>) & {
+    readonly __is_handler__: true;
+};
+export interface H3HandlerOptions {
+    /**
+     * The path the handler is served under, removed before the app routes the request: "/api" for
+     * server/routes/api/[...path].ts. Requests outside it keep their path. Leave it out when h3 already removed the
+     * path (h3 1 app.use("/api", handler)).
+     */
+    prefix?: string;
+}
+/** A Nitro plugin: export default defineNitroPlugin(inferloAI(ai)). */
+export type NitroPlugin = (nitroApp: {
+    hooks: {
+        hook(name: "request", fn: (event: H3EventLike) => void): unknown;
+    };
+}) => void;
+/**
+ * An h3 event handler that runs a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP), for
+ * Nitro and Nuxt server routes and h3 apps, on h3 1 (Nuxt 3 and 4, Nitro 2) and h3 2 (Nitro 3).
+ */
+export declare function toH3Handler(app: Pick<App<any>, "fetch">, options?: H3HandlerOptions): H3Handler;
+/**
+ * A Nitro plugin that puts an AI client (createAI(...) or an Inferlo app's app.ai) on every request as
+ * event.context.ai: export default defineNitroPlugin(inferloAI(ai)) in server/plugins/ai.ts.
+ */
+export declare function inferloAI(ai: AI): NitroPlugin;

package/dist/h3.js

@@ -0,0 +1,61 @@
+import { assertAIClient } from "./ai-client.js";
+import { clientIps } from "./client-ip.js";
+import { InferloError } from "./errors.js";
+import { buildRequest, normalizePrefix, stripPrefix } from "./serve.js";
+const fix = 'Pass the app from createApp and the route\'s path: export default toH3Handler(app, { prefix: "/api" }).';
+/**
+ * An h3 event handler that runs a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP), for
+ * Nitro and Nuxt server routes and h3 apps, on h3 1 (Nuxt 3 and 4, Nitro 2) and h3 2 (Nitro 3).
+ */
+export function toH3Handler(app, options = {}) {
+    if (!app || typeof app.fetch !== "function") {
+        throw new InferloError("IL5021", "toH3Handler() 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("IL5021", 'toH3Handler() prefix must be a path that starts with /, such as "/api".', { fix });
+    }
+    const prefix = normalizePrefix(options.prefix);
+    const handler = async (event) => {
+        const e = event;
+        // h3 2: the event carries a Web request.
+        if (e?.req && e.url instanceof URL) {
+            const url = new URL(e.url.href);
+            url.pathname = stripPrefix(url.pathname, prefix) ?? url.pathname;
+            const method = e.req.method.toUpperCase();
+            const hasBody = e.req.body != null && method !== "GET" && method !== "HEAD";
+            const init = { method, headers: e.req.headers, body: hasBody ? e.req.body : undefined, signal: e.req.signal };
+            if (hasBody)
+                init.duplex = "half";
+            const request = new Request(url, init);
+            if (typeof e.req.ip === "string" && e.req.ip)
+                clientIps.set(request, e.req.ip);
+            return app.fetch(request);
+        }
+        // h3 1: the event carries Node's request and response.
+        if (e?.node?.req) {
+            const raw = typeof e.path === "string" ? e.path : (e.node.req.url ?? "/");
+            const controller = new AbortController();
+            e.node.res.on("close", () => {
+                if (!e.node.res.writableFinished)
+                    controller.abort();
+            });
+            return app.fetch(buildRequest(e.node.req, stripPrefix(raw, prefix) ?? raw, controller.signal));
+        }
+        throw new InferloError("IL5021", "toH3Handler()'s handler was called with something that is not an h3 event.", { fix: "Export it from a Nitro server route or pass it to an h3 app: app.use(\"/api/**\", toH3Handler(inferlo, { prefix: \"/api\" }))." });
+    };
+    // Marks it as an event handler for h3 1 (what defineEventHandler does); h3 2 takes plain functions.
+    return Object.assign(handler, { __is_handler__: true });
+}
+/**
+ * A Nitro plugin that puts an AI client (createAI(...) or an Inferlo app's app.ai) on every request as
+ * event.context.ai: export default defineNitroPlugin(inferloAI(ai)) in server/plugins/ai.ts.
+ */
+export function inferloAI(ai) {
+    assertAIClient(ai, 'Pass createAI({ providers, models }) from "@browserlessapi/inferlo/ai", or an Inferlo app\'s app.ai: export default defineNitroPlugin(inferloAI(ai)).');
+    return (nitroApp) => {
+        nitroApp.hooks.hook("request", (event) => {
+            event.context.ai = ai;
+        });
+    };
+}
+//# sourceMappingURL=h3.js.map

package/dist/h3.js.map

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

package/dist/hapi.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Inferlo inside hapi (21 and later), without a runtime dependency on hapi:
+ *
+ *   import Hapi from "@hapi/hapi";
+ *   import { createAI, anthropic } from "@browserlessapi/inferlo/ai";
+ *   import { inferloPlugin } from "@browserlessapi/inferlo/hapi";
+ *
+ *   const server = Hapi.server({ port: 3000 });
+ *   await server.register({ plugin: inferloPlugin, options: { ai } });                                // server.ai and request.ai
+ *   await server.register({ plugin: inferloPlugin, options: { app: inferloApp }, routes: { prefix: "/api" } }); // a whole Inferlo app under /api
+ *
+ * Importing this entry point adds `ai` to hapi's server and request types. It never loads the router,
+ * database or jobs code.
+ */
+import type { Plugin } from "@hapi/hapi";
+import type { AI } from "./ai/index.ts";
+declare module "@hapi/hapi" {
+    interface Server {
+        /** The AI client registered with inferloPlugin from @browserlessapi/inferlo/hapi. */
+        ai: AI;
+    }
+    interface Request {
+        /** The AI client registered with inferloPlugin from @browserlessapi/inferlo/hapi. */
+        ai: AI;
+    }
+}
+export interface InferloPluginOptions {
+    /** AI client for server.ai and request.ai: createAI(...) or an Inferlo app's app.ai. Default: app.ai, unless server.ai is already set. */
+    ai?: AI;
+    /**
+     * A whole Inferlo app (routes, auth, validation, OpenAPI, MCP) to serve. It is served under the prefix you
+     * register the plugin with (routes: { prefix: "/api" }), or, without one, for every path hapi has no route for.
+     */
+    app?: {
+        fetch(req: Request, ...rest: unknown[]): Promise<Response>;
+        ai?: AI;
+    };
+}
+/** A hapi plugin, registered with server.register({ plugin: inferloPlugin, options }). */
+export type InferloPlugin = Plugin<InferloPluginOptions>;
+/**
+ * hapi plugin. options: { ai } decorates server.ai and request.ai; options: { app } serves a whole Inferlo app
+ * (routes, auth, validation, OpenAPI, MCP) under the prefix the plugin is registered with (routes: { prefix }).
+ */
+export declare const inferloPlugin: InferloPlugin;