@c9up/ream 0.1.26 → 0.1.28

package/dist/testing/RequestBuilder.js

@@ -1,14 +1,51 @@
-/** Assertion failure — plain Error so tests see a clean stack trace. */
-class ExpectationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ExpectationError';
-    }
-}
+/**
+ * Fluent HTTP request builder with assertion methods (`@japa/api-client` model).
+ *
+ *   await client
+ *     .get('/api/users/42')
+ *     .withAuth(user)
+ *     .assertOk()
+ *     .assertBody({ id: 42 })
+ *
+ * The builder chains SYNCHRONOUSLY: setters and assertion methods both return
+ * `this`. Assertions are LAZY — each registers a check; the request is sent once
+ * and every check runs, in order, when the builder is awaited (it is thenable,
+ * so `await builder` resolves to the {@link ApiResponse}). A plain
+ * `await client.get('/x')` (no assertion) just sends and returns the response.
+ */
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { ApiResponse, capBody, ExpectationError, partialMatch, STATUS_ASSERTIONS, } from './ApiResponse.js';
+// Re-export the shared response types + matchers so `@c9up/ream/testing`
+// consumers keep importing them from here (back-compat).
+export { ApiResponse, deepEqual, partialMatch, } from './ApiResponse.js';
 /** Cookie the signed CSRF token is issued in (blackhole default: `XSRF-TOKEN`). */
 const CSRF_COOKIE_NAME = 'XSRF-TOKEN';
 /** Header the client echoes the token back in (Axios/Angular default). */
 const CSRF_HEADER_NAME = 'x-xsrf-token';
