@browserlessapi/inferlo 0.5.0 → 0.7.0

package/dist/app.d.ts

@@ -3,15 +3,21 @@
  * fetch(Request) => Response handler that runs on Node, Bun, Deno and edge runtimes.
  */
 import { type AI, type AIConfig } from "./ai/index.ts";
+import { type Cache, type CacheConfig } from "./cache.ts";
 import { type Db } from "./db/table.ts";
 import type { Adapter } from "./db/types.ts";
 import { type AppDescription } from "./describe.ts";
 import type { AnyModel } from "./model.ts";
 import { type AppDb, type AppUser, type Method, type RouteDef } from "./route.ts";
+import { type RedisClient } from "./redis.ts";
 import { type RateLimitConfig } from "./rate-limit.ts";
 import { type AppJobs, type JobQueueConfig, type JobSource } from "./jobs.ts";
+import { type AppEvents, type EventsConfig } from "./events.ts";
 import { type LogFields, type LoggingConfig } from "./logging.ts";
+import { type TracingConfig } from "./tracing.ts";
 import { type MetricsConfig } from "./metrics.ts";
+import { type AnyModule, type ModuleModels } from "./module.ts";
+import { type Permissions } from "./permissions.ts";
 import { type SecureHeadersConfig } from "./secure-headers.ts";
 export interface AuthConfig {
     /** Return the signed-in user for this request, or null. */
@@ -21,6 +27,12 @@ export interface AuthConfig {
     }): AppUser | null | undefined | Promise<AppUser | null | undefined>;
     /** Roles of a user, checked when a route uses auth: "<role>". Default: user.roles ?? []. */
     roles?(user: AppUser): string[];
