tina4-nodejs 3.13.92 → 3.13.94

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

@@ -0,0 +1,256 @@
+export interface SessionConfig {
+    /** Session backend type: "file", "redis", "valkey", "mongo", "database" (or "db") */
+    backend?: string;
+    /** File storage path (default: "data/sessions") */
+    path?: string;
+    /** Time-to-live in seconds (default: 3600) */
+    ttl?: number;
+    /** Redis host (default: "127.0.0.1") */
+    redisHost?: string;
+    /** Redis port (default: 6379) */
+    redisPort?: number;
+    /** Redis password (optional) */
+    redisPassword?: string;
+    /** Redis key prefix (default: "tina4:session:") */
+    redisPrefix?: string;
+    /** Redis database index (default: 0) */
+    redisDb?: number;
+}
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+/**
+ * Base interface for session storage backends.
+ * Implementations must provide read, write, and destroy.
+ */
+export interface SessionHandler {
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl?: number): void;
+    destroy(sessionId: string): void;
+    /** Garbage-collect expired sessions. Optional — Redis/Valkey/Mongo handle TTL natively. */
+    gc?(maxLifetime: number): void;
+}
+export declare class FileSessionHandler implements SessionHandler {
+    private storagePath;
+    constructor(storagePath?: string);
+    private ensureDir;
+    private filePath;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl?: number): void;
+    destroy(sessionId: string): void;
+    gc(maxLifetime?: number): void;
+}
+/**
+ * Redis session handler using raw TCP (RESP protocol).
+ *
+ * Uses synchronous socket communication — no external Redis client required.
+ * Stores session data as JSON strings with Redis TTL for automatic expiry.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_REDIS_HOST    (default: "127.0.0.1")
+ *   TINA4_SESSION_REDIS_PORT    (default: 6379)
+ *   TINA4_SESSION_REDIS_PASSWORD (optional)
+ *   TINA4_SESSION_REDIS_PREFIX  (default: "tina4:session:")
+ *   TINA4_SESSION_REDIS_DB      (default: 0)
+ *
+ * Or pass via SessionConfig.
+ */
+export declare class RedisSessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private password;
+    private prefix;
+    private db;
+    constructor(config?: SessionConfig);
+    /**
+     * Execute a Redis command synchronously against the live server.
+     *
+     * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
+     * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
+     * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
+     * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
+     */
+    private execSync;
+    private key;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl?: number): void;
+    destroy(sessionId: string): void;
+}
+export declare class Session {
+    private handler;
+    private ttl;
+    private sessionId;
+    private data;
+    /**
+     * Dirty flag — set when data changes, cleared only on a successful write.
+     * Retained on a failed write so a later save() retries once the backend
+     * recovers (mirrors the Python `_dirty` semantics).
+     */
+    private dirty;
+    /**
+     * Backend-failure policy: log-loud + degrade (default), or re-raise when
+     * TINA4_SESSION_STRICT is truthy. A read failure logs + yields an empty
+     * session, a write failure logs + returns false (best-effort, dirty
+     * retained), destroy/gc failures log + swallow. Parity across all four
+     * frameworks. Strict mode is the escape hatch (same as events/seeding).
+     */
+    private strict;
+    constructor(backend?: string, config?: SessionConfig);
+    /**
+     * Use a custom session handler (for advanced use cases).
+     */
+    setHandler(handler: SessionHandler): void;
+    private logBackendError;
+    /** Read through the backend; on FAILURE log + degrade to empty (or re-throw under strict). */
+    private safeRead;
+    /** Write through the backend; on FAILURE log + return false (or re-throw under strict). */
+    private safeWrite;
+    /** Destroy through the backend; on FAILURE log + swallow (or re-throw under strict). */
+    private safeDestroy;
+    /**
+     * Start or resume a session.
+     * @param sessionId - Existing session ID to resume (optional)
+     * @returns The session ID
+     */
+    start(sessionId?: string): string;
+    /**
+     * Get a value from the session.
+     */
+    get(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Set a value in the session.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Delete a key from the session.
+     */
+    delete(key: string): void;
+    /**
+     * Destroy the entire session.
+     *
+     * A backend failure is logged (never silent) but does not throw under the
+     * default policy — local state is cleared regardless so the request proceeds.
+     */
+    destroy(): void;
+    /**
+     * Get all session data (excluding internal keys).
+     */
+    all(): Record<string, unknown>;
+    /**
+     * Clear all session data (but keep the session alive).
+     */
+    clear(): void;
+    /**
+     * Check if a key exists in the session.
+     */
+    has(key: string): boolean;
+    /**
+     * Regenerate the session ID (keeps data, new ID).
+     *
+     * Call this right after a successful login or any privilege change to defeat
+     * session fixation — the pre-auth ID is destroyed and the data is carried
+     * onto a fresh, unguessable ID. A backend destroy/write failure is logged
+     * (never silent) but does not throw under the default policy.
+     */
+    regenerate(): string;
+    /**
+     * Dual-mode flash: set with value, get+remove without.
+     *
+     *   session.flash("message", "Saved!")  // set
+     *   session.flash("message")            // get + auto-remove → "Saved!"
+     */
+    flash(key: string, value?: unknown): unknown;
+    /**
+     * Get flash data by key (alias for flash(key) without value).
+     */
+    getFlash(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Get the current session ID.
+     */
+    getSessionId(): string | null;
+    /**
+     * Return a Set-Cookie header value for this session.
+     *
+     * Honours these env vars (cross-framework parity):
+     *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+     *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+     *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+     *   TINA4_SESSION_SECURE    — emit Secure (default: false)
+     */
+    cookieHeader(cookieName?: string): string;
+    /**
+     * Run garbage collection on the session backend.
+     * Removes expired file/database sessions. Redis/Valkey/Mongo handle TTL natively.
+     *
+     * A backend failure is logged (never silent) but does not throw under the
+     * default policy (re-raises under TINA4_SESSION_STRICT=true).
+     */
+    gc(): void;
+    /**
+     * Persist session data to the backend.
+     *
+     * Returns true on a successful persist, false if the backend was unreachable
+     * (logged). The dirty flag is cleared only on success so a later save()
+     * retries once the backend recovers. A nothing-to-persist call returns true.
+     */
+    save(): boolean;
+}
+/**
+ * Is the client's scheme HTTPS? Proxy-aware.
+ *
+ * TLS is normally terminated at a proxy (nginx, HAProxy, ALB, Cloudflare, most
+ * container deploys) which then forwards plain HTTP to Node — so the native
+ * socket is NOT encrypted on exactly the deployments that ARE https, and it
+ * cannot be the only signal. `x-forwarded-proto` carries the scheme the client
+ * actually used; a chain of proxies appends each hop ("https, http") and the
+ * FIRST is the client-facing one, which is the scheme the browser used.
+ *
+ * Parity with PHP `Request::isSecureScheme` (tina4-php#175). Spoofable when the
+ * app is directly reachable, but the failure mode is self-limiting: a spoofed
+ * `https` only makes the cookie MORE restrictive, and `request.ts` already
+ * trusts the same header for URL construction — honouring it here is consistent.
+ *
+ * @param forwardedProto Raw `x-forwarded-proto` value (or a resolved scheme like
+ *                       "https"/"http"); "" / undefined means "absent".
+ * @param socketEncrypted True when Node terminated TLS itself (direct https, no
+ *                        proxy) — the native fallback when no forwarded header.
+ */
+export declare function isSecureScheme(forwardedProto?: string, socketEncrypted?: boolean): boolean;
+/**
+ * Resolve the session cookie name — the single source of truth shared by the
+ * WRITE side (`buildSessionCookie` / `Session.cookieHeader`) and the READ side
+ * (the auto-session cookie parse in `server.ts`), so a cookie written under a
+ * renamed name is read back on the next request.
+ *
+ *   TINA4_SESSION_NAME   Cookie name (default: "tina4_session")
+ *
+ * Keeping this in one place means the default can never drift between the two
+ * sides: an operator who sets `TINA4_SESSION_NAME` renames the cookie on both
+ * the emit and the parse paths at once. Parity with Python
+ * `session.session_cookie_name()`.
+ */
+export declare function sessionCookieName(): string;
+/**
+ * Build the `Set-Cookie` header value for a Tina4 session. Centralised so
+ * the auto-cookie path in server.ts and `Session.cookieHeader()` agree on
+ * which env vars are honoured and what the defaults are.
+ *
+ * Env vars (Python parity):
+ *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+ *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+ *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+ *   TINA4_SESSION_SECURE    — emit Secure (default: false; SameSite=None forces it on)
+ *
+ * `Secure` is emitted when ANY of: TINA4_SESSION_SECURE is truthy; SameSite is
+ * `None` (browsers reject a None cookie without Secure); OR the request scheme
+ * is https, detected proxy-aware from `forwardedProto` / `socketEncrypted`. The
+ * auto-cookie path in server.ts threads the request's scheme in so an HTTPS
+ * deploy behind a TLS-terminating proxy ships Secure without the operator
+ * having to know about TINA4_SESSION_SECURE (nodejs#34). Plain HTTP with no
+ * proxy header and no native TLS stays NOT Secure — an eager Secure would make
+ * http://localhost dev cookies undeliverable.
+ */
+export declare function buildSessionCookie(sessionId: string | null, ttl: number, cookieName?: string, forwardedProto?: string, socketEncrypted?: boolean): string;
+export {};

package/types/core/src/sessionHandlers/childError.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tina4 session handlers — turn a failed `execFileSync` child into a readable cause.
+ *
+ * The session-handler interface is synchronous but every backend client is async,
+ * so each command runs in a short-lived `node -e` child. When that child fails,
+ * `execFileSync` throws an error whose `.message` begins "Command failed:" and
+ * then embeds THE ENTIRE GENERATED SCRIPT — kilobytes of source with the real
+ * reason nowhere in it. Every handler used to throw exactly that, so an
+ * operator debugging a Redis outage got a wall of JavaScript instead of
+ * "connect ECONNREFUSED 127.0.0.1:6379".
+ *
+ * The children already write the real reason to stderr; `execFileSync` captures
+ * it on `err.stderr`. This module is the ONE place that prefers it, so the three
+ * call sites (respClient, mongoClient, redisHandler's npm path) cannot drift.
+ */
+/**
+ * Extract the most useful one-line cause from a thrown `execFileSync` error.
+ *
+ * Order of preference:
+ *  1. the child's own stderr — what it actually reported;
+ *  2. a timeout, named as such (a SIGTERM kill leaves stderr empty, so without
+ *     this the caller would see the useless generic message);
+ *  3. a non-zero exit code with no output at all;
+ *  4. the error's own message, first line only and length-capped, so the
+ *     generated script can never be dumped into a log.
+ */
+export declare function childFailureReason(err: unknown): string;
+/**
+ * Build the Error a session handler throws when its child command failed.
+ *
+ * `label` names the backend ("Redis", "Valkey", "MongoDB") so the message says
+ * which one broke; the wording is shared so all three read alike.
+ */
+export declare function childFailureError(label: string, err: unknown): Error;

package/types/core/src/sessionHandlers/databaseHandler.d.ts

@@ -0,0 +1,42 @@
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface DatabaseSessionConfig {
+    /** SQLite database file path (default: extracted from TINA4_DATABASE_URL or "data/tina4_sessions.db") */
+    dbPath?: string;
+    backend?: string;
+    path?: string;
+    ttl?: number;
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+    redisPrefix?: string;
+    redisDb?: number;
+}
+/**
+ * Database session handler using node:sqlite (synchronous SQLite).
+ *
+ * Stores session data as JSON in a `tina4_session` table.
+ * Expiry is checked on read; expired rows are cleaned up lazily.
+ */
+export declare class DatabaseSessionHandler implements SessionHandler {
+    private db;
+    private initialized;
+    constructor(config?: DatabaseSessionConfig);
+    /**
+     * Resolve the database file path from TINA4_DATABASE_URL or use the default.
+     */
+    private resolveDbPath;
+    /**
+     * Ensure the session table exists (called once on first use).
+     */
+    private ensureTable;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl: number): void;
+    destroy(sessionId: string): void;
+    gc(_maxLifetime: number): void;
+}
+export {};

package/types/core/src/sessionHandlers/mongoClient.d.ts

@@ -0,0 +1,24 @@
+export interface MongoTarget {
+    host: string;
+    port: number;
+    database: string;
+    collection: string;
+}
+/** Command args: `filter` (always), plus `data`/`last_accessed` for an update. */
+export interface MongoCommandArgs {
+    filter: Record<string, unknown>;
+    data?: unknown;
+    last_accessed?: number;
+}
+/**
+ * Run a session Mongo command synchronously and return the raw child stdout.
+ *
+ * - command "find"   -> the matched document as a JSON string, or "__EMPTY__".
+ * - command "update" -> "__OK__" (upsert of `{_id, data, last_accessed}`).
+ * - command "delete" -> "__OK__".
+ *
+ * THROWS `<label> command failed: ...` on a transport failure (server unreachable,
+ * timeout) OR a Mongo command error (`ok != 1`), so the Session boundary can
+ * log-loud + degrade (or re-throw under strict mode).
+ */
+export declare function mongoCommandSync(target: MongoTarget, command: "find" | "update" | "delete", args: MongoCommandArgs, label?: string): string;

package/types/core/src/sessionHandlers/mongoHandler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tina4 MongoDB Session Handler — MongoDB wire protocol via raw TCP, zero dependencies.
+ *
+ * Stores session data in MongoDB using the MongoDB wire protocol directly.
+ * No `mongodb` or `mongoose` npm package required.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_MONGO_HOST       (default: "127.0.0.1")
+ *   TINA4_SESSION_MONGO_PORT       (default: 27017)
+ *   TINA4_SESSION_MONGO_URI        (overrides host/port if set)
+ *   TINA4_SESSION_MONGO_USERNAME   (optional)
+ *   TINA4_SESSION_MONGO_PASSWORD   (optional)
+ *   TINA4_SESSION_MONGO_DB         (default: "tina4_sessions")
+ *   TINA4_SESSION_MONGO_COLLECTION (default: "sessions")
+ */
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface MongoSessionConfig {
+    host?: string;
+    port?: number;
+    uri?: string;
+    username?: string;
+    password?: string;
+    database?: string;
+    collection?: string;
+    backend?: string;
+    path?: string;
+    ttl?: number;
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+    redisPrefix?: string;
+    redisDb?: number;
+}
+/**
+ * MongoDB session handler using raw TCP (MongoDB wire protocol).
+ *
+ * Uses synchronous socket communication via child process — no external
+ * MongoDB client library required. Stores session data as BSON documents
+ * with TTL index support.
+ */
+export declare class MongoSessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private uri;
+    private username;
+    private password;
+    private database;
+    private collection;
+    constructor(config?: MongoSessionConfig);
+    /** Resolve the effective host/port (honours a configured mongodb:// URI). */
+    private target;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, _ttl: number): void;
+    destroy(sessionId: string): void;
+}
+export {};

