tina4-nodejs 3.13.68 → 3.13.70

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);
+            }
+        }
     }
 }