tina4-nodejs 3.13.92 → 3.13.95

package/types/core/src/dispatchPipeline.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The dispatch pipeline: the concerns of `dispatch`, named and extracted.
+ *
+ * `dispatch` was a 485-line closure at cyclomatic complexity 65 against a
+ * ceiling of 10, on the path of every request, nested inside `startServer`
+ * (which is why that measured 45 as well). These are its concerns as
+ * standalone functions, so each can be read and tested without standing up a
+ * server.
+ *
+ * PROLOGUE_STAGES run before anything else, in order. They are extracted FIRST
+ * because they close over nothing from `startServer` - only the raw
+ * request/response - so no context object is needed for them at all. The later
+ * stages need `router`, `staticDir`, `port` and `middleware`, and follow.
+ * `sessionAutoStart` is the one prologue stage that runs INSIDE the dispatch
+ * try-block, so a TINA4_SESSION_STRICT refusal renders a 500 like every other
+ * request error instead of rejecting `dispatch` into an unhandled rejection
+ * that takes the worker down (ADR-0021; parity with Python, where the raise
+ * leaves the request path and the ASGI server turns it into a 500).
+ *
+ * Ordering here is BEHAVIOUR, not taste:
+ *   * `headStripIntercept` MUST run before anything can write. Node streams its
+ *     response, so there is no single exit point to strip at - the interception
+ *     IS the mechanism (ADR-0011: the CONTRACT is the outcome, and Ruby and
+ *     Python satisfy it by stripping late at their single return instead).
+ *   * `sessionAutoStart` wraps `end` after that, so its save-and-set-cookie
+ *     runs on the real `end` rather than on the HEAD interceptor's.
+ *
+ * @see tina4-ruby/lib/tina4/dispatch_pipeline.rb - the same extraction, and
+ *      the source of the stage-list-as-data pattern.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Tina4Request } from "./types.js";
+/**
+ * The prologue, in order. Exported as DATA so the pipeline can be asserted and
+ * compared across frameworks without reading an implementation.
+ */
+export declare const PROLOGUE_STAGES: readonly ["resetRequestCaches", "headStripIntercept", "sessionAutoStart"];
+/**
+ * After the prologue, before a route is looked up.
+ *
+ * `wrapResponseEnd` MUST come before the global pass: it installs the end()
+ * wrapper that injects the dev toolbar and captures the request, and a
+ * middleware that short-circuits still has to be captured.
+ */
+export declare const REQUEST_STAGES: readonly ["blockAiPortReload", "wrapResponseEnd", "runGlobalMiddlewarePass"];
+/**
+ * A matched route, in order - and the order is BEHAVIOUR (ADR-0012):
+ * POST-MATCH globals -> auth gate -> the route's OWN middleware -> handler.
+ *
+ * The globals run BEFORE the gate so a rate limiter can throttle a brute-force
+ * login and an access log records the 401 - neither is possible if they only
+ * run on authenticated requests. The route's own middleware stays AFTER the
+ * gate, so middleware attached to a secured route never processes an
+ * unauthenticated request.
+ *
+ * `runGlobalMiddlewarePass` appears here AND in REQUEST_STAGES on purpose:
+ * one function, two phases. That split IS ADR-0012.
+ */
+export declare const ROUTE_STAGES: readonly ["runGlobalMiddlewarePass", "enforceRouteAuth", "runRouteMiddlewares", "invokeRouteHandler", "renderIfTemplateRoute"];
+/**
+ * Nothing matched a route: the fallback chain, walked until one answers.
+ *
+ * Order is BEHAVIOUR: a template beats the landing page (so a project's own
+ * pages/index.twig wins at "/"), 405 beats static (a known path with the wrong
+ * method is not a missing file), and the 404 is terminal.
+ *
+ * This chain runs AFTER matching because routes beat files (ADR-0010): a file
+ * from a build step or a careless deploy must never shadow a reviewed route.
+ *
+ * server.ts holds the same order as an array of the real FUNCTIONS - that is
+ * what dispatch actually walks. dispatchPipeline.test.ts asserts the two agree,
+ * so this list cannot drift from the runner.
+ */
+export declare const FALLBACK_STAGES: readonly ["serveTemplateFallback", "serveLandingPage", "serveMethodNotAllowed", "serveStaticAsset", "serveNotFound"];
+/** The catch arm. Everything above throws into this one. */
+export declare const ERROR_STAGES: readonly ["renderDispatchError"];
+/**
+ * Request-scoped DB query cache boundary.
+ *
+ * Clears the request-scoped cache on every live connection at the START of each
+ * request so it never serves rows across requests (persistent-mode connections
+ * are left alone). The ORM is loaded lazily and may be absent, so this is
+ * best-effort: a failure here must never break a request. Mirrors Python's
+ * dispatcher calling `Database.reset_request_caches()`.
+ */
+export declare function resetRequestCaches(): Promise<void>;
+/**
+ * RFC 9110 s9.3.2: the server MUST NOT send content in a HEAD response.
+ *
+ * Intercepts `write` / `end` so every code path - an explicit `Router.head()`
+ * handler, the GET auto-fallback, 405 and 404 responses - drops its body.
+ * Content-Length is preserved when present, so cache validators, link checkers
+ * and monitoring probes still see the size the equivalent GET would have sent.
+ *
+ * No-op for any method other than HEAD.
+ *
+ * @param rawReq Node's incoming message, read for the method
+ * @param rawRes Node's server response, whose write/end are replaced in place
+ */
+export declare function headStripIntercept(rawReq: IncomingMessage, rawRes: ServerResponse): void;
+/**
+ * Auto-start the session: read the cookie, create the session, then save it and
+ * set the cookie when the response ends.
+ *
+ * The incoming cookie is read by the SAME configured name the write side emits
+ * (`TINA4_SESSION_NAME`, default `tina4_session`) via the shared
+ * `sessionCookieName()` resolver - otherwise a renamed cookie would be written
+ * but never read back and the session would silently never resume. A whole
+ * cookie pair is matched by its exact `name=` prefix (split on ";", trim,
+ * startsWith) so `tina4_session` never matches `tina4_session_foo=` nor a value
+ * mid-header. Parity with Python `core/server._init_session`.
+ *
+ * @param rawReq Node's incoming message, read for cookies and the proxy scheme
+ * @param rawRes Node's server response, whose `end` is wrapped
+ * @param req    The Tina4 request the session is attached to
+ */
+export declare function sessionAutoStart(rawReq: IncomingMessage, rawRes: ServerResponse, req: Tina4Request): Promise<void>;

