tina4-nodejs 3.13.68 → 3.13.69

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.68)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.69)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.68 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.69 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -877,7 +877,7 @@ frond.unsandbox();
 
 Zero-dep HTTP client over `node:http` / `node:https`. Used by integrations, queue producers, health checks, and tests.
 
-**Retry/backoff (opt-in, default off):** pass `maxRetries` (default `0`) and `retryBackoff` (default `0.5`s base, exponential) in the options bag — `new Api(url, { bearerToken, maxRetries: 3, retryBackoff: 0.5 })`. Retries a transport error (`http_code` null) or a retryable status (429/500/502/503/504); 4xx is never retried (a retried non-idempotent request may be re-sent, so retries are opt-in). Node's `node:http`/`node:https` doesn't auto-follow redirects, so there's no cross-host Authorization-leak surface (the redirect auth-strip is Python-only).
+**Retry/backoff (opt-in, default off):** pass `maxRetries` (default `0`) and `retryBackoff` (default `0.5`s base, exponential) in the options bag — `new Api(url, { bearerToken, maxRetries: 3, retryBackoff: 0.5 })`. Retries a transport error (`http_code` null) or a retryable status (429/500/502/503/504); 4xx is never retried (a retried non-idempotent request may be re-sent, so retries are opt-in).
 
 ```typescript
 import { Api } from "@tina4/core";
@@ -902,6 +902,34 @@ await api.sendRequest("OPTIONS", "/users");
 
 `error` is non-null on transport failure or timeout; `http_code` is `null` if the request never reached the server.
 
+**Multipart upload, streaming download, transport seam, cookie jar, redirects (v3.13.69, Python master parity).** All zero-dep, all opt-in and non-breaking:
+
+```typescript
+// Multipart upload — from disk OR in-memory bytes (no temp file needed).
+// Boundary is "----Tina4Boundary" + 32 hex; part Content-Type is guessed from
+// the filename (fallback application/octet-stream). A missing file / no source
+// returns a clean error result ({ http_code: null, error: ... }) — never throws.
+await api.upload("/avatars", { filePath: "/tmp/me.png", extraFields: { user_id: "42" } });
+await api.upload("/avatars", { fileBytes: buf, filename: "me.png", fieldName: "file" });
+
+// Streaming download — writes the body to disk in 64KB chunks (never buffered
+// whole). Returns { http_code, headers, error, path } (NO body field); path is
+// null and no file is written on any error.
+const dl = await api.download("/report.pdf", "/tmp/report.pdf", { q: "2026" });
+
+// Transport seam — an injectable async/sync callable
+// (method, url, headers, body, timeout) => { http_code, body, headers, error }
+// that REPLACES the node:http/https call. For APPLICATION-developer unit tests
+// only — Tina4's own suite never injects a fake (no-mock rule).
+new Api(url, { transport: async (method, u, headers, body, timeout) => ({ http_code: 200, body: {}, headers: {}, error: null }) });
+
+// Cookie jar — opt-in, in-memory, per-client. Parses Set-Cookie (leading
+// name=value, last write wins) and replays the accumulated Cookie header.
+new Api(url, { cookies: true });
+```
+
+**Redirect following (all verbs + download):** unlike bare `node:http`/`node:https`, the client now follows 3xx redirects (bounded to 10 hops). 301/302/303 on a body-bearing method become GET (body dropped, matching urllib); 307/308 preserve method + body. **Security:** the `Authorization` AND `Cookie` headers are STRIPPED when the redirect target is a different origin (scheme/host/port), so a bearer token or session cookie never leaks to a host you didn't authenticate to; same-origin redirects keep them. Full parity with Python master.
+
 ## Module: Queue (`packages/core/src/queue.ts`)
 
 Pluggable job queue (file/RabbitMQ/Kafka/MongoDB backends). The same fluent API works against any backend — pick via env vars.
@@ -1210,7 +1238,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **45 built-in features**, zero third-party dependencies
-- **3,752 tests** passing across all modules
+- **5,332 tests** passing across all modules
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.68",
+  "version": "3.13.69",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/core/src/api.ts

@@ -6,10 +6,20 @@
  *     const api = new Api("https://api.example.com");
  *     const result = await api.get("/users");
  *     const result = await api.post("/users", { name: "Alice" });
+ *
+ * Multipart upload (from disk or in-memory bytes), streaming download,
+ * an injectable transport seam (for USERS to unit-test their own code),
+ * an opt-in per-client cookie jar, and redirect following with a
+ * cross-origin Authorization/Cookie strip are all built on the same
+ * zero-dependency node:http / node:https core.
  */
 import http from "node:http";
 import https from "node:https";
 import { URL } from "node:url";
+import { randomBytes } from "node:crypto";
+import { promises as fsp, createWriteStream } from "node:fs";
+import { basename } from "node:path";
+import { pipeline } from "node:stream/promises";
 
 export interface ApiResult {
     http_code: number | null;
@@ -18,6 +28,61 @@ export interface ApiResult {
     error: string | null;
 }
 
+/**
+ * Result of {@link Api.download}. There is no `body` field — the response
+ * body went to disk. `path` is the destination on success and `null` on any
+ * error (missing dest, HTTP error status, transport failure); the file is not
+ * written on error. Keeps `http_code` (snake_case) for parity with
+ * {@link ApiResult} and the Python/PHP/Ruby `download` return.
+ */
+export interface DownloadResult {
+    http_code: number | null;
+    headers: Record<string, string>;
+    error: string | null;
+    path: string | null;
+}
+
+/**
+ * An injectable transport seam (constructor option `transport`). When supplied
+ * it fully REPLACES the node:http/https network call. Called as
+ * `(method, url, headers, body, timeout)` and must return the same result
+ * shape every verb returns (`{ http_code, body, headers, error }`); may be sync
+ * or async.
+ *
+ * NOTE: Tina4's own test suite must NEVER inject a fake/canned transport — the
+ * no-mock rule stands, so framework tests always exercise the real network path
+ * against a real local server. This seam exists purely so *application*
+ * developers can unit-test code that calls an `Api` instance without a live
+ * server.
+ */
+export type ApiTransport = (
+    method: string,
+    url: string,
+    headers: Record<string, string>,
+    body: Buffer | null,
+    timeout: number,
+) => ApiResult | Promise<ApiResult>;
+
+/**
+ * Options for {@link Api.upload}. Supply the file EITHER as `filePath` (a file
+ * on disk) OR as `fileBytes` + `filename` (an in-memory payload) — a caller
+ * never needs a temp file.
+ */
+export interface UploadOptions {
+    /** A file on disk. `filename` defaults to its basename. */
+    filePath?: string;
+    /** The form field the file is sent under (default `"file"`). */
+    fieldName?: string;
+    /** Additional text parts of the multipart body. */
+    extraFields?: Record<string, string>;
+    /** Extra per-call headers merged onto the request. */
+    headers?: Record<string, string>;
+    /** An in-memory payload (Buffer or string). Requires `filename` for a name. */
+    fileBytes?: Buffer | string;
+    /** Filename used in the Content-Disposition part header. */
+    filename?: string;
+}
+
 /**
  * HTTP statuses that warrant an automatic retry when `maxRetries` > 0:
  * rate-limit (429) plus the transient server-side 5xx family. 4xx client
@@ -25,6 +90,60 @@ export interface ApiResult {
  */
 const RETRY_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);
 
+/**
+ * Streaming download writes this many bytes per buffer so a multi-megabyte body
+ * never lands in memory in one piece (matches Python's 64 KB chunked read).
+ */
+const DOWNLOAD_CHUNK_SIZE = 64 * 1024;
+
+/** Bounded redirect hop count — mirrors urllib's HTTPRedirectHandler default. */
+const MAX_REDIRECTS = 10;
+
+/**
+ * Headers dropped when a redirect crosses to a different origin — a bearer
+ * token or a session cookie must never be handed to a host you didn't
+ * authenticate to.
+ */
+const STRIP_ON_CROSS_ORIGIN: ReadonlySet<string> = new Set(["authorization", "cookie"]);
+
+/**
+ * Minimal extension → MIME map for guessing a multipart part's Content-Type.
+ * Kept in-repo so the client stays zero-dependency (Node has no stdlib
+ * mimetypes). Values match Python's `mimetypes.guess_type` for these common
+ * extensions, so the multipart wire body is byte-identical across frameworks.
+ */
+const MIME_BY_EXT: Record<string, string> = {
+    txt: "text/plain",
+    html: "text/html",
+    htm: "text/html",
+    css: "text/css",
+    csv: "text/csv",
+    js: "text/javascript",
+    mjs: "text/javascript",
+    json: "application/json",
+    xml: "application/xml",
+    pdf: "application/pdf",
+    zip: "application/zip",
+    gz: "application/gzip",
+    tar: "application/x-tar",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    webp: "image/webp",
+    ico: "image/vnd.microsoft.icon",
+    bmp: "image/bmp",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/x-wav",
+    ogg: "audio/ogg",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+};
+
 /**
  * Constructor options for {@link Api}. Used as the second argument to
  * `new Api(url, { ... })` — cross-framework parity with Python
@@ -50,8 +169,112 @@ export interface ApiOptions {
     maxRetries?: number;
     /** Base backoff in seconds, doubling each attempt (default 0.5). */
     retryBackoff?: number;
+    /**
+     * Injectable transport seam (default undefined = the real network path).
+     * When supplied it REPLACES the node:http/https call. See {@link ApiTransport}.
+     * Tina4's own suite never injects it (no-mock rule) — it exists so
+     * application developers can unit-test their own code.
+     */
+    transport?: ApiTransport;
+    /**
+     * Opt-in per-client, in-memory cookie jar (default false = off, zero
+     * behaviour change). When true, `Set-Cookie` response headers are parsed and
+     * the accumulated `Cookie` header is sent on subsequent requests. Not
+     * persisted; scoped to this instance.
+     */
+    cookies?: boolean;
+}
+
+/** True when two URLs share scheme + host + (effective) port. */
+function sameOrigin(urlA: string, urlB: string): boolean {
+    try {
+        const a = new URL(urlA);
+        const b = new URL(urlB);
+        const defaultPort: Record<string, string> = { "http:": "80", "https:": "443" };
+        const portA = a.port || defaultPort[a.protocol] || "";
+        const portB = b.port || defaultPort[b.protocol] || "";
+        return a.protocol === b.protocol && a.hostname === b.hostname && portA === portB;
+    } catch {
+        return false;
+    }
+}
+
+/** Delete a header by name, case-insensitively (headers may use any casing). */
+function deleteHeaderCaseInsensitive(headers: Record<string, string>, name: string): void {
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === lower) {
+            delete headers[key];
+        }
+    }
+}
+
+/** Flatten node's IncomingHttpHeaders into a plain string map (arrays joined). */
+function flattenHeaders(headers: http.IncomingHttpHeaders): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value !== undefined) {
+            out[key] = Array.isArray(value) ? value.join(", ") : value;
+        }
+    }
+    return out;
 }
 
+/** Guess a multipart part's Content-Type from the filename extension. */
+function guessContentType(filename: string): string {
+    const dot = filename.lastIndexOf(".");
+    if (dot >= 0) {
+        const ext = filename.slice(dot + 1).toLowerCase();
+        const found = MIME_BY_EXT[ext];
+        if (found) {
+            return found;
+        }
+    }
+    return "application/octet-stream";
+}
+
+/**
+ * Assemble a `multipart/form-data` body as a Buffer.
+ *
+ * Text fields come first, then the file part, then the closing delimiter —
+ * matching the canonical Python/Ruby `build_multipart_body` layout so every
+ * framework produces a byte-identical body: `--<boundary>\r\n` delimited parts,
+ * `\r\n` line breaks, closing `--<boundary>--\r\n`.
+ */
+function buildMultipartBody(
+    boundary: string,
+    fieldName: string,
+    filename: string,
+    fileContent: Buffer,
+    contentType: string,
+    extraFields?: Record<string, string>,
+): Buffer {
+    const crlf = "\r\n";
+    const delimiter = `--${boundary}`;
+    const parts: Buffer[] = [];
+    if (extraFields) {
+        for (const [key, value] of Object.entries(extraFields)) {
+            parts.push(Buffer.from(delimiter + crlf, "utf-8"));
+            parts.push(Buffer.from(`Content-Disposition: form-data; name="${key}"` + crlf + crlf, "utf-8"));
+            parts.push(Buffer.from(String(value) + crlf, "utf-8"));
+        }
+    }
+    parts.push(Buffer.from(delimiter + crlf, "utf-8"));
+    parts.push(
+        Buffer.from(`Content-Disposition: form-data; name="${fieldName}"; filename="${filename}"` + crlf, "utf-8"),
+    );
+    parts.push(Buffer.from(`Content-Type: ${contentType}` + crlf + crlf, "utf-8"));
+    parts.push(fileContent);
+    parts.push(Buffer.from(crlf, "utf-8"));
+    parts.push(Buffer.from(delimiter + "--" + crlf, "utf-8"));
+    return Buffer.concat(parts);
+}
+
+/** Outcome of a single network exchange (after any redirects are followed). */
+type NetworkResult =
+    | { kind: "response"; res: http.IncomingMessage }
+    | { kind: "error"; error: string };
+
 export class Api {
     private baseUrl: string;
     private headers: Record<string, string>;
@@ -60,6 +283,9 @@ export class Api {
     private ignoreSsl: boolean;
     private maxRetries: number;
     private retryBackoff: number;
+    private transportFn?: ApiTransport;
+    private cookiesEnabled: boolean;
+    private cookies: Record<string, string>;
 
     /**
      * Construct an Api client.
@@ -87,6 +313,10 @@ export class Api {
      * opt-in for that reason.
      *
      *     new Api("https://api.example.com", { maxRetries: 3, retryBackoff: 0.5 });
+     *
+     * `transport` (default undefined = the real network path) is an injectable
+     * seam so USERS can unit-test their own code; `cookies` (default false)
+     * turns on a per-client, in-memory cookie jar.
      */
     constructor(
         baseUrl: string = "",
@@ -98,6 +328,10 @@ export class Api {
         // Retry defaults: off (0) so existing callers are unaffected.
         this.maxRetries = 0;
         this.retryBackoff = 0.5;
+        // Transport seam + cookie jar default to inert (zero behaviour change).
+        this.transportFn = undefined;
+        this.cookiesEnabled = false;
+        this.cookies = {};
 
         // Options-bag form — second arg is an object literal
         if (typeof authHeaderOrOptions === "object" && authHeaderOrOptions !== null) {
@@ -107,6 +341,8 @@ export class Api {
             this.ignoreSsl = (opts.ignoreSsl ?? false) || (opts.verifySsl === false);
             this.maxRetries = Math.max(0, opts.maxRetries ?? 0);
             this.retryBackoff = opts.retryBackoff ?? 0.5;
+            this.transportFn = opts.transport;
+            this.cookiesEnabled = opts.cookies ?? false;
 
             // Bearer wins over basic-auth when both are passed
             if (opts.bearerToken != null) {
@@ -209,6 +445,165 @@ export class Api {
         return this.execute(method.toUpperCase(), url, body, contentType);
     }
 
+    /**
+     * POST a `multipart/form-data` body — a file plus optional text fields.
+     *
+     * Two ways to supply the file, so a caller never needs a temp file:
+     *
+     *   - `filePath` — a file on disk. `filename` defaults to its basename.
+     *   - `fileBytes` + `filename` — an in-memory payload (Buffer or string).
+     *
+     * `fieldName` (default `"file"`) is the form field the file is sent under.
+     * `extraFields` become additional text parts. `headers` are extra per-call
+     * headers merged onto the request. The part's Content-Type is guessed from
+     * the filename (falling back to `application/octet-stream`).
+     *
+     * Returns the standard {@link ApiResult}. A missing file or no source given
+     * returns a clean error result (`http_code` null, `error` set) — it does NOT
+     * throw. Retry/backoff (if configured) applies, exactly like the verbs.
+     *
+     *     await api.upload("/avatars", { filePath: "/tmp/me.png" });
+     *     await api.upload("/avatars", { fileBytes: raw, filename: "me.png",
+     *                                    extraFields: { user_id: "42" } });
+     */
+    async upload(path: string, opts: UploadOptions = {}): Promise<ApiResult> {
+        const { filePath, fieldName = "file", extraFields, headers, fileBytes, filename } = opts;
+
+        let content: Buffer;
+        let uploadName: string;
+
+        if (fileBytes !== undefined && fileBytes !== null) {
+            content = Buffer.isBuffer(fileBytes) ? fileBytes : Buffer.from(String(fileBytes), "utf-8");
+            uploadName = filename || "upload.bin";
+        } else if (filePath) {
+            let isFile = false;
+            try {
+                isFile = (await fsp.stat(filePath)).isFile();
+            } catch {
+                isFile = false;
+            }
+            if (!isFile) {
+                return { http_code: null, body: null, headers: {}, error: `file not found: ${filePath}` };
+            }
+            try {
+                content = await fsp.readFile(filePath);
+            } catch (err) {
+                return {
+                    http_code: null,
+                    body: null,
+                    headers: {},
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+            uploadName = filename || basename(filePath);
+        } else {
+            return { http_code: null, body: null, headers: {}, error: "upload requires filePath or fileBytes" };
+        }
+
+        const partContentType = guessContentType(uploadName);
+        const boundary = "----Tina4Boundary" + randomBytes(16).toString("hex");
+        const bodyBuffer = buildMultipartBody(boundary, fieldName, uploadName, content, partContentType, extraFields);
+        const contentType = `multipart/form-data; boundary=${boundary}`;
+        return this.execute("POST", this.buildUrl(path), bodyBuffer, contentType, headers);
+    }
+
+    /**
+     * Stream a GET response body to `destPath` in chunks.
+     *
+     * The body is written to disk `DOWNLOAD_CHUNK_SIZE` bytes at a time instead
+     * of being buffered whole in memory — safe for large payloads. Redirect
+     * following, the cross-origin auth strip, the cookie jar, and the SSL flag
+     * all apply, exactly like the other verbs.
+     *
+     * Returns {@link DownloadResult} — there is no `body` field (it went to
+     * disk). `path` is `destPath` on success and `null` on any error (missing
+     * dest, HTTP error status, or a transport failure); the destination file is
+     * not written on error.
+     */
+    async download(path: string, destPath: string, params?: Record<string, string>): Promise<DownloadResult> {
+        if (!destPath) {
+            return { http_code: null, headers: {}, error: "download requires destPath", path: null };
+        }
+
+        let url = this.buildUrl(path);
+        if (params && Object.keys(params).length > 0) {
+            const qs = new URLSearchParams(params).toString();
+            url += (url.includes("?") ? "&" : "?") + qs;
+        }
+
+        const { headers, data } = this.buildRequest("GET", "application/json", undefined);
+
+        // An injected transport can't stream (it returns a buffered result), so
+        // write its body out; only the real network path streams chunk-by-chunk.
+        if (this.transportFn) {
+            const result = await this.callTransport("GET", url, headers, data);
+            const code = result.http_code;
+            if (result.error === null && code !== null && code >= 200 && code < 300) {
+                const raw = result.body;
+                let buffer: Buffer;
+                if (Buffer.isBuffer(raw)) {
+                    buffer = raw;
+                } else if (typeof raw === "string") {
+                    buffer = Buffer.from(raw, "utf-8");
+                } else {
+                    buffer = Buffer.from(JSON.stringify(raw ?? null), "utf-8");
+                }
+                try {
+                    await fsp.writeFile(destPath, buffer);
+                } catch (err) {
+                    return {
+                        http_code: code,
+                        headers: result.headers,
+                        error: err instanceof Error ? err.message : String(err),
+                        path: null,
+                    };
+                }
+                return { http_code: code, headers: result.headers, error: null, path: destPath };
+            }
+            return {
+                http_code: code,
+                headers: result.headers,
+                error: result.error ?? `download failed (HTTP ${code})`,
+                path: null,
+            };
+        }
+
+        const net = await this.performRequest("GET", url, headers, data, MAX_REDIRECTS);
+        if (net.kind === "error") {
+            return { http_code: null, headers: {}, error: net.error, path: null };
+        }
+
+        const res = net.res;
+        const code = res.statusCode ?? null;
+        const respHeaders = flattenHeaders(res.headers);
+
+        // >= 400 mirrors Python's urllib raising HTTPError — no file written.
+        if (code === null || code >= 400) {
+            res.resume(); // drain so the socket is freed
+            return {
+                http_code: code,
+                headers: respHeaders,
+                error: `download failed (HTTP ${code})`,
+                path: null,
+            };
+        }
+
+        this.storeCookies(res.headers["set-cookie"]);
+
+        const fileStream = createWriteStream(destPath, { highWaterMark: DOWNLOAD_CHUNK_SIZE });
+        try {
+            await pipeline(res, fileStream);
+        } catch (err) {
+            return {
+                http_code: code,
+                headers: respHeaders,
+                error: err instanceof Error ? err.message : String(err),
+                path: null,
+            };
+        }
+        return { http_code: code, headers: respHeaders, error: null, path: destPath };
+    }
+
     // ── Internal helpers ──────────────────────────────────────────────
 
     private buildUrl(path: string): string {
@@ -221,6 +616,59 @@ export class Api {
         return `${this.baseUrl}/${path.replace(/^\/+/, "")}`;
     }
 
+    /**
+     * Build the request headers (auth + cookie jar + extras) and serialize the
+     * body to a Buffer. Shared by every verb, upload, and download so the wire
+     * shape is identical and the transport seam sees exactly what the network
+     * path would.
+     */
+    private buildRequest(
+        method: string,
+        contentType: string,
+        body: unknown,
+        extraHeaders?: Record<string, string>,
+    ): { headers: Record<string, string>; data: Buffer | undefined } {
+        const headers: Record<string, string> = { ...this.headers };
+        if (this.authHeader) {
+            headers["Authorization"] = this.authHeader;
+        }
+
+        // Cookie jar: attach the accumulated Cookie header when enabled.
+        if (this.cookiesEnabled) {
+            const cookieHeader = this.cookieHeader();
+            if (cookieHeader) {
+                headers["Cookie"] = cookieHeader;
+            }
+        }
+
+        let data: Buffer | undefined;
+        if (body !== undefined && body !== null) {
+            if (contentType === "application/json" && typeof body === "object" && !Buffer.isBuffer(body)) {
+                data = Buffer.from(JSON.stringify(body), "utf-8");
+                headers["Content-Type"] = "application/json";
+            } else if (typeof body === "string") {
+                data = Buffer.from(body, "utf-8");
+                headers["Content-Type"] = contentType;
+            } else if (Buffer.isBuffer(body)) {
+                data = body;
+                headers["Content-Type"] = contentType;
+            } else {
+                // Fallback: stringify anything else as JSON
+                data = Buffer.from(JSON.stringify(body), "utf-8");
+                headers["Content-Type"] = "application/json";
+            }
+            if (data) {
+                headers["Content-Length"] = String(data.length);
+            }
+        }
+
+        if (extraHeaders) {
+            Object.assign(headers, extraHeaders);
+        }
+
+        return { headers, data };
+    }
+
     /**
      * Execute the request with opt-in retry/backoff.
      *
@@ -235,11 +683,12 @@ export class Api {
         url: string,
         body?: unknown,
         contentType: string = "application/json",
+        extraHeaders?: Record<string, string>,
     ): Promise<ApiResult> {
         const attempts = this.maxRetries + 1;
         let result: ApiResult = { http_code: null, body: null, headers: {}, error: null };
         for (let attempt = 0; attempt < attempts; attempt++) {
-            result = await this.attempt(method, url, body, contentType);
+            result = await this.attempt(method, url, body, contentType, extraHeaders);
             const code = result.http_code;
             const retryable = code === null || RETRY_STATUSES.has(code);
             if (!retryable || attempt === attempts - 1) {
@@ -252,122 +701,237 @@ export class Api {
     }
 
     /** A single HTTP attempt — returns the standardized result. */
-    private attempt(
+    private async attempt(
         method: string,
         url: string,
         body?: unknown,
         contentType: string = "application/json",
+        extraHeaders?: Record<string, string>,
     ): Promise<ApiResult> {
-        return new Promise<ApiResult>((resolve) => {
+        const { headers, data } = this.buildRequest(method, contentType, body, extraHeaders);
+
+        // A user-injected transport fully replaces the network call.
+        if (this.transportFn) {
+            return this.callTransport(method, url, headers, data);
+        }
+
+        const net = await this.performRequest(method, url, headers, data, MAX_REDIRECTS);
+        if (net.kind === "error") {
+            return { http_code: null, body: null, headers: {}, error: net.error };
+        }
+        return this.readResponse(net.res);
+    }
+
+    /**
+     * Invoke a user-injected transport and normalize its result. The transport
+     * is called with `(method, url, headers, body, timeout)` and its returned
+     * `Set-Cookie` headers (if any) feed the cookie jar.
+     */
+    private async callTransport(
+        method: string,
+        url: string,
+        headers: Record<string, string>,
+        data: Buffer | undefined,
+    ): Promise<ApiResult> {
+        let normalized: ApiResult;
+        try {
+            const result = await this.transportFn!(method, url, headers, data ?? null, this.timeout);
+            normalized = {
+                http_code: result?.http_code ?? null,
+                body: result?.body ?? null,
+                headers: result?.headers ?? {},
+                error: result?.error ?? null,
+            };
+        } catch (err) {
+            return { http_code: null, body: null, headers: {}, error: err instanceof Error ? err.message : String(err) };
+        }
+        this.storeCookiesFromRecord(normalized.headers);
+        return normalized;
+    }
+
+    /**
+     * Perform the network request, following up to `redirectsLeft` redirects.
+     *
+     * node:http/https `request` does NOT auto-follow redirects. On a 3xx with a
+     * Location, this drains the intermediate response and re-issues to the new
+     * URL: 301/302/303 on a non-GET/HEAD become GET (body dropped, urllib
+     * behaviour); 307/308 preserve method + body. When the redirect target is a
+     * DIFFERENT origin, the Authorization and Cookie headers are stripped so a
+     * bearer token / session cookie never leaks to a host you didn't
+     * authenticate to.
+     */
+    private performRequest(
+        method: string,
+        url: string,
+        headers: Record<string, string>,
+        data: Buffer | undefined,
+        redirectsLeft: number,
+    ): Promise<NetworkResult> {
+        return new Promise<NetworkResult>((resolve) => {
+            let parsed: URL;
             try {
-                const parsed = new URL(url);
-                const isHttps = parsed.protocol === "https:";
-                const transport = isHttps ? https : http;
-
-                // Build headers
-                const reqHeaders: Record<string, string> = { ...this.headers };
-                if (this.authHeader) {
-                    reqHeaders["Authorization"] = this.authHeader;
-                }
+                parsed = new URL(url);
+            } catch (err) {
+                resolve({ kind: "error", error: err instanceof Error ? err.message : String(err) });
+                return;
+            }
+
+            const isHttps = parsed.protocol === "https:";
+            const protocolModule = isHttps ? https : http;
+
+            const options: http.RequestOptions = {
+                hostname: parsed.hostname,
+                port: parsed.port || (isHttps ? 443 : 80),
+                path: parsed.pathname + parsed.search,
+                method,
+                headers,
+                timeout: this.timeout * 1000,
+            };
+
+            if (isHttps && this.ignoreSsl) {
+                (options as https.RequestOptions).rejectUnauthorized = false;
+            }
+
+            const req = protocolModule.request(options, (res) => {
+                const status = res.statusCode ?? 0;
+                const location = res.headers.location;
 
-                // Serialize body
-                let data: Buffer | undefined;
-                if (body !== undefined && body !== null) {
-                    if (contentType === "application/json" && typeof body === "object") {
-                        data = Buffer.from(JSON.stringify(body), "utf-8");
-                        reqHeaders["Content-Type"] = "application/json";
-                    } else if (typeof body === "string") {
-                        data = Buffer.from(body, "utf-8");
-                        reqHeaders["Content-Type"] = contentType;
-                    } else if (Buffer.isBuffer(body)) {
-                        data = body;
-                        reqHeaders["Content-Type"] = contentType;
-                    } else {
-                        // Fallback: stringify anything else as JSON
-                        data = Buffer.from(JSON.stringify(body), "utf-8");
-                        reqHeaders["Content-Type"] = "application/json";
+                if (status >= 300 && status < 400 && location && redirectsLeft > 0) {
+                    res.resume(); // drain the redirect body, free the socket
+
+                    let nextUrl: string;
+                    try {
+                        nextUrl = new URL(location, url).toString();
+                    } catch {
+                        resolve({ kind: "response", res });
+                        return;
                     }
-                    if (data) {
-                        reqHeaders["Content-Length"] = String(data.length);
+
+                    const crossOrigin = !sameOrigin(url, nextUrl);
+                    let nextMethod = method;
+                    let nextData = data;
+                    const nextHeaders: Record<string, string> = { ...headers };
+
+                    // 301/302/303 on a body-bearing method → GET, drop the body
+                    // (matches urllib's HTTPRedirectHandler); 307/308 preserve.
+                    if (
+                        (status === 301 || status === 302 || status === 303) &&
+                        method !== "GET" &&
+                        method !== "HEAD"
+                    ) {
+                        nextMethod = "GET";
+                        nextData = undefined;
+                        deleteHeaderCaseInsensitive(nextHeaders, "content-type");
+                        deleteHeaderCaseInsensitive(nextHeaders, "content-length");
                     }
-                }
 
-                const options: http.RequestOptions = {
-                    hostname: parsed.hostname,
-                    port: parsed.port || (isHttps ? 443 : 80),
-                    path: parsed.pathname + parsed.search,
-                    method,
-                    headers: reqHeaders,
-                    timeout: this.timeout * 1000,
-                };
+                    if (crossOrigin) {
+                        for (const name of STRIP_ON_CROSS_ORIGIN) {
+                            deleteHeaderCaseInsensitive(nextHeaders, name);
+                        }
+                    }
 
-                if (isHttps && this.ignoreSsl) {
-                    (options as https.RequestOptions).rejectUnauthorized = false;
+                    this.performRequest(nextMethod, nextUrl, nextHeaders, nextData, redirectsLeft - 1).then(resolve);
+                    return;
                 }
 
-                const req = transport.request(options, (res) => {
-                    const chunks: Buffer[] = [];
+                resolve({ kind: "response", res });
+            });
 
-                    res.on("data", (chunk: Buffer) => {
-                        chunks.push(chunk);
-                    });
+            req.on("timeout", () => {
+                req.destroy();
+                resolve({ kind: "error", error: `Request timed out after ${this.timeout}s` });
+            });
 
-                    res.on("end", () => {
-                        const raw = Buffer.concat(chunks).toString("utf-8");
-                        const respHeaders: Record<string, string> = {};
-                        for (const [key, val] of Object.entries(res.headers)) {
-                            if (val !== undefined) {
-                                respHeaders[key] = Array.isArray(val) ? val.join(", ") : val;
-                            }
-                        }
+            req.on("error", (err) => {
+                resolve({ kind: "error", error: err.message });
+            });
 
-                        let parsed: unknown;
-                        try {
-                            parsed = JSON.parse(raw);
-                        } catch {
-                            parsed = raw;
-                        }
+            if (data) {
+                req.write(data);
+            }
+            req.end();
+        });
+    }
 
-                        resolve({
-                            http_code: res.statusCode ?? null,
-                            body: parsed,
-                            headers: respHeaders,
-                            error: null,
-                        });
-                    });
-                });
+    /** Buffer a response body, parse JSON if possible, and store cookies. */
+    private readResponse(res: http.IncomingMessage): Promise<ApiResult> {
+        return new Promise<ApiResult>((resolve) => {
+            const chunks: Buffer[] = [];
+
+            res.on("data", (chunk: Buffer) => {
+                chunks.push(chunk);
+            });
+
+            res.on("end", () => {
+                const raw = Buffer.concat(chunks).toString("utf-8");
+                const respHeaders = flattenHeaders(res.headers);
+                this.storeCookies(res.headers["set-cookie"]);
+
+                let parsed: unknown;
+                try {
+                    parsed = JSON.parse(raw);
+                } catch {
+                    parsed = raw;
+                }
 
-                req.on("timeout", () => {
-                    req.destroy();
-                    resolve({
-                        http_code: null,
-                        body: null,
-                        headers: {},
-                        error: `Request timed out after ${this.timeout}s`,
-                    });
+                resolve({
+                    http_code: res.statusCode ?? null,
+                    body: parsed,
+                    headers: respHeaders,
+                    error: null,
                 });
+            });
 
-                req.on("error", (err) => {
-                    resolve({
-                        http_code: null,
-                        body: null,
-                        headers: {},
-                        error: err.message,
-                    });
-                });
+            res.on("error", (err) => {
+                resolve({ http_code: null, body: null, headers: {}, error: err.message });
+            });
+        });
+    }
 
-                if (data) {
-                    req.write(data);
+    // ── cookie jar (opt-in, in-memory, per-client) ─────────────────────────
+
+    /** The accumulated `Cookie` request header, or null when the jar is empty. */
+    private cookieHeader(): string | null {
+        const names = Object.keys(this.cookies);
+        if (names.length === 0) {
+            return null;
+        }
+        return names.map((name) => `${name}=${this.cookies[name]}`).join("; ");
+    }
+
+    /**
+     * Parse `Set-Cookie` response headers into the jar (when enabled). Only the
+     * leading `name=value` pair of each is kept (Path/HttpOnly/Expires ignored);
+     * a later value for the same name overwrites an earlier one.
+     */
+    private storeCookies(setCookie: string | string[] | undefined): void {
+        if (!this.cookiesEnabled || !setCookie) {
+            return;
+        }
+        const values = Array.isArray(setCookie) ? setCookie : [setCookie];
+        for (const raw of values) {
+            const firstPair = raw.split(";", 1)[0].trim();
+            const eq = firstPair.indexOf("=");
+            if (eq > 0) {
+                const name = firstPair.slice(0, eq).trim();
+                const value = firstPair.slice(eq + 1).trim();
+                if (name) {
+                    this.cookies[name] = value;
                 }
-                req.end();
-            } catch (err) {
-                resolve({
-                    http_code: null,
-                    body: null,
-                    headers: {},
-                    error: err instanceof Error ? err.message : String(err),
-                });
             }
-        });
+        }
+    }
+
+    /** Store cookies from a plain header record (the transport seam path). */
+    private storeCookiesFromRecord(headers: Record<string, string>): void {
+        if (!this.cookiesEnabled) {
+            return;
+        }
+        for (const [key, value] of Object.entries(headers)) {
+            if (key.toLowerCase() === "set-cookie" && value) {
+                this.storeCookies(value);
+            }
+        }
     }
 }

package/packages/core/src/index.ts

@@ -74,7 +74,7 @@ export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from
 export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api } from "./api.js";
-export type { ApiResult } from "./api.js";
+export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions } from "./api.js";
 export { Context, defaultContext, existingContext, fts5Supported, _sharedContexts } from "./context/index.js";
 export type { SearchHit } from "./context/index.js";
 export { Events } from "./events.js";