package/types/core/src/sessionHandlers/redisHandler.d.ts

@@ -0,0 +1,60 @@
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface RedisNpmSessionConfig {
+    host?: string;
+    port?: number;
+    url?: string;
+    password?: string;
+    prefix?: string;
+    db?: number;
+    backend?: string;
+    path?: string;
+    ttl?: number;
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+    redisPrefix?: string;
+    redisDb?: number;
+}
+/**
+ * Redis session handler using the `redis` npm package.
+ *
+ * Falls back to raw TCP (RESP protocol) if the `redis` package is not
+ * installed, matching the approach used by the Valkey handler.
+ *
+ * Stores session data as JSON strings with Redis TTL for automatic expiry.
+ */
+export declare class RedisNpmSessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private url;
+    private password;
+    private prefix;
+    private db;
+    constructor(config?: RedisNpmSessionConfig);
+    /** Resolve a host/port for the raw-RESP path (parses TINA4_SESSION_REDIS_URL if set). */
+    private resolveHostPort;
+    /**
+     * Execute a Redis command synchronously.
+     *
+     * Prefers the official `redis` driver when it is installed (the class's reason
+     * to exist); otherwise speaks raw RESP via the shared {@link respCommandSync}
+     * transport — same correct path as the Valkey handler, no `redis` dependency.
+     *
+     * A genuine key miss yields `""`; a transport/connection FAILURE (server
+     * unreachable, rejected AUTH, timeout) THROWS so the Session boundary can
+     * distinguish "not found" (silent) from "backend failed" (log-loud + degrade).
+     */
+    private execSync;
+    /** Drive the command through the `redis` npm client in a short-lived child. */
+    private execViaNpm;
+    private key;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl: number): void;
+    destroy(sessionId: string): void;
+}
+export {};