package/types/core/src/docs.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Tina4 Live API RAG — `Docs` module.
+ *
+ * Walks framework packages (`@tina4/core`, `@tina4/orm`, `@tina4/swagger`,
+ * `@tina4/frond`) and the user project's `src/` tree via lightweight TS
+ * regex parsing (no AST — works on .ts files without importing them, so
+ * user-code import errors don't break reflection).
+ *
+ * Exposes ranked search, class/method specs, a flat index, MCP-style
+ * static mirrors, and a Markdown drift/sync helper. Zero new runtime
+ * dependencies — Node stdlib only.
+ *
+ * Spec: plan/v3/22-LIVE-API-RAG.md
+ *
+ * Method names follow Tina4 Node.js convention (camelCase) — see PHP
+ * `Tina4\Docs` and Python `tina4_python.docs.Docs` for parity references.
+ */
+export interface DocsHit {
+    fqn: string;
+    kind: "class" | "method" | "function" | "property";
+    name: string;
+    signature: string;
+    summary: string;
+    file: string;
+    line: number;
+    version: string;
+    source: "framework" | "user" | "vendor";
+    visibility: "public" | "protected" | "private";
+    static?: boolean;
+    class?: string;
+    score: number;
+}
+export interface MethodSpec {
+    name: string;
+    fqn: string;
+    class: string;
+    kind: "method";
+    signature: string;
+    summary: string;
+    docblock: string;
+    file: string;
+    line: number;
+    visibility: "public" | "protected" | "private";
+    static: boolean;
+    source: "framework" | "user" | "vendor";
+    version: string;
+    params: Array<{
+        name: string;
+        type: string;
+        default?: string | null;
+    }>;
+    return: string;
+}
+export interface ClassSpec {
+    fqn: string;
+    kind: "class";
+    name: string;
+    file: string;
+    line: number;
+    summary: string;
+    docblock: string;
+    source: "framework" | "user" | "vendor";
+    version: string;
+    methods: Array<Omit<MethodSpec, "params" | "return"> & {
+        params?: unknown[];
+        return?: string;
+    }>;
+    properties: unknown[];
+}
+export interface IndexEntry {
+    fqn: string;
+    kind: "class" | "method" | "function" | "property";
+    name: string;
+    signature: string;
+    summary: string;
+    file: string;
+    line: number;
+    version: string;
+    source: "framework" | "user" | "vendor";
+    visibility: "public" | "protected" | "private";
+    static?: boolean;
+    class?: string;
+}
+export interface DriftHit {
+    method: string;
+    line: number;
+    block: string;
+}
+export declare class Docs {
+    private projectRoot;
+    private frameworkRoots;
+    private version;
+    private indexCache;
+    private frameworkEntries;
+    private userEntries;
+    private userMtime;
+    private frameworkMtime;
+    constructor(projectRoot: string);
+    /**
+     * Search the merged framework + user index for query-matching entities.
+     * Source filter accepts `all` (default), `framework`, `user`, `vendor`.
+     * Private/underscore methods are excluded unless `includePrivate=true`.
+     */
+    search(query: string, k?: number, source?: string, includePrivate?: boolean): DocsHit[];
+    /**
+     * Resolve a class by exact FQN, documented public import path, or bare name.
+     *
+     * Node stores the bare class name as the FQN (`Database`), but a developer
+     * reading the docs may type the published path (`@tina4/orm.Database`,
+     * `orm/Database`) or just `Database`. Match exactly first, then by class
+     * name (last path segment), disambiguating by requiring the given segments
+     * to appear in the stored FQN/file (framework + shortest wins). Unknown
+     * names stay `null` — no false positives.
+     */
+    private resolveClassEntry;
+    /**
+     * Return the full spec for a single class, or `null` if not found.
+     */
+    classSpec(fqn: string): ClassSpec | null;
+    /**
+     * Return the spec for a single method, or `null` if unknown.
+     */
+    methodSpec(classFqn: string, methodName: string): MethodSpec | null;
+    /**
+     * Flat list of every reflected entity (classes + methods + functions),
+     * user + framework. Vendor entries are included here for completeness.
+     */
+    index(): IndexEntry[];
+    static mcpSearch(query: string, k?: number, projectRoot?: string, source?: string, includePrivate?: boolean): DocsHit[];
+    static mcpMethod(classFqn: string, name: string, projectRoot?: string): MethodSpec | null;
+    static mcpClass(fqn: string, projectRoot?: string): ClassSpec | null;
+    static checkDocs(mdPath: string, projectRoot?: string): {
+        drift: DriftHit[];
+    };
+    static syncDocs(mdPath: string, projectRoot?: string): void;
+    private static cached;
+    private ensureIndex;
+    private maxMtime;
+    private scoreEntry;
+    private renderGeneratedBlock;
+}

package/types/core/src/docsAutoDiscovery.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Write `.tina4/mcp.json` and (if `.git/` exists) append `.tina4/` to .gitignore.
+ *
+ * Returns true if the discovery file was written or updated.
+ */
+export declare function writeMcpDiscovery(projectRoot: string, port: number): boolean;

package/types/core/src/dotenv.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Load environment variables from a root DIRECTORY or a single .env file.
+ *
+ * Pass a **directory** and it loads `<dir>/.env.local` then `<dir>/.env`, both
+ * first-wins, which IS the precedence real-env > `.env.local` > `.env`. That is
+ * the canonical form in all four frameworks.
+ *
+ * Before this, the ordering was the CALLER's job and this doc comment was the
+ * only place it was written down: load `.env.local` first, then `.env`, both
+ * with override=false. Every caller had to remember, and getting it wrong
+ * (override=true on `.env.local`) lets a stray gitignored file clobber an
+ * explicitly set real env var such as a production TINA4_SECRET. A rule nobody
+ * can forget beats a rule written in a comment.
+ *
+ * A **file** path still works exactly as before: only that file is read, and the
+ * caller owns the ordering.
+ *
+ * By default this does NOT override existing process.env values — it is
+ * first-wins, which is how a real env var always beats both files.
+ *
+ * Resolution order when `path` is omitted:
+ *   1. `TINA4_ENV_FILE` env var (if set and non-empty) — the named file, plus
+ *      `.env.local` BESIDE it, so pointing at `.env.staging` does not silently
+ *      stop honouring local overrides
+ *   2. the current working directory, as a root
+ *
+ * @param path     - A root directory (canonical) OR a path to a single .env file.
+ * @param override - When true, overwrite keys already present in process.env.
+ * @returns The parsed key-value pairs. For the directory form this is the merge
+ *          of both files, with `.env.local` winning on a duplicate key.
+ */
+export declare function loadEnv(path?: string, override?: boolean): Record<string, string>;
+/**
+ * Get an environment variable value with an optional default.
+ *
+ * @param key - The environment variable name.
+ * @param defaultValue - Value to return if the variable is not set.
+ * @returns The environment variable value, or the default.
+ */
+export declare function getEnv(key: string, defaultValue?: string): string | undefined;
+/**
+ * Get a required environment variable. Throws if not set.
+ *
+ * @param key - The environment variable name.
+ * @returns The environment variable value.
+ * @throws Error if the variable is not set.
+ */
+/**
+ * Validate that required environment variables exist, and return them.
+ *
+ * Takes VARARGS and returns a map, matching Python, PHP and Ruby. It used to
+ * take one key and return that value, so checking five variables meant five
+ * calls that each failed on the first problem - an operator fixing a deployment
+ * got one name per restart instead of the whole list.
+ *
+ * @param keys - Variable names that must be set.
+ * @returns Every requested key mapped to its value.
+ * @throws Error naming ALL missing variables, not just the first.
+ */
+export declare function requireEnv(...keys: string[]): Record<string, string>;
+/**
+ * Check if an environment variable exists (is defined in process.env).
+ *
+ * @param key - The environment variable name.
+ * @returns true if the variable is set, false otherwise.
+ */
+export declare function hasEnv(key: string): boolean;
+/**
+ * Return all currently loaded environment variables.
+ *
+ * @returns A shallow copy of process.env as a record.
+ */
+export declare function allEnv(): Record<string, string | undefined>;
+/**
+ * Check if a value is truthy for env boolean checks.
+ *
+ * Accepts: "true", "True", "TRUE", "1", "yes", "Yes", "YES", "on", "On", "ON".
+ * Everything else is falsy (including empty string, undefined, not set).
+ *
+ * Mirrors Python's `is_truthy()` in `tina4_python.dotenv`.
+ */
+export declare function isTruthy(val: string | undefined | null): boolean;
+/**
+ * Remove all environment variables that were loaded by loadEnv().
+ * Useful for testing. Only removes keys set by loadEnv(), not pre-existing system env vars.
+ */
+export declare function resetEnv(): void;

package/types/core/src/env.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Typed environment-variable helpers.
+ *
+ * All methods are static so callers can write `Env.bool(...)` without
+ * instantiating anything — matching the Python/PHP/Ruby ports.
+ */
+export declare class Env {
+    /**
+     * Read `name` and coerce to bool.
+     *
+     * Truthy values (case-insensitive after trim): `1`, `true`, `on`, `yes`,
+     * `y`, `t`. Falsy: `0`, `false`, `off`, `no`, `n`, `f`, empty string.
+     * Anything else returns the `defaultValue` — never throws.
+     */
+    static bool(name: string, defaultValue?: boolean): boolean;
+    /** Read `name` and coerce to int. Returns `defaultValue` on parse failure. */
+    static int(name: string, defaultValue?: number): number;
+    /** Read `name` and coerce to float. Returns `defaultValue` on parse failure. */
+    static float(name: string, defaultValue?: number): number;
+    /**
+     * Read `name` as a string. Returns `defaultValue` if unset.
+     *
+     * Whitespace is preserved — this is a pass-through for the raw env value.
+     * `Env.str("PATH")` is exactly `process.env.PATH ?? ""` with a more
+     * discoverable name.
+     */
+    static str(name: string, defaultValue?: string): string;
+}

package/types/core/src/errorOverlay.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tina4 Debug — Rich error overlay for development mode.
+ *
+ * Renders a professional, syntax-highlighted HTML error page when an unhandled
+ * exception occurs in a route handler.
+ *
+ *   import { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
+ *
+ *   try {
+ *     await handler(req, res);
+ *   } catch (err) {
+ *     const html = isDebugMode()
+ *       ? renderErrorOverlay(err as Error, req)
+ *       : renderProductionError();
+ *     res.html(html, 500);
+ *   }
+ *
+ * Only activate when TINA4_DEBUG is true.
+ * In production, call renderProductionError() instead.
+ */
+/**
+ * Render a rich HTML error overlay.
+ *
+ * @param error - The caught error.
+ * @param request - Optional request object with method, url, headers, etc.
+ * @returns Complete HTML page string.
+ */
+export declare function renderErrorOverlay(error: Error, request?: any): string;
+/**
+ * Render a safe, generic error page for production.
+ */
+export declare function renderProductionError(statusCode?: number, message?: string, path?: string): string;
+/**
+ * Check if TINA4_DEBUG is enabled.
+ */
+export declare function isDebugMode(): boolean;

package/types/core/src/events.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Tina4 Events — Simple observer pattern for decoupled communication.
+ *
+ * Zero-dependency event system. Fire events, register listeners.
+ *
+ *   Events.on("user.created", (user) => console.log(`Welcome ${user.name}!`));
+ *   Events.emit("user.created", { name: "Alice", email: "alice@example.com" });
+ *
+ * One-time listeners:
+ *
+ *   Events.once("app.ready", () => console.log("App started!"));
+ */
+export declare class Events {
+    /**
+     * Register a listener for an event.
+     * Higher priority runs first.
+     */
+    static on(event: string, callback: (...args: unknown[]) => void, priority?: number): void;
+    /**
+     * Register a listener that fires only once then auto-removes.
+     */
+    static once(event: string, callback: (...args: unknown[]) => void, priority?: number): void;
+    /**
+     * Remove a specific listener, or all listeners for an event.
+     *
+     *   Events.off("user.created", handler)  // remove specific
+     *   Events.off("user.created")           // remove all for event
+     */
+    static off(event: string, callback?: (...args: unknown[]) => void): void;
+    /**
+     * Fire an event synchronously. Returns array of listener results.
+     *
+     * Listener isolation (E1): each listener call is wrapped — a listener
+     * that THROWS does NOT abort the rest of emit(). The error is LOGGED
+     * (never silent) and the failed listener contributes a `null` slot, so
+     * N listeners always yield N results in priority order; surviving
+     * listeners run regardless of an earlier throw.
+     *
+     * Pass `{ strict: true }` to RE-RAISE on the first listener error
+     * instead of isolating it (later listeners then do NOT run).
+     *
+     * once() cleanup stays correct under isolation: the one-shot listener is
+     * spliced out BEFORE its callback runs, so a throw never leaves it
+     * registered.
+     */
+    static emit(event: string, ...args: unknown[]): unknown[];
+    static emit(event: string, options: {
+        strict?: boolean;
+    }, ...args: unknown[]): unknown[];
+    /**
+     * Emit an event and await all async listeners.
+     * Returns array of resolved results from each listener.
+     *
+     * Listener isolation (E1): identical to emit() — each awaited listener
+     * is isolated; a rejection/throw is LOGGED and contributes a `null`
+     * slot without aborting the others. `{ strict: true }` re-raises on the
+     * first error.
+     */
+    static emitAsync(event: string, ...args: unknown[]): Promise<unknown[]>;
+    static emitAsync(event: string, options: {
+        strict?: boolean;
+    }, ...args: unknown[]): Promise<unknown[]>;
+    /**
+     * Get all listener callbacks for an event (in priority order).
+     */
+    static listeners(event: string): Array<(...args: unknown[]) => void>;
+    /**
+     * List all registered event names.
+     */
+    static events(): string[];
+    /**
+     * Remove all listeners for all events.
+     */
+    static clear(): void;
+}

package/types/core/src/fakeData.d.ts

@@ -0,0 +1,55 @@
+export declare class FakeData {
+    private rng;
+    private seeded;
+    constructor(seed?: number);
+    /** Static factory — create a seeded FakeData instance. */
+    static seed(seed: number): FakeData;
+    /** Returns a random integer in [min, max) using the instance PRNG. */
+    private randInt;
+    /** Pick a random element from an array. */
+    private pick;
+    firstName(): string;
+    lastName(): string;
+    name(): string;
+    email(): string;
+    phone(): string;
+    address(): string;
+    city(): string;
+    country(): string;
+    zipCode(): string;
+    company(): string;
+    jobTitle(): string;
+    paragraph(sentences?: number): string;
+    sentence(words?: number): string;
+    word(): string;
+    integer(min?: number, max?: number): number;
+    numeric(min?: number, max?: number, decimals?: number): number;
+    boolean(): boolean;
+    date(start?: string, end?: string): string;
+    uuid(): string;
+    url(): string;
+    ipAddress(): string;
+    colorHex(): string;
+    /** Returns fake test credit card numbers (Luhn-valid test patterns). */
+    creditCard(): string;
+    currency(): string;
+    /**
+     * Returns multi-paragraph text.
+     * Matches Python's text() method.
+     */
+    text(paragraphs?: number): string;
+    /**
+     * Returns a random element from the given array.
+     * Matches Python's choice() method.
+     */
+    choice<T>(items: T[]): T;
+    /**
+     * Run seed files from a directory. Each file should export a default async function.
+     * Returns an array of executed file paths.
+     */
+    seedDir(seedDir?: string): Promise<string[]>;
+    /**
+     * Run a generator function `count` times and return the results.
+     */
+    run(fn: () => Record<string, unknown>, count?: number): Record<string, unknown>[];
+}

package/types/core/src/feedback.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Customer feedback widget — Tier 4 port from tina4-python.
+ *
+ * End-users of a shipped Tina4 app give UX feedback via a floating bubble
+ * widget. Widget visibility + API are gated by TWO env flags:
+ *
+ *   - TINA4_ENABLE_FEEDBACK   master switch (explicit opt-in)
+ *   - TINA4_FEEDBACK_WHITELIST comma-separated emails / user IDs
+ *
+ * Architecture (mirrors Python `tina4_python/dev_admin/__init__.py`
+ * lines 1440-1645):
+ *
+ *   1. Framework middleware injects <script src="/__feedback/widget.js">
+ *      into HTML responses for whitelisted users only.
+ *   2. Widget POSTs to /__feedback/api/turn for each conversational turn.
+ *   3. That handler verifies whitelist + rate-limit, stamps the user
+ *      identity server-side (client cannot fake `sender`), then forwards
+ *      to the Rust agent's /feedback/intake.
+ *
+ * The widget is for END USERS of a shipped app — the /__dev paths get
+ * skipped so the dev admin's own chat bubble doesn't sit on top of the
+ * customer feedback bubble.
+ */
+import type { RouteHandler, Tina4Request } from "./types.js";
+import type { Router } from "./router.js";
+/**
+ * Master switch — both this AND a non-empty whitelist must be set for
+ * the widget to render or the API to accept submissions. Mirrors
+ * Python's `_feedback_enabled()`.
+ */
+export declare function feedbackEnabled(): boolean;
+/**
+ * Comma-separated emails / user IDs in env, lowercased + trimmed.
+ * Returns [] when the master switch is off so callers can short-circuit
+ * with a single check. Mirrors Python's `_feedback_whitelist()`.
+ */
+export declare function feedbackWhitelist(): string[];
+/**
+ * Best-effort user identity from JWT/Bearer auth. Falls back to
+ * TINA4_FEEDBACK_DEV_USER (local dev convenience — lets the framework
+ * owner test the widget without a full auth setup). Mirrors Python's
+ * `_feedback_identify_user()`.
+ */
+export declare function feedbackIdentifyUser(request: Tina4Request): string | null;
+/**
+ * Returns [allowed, userId]. Both halves are required — feature off when
+ * either is falsy. Mirrors Python's `_feedback_is_whitelisted()`.
+ */
+export declare function feedbackIsWhitelisted(request: Tina4Request): [boolean, string | null];
+/**
+ * 5 turns/hour per user, sliding window. Prunes old timestamps lazily on
+ * every call (no background task needed). Mirrors Python's
+ * `_feedback_rate_limit_ok()`.
+ */
+export declare function feedbackRateLimitOk(user: string): boolean;
+/** Test-only: clear rate-limit state between cases. Not part of public API. */
+export declare function _resetFeedbackRateLimit(): void;
+/**
+ * Insert the widget <script> into HTML for whitelisted users. Called
+ * from the response pipeline right before the body is flushed. No-op if:
+ *   - request path starts with /__dev or /__feedback (developer
+ *     pages have their own chat trigger)
+ *   - master switch / whitelist not set
+ *   - user not in whitelist
+ *   - html lacks </body>
+ * Idempotent — looks for the `data-tina4-feedback` marker and bails.
+ * Mirrors Python's `inject_feedback_widget()`.
+ */
+export declare function injectFeedbackWidget(request: Tina4Request, html: string): string;
+/**
+ * POST /__feedback/api/turn — proxy one conversational turn to the Rust
+ * agent's `/feedback/intake`. Server stamps `sender` from the verified
+ * identity so the client cannot inject who they are. Mirrors Python's
+ * `_api_feedback_turn()`.
+ */
+export declare const handleFeedbackTurn: RouteHandler;
+declare const WIDGET_BUNDLE_PATH: string;
+/**
+ * GET /__feedback/widget.js — serve the widget bundle with no-cache
+ * headers so a broken bundle doesn't get stuck in browser caches.
+ * Mirrors Python's `_api_feedback_widget_js()`.
+ */
+export declare const handleFeedbackWidgetJs: RouteHandler;
+/**
+ * Register the two feedback routes on a Router. Called from the dev
+ * admin setup so the routes only exist when the dev surface is
+ * enabled — production deployments without TINA4_DEBUG also skip them.
+ */
+export declare function registerFeedbackRoutes(router: Router): void;
+export { WIDGET_BUNDLE_PATH };