@browserlessapi/inferlo 0.4.0 → 0.5.0

package/dist/metrics.d.ts

@@ -0,0 +1,48 @@
+export interface MetricsConfig {
+    /** Path of the metrics endpoint. Default "/metrics". */
+    path?: string;
+    /**
+     * Require Authorization: Bearer <token> to read metrics (set the same token in the scraper's
+     * bearer_token). Without it the endpoint is public, so only leave it out when the endpoint is not
+     * reachable from the internet.
+     */
+    token?: string;
+    /** Upper bounds in seconds of the duration histogram buckets. Default 0.005 to 10 seconds. */
+    buckets?: readonly number[];
+}
+export interface ResolvedMetrics {
+    path: string;
+    token: string | undefined;
+    buckets: number[];
+}
+/** Default histogram buckets in seconds, the same as the Prometheus client libraries. */
+export declare const DEFAULT_BUCKETS: number[];
+/** Checks createApp({ metrics }) and returns it with defaults, or undefined when metrics are off. */
+export declare function resolveMetrics(option: unknown, taken: {
+    path: string | false;
+    what: string;
+}[]): ResolvedMetrics | undefined;
+/** True when the request carries Authorization: Bearer <token>, compared in constant time. */
+export declare function hasMetricsToken(req: Request, token: string): boolean;
+export interface AppMetrics {
+    /** A request finished: route is the route pattern ("/tickets/:id"), or "unmatched". */
+    request(method: string, route: string, status: number, seconds: number): void;
+    inFlight(delta: number): void;
+    job(name: string, outcome: "done" | "retried" | "failed", seconds: number): void;
+    ai(usage: {
+        requested: string;
+        model: string;
+        kind: string;
+        inputTokens: number;
+        outputTokens: number;
+        cost: number;
+        durationMs: number;
+    }): void;
+    /** The Prometheus text exposition of every metric. */
+    render(): string;
+}
+export declare function createMetrics(info: {
+    app: string;
+    version: string;
+    inferlo: string;
+}, buckets: readonly number[]): AppMetrics;

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/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/openapi.d.ts

