@onetype/stack-api-kit 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+import { C as Context, a as Command, L as Listener, P as Participant, D as Definition, b as Plugin, R as Route, N as Narrowing, O as Outbox, S as Schedule, K as Kernel, c as Caller, d as Outbound, e as Store, f as Opening, g as Dialer, B as Budget, h as Logger } from './api-BZrn0c9T.js';
+export { A as Announcement, i as Described, E as Endpoint, j as Event, F as Failure, H as Handle, k as Heard, l as Hook, I as Incoming, J as Joined, m as Log, M as Method, n as MigrationFault, o as Options, p as Outgoing, q as Permission, r as Registered, s as Run, t as Scheduled, u as Schematic, v as Source, w as Step, x as Storage, T as Tables, y as createKernel, z as database } from './api-BZrn0c9T.js';
+import { z } from 'zod';
+import { Context as Context$1, Hono } from 'hono';
+import Database from 'better-sqlite3';
+import 'drizzle-orm/better-sqlite3';
+
+/** What a client is told: a status, a stable code, and one sentence. */
+type Answer = {
+    status: number;
+    code: string;
+    message: string;
+    /** Field-level detail, only ever from an input schema. */
+    fields?: Readonly<Record<string, string>>;
+};
+/**
+ * What a handler returns when the body alone is not the answer.
+ *
+ * A route returning a plain value gets 200, or 201 for a POST, which is what
+ * almost every route wants. This is for the rest: a redirect, a created
+ * resource naming where it went, a 304, a download with a filename.
+ *
+ * The body still passes the output schema. Status and headers are the only
+ * things this adds, because they are the only things a schema cannot carry.
+ */
+declare class Answered {
+    readonly status: number;
+    readonly body: unknown;
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(status: number, body: unknown, headers?: Readonly<Record<string, string>>);
+    /** Sends the caller somewhere else. */
+    static redirect(to: string, permanent?: boolean): Answered;
+}
+/** A refusal a plugin raises on purpose, meant to reach the caller. */
+declare class Refusal extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly fields: Readonly<Record<string, string>> | undefined;
+    constructor(status: number, code: string, message: string, fields?: Readonly<Record<string, string>>);
+}
+/**
+ * What the caller is told about a failure.
+ *
+ * Nothing that was not written for a caller ever reaches one. A thrown thing
+ * is either a Refusal, which a plugin wrote deliberately, or one of the few
+ * kernel codes that mean something to a client. Everything else answers 500
+ * with one fixed sentence, whatever it actually was.
+ *
+ * This is the whole point: a stack, a file path, a SQL fragment, a column
+ * name, a driver message and a config value are all things an attacker learns
+ * from, and none of them are things a caller needs.
+ */
+declare function answer(cause: unknown): Answer;
+
+/**
+ * Declares a plugin.
+ *
+ * The name is checked here rather than at start, so a typo names itself where
+ * it was written instead of in a stack from somewhere else.
+ *
+ * `Db` is what `ctx.db` will be: the Drizzle handle over this plugin's own
+ * tables. TypeScript cannot infer it, because the kernel never imports a
+ * driver, so a plugin that queries names it:
+ *
+ *     export default definePlugin.over<ItemRows>()("items", { … });
+ *
+ * A plugin that never touches the database writes `definePlugin(name, …)` and
+ * ignores all of this.
+ */
+declare function definePlugin<Schema extends z.ZodType, Services = unknown, Db = unknown>(name: string, definition: Definition<Schema, Services, Db>): Plugin;
+declare namespace definePlugin {
+    var over: <Db, Services = unknown>() => <Schema extends z.ZodType>(name: string, definition: Definition<Schema, Services, Db>) => Plugin;
+}
+/**
+ * Declares one route, with its input typed by its own schema.
+ *
+ * TypeScript settles a whole object literal's type before it looks inside an
+ * array, so a route written inline hands its handler `unknown`. Declaring the
+ * route through a function infers the schema first, and the handler reads its
+ * fields.
+ *
+ *     defineRoute<ItemCtx>()({
+ *         method: "GET",
+ *         input: z.object({ id: z.uuid() }),
+ *         handle: (given) => given.id,   // a string, no cast
+ *     })
+ */
+declare function defineRoute<Ctx = Context>(): <Input extends z.ZodType>(route: Route<Ctx, Input>) => Route<Ctx, Input>;
+/**
+ * Declares one listener, with its payload typed by the event's own schema.
+ *
+ * Pass the schema the emitting plugin declared: the kernel parses against it
+ * before delivering, so what arrives has already passed.
+ *
+ *     defineListener<ItemCtx>()(ItemMade.schema, {
+ *         describe: "…",
+ *         handle: (made) => made.id,   // a string, no cast
+ *     })
+ */
+declare function defineListener<Ctx = Context>(): <Payload extends z.ZodType>(_schema: Payload, listener: Listener<Ctx, z.infer<Payload>>) => Listener<Ctx, z.infer<Payload>>;
+/** Declares one participant, with its payload typed by the hook's schema. */
+declare function defineParticipant<Ctx = Context>(): <Payload extends z.ZodType>(_schema: Payload, participant: Participant<Ctx, z.infer<Payload>>) => Participant<Ctx, z.infer<Payload>>;
+/** Declares one command, with its input typed by its own schema. */
+declare function defineCommand<Ctx = Context>(): <Input extends z.ZodType>(command: Command<Ctx, Input>) => Command<Ctx, Input>;
+
+/**
+ * What the kernel refuses.
+ *
+ * A closed union rather than a string: a caller branches on it, and a new
+ * member is a compile error everywhere it is handled exhaustively.
+ */
+type FaultCode = "DUPLICATE_PLUGIN" | "UNKNOWN_DEPENDENCY" | "DEPENDENCY_CYCLE" | "INVALID_NAME" | "INVALID_CONFIG" | "INVALID_ROUTE" | "INVALID_PAYLOAD" | "WRONG_PAYLOAD" | "INVALID_OUTPUT" | "UNDECLARED_EVENT" | "UNDECLARED_HOOK" | "UNDECLARED_COMMAND" | "UNDECLARED_SCOPE" | "OUT_OF_SCOPE" | "UNDECLARED_PERMISSION" | "UNDECLARED_DEPENDENCY" | "UNDECLARED_HOST" | "DUPLICATE_ROUTE" | "DUPLICATE_EVENT" | "DUPLICATE_HOOK" | "DUPLICATE_COMMAND" | "DUPLICATE_PERMISSION" | "DUPLICATE_TABLE" | "UNAUTHENTICATED" | "PERMISSION_DENIED" | "RATE_LIMITED" | "NOT_STARTED";
+type Made = {
+    plugin?: string;
+    detail?: Readonly<Record<string, unknown>>;
+    cause?: unknown;
+};
+/**
+ * A refusal, naming the plugin it came from.
+ *
+ * What makes a message worth the line is the plugin, the key, the owner, and
+ * what to do about it. A code alone costs an hour.
+ *
+ * This is what the kernel says to whoever wrote the plugin. It is never what
+ * a client is told: `internal/answer.ts` decides that, and it says less.
+ */
+declare class KernelFault extends Error {
+    readonly code: FaultCode;
+    readonly plugin: string | undefined;
+    readonly detail: Readonly<Record<string, unknown>>;
+    constructor(code: FaultCode, message: string, made?: Made);
+    toString(): string;
+}
+
+/** One thing wrong, and everything needed to fix it. */
+type Wrong = {
+    code: KernelFault["code"];
+    plugin: string;
+    message: string;
+};
+
+/**
+ * Turns a declared scope into a condition.
+ *
+ * The kernel knows which table and which column, and nothing about how a
+ * query is built. This knows Drizzle and nothing about tenants, so neither
+ * half has to learn the other's business.
+ */
+declare function narrowing(owned: Readonly<Record<string, Readonly<Record<string, unknown>>>>): Narrowing;
+
+/**
+ * Where events wait, in the same database as the work they announce.
+ *
+ * That is the whole point: the row is written by the transaction that emitted
+ * the event, so the two cannot disagree. An event about work that rolled back
+ * rolls back with it, and work that committed leaves an event behind even if
+ * the process stops before anyone hears it.
+ *
+ * Its table is the kit's, not a plugin's, so no contract declares it and no
+ * `ctx.db` reaches it.
+ */
+declare function outbox(connection: Database.Database): Outbox;
+
+/**
+ * Where later work waits, in the same database as the work that asked for it.
+ *
+ * A job claimed by one process is not claimed by another: `take` marks and
+ * reads in one statement, so two processes beating at the same moment split
+ * the work rather than doubling it.
+ *
+ * Its table is the kit's, not a plugin's, so no contract declares it.
+ */
+declare function schedule(connection: Database.Database): Schedule;
+
+/**
+ * What every response carries, whatever it answers.
+ *
+ * An API serves data, not documents, so these are the ones that still mean
+ * something: the browser protections that matter for a page are set by
+ * whatever serves the page.
+ *
+ * - nosniff stops a browser guessing a content type it was already told.
+ * - DENY in frame-options and frame-ancestors 'none' keeps an error page out
+ *   of someone else's iframe.
+ * - no-store keeps an authenticated answer out of a shared cache. An API
+ *   response is per-caller, and a cache that kept one would hand it to the
+ *   next.
+ * - no-referrer keeps a path with an id in it from reaching another origin.
+ */
+declare const always: Readonly<Record<string, string>>;
+
+/** What serving needs to know. */
+type Serving = {
+    kernel: Kernel;
+    /**
+     * Who is calling. The project owns this entirely: a cookie, a bearer
+     * token, a header, whatever it decided a session is.
+     *
+     * Throwing answers 401. Returning undefined is an anonymous caller, which
+     * only a public route accepts.
+     */
+    identify?: ((c: Context$1) => Caller | undefined | Promise<Caller | undefined>) | undefined;
+    /**
+     * What to count an anonymous caller by, for a rate limit: an address, an
+     * api key, whatever the deployment can trust. Reading a forwarded header
+     * blindly lets anyone spend anyone's budget, so the project decides.
+     */
+    from?: ((c: Context$1) => string) | undefined;
+    origins?: readonly string[];
+    methods?: readonly string[];
+    headers?: readonly string[];
+    maxAge?: number;
+    /** The largest body accepted, before it is parsed. */
+    bodyBytes?: number;
+    /** Where a line goes. */
+    log?: ((level: "info" | "warn" | "error", line: string, about?: Readonly<Record<string, unknown>>) => void) | undefined;
+};
+declare function identifier(sent: string | undefined): string;
+declare function serve(serving: Serving): Hono;
+
+type Server = ReturnType<typeof serve>;
+
+type Dialing = {
+    timeoutMs?: number;
+    maxBytes?: number;
+    headers?: (() => Readonly<Record<string, string>>) | undefined;
+};
+declare class OutboundFault extends Error {
+    readonly code: "TIMEOUT" | "ABORTED" | "NETWORK" | "TOO_LARGE" | "MALFORMED" | "STATUS";
+    readonly status: number | undefined;
+    constructor(code: OutboundFault["code"], message: string, status?: number, cause?: unknown);
+}
+declare function dial(dialing?: Dialing): (call: Outbound) => Promise<unknown>;
+
+declare function same(left: string, right: string): boolean;
+
+type Window = {
+    requests: number;
+    seconds: number;
+};
+type Verdict = {
+    allowed: boolean;
+    remaining: number;
+    resetsIn: number;
+};
+declare function limiter(now?: () => number): {
+    take: (key: string, window: Window) => Verdict;
+    sweep: () => number;
+    size: () => number;
+};
+
+type Limiter = ReturnType<typeof limiter>;
+
+type Found = Readonly<Record<string, {
+    default?: Plugin;
+}>>;
+declare function discover(found: Found): Plugin[];
+
+declare function start(starting: Starting): Promise<Started>;
+
+type Starting = {
+    plugins: readonly Plugin[];
+    /**
+     * Where the database is, or a store the project built itself.
+     *
+     * Given a path, the kit opens SQLite and migrates. Given a store, it uses
+     * that one and migrates only if it can: a project running Postgres, or
+     * anything else answering `Store`, replaces the database without the kit
+     * knowing which one it got.
+     */
+    database: Opening | Store;
+    config?: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Who is calling.
+     *
+     * Given the kernel, because anything reading a session reads it from a
+     * plugin, and the kernel is what reaches one. Passing the function
+     * directly would mean holding a kernel that does not exist yet.
+     */
+    identify?: ((kernel: Kernel) => Serving["identify"]) | undefined;
+    http?: Omit<Serving, "kernel" | "identify" | "log"> | undefined;
+    /**
+     * How outbound calls are carried, or how the built-in one is configured.
+     *
+     * A dialler of its own is how a project reaches what the kit's cannot: a
+     * proxy, a signed request, a protocol that is not https. The kernel still
+     * refuses a host the plugin did not declare, whichever dialler carries it.
+     */
+    outbound?: Dialing | Dialer | undefined;
+    /**
+     * What counts requests against a route's declared limit.
+     *
+     * Omitted, the kit keeps one in memory, which counts for this process
+     * only. A deployment behind more than one process passes its own, so a
+     * limit means the same thing whichever process answered.
+     */
+    budget?: Budget | undefined;
+    /**
+     * Whether events are kept until a listener has heard them.
+     *
+     * Off by default, and that is a real choice rather than a default nobody
+     * revisits: without it an event lives only in memory, so a process that
+     * stops between a commit and its delivery leaves work done that nothing
+     * was ever told about. On, delivery is at least once and a listener that
+     * writes must survive hearing the same event twice.
+     */
+    outbox?: boolean | undefined;
+    /**
+     * Whether a plugin may ask for work later.
+     *
+     * Off by default. On, the kit keeps a schedule in the same database and
+     * asks it every second what is due. It knows seconds from now and nothing
+     * about calendars: work that repeats schedules itself again when it ends.
+     */
+    schedule?: boolean | undefined;
+    log?: Logger | undefined;
+};
+type Started = {
+    kernel: Kernel;
+    store: Store;
+    app: ReturnType<typeof serve>;
+    /** What a runtime serves: `export default { fetch }`. */
+    fetch: (request: Request) => Response | Promise<Response>;
+    stop: () => Promise<void>;
+};
+
+export { type Answer, Answered, Budget, Caller, Command, Context, Definition, Dialer, type Dialing, type FaultCode, Kernel, KernelFault, type Limiter, Listener, Logger, Narrowing, Opening, Outbound, OutboundFault, Outbox, Participant, Plugin, Refusal, Route, Schedule, type Server, type Serving, type Started, type Starting, Store, type Verdict, type Window, type Wrong, always, answer, defineCommand, defineListener, defineParticipant, definePlugin, defineRoute, dial, discover, identifier, limiter, narrowing, outbox, same, schedule, serve, start };