@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/snapshot/golden-file.js

@@ -0,0 +1,173 @@
+/**
+ * Reads and writes a request's golden response: the `<slug>.golden.yaml` sidecar beside its request
+ * file (snapshot regression, #34). Shared by the desktop's Snapshot tab and the runner's `--baseline`
+ * (#36) and `--update-baseline` (#217), so the file is read and written one way. Uses `node:fs`, so it is exported from the main entry only —
+ * never from the `@wirebench/engine/snapshot` subpath, which the renderer imports.
+ *
+ * An ancestor folder swapped for a symlink between the containment check and the rename is not
+ * guarded: Node has no `openat` (#219).
+ */
+import { randomUUID } from 'node:crypto';
+import { constants, existsSync } from 'node:fs';
+import { lstat, open, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { Document, parse as parseYamlText } from 'yaml';
+import { z } from 'zod';
+import { requestFileLocation } from '../project/request-location.js';
+const goldenFileSchema = z.object({
+    contentType: z.string().optional(),
+    savedAt: z.string(),
+    ignore: z.array(z.string()),
+    body: z.string(),
+});
+const NONE = { status: 'none' };
+const NOT_A_FILE = { status: 'unreadable', reason: 'not-a-file' };
+const MALFORMED = { status: 'unreadable', reason: 'malformed' };
+/** Read-only, never through a link, never blocking on a FIFO; Windows defines neither extra flag. */
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+/** `path` with `realpath` resolved through whatever prefix of it exists, so a symlink cannot hide an escape. */
+async function realpathOfPrefix(path) {
+    const tail = [];
+    let current = path;
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            return path;
+        tail.unshift(basename(current));
+        current = parent;
+    }
+    try {
+        const real = await realpath(current);
+        return tail.length === 0 ? real : join(real, ...tail);
+    }
+    catch {
+        return path;
+    }
+}
+/** True when `candidate` is `root` or below it; both real paths. */
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/** Where `requestId`'s sidecar goes once containment and the request file are checked; `undefined` is "unsaved". */
+async function sidecarOf(projectDir, project, requestId) {
+    const location = requestFileLocation(project, requestId);
+    if (location === undefined)
+        return undefined;
+    const folder = join(projectDir, ...location.dir.split('/'));
+    const requestFile = join(folder, `${location.slug}.request.yaml`);
+    const [root, requestReal, folderReal] = await Promise.all([
+        realpathOfPrefix(projectDir),
+        realpathOfPrefix(requestFile),
+        realpathOfPrefix(folder),
+    ]);
+    if (!isInside(root, requestReal) || !isInside(root, folderReal) || !existsSync(requestFile))
+        return undefined;
+    const name = `${location.slug}.golden.yaml`;
+    return { file: join(folderReal, name), relative: location.dir === '' ? name : `${location.dir}/${name}` };
+}
+/**
+ * The golden saved for `requestId` in the project saved at `projectDir`. `none` when the request
+ * has no file location, its folder leaves the project, its `*.request.yaml` is not on disk, or no
+ * sidecar exists. The sidecar's own name is checked with `lstat`, never followed, and read through
+ * the one handle that was checked.
+ */
+export async function readGoldenFile(projectDir, project, requestId) {
+    const sidecar = await sidecarOf(projectDir, project, requestId);
+    if (sidecar === undefined)
+        return NONE;
+    const file = sidecar.file;
+    let checked;
+    try {
+        checked = await lstat(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return NONE;
+        throw error;
+    }
+    if (!checked.isFile())
+        return NOT_A_FILE;
+    // The path may change after the lstat: open it without following a link, then check the handle
+    // is the file lstat saw. Where O_NOFOLLOW is missing (Windows), a followed link fails that check.
+    let handle;
+    try {
+        handle = await open(file, OPEN_FLAGS);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return NONE;
+        if (code === 'ELOOP')
+            return NOT_A_FILE;
+        return MALFORMED;
+    }
+    let parsed;
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.dev !== checked.dev || opened.ino !== checked.ino)
+            return NOT_A_FILE;
+        parsed = goldenFileSchema.safeParse(parseYamlText(await handle.readFile('utf8')));
+    }
+    catch {
+        return MALFORMED;
+    }
+    finally {
+        await handle.close();
+    }
+    if (!parsed.success)
+        return MALFORMED;
+    const { contentType, savedAt, ignore, body } = parsed.data;
+    return {
+        status: 'present',
+        golden: { ...(contentType !== undefined ? { contentType } : {}), savedAt, ignore, body },
+    };
+}
+/**
+ * `golden` as sidecar text, keys sorted, the body a block scalar so a golden diffs well in git. A
+ * block scalar cannot hold every string — a whitespace-only body such as `"  \n"` reads back
+ * differently — so the text is parsed back, and a body that does not survive is double-quoted.
+ */
+function goldenText(golden) {
+    const doc = new Document({
+        ...(golden.contentType !== undefined ? { contentType: golden.contentType } : {}),
+        savedAt: golden.savedAt,
+        ignore: [...golden.ignore],
+        body: golden.body,
+    }, { sortMapEntries: true });
+    const body = doc.get('body', true);
+    body.type = 'BLOCK_LITERAL';
+    const text = doc.toString({ lineWidth: 0 });
+    if (parseYamlText(text).body === golden.body)
+        return text;
+    body.type = 'QUOTE_DOUBLE';
+    return doc.toString({ lineWidth: 0 });
+}
+/**
+ * Saves `golden` as `requestId`'s sidecar, atomically: a uniquely named temp file, then a rename
+ * over it. Refuses an unsaved request, and a sidecar path that holds a symlink, a folder or
+ * anything but a regular file (it is never followed). A failed write removes the temp file and throws.
+ */
+export async function writeGoldenFile(projectDir, project, requestId, golden) {
+    const sidecar = await sidecarOf(projectDir, project, requestId);
+    if (sidecar === undefined)
+        return { status: 'refused', reason: 'unsaved' };
+    try {
+        if (!(await lstat(sidecar.file)).isFile())
+            return { status: 'refused', reason: 'not-a-file' };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const temp = `${sidecar.file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, goldenText(golden), { encoding: 'utf8', flag: 'wx' });
+        await rename(temp, sidecar.file);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+    return { status: 'written', file: sidecar.relative };
+}

package/dist/snapshot/ignore.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Splits ignore-rule text into the rules a diff applies: one per line,
+ * trimmed, with blank lines and `#`-comment lines skipped. The sidecar's
+ * `ignore` array keeps comment lines as the user typed them, so the
+ * Snapshot tab runs the stored lines through this only when it diffs.
+ */
+export declare function parseIgnoreRules(text: string): string[];
+/**
+ * Tests whether `rule` covers `path`, either directly or because `path` is a
+ * descendant of the path the rule names. A rule's `*` segment matches any
+ * one segment; a leading `//` means "at any depth"; a segment with no
+ * `[n]` matches every index of that name; `/` alone matches every path.
+ */
+export declare function matchesIgnoreRule(path: string, rule: string): boolean;

package/dist/snapshot/ignore.js

@@ -0,0 +1,79 @@
+/**
+ * Splits ignore-rule text into the rules a diff applies: one per line,
+ * trimmed, with blank lines and `#`-comment lines skipped. The sidecar's
+ * `ignore` array keeps comment lines as the user typed them, so the
+ * Snapshot tab runs the stored lines through this only when it diffs.
+ */
+export function parseIgnoreRules(text) {
+    return text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('#'));
+}
+/** Splits a diff path or an ignore rule into its `/`-separated segments. */
+function segments(path) {
+    return path.split('/').filter((segment) => segment.length > 0);
+}
+/** The local name and, if present, the 1-based `[n]` index of one path segment. */
+function parseSegment(segment) {
+    const match = /^(.*)\[(\d+)]$/.exec(segment);
+    if (match === null) {
+        return { name: segment };
+    }
+    const index = match[2];
+    return index === undefined ? { name: match[1] ?? '' } : { name: match[1] ?? '', index };
+}
+/** Whether one path segment matches one rule segment. */
+function segmentMatches(pathSegment, ruleSegment) {
+    if (ruleSegment === '*') {
+        return true;
+    }
+    const rule = parseSegment(ruleSegment);
+    const path = parseSegment(pathSegment);
+    if (rule.name !== path.name) {
+        return false;
+    }
+    // "A segment without [n] matches any index" — only compare the index when the
+    // rule itself names one.
+    if (rule.index === undefined) {
+        return true;
+    }
+    return rule.index === path.index;
+}
+/**
+ * Tests whether `rule` covers `path`, either directly or because `path` is a
+ * descendant of the path the rule names. A rule's `*` segment matches any
+ * one segment; a leading `//` means "at any depth"; a segment with no
+ * `[n]` matches every index of that name; `/` alone matches every path.
+ */
+export function matchesIgnoreRule(path, rule) {
+    const anyDepth = rule.startsWith('//');
+    const ruleSegments = segments(rule);
+    const pathSegments = segments(path);
+    if (ruleSegments.length === 0) {
+        // `/` names the root, which every path descends from.
+        return rule.startsWith('/');
+    }
+    const matchesFrom = (start) => {
+        if (ruleSegments.length > pathSegments.length - start) {
+            return false;
+        }
+        for (let i = 0; i < ruleSegments.length; i += 1) {
+            const ruleSegment = ruleSegments[i];
+            const pathSegment = pathSegments[start + i];
+            if (ruleSegment === undefined || pathSegment === undefined || !segmentMatches(pathSegment, ruleSegment)) {
+                return false;
+            }
+        }
+        return true;
+    };
+    if (anyDepth) {
+        for (let start = 0; start <= pathSegments.length - ruleSegments.length; start += 1) {
+            if (matchesFrom(start)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    return matchesFrom(0);
+}

package/dist/snapshot/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@wirebench/engine/snapshot`: the pure semantic diff behind snapshot
+ * regression (issue #34). Compares a golden response body against a newly
+ * received one, structurally for JSON and XML and exactly for everything
+ * else, honouring per-request ignore rules.
+ */
+export { diffSnapshot, type SnapshotFormat, type SnapshotChange, type SnapshotDiff } from './diff.js';
+export { detectSnapshotFormat } from './format.js';
+export { matchesIgnoreRule, parseIgnoreRules } from './ignore.js';

package/dist/snapshot/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@wirebench/engine/snapshot`: the pure semantic diff behind snapshot
+ * regression (issue #34). Compares a golden response body against a newly
+ * received one, structurally for JSON and XML and exactly for everything
+ * else, honouring per-request ignore rules.
+ */
+export { diffSnapshot } from './diff.js';
+export { detectSnapshotFormat } from './format.js';
+export { matchesIgnoreRule, parseIgnoreRules } from './ignore.js';

package/dist/snapshot/json-diff.d.ts

@@ -0,0 +1,3 @@
+import type { SnapshotChange } from './diff.js';
+/** Semantically diffs two JSON documents, returning every change found. */
+export declare function diffJson(golden: unknown, actual: unknown): SnapshotChange[];

package/dist/snapshot/json-diff.js

@@ -0,0 +1,93 @@
+import { truncateValue } from './format.js';
+/** JSON Pointer escaping: `~` first, then `/` (RFC 6901 §4). */
+function escapeToken(token) {
+    return token.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+/**
+ * Builds a JSON Pointer from path segments (already unescaped). The root is
+ * `/` rather than RFC 6901's empty string, so every path a diff reports can
+ * be shown and saved as an ignore rule as it is.
+ */
+function pointer(segments) {
+    return segments.length === 0 ? '/' : segments.map((segment) => `/${escapeToken(segment)}`).join('');
+}
+function kindOf(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+}
+function display(value) {
+    return truncateValue(value === undefined ? 'undefined' : JSON.stringify(value));
+}
+/**
+ * Recursively compares two parsed JSON values and appends every difference
+ * found to `changes`, as a JSON Pointer path plus the semantic rules from
+ * the "Semantic diff" spec section: key order doesn't matter, `1.0` equals
+ * `1`, array tails are `added`/`removed`, and a type change is one `changed`.
+ */
+function diffValue(golden, actual, path, changes) {
+    const goldenKind = kindOf(golden);
+    const actualKind = kindOf(actual);
+    if (goldenKind !== actualKind) {
+        changes.push({ kind: 'changed', path: pointer(path), expected: display(golden), actual: display(actual) });
+        return;
+    }
+    switch (goldenKind) {
+        case 'array': {
+            const goldenArray = golden;
+            const actualArray = actual;
+            const shared = Math.min(goldenArray.length, actualArray.length);
+            for (let i = 0; i < shared; i += 1) {
+                diffValue(goldenArray[i], actualArray[i], [...path, String(i)], changes);
+            }
+            for (let i = shared; i < goldenArray.length; i += 1) {
+                changes.push({ kind: 'removed', path: pointer([...path, String(i)]), expected: display(goldenArray[i]) });
+            }
+            for (let i = shared; i < actualArray.length; i += 1) {
+                changes.push({ kind: 'added', path: pointer([...path, String(i)]), actual: display(actualArray[i]) });
+            }
+            return;
+        }
+        case 'object': {
+            const goldenObject = golden;
+            const actualObject = actual;
+            const keys = new Set([...Object.keys(goldenObject), ...Object.keys(actualObject)]);
+            for (const key of keys) {
+                const inGolden = Object.hasOwn(goldenObject, key);
+                const inActual = Object.hasOwn(actualObject, key);
+                if (inGolden && inActual) {
+                    diffValue(goldenObject[key], actualObject[key], [...path, key], changes);
+                }
+                else if (inGolden) {
+                    changes.push({ kind: 'removed', path: pointer([...path, key]), expected: display(goldenObject[key]) });
+                }
+                else {
+                    changes.push({ kind: 'added', path: pointer([...path, key]), actual: display(actualObject[key]) });
+                }
+            }
+            return;
+        }
+        case 'number': {
+            // Compared by value, so `1.0` and `1` — indistinguishable once parsed — are equal.
+            if (golden !== actual) {
+                changes.push({ kind: 'changed', path: pointer(path), expected: display(golden), actual: display(actual) });
+            }
+            return;
+        }
+        default: {
+            if (golden !== actual) {
+                changes.push({ kind: 'changed', path: pointer(path), expected: display(golden), actual: display(actual) });
+            }
+        }
+    }
+}
+/** Semantically diffs two JSON documents, returning every change found. */
+export function diffJson(golden, actual) {
+    const changes = [];
+    diffValue(golden, actual, [], changes);
+    return changes;
+}

package/dist/snapshot/xml-diff.d.ts

@@ -0,0 +1,10 @@
+import type { SnapshotChange } from './diff.js';
+/**
+ * Semantically diffs two XML documents per the "Semantic diff" spec
+ * section: elements/attributes compared by namespace URI + local name (so
+ * prefixes don't matter), `xmlns` declarations/attribute order/comments/PIs
+ * ignored, whitespace-only text ignored and other text trimmed, and
+ * repeated same-name siblings paired in order (so an earlier sibling with a
+ * different name doesn't shift the rest).
+ */
+export declare function diffXml(golden: string, actual: string): SnapshotChange[];

package/dist/snapshot/xml-diff.js

@@ -0,0 +1,194 @@
+import { truncateValue } from './format.js';
+import { parseXml } from '../xml/parse.js';
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const CDATA_SECTION_NODE = 4;
+const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
+/** The (namespace URI, local name) pair elements and attributes are compared by. */
+function nameKey(namespaceURI, localName) {
+    return `${namespaceURI ?? ''}|${localName}`;
+}
+function isElement(node) {
+    return node.nodeType === ELEMENT_NODE;
+}
+function childElements(node) {
+    const result = [];
+    for (let i = 0; i < node.childNodes.length; i += 1) {
+        const child = node.childNodes.item(i);
+        if (child !== null && isElement(child)) {
+            result.push(child);
+        }
+    }
+    return result;
+}
+/**
+ * Direct text (and CDATA) children — comments, PIs and whitespace-only text ignored. In mixed
+ * content each run of text between child elements is trimmed on its own and the runs joined by
+ * one space, so indentation around a child element never reads as a text change.
+ */
+function ownText(node) {
+    const runs = [];
+    let run = '';
+    const flush = () => {
+        const trimmed = run.trim();
+        if (trimmed.length > 0) {
+            runs.push(trimmed);
+        }
+        run = '';
+    };
+    for (let i = 0; i < node.childNodes.length; i += 1) {
+        const child = node.childNodes.item(i);
+        if (child === null) {
+            continue;
+        }
+        if (child.nodeType === TEXT_NODE || child.nodeType === CDATA_SECTION_NODE) {
+            run += child.nodeValue ?? '';
+        }
+        else if (child.nodeType === ELEMENT_NODE) {
+            flush();
+        }
+    }
+    flush();
+    return runs.join(' ');
+}
+/** An element's non-`xmlns` attributes, keyed by (namespace, local name). */
+function attributesOf(node) {
+    const result = new Map();
+    for (let i = 0; i < node.attributes.length; i += 1) {
+        const attr = node.attributes.item(i);
+        if (attr === null) {
+            continue;
+        }
+        if (attr.namespaceURI === XMLNS_NS || attr.nodeName === 'xmlns' || attr.nodeName.startsWith('xmlns:')) {
+            continue;
+        }
+        result.set(nameKey(attr.namespaceURI, attr.localName ?? attr.nodeName), attr);
+    }
+    return result;
+}
+/** Groups an element's children by (namespace, local name), preserving document order within each group. */
+function groupChildren(elements) {
+    const groups = new Map();
+    for (const element of elements) {
+        const key = nameKey(element.namespaceURI, element.localName ?? element.tagName);
+        const group = groups.get(key);
+        if (group === undefined) {
+            groups.set(key, [element]);
+        }
+        else {
+            group.push(element);
+        }
+    }
+    return groups;
+}
+function elementDisplay(element) {
+    return `<${element.localName ?? element.tagName}>`;
+}
+function childPath(parentPath, localName, indexInGroup, groupSize) {
+    const segment = groupSize > 1 ? `${localName}[${indexInGroup + 1}]` : localName;
+    return `${parentPath}/${segment}`;
+}
+function diffAttributes(golden, actual, path, changes) {
+    const goldenAttrs = attributesOf(golden);
+    const actualAttrs = attributesOf(actual);
+    const keys = new Set([...goldenAttrs.keys(), ...actualAttrs.keys()]);
+    for (const key of keys) {
+        const goldenAttr = goldenAttrs.get(key);
+        const actualAttr = actualAttrs.get(key);
+        const attrPath = `${path}/@${(goldenAttr ?? actualAttr)?.localName ?? (goldenAttr ?? actualAttr)?.nodeName}`;
+        if (goldenAttr !== undefined && actualAttr === undefined) {
+            changes.push({ kind: 'removed', path: attrPath, expected: truncateValue(goldenAttr.value) });
+        }
+        else if (goldenAttr === undefined && actualAttr !== undefined) {
+            changes.push({ kind: 'added', path: attrPath, actual: truncateValue(actualAttr.value) });
+        }
+        else if (goldenAttr !== undefined && actualAttr !== undefined && goldenAttr.value !== actualAttr.value) {
+            changes.push({
+                kind: 'changed',
+                path: attrPath,
+                expected: truncateValue(goldenAttr.value),
+                actual: truncateValue(actualAttr.value),
+            });
+        }
+    }
+}
+function diffChildren(golden, actual, path, changes) {
+    const goldenGroups = groupChildren(childElements(golden));
+    const actualGroups = groupChildren(childElements(actual));
+    const keys = new Set([...goldenGroups.keys(), ...actualGroups.keys()]);
+    for (const key of keys) {
+        const goldenGroup = goldenGroups.get(key) ?? [];
+        const actualGroup = actualGroups.get(key) ?? [];
+        const groupSize = Math.max(goldenGroup.length, actualGroup.length);
+        const shared = Math.min(goldenGroup.length, actualGroup.length);
+        const localName = (goldenGroup[0] ?? actualGroup[0])?.localName ?? (goldenGroup[0] ?? actualGroup[0])?.tagName ?? '';
+        for (let i = 0; i < shared; i += 1) {
+            const goldenChild = goldenGroup[i];
+            const actualChild = actualGroup[i];
+            if (goldenChild !== undefined && actualChild !== undefined) {
+                diffElement(goldenChild, actualChild, childPath(path, localName, i, groupSize), changes);
+            }
+        }
+        for (let i = shared; i < goldenGroup.length; i += 1) {
+            const goldenChild = goldenGroup[i];
+            if (goldenChild !== undefined) {
+                changes.push({
+                    kind: 'removed',
+                    path: childPath(path, localName, i, groupSize),
+                    expected: elementDisplay(goldenChild),
+                });
+            }
+        }
+        for (let i = shared; i < actualGroup.length; i += 1) {
+            const actualChild = actualGroup[i];
+            if (actualChild !== undefined) {
+                changes.push({
+                    kind: 'added',
+                    path: childPath(path, localName, i, groupSize),
+                    actual: elementDisplay(actualChild),
+                });
+            }
+        }
+    }
+}
+function diffElement(golden, actual, path, changes) {
+    diffAttributes(golden, actual, path, changes);
+    const goldenText = ownText(golden);
+    const actualText = ownText(actual);
+    if (goldenText !== actualText) {
+        changes.push({ kind: 'changed', path, expected: truncateValue(goldenText), actual: truncateValue(actualText) });
+    }
+    diffChildren(golden, actual, path, changes);
+}
+/**
+ * Semantically diffs two XML documents per the "Semantic diff" spec
+ * section: elements/attributes compared by namespace URI + local name (so
+ * prefixes don't matter), `xmlns` declarations/attribute order/comments/PIs
+ * ignored, whitespace-only text ignored and other text trimmed, and
+ * repeated same-name siblings paired in order (so an earlier sibling with a
+ * different name doesn't shift the rest).
+ */
+export function diffXml(golden, actual) {
+    const goldenDoc = parseXml(golden);
+    const actualDoc = parseXml(actual);
+    const goldenRoot = goldenDoc.documentElement;
+    const actualRoot = actualDoc.documentElement;
+    if (goldenRoot === null || actualRoot === null) {
+        return [];
+    }
+    const goldenKey = nameKey(goldenRoot.namespaceURI, goldenRoot.localName ?? goldenRoot.tagName);
+    const actualKey = nameKey(actualRoot.namespaceURI, actualRoot.localName ?? actualRoot.tagName);
+    const rootName = goldenRoot.localName ?? goldenRoot.tagName;
+    const changes = [];
+    if (goldenKey !== actualKey) {
+        changes.push({
+            kind: 'changed',
+            path: `/${rootName}`,
+            expected: elementDisplay(goldenRoot),
+            actual: elementDisplay(actualRoot),
+        });
+        return changes;
+    }
+    diffElement(goldenRoot, actualRoot, `/${rootName}`, changes);
+    return changes;
+}

package/dist/soap/auth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Token credentials on a SOAP send: Bearer, API key and OAuth2 become headers or a query
+ * parameter, exactly as on a REST send, so there is one implementation of each ({@link applyAuth}).
+ *
+ * Basic and NTLM are passed through as `transportAuth`, because they may need a challenge round
+ * trip that only the transport (`http/auth/*`) can run.
+ */
+import type { SendAuth } from '../http/auth/send-auth.js';
+/** A SOAP send's endpoint and headers with token credentials applied. */
+export interface SoapAppliedAuth {
+    /** The endpoint to put on the wire: the input one, plus an API key's query parameter if any. */
+    readonly endpoint: string;
+    /** The caller's headers plus any credential header they did not already set. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Basic or NTLM, for `sendWithAuth`; absent for token schemes and for no auth. */
+    readonly transportAuth?: SendAuth;
+}
+/**
+ * Applies resolved credentials to one SOAP send.
+ *
+ * A header the caller set wins over the credential's, compared case-insensitively, so a request
+ * that writes its own `Authorization` keeps it — the same rule the REST send and the Basic
+ * transport follow. An endpoint that does not parse as a URL is returned unchanged: the send
+ * then fails on the URL itself, which is the clearer error.
+ */
+export declare function applySoapAuth(endpoint: string, headers: Readonly<Record<string, string>> | undefined, auth: SendAuth | undefined): SoapAppliedAuth;

package/dist/soap/auth.js

@@ -0,0 +1,54 @@
+/**
+ * Token credentials on a SOAP send: Bearer, API key and OAuth2 become headers or a query
+ * parameter, exactly as on a REST send, so there is one implementation of each ({@link applyAuth}).
+ *
+ * Basic and NTLM are passed through as `transportAuth`, because they may need a challenge round
+ * trip that only the transport (`http/auth/*`) can run.
+ */
+import { applyAuth } from '../http/auth/apply-auth.js';
+/**
+ * Applies resolved credentials to one SOAP send.
+ *
+ * A header the caller set wins over the credential's, compared case-insensitively, so a request
+ * that writes its own `Authorization` keeps it — the same rule the REST send and the Basic
+ * transport follow. An endpoint that does not parse as a URL is returned unchanged: the send
+ * then fails on the URL itself, which is the clearer error.
+ */
+export function applySoapAuth(endpoint, headers, auth) {
+    const applied = applyAuth(auth);
+    const merged = { ...headers };
+    const taken = new Set(Object.keys(merged).map((name) => name.toLowerCase()));
+    for (const [name, value] of Object.entries(applied.headers)) {
+        if (!taken.has(name.toLowerCase())) {
+            merged[name] = value;
+        }
+    }
+    return {
+        endpoint: withQuery(endpoint, applied.query),
+        headers: merged,
+        ...(applied.transportAuth !== undefined ? { transportAuth: applied.transportAuth } : {}),
+    };
+}
+/**
+ * The endpoint with `rows` appended to its query. Built by hand rather than through
+ * `URL.searchParams`, which would re-serialise the whole query as form encoding: the endpoint's own
+ * query and fragment stay byte-for-byte as configured (an `?op` stays `?op`), as REST keeps an
+ * inline query. An endpoint that is not an absolute URL is returned unchanged.
+ */
+function withQuery(endpoint, rows) {
+    if (rows.length === 0) {
+        return endpoint;
+    }
+    try {
+        new URL(endpoint);
+    }
+    catch {
+        return endpoint;
+    }
+    const hash = endpoint.indexOf('#');
+    const head = hash === -1 ? endpoint : endpoint.slice(0, hash);
+    const fragment = hash === -1 ? '' : endpoint.slice(hash);
+    const separator = !head.includes('?') ? '?' : /[?&]$/.test(head) ? '' : '&';
+    const query = rows.map((row) => `${encodeURIComponent(row.name)}=${encodeURIComponent(row.value)}`).join('&');
+    return `${head}${separator}${query}${fragment}`;
+}