@@ -1,4 +1,3 @@
-/** OpenAPI 3.1 document generated from routes. Served at /openapi.json by default. */
 import type { App } from "./app.ts";
 export declare function buildOpenAPI(app: App<any>, options: {
     description?: string;

package/dist/openapi.js

@@ -1,3 +1,5 @@
+/** OpenAPI 3.1 document generated from routes. Served at /openapi.json by default. */
+import { describeDeprecation, resolveDeprecation } from "./deprecation.js";
 import { toolName } from "./mcp.js";
 const errorSchema = {
     type: "object",
@@ -52,6 +54,8 @@ export function buildOpenAPI(app, options) {
             security: !isPublic && options.auth ? [{ bearerAuth: [] }] : undefined,
             "x-inferlo-auth": o.auth ?? "user",
             "x-inferlo-tool": o.tool ? toolName(route) : undefined,
+            deprecated: o.deprecated ? true : undefined,
+            "x-inferlo-deprecation": typeof o.deprecated === "object" ? describeDeprecation(resolveDeprecation(o.deprecated, `${route.method} ${route.path}`)) : undefined,
         };
         for (const key of Object.keys(operation))
             if (operation[key] === undefined)

package/dist/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGpC,MAAM,WAAW,GAAe;IAC9B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,QAAQ,CAAC,EAAE;gBAC9C,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC3B,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACvB,OAAO,EAAE,EAAE;gBACX,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE;aACxC;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC;SACtC;KACF;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,GAAa,EAAE,OAAgD;IAC1F,MAAM,KAAK,GAA4C,EAAE,CAAC;IAC1D,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;QACxB,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACzF,MAAM,UAAU,GAA8B,EAAE,CAAC;QACjD,MAAM,UAAU,GAAI,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,UAAyC,IAAI,EAAE,CAAC;QAC7F,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChG,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC5G,CAAC;QACD,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;YACZ,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAE,CAAC,CAAC,QAAqB,IAAI,EAAE,CAAC,CAAC;YACzD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAE,CAAC,CAAC,UAAyC,IAAI,EAAE,CAAC,EAAE,CAAC;gBAChG,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/E,CAAC;QACH,CAAC;QACD,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,QAAQ,CAAC;QACjD,MAAM,SAAS,GAA4B;YACzC,WAAW,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC;YAC1C,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YACtD,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS;YACxI,SAAS,EAAE;gBACT,KAAK,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE;gBAClI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,4BAA4B,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5J,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,2BAA2B,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvI,GAAG,CAAC,CAAC,CAAC,SAAS;oBACb,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,+BAA+B,CAAC,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,IAAI,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE;oBAC/L,CAAC,CAAC,EAAE,CAAC;aACR;YACD,QAAQ,EAAE,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;YACtE,gBAAgB,EAAE,CAAC,CAAC,IAAI,IAAI,MAAM;YAClC,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;SACvD,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;QAClG,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC;IACnE,CAAC;IACD,MAAM,OAAO,GAA+B,EAAE,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;IACnE,OAAO;QACL,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;QACjF,KAAK;QACL,UAAU,EAAE;YACV,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE;YAC3C,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjG;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGpC,MAAM,WAAW,GAAe;IAC9B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,QAAQ,CAAC,EAAE;gBAC9C,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC3B,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACvB,OAAO,EAAE,EAAE;gBACX,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE;aACxC;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC;SACtC;KACF;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,GAAa,EAAE,OAAgD;IAC1F,MAAM,KAAK,GAA4C,EAAE,CAAC;IAC1D,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;QACxB,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACzF,MAAM,UAAU,GAA8B,EAAE,CAAC;QACjD,MAAM,UAAU,GAAI,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,UAAyC,IAAI,EAAE,CAAC;QAC7F,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChG,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC5G,CAAC;QACD,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;YACZ,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAE,CAAC,CAAC,QAAqB,IAAI,EAAE,CAAC,CAAC;YACzD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAE,CAAC,CAAC,UAAyC,IAAI,EAAE,CAAC,EAAE,CAAC;gBAChG,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/E,CAAC;QACH,CAAC;QACD,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,QAAQ,CAAC;QACjD,MAAM,SAAS,GAA4B;YACzC,WAAW,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC;YAC1C,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YACtD,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS;YACxI,SAAS,EAAE;gBACT,KAAK,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE;gBAClI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,4BAA4B,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5J,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,2BAA2B,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvI,GAAG,CAAC,CAAC,CAAC,SAAS;oBACb,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,+BAA+B,CAAC,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,IAAI,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE;oBAC/L,CAAC,CAAC,EAAE,CAAC;aACR;YACD,QAAQ,EAAE,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;YACtE,gBAAgB,EAAE,CAAC,CAAC,IAAI,IAAI,MAAM;YAClC,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;YACtD,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YAC3C,uBAAuB,EAAE,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAE,CAAC,CAAC,CAAC,CAAC,SAAS;SAChK,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;QAClG,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC;IACnE,CAAC;IACD,MAAM,OAAO,GAA+B,EAAE,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;IACnE,OAAO;QACL,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;QACjF,KAAK;QACL,UAAU,EAAE;YACV,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE;YAC3C,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjG;KACF,CAAC;AACJ,CAAC"}

package/dist/redact.d.ts

@@ -0,0 +1,19 @@
+export declare const REDACTED = "[redacted]";
+/** Internal: remember the secret values an object holds (a config() result or an AI provider). */
+export declare function holdSecrets<T extends object>(owner: T, values: readonly (string | undefined | null)[]): T;
+export declare function secretsOf(owner: unknown): readonly string[];
+export interface Redactor {
+    text(value: string): string;
+    value(value: unknown): unknown;
+}
+export declare function createRedactor(secretValues: readonly string[]): Redactor;
+export interface LoggerLike {
+    info(message: string, data?: unknown, fields?: Record<string, string | number | boolean | undefined>): void;
+    error(message: string, data?: unknown, fields?: Record<string, string | number | boolean | undefined>): void;
+}
+/** A logger that redacts every message, data value and field before passing them on. */
+export declare function redactingLogger(logger: LoggerLike, redactor: Redactor): LoggerLike;
+/** The values of createApp({ redact }): strings, or objects that hold secrets (config() results). */
+export declare function redactValues(option: unknown): string[];
+/** Internal: remember a config() result and its secret values, for createApp({ redact: [settings] }). */
+export declare function holdConfigSecrets<T extends object>(settings: T, values: readonly unknown[]): T;

package/dist/redact.js

@@ -0,0 +1,150 @@
+/**
+ * Secret redaction for everything createApp logs (and the error messages exposeErrors shows): credentials in
+ * headers, tokens, API keys, passwords in URLs, the app's AI provider keys and the values passed to
+ * createApp({ redact }). Internal: createApp wraps its logger with redactingLogger().
+ */
+import { InferloError } from "./errors.js";
+export const REDACTED = "[redacted]";
+/** Secret values of objects that hold them (config() results, AI providers), looked up by createApp. */
+const heldSecrets = new WeakMap();
+/** Internal: remember the secret values an object holds (a config() result or an AI provider). */
+export function holdSecrets(owner, values) {
+    const list = values.filter((v) => typeof v === "string" && v.length > 0);
+    if (list.length)
+        heldSecrets.set(owner, [...(heldSecrets.get(owner) ?? []), ...list]);
+    return owner;
+}
+export function secretsOf(owner) {
+    return owner && typeof owner === "object" ? (heldSecrets.get(owner) ?? []) : [];
+}
+const SENSITIVE_KEY = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|api[-_]?key|apikey|password|passwd|secret|client[-_]?secret|token|access[-_]?token|refresh[-_]?token|id[-_]?token|private[-_]?key|session)$/i;
+const PATTERNS = [
+    // Header-like "name: value" or "name=value" pairs, also inside JSON text. Cookies run to the end of the value.
+    [/\b(cookie|set-cookie)(["']?\s*[:=]\s*["']?)(?!\[redacted\])[^"'\r\n]+/gi, `$1$2${REDACTED}`],
+    [
+        /\b(authorization|proxy-authorization|x-api-key|api-key)(["']?\s*[:=]\s*["']?)(?:(Bearer|Basic|Token)\s+)?(?!\[redacted\]|(?:Bearer|Basic|Token)\s)[^\s"',;]+/gi,
+        (_match, name, separator, scheme) => `${name}${separator}${scheme ? `${scheme} ` : ""}${REDACTED}`,
+    ],
+    // Bearer <token> and Basic <credentials> anywhere else
+    [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{4,}/g, `$1 ${REDACTED}`],
+    // Passwords in connection strings and URLs: postgres://user:password@host
+    [/\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]*:)[^\s@/]+@/gi, `$1${REDACTED}@`],
+    // Secrets in query strings: ?key=..., &access_token=...
+    [/([?&](?:key|api_key|apikey|access_token|token|secret|password|signature|sig)=)[^&\s"'#]+/gi, `$1${REDACTED}`],
+    // Well-known API key formats: OpenAI and Anthropic (sk-...), Google (AIza...), GitHub tokens.
+    [/\bsk-[A-Za-z0-9_-]{16,}/g, REDACTED],
+    [/\bAIza[0-9A-Za-z_-]{30,}/g, REDACTED],
+    [/\bgh[pousr]_[A-Za-z0-9]{30,}/g, REDACTED],
+];
+export function createRedactor(secretValues) {
+    // Longest first, so a secret that contains another is replaced whole. Very short values would hide normal text.
+    const known = [...new Set(secretValues.filter((v) => v.length >= 6))].sort((a, b) => b.length - a.length);
+    const text = (input) => {
+        let out = input;
+        for (const secret of known)
+            if (out.includes(secret))
+                out = out.split(secret).join(REDACTED);
+        for (const [pattern, replacement] of PATTERNS)
+            out = out.replace(pattern, replacement);
+        return out;
+    };
+    const value = (input, depth = 0, seen = new WeakMap()) => {
+        if (typeof input === "string")
+            return text(input);
+        if (!input || typeof input !== "object")
+            return input;
+        if (seen.has(input))
+            return seen.get(input);
+        if (depth > 8)
+            return input;
+        if (input instanceof Error) {
+            const copy = Object.create(Object.getPrototypeOf(input));
+            seen.set(input, copy);
+            Object.defineProperty(copy, "message", { value: text(input.message), writable: true, configurable: true });
+            if (input.stack !== undefined)
+                Object.defineProperty(copy, "stack", { value: text(input.stack), writable: true, configurable: true });
+            if (input.name !== Object.getPrototypeOf(input)?.name)
+                Object.defineProperty(copy, "name", { value: input.name, writable: true, configurable: true });
+            for (const key of Object.keys(input))
+                copy[key] = redactEntry(key, input[key], depth, seen);
+            if ("cause" in input)
+                Object.defineProperty(copy, "cause", { value: value(input.cause, depth + 1, seen), writable: true, configurable: true });
+            return copy;
+        }
+        if (typeof Headers !== "undefined" && input instanceof Headers) {
+            const out = {};
+            seen.set(input, out);
+            input.forEach((v, k) => (out[k] = redactEntry(k, v, depth, seen)));
+            return out;
+        }
+        if (Array.isArray(input)) {
+            const out = [];
+            seen.set(input, out);
+            for (const item of input)
+                out.push(value(item, depth + 1, seen));
+            return out;
+        }
+        const proto = Object.getPrototypeOf(input);
+        if (proto !== Object.prototype && proto !== null)
+            return input;
+        const out = {};
+        seen.set(input, out);
+        for (const [k, v] of Object.entries(input))
+            out[k] = redactEntry(k, v, depth, seen);
+        return out;
+    };
+    const redactEntry = (key, entry, depth, seen) => {
+        if (SENSITIVE_KEY.test(key) && entry !== undefined && entry !== null && entry !== "")
+            return REDACTED;
+        return value(entry, depth + 1, seen);
+    };
+    return { text, value: (input) => value(input) };
+}
+/** A logger that redacts every message, data value and field before passing them on. */
+export function redactingLogger(logger, redactor) {
+    const pass = (level, message, data, fields) => {
+        const text = redactor.text(String(message));
+        if (fields !== undefined) {
+            const clean = {};
+            for (const [key, value] of Object.entries(fields))
+                clean[key] = typeof value === "string" ? redactor.text(value) : value;
+            return logger[level](text, data === undefined ? undefined : redactor.value(data), clean);
+        }
+        return data === undefined ? logger[level](text) : logger[level](text, redactor.value(data));
+    };
+    return {
+        info: (message, data, fields) => pass("info", message, data, fields),
+        error: (message, data, fields) => pass("error", message, data, fields),
+    };
+}
+/** The values of createApp({ redact }): strings, or objects that hold secrets (config() results). */
+export function redactValues(option) {
+    if (option === undefined)
+        return [];
+    if (!Array.isArray(option))
+        throw invalidRedact(`createApp({ redact }) must be an array, got ${typeof option}.`);
+    const out = [];
+    option.forEach((item, i) => {
+        if (item === undefined || item === null || item === "")
+            return; // an unset optional variable
+        if (typeof item === "string")
+            out.push(item);
+        else if (typeof item === "object" && configs.has(item))
+            out.push(...secretsOf(item));
+        else
+            throw invalidRedact(`createApp({ redact }) item ${i} is ${typeof item === "object" ? "an object that is not a config() result" : `a ${typeof item}`}.`);
+    });
+    return out;
+}
+const configs = new WeakSet();
+/** Internal: remember a config() result and its secret values, for createApp({ redact: [settings] }). */
+export function holdConfigSecrets(settings, values) {
+    configs.add(settings);
+    return holdSecrets(settings, values.map((v) => (v === undefined || v === null ? undefined : String(v))));
+}
+function invalidRedact(message) {
+    return new InferloError("IL6018", message, {
+        fix: "Pass the values to hide from logs, or your config() result: createApp({ redact: [settings, process.env.WEBHOOK_SECRET] }).",
+    });
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

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

package/dist/route.d.ts

@@ -8,6 +8,7 @@
  *
  * Secure by default: routes require a signed-in user unless you set auth: "public".
  */
+import type { Deprecation } from "./deprecation.ts";
 import type { AI } from "./ai/index.ts";
 import type { Db } from "./db/table.ts";
 import type { Jobs } from "./jobs.ts";
@@ -60,6 +61,16 @@ export interface RouteOptions<B extends AnySchema | undefined, Q extends ObjectS
     tool?: boolean | ToolOptions;
     /** Limit requests per user or IP: { max: 10, per: "minute", by: "user" }. More raise IL2005 (HTTP 429). */
     rateLimit?: RateLimit;
+    /**
+     * Longest time in milliseconds this route may take (reading the body and running the handler) before it
+     * answers 503 IL2007 and ctx.signal is aborted. Overrides createApp({ requestTimeoutMs }); false turns it off.
+     */
+    timeoutMs?: number | false;
+    /**
+     * Mark the route deprecated: true, or { since, sunset, link } to also send the Deprecation, Sunset and
+     * Link rel="deprecation" headers on every response. Shown in OpenAPI, describe and MCP tool descriptions.
+     */
+    deprecated?: boolean | Deprecation;
 }
 type PathParams<P extends string> = P extends `${string}:${infer Param}/${infer Rest}` ? {
     [K in Param | keyof PathParams<`/${Rest}`>]: string;
@@ -86,6 +97,13 @@ export interface Context<Body, Query, Params, User> {
     header(name: string, value: string): void;
     /** Values shared by middleware for this request. */
     state: Record<string, unknown>;
+    /**
+     * Aborted when the request times out (requestTimeoutMs or the route's timeoutMs) or the client disconnects.
+     * ctx.ai calls use it automatically; pass it to fetch and other slow work: fetch(url, { signal }).
+     */
+    signal: AbortSignal;
+    /** This request's id: sent back in the X-Request-Id header and added to the request's log entries. */
+    requestId: string;
     /** Run work after the response is sent (logging, webhooks). Errors are logged, not thrown. */
     waitUntil(promise: Promise<unknown>): void;
 }

package/dist/route.js.map

@@ -1 +1 @@
-{"version":3,"file":"route.js","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"AA6GA,MAAM,OAAO,YAAY;IACd,MAAM,CAAS;IACf,IAAI,CAAO;IACX,OAAO,CAAwB;IAExC,YAAY,MAAc,EAAE,IAAU,EAAE,OAA8B;QACpE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,qFAAqF;IACrF,MAAM,CACJ,OAQC;QAED,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAuC,EAE5I,CAAC;IACJ,CAAC;CACF;AAED,SAAS,OAAO,CAAC,MAAc;IAC7B,OAAO,CAOL,IAAU,EACV,UAAgD,EAAE,EAClD,EAAE,CAAC,IAAI,YAAY,CAAmB,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC;CAC1B,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAkB,CAAC,IAAI,KAAK,eAAe,CAAC;AACrG,CAAC"}
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"AA+HA,MAAM,OAAO,YAAY;IACd,MAAM,CAAS;IACf,IAAI,CAAO;IACX,OAAO,CAAwB;IAExC,YAAY,MAAc,EAAE,IAAU,EAAE,OAA8B;QACpE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,qFAAqF;IACrF,MAAM,CACJ,OAQC;QAED,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAuC,EAE5I,CAAC;IACJ,CAAC;CACF;AAED,SAAS,OAAO,CAAC,MAAc;IAC7B,OAAO,CAOL,IAAU,EACV,UAAgD,EAAE,EAClD,EAAE,CAAC,IAAI,YAAY,CAAmB,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC;CAC1B,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAkB,CAAC,IAAI,KAAK,eAAe,CAAC;AACrG,CAAC"}

package/dist/secure-headers.d.ts

@@ -0,0 +1,8 @@
+/** Header name to value; false leaves the header out. Names are case-insensitive. */
+export type SecureHeadersConfig = Record<string, string | false>;
+/** Sent on every response by default. Strict-Transport-Security is sent only over HTTPS. */
+export declare const DEFAULT_SECURE_HEADERS: Readonly<Record<string, string>>;
+/** The headers to send (lowercase names), from createApp({ secureHeaders }). */
+export declare function resolveSecureHeaders(option: boolean | SecureHeadersConfig | undefined): [string, string][];
+/** Add the headers the response does not set itself. Strict-Transport-Security only when the request came over HTTPS. */
+export declare function applySecureHeaders(response: Response, headers: [string, string][], https: boolean): Response;