@zlink-systems/http-client 0.10.0

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+import { HttpClientRuntime } from './runtime/runtime';
+import { ZLinkHttpRequestBuilder } from './request-builder';
+import type { ZLinkHttpExecutionScheduler } from './types';
+/**
+ * ZLink-style fluent HTTP client. Wraps undici behind a builder so transport types never leak into
+ * application code. A general HTTP client; the typed-JSON path (`body(dto)` / `async<T>()`) is a
+ * convenience layer on top. Mirrors the C++ `zlink::http_client::client_t`.
+ */
+export declare class ZLinkHttpClient {
+    private readonly runtimeInstance;
+    readonly executionScheduler?: ZLinkHttpExecutionScheduler | undefined;
+    constructor(runtimeInstance: HttpClientRuntime, executionScheduler?: ZLinkHttpExecutionScheduler | undefined);
+    /** @internal */
+    get runtime(): HttpClientRuntime;
+    static create(baseUrl?: string): ZLinkHttpClientBuilder;
+    get(path: string): ZLinkHttpRequestBuilder;
+    post(path: string): ZLinkHttpRequestBuilder;
+    put(path: string): ZLinkHttpRequestBuilder;
+    delete(path: string): ZLinkHttpRequestBuilder;
+    patch(path: string): ZLinkHttpRequestBuilder;
+    head(path: string): ZLinkHttpRequestBuilder;
+    options(path: string): ZLinkHttpRequestBuilder;
+    /** Releases the underlying dispatcher (connection pool). */
+    close(): Promise<void>;
+}
+/** Fluent builder for {@link ZLinkHttpClient}. Mirrors the C++ `client_builder_t`. */
+export declare class ZLinkHttpClientBuilder {
+    private baseUrlValue;
+    private timeoutMsValue;
+    private maxResponseBodySizeValue;
+    private readonly headersValue;
+    private trustCertificateFileValue;
+    private clientCertificateValue;
+    private followRedirectsValue;
+    private retryAttemptsValue;
+    private cookiesValue;
+    private proxyValue;
+    private proxyAuthorizationValue;
+    private compressionValue;
+    private executionSchedulerValue;
+    baseUrl(value: string): this;
+    timeout(milliseconds: number): this;
+    defaultHeader(name: string, value: string): this;
+    basicAuth(user: string, password: string): this;
+    bearerToken(token: string): this;
+    maxResponseBodySize(bytes: number): this;
+    trustCertificateFile(path: string): this;
+    clientCertificateFile(certificatePath: string, keyPath: string): this;
+    followRedirects(maxRedirects?: number): this;
+    retry(attempts: number): this;
+    cookies(): this;
+    proxy(url: string): this;
+    proxyBasicAuth(user: string, password: string): this;
+    compression(): this;
+    /** Supplies the framework turn scheduler used by server-side terminators. */
+    executionScheduler(scheduler: ZLinkHttpExecutionScheduler): this;
+    /** @internal Captures a turn for one-shot requests before the client is built. */
+    captureExecutionTurn(): import("./types").ZLinkHttpExecutionTurn | undefined;
+    build(): ZLinkHttpClient;
+    get(path: string): ZLinkHttpRequestBuilder;
+    post(path: string): ZLinkHttpRequestBuilder;
+    put(path: string): ZLinkHttpRequestBuilder;
+    delete(path: string): ZLinkHttpRequestBuilder;
+    patch(path: string): ZLinkHttpRequestBuilder;
+    head(path: string): ZLinkHttpRequestBuilder;
+    options(path: string): ZLinkHttpRequestBuilder;
+}

package/dist/client.js

