@wirebench/engine 2.1.1

package/dist/rest/response.js

@@ -0,0 +1,221 @@
+/**
+ * Making sense of what came back: what kind of document it is, how to read it as text, how to show
+ * it formatted, and what cookies it set.
+ *
+ * Everything here is pure and defensive. A response is whatever the server felt like sending — a
+ * JSON body labelled `text/plain`, a charset Node has never heard of, HTML where an API was
+ * promised, a `Set-Cookie` with an attribute in the wrong order — and none of that may throw,
+ * because the user still has to be able to look at it.
+ */
+import { decodeBody } from '../soap/charset.js';
+import { mediaTypeOf } from '../soap/mime/multipart.js';
+import { formatXml } from '../xml/pretty.js';
+/**
+ * The language of a response body.
+ *
+ * The declared `Content-Type` is believed first, but only so far: `text/plain` and
+ * `application/octet-stream` are what servers send when they have not thought about it, so a body
+ * that begins like JSON or XML is treated as such. A structured suffix (`+json`, `+xml`) counts as
+ * its base type, which is what `application/problem+json` and every SOAP-ish REST API rely on.
+ */
+export function detectLanguage(contentType, bytes) {
+    const media = contentType === undefined ? '' : mediaTypeOf(contentType).toLowerCase();
+    if (media.startsWith('image/')) {
+        return 'image';
+    }
+    if (media === 'application/json' || media.endsWith('+json')) {
+        return 'json';
+    }
+    if (media === 'text/xml' || media === 'application/xml' || media.endsWith('+xml')) {
+        return 'xml';
+    }
+    if (media === 'text/html' || media === 'application/xhtml+xml') {
+        return 'html';
+    }
+    if (media === 'application/javascript' || media === 'text/javascript') {
+        return 'javascript';
+    }
+    const sniffed = sniff(bytes);
+    if (sniffed !== undefined) {
+        return sniffed;
+    }
+    if (media.startsWith('text/')) {
+        return 'text';
+    }
+    return media === '' || media === 'application/octet-stream' ? 'binary' : 'text';
+}
+/**
+ * The first non-whitespace bytes, as a short ASCII string, for sniffing.
+ *
+ * A UTF-8 byte-order mark is skipped at the byte level: read as characters it would be three
+ * Latin-1 letters, and a BOM-prefixed JSON body would then sniff as text.
+ */
+function head(bytes, length = 512) {
+    const start = bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf ? 3 : 0;
+    const slice = bytes.subarray(start, start + length);
+    let text = '';
+    for (const byte of slice) {
+        text += String.fromCharCode(byte);
+    }
+    return text.trimStart();
+}
+/** What the first bytes look like, when they look like anything in particular. */
+function sniff(bytes) {
+    const start = head(bytes);
+    if (start === '') {
+        return undefined;
+    }
+    if (start.startsWith('{') || start.startsWith('[')) {
+        return 'json';
+    }
+    if (/^<!doctype html/i.test(start) || /^<html[\s>]/i.test(start)) {
+        return 'html';
+    }
+    if (start.startsWith('<?xml') || /^<[A-Za-z_]/.test(start)) {
+        return 'xml';
+    }
+    return undefined;
+}
+/**
+ * Decodes a body to text per the charset in its `Content-Type`, defaulting to UTF-8.
+ *
+ * Never throws and never returns nothing: an unsupported label falls back to UTF-8 with a note,
+ * and invalid bytes become replacement characters, because a body the user cannot read at all is
+ * worse than one they can read imperfectly.
+ */
+export function decodeResponseText(bytes, contentType) {
+    const { text, problem } = decodeBody(bytes, contentType);
+    const withoutBom = text.replace(/^/, '');
+    return problem === undefined ? { text: withoutBom } : { text: withoutBom, problem: problem.message };
+}
+/**
+ * Formats a body for reading: JSON re-indented, XML through the engine's own pretty printer, HTML
+ * given one tag per line.
+ *
+ * A malformed document is returned unchanged with a problem rather than repaired or rejected — the
+ * broken body *is* the interesting thing when an API misbehaves, and hiding it would hide the bug.
+ */
+export function prettyBody(text, language, indent = 2) {
+    if (language === 'json') {
+        try {
+            const formatted = JSON.stringify(JSON.parse(text), null, indent);
+            return { text: formatted, changed: formatted !== text };
+        }
+        catch (error) {
+            return { text, changed: false, problem: error instanceof Error ? error.message : 'Invalid JSON' };
+        }
+    }
+    if (language === 'xml') {
+        const result = formatXml(text, { indent: ' '.repeat(indent) });
+        return result.problem === undefined
+            ? { text: result.text, changed: result.changed }
+            : { text: result.text, changed: result.changed, problem: result.problem };
+    }
+    if (language === 'html') {
+        const formatted = formatHtml(text, indent);
+        return { text: formatted, changed: formatted !== text };
+    }
+    return { text, changed: false };
+}
+/**
+ * Indents HTML by tag depth.
+ *
+ * Deliberately not a parser: HTML's void elements, optional end tags and inline content make a
+ * faithful formatter a project of its own, and this only has to make a response readable. Text
+ * runs are kept on the line of the tag that opened them.
+ */
+function formatHtml(text, indent) {
+    const tokens = text
+        .replace(/\r\n?/g, '\n')
+        .split(/(<[^>]*>)/)
+        .filter((token) => token.trim() !== '');
+    const pad = ' '.repeat(indent);
+    const lines = [];
+    let depth = 0;
+    for (const token of tokens) {
+        const isTag = token.startsWith('<');
+        const isClose = token.startsWith('</');
+        const selfCloses = /\/>$/.test(token) || /^<(?:area|base|br|col|embed|hr|img|input|link|meta|source|track|wbr|!)/i.test(token);
+        if (isTag && isClose) {
+            depth = Math.max(0, depth - 1);
+        }
+        lines.push(pad.repeat(depth) + (isTag ? token.trim() : token.trim()));
+        if (isTag && !isClose && !selfCloses) {
+            depth += 1;
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Parses every `Set-Cookie` header of a response (RFC 6265 §5.2).
+ *
+ * `rawHeaders` rather than the merged map, because several cookies arrive as several headers and
+ * joining them with `, ` — which is what merging does — makes them unparseable. A line that is not
+ * a cookie at all is kept as `malformed` instead of dropped: it is evidence about the server.
+ */
+export function parseSetCookie(rawHeaders) {
+    const cookies = [];
+    for (const [name, value] of rawHeaders) {
+        if (name.toLowerCase() !== 'set-cookie') {
+            continue;
+        }
+        cookies.push(parseOne(value));
+    }
+    return cookies;
+}
+function parseOne(header) {
+    const parts = header.split(';');
+    const pair = parts[0] ?? '';
+    const equals = pair.indexOf('=');
+    if (equals <= 0) {
+        return { name: header.trim(), value: '', malformed: true };
+    }
+    const cookie = {
+        name: pair.slice(0, equals).trim(),
+        value: unquote(pair.slice(equals + 1).trim()),
+    };
+    for (const attribute of parts.slice(1)) {
+        const split = attribute.indexOf('=');
+        const key = (split === -1 ? attribute : attribute.slice(0, split)).trim().toLowerCase();
+        const attributeValue = split === -1 ? '' : attribute.slice(split + 1).trim();
+        switch (key) {
+            case 'domain':
+                // A leading dot is legal and means the same as its absence (RFC 6265 §5.2.3).
+                cookie.domain = attributeValue.replace(/^\./, '').toLowerCase();
+                break;
+            case 'path':
+                cookie.path = attributeValue;
+                break;
+            case 'expires': {
+                const date = new Date(attributeValue);
+                cookie.expires = Number.isNaN(date.getTime()) ? attributeValue : date.toISOString();
+                break;
+            }
+            case 'max-age': {
+                const seconds = Number.parseInt(attributeValue, 10);
+                if (!Number.isNaN(seconds)) {
+                    cookie.maxAge = seconds;
+                }
+                break;
+            }
+            case 'secure':
+                cookie.secure = true;
+                break;
+            case 'httponly':
+                cookie.httpOnly = true;
+                break;
+            case 'samesite': {
+                const normalized = attributeValue.toLowerCase();
+                cookie.sameSite = normalized === 'strict' ? 'Strict' : normalized === 'none' ? 'None' : 'Lax';
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return cookie;
+}
+/** Strips one layer of double quotes from a cookie value, which some servers add. */
+function unquote(value) {
+    return value.length > 1 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+}

package/dist/rest/send.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Sending one REST request.
+ *
+ * Everything is already resolved by the time it gets here: the base URL (environment overrides
+ * applied), every `${…}` property expanded, credentials turned from `secretRef`s into values, TLS
+ * and proxy settled. This function composes the wire request, hands it to the one HTTP transport
+ * the SOAP path also uses, and decodes what came back — so the desktop app and the planned CLI
+ * runner send identically, and there is one implementation of redirects, timings and raw capture
+ * rather than two.
+ */
+import type { HttpExchange, HttpRequest, ProxyOptions, TlsOptions } from '../http/types.js';
+import type { AuthSummary, SendAuth } from '../types.js';
+import type { FileResolver } from './body.js';
+import type { KeyValueEntry, RestBody, RestMethod } from './model.js';
+import type { BodyLanguage, Cookie } from './response.js';
+/** The parts of a saved request a send reads, with every property already expanded. */
+export interface RestSendRequest {
+    readonly method: RestMethod;
+    readonly url: string;
+    readonly pathParams: readonly KeyValueEntry[];
+    readonly query: readonly KeyValueEntry[];
+    readonly headers: readonly KeyValueEntry[];
+    readonly body: RestBody;
+}
+/** Transport settings for one send, every value already resolved from request, API and preference. */
+export interface RestSendSettings {
+    readonly timeoutMs: number;
+    readonly followRedirects: boolean;
+    readonly maxRedirects?: number;
+    readonly keepBodyOnRedirect?: boolean;
+    readonly encodeUrl?: boolean;
+    readonly maxSizeBytes?: number;
+    readonly localAddress?: string;
+    readonly allowH2?: boolean;
+    readonly decompress?: boolean;
+    /** Charset for a raw or form body, and for the `Content-Type` that declares it. */
+    readonly charset?: string;
+}
+/** Everything {@link sendRest} needs. */
+export interface RestSendInput {
+    /** The API's effective base URL, already expanded. Empty when the request's URL is absolute. */
+    readonly baseUrl: string;
+    readonly request: RestSendRequest;
+    readonly settings: RestSendSettings;
+    /**
+     * Headers the host adds on the request's behalf — `User-Agent`, `Accept-Encoding`, `Connection`,
+     * a default `Accept` — which a header the request sets itself overrides.
+     */
+    readonly defaultHeaders?: Readonly<Record<string, string>>;
+    /** Credentials, already resolved to values. */
+    readonly auth?: SendAuth;
+    /** Cookies to send back, already matched against the URL (`rest/cookies.ts`). */
+    readonly cookies?: readonly Cookie[];
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    /** How a multipart file part or a binary body is read. */
+    readonly resolveFile?: FileResolver;
+    /** Fixed multipart boundary; tests inject it. */
+    readonly boundary?: string;
+    readonly signal?: AbortSignal;
+}
+/** One REST exchange: everything the transport captured, plus what the body turned out to be. */
+export interface RestExchange extends HttpExchange {
+    /** The response body decoded to text; empty for a body with no text form. */
+    readonly text: string;
+    readonly language: BodyLanguage;
+    /** Set when the declared charset could not be honoured and UTF-8 was used instead. */
+    readonly decodeNote?: string;
+    readonly cookies: readonly Cookie[];
+    /** True when a redirect turned the request into a `GET`, which the HTTP log calls out. */
+    readonly methodChanged: boolean;
+    /** What authentication did, when credentials needed a round trip of their own. */
+    readonly auth?: AuthSummary;
+    /**
+     * Total time across every leg of the send, including a Basic challenge retry or an NTLM
+     * handshake — `timings.totalMs` describes the final leg alone.
+     */
+    readonly durationMs: number;
+}
+/**
+ * Sends one REST request and decodes the response.
+ *
+ * Order of work: credentials are applied first (an API key in the query has to be part of the URL),
+ * then the URL is composed, then the body encoded, then headers merged. A URL that is still
+ * incomplete — an unfilled `{param}`, an unexpanded property, no host at all — is refused here
+ * rather than sent: those are the problems the preflight surfaces, and sending anyway would put a
+ * literal `{id}` on someone's wire.
+ *
+ * HTTP-level failures (timeout, DNS, TLS, too many redirects) propagate as `HttpError`. A non-2xx
+ * status is not a failure: it is a response, and the caller inspects it.
+ *
+ * @throws WirebenchError `rest-url-incomplete` when the URL could not be completed
+ */
+export declare function sendRest(input: RestSendInput): Promise<RestExchange>;
+/**
+ * Turns a finished HTTP exchange into a REST one: body decoded to text, language detected, cookies
+ * parsed, and a note when a redirect changed the method.
+ *
+ * Split out so a response replayed from history or from the exchange cache is presented exactly as
+ * a live one.
+ */
+export declare function decodeRestResponse(exchange: HttpExchange, sentMethod: HttpRequest['method']): RestExchange;

package/dist/rest/send.js

@@ -0,0 +1,148 @@
+/**
+ * Sending one REST request.
+ *
+ * Everything is already resolved by the time it gets here: the base URL (environment overrides
+ * applied), every `${…}` property expanded, credentials turned from `secretRef`s into values, TLS
+ * and proxy settled. This function composes the wire request, hands it to the one HTTP transport
+ * the SOAP path also uses, and decodes what came back — so the desktop app and the planned CLI
+ * runner send identically, and there is one implementation of redirects, timings and raw capture
+ * rather than two.
+ */
+import { WirebenchError } from '../errors.js';
+import { sendWithAuth } from '../http/auth/apply.js';
+import { applyAuth } from './auth.js';
+import { encodeRestBody } from './body.js';
+import { cookieHeader } from './cookies.js';
+import { decodeResponseText, detectLanguage, parseSetCookie } from './response.js';
+import { composeUrl } from './url.js';
+/**
+ * Merges the header sources in precedence order, lowest first: host defaults, then what the body
+ * and credentials imply, then the request's own typed headers.
+ *
+ * The request always wins — a user who typed a `Content-Type` meant it, even when the body kind
+ * implies another — which is the same rule the SOAP path applies to its computed headers.
+ */
+function mergeRequestHeaders(input) {
+    const merged = new Map();
+    const put = (name, value) => {
+        merged.set(name.toLowerCase(), [name, value]);
+    };
+    for (const [name, value] of Object.entries(input.defaults)) {
+        put(name, value);
+    }
+    for (const [name, value] of Object.entries(input.computed)) {
+        put(name, value);
+    }
+    // A repeated header name in the request's own table is joined with `, `, which is what RFC 9110
+    // §5.3 says a recipient must treat as equivalent to two headers; undici takes one value per name.
+    const typedSeen = new Set();
+    for (const header of input.typed) {
+        if (!header.enabled || header.name === '') {
+            continue;
+        }
+        const key = header.name.toLowerCase();
+        const previous = typedSeen.has(key) ? merged.get(key)?.[1] : undefined;
+        put(header.name, previous === undefined ? header.value : `${previous}, ${header.value}`);
+        typedSeen.add(key);
+    }
+    return Object.fromEntries([...merged.values()]);
+}
+/** The methods this transport will send. A custom method is passed through as given. */
+function methodFor(method) {
+    return method.toUpperCase();
+}
+/**
+ * Sends one REST request and decodes the response.
+ *
+ * Order of work: credentials are applied first (an API key in the query has to be part of the URL),
+ * then the URL is composed, then the body encoded, then headers merged. A URL that is still
+ * incomplete — an unfilled `{param}`, an unexpanded property, no host at all — is refused here
+ * rather than sent: those are the problems the preflight surfaces, and sending anyway would put a
+ * literal `{id}` on someone's wire.
+ *
+ * HTTP-level failures (timeout, DNS, TLS, too many redirects) propagate as `HttpError`. A non-2xx
+ * status is not a failure: it is a response, and the caller inspects it.
+ *
+ * @throws WirebenchError `rest-url-incomplete` when the URL could not be completed
+ */
+export async function sendRest(input) {
+    const { request, settings } = input;
+    const applied = applyAuth(input.auth);
+    const composed = composeUrl(input.baseUrl, request.url, request.pathParams, [...request.query, ...applied.query], {
+        encode: settings.encodeUrl ?? true,
+    });
+    if (composed.problems.length > 0) {
+        throw urlIncomplete(composed.problems, composed.url);
+    }
+    const encoded = await encodeRestBody(request.body, {
+        ...(input.resolveFile !== undefined ? { resolveFile: input.resolveFile } : {}),
+        ...(settings.charset !== undefined ? { charset: settings.charset } : {}),
+        ...(input.boundary !== undefined ? { boundary: input.boundary } : {}),
+        ...(input.signal !== undefined ? { signal: input.signal } : {}),
+    });
+    const cookies = cookieHeader(input.cookies ?? []);
+    const headers = mergeRequestHeaders({
+        defaults: input.defaultHeaders ?? {},
+        computed: {
+            ...applied.headers,
+            ...(encoded.contentType !== undefined ? { 'Content-Type': encoded.contentType } : {}),
+            ...(cookies !== undefined ? { Cookie: cookies } : {}),
+        },
+        typed: request.headers,
+    });
+    const httpRequest = {
+        url: composed.url,
+        method: methodFor(request.method),
+        headers,
+        ...(encoded.bytes !== undefined ? { body: encoded.bytes } : {}),
+        timeoutMs: settings.timeoutMs,
+        followRedirects: settings.followRedirects,
+        ...(settings.maxRedirects !== undefined ? { maxRedirects: settings.maxRedirects } : {}),
+        ...(settings.keepBodyOnRedirect === true ? { preserveMethodOnRedirect: true } : {}),
+        ...(settings.maxSizeBytes !== undefined ? { maxSizeBytes: settings.maxSizeBytes } : {}),
+        ...(settings.localAddress !== undefined ? { localAddress: settings.localAddress } : {}),
+        ...(settings.allowH2 === true ? { allowH2: true } : {}),
+        ...(settings.decompress !== undefined ? { decompress: settings.decompress } : {}),
+        ...(input.tls !== undefined ? { tls: input.tls } : {}),
+        ...(input.proxy !== undefined ? { proxy: input.proxy } : {}),
+        ...(input.signal !== undefined ? { signal: input.signal } : {}),
+    };
+    // Basic and NTLM may need a round trip of their own; every other scheme is already in `headers`.
+    const authenticated = await sendWithAuth(httpRequest, applied.transportAuth);
+    return {
+        ...decodeRestResponse(authenticated.http, methodFor(request.method)),
+        ...(authenticated.auth !== undefined ? { auth: authenticated.auth } : {}),
+        durationMs: authenticated.durationMs,
+    };
+}
+/** The error a URL that cannot be completed raises, naming every problem at once. */
+function urlIncomplete(problems, url) {
+    const missing = problems.filter((problem) => problem.code === 'missing-path-param').map((problem) => problem.name);
+    const message = missing.length > 0
+        ? `The URL still needs a value for ${missing.map((name) => `{${name}}`).join(', ')}`
+        : `The URL is not a complete address: ${url}`;
+    return new WirebenchError('rest-url-incomplete', message, { details: { url, problems } });
+}
+/**
+ * Turns a finished HTTP exchange into a REST one: body decoded to text, language detected, cookies
+ * parsed, and a note when a redirect changed the method.
+ *
+ * Split out so a response replayed from history or from the exchange cache is presented exactly as
+ * a live one.
+ */
+export function decodeRestResponse(exchange, sentMethod) {
+    const contentType = exchange.headers['content-type'];
+    const language = detectLanguage(contentType, exchange.body);
+    const decoded = language === 'image' || language === 'binary' ? { text: '' } : decodeResponseText(exchange.body, contentType);
+    const methodChanged = sentMethod !== 'GET' &&
+        exchange.redirects.some((hop) => hop.status === 303 || ((hop.status === 301 || hop.status === 302) && sentMethod === 'POST'));
+    return {
+        ...exchange,
+        durationMs: exchange.timings.totalMs,
+        text: decoded.text,
+        language,
+        ...(decoded.problem !== undefined ? { decodeNote: decoded.problem } : {}),
+        cookies: parseSetCookie(exchange.rawHeaders),
+        methodChanged,
+    };
+}

package/dist/rest/url.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Building the URL a REST request actually sends, and taking one apart again.
+ *
+ * Two jobs, both pure. {@link composeUrl} joins the API's base URL with the request's own URL,
+ * fills its `{name}` path parameters and appends its enabled query rows, percent-encoding to
+ * RFC 3986. {@link splitQuery} and {@link joinQuery} are the other direction: the editor keeps one
+ * URL field and one query table, and they have to be the same thing seen twice, so a value typed
+ * into either lands in the other without drifting.
+ *
+ * Nothing here throws for bad input. A missing path parameter or a property reference nothing
+ * expanded is a {@link UrlProblem} the caller surfaces before the send — a URL that is merely
+ * unfinished is the normal state of a request being written.
+ */
+import type { KeyValueEntry } from './model.js';
+/** Something wrong with a URL that must stop the send rather than reach the wire. */
+export interface UrlProblem {
+    readonly code: 
+    /** A `{name}` in the URL with no value in the request's path-parameter table. */
+    'missing-path-param'
+    /** A `${…}` property reference the caller did not expand. */
+     | 'unexpanded-property'
+    /** Neither the request's URL nor the base URL gives a scheme and host. */
+     | 'no-host';
+    /** The parameter or reference the problem is about. */
+    readonly name: string;
+}
+/** The result of {@link composeUrl}: the URL to send, and anything that must stop the send. */
+export interface ComposedUrl {
+    readonly url: string;
+    readonly problems: readonly UrlProblem[];
+}
+/** Options for {@link composeUrl}. */
+export interface ComposeUrlOptions {
+    /**
+     * Percent-encode path-parameter and query values. On by default. Off sends them exactly as
+     * typed, which is what a request that has to pass a pre-encoded or deliberately odd value needs.
+     */
+    readonly encode?: boolean;
+}
+/**
+ * Percent-encodes one value, leaving an existing valid `%XX` escape alone.
+ *
+ * The double-encoding guard is the whole point: a user who pastes `a%20b` means one space, and
+ * turning it into `a%2520b` would silently change the request. A lone `%` that is not a valid
+ * escape *is* encoded, because on the wire it has to be.
+ */
+export declare function encodeValue(value: string, extraSafe?: string): string;
+/** Every `{name}` in `url`, in the order they appear, without duplicates. */
+export declare function parseUrlParams(url: string): string[];
+/**
+ * Drops every trailing `/` from `text`.
+ *
+ * A character walk rather than `replace(/\/+$/, '')`: that pattern is anchored at the end but not
+ * at the start, so the engine retries it at each of the string's positions and the whole trim costs
+ * O(n²) — 80k slashes took five seconds. Nothing here is attacker-supplied (it is the user's own
+ * base URL), so this is a sharp edge rather than a vulnerability, but linear is free.
+ */
+export declare function trimTrailingSlashes(text: string): string;
+/**
+ * Joins a base URL with a request's relative URL.
+ *
+ * The base's own path is kept (`https://h/api/v3` + `/pet` is `https://h/api/v3/pet`), because an
+ * API's base URL usually *is* a path prefix; exactly one `/` ends up between the two however many
+ * either side brought. An empty relative URL sends the base itself.
+ */
+export declare function joinBase(base: string, url: string): string;
+/** Splits `url` into its part before `?`/`#` and the query rows after it. */
+export declare function splitQuery(url: string): {
+    readonly path: string;
+    readonly query: KeyValueEntry[];
+};
+/**
+ * The inverse of {@link splitQuery}: puts enabled rows back onto `path` as its query string.
+ *
+ * Values are written exactly as given — this is the editor's URL field, not the wire — so
+ * `joinQuery(splitQuery(url))` returns `url` for any URL the editor could have produced.
+ */
+export declare function joinQuery(path: string, query: readonly KeyValueEntry[]): string;
+/**
+ * Builds the URL one send actually uses.
+ *
+ * Order of work: the request's URL wins over the base when it is absolute; `{name}` parameters are
+ * filled from the enabled rows of `pathParams`; the URL's own query string and the `query` table
+ * are concatenated, in that order, so a parameter typed into the field and one added in the table
+ * both survive; every value is encoded unless `encode` is off.
+ *
+ * @param base the API's effective base URL, already expanded
+ * @param url the request's URL, already expanded
+ * @param pathParams values for the URL's `{name}` placeholders
+ * @param query query rows to append
+ */
+export declare function composeUrl(base: string, url: string, pathParams?: readonly KeyValueEntry[], query?: readonly KeyValueEntry[], options?: ComposeUrlOptions): ComposedUrl;