@truefoundry/trueforge-sdk 0.0.0 → 0.1.0-rc.1

package/dist/esm/core/stream/Stream.mjs

@@ -0,0 +1,501 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { fromJson } from "../json.mjs";
+import { RUNTIME } from "../runtime/index.mjs";
+const DATA_PREFIX = "data:";
+const EVENT_PREFIX = "event:";
+const ID_PREFIX = "id:";
+const RETRY_PREFIX = "retry:";
+const DEFAULT_MAX_RECONNECTION_ATTEMPTS = 5;
+const DEFAULT_RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_DELAY_MS = 30000;
+export class Stream {
+    constructor({ stream, parse, eventShape, signal, reconnectionEnabled, maxReconnectionAttempts, reconnect, }) {
+        var _a;
+        this.controller = new AbortController();
+        this.stream = stream;
+        this.parse = parse;
+        if (eventShape.type === "sse") {
+            this.prefix = DATA_PREFIX;
+            this.messageTerminator = "\n";
+            this.streamTerminator = eventShape.streamTerminator;
+            this.eventDiscriminator = eventShape.eventDiscriminator;
+            this.resumable = (_a = eventShape.resumable) !== null && _a !== void 0 ? _a : false;
+        }
+        else {
+            this.messageTerminator = eventShape.messageTerminator;
+            this.resumable = false;
+        }
+        this.reconnectionEnabled = reconnectionEnabled !== null && reconnectionEnabled !== void 0 ? reconnectionEnabled : true;
+        this.maxReconnectionAttempts = maxReconnectionAttempts !== null && maxReconnectionAttempts !== void 0 ? maxReconnectionAttempts : DEFAULT_MAX_RECONNECTION_ATTEMPTS;
+        this.reconnect = reconnect;
+        if (signal != null) {
+            this.externalSignal = signal;
+            this.onExternalAbort = () => this.controller.abort();
+            signal.addEventListener("abort", this.onExternalAbort, { once: true });
+        }
+        // Initialize shared TextDecoder
+        if (typeof TextDecoder !== "undefined") {
+            this.decoder = new TextDecoder("utf-8");
+        }
+    }
+    iterMessages() {
+        return __asyncGenerator(this, arguments, function* iterMessages_1() {
+            if (this.eventDiscriminator != null) {
+                yield __await(yield* __asyncDelegator(__asyncValues(this.iterSseEvents())));
+            }
+            else {
+                yield __await(yield* __asyncDelegator(__asyncValues(this.iterDataMessages())));
+            }
+        });
+    }
+    iterDataMessages() {
+        return __asyncGenerator(this, arguments, function* iterDataMessages_1() {
+            var _a, e_1, _b, _c;
+            let reconnectAttempts = 0;
+            let currentStream = this.stream;
+            let lastId;
+            // The id of the most recently *dispatched* event. Per the WHATWG
+            // EventSource spec, the "last event ID" is only committed when an event
+            // is dispatched, not when the `id:` line is parsed. Reconnecting with a
+            // parsed-but-undispatched id would skip an event that was never yielded
+            // (e.g. if the connection drops after `id:` but before the event's
+            // terminating blank line), so reconnection uses lastDispatchedId.
+            let lastDispatchedId;
+            let lastRetry;
+            while (true) {
+                const stream = readableStreamAsyncIterable(currentStream);
+                let buf = "";
+                let dataValue;
+                try {
+                    for (var _d = true, stream_1 = (e_1 = void 0, __asyncValues(stream)), stream_1_1; stream_1_1 = yield __await(stream_1.next()), _a = stream_1_1.done, !_a; _d = true) {
+                        _c = stream_1_1.value;
+                        _d = false;
+                        const chunk = _c;
+                        buf += this.decodeChunk(chunk);
+                        let terminatorIndex;
+                        while ((terminatorIndex = buf.indexOf(this.messageTerminator)) >= 0) {
+                            const line = buf.slice(0, terminatorIndex);
+                            buf = buf.slice(terminatorIndex + this.messageTerminator.length);
+                            if (!line.trim()) {
+                                if (this.prefix != null && dataValue != null) {
+                                    if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+                                        return yield __await(void 0);
+                                    }
+                                    const data = yield __await(this.parse(fromJson(dataValue)));
+                                    yield yield __await({ data, id: lastId, retry: lastRetry, event: undefined });
+                                    lastDispatchedId = lastId;
+                                    reconnectAttempts = 0;
+                                    dataValue = undefined;
+                                }
+                                continue;
+                            }
+                            if (line.startsWith(ID_PREFIX)) {
+                                const idValue = line.slice(ID_PREFIX.length).trim();
+                                if (!idValue.includes("\0")) {
+                                    lastId = idValue;
+                                }
+                                continue;
+                            }
+                            if (line.startsWith(RETRY_PREFIX)) {
+                                const retryValue = line.slice(RETRY_PREFIX.length).trim();
+                                const parsed = parseInt(retryValue, 10);
+                                if (!Number.isNaN(parsed) && String(parsed) === retryValue) {
+                                    lastRetry = parsed;
+                                }
+                                continue;
+                            }
+                            if (this.prefix != null) {
+                                const prefixIndex = line.indexOf(this.prefix);
+                                if (prefixIndex === -1) {
+                                    continue;
+                                }
+                                const val = line.slice(prefixIndex + this.prefix.length).trim();
+                                dataValue = dataValue != null ? `${dataValue}\n${val}` : val;
+                            }
+                            else {
+                                if (this.streamTerminator != null && line.includes(this.streamTerminator)) {
+                                    return yield __await(void 0);
+                                }
+                                const data = yield __await(this.parse(fromJson(line)));
+                                yield yield __await({ data, id: lastId, retry: lastRetry, event: undefined });
+                                lastDispatchedId = lastId;
+                                reconnectAttempts = 0;
+                            }
+                        }
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+                if (this.prefix != null && dataValue != null) {
+                    if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+                        return yield __await(void 0);
+                    }
+                    const data = yield __await(this.parse(fromJson(dataValue)));
+                    yield yield __await({ data, id: lastId, retry: lastRetry, event: undefined });
+                    lastDispatchedId = lastId;
+                    reconnectAttempts = 0;
+                }
+                if (!this.shouldReconnect(lastDispatchedId, reconnectAttempts)) {
+                    return yield __await(void 0);
+                }
+                reconnectAttempts++;
+                yield __await(this.delayReconnect(lastRetry));
+                if (this.controller.signal.aborted) {
+                    return yield __await(void 0);
+                }
+                // Re-check after async delay; needed for TypeScript narrowing.
+                const reconnectFn = this.reconnect;
+                if (reconnectFn == null || lastDispatchedId == null) {
+                    return yield __await(void 0);
+                }
+                try {
+                    const reconnected = yield __await(reconnectFn(lastDispatchedId));
+                    if (reconnected == null) {
+                        currentStream = this.createEmptyStream();
+                        continue;
+                    }
+                    currentStream = reconnected;
+                }
+                catch (_e) {
+                    // Failed reconnect (e.g. HTTP error); assign an empty stream
+                    // so the next iteration is a safe no-op before shouldReconnect.
+                    currentStream = this.createEmptyStream();
+                }
+            }
+        });
+    }
+    iterSseEvents() {
+        return __asyncGenerator(this, arguments, function* iterSseEvents_1() {
+            var _a, e_2, _b, _c;
+            let reconnectAttempts = 0;
+            let currentStream = this.stream;
+            let lastId;
+            // See iterDataMessages: reconnection uses the last *dispatched* id (per
+            // the EventSource spec), not the last *parsed* id, to avoid skipping an
+            // event that was never yielded when a drop lands mid-event.
+            let lastDispatchedId;
+            let lastRetry;
+            while (true) {
+                const stream = readableStreamAsyncIterable(currentStream);
+                let buf = "";
+                let eventType;
+                let dataValue;
+                try {
+                    for (var _d = true, stream_2 = (e_2 = void 0, __asyncValues(stream)), stream_2_1; stream_2_1 = yield __await(stream_2.next()), _a = stream_2_1.done, !_a; _d = true) {
+                        _c = stream_2_1.value;
+                        _d = false;
+                        const chunk = _c;
+                        buf += this.decodeChunk(chunk);
+                        let terminatorIndex;
+                        while ((terminatorIndex = buf.indexOf("\n")) >= 0) {
+                            const line = buf.slice(0, terminatorIndex).replace(/\r$/, "");
+                            buf = buf.slice(terminatorIndex + 1);
+                            if (!line.trim()) {
+                                if (dataValue != null) {
+                                    const data = yield __await(this.dispatchSseEvent(dataValue, eventType));
+                                    if (data == null) {
+                                        return yield __await(void 0);
+                                    }
+                                    yield yield __await({ data, id: lastId, retry: lastRetry, event: eventType });
+                                    lastDispatchedId = lastId;
+                                    reconnectAttempts = 0;
+                                }
+                                eventType = undefined;
+                                dataValue = undefined;
+                                continue;
+                            }
+                            if (line.startsWith(EVENT_PREFIX)) {
+                                eventType = line.slice(EVENT_PREFIX.length).trim();
+                            }
+                            else if (line.startsWith(DATA_PREFIX)) {
+                                const val = line.slice(DATA_PREFIX.length).trim();
+                                dataValue = dataValue != null ? `${dataValue}\n${val}` : val;
+                            }
+                            else if (line.startsWith(ID_PREFIX)) {
+                                const idValue = line.slice(ID_PREFIX.length).trim();
+                                if (!idValue.includes("\0")) {
+                                    lastId = idValue;
+                                }
+                            }
+                            else if (line.startsWith(RETRY_PREFIX)) {
+                                const retryValue = line.slice(RETRY_PREFIX.length).trim();
+                                const parsed = parseInt(retryValue, 10);
+                                if (!Number.isNaN(parsed) && String(parsed) === retryValue) {
+                                    lastRetry = parsed;
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_2.return)) yield __await(_b.call(stream_2));
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                }
+                if (dataValue != null) {
+                    const data = yield __await(this.dispatchSseEvent(dataValue, eventType));
+                    if (data != null) {
+                        yield yield __await({ data, id: lastId, retry: lastRetry, event: eventType });
+                        lastDispatchedId = lastId;
+                        reconnectAttempts = 0;
+                    }
+                }
+                if (!this.shouldReconnect(lastDispatchedId, reconnectAttempts)) {
+                    return yield __await(void 0);
+                }
+                reconnectAttempts++;
+                yield __await(this.delayReconnect(lastRetry));
+                if (this.controller.signal.aborted) {
+                    return yield __await(void 0);
+                }
+                // Re-check after async delay; needed for TypeScript narrowing.
+                const reconnectFn = this.reconnect;
+                if (reconnectFn == null || lastDispatchedId == null) {
+                    return yield __await(void 0);
+                }
+                try {
+                    const reconnected = yield __await(reconnectFn(lastDispatchedId));
+                    if (reconnected == null) {
+                        currentStream = this.createEmptyStream();
+                        continue;
+                    }
+                    currentStream = reconnected;
+                }
+                catch (_e) {
+                    // Failed reconnect (e.g. HTTP error); assign an empty stream
+                    // so the next iteration is a safe no-op before shouldReconnect.
+                    currentStream = this.createEmptyStream();
+                }
+            }
+        });
+    }
+    /**
+     * Parses and returns a single SSE event, or returns null if the event is a stream terminator.
+     */
+    dispatchSseEvent(dataValue, eventType) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+                return null;
+            }
+            return this.parse(this.injectDiscriminator(fromJson(dataValue), eventType));
+        });
+    }
+    /**
+     * Determines whether a reconnection attempt should be made.
+     */
+    shouldReconnect(lastId, reconnectAttempts) {
+        if (!this.resumable) {
+            return false;
+        }
+        if (this.streamTerminator == null) {
+            // Without a terminator the client cannot distinguish a completed
+            // stream from a dropped connection, so reconnection is disabled.
+            return false;
+        }
+        // NOTE: When a terminator IS configured but the server never sends it
+        // (e.g. it drops the connection after emitting events every time),
+        // maxReconnectionAttempts is a per-consecutive-failure cap — each
+        // yielded event resets the counter. This matches EventSource semantics
+        // but means such a server can cause unbounded reconnections. Callers
+        // concerned about this should impose a wall-clock budget externally.
+        if (!this.reconnectionEnabled) {
+            return false;
+        }
+        if (this.reconnect == null) {
+            return false;
+        }
+        if (lastId == null || lastId === "") {
+            return false;
+        }
+        if (reconnectAttempts >= this.maxReconnectionAttempts) {
+            return false;
+        }
+        if (this.controller.signal.aborted) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delays before reconnecting, using a server-sent retry directive if provided
+     * (clamped to MAX_RECONNECT_DELAY_MS), otherwise falling back to
+     * DEFAULT_RECONNECT_DELAY_MS. The delay is abortable: if the stream's abort
+     * signal fires during the wait, the promise resolves immediately.
+     */
+    delayReconnect(lastRetry) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const base = lastRetry != null && lastRetry > 0 ? lastRetry : DEFAULT_RECONNECT_DELAY_MS;
+            const delay = Math.min(base, MAX_RECONNECT_DELAY_MS);
+            const signal = this.controller.signal;
+            if (signal.aborted) {
+                return;
+            }
+            yield new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    signal.removeEventListener("abort", onAbort);
+                    resolve();
+                }, delay);
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+        });
+    }
+    createEmptyStream() {
+        return new ReadableStream({
+            start(controller) {
+                controller.close();
+            },
+        });
+    }
+    removeAbortListener() {
+        if (this.externalSignal != null && this.onExternalAbort != null) {
+            this.externalSignal.removeEventListener("abort", this.onExternalAbort);
+            this.onExternalAbort = undefined;
+        }
+    }
+    withMetadata() {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return __asyncGenerator(this, arguments, function* _a() {
+                    try {
+                        yield __await(yield* __asyncDelegator(__asyncValues(self.iterMessages())));
+                    }
+                    finally {
+                        self.removeAbortListener();
+                    }
+                });
+            },
+        };
+    }
+    injectDiscriminator(parsed, eventType) {
+        if (this.eventDiscriminator == null || eventType == null) {
+            return parsed;
+        }
+        if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return parsed;
+        }
+        const obj = parsed;
+        if (this.eventDiscriminator in obj) {
+            return parsed;
+        }
+        return Object.assign({ [this.eventDiscriminator]: eventType }, obj);
+    }
+    [Symbol.asyncIterator]() {
+        return __asyncGenerator(this, arguments, function* _a() {
+            var _b, e_3, _c, _d;
+            try {
+                try {
+                    for (var _e = true, _f = __asyncValues(this.iterMessages()), _g; _g = yield __await(_f.next()), _b = _g.done, !_b; _e = true) {
+                        _d = _g.value;
+                        _e = false;
+                        const event = _d;
+                        yield yield __await(event.data);
+                    }
+                }
+                catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                finally {
+                    try {
+                        if (!_e && !_b && (_c = _f.return)) yield __await(_c.call(_f));
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                }
+            }
+            finally {
+                this.removeAbortListener();
+            }
+        });
+    }
+    decodeChunk(chunk) {
+        let decoded = "";
+        // If TextDecoder is available, use the streaming decoder instance
+        if (this.decoder != null) {
+            decoded += this.decoder.decode(chunk, { stream: true });
+        }
+        // Buffer is present in Node.js environment
+        else if (RUNTIME.type === "node" && typeof chunk !== "undefined") {
+            decoded += Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        }
+        return decoded;
+    }
+}
+/**
+ * Browser polyfill for ReadableStream
+ */
+// biome-ignore lint/suspicious/noExplicitAny: allow explicit any
+export function readableStreamAsyncIterable(stream) {
+    if (stream[Symbol.asyncIterator]) {
+        return stream;
+    }
+    const reader = stream.getReader();
+    return {
+        next() {
+            return __awaiter(this, void 0, void 0, function* () {
+                try {
+                    const result = yield reader.read();
+                    if (result === null || result === void 0 ? void 0 : result.done) {
+                        reader.releaseLock();
+                    } // release lock when stream becomes closed
+                    return result;
+                }
+                catch (e) {
+                    reader.releaseLock(); // release lock when stream becomes errored
+                    throw e;
+                }
+            });
+        },
+        return() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const cancelPromise = reader.cancel();
+                reader.releaseLock();
+                yield cancelPromise;
+                return { done: true, value: undefined };
+            });
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+}

