phenoml 13.0.0 → 14.0.0

package/dist/cjs/api/resources/tools/types/index.js

@@ -18,7 +18,9 @@ __exportStar(require("./CohortResponse.js"), exports);
 __exportStar(require("./Lang2FhirAndCreateMultiResponse.js"), exports);
 __exportStar(require("./Lang2FhirAndCreateResponse.js"), exports);
 __exportStar(require("./Lang2FhirAndSearchResponse.js"), exports);
+__exportStar(require("./McpServer.js"), exports);
 __exportStar(require("./McpServerResponse.js"), exports);
+__exportStar(require("./McpServerTool.js"), exports);
 __exportStar(require("./McpServerToolCallResponse.js"), exports);
 __exportStar(require("./McpServerToolResponse.js"), exports);
 __exportStar(require("./SearchConcept.js"), exports);

package/dist/cjs/api/resources/workflows/client/Client.d.ts

@@ -42,11 +42,12 @@ export declare class WorkflowsClient {
      *     await client.workflows.create({
      *         verbose: true,
      *         name: "Patient Data Mapping Workflow",
-     *         workflow_instructions: "Given diagnosis data, find the patient and create condition record",
+     *         workflow_instructions: "Given diagnosis data, find the patient and create a condition record linked to their encounter",
      *         sample_data: {
      *             "patient_last_name": "Rippin",
      *             "patient_first_name": "Clay",
-     *             "diagnosis_code": "I10"
+     *             "diagnosis_code": "I10",
+     *             "encounter_date": "2024-01-15"
      *         },
      *         fhir_provider_id: "550e8400-e29b-41d4-a716-446655440000"
      *     })
@@ -88,12 +89,13 @@ export declare class WorkflowsClient {
      * @example
      *     await client.workflows.update("id", {
      *         verbose: true,
-     *         name: "Updated Patient Data Mapping Workflow",
-     *         workflow_instructions: "Given diagnosis data, find the patient and create condition record",
+     *         name: "Patient Data Mapping Workflow (v2)",
+     *         workflow_instructions: "Given diagnosis data, find the patient and create a condition record linked to their encounter",
      *         sample_data: {
-     *             "patient_last_name": "Smith",
-     *             "patient_first_name": "John",
-     *             "diagnosis_code": "E11"
+     *             "patient_last_name": "Rippin",
+     *             "patient_first_name": "Clay",
+     *             "diagnosis_code": "I10",
+     *             "encounter_date": "2024-01-15"
      *         },
      *         fhir_provider_id: "550e8400-e29b-41d4-a716-446655440000"
      *     })
@@ -130,14 +132,24 @@ export declare class WorkflowsClient {
      * @throws {@link phenoml.workflows.InternalServerError}
      *
      * @example
-     *     await client.workflows.execute("id", {
+     *     await client.workflows.execute("7a8b9c0d-1234-5678-abcd-ef9876543210", {
      *         input_data: {
      *             "patient_last_name": "Johnson",
      *             "patient_first_name": "Mary",
      *             "diagnosis_code": "M79.3",
-     *             "encounter_date": "2024-01-15"
+     *             "encounter_date": "2024-03-20"
      *         }
      *     })
+     *
+     * @example
+     *     await client.workflows.execute("7a8b9c0d-1234-5678-abcd-ef9876543210", {
+     *         input_data: {
+     *             "patient_last_name": "Johnson",
+     *             "patient_first_name": "Mary",
+     *             "diagnosis_code": "M79.3"
+     *         },
+     *         preview: true
+     *     })
      */
     execute(id: string, request: phenoml.workflows.ExecuteWorkflowRequest, requestOptions?: WorkflowsClient.RequestOptions): core.HttpResponsePromise<phenoml.workflows.ExecuteWorkflowResponse>;
     private __execute;

package/dist/cjs/api/resources/workflows/client/Client.js

@@ -97,7 +97,11 @@ class WorkflowsClient {
                 url: core.url.join((_d = (_c = (yield core.Supplier.get(this._options.baseUrl))) !== null && _c !== void 0 ? _c : (yield core.Supplier.get(this._options.environment))) !== null && _d !== void 0 ? _d : environments.phenomlEnvironment.Default, "workflows"),
                 method: "GET",
                 headers: _headers,
-                queryParameters: Object.assign(Object.assign({}, _queryParams), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams),
+                queryString: core.url
+                    .queryBuilder()
+                    .addMany(_queryParams)
+                    .mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams)
+                    .build(),
                 timeoutMs: ((_g = (_e = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _e !== void 0 ? _e : (_f = this._options) === null || _f === void 0 ? void 0 : _f.timeoutInSeconds) !== null && _g !== void 0 ? _g : 60) * 1000,
                 maxRetries: (_h = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _h !== void 0 ? _h : (_j = this._options) === null || _j === void 0 ? void 0 : _j.maxRetries,
                 abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
@@ -144,11 +148,12 @@ class WorkflowsClient {
      *     await client.workflows.create({
      *         verbose: true,
      *         name: "Patient Data Mapping Workflow",
-     *         workflow_instructions: "Given diagnosis data, find the patient and create condition record",
+     *         workflow_instructions: "Given diagnosis data, find the patient and create a condition record linked to their encounter",
      *         sample_data: {
      *             "patient_last_name": "Rippin",
      *             "patient_first_name": "Clay",
-     *             "diagnosis_code": "I10"
+     *             "diagnosis_code": "I10",
+     *             "encounter_date": "2024-01-15"
      *         },
      *         fhir_provider_id: "550e8400-e29b-41d4-a716-446655440000"
      *     })
@@ -170,7 +175,11 @@ class WorkflowsClient {
                 method: "POST",
                 headers: _headers,
                 contentType: "application/json",
-                queryParameters: Object.assign(Object.assign({}, _queryParams), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams),
+                queryString: core.url
+                    .queryBuilder()
+                    .addMany(_queryParams)
+                    .mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams)
+                    .build(),
                 requestType: "json",
                 body: _body,
                 timeoutMs: ((_g = (_e = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _e !== void 0 ? _e : (_f = this._options) === null || _f === void 0 ? void 0 : _f.timeoutInSeconds) !== null && _g !== void 0 ? _g : 60) * 1000,
@@ -239,7 +248,11 @@ class WorkflowsClient {
                 url: core.url.join((_d = (_c = (yield core.Supplier.get(this._options.baseUrl))) !== null && _c !== void 0 ? _c : (yield core.Supplier.get(this._options.environment))) !== null && _d !== void 0 ? _d : environments.phenomlEnvironment.Default, `workflows/${core.url.encodePathParam(id)}`),
                 method: "GET",
                 headers: _headers,
-                queryParameters: Object.assign(Object.assign({}, _queryParams), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams),
+                queryString: core.url
+                    .queryBuilder()
+                    .addMany(_queryParams)
+                    .mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams)
+                    .build(),
                 timeoutMs: ((_g = (_e = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _e !== void 0 ? _e : (_f = this._options) === null || _f === void 0 ? void 0 : _f.timeoutInSeconds) !== null && _g !== void 0 ? _g : 60) * 1000,
                 maxRetries: (_h = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _h !== void 0 ? _h : (_j = this._options) === null || _j === void 0 ? void 0 : _j.maxRetries,
                 abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
@@ -289,12 +302,13 @@ class WorkflowsClient {
      * @example
      *     await client.workflows.update("id", {
      *         verbose: true,
-     *         name: "Updated Patient Data Mapping Workflow",
-     *         workflow_instructions: "Given diagnosis data, find the patient and create condition record",
+     *         name: "Patient Data Mapping Workflow (v2)",
+     *         workflow_instructions: "Given diagnosis data, find the patient and create a condition record linked to their encounter",
      *         sample_data: {
-     *             "patient_last_name": "Smith",
-     *             "patient_first_name": "John",
-     *             "diagnosis_code": "E11"
+     *             "patient_last_name": "Rippin",
+     *             "patient_first_name": "Clay",
+     *             "diagnosis_code": "I10",
+     *             "encounter_date": "2024-01-15"
      *         },
      *         fhir_provider_id: "550e8400-e29b-41d4-a716-446655440000"
      *     })
@@ -316,7 +330,11 @@ class WorkflowsClient {
                 method: "PUT",
                 headers: _headers,
                 contentType: "application/json",
-                queryParameters: Object.assign(Object.assign({}, _queryParams), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams),
+                queryString: core.url
+                    .queryBuilder()
+                    .addMany(_queryParams)
+                    .mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams)
+                    .build(),
                 requestType: "json",
                 body: _body,
                 timeoutMs: ((_g = (_e = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _e !== void 0 ? _e : (_f = this._options) === null || _f === void 0 ? void 0 : _f.timeoutInSeconds) !== null && _g !== void 0 ? _g : 60) * 1000,
@@ -380,7 +398,7 @@ class WorkflowsClient {
                 url: core.url.join((_d = (_c = (yield core.Supplier.get(this._options.baseUrl))) !== null && _c !== void 0 ? _c : (yield core.Supplier.get(this._options.environment))) !== null && _d !== void 0 ? _d : environments.phenomlEnvironment.Default, `workflows/${core.url.encodePathParam(id)}`),
                 method: "DELETE",
                 headers: _headers,
-                queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
+                queryString: core.url.queryBuilder().mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams).build(),
                 timeoutMs: ((_g = (_e = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _e !== void 0 ? _e : (_f = this._options) === null || _f === void 0 ? void 0 : _f.timeoutInSeconds) !== null && _g !== void 0 ? _g : 60) * 1000,
                 maxRetries: (_h = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _h !== void 0 ? _h : (_j = this._options) === null || _j === void 0 ? void 0 : _j.maxRetries,
                 abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
@@ -428,14 +446,24 @@ class WorkflowsClient {
      * @throws {@link phenoml.workflows.InternalServerError}
      *
      * @example
-     *     await client.workflows.execute("id", {
+     *     await client.workflows.execute("7a8b9c0d-1234-5678-abcd-ef9876543210", {
      *         input_data: {
      *             "patient_last_name": "Johnson",
      *             "patient_first_name": "Mary",
      *             "diagnosis_code": "M79.3",
-     *             "encounter_date": "2024-01-15"
+     *             "encounter_date": "2024-03-20"
      *         }
      *     })
+     *
+     * @example
+     *     await client.workflows.execute("7a8b9c0d-1234-5678-abcd-ef9876543210", {
+     *         input_data: {
+     *             "patient_last_name": "Johnson",
+     *             "patient_first_name": "Mary",
+     *             "diagnosis_code": "M79.3"
+     *         },
+     *         preview: true
+     *     })
      */
     execute(id, request, requestOptions) {
         return core.HttpResponsePromise.fromPromise(this.__execute(id, request, requestOptions));
@@ -450,7 +478,7 @@ class WorkflowsClient {
                 method: "POST",
                 headers: _headers,
                 contentType: "application/json",
-                queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
+                queryString: core.url.queryBuilder().mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams).build(),
                 requestType: "json",
                 body: request,
                 timeoutMs: ((_g = (_e = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _e !== void 0 ? _e : (_f = this._options) === null || _f === void 0 ? void 0 : _f.timeoutInSeconds) !== null && _g !== void 0 ? _g : 60) * 1000,

package/dist/cjs/api/resources/workflows/client/requests/CreateWorkflowRequest.d.ts

@@ -3,11 +3,12 @@
  *     {
  *         verbose: true,
  *         name: "Patient Data Mapping Workflow",
- *         workflow_instructions: "Given diagnosis data, find the patient and create condition record",
+ *         workflow_instructions: "Given diagnosis data, find the patient and create a condition record linked to their encounter",
  *         sample_data: {
  *             "patient_last_name": "Rippin",
  *             "patient_first_name": "Clay",
- *             "diagnosis_code": "I10"
+ *             "diagnosis_code": "I10",
+ *             "encounter_date": "2024-01-15"
  *         },
  *         fhir_provider_id: "550e8400-e29b-41d4-a716-446655440000"
  *     }

package/dist/cjs/api/resources/workflows/client/requests/ExecuteWorkflowRequest.d.ts

@@ -5,9 +5,19 @@
  *             "patient_last_name": "Johnson",
  *             "patient_first_name": "Mary",
  *             "diagnosis_code": "M79.3",
- *             "encounter_date": "2024-01-15"
+ *             "encounter_date": "2024-03-20"
  *         }
  *     }
+ *
+ * @example
+ *     {
+ *         input_data: {
+ *             "patient_last_name": "Johnson",
+ *             "patient_first_name": "Mary",
+ *             "diagnosis_code": "M79.3"
+ *         },
+ *         preview: true
+ *     }
  */
 export interface ExecuteWorkflowRequest {
     /** Input data for workflow execution */

package/dist/cjs/api/resources/workflows/client/requests/UpdateWorkflowRequest.d.ts

@@ -2,12 +2,13 @@
  * @example
  *     {
  *         verbose: true,
- *         name: "Updated Patient Data Mapping Workflow",
- *         workflow_instructions: "Given diagnosis data, find the patient and create condition record",
+ *         name: "Patient Data Mapping Workflow (v2)",
+ *         workflow_instructions: "Given diagnosis data, find the patient and create a condition record linked to their encounter",
  *         sample_data: {
- *             "patient_last_name": "Smith",
- *             "patient_first_name": "John",
- *             "diagnosis_code": "E11"
+ *             "patient_last_name": "Rippin",
+ *             "patient_first_name": "Clay",
+ *             "diagnosis_code": "I10",
+ *             "encounter_date": "2024-01-15"
  *         },
  *         fhir_provider_id: "550e8400-e29b-41d4-a716-446655440000"
  *     }

package/dist/cjs/core/auth/AuthProvider.d.ts

@@ -5,3 +5,4 @@ export interface AuthProvider {
         endpointMetadata?: EndpointMetadata;
     }): Promise<AuthRequest>;
 }
+export declare function isAuthProvider(value: unknown): value is AuthProvider;

package/dist/cjs/core/auth/AuthProvider.js

@@ -1,2 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAuthProvider = isAuthProvider;
+function isAuthProvider(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "getAuthRequest" in value &&
+        typeof value.getAuthRequest === "function");
+}

package/dist/cjs/core/auth/BasicAuth.d.ts

@@ -1,6 +1,6 @@
 export interface BasicAuth {
-    username: string;
-    password: string;
+    username?: string;
+    password?: string;
 }
 export declare const BasicAuth: {
     toAuthorizationHeader: (basicAuth: BasicAuth | undefined) => string | undefined;

package/dist/cjs/core/auth/BasicAuth.js

@@ -5,10 +5,16 @@ const base64_js_1 = require("../base64.js");
 const BASIC_AUTH_HEADER_PREFIX = /^Basic /i;
 exports.BasicAuth = {
     toAuthorizationHeader: (basicAuth) => {
+        var _a, _b;
         if (basicAuth == null) {
             return undefined;
         }
-        const token = (0, base64_js_1.base64Encode)(`${basicAuth.username}:${basicAuth.password}`);
+        const username = (_a = basicAuth.username) !== null && _a !== void 0 ? _a : "";
+        const password = (_b = basicAuth.password) !== null && _b !== void 0 ? _b : "";
+        if (username === "" && password === "") {
+            return undefined;
+        }
+        const token = (0, base64_js_1.base64Encode)(`${username}:${password}`);
         return `Basic ${token}`;
     },
     fromAuthorizationHeader: (header) => {

package/dist/cjs/core/auth/index.d.ts

@@ -1,4 +1,4 @@
-export type { AuthProvider } from "./AuthProvider.js";
+export { type AuthProvider, isAuthProvider } from "./AuthProvider.js";
 export type { AuthRequest } from "./AuthRequest.js";
 export { BasicAuth } from "./BasicAuth.js";
 export { BearerToken } from "./BearerToken.js";

package/dist/cjs/core/auth/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoOpAuthProvider = exports.BearerToken = exports.BasicAuth = void 0;
+exports.NoOpAuthProvider = exports.BearerToken = exports.BasicAuth = exports.isAuthProvider = void 0;
+var AuthProvider_js_1 = require("./AuthProvider.js");
+Object.defineProperty(exports, "isAuthProvider", { enumerable: true, get: function () { return AuthProvider_js_1.isAuthProvider; } });
 var BasicAuth_js_1 = require("./BasicAuth.js");
 Object.defineProperty(exports, "BasicAuth", { enumerable: true, get: function () { return BasicAuth_js_1.BasicAuth; } });
 var BearerToken_js_1 = require("./BearerToken.js");

package/dist/cjs/core/fetcher/Fetcher.d.ts

@@ -8,7 +8,13 @@ export declare namespace Fetcher {
         method: string;
         contentType?: string;
         headers?: Record<string, unknown>;
+        /**
+         * @deprecated Prefer `queryString` (produced by `core.url.queryBuilder()`).
+         * Retained for backwards compatibility with custom fetchers and callers that
+         * still construct request args with a query-parameter object.
+         */
         queryParameters?: Record<string, unknown>;
+        queryString?: string;
         body?: unknown;
         timeoutMs?: number;
         maxRetries?: number;
@@ -38,10 +44,12 @@ export declare namespace Fetcher {
     }
     interface TimeoutError {
         reason: "timeout";
+        cause?: unknown;
     }
     interface UnknownError {
         reason: "unknown";
         errorMessage: string;
+        cause?: unknown;
     }
 }
 export declare function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIResponse<R, Fetcher.Error>>;

package/dist/cjs/core/fetcher/Fetcher.js

@@ -75,16 +75,11 @@ const SENSITIVE_QUERY_PARAMS = new Set([
 ]);
 function redactQueryParameters(queryParameters) {
     if (queryParameters == null) {
-        return queryParameters;
+        return undefined;
     }
     const redacted = {};
     for (const [key, value] of Object.entries(queryParameters)) {
-        if (SENSITIVE_QUERY_PARAMS.has(key.toLowerCase())) {
-            redacted[key] = "[REDACTED]";
-        }
-        else {
-            redacted[key] = value;
-        }
+        redacted[key] = SENSITIVE_QUERY_PARAMS.has(key.toLowerCase()) ? "[REDACTED]" : value;
     }
     return redacted;
 }
@@ -186,7 +181,13 @@ function getHeaders(args) {
 function fetcherImpl(args) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
-        const url = (0, createRequestUrl_js_1.createRequestUrl)(args.url, args.queryParameters);
+        let url = args.url;
+        if (args.queryString != null && args.queryString.length > 0) {
+            url = `${url}?${args.queryString}`;
+        }
+        else {
+            url = (0, createRequestUrl_js_1.createRequestUrl)(args.url, args.queryParameters);
+        }
         const requestBody = yield (0, getRequestBody_js_1.getRequestBody)({
             body: args.body,
             type: (_a = args.requestType) !== null && _a !== void 0 ? _a : "other",
@@ -261,6 +262,7 @@ function fetcherImpl(args) {
                     error: {
                         reason: "unknown",
                         errorMessage: "The user aborted a request",
+                        cause: error,
                     },
                     rawResponse: RawResponse_js_1.abortRawResponse,
                 };
@@ -278,6 +280,7 @@ function fetcherImpl(args) {
                     ok: false,
                     error: {
                         reason: "timeout",
+                        cause: error,
                     },
                     rawResponse: RawResponse_js_1.abortRawResponse,
                 };
@@ -296,6 +299,7 @@ function fetcherImpl(args) {
                     error: {
                         reason: "unknown",
                         errorMessage: error.message,
+                        cause: error,
                     },
                     rawResponse: RawResponse_js_1.unknownRawResponse,
                 };
@@ -313,6 +317,7 @@ function fetcherImpl(args) {
                 error: {
                     reason: "unknown",
                     errorMessage: (0, json_js_1.toJson)(error),
+                    cause: error,
                 },
                 rawResponse: RawResponse_js_1.unknownRawResponse,
             };

package/dist/cjs/core/fetcher/requestWithRetries.js

@@ -14,6 +14,9 @@ const INITIAL_RETRY_DELAY = 1000; // in milliseconds
 const MAX_RETRY_DELAY = 60000; // in milliseconds
 const DEFAULT_MAX_RETRIES = 2;
 const JITTER_FACTOR = 0.2; // 20% random jitter
+function isRetryableStatusCode(statusCode) {
+    return [408, 429].includes(statusCode) || statusCode >= 500;
+}
 function addPositiveJitter(delay) {
     const jitterMultiplier = 1 + Math.random() * JITTER_FACTOR;
     return delay * jitterMultiplier;
@@ -53,7 +56,7 @@ function requestWithRetries(requestFn_1) {
     return __awaiter(this, arguments, void 0, function* (requestFn, maxRetries = DEFAULT_MAX_RETRIES) {
         let response = yield requestFn();
         for (let i = 0; i < maxRetries; ++i) {
-            if ([408, 429].includes(response.status) || response.status >= 500) {
+            if (isRetryableStatusCode(response.status)) {
                 const delay = getRetryDelayFromHeaders(response, i);
                 yield new Promise((resolve) => setTimeout(resolve, delay));
                 response = yield requestFn();

package/dist/cjs/core/url/QueryStringBuilder.d.ts

@@ -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/cjs/core/url/QueryStringBuilder.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryBuilder = queryBuilder;
+const qs_js_1 = require("./qs.js");
+/**
+ * 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();
+ */
+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 = (0, qs_js_1.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 = (0, qs_js_1.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/cjs/core/url/index.d.ts

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

package/dist/cjs/core/url/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toQueryString = exports.join = exports.encodePathParam = void 0;
+exports.toQueryString = exports.queryBuilder = exports.join = exports.encodePathParam = void 0;
 var encodePathParam_js_1 = require("./encodePathParam.js");
 Object.defineProperty(exports, "encodePathParam", { enumerable: true, get: function () { return encodePathParam_js_1.encodePathParam; } });
 var join_js_1 = require("./join.js");
 Object.defineProperty(exports, "join", { enumerable: true, get: function () { return join_js_1.join; } });
+var QueryStringBuilder_js_1 = require("./QueryStringBuilder.js");
+Object.defineProperty(exports, "queryBuilder", { enumerable: true, get: function () { return QueryStringBuilder_js_1.queryBuilder; } });
 var qs_js_1 = require("./qs.js");
 Object.defineProperty(exports, "toQueryString", { enumerable: true, get: function () { return qs_js_1.toQueryString; } });

package/dist/cjs/core/url/qs.d.ts

@@ -1,5 +1,6 @@
+type ArrayFormat = "indices" | "repeat" | "comma";
 interface QueryStringOptions {
-    arrayFormat?: "indices" | "repeat";
+    arrayFormat?: ArrayFormat;
     encode?: boolean;
 }
 export declare function toQueryString(obj: unknown, options?: QueryStringOptions): string;

package/dist/cjs/core/url/qs.js

@@ -26,19 +26,31 @@ function stringifyObject(obj, prefix = "", options) {
             if (value.length === 0) {
                 continue;
             }
-            for (let i = 0; i < value.length; i++) {
-                const item = value[i];
-                if (item === undefined) {
-                    continue;
+            const effectiveFormat = options.arrayFormat;
+            if (effectiveFormat === "comma") {
+                const encodedKey = options.encode ? encodeURIComponent(fullKey) : fullKey;
+                const encodedValues = value
+                    .filter((item) => item !== undefined && item !== null)
+                    .map((item) => encodeValue(item, options.encode));
+                if (encodedValues.length > 0) {
+                    parts.push(`${encodedKey}=${encodedValues.join(",")}`);
                 }
-                if (typeof item === "object" && !Array.isArray(item) && item !== null) {
-                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
-                    parts.push(...stringifyObject(item, arrayKey, options));
-                }
-                else {
-                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
-                    const encodedKey = options.encode ? encodeURIComponent(arrayKey) : arrayKey;
-                    parts.push(`${encodedKey}=${encodeValue(item, options.encode)}`);
+            }
+            else {
+                for (let i = 0; i < value.length; i++) {
+                    const item = value[i];
+                    if (item === undefined) {
+                        continue;
+                    }
+                    if (typeof item === "object" && !Array.isArray(item) && item !== null) {
+                        const arrayKey = effectiveFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                        parts.push(...stringifyObject(item, arrayKey, options));
+                    }
+                    else {
+                        const arrayKey = effectiveFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                        const encodedKey = options.encode ? encodeURIComponent(arrayKey) : arrayKey;
+                        parts.push(`${encodedKey}=${encodeValue(item, options.encode)}`);
+                    }
                 }
             }
         }