@@ -0,0 +1,203 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkHttpClientBuilder = exports.ZLinkHttpClient = void 0;
+const framework_1 = require("@zlink-systems/framework");
+const runtime_1 = require("./runtime/runtime");
+const text_1 = require("./runtime/text");
+const request_builder_1 = require("./request-builder");
+/**
+ * ZLink-style fluent HTTP client. Wraps undici behind a builder so transport types never leak into
+ * application code. A general HTTP client; the typed-JSON path (`body(dto)` / `async<T>()`) is a
+ * convenience layer on top. Mirrors the C++ `zlink::http_client::client_t`.
+ */
+class ZLinkHttpClient {
+    runtimeInstance;
+    executionScheduler;
+    constructor(runtimeInstance, executionScheduler) {
+        this.runtimeInstance = runtimeInstance;
+        this.executionScheduler = executionScheduler;
+    }
+    /** @internal */
+    get runtime() {
+        return this.runtimeInstance;
+    }
+    static create(baseUrl) {
+        const builder = new ZLinkHttpClientBuilder();
+        return baseUrl === undefined ? builder : builder.baseUrl(baseUrl);
+    }
+    get(path) {
+        return (0, request_builder_1.createZLinkHttpRequestBuilder)(this, 'GET', path);
+    }
+    post(path) {
+        return (0, request_builder_1.createZLinkHttpRequestBuilder)(this, 'POST', path);
+    }
+    put(path) {
+        return (0, request_builder_1.createZLinkHttpRequestBuilder)(this, 'PUT', path);
+    }
+    delete(path) {
+        return (0, request_builder_1.createZLinkHttpRequestBuilder)(this, 'DELETE', path);
+    }
+    patch(path) {
+        return (0, request_builder_1.createZLinkHttpRequestBuilder)(this, 'PATCH', path);
+    }
+    head(path) {
+        return (0, request_builder_1.createZLinkHttpRequestBuilder)(this, 'HEAD', path);
+    }
+    options(path) {
+        return (0, request_builder_1.createZLinkHttpRequestBuilder)(this, 'OPTIONS', path);
+    }
+    /** Releases the underlying dispatcher (connection pool). */
+    async close() {
+        await this.runtimeInstance.close();
+    }
+}
+exports.ZLinkHttpClient = ZLinkHttpClient;
+/** Fluent builder for {@link ZLinkHttpClient}. Mirrors the C++ `client_builder_t`. */
+class ZLinkHttpClientBuilder {
+    baseUrlValue = '';
+    timeoutMsValue = 3000;
+    maxResponseBodySizeValue = 16 * 1024 * 1024;
+    headersValue = {};
+    trustCertificateFileValue;
+    clientCertificateValue;
+    followRedirectsValue = 0;
+    retryAttemptsValue = 0;
+    cookiesValue = false;
+    proxyValue;
+    proxyAuthorizationValue;
+    compressionValue = false;
+    executionSchedulerValue;
+    baseUrl(value) {
+        (0, text_1.requireNonBlank)(value, 'HTTP client base_url is required');
+        this.baseUrlValue = value;
+        return this;
+    }
+    timeout(milliseconds) {
+        (0, text_1.requirePositiveTimeout)(milliseconds);
+        this.timeoutMsValue = milliseconds;
+        return this;
+    }
+    defaultHeader(name, value) {
+        (0, text_1.requireNonBlank)(name, 'HTTP client default header name is required');
+        this.headersValue[name.toLowerCase()] = value;
+        return this;
+    }
+    basicAuth(user, password) {
+        (0, text_1.requireNonBlank)(user, 'HTTP client basic auth user is required');
+        this.headersValue['authorization'] = (0, text_1.basicAuthorization)(user, password);
+        return this;
+    }
+    bearerToken(token) {
+        (0, text_1.requireNonBlank)(token, 'HTTP client bearer token is required');
+        this.headersValue['authorization'] = `Bearer ${token}`;
+        return this;
+    }
+    maxResponseBodySize(bytes) {
+        if (!(bytes > 0)) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP client max response body size must be greater than zero');
+        }
+        this.maxResponseBodySizeValue = bytes;
+        return this;
+    }
+    trustCertificateFile(path) {
+        (0, text_1.requireNonBlank)(path, 'HTTP client trust certificate file is required');
+        this.trustCertificateFileValue = path;
+        return this;
+    }
+    clientCertificateFile(certificatePath, keyPath) {
+        (0, text_1.requireNonBlank)(certificatePath, 'HTTP client certificate file is required');
+        (0, text_1.requireNonBlank)(keyPath, 'HTTP client certificate key file is required');
+        this.clientCertificateValue = { certificatePath, keyPath };
+        return this;
+    }
+    followRedirects(maxRedirects = 5) {
+        if (!(maxRedirects > 0)) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP client follow_redirects must be greater than zero');
+        }
+        this.followRedirectsValue = maxRedirects;
+        return this;
+    }
+    retry(attempts) {
+        if (!(attempts > 0)) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP client retry attempts must be greater than zero');
+        }
+        this.retryAttemptsValue = attempts;
+        return this;
+    }
+    cookies() {
+        this.cookiesValue = true;
+        return this;
+    }
+    proxy(url) {
+        (0, text_1.requireNonBlank)(url, 'HTTP client proxy url is required');
+        if (!url.startsWith('http://')) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP client proxy url must start with http://');
+        }
+        this.proxyValue = url;
+        return this;
+    }
+    proxyBasicAuth(user, password) {
+        (0, text_1.requireNonBlank)(user, 'HTTP client proxy auth user is required');
+        this.proxyAuthorizationValue = (0, text_1.basicAuthorization)(user, password);
+        return this;
+    }
+    compression() {
+        this.compressionValue = true;
+        return this;
+    }
+    /** Supplies the framework turn scheduler used by server-side terminators. */
+    executionScheduler(scheduler) {
+        this.executionSchedulerValue = scheduler;
+        return this;
+    }
+    /** @internal Captures a turn for one-shot requests before the client is built. */
+    captureExecutionTurn() {
+        return this.executionSchedulerValue?.capture();
+    }
+    build() {
+        (0, text_1.requireNonBlank)(this.baseUrlValue, 'HTTP client base_url is required');
+        (0, text_1.requirePositiveTimeout)(this.timeoutMsValue);
+        const lower = this.baseUrlValue.toLowerCase();
+        if (!lower.startsWith('http://') && !lower.startsWith('https://')) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP client base_url must start with http:// or https://');
+        }
+        const options = {
+            baseUrl: this.baseUrlValue,
+            timeoutMs: this.timeoutMsValue,
+            maxResponseBodySize: this.maxResponseBodySizeValue,
+            headers: { ...this.headersValue },
+            ...(this.trustCertificateFileValue !== undefined ? { trustCertificateFile: this.trustCertificateFileValue } : {}),
+            ...(this.clientCertificateValue !== undefined ? { clientCertificate: this.clientCertificateValue } : {}),
+            followRedirects: this.followRedirectsValue,
+            retryAttempts: this.retryAttemptsValue,
+            cookies: this.cookiesValue,
+            ...(this.proxyValue !== undefined ? { proxy: this.proxyValue } : {}),
+            ...(this.proxyAuthorizationValue !== undefined ? { proxyAuthorization: this.proxyAuthorizationValue } : {}),
+            compression: this.compressionValue,
+        };
+        return new ZLinkHttpClient(new runtime_1.HttpClientRuntime(options), this.executionSchedulerValue);
+    }
+    get(path) {
+        return new request_builder_1.ZLinkHttpRequestBuilder(undefined, 'GET', path, this);
+    }
+    post(path) {
+        return new request_builder_1.ZLinkHttpRequestBuilder(undefined, 'POST', path, this);
+    }
+    put(path) {
+        return new request_builder_1.ZLinkHttpRequestBuilder(undefined, 'PUT', path, this);
+    }
+    delete(path) {
+        return new request_builder_1.ZLinkHttpRequestBuilder(undefined, 'DELETE', path, this);
+    }
+    patch(path) {
+        return new request_builder_1.ZLinkHttpRequestBuilder(undefined, 'PATCH', path, this);
+    }
+    head(path) {
+        return new request_builder_1.ZLinkHttpRequestBuilder(undefined, 'HEAD', path, this);
+    }
+    options(path) {
+        return new request_builder_1.ZLinkHttpRequestBuilder(undefined, 'OPTIONS', path, this);
+    }
+}
+exports.ZLinkHttpClientBuilder = ZLinkHttpClientBuilder;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ZLinkHttpClient, ZLinkHttpClientBuilder } from './client';
+export { ZLinkHttpRequestBuilder } from './request-builder';
+export type { ZLinkHttpMethod, RawHttpResponse, HttpResponse, BodyChunkProvider, DownloadSink, ZLinkHttpCallback, ZLinkHttpExecutionScheduler, ZLinkHttpExecutionTurn, } from './types';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkHttpRequestBuilder = exports.ZLinkHttpClientBuilder = exports.ZLinkHttpClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "ZLinkHttpClient", { enumerable: true, get: function () { return client_1.ZLinkHttpClient; } });
+Object.defineProperty(exports, "ZLinkHttpClientBuilder", { enumerable: true, get: function () { return client_1.ZLinkHttpClientBuilder; } });
+var request_builder_1 = require("./request-builder");
+Object.defineProperty(exports, "ZLinkHttpRequestBuilder", { enumerable: true, get: function () { return request_builder_1.ZLinkHttpRequestBuilder; } });

