@harborclient/core 0.1.1

package/dist/scripting/scriptApi.js

@@ -0,0 +1,692 @@
+import { buildScriptRunInfo } from '../types/script';
+import { applyScriptAuthSet, applyScriptAuthUpdate, defaultAuth, flattenAuthConfig, normalizeAuth } from '../auth';
+import { resolveDynamicVariable, substituteVariablesWithResolver } from '@harborclient/sdk/variables';
+import { parseResponseDocument } from './scriptResponseDocument';
+import { scriptExpect } from './scriptExpect';
+import { createResponseAssertionSubject } from './scriptResponseAssertions';
+/**
+ * Builds a variable bag with get, set, and clear keyed by name.
+ *
+ * @param scope - Variable scope label recorded in execution events.
+ * @param getSets - Returns the mutable set map for this scope.
+ * @param getClears - Returns the mutable clear set for this scope.
+ * @param getFallback - Resolves values from the merged runtime variable map.
+ * @param emit - Appends a variable execution event in call order.
+ * @returns Variable bag API shared by request, collection, environment, and global scopes.
+ */
+function makeVariableBag(scope, getSets, getClears, getFallback, emit) {
+    return {
+        get: (key) => {
+            const k = String(key);
+            const sets = getSets();
+            if (Object.prototype.hasOwnProperty.call(sets, k)) {
+                return sets[k];
+            }
+            if (getClears().has(k)) {
+                return undefined;
+            }
+            return getFallback(k);
+        },
+        set: (key, value) => {
+            const k = String(key);
+            const sets = getSets();
+            const clears = getClears();
+            let priorValue;
+            if (Object.prototype.hasOwnProperty.call(sets, k)) {
+                priorValue = sets[k];
+            }
+            else if (clears.has(k)) {
+                priorValue = undefined;
+            }
+            else {
+                priorValue = getFallback(k);
+            }
+            const v = String(value);
+            emit({
+                type: 'variable',
+                scope,
+                action: priorValue !== undefined ? 'update' : 'set',
+                key: k,
+                value: v
+            });
+            clears.delete(k);
+            sets[k] = v;
+        },
+        clear: (key) => {
+            const k = String(key);
+            emit({
+                type: 'variable',
+                scope,
+                action: 'clear',
+                key: k
+            });
+            delete getSets()[k];
+            getClears().add(k);
+        }
+    };
+}
+/**
+ * Builds a cookie bag scoped to the request host resolved at send start.
+ *
+ * @param getRows - Returns mutable cookie rows seeded from the jar.
+ * @param getSets - Returns cookie name to value writes for persistence.
+ * @param getClears - Returns cookie names cleared during the script run.
+ * @returns Cookie get/set/clear API for hc.cookies.
+ */
+function makeCookieBag(getRows, getSets, getClears) {
+    return {
+        get: (name) => {
+            const k = String(name);
+            const sets = getSets();
+            if (Object.prototype.hasOwnProperty.call(sets, k)) {
+                return sets[k];
+            }
+            if (getClears().has(k)) {
+                return undefined;
+            }
+            const row = getRows().find((cookie) => cookie.enabled && cookie.key.trim().toLowerCase() === k.toLowerCase());
+            return row ? row.value : undefined;
+        },
+        set: (name, value) => {
+            const k = String(name);
+            const v = String(value);
+            getClears().delete(k);
+            getSets()[k] = v;
+            const rows = getRows();
+            const existing = rows.find((cookie) => cookie.enabled && cookie.key.trim().toLowerCase() === k.toLowerCase());
+            if (existing) {
+                existing.value = v;
+            }
+            else {
+                rows.push({ key: k, value: v, enabled: true });
+            }
+        },
+        clear: (name) => {
+            const k = String(name);
+            delete getSets()[k];
+            getClears().add(k);
+            const rows = getRows();
+            const index = rows.findIndex((cookie) => cookie.key.trim().toLowerCase() === k.toLowerCase());
+            if (index >= 0) {
+                rows.splice(index, 1);
+            }
+        }
+    };
+}
+/**
+ * Builds a parameter bag over mutable key/value rows with batch and single set.
+ *
+ * @param getRows - Returns the rows mutated by set and clear.
+ * @param options - Whether keys are matched case-insensitively.
+ * @returns Parameter bag API shared by hc.request.params, hc.request.headers, and hc.collection.headers.
+ */
+function makeParameterBag(getRows, options) {
+    const normalizeKey = (key) => String(key).trim();
+    const keysEqual = (left, right) => {
+        const a = normalizeKey(left);
+        const b = normalizeKey(right);
+        return options.caseInsensitive ? a.toLowerCase() === b.toLowerCase() : a === b;
+    };
+    const findRow = (key) => {
+        const rows = getRows();
+        return rows.find((row) => row.enabled && keysEqual(row.key, key));
+    };
+    const upsert = (key, value) => {
+        const k = String(key);
+        const v = String(value);
+        const rows = getRows();
+        const existing = rows.find((row) => row.enabled && keysEqual(row.key, k));
+        if (existing) {
+            existing.value = v;
+        }
+        else {
+            rows.push({ key: k, value: v, enabled: true });
+        }
+    };
+    const getAll = () => {
+        const map = {};
+        for (const row of getRows()) {
+            if (row.enabled && row.key.trim()) {
+                map[row.key.trim()] = row.value;
+            }
+        }
+        return map;
+    };
+    const get = ((key) => {
+        if (key === undefined) {
+            return getAll();
+        }
+        const row = findRow(key);
+        return row ? row.value : undefined;
+    });
+    const set = ((first, second) => {
+        if (first != null && typeof first === 'object' && !Array.isArray(first)) {
+            for (const [key, value] of Object.entries(first)) {
+                upsert(key, value);
+            }
+            return;
+        }
+        upsert(String(first), second);
+    });
+    return {
+        get,
+        set,
+        clear: () => {
+            getRows().length = 0;
+        }
+    };
+}
+/**
+ * Builds a notes bag over request tags and comment fields.
+ *
+ * @param getRequest - Returns the mutable script request context.
+ * @returns Notes get/set/clear API for hc.request.notes.
+ */
+function makeNotesBag(getRequest) {
+    const getAll = () => {
+        const request = getRequest();
+        return {
+            tags: request.tags ?? '',
+            comment: request.comment ?? ''
+        };
+    };
+    const get = ((field) => {
+        const notes = getAll();
+        if (field === undefined) {
+            return notes;
+        }
+        return notes[field];
+    });
+    const set = ((first, second) => {
+        const request = getRequest();
+        if (first != null && typeof first === 'object' && !Array.isArray(first)) {
+            const entries = first;
+            if (entries.tags !== undefined) {
+                request.tags = String(entries.tags);
+            }
+            if (entries.comment !== undefined) {
+                request.comment = String(entries.comment);
+            }
+            return;
+        }
+        const field = String(first);
+        if (field === 'tags' || field === 'comment') {
+            request[field] = String(second);
+        }
+    });
+    return {
+        get,
+        set,
+        clear: () => {
+            const request = getRequest();
+            request.tags = '';
+            request.comment = '';
+        }
+    };
+}
+/**
+ * Builds get/set/update auth helpers over a mutable auth config ref.
+ *
+ * @param getAuth - Returns the mutable auth config for this scope.
+ * @returns Auth bag API shared by hc.request.auth and hc.collection.auth.
+ */
+function makeAuthApi(getAuth) {
+    return {
+        get: () => flattenAuthConfig(getAuth()),
+        set: (input) => {
+            const next = applyScriptAuthSet(getAuth(), input);
+            const auth = getAuth();
+            auth.type = next.type;
+            auth.basic = next.basic;
+            auth.bearer = next.bearer;
+            auth.oauth2 = next.oauth2;
+        },
+        update: (field, value) => {
+            const next = applyScriptAuthUpdate(getAuth(), field, value);
+            const auth = getAuth();
+            auth.type = next.type;
+            auth.basic = next.basic;
+            auth.bearer = next.bearer;
+            auth.oauth2 = next.oauth2;
+        }
+    };
+}
+/**
+ * Formats console arguments the same way as the legacy bootstrap string.
+ *
+ * @param args - Values passed to console.log or console.error.
+ * @returns Single-line string joined with spaces.
+ */
+function formatConsoleArgs(args) {
+    return args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ');
+}
+/**
+ * Normalizes a script sendRequest input from the hc API into a SendRequestInput.
+ *
+ * @param req - User-provided request object from hc.sendRequest.
+ * @returns Normalized send input for the HTTP layer.
+ */
+function normalizeScriptSendRequest(req) {
+    if (!req || typeof req !== 'object') {
+        throw new Error('hc.sendRequest requires a request object');
+    }
+    const input = req;
+    const method = input.method != null ? String(input.method) : 'GET';
+    const url = input.url != null ? String(input.url) : '';
+    if (!url.trim()) {
+        throw new Error('hc.sendRequest requires a url');
+    }
+    const rawHeaders = input.headers;
+    let headers = [];
+    if (Array.isArray(rawHeaders)) {
+        headers = rawHeaders.map((row) => {
+            const entry = row;
+            return {
+                key: String(entry.key ?? ''),
+                value: String(entry.value ?? ''),
+                enabled: entry.enabled !== false
+            };
+        });
+    }
+    else if (rawHeaders && typeof rawHeaders === 'object') {
+        headers = Object.entries(rawHeaders).map(([key, value]) => ({
+            key,
+            value: String(value),
+            enabled: true
+        }));
+    }
+    const rawParams = input.params;
+    let params = [];
+    if (Array.isArray(rawParams)) {
+        params = rawParams.map((row) => {
+            const entry = row;
+            return {
+                key: String(entry.key ?? ''),
+                value: String(entry.value ?? ''),
+                enabled: entry.enabled !== false
+            };
+        });
+    }
+    const bodyTypeRaw = String(input.bodyType ?? input.body_type ?? 'none');
+    const allowedBodyTypes = ['none', 'json', 'text', 'multipart', 'urlencoded'];
+    const bodyType = allowedBodyTypes.includes(bodyTypeRaw)
+        ? bodyTypeRaw
+        : 'none';
+    return {
+        method: method,
+        url,
+        headers,
+        params,
+        body: input.body != null ? String(input.body) : '',
+        bodyType
+    };
+}
+/**
+ * Builds the hc API and capturing console over a fresh mutable state.
+ *
+ * Shared by pre/post request scripts and main-process plugin script contexts so
+ * the hc surface never drifts between runners.
+ *
+ * @param input - Phase, request, response, variables, and optional collection/environment context.
+ * @param options - Optional runtime hooks such as hc.sendRequest transport.
+ * @returns hc object, console, and a reader for accumulated sandbox mutations.
+ */
+export function createScriptApi(input, options) {
+    const ctx = {
+        phase: input.phase,
+        request: input.request,
+        response: input.response,
+        variables: input.variables,
+        collection: input.collection,
+        environment: input.environment,
+        folder: input.folder
+    };
+    const state = {
+        request: {
+            ...input.request,
+            auth: normalizeAuth(input.request.auth)
+        },
+        variables: { ...input.variables },
+        variableSets: {},
+        variableClears: new Set(),
+        collectionVariableSets: {},
+        collectionVariableClears: new Set(),
+        folderVariableSets: {},
+        folderVariableClears: new Set(),
+        environmentVariableSets: {},
+        environmentVariableClears: new Set(),
+        globalVariableSets: {},
+        globalVariableClears: new Set(),
+        cookies: input.cookies ? input.cookies.map((cookie) => ({ ...cookie })) : [],
+        cookieSets: {},
+        cookieClears: new Set(),
+        collectionHeaders: input.collection?.headers ? [...input.collection.headers] : [],
+        collectionAuth: normalizeAuth(input.collection?.auth),
+        folderHeaders: input.folder?.headers ? [...input.folder.headers] : [],
+        folderAuth: normalizeAuth(input.folder?.auth),
+        tests: [],
+        logs: [],
+        executionEvents: [],
+        phase: input.phase,
+        nextRequest: undefined,
+        skipRequest: false,
+        data: input.data ? { ...input.data } : {}
+    };
+    const resolveRuntimeVariable = (key) => {
+        if (Object.prototype.hasOwnProperty.call(state.variableSets, key)) {
+            return state.variableSets[key];
+        }
+        if (state.variableClears.has(key)) {
+            return undefined;
+        }
+        return state.variables[key];
+    };
+    const resolveSeededVariable = (key) => state.variables[key];
+    const emitExecutionEvent = (event) => {
+        state.executionEvents.push(event);
+    };
+    const info = input.info ??
+        buildScriptRunInfo(input.phase, {
+            requestName: '',
+            requestId: null,
+            iteration: 0
+        });
+    const hc = {
+        info: {
+            get eventName() {
+                return info.eventName;
+            },
+            get requestName() {
+                return info.requestName;
+            },
+            get requestId() {
+                return info.requestId;
+            },
+            get iteration() {
+                return info.iteration;
+            }
+        },
+        request: {
+            get method() {
+                return state.request.method;
+            },
+            set method(v) {
+                state.request.method = String(v);
+            },
+            get url() {
+                return state.request.url;
+            },
+            set url(v) {
+                state.request.url = String(v);
+            },
+            get body() {
+                return state.request.body;
+            },
+            set body(v) {
+                state.request.body = String(v);
+            },
+            headers: makeParameterBag(() => state.request.headers, { caseInsensitive: true }),
+            params: makeParameterBag(() => state.request.params, { caseInsensitive: false }),
+            notes: makeNotesBag(() => state.request),
+            auth: makeAuthApi(() => state.request.auth),
+            variables: {
+                ...makeVariableBag('request', () => state.variableSets, () => state.variableClears, resolveRuntimeVariable, emitExecutionEvent),
+                replaceIn: (template) => {
+                    const text = String(template);
+                    return substituteVariablesWithResolver(text, (key) => {
+                        if (Object.prototype.hasOwnProperty.call(state.variableSets, key)) {
+                            return state.variableSets[key];
+                        }
+                        if (state.variableClears.has(key)) {
+                            return undefined;
+                        }
+                        if (Object.prototype.hasOwnProperty.call(state.variables, key)) {
+                            return state.variables[key];
+                        }
+                        return resolveDynamicVariable(key);
+                    });
+                }
+            }
+        },
+        collection: {
+            get id() {
+                return ctx.collection ? ctx.collection.id : null;
+            },
+            get name() {
+                return ctx.collection ? ctx.collection.name : '';
+            },
+            variables: makeVariableBag('collection', () => state.collectionVariableSets, () => state.collectionVariableClears, resolveSeededVariable, emitExecutionEvent),
+            headers: makeParameterBag(() => state.collectionHeaders, { caseInsensitive: true }),
+            auth: makeAuthApi(() => state.collectionAuth)
+        },
+        folder: {
+            get id() {
+                return ctx.folder ? ctx.folder.id : null;
+            },
+            get name() {
+                return ctx.folder ? ctx.folder.name : '';
+            },
+            variables: makeVariableBag('folder', () => state.folderVariableSets, () => state.folderVariableClears, resolveSeededVariable, emitExecutionEvent),
+            headers: makeParameterBag(() => state.folderHeaders, { caseInsensitive: true }),
+            auth: makeAuthApi(() => state.folderAuth)
+        },
+        environment: {
+            get name() {
+                return ctx.environment ? ctx.environment.name : '';
+            },
+            variables: makeVariableBag('environment', () => state.environmentVariableSets, () => state.environmentVariableClears, resolveSeededVariable, emitExecutionEvent)
+        },
+        globals: makeVariableBag('global', () => state.globalVariableSets, () => state.globalVariableClears, resolveSeededVariable, emitExecutionEvent),
+        /**
+         * Cookie bag for the request host resolved at send start. URL changes mid-script
+         * do not retarget this bag.
+         */
+        cookies: makeCookieBag(() => state.cookies, () => state.cookieSets, () => state.cookieClears),
+        /**
+         * Mutable object shared across scripts in the current send (pre through post).
+         */
+        get data() {
+            return state.data;
+        },
+        set data(v) {
+            state.data =
+                v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+        },
+        execution: {
+            setNextRequest: (name) => {
+                state.nextRequest = name == null ? null : String(name);
+                emitExecutionEvent({
+                    type: 'flow',
+                    action: 'set-next-request',
+                    nextRequest: state.nextRequest
+                });
+            },
+            skipRequest: () => {
+                state.skipRequest = true;
+                emitExecutionEvent({
+                    type: 'flow',
+                    action: 'skip-request'
+                });
+            }
+        },
+        test: (name, fn) => {
+            try {
+                fn();
+                state.tests.push({ name: String(name), passed: true });
+            }
+            catch (err) {
+                state.tests.push({
+                    name: String(name),
+                    passed: false,
+                    error: String(err && typeof err === 'object' && 'message' in err ? err.message : err)
+                });
+            }
+        },
+        /** Chai BDD expect; see https://www.chaijs.com/api/bdd/ */
+        expect: scriptExpect
+    };
+    if (options?.sendRequest) {
+        const transport = options.sendRequest;
+        hc.sendRequest = async (req) => {
+            const normalized = normalizeScriptSendRequest(req);
+            const result = await transport(normalized);
+            return {
+                code: result.status,
+                status: result.statusText,
+                headers: result.headers,
+                responseTime: result.timeMs,
+                text: () => result.body,
+                json: () => JSON.parse(result.body)
+            };
+        };
+    }
+    else {
+        hc.sendRequest = () => {
+            throw new Error('hc.sendRequest is not available in this script context');
+        };
+    }
+    const fileBridge = options?.fileBridge;
+    /**
+     * Invokes the main-process file bridge or throws when unavailable.
+     *
+     * @param req - Bridged operation payload.
+     * @returns Operation result from main.
+     */
+    const callFileBridge = async (req) => {
+        if (!fileBridge) {
+            throw new Error('hc.fs is not available in this script context');
+        }
+        return fileBridge(req);
+    };
+    hc.fs = {
+        readText: (path) => callFileBridge({ op: 'readText', path: String(path) }),
+        readBytes: (path) => callFileBridge({ op: 'readBytes', path: String(path) }),
+        writeText: (path, contents) => callFileBridge({ op: 'writeText', path: String(path), contents: String(contents ?? '') }),
+        writeBytes: (path, bytes) => callFileBridge({
+            op: 'writeBytes',
+            path: String(path),
+            bytes: bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+        }),
+        append: (path, contents) => callFileBridge({ op: 'append', path: String(path), contents: String(contents ?? '') }),
+        exists: (path) => callFileBridge({ op: 'exists', path: String(path) }),
+        stat: (path) => callFileBridge({ op: 'stat', path: String(path) }),
+        readJson: (path) => callFileBridge({ op: 'readJson', path: String(path) }),
+        readYaml: (path) => callFileBridge({ op: 'readYaml', path: String(path) }),
+        readCsv: (path, csvOptions) => callFileBridge({ op: 'readCsv', path: String(path), options: csvOptions }),
+        writeJson: (path, value, jsonOptions) => callFileBridge({
+            op: 'writeJson',
+            path: String(path),
+            value,
+            options: jsonOptions
+        }),
+        writeYaml: (path, value) => callFileBridge({ op: 'writeYaml', path: String(path), value }),
+        writeCsv: (path, rows, csvOptions) => callFileBridge({
+            op: 'writeCsv',
+            path: String(path),
+            value: rows,
+            options: csvOptions
+        })
+    };
+    hc.parse = {
+        yaml: (text) => callFileBridge({ op: 'parseYaml', contents: String(text ?? '') }),
+        csv: (text, csvOptions) => callFileBridge({
+            op: 'parseCsv',
+            contents: String(text ?? ''),
+            options: csvOptions
+        })
+    };
+    hc.stringify = {
+        yaml: (value) => callFileBridge({ op: 'stringifyYaml', value }),
+        csv: (rows, csvOptions) => callFileBridge({ op: 'stringifyCsv', value: rows, options: csvOptions })
+    };
+    if (ctx.response) {
+        const resp = ctx.response;
+        let cachedDocument;
+        const responseSubject = createResponseAssertionSubject(resp);
+        hc.response = {
+            get code() {
+                return resp.status;
+            },
+            get status() {
+                return resp.statusText;
+            },
+            get headers() {
+                return resp.headers;
+            },
+            get responseTime() {
+                return resp.timeMs;
+            },
+            get to() {
+                return scriptExpect(responseSubject).to;
+            },
+            text: () => resp.body,
+            json: () => JSON.parse(resp.body),
+            document: () => {
+                cachedDocument ??= parseResponseDocument(resp.body);
+                return cachedDocument;
+            }
+        };
+    }
+    const scriptConsole = {
+        log: (...args) => {
+            state.logs.push(formatConsoleArgs(args));
+        },
+        error: (...args) => {
+            state.logs.push(`[error] ${formatConsoleArgs(args)}`);
+        }
+    };
+    return {
+        hc,
+        console: scriptConsole,
+        readResult: () => ({
+            request: state.request,
+            variableSets: state.variableSets ?? {},
+            variableClears: [...state.variableClears],
+            collectionVariableSets: state.collectionVariableSets ?? {},
+            collectionVariableClears: [...state.collectionVariableClears],
+            folderVariableSets: state.folderVariableSets ?? {},
+            folderVariableClears: [...state.folderVariableClears],
+            environmentVariableSets: state.environmentVariableSets ?? {},
+            environmentVariableClears: [...state.environmentVariableClears],
+            globalVariableSets: state.globalVariableSets ?? {},
+            globalVariableClears: [...state.globalVariableClears],
+            cookieSets: state.cookieSets ?? {},
+            cookieClears: [...state.cookieClears],
+            collectionHeaders: state.collectionHeaders ?? [],
+            collectionAuth: state.collectionAuth,
+            folderHeaders: state.folderHeaders ?? [],
+            folderAuth: state.folderAuth,
+            nextRequest: state.nextRequest,
+            skipRequest: state.skipRequest || undefined,
+            tests: state.tests ?? [],
+            logs: state.logs ?? [],
+            executionEvents: state.executionEvents ?? [],
+            data: state.data
+        })
+    };
+}
+/**
+ * Default request/collection/environment context for plugin script sandboxes.
+ *
+ * @returns Minimal pre-phase context with an empty GET request and no variables.
+ */
+export function defaultScriptContextInput() {
+    return {
+        phase: 'pre',
+        request: {
+            method: 'GET',
+            url: '',
+            headers: [],
+            params: [],
+            body: '',
+            bodyType: 'none',
+            auth: defaultAuth(),
+            tags: '',
+            comment: ''
+        },
+        variables: {},
+        data: {},
+        info: buildScriptRunInfo('pre')
+    };
+}
+//# sourceMappingURL=scriptApi.js.map