@harborclient/core 0.1.1

package/dist/scripting/scriptFileOperations.js

@@ -0,0 +1,271 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'path';
+import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
+import Papa from 'papaparse';
+/**
+ * Maximum bytes a script may read or write in a single file operation.
+ */
+export const SCRIPT_FILE_MAX_BYTES = 50 * 1024 * 1024;
+/**
+ * Returns the access level required for a file bridge operation.
+ *
+ * @param op - Bridged operation name.
+ * @returns Access level used by the host gate.
+ */
+export function scriptFileAccessForOp(op) {
+    switch (op) {
+        case 'parseYaml':
+        case 'parseCsv':
+        case 'stringifyYaml':
+        case 'stringifyCsv':
+            return 'none';
+        case 'writeText':
+        case 'writeBytes':
+        case 'append':
+        case 'writeJson':
+        case 'writeYaml':
+        case 'writeCsv':
+            return 'write';
+        default:
+            return 'read';
+    }
+}
+/**
+ * Resolves the effective root directory that confines script filesystem access.
+ *
+ * Git-backed collections use their repository directory. Otherwise the
+ * configured scriptFileRoot is used, falling back to the user home directory.
+ *
+ * @param context - Optional collection connection used to detect git roots.
+ * @returns Absolute root directory path.
+ */
+export function resolveScriptFileRoot(dependencies, context) {
+    return resolve(dependencies.resolveRoot(context));
+}
+/**
+ * Resolves a script-supplied path under the effective root and rejects escapes.
+ *
+ * @param root - Absolute confinement root.
+ * @param targetPath - Relative or absolute path from the script.
+ * @returns Canonical absolute path under the root.
+ * @throws When the path escapes the root or contains parent segments.
+ */
+export function resolveScriptFilePath(root, targetPath) {
+    const trimmed = String(targetPath ?? '').trim();
+    if (!trimmed) {
+        throw new Error('hc.fs requires a path');
+    }
+    const rootReal = resolve(root);
+    const candidate = isAbsolute(trimmed) ? trimmed : join(root, trimmed);
+    const resolved = resolve(candidate);
+    const prefix = rootReal.endsWith(sep) ? rootReal : `${rootReal}${sep}`;
+    if (resolved !== rootReal && !resolved.startsWith(prefix)) {
+        throw new Error(`Path is outside the script file root: ${trimmed}`);
+    }
+    return resolved;
+}
+/**
+ * Asserts a byte length does not exceed the script file size limit.
+ *
+ * @param byteLength - Number of bytes about to be read or written.
+ * @throws When the payload exceeds {@link SCRIPT_FILE_MAX_BYTES}.
+ */
+function assertWithinSizeLimit(byteLength) {
+    if (byteLength > SCRIPT_FILE_MAX_BYTES) {
+        throw new Error(`Script file exceeds the ${SCRIPT_FILE_MAX_BYTES} byte limit (${byteLength} bytes)`);
+    }
+}
+/**
+ * Ensures the parent directory of a write target exists.
+ *
+ * @param filePath - Absolute file path about to be written.
+ */
+function ensureParentDir(filePath) {
+    mkdirSync(dirname(filePath), { recursive: true });
+}
+/**
+ * Parses CSV text with PapaParse using script-facing options.
+ *
+ * @param text - Raw CSV text.
+ * @param options - Optional parse options.
+ * @returns Object rows when headers are enabled, otherwise string[][].
+ */
+export function parseCsvText(text, options) {
+    const headers = options?.headers !== false && !Array.isArray(options?.headers);
+    const delimiter = typeof options?.delimiter === 'string' ? options.delimiter : ',';
+    const skipEmpty = options?.skipEmpty !== false;
+    const parsed = Papa.parse(text, {
+        header: headers,
+        delimiter,
+        skipEmptyLines: skipEmpty,
+        dynamicTyping: false
+    });
+    if (parsed.errors.length > 0) {
+        const first = parsed.errors[0];
+        throw new Error(`CSV parse error: ${first.message}`);
+    }
+    return parsed.data;
+}
+/**
+ * Serializes rows to CSV text with PapaParse.
+ *
+ * @param rows - Object rows or string[][].
+ * @param options - Optional stringify options.
+ * @returns CSV text.
+ */
+export function stringifyCsvText(rows, options) {
+    if (!Array.isArray(rows)) {
+        throw new Error('hc.fs.writeCsv / hc.stringify.csv requires an array of rows');
+    }
+    const delimiter = typeof options?.delimiter === 'string' ? options.delimiter : ',';
+    const columns = Array.isArray(options?.headers) ? options.headers : undefined;
+    return Papa.unparse(rows, {
+        delimiter,
+        columns,
+        header: columns != null || (rows.length > 0 && !Array.isArray(rows[0]))
+    });
+}
+/**
+ * Parses YAML text with js-yaml.
+ *
+ * @param text - Raw YAML text.
+ * @returns Parsed value.
+ */
+export function parseYamlText(text) {
+    return yamlLoad(text) ?? null;
+}
+/**
+ * Serializes a value to YAML text.
+ *
+ * @param value - Value to dump.
+ * @returns YAML text.
+ */
+export function stringifyYamlText(value) {
+    return yamlDump(value, { lineWidth: -1, noRefs: true });
+}
+/**
+ * Serializes a value to JSON text with optional pretty-printing.
+ *
+ * @param value - Value to stringify.
+ * @param options - Pretty / indent options.
+ * @returns JSON text.
+ */
+export function stringifyJsonText(value, options) {
+    const pretty = options?.pretty !== false;
+    const indent = Number.isInteger(options?.indent) ? Number(options?.indent) : 2;
+    return pretty ? `${JSON.stringify(value, null, indent)}\n` : JSON.stringify(value);
+}
+/**
+ * Executes a bridged script file / codec operation under the resolved root.
+ *
+ * @param request - Operation and payload from the sandbox.
+ * @param rootContext - Collection connection used for git root resolution.
+ * @returns Operation result (string, Uint8Array, object, boolean, null, or undefined).
+ */
+export function executeScriptFileRequest(request, dependencies, rootContext) {
+    const op = request.op;
+    const access = scriptFileAccessForOp(op);
+    if (access === 'none') {
+        switch (op) {
+            case 'parseYaml':
+                return parseYamlText(String(request.contents ?? ''));
+            case 'parseCsv':
+                return parseCsvText(String(request.contents ?? ''), request.options);
+            case 'stringifyYaml':
+                return stringifyYamlText(request.value);
+            case 'stringifyCsv':
+                return stringifyCsvText(request.value, request.options);
+            default:
+                throw new Error(`Unsupported script file operation: ${op}`);
+        }
+    }
+    const root = resolveScriptFileRoot(dependencies, rootContext);
+    const filePath = resolveScriptFilePath(root, String(request.path ?? ''));
+    switch (op) {
+        case 'exists':
+            return existsSync(filePath);
+        case 'stat': {
+            if (!existsSync(filePath)) {
+                return null;
+            }
+            const stats = statSync(filePath);
+            const result = {
+                size: stats.size,
+                mtimeMs: stats.mtimeMs,
+                isFile: stats.isFile(),
+                isDirectory: stats.isDirectory()
+            };
+            return result;
+        }
+        case 'readText':
+        case 'readJson':
+        case 'readYaml':
+        case 'readCsv': {
+            const stats = statSync(filePath);
+            assertWithinSizeLimit(stats.size);
+            const text = readFileSync(filePath, 'utf8');
+            if (op === 'readText') {
+                return text;
+            }
+            if (op === 'readJson') {
+                return JSON.parse(text);
+            }
+            if (op === 'readYaml') {
+                return parseYamlText(text);
+            }
+            return parseCsvText(text, request.options);
+        }
+        case 'readBytes': {
+            const stats = statSync(filePath);
+            assertWithinSizeLimit(stats.size);
+            return new Uint8Array(readFileSync(filePath));
+        }
+        case 'writeText':
+        case 'append': {
+            const contents = String(request.contents ?? '');
+            assertWithinSizeLimit(Buffer.byteLength(contents, 'utf8'));
+            ensureParentDir(filePath);
+            if (op === 'append') {
+                appendFileSync(filePath, contents, 'utf8');
+            }
+            else {
+                writeFileSync(filePath, contents, 'utf8');
+            }
+            return undefined;
+        }
+        case 'writeBytes': {
+            if (!(request.bytes instanceof Uint8Array)) {
+                throw new Error('hc.fs.writeBytes requires a Uint8Array');
+            }
+            const bytes = request.bytes;
+            assertWithinSizeLimit(bytes.byteLength);
+            ensureParentDir(filePath);
+            writeFileSync(filePath, bytes);
+            return undefined;
+        }
+        case 'writeJson': {
+            const text = stringifyJsonText(request.value, request.options);
+            assertWithinSizeLimit(Buffer.byteLength(text, 'utf8'));
+            ensureParentDir(filePath);
+            writeFileSync(filePath, text, 'utf8');
+            return undefined;
+        }
+        case 'writeYaml': {
+            const text = stringifyYamlText(request.value);
+            assertWithinSizeLimit(Buffer.byteLength(text, 'utf8'));
+            ensureParentDir(filePath);
+            writeFileSync(filePath, text, 'utf8');
+            return undefined;
+        }
+        case 'writeCsv': {
+            const text = stringifyCsvText(request.value, request.options);
+            assertWithinSizeLimit(Buffer.byteLength(text, 'utf8'));
+            ensureParentDir(filePath);
+            writeFileSync(filePath, text, 'utf8');
+            return undefined;
+        }
+        default:
+            throw new Error(`Unsupported script file operation: ${op}`);
+    }
+}
+//# sourceMappingURL=scriptFileOperations.js.map