+/** Content-type / accept shorthands — mirrors japa/api-client's `.type()`/`.accept()`. */
+const TYPE_SHORTHANDS = {
+    json: 'application/json',
+    form: 'application/x-www-form-urlencoded',
+    urlencoded: 'application/x-www-form-urlencoded',
+    text: 'text/plain',
+    html: 'text/html',
+    xml: 'application/xml',
+};
+/** Expand a shorthand (`'json'`) to a full MIME type, or pass a full type through. */
+function resolveMime(type) {
+    return TYPE_SHORTHANDS[type] ?? type;
+}
+/** HTTP statuses that trigger redirect-following (Japa `.redirects()`). */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Japa follows 5 redirects by default. */
+const DEFAULT_MAX_REDIRECTS = 5;
+/** Consumer-registered macros/getters (Japa `ApiRequest.macro`/`.getter`). */
+const requestMacros = new Map();
+const requestGetters = new Map();
+/** Consumer-registered request body serializers (Japa `ApiRequest.addSerializer`), by name. */
+const requestSerializers = new Map();
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the merged interface (StatusAssertions) types the status-shortcut asserts attached from STATUS_ASSERTIONS at load — the same generated-method pattern as EonSchema/Macroable (AdonisJS parity); every member is implemented, so the merge is safe.
 export class RequestBuilder {
     #sender;
     #method;
@@ -20,12 +57,19 @@ export class RequestBuilder {
     #query = new URLSearchParams();
     #authStrategy;
     #pendingAuth = null;
+    #timeoutMs;
+    #maxRedirects = DEFAULT_MAX_REDIRECTS;
     #sent = null;
+    // Lazy assertions (japa model): each `assert*`/`expect*` registers a check and
+    // returns `this` synchronously; the checks run in order when the builder is
+    // awaited (`then`) — after the single send.
+    #checks = [];
     constructor(sender, method, path, authStrategy = null) {
         this.#sender = sender;
         this.#method = method;
         this.#path = path;
         this.#authStrategy = authStrategy;
+        applyRequestExtensions(this);
     }
     headers(map) {
         for (const [k, v] of Object.entries(map)) {
@@ -34,7 +78,8 @@ export class RequestBuilder {
         return this;
     }
     header(name, value) {
-        this.#headers[name.toLowerCase()] = value;
+        // Japa accepts string | string[]; a list is joined into one header value.
+        this.#headers[name.toLowerCase()] = Array.isArray(value) ? value.join(', ') : value;
         return this;
     }
     json(data) {
@@ -42,6 +87,10 @@ export class RequestBuilder {
         this.#headers['content-type'] = 'application/json';
         return this;
     }
+    /** Japa `.unsafeJson()` — set a JSON body without any transform (alias of {@link json}). */
+    unsafeJson(data) {
+        return this.json(data);
+    }
     body(data, contentType) {
         this.#body = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
         if (contentType)
@@ -49,34 +98,64 @@ export class RequestBuilder {
         return this;
     }
     form(data) {
-        const pairs = Object.entries(data).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
+        // Array values repeat the key (`a=1&a=2`) — Japa parity.
+        const pairs = [];
+        for (const [k, v] of Object.entries(data)) {
+            const values = Array.isArray(v) ? v : [v];
+            for (const item of values) {
+                pairs.push(`${encodeURIComponent(k)}=${encodeURIComponent(fieldToString(item))}`);
+            }
+        }
         this.#body = Buffer.from(pairs.join('&'), 'utf8');
         this.#headers['content-type'] = 'application/x-www-form-urlencoded';
         return this;
     }
+    /** Japa `.unsafeForm()` — set a urlencoded body without transform (alias of {@link form}). */
+    unsafeForm(data) {
+        return this.form(data);
+    }
     /**
-     * Add a `multipart/form-data` text field — mirrors Adonis/japa's `.field()`.
-     * Calling `.field()` or `.file()` switches the body to multipart (use
-     * `.form()` for `application/x-www-form-urlencoded`). The boundary +
-     * `Content-Type` header are produced at send time.
+     * Add a `multipart/form-data` field — mirrors Adonis/japa's `.field()`. Accepts
+     * a string/number/boolean, a Buffer, a Blob, a Readable stream, or an array of
+     * these (repeated part). Calling `.field()`/`.fields()`/`.file()` switches the
+     * body to multipart; the boundary + `Content-Type` header are produced at send
+     * time (streams/blobs are drained to Buffers then).
      */
     field(name, value) {
-        this.#multipart.push({ kind: 'field', name, value });
+        const values = Array.isArray(value) ? value : [value];
+        for (const v of values) {
+            this.#multipart.push({
+                kind: 'field',
+                name,
+                value: isScalar(v) ? fieldToString(v) : v,
+            });
+        }
+        return this;
+    }
+    /** Add several multipart fields at once — Japa `.fields()`. */
+    fields(map) {
+        for (const [name, value] of Object.entries(map)) {
+            this.field(name, value);
+        }
         return this;
     }
     /**
      * Attach a file as a `multipart/form-data` part — mirrors Adonis/japa's
-     * `.file(field, contents, { filename, contentType })`. `contents` is a
-     * Buffer (binary) or a string (encoded as utf8). Server-side
-     * `request.file(field, …)` reads the resulting part.
+     * `.file(field, value, { filename, contentType })`. `value` is a Buffer, a
+     * Blob, a Readable stream, OR a string absolute PATH to a file on disk (read at
+     * call time, Japa parity). The filename defaults to the path basename / field
+     * name; streams/blobs are drained to Buffers at send time.
      */
-    file(field, contents, options = {}) {
+    file(field, value, options = {}) {
+        // A string is a PATH → read now; other kinds are resolved at send time.
+        const content = typeof value === 'string' ? readFileSync(value) : value;
+        const filename = options.filename ?? (typeof value === 'string' ? basename(value) : field);
         this.#multipart.push({
             kind: 'file',
             name: field,
-            filename: options.filename ?? field,
+            filename,
             contentType: options.contentType ?? 'application/octet-stream',
-            content: typeof contents === 'string' ? Buffer.from(contents, 'utf8') : contents,
+            content,
         });
         return this;
     }
@@ -105,6 +184,14 @@ export class RequestBuilder {
         }
         return this;
     }
+    /**
+     * Append query params WITHOUT any validation/normalisation — Japa
+     * `.unsafeQs({ … })`. Values are still URL-encoded so the wire stays valid, but
+     * (unlike `.qs()`) no key filtering is applied; arrays repeat the key.
+     */
+    unsafeQs(params) {
+        return this.qs(params);
+    }
     /** Pass a bearer token as the `Authorization` header — japa `.bearerToken()`. */
     bearerToken(token) {
         this.#headers.authorization = `Bearer ${token}`;
@@ -116,15 +203,65 @@ export class RequestBuilder {
         this.#headers.authorization = `Basic ${encoded}`;
         return this;
     }
+    /**
+     * Set the request `Content-Type` from a shorthand (`'json'`, `'form'`, …) or a
+     * full MIME type — mirrors japa/api-client's `.type()`.
+     */
+    type(mime) {
+        this.#headers['content-type'] = resolveMime(mime);
+        return this;
+    }
+    /**
+     * Set the `Accept` header from a shorthand (`'json'`, `'html'`, …) or a full
+     * MIME type — mirrors japa/api-client's `.accept()`.
+     */
+    accept(mime) {
+        this.#headers.accept = resolveMime(mime);
+        return this;
+    }
+    /** Per-request timeout in ms — Japa `.timeout()`. Honoured by the sender. */
+    timeout(ms) {
+        this.#timeoutMs = ms;
+        return this;
+    }
+    /**
+     * Follow up to `count` redirects before resolving — Japa `.redirects()`.
+     * Defaults to 5 (Japa default); pass `0` to disable following.
+     */
+    redirects(count) {
+        this.#maxRedirects = Math.max(0, count);
+        return this;
+    }
+    // TLS knobs — Japa parity. The test server is plain HTTP over loopback, so
+    // these are inert (there is no TLS handshake to configure); they exist so
+    // Japa-shaped code type-checks and runs unchanged. NAMED as a ream deviation.
+    /** No-op: the loopback test server has no TLS — Japa `.trustLocalhost()`. */
+    trustLocalhost(_trust = true) {
+        return this;
+    }
+    /** No-op: no TLS on the loopback test server — Japa `.ca()`. */
+    ca(_cert) {
+        return this;
+    }
+    /** No-op: no TLS on the loopback test server — Japa `.cert()`. */
+    cert(_chain) {
+        return this;
+    }
+    /** No-op: no TLS on the loopback test server — Japa `.privateKey()`. */
+    privateKey(_key) {
+        return this;
+    }
+    /** No-op: no TLS on the loopback test server — Japa `.pfx()`. */
+    pfx(_encoded) {
+        return this;
+    }
+    /** No-op: no TLS on the loopback test server — Japa `.disableTLSCerts()`. */
+    disableTLSCerts() {
+        return this;
+    }
     /**
      * Satisfy blackhole's signed double-submit CSRF check: echo the `XSRF-TOKEN`
      * cookie back in the `X-XSRF-TOKEN` header (the pair the server compares).
-     *
-     * With a `token` argument, sets both the cookie and the header — useful when
-     * you already hold a signed token. Without one, reads the token from a cookie
-     * set earlier on this request (typically extracted from a prior safe GET's
-     * `Set-Cookie`); throws if none is present so the mistake is caught at the
-     * call site instead of surfacing as a confusing 403.
      */
     withCsrf(token) {
         if (token !== undefined)
@@ -137,10 +274,13 @@ export class RequestBuilder {
         this.#headers[CSRF_HEADER_NAME] = value;
         return this;
     }
+    /** japa/api-client's spelling of {@link withCsrf}. */
+    withCsrfToken(token) {
+        return this.withCsrf(token);
+    }
     /**
      * Attach auth for a user. Uses the strategy passed to `client`'s `auth`
-     * option — Warden's session/JWT/API-key strategy decides the header/cookie
-     * shape. Without a strategy, throws at send time.
+     * option. Without a strategy, throws at send time.
      */
     withAuth(subject) {
         this.#pendingAuth = subject;
@@ -151,191 +291,107 @@ export class RequestBuilder {
         this.#pendingAuth = { id: userId };
         return this;
     }
-    /** Fire the request (once) and return the raw response. Idempotent. */
+    /** Fire the request (once) and return the rich response. Idempotent. */
     send() {
         if (this.#sent === null)
             this.#sent = this.#execute();
         return this.#sent;
     }
-    async expectStatus(code) {
-        const res = await this.send();
-        if (res.status !== code) {
-            throw new ExpectationError(`Expected status ${code}, got ${res.status}. Body: ${capBody(res.body)}`);
-        }
-        return this;
+    /**
+     * Thenable — `await client.get('/x')` sends the request and resolves to the
+     * {@link ApiResponse} (Japa/api-client parity). Assertion methods return `this`;
+     * awaiting one resolves via this `then` to the response after running the checks.
+     */
+    // biome-ignore lint/suspicious/noThenProperty: the thenable IS the public API — `await client.get('/x')` is the documented Japa/api-client ergonomic; removing `.then` breaks every await-the-builder call site.
+    then(onFulfilled, onRejected) {
+        return this.#settle().then(onFulfilled, onRejected);
     }
-    async expectHeader(name, value) {
+    /** Send once, then run every registered assertion (throws on first failure). */
+    async #settle() {
         const res = await this.send();
-        const actual = res.headers[name.toLowerCase()];
-        if (actual === undefined) {
-            throw new ExpectationError(`Expected header ${name}, not present in response headers: ${Object.keys(res.headers).join(', ')}`);
-        }
-        if (value instanceof RegExp) {
-            if (!value.test(actual)) {
-                throw new ExpectationError(`Expected header ${name} to match ${value}, got "${actual}"`);
-            }
-        }
-        else if (actual !== value) {
-            throw new ExpectationError(`Expected header ${name} = "${value}", got "${actual}"`);
-        }
+        for (const check of this.#checks)
+            check(res);
+        return res;
+    }
+    /** Register a lazy assertion; returns `this` for synchronous chaining. */
+    #assert(check) {
+        this.#checks.push(check);
         return this;
     }
-    async expectCookie(name, value) {
-        const res = await this.send();
-        const setCookie = res.headers['set-cookie'];
-        if (!setCookie) {
-            throw new ExpectationError(`Expected cookie ${name}, but no Set-Cookie header was returned`);
-        }
-        const cookies = setCookie.split(/,(?=\s*\w+=)/);
-        const match = cookies.find((c) => c.trimStart().startsWith(`${name}=`));
-        if (!match) {
-            throw new ExpectationError(`Expected cookie ${name}, not found in: ${setCookie}`);
-        }
-        if (value === undefined)
-            return this;
-        const rawVal = match.split(';')[0]?.split('=')[1] ?? '';
-        if (value instanceof RegExp) {
-            if (!value.test(rawVal)) {
-                throw new ExpectationError(`Expected cookie ${name} to match ${value}, got "${rawVal}"`);
+    // ── ream-flavoured `expect*` aliases (kept for back-compat) ───────────────
+    expectStatus(code) {
+        return this.#assert((res) => res.assertStatus(code));
+    }
+    expectHeader(name, value) {
+        return this.#assert((res) => res.assertHeader(name, value));
+    }
+    expectCookie(name, value) {
+        return this.#assert((res) => res.assertCookie(name, value));
+    }
+    expectJson(expected) {
+        // ream alias: partial JSON match with its own message (kept for back-compat;
+        // `assertBodyContains` is the Japa-named equivalent).
+        return this.#assert((res) => {
+            if (!partialMatch(res.json(), expected)) {
+                throw new ExpectationError(`JSON partial match failed.\nExpected (partial): ${JSON.stringify(expected)}\nActual: ${capBody(JSON.stringify(res.json()))}`);
             }
-        }
-        else if (rawVal !== value) {
-            throw new ExpectationError(`Expected cookie ${name} = "${value}", got "${rawVal}"`);
-        }
-        return this;
+        });
     }
-    async expectJson(expected) {
-        const res = await this.send();
-        let actual;
-        try {
-            actual = res.json();
-        }
-        catch (err) {
-            throw new ExpectationError(`Expected JSON body, got non-JSON. Body: ${capBody(res.body)} (parse error: ${err instanceof Error ? err.message : String(err)})`);
-        }
-        if (!partialMatch(actual, expected)) {
-            throw new ExpectationError(`JSON partial match failed.\nExpected (partial): ${JSON.stringify(expected)}\nActual: ${capBody(JSON.stringify(actual))}`);
-        }
-        return this;
+    // ── Japa assertions (lazy — delegate to the response) ─────────────────────
+    assertStatus(code) {
+        return this.#assert((res) => res.assertStatus(code));
     }
-    // ─── japa/api-client status shortcuts ──────────────────────
-    // Thin aliases over expectStatus() — one per common HTTP status, matching
-    // @japa/api-client's assertOk()/assertCreated()/… surface.
-    /** Assert a 200 OK response. */
-    assertOk() {
-        return this.expectStatus(200);
+    assertHeader(name, value) {
+        return this.#assert((res) => res.assertHeader(name, value));
     }
-    /** Assert a 201 Created response. */
-    assertCreated() {
-        return this.expectStatus(201);
+    assertHeaderMissing(name) {
+        return this.#assert((res) => res.assertHeaderMissing(name));
     }
-    /** Assert a 204 No Content response. */
-    assertNoContent() {
-        return this.expectStatus(204);
+    assertCookie(name, value) {
+        return this.#assert((res) => res.assertCookie(name, value));
     }
-    /** Assert a 400 Bad Request response. */
-    assertBadRequest() {
-        return this.expectStatus(400);
+    assertCookieMissing(name) {
+        return this.#assert((res) => res.assertCookieMissing(name));
     }
-    /** Assert a 401 Unauthorized response. */
-    assertUnauthorized() {
-        return this.expectStatus(401);
+    assertBody(expected) {
+        return this.#assert((res) => res.assertBody(expected));
     }
-    /** Assert a 403 Forbidden response. */
-    assertForbidden() {
-        return this.expectStatus(403);
+    assertBodyContains(subset) {
+        return this.#assert((res) => res.assertBodyContains(subset));
     }
-    /** Assert a 404 Not Found response. */
-    assertNotFound() {
-        return this.expectStatus(404);
+    assertBodyNotContains(subset) {
+        return this.#assert((res) => res.assertBodyNotContains(subset));
     }
-    /**
-     * Assert a redirect (3xx) whose `Location` resolves to `path`. Compares the
-     * pathname (query/host ignored), mirroring japa's `assertRedirectsTo`.
-     */
-    async assertRedirectsTo(path) {
-        const res = await this.send();
-        if (res.status < 300 || res.status >= 400) {
-            throw new ExpectationError(`Expected a redirect (3xx) to "${path}", got status ${res.status}.`);
-        }
-        const location = res.headers.location;
-        if (location === undefined) {
-            throw new ExpectationError(`Expected a redirect to "${path}", but the response has no Location header.`);
-        }
-        // Location may be absolute or path-only; compare pathnames either way.
-        const actual = location.startsWith('http')
-            ? new URL(location).pathname
-            : (location.split('?')[0] ?? location);
-        if (actual !== path) {
-            throw new ExpectationError(`Expected redirect to "${path}", got "${actual}".`);
-        }
-        return this;
+    assertTextIncludes(substring) {
+        return this.#assert((res) => res.assertTextIncludes(substring));
     }
-    /** Assert the JSON body contains `subset` (deep partial) — japa `assertBodyContains`. */
-    async assertBodyContains(subset) {
-        const actual = await this.#bodyJson();
-        if (!partialMatch(actual, subset)) {
-            throw new ExpectationError(`Expected body to contain subset.\nSubset: ${JSON.stringify(subset)}\nActual: ${capBody(JSON.stringify(actual))}`);
-        }
-        return this;
+    assertRedirectsTo(path) {
+        return this.#assert((res) => res.assertRedirectsTo(path));
     }
-    /** Assert the JSON body does NOT contain `subset` — japa `assertBodyNotContains`. */
-    async assertBodyNotContains(subset) {
-        const actual = await this.#bodyJson();
-        if (partialMatch(actual, subset)) {
-            throw new ExpectationError(`Expected body NOT to contain subset, but it did.\nSubset: ${JSON.stringify(subset)}\nActual: ${capBody(JSON.stringify(actual))}`);
-        }
+    // ── Request debugging (Japa `request.dump*` — dumps the REQUEST) ──────────
+    /** Print the pending request (method/path/headers/body) — Japa `request.dump()`. */
+    dump() {
+        process.stderr.write(`[helix:request.dump] ${this.#method} ${this.#path}\n` +
+            `headers: ${JSON.stringify(this.#headers, null, 2)}\n` +
+            `cookies: ${JSON.stringify(this.#cookies, null, 2)}\n` +
+            `body: ${capBody(this.#body.toString('utf8'), 2048)}\n`);
         return this;
     }
-    /**
-     * Assert a response header is present, and equals `value` when given. Unlike
-     * {@link expectHeader}, the value is optional (presence-only check).
-     */
-    async assertHeader(name, value) {
-        if (value !== undefined)
-            return this.expectHeader(name, value);
-        const res = await this.send();
-        if (res.headers[name.toLowerCase()] === undefined) {
-            throw new ExpectationError(`Expected header ${name}, not present in: ${Object.keys(res.headers).join(', ')}`);
-        }
+    /** Print only the pending request body — Japa `request.dumpBody()`. */
+    dumpBody() {
+        process.stderr.write(`[helix:request.dumpBody] ${capBody(this.#body.toString('utf8'), 2048)}\n`);
         return this;
     }
-    /** Assert a response header is absent — japa `assertHeaderMissing`. */
-    async assertHeaderMissing(name) {
-        const res = await this.send();
-        if (res.headers[name.toLowerCase()] !== undefined) {
-            throw new ExpectationError(`Expected header ${name} to be absent, but it was present.`);
-        }
+    /** Print only the pending request headers — Japa `request.dumpHeaders()`. */
+    dumpHeaders() {
+        process.stderr.write(`[helix:request.dumpHeaders] ${JSON.stringify(this.#headers, null, 2)}\n`);
         return this;
     }
-    /** Assert the response set a cookie, optionally with a given value — japa `assertCookie`. */
-    assertCookie(name, value) {
-        return this.expectCookie(name, value);
-    }
-    /** Assert the response did NOT set a cookie — japa `assertCookieMissing`. */
-    async assertCookieMissing(name) {
-        const res = await this.send();
-        const setCookie = res.headers['set-cookie'];
-        if (setCookie) {
-            const present = setCookie
-                .split(/,(?=\s*\w+=)/)
-                .some((c) => c.trimStart().startsWith(`${name}=`));
-            if (present) {
-                throw new ExpectationError(`Expected cookie ${name} to be absent, but it was set: ${setCookie}`);
-            }
-        }
+    /** Print only the pending request cookies — Japa `request.dumpCookies()`. */
+    dumpCookies() {
+        process.stderr.write(`[helix:request.dumpCookies] ${JSON.stringify(this.#cookies, null, 2)}\n`);
         return this;
     }
-    /** Send (once) and parse the body as JSON, wrapping parse errors as ExpectationError. */
-    async #bodyJson() {
-        const res = await this.send();
-        try {
-            return res.json();
-        }
-        catch (err) {
-            throw new ExpectationError(`Expected JSON body, got non-JSON. Body: ${capBody(res.body)} (parse error: ${err instanceof Error ? err.message : String(err)})`);
-        }
-    }
     async #execute() {
         // Resolve auth before sending.
         if (this.#pendingAuth !== null) {
@@ -360,7 +416,17 @@ export class RequestBuilder {
         // json()/form()/body(); encode them with a fresh boundary at send time.
         if (this.#multipart.length > 0) {
             const boundary = `----ReamRequestBuilder${crypto.randomUUID().replace(/-/g, '')}`;
-            this.#body = encodeMultipart(this.#multipart, boundary);
+            // Drain any stream/blob part to a Buffer before encoding (Japa parity).
+            const resolved = await Promise.all(this.#multipart.map(async (p) => p.kind === 'field'
+                ? { kind: 'field', name: p.name, value: await toBuffer(p.value) }
+                : {
+                    kind: 'file',
+                    name: p.name,
+                    filename: p.filename,
+                    contentType: p.contentType,
+                    content: await toBuffer(p.content),
+                }));
+            this.#body = encodeMultipart(resolved, boundary);
             this.#headers['content-type'] = `multipart/form-data; boundary=${boundary}`;
         }
         // Serialise cookies into a single `Cookie:` header.
@@ -368,35 +434,164 @@ export class RequestBuilder {
         if (cookieEntries.length > 0) {
             this.#headers.cookie = cookieEntries.map(([k, v]) => `${k}=${v}`).join('; ');
         }
-        // Merge `.qs()` params into the path, preserving any query string it
-        // already carries.
+        // Merge `.qs()` params into the path, preserving any existing query string.
         let path = this.#path;
         const qs = this.#query.toString();
         if (qs) {
             path += (path.includes('?') ? '&' : '?') + qs;
         }
-        return this.#sender(this.#method, path, {
+        let method = this.#method;
+        let body = this.#body;
+        let raw = await this.#sender(method, path, {
             headers: this.#headers,
-            body: this.#body,
+            body,
+            timeoutMs: this.#timeoutMs,
         });
+        // Follow redirects up to the configured budget — Japa `.redirects()` (5 by default).
+        const chain = [];
+        let followed = 0;
+        while (followed < this.#maxRedirects &&
+            REDIRECT_STATUSES.has(raw.status) &&
+            raw.headers.location !== undefined) {
+            const location = raw.headers.location;
+            chain.push(location);
+            followed += 1;
+            path = location.startsWith('http')
+                ? new URL(location).pathname + new URL(location).search
+                : location;
+            // 303 (and, per browser convention, 301/302) switch to GET with no body;
+            // 307/308 preserve the method and body.
+            if (raw.status === 307 || raw.status === 308) {
+                // keep method + body
+            }
+            else {
+                method = 'GET';
+                body = Buffer.alloc(0);
+                delete this.#headers['content-type'];
+            }
+            raw = await this.#sender(method, path, {
+                headers: this.#headers,
+                body,
+                timeoutMs: this.#timeoutMs,
+            });
+        }
+        return new ApiResponse(raw, { method, redirects: chain });
+    }
+    /**
+     * Serialize `data` with a registered serializer and set it as the request body
+     * — the send-side twin of {@link ApiResponse.addParser}. Register serializers
+     * via {@link RequestBuilder.addSerializer} (Japa `ApiRequest.addSerializer`).
+     */
+    serialize(name, data) {
+        const serializer = requestSerializers.get(name);
+        if (!serializer) {
+            throw new Error(`RequestBuilder: no serializer registered for "${name}" (see RequestBuilder.addSerializer).`);
+        }
+        const { body, contentType } = serializer(data);
+        this.#body = body;
+        this.#headers['content-type'] = contentType;
+        return this;
+    }
+    /**
+     * Register a shared property (Japa `ApiRequest.macro`) or lazy getter
+     * (`ApiRequest.getter`). The callback is invoked with `this` bound to the
+     * builder AND the builder as its first arg, so both Japa's
+     * `function () { return this.header('x') }` and `(req) => …` work.
+     */
+    static macro(name, value) {
+        requestMacros.set(name, value);
     }
+    static getter(name, fn) {
+        requestGetters.set(name, fn);
+    }
+    /** Register a request body serializer — Japa `ApiRequest.addSerializer`. */
+    static addSerializer(name, fn) {
+        requestSerializers.set(name, fn);
+    }
+    /** Register a response body parser — Japa `ApiRequest.addParser` (delegates to ApiResponse). */
+    static addParser(contentType, fn) {
+        ApiResponse.addParser(contentType, fn);
+    }
+}
+// Attach the lazy status-shortcut assertions from the shared map so the builder
+// and ApiResponse never disagree on the code set. Each defers to the public
+// `expectStatus` (private fields aren't reachable from prototype-added fns).
+for (const [method, code] of Object.entries(STATUS_ASSERTIONS)) {
+    Object.defineProperty(RequestBuilder.prototype, method, {
+        value() {
+            return this.expectStatus(code);
+        },
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
 }
-function capBody(s, max = 512) {
-    return s.length <= max ? s : `${s.slice(0, max)}...[truncated]`;
+/** Coerce a field value to its wire string (Buffers are handled separately). */
+function fieldToString(value) {
+    return Buffer.isBuffer(value) ? value.toString('utf8') : String(value);
+}
+/** Whether a multipart value is a scalar (string/number/boolean/Buffer), not a stream/blob. */
+function isScalar(v) {
+    return (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || Buffer.isBuffer(v));
+}
+/** Drain a multipart value (string/Buffer/Blob/Readable) to a Buffer at send time. */
+async function toBuffer(v) {
+    if (Buffer.isBuffer(v))
+        return v;
+    if (typeof v === 'string')
+        return Buffer.from(v, 'utf8');
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return Buffer.from(String(v), 'utf8');
+    // `in` narrows the Blob | Readable union without a cast: only Blob has arrayBuffer.
+    if ('arrayBuffer' in v)
+        return Buffer.from(await v.arrayBuffer());
+    // Readable / async-iterable → collect chunks.
+    const chunks = [];
+    for await (const chunk of v) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/** Apply registered request macros/getters onto a freshly built builder. */
+function applyRequestExtensions(req) {
+    for (const [name, value] of requestMacros) {
+        Object.defineProperty(req, name, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    for (const [name, fn] of requestGetters) {
+        let computed = false;
+        let cached;
+        Object.defineProperty(req, name, {
+            enumerable: true,
+            configurable: true,
+            get() {
+                if (!computed) {
+                    // `this`-bound AND passed as arg → both `function(){this.x}` and `(req)=>req.x` work.
+                    cached = fn.call(req, req);
+                    computed = true;
+                }
+                return cached;
+            },
+        });
+    }
 }
 /** Strip CR/LF and escape quotes so a name/filename can't break the headers. */
 function sanitizeHeaderParam(value) {
     return value.replace(/[\r\n]/g, '').replace(/"/g, '%22');
 }
-/** Encode multipart/form-data parts (RFC 7578) into a single body Buffer. */
+/** Encode resolved multipart/form-data parts (RFC 7578) into a single body Buffer. */
 function encodeMultipart(parts, boundary) {
     const CRLF = '\r\n';
     const chunks = [];
     for (const part of parts) {
         if (part.kind === 'field') {
+            const valueBuf = part.value;
             chunks.push(Buffer.from(`--${boundary}${CRLF}` +
-                `Content-Disposition: form-data; name="${sanitizeHeaderParam(part.name)}"${CRLF}${CRLF}` +
-                `${part.value}${CRLF}`, 'utf8'));
+                `Content-Disposition: form-data; name="${sanitizeHeaderParam(part.name)}"${CRLF}${CRLF}`, 'utf8'), valueBuf, Buffer.from(CRLF, 'utf8'));
         }
         else {
             chunks.push(Buffer.from(`--${boundary}${CRLF}` +
@@ -407,32 +602,4 @@ function encodeMultipart(parts, boundary) {
     chunks.push(Buffer.from(`--${boundary}--${CRLF}`, 'utf8'));
     return Buffer.concat(chunks);
 }
-/** Narrowing guard — a non-null, non-array object usable as a string map. */
-function isRecord(x) {
-    return typeof x === 'object' && x !== null && !Array.isArray(x);
-}
-/**
- * Partial deep-match. For objects, every key in `expected` must match in
- * `actual`. For arrays, every element in `expected` must match SOMEWHERE in
- * `actual` (order-independent). Primitives compared by strict equality.
- */
-export function partialMatch(actual, expected) {
-    if (expected === null || expected === undefined) {
-        return actual === expected;
-    }
-    if (typeof expected !== 'object')
-        return actual === expected;
-    if (Array.isArray(expected)) {
-        if (!Array.isArray(actual))
-            return false;
-        return expected.every((want) => actual.some((have) => partialMatch(have, want)));
-    }
-    if (!isRecord(actual) || !isRecord(expected))
-        return false;
-    for (const key of Object.keys(expected)) {
-        if (!partialMatch(actual[key], expected[key]))
-            return false;
-    }
-    return true;
-}
 //# sourceMappingURL=RequestBuilder.js.map