package/dist/esm/core/stream/index.d.mts

@@ -0,0 +1,2 @@
+export type { ServerSentEvent } from "./Stream.mjs";
+export { Stream } from "./Stream.mjs";

package/dist/esm/core/stream/index.mjs

@@ -0,0 +1 @@
+export { Stream } from "./Stream.mjs";

package/dist/esm/core/url/QueryStringBuilder.d.mts

@@ -0,0 +1,47 @@
+/**
+ * Creates a fluent builder for constructing URL query strings.
+ *
+ * Each `.add()` call serializes its value immediately (like C#'s builder),
+ * so no format tracking is needed — the style is applied at add-time.
+ *
+ * Usage (generated code):
+ *
+ *     const qs = core.url.queryBuilder()
+ *         .add("limit", limit)
+ *         .add("tags", tags, { style: "comma" })   // explode: false
+ *         .mergeAdditional(requestOptions?.queryParams)
+ *         .build();
+ */
+export declare function queryBuilder(): QueryStringBuilder;
+declare class QueryStringBuilder {
+    private parts;
+    /**
+     * Adds a query parameter, serializing it immediately.
+     *
+     * By default arrays use "repeat" format (`key=a&key=b`).
+     * Pass `{ style: "comma" }` for OpenAPI `explode: false` parameters
+     * to get comma-separated values (`key=a,b,c`).
+     *
+     * Null / undefined values are silently skipped.
+     */
+    add(key: string, value: unknown, options?: {
+        style?: "comma";
+    }): this;
+    /**
+     * Adds multiple query parameters at once from a record.
+     * All parameters use the default "repeat" array format.
+     * Null / undefined values are silently skipped.
+     */
+    addMany(params: Record<string, unknown>): this;
+    /**
+     * Merges additional query parameters supplied at call-time via
+     * `requestOptions.queryParams`. Overrides existing keys (last-write-wins).
+     */
+    mergeAdditional(additionalParams?: Record<string, unknown>): this;
+    /**
+     * Returns the assembled query string (without the leading `?`).
+     * Returns an empty string when no parameters were added.
+     */
+    build(): string;
+}
+export {};