package/dist/request-builder.d.ts

@@ -0,0 +1,60 @@
+import type { ZLinkHttpClient, ZLinkHttpClientBuilder } from './client';
+import type { BodyChunkProvider, DownloadSink, HttpResponse, RawHttpResponse, ZLinkHttpCallback, ZLinkHttpExecutionScheduler, ZLinkHttpExecutionTurn, ZLinkHttpMethod } from './types';
+/**
+ * Fluent builder for a single request. Mirrors the C++ `request_builder_t`. Submission returns a
+ * `Promise`; the event loop is never blocked while the request is in flight.
+ */
+export declare class ZLinkHttpRequestBuilder {
+    private readonly method;
+    private readonly path;
+    private bodyValue;
+    private bodyProviderValue;
+    private readonly headersValue;
+    private timeoutMsValue;
+    private readonly queryValue;
+    private readonly formValue;
+    private readonly multipartValue;
+    private clientInstance;
+    private readonly clientFactory;
+    private readonly ownsClient;
+    protected readonly executionTurn: ZLinkHttpExecutionTurn | undefined;
+    protected readonly executionScheduler: ZLinkHttpExecutionScheduler | undefined;
+    private consumed;
+    constructor(client: ZLinkHttpClient | undefined, method: ZLinkHttpMethod, path: string, clientFactory?: ZLinkHttpClientBuilder);
+    private resolveClient;
+    private closeIfOwned;
+    header(name: string, value: string): this;
+    query(name: string, value: string): this;
+    timeout(milliseconds: number): this;
+    /** Sets a typed JSON body (1 arg) or a raw body with explicit content type (2 args). */
+    body<T>(value: T): this;
+    body(content: string, contentType: string): this;
+    /**
+     * Streams the request body chunk by chunk with chunked transfer-encoding; the provider returns
+     * `null` when the body is complete. Streamed requests are excluded from retry.
+     */
+    bodyStream(provider: BodyChunkProvider, contentType: string): this;
+    form(name: string, value: string): this;
+    multipart(name: string, value: string): this;
+    multipartFile(name: string, filename: string, content: string, contentType: string): this;
+    /** Executes the request and returns the raw response while retaining the current turn. */
+    submitRaw(): Promise<RawHttpResponse>;
+    /**
+     * Streams the response body to `sink` chunk by chunk instead of buffering it; the returned
+     * response carries status and headers with an empty body (no decompression of chunks).
+     */
+    download(sink: DownloadSink): Promise<RawHttpResponse>;
+    async<T>(): Promise<HttpResponse<T>>;
+    async<T>(callback: ZLinkHttpCallback<T>): void;
+    protected executeTyped<T>(): Promise<HttpResponse<T>>;
+    /** Returns only the decoded body for client-side scenarios that do not need the HTTP envelope. */
+    fetch<T>(): Promise<T>;
+    private completeCallback;
+    private makeRequest;
+    private resolveTarget;
+    private resolveBodyAndHeaders;
+    private countBodySources;
+    private encodeFormBody;
+    private encodeMultipartBody;
+}
+export declare function createZLinkHttpRequestBuilder(client: ZLinkHttpClient, method: ZLinkHttpMethod, path: string): ZLinkHttpRequestBuilder;