package/dist/scripting/scriptFileOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptFileOperations.js","sourceRoot":"","sources":["../../src/scripting/scriptFileOperations.ts"],"names":[],"mappings":"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"}

package/dist/scripting/scriptResponseAssertions.d.ts

@@ -0,0 +1,40 @@
+import type { SendResult } from '../types';
+/**
+ * Brand symbol marking objects that are valid subjects for response assertion matchers.
+ */
+export declare const RESPONSE_ASSERTION_BRAND: unique symbol;
+/**
+ * Branded response snapshot used as the Chai assertion subject for `hc.response.to`.
+ */
+export interface ResponseAssertionSubject {
+    code: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    responseTime: number;
+    sizeBytes: number;
+    [RESPONSE_ASSERTION_BRAND]: true;
+}
+/**
+ * Returns whether a value is a branded response assertion subject.
+ *
+ * @param value - Assertion subject from Chai.
+ * @returns True when the value was created by {@link createResponseAssertionSubject}.
+ */
+export declare function isResponseAssertionSubject(value: unknown): value is ResponseAssertionSubject;
+/**
+ * Builds a branded response facade from a send result for Chai assertion subjects.
+ *
+ * @param resp - HTTP response from the completed send.
+ * @returns Branded subject passed to `scriptExpect` for `hc.response.to`.
+ */
+export declare function createResponseAssertionSubject(resp: SendResult): ResponseAssertionSubject;
+/**
+ * Registers Postman-style response matchers on the Chai Assertion prototype.
+ *
+ * Must run before SES `lockdown()` in the script runner import chain.
+ *
+ * @param chai - Chai module instance from the script sandbox host.
+ */
+export declare function installResponseAssertions(chai: Chai.ChaiStatic): void;
+//# sourceMappingURL=scriptResponseAssertions.d.ts.map