package/types/core/src/sessionHandlers/respClient.d.ts

@@ -0,0 +1,22 @@
+export interface RespTarget {
+    host: string;
+    port: number;
+    /** AUTH password (empty/undefined = no AUTH sent). */
+    password?: string;
+    /** SELECT db index (0/undefined = no SELECT sent). */
+    db?: number;
+}
+/**
+ * Run a single RESP command synchronously against host:port and return the reply.
+ *
+ * - A genuine nil / key-miss returns `""` (callers treat "" as "no session yet").
+ * - A transport FAILURE (server unreachable, timeout, connection closed before a
+ *   reply) THROWS `<label> command failed: ...`.
+ * - A RESP error reply — including a rejected AUTH/SELECT handshake — THROWS
+ *   `<label> error: ...`. A rejected handshake is a transport failure, not a
+ *   result, so it is surfaced ahead of the command reply.
+ *
+ * Session values are JSON strings (they start with `{`), so they never collide
+ * with the `__NULL__` / `__ERR__` sentinels the child uses on stdout.
+ */
+export declare function respCommandSync(target: RespTarget, args: string[], label?: string): string;

package/types/core/src/sessionHandlers/valkeyHandler.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Tina4 Valkey Session Handler — Valkey (Redis-compatible) via raw TCP, zero dependencies.
+ *
+ * Same as the Redis handler but uses VALKEY-prefixed configuration variables.
+ * Valkey is a Redis-compatible key-value store fork.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_VALKEY_HOST     (default: "127.0.0.1")
+ *   TINA4_SESSION_VALKEY_PORT     (default: 6379)
+ *   TINA4_SESSION_VALKEY_PASSWORD (optional)
+ *   TINA4_SESSION_VALKEY_PREFIX   (default: "tina4:session:")
+ *   TINA4_SESSION_VALKEY_DB       (default: 0)
+ */
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface ValkeySessionConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    prefix?: string;
+    db?: number;
+    backend?: string;
+    path?: string;
+    ttl?: number;
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+    redisPrefix?: string;
+    redisDb?: number;
+}
+/**
+ * Valkey session handler using raw TCP (RESP protocol).
+ *
+ * Uses synchronous socket communication — no external Valkey/Redis client required.
+ * Stores session data as JSON strings with Valkey TTL for automatic expiry.
+ *
+ * Valkey uses the same RESP protocol as Redis, so this handler is functionally
+ * identical to RedisSessionHandler but with VALKEY config variable names.
+ */
+export declare class ValkeySessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private password;
+    private prefix;
+    private db;
+    constructor(config?: ValkeySessionConfig);
+    /**
+     * Execute a RESP command synchronously against the live Valkey server.
+     *
+     * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
+     * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
+     * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
+     * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
+     */
+    private execSync;
+    private key;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl: number): void;
+    destroy(sessionId: string): void;
+}
+export {};

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

