@c9up/ream 0.1.25 → 0.1.27

package/dist/testing/RequestBuilder.js

@@ -1,10 +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;
@@ -13,14 +54,22 @@ export class RequestBuilder {
     #body = Buffer.alloc(0);
     #multipart = [];
     #cookies = {};
+    #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)) {
@@ -29,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) {
@@ -37,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)
@@ -44,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;
     }
@@ -83,10 +167,120 @@ export class RequestBuilder {
         this.#cookies[name] = value;
         return this;
     }
+    /**
+     * Append query-string params — mirrors japa/api-client's `.qs()`. Values are
+     * URL-encoded; arrays repeat the key (`?tag=a&tag=b`). Merges with any query
+     * string already on the path and with earlier `.qs()` calls.
+     */
+    qs(params) {
+        for (const [key, value] of Object.entries(params)) {
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    this.#query.append(key, String(item));
+            }
+            else {
+                this.#query.append(key, String(value));
+            }
+        }
+        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}`;
+        return this;
+    }
+    /** Pass HTTP Basic credentials as the `Authorization` header — japa `.basicAuth()`. */
+    basicAuth(user, password) {
+        const encoded = Buffer.from(`${user}:${password}`, 'utf8').toString('base64');
+        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).
+     */
+    withCsrf(token) {
+        if (token !== undefined)
+            this.#cookies[CSRF_COOKIE_NAME] = token;
+        const value = this.#cookies[CSRF_COOKIE_NAME];
+        if (value === undefined) {
+            throw new Error(`RequestBuilder: withCsrf() found no '${CSRF_COOKIE_NAME}' cookie. Set it first via ` +
+                `.cookie('${CSRF_COOKIE_NAME}', token) (extracted from a prior safe GET) or pass the token: withCsrf(token).`);
+        }
+        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;
@@ -97,71 +291,105 @@ 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) {
+    /**
+     * 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);
+    }
+    /** Send once, then run every registered assertion (throws on first failure). */
+    async #settle() {
         const res = await this.send();
-        if (res.status !== code) {
-            throw new ExpectationError(`Expected status ${code}, got ${res.status}. Body: ${capBody(res.body)}`);
-        }
+        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 expectHeader(name, value) {
-        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}"`);
+    // ── 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 (actual !== value) {
-            throw new ExpectationError(`Expected header ${name} = "${value}", got "${actual}"`);
-        }
+        });
+    }
+    // ── Japa assertions (lazy — delegate to the response) ─────────────────────
+    assertStatus(code) {
+        return this.#assert((res) => res.assertStatus(code));
+    }
+    assertHeader(name, value) {
+        return this.#assert((res) => res.assertHeader(name, value));
+    }
+    assertHeaderMissing(name) {
+        return this.#assert((res) => res.assertHeaderMissing(name));
+    }
+    assertCookie(name, value) {
+        return this.#assert((res) => res.assertCookie(name, value));
+    }
+    assertCookieMissing(name) {
+        return this.#assert((res) => res.assertCookieMissing(name));
+    }
+    assertBody(expected) {
+        return this.#assert((res) => res.assertBody(expected));
+    }
+    assertBodyContains(subset) {
+        return this.#assert((res) => res.assertBodyContains(subset));
+    }
+    assertBodyNotContains(subset) {
+        return this.#assert((res) => res.assertBodyNotContains(subset));
+    }
+    assertTextIncludes(substring) {
+        return this.#assert((res) => res.assertTextIncludes(substring));
+    }
+    assertRedirectsTo(path) {
+        return this.#assert((res) => res.assertRedirectsTo(path));
+    }
+    // ── 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;
     }
-    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}"`);
-            }
-        }
-        else if (rawVal !== value) {
-            throw new ExpectationError(`Expected cookie ${name} = "${value}", got "${rawVal}"`);
-        }
+    /** 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;
     }
-    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))}`);
-        }
+    /** 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;
+    }
+    /** 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;
     }
     async #execute() {
@@ -188,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.
@@ -196,28 +434,164 @@ export class RequestBuilder {
         if (cookieEntries.length > 0) {
             this.#headers.cookie = cookieEntries.map(([k, v]) => `${k}=${v}`).join('; ');
         }
-        return this.#sender(this.#method, this.#path, {
+        // 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;
+        }
+        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}` +
@@ -228,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