package/dist/esm/core/url/QueryStringBuilder.mjs

@@ -0,0 +1,80 @@
+import { toQueryString } from "./qs.mjs";
+/**
+ * Creates a fluent builder for constructing URL query strings.
+ *
+ * Each `.add()` call serializes its value immediately (like C#'s builder),
+ * so no format tracking is needed — the style is applied at add-time.
+ *
+ * Usage (generated code):
+ *
+ *     const qs = core.url.queryBuilder()
+ *         .add("limit", limit)
+ *         .add("tags", tags, { style: "comma" })   // explode: false
+ *         .mergeAdditional(requestOptions?.queryParams)
+ *         .build();
+ */
+export function queryBuilder() {
+    return new QueryStringBuilder();
+}
+class QueryStringBuilder {
+    constructor() {
+        this.parts = new Map();
+    }
+    /**
+     * Adds a query parameter, serializing it immediately.
+     *
+     * By default arrays use "repeat" format (`key=a&key=b`).
+     * Pass `{ style: "comma" }` for OpenAPI `explode: false` parameters
+     * to get comma-separated values (`key=a,b,c`).
+     *
+     * Null / undefined values are silently skipped.
+     */
+    add(key, value, options) {
+        if (value === undefined || value === null) {
+            return this;
+        }
+        const serialized = toQueryString({ [key]: value }, { arrayFormat: (options === null || options === void 0 ? void 0 : options.style) === "comma" ? "comma" : "repeat" });
+        if (serialized.length > 0) {
+            this.parts.set(key, serialized);
+        }
+        return this;
+    }
+    /**
+     * Adds multiple query parameters at once from a record.
+     * All parameters use the default "repeat" array format.
+     * Null / undefined values are silently skipped.
+     */
+    addMany(params) {
+        if (params != null) {
+            for (const [key, value] of Object.entries(params)) {
+                this.add(key, value);
+            }
+        }
+        return this;
+    }
+    /**
+     * Merges additional query parameters supplied at call-time via
+     * `requestOptions.queryParams`. Overrides existing keys (last-write-wins).
+     */
+    mergeAdditional(additionalParams) {
+        if (additionalParams != null) {
+            for (const [key, value] of Object.entries(additionalParams)) {
+                if (value === undefined || value === null) {
+                    continue;
+                }
+                const serialized = toQueryString({ [key]: value }, { arrayFormat: "repeat" });
+                if (serialized.length > 0) {
+                    this.parts.set(key, serialized);
+                }
+            }
+        }
+        return this;
+    }
+    /**
+     * Returns the assembled query string (without the leading `?`).
+     * Returns an empty string when no parameters were added.
+     */
+    build() {
+        return [...this.parts.values()].join("&");
+    }
+}