@@ -0,0 +1,2 @@
+import type { Tina4Request, Tina4Response } from "./types.js";
+export declare function tryServeStatic(staticDir: string, req: Tina4Request, res: Tina4Response): boolean;

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

@@ -0,0 +1,94 @@
+/**
+ * Tina4 — The Intelligent Native Application 4ramework
+ * Copyright 2007 - current Tina4
+ * License: MIT https://opensource.org/licenses/MIT
+ *
+ * Tina4 xUnit-style Test base class.
+ *
+ * Chapter 18 of the documentation has long shown:
+ *
+ *     class UserApiTest extends Tina4Test {
+ *       async testHealth() {
+ *         const resp = await this.get("/health");
+ *         this.assertEqual(resp.status, 200);
+ *       }
+ *     }
+ *
+ * Until 3.13.0 this class did not exist — examples crashed with
+ * "ReferenceError: Tina4Test is not defined". This is the Node.js
+ * parity of the Python `tina4_python.test.Test`, PHP `Tina4\Test`,
+ * and Ruby `Tina4::Test` classes shipped at the same time.
+ *
+ * The class has a built-in runner (`Tina4Test.runAll`) so the docs'
+ * `npx tina4nodejs test` flow can discover every subclass without
+ * an external test framework. HTTP helpers (get/post/put/patch/delete)
+ * delegate to a lazy TestClient. Positional assertions match the
+ * cross-framework (actual, expected, message) shape.
+ */
+import { TestClient, type TestResponse, type RequestOptions } from "./testClient.js";
+/** Raised by Tina4Test assertion helpers when an assertion fails. */
+export declare class AssertionError extends Error {
+    constructor(message: string);
+}
+/** Result of running a Tina4Test subclass (or all subclasses). */
+export interface TestRunResults {
+    passed: number;
+    failed: number;
+    errors: number;
+    details: Array<{
+        suite: string;
+        test: string;
+        status: "passed" | "failed" | "error";
+        message?: string;
+    }>;
+}
+/**
+ * Tina4 xUnit-style test base class — class-based suites with HTTP
+ * helpers and positional assertions, zero external deps.
+ *
+ * Subclass and define `test*` methods:
+ *
+ *     class BasicTest extends Tina4Test {
+ *       async testAddition() {
+ *         this.assertEqual(2 + 2, 4, "addition works");
+ *       }
+ *       async testHttpHealth() {
+ *         const resp = await this.get("/health");
+ *         this.assertEqual(resp.status, 200);
+ *       }
+ *     }
+ *
+ *     const results = await Tina4Test.runAll();
+ *     // → { passed, failed, errors, details }
+ */
+export declare class Tina4Test {
+    private _client;
+    /** snake_case lifecycle hook — runs before each test. Override in subclasses. */
+    setUp(): Promise<void>;
+    /** snake_case lifecycle hook — runs after each test. Override in subclasses. */
+    tearDown(): Promise<void>;
+    /** The lazily-created TestClient instance shared by this suite's tests. */
+    protected get client(): TestClient;
+    get(path: string, options?: RequestOptions): Promise<TestResponse>;
+    post(path: string, options?: RequestOptions): Promise<TestResponse>;
+    put(path: string, options?: RequestOptions): Promise<TestResponse>;
+    patch(path: string, options?: RequestOptions): Promise<TestResponse>;
+    delete(path: string, options?: RequestOptions): Promise<TestResponse>;
+    assertEqual(actual: unknown, expected: unknown, message?: string): void;
+    assertNotEqual(actual: unknown, expected: unknown, message?: string): void;
+    assertTrue(value: unknown, message?: string): void;
+    assertFalse(value: unknown, message?: string): void;
+    assertNull(value: unknown, message?: string): void;
+    assertNotNull(value: unknown, message?: string): void;
+    assertRaises(expectedClass: new (...args: never[]) => Error, fn: () => unknown | Promise<unknown>, message?: string): Promise<void>;
+    /** Register a subclass for discovery. Called automatically via `extends Tina4Test`. */
+    static register(klass: typeof Tina4Test): void;
+    /** Run every `test*` method on this class. Returns counts and per-test details. */
+    static run(this: typeof Tina4Test): Promise<TestRunResults>;
+    /** Run every Tina4Test subclass discovered via auto-registration. */
+    static runAll(options?: {
+        quiet?: boolean;
+    }): Promise<TestRunResults>;
+    /** Subclasses array — read-only view used by tests. */
+    static get subclasses(): ReadonlyArray<typeof Tina4Test>;
+}