+    /**
+     * The tenant (organisation, workspace, customer) a user belongs to, for tenant-scoped models
+     * (model(name, fields, { tenant: true })): ctx.db filters and stamps their rows with it.
+     * Default: user.tenantId. Return null for a user without a tenant.
+     */
+    tenant?(user: AppUser): string | null | undefined;
 }
 export interface CorsConfig {
     /** Allowed origins, or "*". */
@@ -52,7 +64,7 @@ export interface HealthConfig {
     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() }. */
+    /** Your own checks, by name ("database", "ai" and, with createApp({ redis }), "redis" are built in): { search: () => search.ping() }. */
     checks?: Record<string, HealthCheck>;
     /** Time each check may take before it fails. Default 5000 ms. */
     timeoutMs?: number;
@@ -80,20 +92,37 @@ export interface ReadinessReport {
 export type RouteSource = RouteDef | readonly RouteSource[] | {
     readonly [name: string]: unknown;
 };
-export interface AppConfig<Models extends readonly AnyModel[]> {
+export interface AppConfig<Models extends readonly AnyModel[], Modules extends readonly AnyModule[] = readonly AnyModule[]> {
     /** Shown in OpenAPI, MCP and describe. */
     name?: string;
     version?: string;
     description?: string;
     models?: Models;
+    /**
+     * Feature modules from module("billing", { imports, models, routes, jobs, provides }). Their models, routes
+     * and jobs join the app's own; every module a module imports must be listed here too.
+     */
+    modules?: Modules;
     routes?: RouteSource[];
-    /** Background jobs and crons: jobs, cron(schedule, job) values, arrays or modules (import * as jobs from "./jobs.ts"). */
+    /** Background jobs, crons and event subscriptions: jobs, cron(schedule, job) and on(event, job) values, arrays or modules (import * as jobs from "./jobs.ts"). */
     jobs?: JobSource[];
     /** Where queued jobs are kept: { store: "memory" } (default) or { store: "database" } (Postgres table inferlo_jobs, shared by every instance). */
     jobQueue?: JobQueueConfig;
+    /**
+     * Events between services: { transport: "redis" } sends published events through Redis Streams (needs redis and
+     * name), so every service with an on(event, job) subscription gets them. Default: events stay in this app.
+     */
+    events?: EventsConfig;
+    /**
+     * Where ctx.cache and app.cache keep entries: { store: "memory" } (default), { store: "database" } (Postgres
+     * table inferlo_cache) or { store: "redis" } (createApp({ redis })), both shared by every instance.
+     */
+    cache?: CacheConfig;
     /** Database adapter. Default: memory(). Use postgres() from "@browserlessapi/inferlo/postgres" in production. */
     db?: Adapter;
     auth?: AuthConfig;
+    /** Named permissions from permissions({ ... }), required when a route sets permission. */
+    permissions?: Permissions<any>;
     ai?: AIConfig;
     cors?: boolean | CorsConfig;
     middleware?: Middleware[];
@@ -103,7 +132,16 @@ export interface AppConfig<Models extends readonly AnyModel[]> {
     mcp?: string | false;
     /** Maximum request body in bytes. Default 1 MiB. */
     maxBodySize?: number;
-    /** Where route rateLimit counts are kept: { store: "memory" } (default) or { store: "database" } (Postgres, shared by every instance). */
+    /**
+     * A connected Redis client (createClient() from the redis package, after await client.connect()), for
+     * rateLimit: { store: "redis" } and cache: { store: "redis" }. /ready checks that it answers. Inferlo never closes it: call client.close()
+     * after app.close().
+     */
+    redis?: RedisClient;
+    /**
+     * Where route rateLimit counts are kept: { store: "memory" } (default), { store: "database" } (Postgres) or
+     * { store: "redis" } (createApp({ redis })), both shared by every instance.
+     */
     rateLimit?: RateLimitConfig;
     /**
      * Behind a load balancer or proxy that sets X-Forwarded-For: true uses its first address as the client IP
@@ -148,6 +186,12 @@ export interface AppConfig<Models extends readonly AnyModel[]> {
      * public, so keep it off the internet. Off by default.
      */
     metrics?: boolean | MetricsConfig;
+    /**
+     * OpenTelemetry tracing: import * as otel from "@opentelemetry/api", then tracing: { api: otel }. Every request
+     * gets a server span that continues the caller's trace, and log entries get traceId and spanId. AI calls and
+     * database queries inside it get client spans (model, tokens and cost; table and operation). Off by default.
+     */
+    tracing?: TracingConfig;
 }
 export interface RequestOptions {
     method?: Method | Lowercase<Method> | "OPTIONS" | "HEAD";
@@ -163,11 +207,18 @@ export interface App<Models extends readonly AnyModel[]> {
     readonly name: string;
     readonly version: string;
     readonly routes: readonly RouteDef[];
+    /** Every model: createApp({ models }) and then the models of each module. */
     readonly models: Models;
+    /** The feature modules from createApp({ modules }). */
+    readonly modules: readonly AnyModule[];
     readonly db: Db<Models>;
     readonly ai: AI;
     /** Background jobs: app.jobs.enqueue(job, input), app.jobs.start() to run them, app.jobs.runDue() in tests. */
     readonly jobs: AppJobs;
+    /** Events: app.events.publish(orderPaid, payload) queues the jobs subscribed with on(event, job) in createApp({ jobs }). */
+    readonly events: AppEvents;
+    /** The app cache, the same as ctx.cache: await app.cache.getOrSet(key, { ttlMs, tags }, compute), app.cache.invalidate(tag). */
+    readonly cache: Cache;
     /** Standard fetch handler: export default app works on Bun, Deno and Cloudflare Workers. */
     fetch(req: Request, ...rest: unknown[]): Promise<Response>;
     /** In-process request for tests: await app.request("/tickets", { method: "POST", json: {...}, as: user }). */
@@ -189,6 +240,9 @@ export interface App<Models extends readonly AnyModel[]> {
     close(options?: CloseOptions): Promise<void>;
     /** Machine-readable map of the whole app: routes, models, auth and AI. */
     describe(): AppDescription;
-    openapi(): Record<string, unknown>;
+    /** The OpenAPI 3.1 document: every route, or with { version: "v1" } the routes of apiVersion("v1", ...) and the routes outside every version. */
+    openapi(options?: {
+        version?: string;
+    }): Record<string, unknown>;
 }
-export declare function createApp<const Models extends readonly AnyModel[] = []>(config?: AppConfig<Models>): App<Models>;
+export declare function createApp<const Models extends readonly AnyModel[] = [], const Modules extends readonly AnyModule[] = []>(config?: AppConfig<Models, Modules>): App<[...Models, ...ModuleModels<Modules>]>;