package/dist/request-builder.js

@@ -0,0 +1,291 @@
+"use strict";
+/* SPDX-License-Identifier: Apache-2.0 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkHttpRequestBuilder = void 0;
+exports.createZLinkHttpRequestBuilder = createZLinkHttpRequestBuilder;
+const framework_1 = require("@zlink-systems/framework");
+const text_1 = require("./runtime/text");
+/**
+ * Fluent builder for a single request. Mirrors the C++ `request_builder_t`. Submission returns a
+ * `Promise`; the event loop is never blocked while the request is in flight.
+ */
+class ZLinkHttpRequestBuilder {
+    method;
+    path;
+    bodyValue;
+    bodyProviderValue;
+    headersValue = {};
+    timeoutMsValue;
+    queryValue = [];
+    formValue = [];
+    multipartValue = [];
+    clientInstance;
+    clientFactory;
+    ownsClient;
+    executionTurn;
+    executionScheduler;
+    consumed = false;
+    constructor(client, method, path, clientFactory) {
+        this.method = method;
+        this.path = path;
+        this.clientInstance = client;
+        this.clientFactory = clientFactory;
+        // A one-shot request (builder verb shortcut) owns the lazily-built client and closes it once the
+        // request completes.
+        this.ownsClient = clientFactory !== undefined;
+        this.executionScheduler = client?.executionScheduler;
+        this.executionTurn = client?.executionScheduler?.capture()
+            ?? clientFactory?.captureExecutionTurn();
+        if (path.length === 0 || path[0] !== '/') {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP request path must start with /');
+        }
+    }
+    // Resolves the client to run on, building a one-shot client lazily. A one-shot request builder is
+    // single-use so its lazily-built client is closed exactly once.
+    resolveClient() {
+        if (this.ownsClient && this.consumed) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'A one-shot HTTP request can only be submitted once');
+        }
+        this.consumed = true;
+        if (this.clientInstance === undefined) {
+            if (this.clientFactory === undefined) {
+                throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP request has no client');
+            }
+            this.clientInstance = this.clientFactory.build();
+        }
+        return this.clientInstance;
+    }
+    async closeIfOwned() {
+        if (this.ownsClient && this.clientInstance !== undefined) {
+            // A one-shot cleanup failure must not mask the request result.
+            await this.clientInstance.close().catch(() => undefined);
+        }
+    }
+    header(name, value) {
+        (0, text_1.requireNonBlank)(name, 'HTTP request header name is required');
+        this.headersValue[name.toLowerCase()] = value;
+        return this;
+    }
+    query(name, value) {
+        (0, text_1.requireNonBlank)(name, 'HTTP request query name is required');
+        this.queryValue.push([name, value]);
+        return this;
+    }
+    timeout(milliseconds) {
+        (0, text_1.requirePositiveTimeout)(milliseconds);
+        this.timeoutMsValue = milliseconds;
+        return this;
+    }
+    body(value, contentType) {
+        if (contentType !== undefined) {
+            if (typeof value !== 'string') {
+                throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP request raw body content is required');
+            }
+            (0, text_1.requireNonBlank)(contentType, 'HTTP request body content type is required');
+            this.bodyValue = value;
+            this.headersValue['content-type'] = contentType;
+            return this;
+        }
+        this.bodyValue = JSON.stringify(value);
+        this.headersValue['content-type'] ??= 'application/json';
+        return this;
+    }
+    /**
+     * Streams the request body chunk by chunk with chunked transfer-encoding; the provider returns
+     * `null` when the body is complete. Streamed requests are excluded from retry.
+     */
+    bodyStream(provider, contentType) {
+        if (typeof provider !== 'function') {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP request body stream provider is required');
+        }
+        (0, text_1.requireNonBlank)(contentType, 'HTTP request body content type is required');
+        this.bodyProviderValue = provider;
+        this.headersValue['content-type'] = contentType;
+        return this;
+    }
+    form(name, value) {
+        (0, text_1.requireNonBlank)(name, 'HTTP request form field name is required');
+        this.formValue.push([name, value]);
+        return this;
+    }
+    multipart(name, value) {
+        (0, text_1.requireNonBlank)(name, 'HTTP request multipart field name is required');
+        this.multipartValue.push({ name, filename: '', content: value, contentType: '' });
+        return this;
+    }
+    multipartFile(name, filename, content, contentType) {
+        (0, text_1.requireNonBlank)(name, 'HTTP request multipart field name is required');
+        (0, text_1.requireNonBlank)(filename, 'HTTP request multipart filename is required');
+        (0, text_1.requireNonBlank)(contentType, 'HTTP request multipart content type is required');
+        this.multipartValue.push({ name, filename, content, contentType });
+        return this;
+    }
+    /** Executes the request and returns the raw response while retaining the current turn. */
+    async submitRaw() {
+        const request = this.makeRequest(undefined);
+        const client = this.resolveClient();
+        try {
+            return await client.runtime.executeAsync(request);
+        }
+        finally {
+            await this.closeIfOwned();
+        }
+    }
+    /**
+     * Streams the response body to `sink` chunk by chunk instead of buffering it; the returned
+     * response carries status and headers with an empty body (no decompression of chunks).
+     */
+    async download(sink) {
+        if (typeof sink !== 'function') {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP request download sink is required');
+        }
+        const request = this.makeRequest(sink);
+        const client = this.resolveClient();
+        try {
+            return await client.runtime.executeAsync(request);
+        }
+        finally {
+            await this.closeIfOwned();
+        }
+    }
+    async(callback) {
+        const pending = this.executeTyped();
+        if (callback === undefined) {
+            return pending;
+        }
+        void pending.then((response) => this.completeCallback(() => callback(undefined, response)), (error) => this.completeCallback(() => callback(error, undefined)));
+    }
+    async executeTyped() {
+        const raw = await this.submitRaw();
+        if (raw.status >= 400) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.InternalFailure, `HTTP request failed with status ${raw.status}`);
+        }
+        let body;
+        if (raw.body.length === 0) {
+            body = null;
+        }
+        else {
+            try {
+                body = JSON.parse(raw.body, safeJsonReviver);
+            }
+            catch (cause) {
+                throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, cause instanceof Error ? cause.message : 'HTTP response body decode failed', cause);
+            }
+        }
+        return { status: raw.status, headers: raw.headers, body, rawBody: raw.body };
+    }
+    /** Returns only the decoded body for client-side scenarios that do not need the HTTP envelope. */
+    async fetch() {
+        return (await this.executeTyped()).body;
+    }
+    completeCallback(callback) {
+        if (this.executionTurn === undefined) {
+            callback();
+            return;
+        }
+        this.executionTurn.post(callback);
+    }
+    makeRequest(sink) {
+        const { body, headers } = this.resolveBodyAndHeaders();
+        return {
+            method: this.method,
+            target: this.resolveTarget(),
+            ...(body !== undefined ? { body } : {}),
+            ...(this.bodyProviderValue !== undefined ? { bodyProvider: this.bodyProviderValue } : {}),
+            headers,
+            ...(this.timeoutMsValue !== undefined ? { timeoutMs: this.timeoutMsValue } : {}),
+            ...(sink !== undefined ? { sink } : {}),
+        };
+    }
+    resolveTarget() {
+        if (this.queryValue.length === 0) {
+            return this.path;
+        }
+        let target = this.path;
+        let separator = this.path.includes('?') ? '&' : '?';
+        for (const [name, value] of this.queryValue) {
+            target += `${separator}${(0, text_1.percentEncode)(name)}=${(0, text_1.percentEncode)(value)}`;
+            separator = '&';
+        }
+        return target;
+    }
+    resolveBodyAndHeaders() {
+        if (this.countBodySources() > 1) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP request accepts a single body source: body, body_stream, form, or multipart');
+        }
+        const headers = { ...this.headersValue };
+        if (this.bodyValue !== undefined) {
+            return { body: this.bodyValue, headers };
+        }
+        if (this.formValue.length > 0) {
+            headers['content-type'] = 'application/x-www-form-urlencoded';
+            return { body: this.encodeFormBody(), headers };
+        }
+        if (this.multipartValue.length > 0) {
+            const boundary = (0, text_1.makeMultipartBoundary)();
+            headers['content-type'] = `multipart/form-data; boundary=${boundary}`;
+            return { body: this.encodeMultipartBody(boundary), headers };
+        }
+        return { body: undefined, headers };
+    }
+    countBodySources() {
+        return ((this.bodyValue !== undefined ? 1 : 0) +
+            (this.bodyProviderValue !== undefined ? 1 : 0) +
+            (this.formValue.length > 0 ? 1 : 0) +
+            (this.multipartValue.length > 0 ? 1 : 0));
+    }
+    encodeFormBody() {
+        return this.formValue
+            .map(([name, value]) => `${(0, text_1.percentEncode)(name)}=${(0, text_1.percentEncode)(value)}`)
+            .join('&');
+    }
+    encodeMultipartBody(boundary) {
+        let encoded = '';
+        for (const part of this.multipartValue) {
+            encoded += `--${boundary}\r\n`;
+            encoded += `Content-Disposition: form-data; name="${part.name}"`;
+            if (part.filename.length > 0) {
+                encoded += `; filename="${part.filename}"`;
+            }
+            encoded += '\r\n';
+            if (part.contentType.length > 0) {
+                encoded += `Content-Type: ${part.contentType}\r\n`;
+            }
+            encoded += '\r\n';
+            encoded += part.content;
+            encoded += '\r\n';
+        }
+        encoded += `--${boundary}--\r\n`;
+        return encoded;
+    }
+}
+exports.ZLinkHttpRequestBuilder = ZLinkHttpRequestBuilder;
+class ZLinkFrameworkHttpRequestBuilder extends ZLinkHttpRequestBuilder {
+    /** Starts a server-side one-way request and ignores its response body. */
+    async submit() {
+        if (this.executionScheduler === undefined) {
+            throw new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP submit requires a framework server client');
+        }
+        await this.submitRaw();
+    }
+    /** Executes a typed request while yielding the current Spot turn. */
+    yield() {
+        if (this.executionTurn === undefined) {
+            return Promise.reject(new framework_1.ZLinkFrameworkException(framework_1.ZLinkFrameworkErrorKind.ProtocolError, 'HTTP yield requires a framework Spot turn'));
+        }
+        return this.executionTurn.yieldPromise(this.executeTyped());
+    }
+}
+function createZLinkHttpRequestBuilder(client, method, path) {
+    return client.executionScheduler === undefined
+        ? new ZLinkHttpRequestBuilder(client, method, path)
+        : new ZLinkFrameworkHttpRequestBuilder(client, method, path);
+}
+// Prototype-pollution guard, mirroring the framework's stream JSON codec.
+const prototypeKeys = new Set(['__proto__', 'constructor', 'prototype']);
+function safeJsonReviver(key, value) {
+    if (prototypeKeys.has(key)) {
+        return undefined;
+    }
+    return value;
+}

package/dist/runtime/browser-runtime.d.ts

@@ -0,0 +1,12 @@
+import type { HttpClientOptions } from './options';
+import type { HttpRequestSpec, RawResult } from './request-performer';
+/** Browser transport for the same public client surface used by the Node runtime. */
+export declare class HttpClientRuntime {
+    private readonly options;
+    private readonly retryPolicy;
+    constructor(options: HttpClientOptions);
+    executeAsync(spec: HttpRequestSpec): Promise<RawResult>;
+    close(): Promise<void>;
+    private perform;
+    private buildHeaders;
+}