package/dist/esm/core/url/encodePathParam.d.mts

@@ -0,0 +1 @@
+export declare function encodePathParam(param: unknown): string;

package/dist/esm/core/url/encodePathParam.mjs

@@ -0,0 +1,18 @@
+export function encodePathParam(param) {
+    if (param === null) {
+        return "null";
+    }
+    const typeofParam = typeof param;
+    switch (typeofParam) {
+        case "undefined":
+            return "undefined";
+        case "string":
+        case "number":
+        case "boolean":
+            break;
+        default:
+            param = String(param);
+            break;
+    }
+    return encodeURIComponent(param);
+}

package/dist/esm/core/url/index.d.mts

@@ -0,0 +1,4 @@
+export { encodePathParam } from "./encodePathParam.mjs";
+export { join } from "./join.mjs";
+export { queryBuilder } from "./QueryStringBuilder.mjs";
+export { toQueryString } from "./qs.mjs";

package/dist/esm/core/url/index.mjs

@@ -0,0 +1,4 @@
+export { encodePathParam } from "./encodePathParam.mjs";
+export { join } from "./join.mjs";
+export { queryBuilder } from "./QueryStringBuilder.mjs";
+export { toQueryString } from "./qs.mjs";

package/dist/esm/core/url/join.d.mts

@@ -0,0 +1 @@
+export declare function join(base: string, ...segments: string[]): string;