@browserlessapi/inferlo 0.4.0 → 0.5.0

package/dist/ai/tool.js

@@ -0,0 +1,85 @@
+/**
+ * Tools made from plain functions, for ai.generate({ tools }) anywhere (createAI or ctx.ai):
+ *
+ *   export const getWeather = tool("getWeather", {
+ *     description: "Current weather for a city",
+ *     input: t.object({ city: t.string() }),
+ *   }).handle(async ({ input }) => fetchWeather(input.city))
+ *
+ * The model's arguments are validated against input before the function runs.
+ */
+import { InferloError } from "../errors.js";
+import { ObjectSchema, ValidationError } from "../schema.js";
+export class ToolBuilder {
+    name;
+    options;
+    constructor(name, options) {
+        this.name = name;
+        this.options = options;
+    }
+    /**
+     * The tool's work. Return any JSON value (or a string) for the model. Throw httpError(404, "...")
+     * to send a failed tool result to the model; any other error rejects ai.generate.
+     */
+    handle(handler) {
+        if (typeof handler !== "function")
+            throw invalid(this.name, ["handle() needs a function"]);
+        return { kind: "inferlo.tool", name: this.name, description: this.options.description, input: this.options.input, handler: handler };
+    }
+}
+/** Provider limit for tool names (Anthropic, OpenAI and Gemini). */
+const TOOL_NAME = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+/** Define a tool the model can call: tool("getWeather", { description, input: t.object({ ... }) }).handle(fn). */
+export function tool(name, options) {
+    const problems = [];
+    if (typeof name !== "string" || !TOOL_NAME.test(name))
+        problems.push("the name must be letters, digits, _ and -, starting with a letter, at most 64 characters");
+    if (!options || typeof options !== "object")
+        problems.push("options must be an object with a description and an input schema");
+    else {
+        if (typeof options.description !== "string" || !options.description.trim())
+            problems.push("description must say what the tool does");
+        if (!(options.input instanceof ObjectSchema))
+            problems.push("input must be a t.object({ ... }) schema");
+    }
+    if (problems.length)
+        throw invalid(name, problems);
+    return new ToolBuilder(name, options);
+}
+function invalid(name, problems) {
+    return new InferloError("IL5013", `Invalid tool "${String(name)}": ${problems.join(", ")}.`, {
+        fix: 'Use tool("getWeather", { description: "Current weather for a city", input: t.object({ city: t.string() }) }).handle(async ({ input }) => { ... }).',
+    });
+}
+export function isTool(value) {
+    return typeof value === "object" && value !== null && value.kind === "inferlo.tool";
+}
+/** What the model is offered for a function tool. Internal. */
+export function functionToolSpec(def) {
+    return { name: def.name, description: def.description, inputSchema: def.input.toJSONSchema() };
+}
+/**
+ * Runs one call of a function tool. Validation errors and InferloErrors with a status below 500
+ * (httpError, notFound, forbidden) become failed tool results for the model; other errors are rethrown.
+ * Internal.
+ */
+export async function runFunctionTool(def, input, signal) {
+    try {
+        const parsed = def.input.safeParse(input);
+        if (!parsed.ok)
+            throw new ValidationError(parsed.issues, "tool input");
+        const output = await def.handler({ input: parsed.value, ...(signal ? { signal } : {}) });
+        if (typeof output === "string")
+            return { status: 200, output, text: output };
+        const text = JSON.stringify(output ?? null);
+        return { status: 200, output: output ?? null, text };
+    }
+    catch (error) {
+        if (error instanceof InferloError && error.status < 500) {
+            const output = error.toJSON();
+            return { status: error.status, output, text: JSON.stringify(output) };
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=tool.js.map

package/dist/ai/tool.js.map

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

package/dist/ai-client.d.ts

@@ -0,0 +1,3 @@
+/** Shared by the framework integrations: checks that a value is an AI client (createAI(...) or app.ai). */
+import type { AI } from "./ai/index.ts";
+export declare function assertAIClient(ai: unknown, fix: string): asserts ai is AI;

package/dist/ai-client.js

@@ -0,0 +1,8 @@
+import { InferloError } from "./errors.js";
+export function assertAIClient(ai, fix) {
+    const candidate = ai;
+    if (!candidate || typeof candidate.generate !== "function" || typeof candidate.stream !== "function" || typeof candidate.embed !== "function") {
+        throw new InferloError("IL5014", "inferloAI() needs an AI client.", { fix });
+    }
+}
+//# sourceMappingURL=ai-client.js.map

package/dist/ai-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-client.js","sourceRoot":"","sources":["../src/ai-client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,UAAU,cAAc,CAAC,EAAW,EAAE,GAAW;IACrD,MAAM,SAAS,GAAG,EAA6B,CAAC;IAChD,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,UAAU,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QAC9I,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,iCAAiC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC"}

package/dist/app.d.ts

@@ -10,6 +10,9 @@ import type { AnyModel } from "./model.ts";
 import { type AppDb, type AppUser, type Method, type RouteDef } from "./route.ts";
 import { type RateLimitConfig } from "./rate-limit.ts";
 import { type AppJobs, type JobQueueConfig, type JobSource } from "./jobs.ts";
+import { type LogFields, type LoggingConfig } from "./logging.ts";
+import { type MetricsConfig } from "./metrics.ts";
+import { type SecureHeadersConfig } from "./secure-headers.ts";
 export interface AuthConfig {
     /** Return the signed-in user for this request, or null. */
     resolve(req: Request, ctx: {
@@ -30,11 +33,48 @@ export interface MiddlewareContext {
     req: Request;
     url: URL;
     state: Record<string, unknown>;
+    /** This request's id, sent back in the X-Request-Id header and added to its log entries. */
+    requestId: string;
 }
 export type Middleware = (ctx: MiddlewareContext, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Where the app writes logs. fields holds structured values such as requestId (a request's log entries)
+ * or method, path, status and durationMs (request logs); loggers that only take two arguments ignore them.
+ */
 export interface Logger {
-    info(message: string, data?: unknown): void;
-    error(message: string, data?: unknown): void;
+    info(message: string, data?: unknown, fields?: LogFields): void;
+    error(message: string, data?: unknown, fields?: LogFields): void;
+}
+/** A readiness check: resolve (or return) when the dependency is usable, throw when it is not. */
+export type HealthCheck = () => unknown | Promise<unknown>;
+export interface HealthConfig {
+    /** Liveness endpoint: 200 while the process can answer requests. Default "/health". */
+    path?: string;
+    /** Readiness endpoint: 200 when every check passes, 503 otherwise. Default "/ready". */
+    readyPath?: string;
+    /** Your own checks, by name ("database" and "ai" are built in): { redis: () => redis.ping() }. */
+    checks?: Record<string, HealthCheck>;
+    /** Time each check may take before it fails. Default 5000 ms. */
+    timeoutMs?: number;
+}
+export interface CheckResult {
+    status: "ok" | "error";
+    durationMs: number;
+    /** "Check failed." unless the check threw an exposed InferloError (httpError) or exposeErrors is on. */
+    error?: string;
+}
+export interface CloseOptions {
+    /**
+     * Keep serving requests for this long after /ready starts answering 503, so load balancers stop sending
+     * traffic first (for example a few seconds more than the readiness probe period). Default 0.
+     */
+    delayMs?: number;
+    /** Longest wait for in-flight requests, waitUntil tasks and the running job before closing anyway. Default 10000. */
+    timeoutMs?: number;
+}
+export interface ReadinessReport {
+    status: "ready" | "not_ready";
+    checks: Record<string, CheckResult>;
 }
 /** Anything that contains routes: a route, an array, or a module (import * as tickets from "./routes/tickets.ts"). */
 export type RouteSource = RouteDef | readonly RouteSource[] | {
@@ -70,9 +110,44 @@ export interface AppConfig<Models extends readonly AnyModel[]> {
      * (for rateLimit by "ip"). Default false, because clients can send that header themselves.
      */
     trustProxy?: boolean;
+    /**
+     * Health endpoints for load balancers and orchestrators: GET /health (liveness) and GET /ready (readiness:
+     * the database, the AI configuration and your checks). Public, never cached. Off by default.
+     */
+    health?: boolean | HealthConfig;
+    /**
+     * Security headers sent on every response that does not set them itself: Content-Security-Policy,
+     * Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy, Referrer-Policy, X-Content-Type-Options,
+     * X-Frame-Options, and Strict-Transport-Security over HTTPS. Change one by name, false leaves it out:
+     * { "X-Frame-Options": "SAMEORIGIN", "Content-Security-Policy": false }. false sends none. Default true.
+     */
+    secureHeaders?: boolean | SecureHeadersConfig;
+    /**
+     * Longest time in milliseconds a route may take (reading the body and running the handler) before it answers
+     * 503 IL2007 and ctx.signal is aborted. Routes can set their own timeoutMs. false turns it off. Default 60000.
+     */
+    requestTimeoutMs?: number | false;
+    /**
+     * More values to hide from logs, besides credentials Inferlo finds itself (authorization and cookie headers,
+     * tokens, API keys, passwords in URLs) and the AI provider keys: your config() result (its secrets) or
+     * strings: redact: [settings, process.env.WEBHOOK_SECRET]. They are replaced with "[redacted]".
+     */
+    redact?: readonly (string | object | undefined | null)[];
     /** Include error messages of unexpected (500) errors in responses. Default false. */
     exposeErrors?: boolean;
+    /** Your own logger (for example pino or winston): { info(message, data, fields), error(message, data, fields) }. */
     logger?: Logger;
+    /**
+     * The built-in logger's format ("text" or "json", one object per line) and request logs (requests: true logs
+     * each request's id, method, path, status and duration). Every response has an X-Request-Id header.
+     */
+    logging?: LoggingConfig;
+    /**
+     * Prometheus metrics at GET /metrics: requests by route and status with durations, job runs, and AI calls,
+     * tokens and cost per alias. { token } requires Authorization: Bearer <token>; without it the endpoint is
+     * public, so keep it off the internet. Off by default.
+     */
+    metrics?: boolean | MetricsConfig;
 }
 export interface RequestOptions {
     method?: Method | Lowercase<Method> | "OPTIONS" | "HEAD";
@@ -102,6 +177,16 @@ export interface App<Models extends readonly AnyModel[]> {
         port: number;
         close(): Promise<void>;
     }>;
+    /** Run the readiness checks (the same report as GET /ready, also when health is off). */
+    checkReady(): Promise<ReadinessReport>;
+    /** True once app.close() was called: /ready answers 503. */
+    readonly closing: boolean;
+    /**
+     * Graceful shutdown, for SIGTERM: /ready answers 503, then (after delayMs) new requests get 503 IL2006,
+     * in-flight requests, waitUntil tasks and the job workers from app.jobs.start() finish (up to timeoutMs),
+     * servers from app.listen() close, then the database. Calling it again returns the same promise.
+     */
+    close(options?: CloseOptions): Promise<void>;
     /** Machine-readable map of the whole app: routes, models, auth and AI. */
     describe(): AppDescription;
     openapi(): Record<string, unknown>;