package/dist/scripting/scriptResponseAssertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptResponseAssertions.d.ts","sourceRoot":"","sources":["../../src/scripting/scriptResponseAssertions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,wBAAwB,eAAkC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,wBAAwB,CAAC,EAAE,IAAI,CAAC;CAClC;AAQD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAO5F;AAmDD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,UAAU,GAAG,wBAAwB,CAWzF;AA4DD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAqQrE"}

package/dist/scripting/scriptResponseAssertions.js

@@ -0,0 +1,249 @@
+/// <reference types="chai" />
+import { wrapCallablePropertyGetter } from './scriptAssertionCompat';
+/**
+ * Brand symbol marking objects that are valid subjects for response assertion matchers.
+ */
+export const RESPONSE_ASSERTION_BRAND = Symbol('hc.response.assertion');
+/**
+ * Error message when response matchers are invoked on a non-response subject.
+ */
+const RESPONSE_SCOPE_ERROR = 'response assertions require hc.response; use hc.response.to.have.status(...)';
+/**
+ * Returns whether a value is a branded response assertion subject.
+ *
+ * @param value - Assertion subject from Chai.
+ * @returns True when the value was created by {@link createResponseAssertionSubject}.
+ */
+export function isResponseAssertionSubject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        RESPONSE_ASSERTION_BRAND in value &&
+        value[RESPONSE_ASSERTION_BRAND] === true);
+}
+/**
+ * Returns a header value by case-insensitive name.
+ *
+ * @param headers - Flat response header map.
+ * @param name - Header name to look up.
+ * @returns Header value or undefined when absent.
+ */
+function getHeader(headers, name) {
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Parses the response body as JSON, throwing when invalid.
+ *
+ * @param body - Raw response body text.
+ * @returns Parsed JSON value.
+ */
+function parseJsonBody(body) {
+    return JSON.parse(body);
+}
+/**
+ * Returns whether the Content-Type header indicates JSON.
+ *
+ * @param headers - Flat response header map.
+ * @returns True when content-type includes "json".
+ */
+function isJsonContentType(headers) {
+    const contentType = getHeader(headers, 'content-type');
+    return contentType !== undefined && contentType.toLowerCase().includes('json');
+}
+/**
+ * Deep-compares two values using JSON serialization (matches Chai eql semantics for plain objects).
+ *
+ * @param actual - Parsed response JSON.
+ * @param expected - Expected object shape.
+ * @returns True when deeply equal.
+ */
+function deepEqualJson(actual, expected) {
+    return JSON.stringify(actual) === JSON.stringify(expected);
+}
+/**
+ * Builds a branded response facade from a send result for Chai assertion subjects.
+ *
+ * @param resp - HTTP response from the completed send.
+ * @returns Branded subject passed to `scriptExpect` for `hc.response.to`.
+ */
+export function createResponseAssertionSubject(resp) {
+    const subject = {
+        code: resp.status,
+        statusText: resp.statusText,
+        headers: resp.headers,
+        body: resp.body,
+        responseTime: resp.timeMs,
+        sizeBytes: resp.sizeBytes,
+        [RESPONSE_ASSERTION_BRAND]: true
+    };
+    return subject;
+}
+/**
+ * Runs a Chai assertion with optional expected/actual placeholders for strict typing.
+ *
+ * @param assertion - Chai assertion instance.
+ * @param expr - Expression that must be truthy for the assertion to pass.
+ * @param message - Failure message when expr is false.
+ * @param negateMessage - Failure message when expr is true under negation.
+ * @param expected - Optional expected value for message interpolation.
+ * @param actual - Optional actual value for message interpolation.
+ */
+function assertMatch(assertion, expr, message, negateMessage, expected, actual) {
+    assertion.assert(expr, message, negateMessage, expected, actual);
+}
+/**
+ * Reads the branded response subject from a Chai assertion or throws a scope error.
+ *
+ * @param assertion - Chai assertion instance (`this` inside a matcher).
+ * @param utils - Chai plugin utilities.
+ * @returns Branded response subject.
+ */
+function requireResponseSubject(assertion, utils) {
+    const subject = utils.flag(assertion, 'object');
+    if (!isResponseAssertionSubject(subject)) {
+        throw new Error(RESPONSE_SCOPE_ERROR);
+    }
+    return subject;
+}
+/**
+ * Registers Postman-style response matchers on the Chai Assertion prototype.
+ *
+ * Must run before SES `lockdown()` in the script runner import chain.
+ *
+ * @param chai - Chai module instance from the script sandbox host.
+ */
+export function installResponseAssertions(chai) {
+    const { Assertion } = chai;
+    const utils = chai.util;
+    /**
+     * Asserts HTTP status code or status text.
+     *
+     * @param codeOrText - Numeric status code or status text string.
+     */
+    utils.addMethod(Assertion.prototype, 'status', function statusMatcher(codeOrText) {
+        const res = requireResponseSubject(this, utils);
+        if (typeof codeOrText === 'number') {
+            assertMatch(this, res.code === codeOrText, `expected response to have status code #{exp} but got #{act}`, `expected response to not have status code #{exp}`, codeOrText, res.code);
+        }
+        else {
+            const expected = String(codeOrText).toLowerCase();
+            const actual = res.statusText.toLowerCase();
+            assertMatch(this, actual === expected, `expected response to have status text #{exp} but got #{act}`, `expected response to not have status text #{exp}`, codeOrText, res.statusText);
+        }
+    }, 'have');
+    /**
+     * Asserts response header presence or header value.
+     *
+     * @param name - Header name (case-insensitive).
+     * @param value - Optional expected header value.
+     */
+    utils.addMethod(Assertion.prototype, 'header', function headerMatcher(name, value) {
+        const res = requireResponseSubject(this, utils);
+        const headerName = String(name);
+        const actual = getHeader(res.headers, headerName);
+        if (value === undefined) {
+            assertMatch(this, actual !== undefined, `expected response to have header #{exp}`, `expected response to not have header #{exp}`, headerName);
+        }
+        else {
+            const expected = String(value);
+            assertMatch(this, actual === expected, `expected response header #{exp} to equal #{act}`, `expected response header #{exp} to not equal #{act}`, `${headerName}=${expected}`, actual === undefined ? undefined : `${headerName}=${actual}`);
+        }
+    }, 'have');
+    /**
+     * Asserts response body content.
+     *
+     * @param expected - When omitted, body must be non-empty; string for exact match; RegExp for pattern.
+     */
+    utils.addMethod(Assertion.prototype, 'body', function bodyMatcher(expected) {
+        const res = requireResponseSubject(this, utils);
+        if (expected === undefined) {
+            assertMatch(this, res.body.length > 0, 'expected response to have a body', 'expected response to not have a body');
+        }
+        else if (expected instanceof RegExp) {
+            assertMatch(this, expected.test(res.body), `expected response body to match #{exp}`, `expected response body to not match #{exp}`, expected, res.body);
+        }
+        else {
+            const expectedText = String(expected);
+            assertMatch(this, res.body === expectedText, `expected response body to equal #{exp}`, `expected response body to not equal #{exp}`, expectedText, res.body);
+        }
+    }, 'have');
+    /**
+     * Asserts the response body is valid JSON, optionally deep-equal to an expected object.
+     *
+     * @param expected - When provided, parsed body must deeply equal this value.
+     */
+    utils.addMethod(Assertion.prototype, 'jsonBody', function jsonBodyMatcher(expected) {
+        const res = requireResponseSubject(this, utils);
+        let parsed;
+        try {
+            parsed = parseJsonBody(res.body);
+        }
+        catch {
+            assertMatch(this, false, 'expected response body to be valid JSON', 'expected response body to not be valid JSON');
+            return;
+        }
+        if (expected !== undefined) {
+            assertMatch(this, deepEqualJson(parsed, expected), `expected response JSON body to deeply equal #{exp}`, `expected response JSON body to not deeply equal #{exp}`, expected, parsed);
+        }
+    }, 'have');
+    /**
+     * Registers a boolean status-class property on the assertion chain after `be`.
+     *
+     * @param name - Property name exposed as `.to.be.<name>`.
+     * @param predicate - Returns true when the response matches the status class.
+     * @param label - Human-readable label for assertion messages.
+     */
+    function addStatusClassProperty(name, predicate, label) {
+        utils.addProperty(Assertion.prototype, name, wrapCallablePropertyGetter(function statusClassProperty() {
+            const res = requireResponseSubject(this, utils);
+            assertMatch(this, predicate(res.code), `expected response to be ${label} but got status #{act}`, `expected response to not be ${label}`, undefined, res.code);
+        }), 'be');
+    }
+    addStatusClassProperty('success', (code) => code >= 200 && code < 300, 'successful (2xx)');
+    addStatusClassProperty('redirection', (code) => code >= 300 && code < 400, 'a redirection (3xx)');
+    addStatusClassProperty('clientError', (code) => code >= 400 && code < 500, 'a client error (4xx)');
+    addStatusClassProperty('serverError', (code) => code >= 500 && code < 600, 'a server error (5xx)');
+    addStatusClassProperty('error', (code) => code >= 400, 'an error (4xx or 5xx)');
+    /**
+     * Extends Chai's truthy `.to.be.ok` with a 2xx check when the subject is hc.response.
+     */
+    Assertion.overwriteProperty('ok', function okProperty(superFn) {
+        return function okPropertyGetter() {
+            const subject = utils.flag(this, 'object');
+            if (!isResponseAssertionSubject(subject)) {
+                superFn.call(this);
+                return;
+            }
+            assertMatch(this, subject.code >= 200 && subject.code < 300, 'expected response to be ok (2xx) but got status #{act}', 'expected response to not be ok (2xx)', undefined, subject.code);
+        };
+    });
+    addStatusClassProperty('accepted', (code) => code === 202, 'Accepted (202)');
+    addStatusClassProperty('badRequest', (code) => code === 400, 'Bad Request (400)');
+    addStatusClassProperty('unauthorized', (code) => code === 401, 'Unauthorized (401)');
+    addStatusClassProperty('forbidden', (code) => code === 403, 'Forbidden (403)');
+    addStatusClassProperty('notFound', (code) => code === 404, 'Not Found (404)');
+    addStatusClassProperty('rateLimited', (code) => code === 429, 'Too Many Requests (429)');
+    utils.addProperty(Assertion.prototype, 'json', wrapCallablePropertyGetter(function jsonProperty() {
+        const res = requireResponseSubject(this, utils);
+        let parses = false;
+        try {
+            parseJsonBody(res.body);
+            parses = true;
+        }
+        catch {
+            parses = false;
+        }
+        const hasJsonType = isJsonContentType(res.headers);
+        assertMatch(this, hasJsonType && parses, 'expected response to be JSON (content-type and valid JSON body)', 'expected response to not be JSON');
+    }), 'be');
+    utils.addProperty(Assertion.prototype, 'withBody', wrapCallablePropertyGetter(function withBodyProperty() {
+        const res = requireResponseSubject(this, utils);
+        assertMatch(this, res.body.length > 0, 'expected response to have a body', 'expected response to not have a body');
+    }), 'be');
+}
+//# sourceMappingURL=scriptResponseAssertions.js.map

package/dist/scripting/scriptResponseAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptResponseAssertions.js","sourceRoot":"","sources":["../../src/scripting/scriptResponseAssertions.ts"],"names":[],"mappings":"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"}

package/dist/scripting/scriptResponseDocument.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Element surface exposed to post-request scripts for HTML response querying.
+ */
+export interface ScriptElementFacade {
+    /**
+     * Concatenated text content of the element and its descendants.
+     */
+    textContent: string;
+    /**
+     * Returns the named attribute value, or null when absent.
+     *
+     * @param name - Attribute name (case-sensitive per HTML rules).
+     */
+    getAttribute(name: string): string | null;
+    /**
+     * Serialized inner HTML of the element's children.
+     */
+    innerHTML: string;
+}
+/**
+ * Document surface backed by Cheerio for querying HTML response bodies.
+ */
+export interface ScriptDocumentFacade {
+    /**
+     * Returns the first element matching a CSS selector, or null when none match.
+     *
+     * @param selector - CSS selector understood by Cheerio.
+     */
+    querySelector(selector: string): ScriptElementFacade | null;
+    /**
+     * Returns every element matching a CSS selector.
+     *
+     * @param selector - CSS selector understood by Cheerio.
+     */
+    querySelectorAll(selector: string): ScriptElementFacade[];
+}
+/**
+ * Parses an HTML response body into a DOM-like document facade for script sandboxes.
+ *
+ * Uses Cheerio under the hood; returned objects are plain facades without exposing
+ * the Cheerio instance to user scripts.
+ *
+ * @param html - Raw response body string.
+ * @returns Document with querySelector helpers.
+ */
+export declare function parseResponseDocument(html: string): ScriptDocumentFacade;
+//# sourceMappingURL=scriptResponseDocument.d.ts.map

package/dist/scripting/scriptResponseDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptResponseDocument.d.ts","sourceRoot":"","sources":["../../src/scripting/scriptResponseDocument.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAE1C;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IAE5D;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAAC;CAC3D;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAgBxE"}