@usebruno/js 0.46.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usebruno/js",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "license": "MIT",
   "main": "src/index.js",
   "files": [
@@ -13,17 +13,18 @@
     "prepack": "npm run test"
   },
   "dependencies": {
-    "@usebruno/common": "0.20.0",
-    "@usebruno/query": "0.2.0",
+    "@usebruno/common": "0.21.0",
+    "@usebruno/query": "0.2.2",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "atob": "^2.1.2",
-    "axios": "^1.8.3",
+    "axios": "1.13.6",
     "btoa": "^1.2.1",
     "chai": "^4.3.7",
     "chai-string": "^1.5.0",
     "cheerio": "^1.0.0",
     "crypto-js": "^4.2.0",
+    "handlebars": "^4.7.9",
     "json-query": "^2.2.2",
     "jsonwebtoken": "^9.0.3",
     "lodash": "^4.17.21",
@@ -33,7 +34,7 @@
     "path": "^0.12.7",
     "quickjs-emscripten": "^0.29.2",
     "tv4": "^1.3.0",
-    "uuid": "^9.0.0",
+    "uuid": "^10.0.0",
     "xml-formatter": "^3.5.0",
     "xml2js": "^0.6.2",
     "yaml": "^2.3.4"
@@ -41,7 +42,7 @@
   "devDependencies": {
     "@rollup/plugin-commonjs": "^23.0.2",
     "@rollup/plugin-node-resolve": "^15.0.1",
-    "rollup": "3.29.5",
-    "rollup-plugin-terser": "^7.0.2"
+    "@rollup/plugin-terser": "^1.0.0",
+    "rollup": "3.30.0"
   }
 }

package/src/bru.js

@@ -3,31 +3,90 @@ const { uuid } = require('./utils');
 const xmlFormat = require('xml-formatter');
 const { interpolate: _interpolate } = require('@usebruno/common');
 const { sendRequest, createSendRequest } = require('@usebruno/requests').scripting;
-const { jar: createCookieJar } = require('@usebruno/requests').cookies;
-
+const { jar: createCookieJar, getCookiesForUrl } = require('@usebruno/requests').cookies;
+const CookieList = require('./cookie-list');
+const Handlebars = require('handlebars');
+
+const VISUALIZATION_CLEAR = '__clear__';
+const MAX_TEMPLATE_LENGTH = 1_000_000; // 1 million characters
+/*
+ * All Handlebars.compile() options (v4.x):
+ *   data                    - set false to disable @data tracking
+ *   compat                  - enable recursive field lookup
+ *   knownHelpers            - hash of helpers known at compile time (optimization)
+ *   knownHelpersOnly        - only allow known helpers (optimization)       [SAFE]
+ *   noEscape                - skip HTML escaping of content                 [SAFE]
+ *   strict                  - throw on missing fields instead of ignoring   [SAFE]
+ *   assumeObjects           - skip object existence checks on paths         [SAFE]
+ *   preventIndent           - disable auto-indent for partials              [SAFE]
+ *   ignoreStandalone        - disable standalone tag removal                [SAFE]
+ *   explicitPartialContext  - disable implicit context for partials         [SAFE]
+ *
+ * Excluded from allowlist:
+ *   data, compat, knownHelpers - can alter template resolution in unexpected ways
+ *   allowProtoPropertiesByDefault, allowProtoMethodsByDefault - defense-in-depth against
+ *     prototype traversal. Handlebars >=4.3.0 fixed the original CVE-2019-19919 and >=4.7.0
+ *     hardcodes blocks on __proto__, constructor, etc. even when these flags are true, but
+ *     we still exclude them to avoid relaxing the security posture.
+ *     https://nvd.nist.gov/vuln/detail/CVE-2019-19919
+ *
+ * Use `dangerouslyAllowAllOptions: true` in data.options to bypass the allowlist.
+ */
+const SAFE_HBS_OPTIONS = new Set([
+  'noEscape', 'strict', 'assumeObjects', 'preventIndent',
+  'ignoreStandalone', 'explicitPartialContext', 'knownHelpersOnly'
+]);
 const variableNameRegex = /^[\w-.]*$/;
 
 class Bru {
   /**
-   * @param {string} runtime - The runtime environment ('quickjs' or 'nodevm')
-   * @param {object} envVariables - Environment variables
-   * @param {object} runtimeVariables - Runtime variables
-   * @param {object} processEnvVars - Process environment variables
-   * @param {string} collectionPath - Path to the collection
-   * @param {function} historyLogger - History logger function
-   * @param {function} setVisualizations - Visualizations setter function
-   * @param {object} secretVariables - Secret variables
-   * @param {object} collectionVariables - Collection-level variables
-   * @param {object} folderVariables - Folder-level variables
-   * @param {object} requestVariables - Request-level variables
-   * @param {object} globalEnvironmentVariables - Global environment variables
-   * @param {object} oauth2CredentialVariables - OAuth2 credential variables
-   * @param {object} iterationDetails - Iteration details for runner
-   * @param {string} collectionName - Name of the collection
-   * @param {object} promptVariables - Prompt variables
-   * @param {object} certsAndProxyConfig - Configuration for bru.sendRequest (proxy, certs, TLS)
+   * @param {object} options - Single options object (destructured)
+   * @property {string} options.runtime - The runtime environment ('quickjs' or 'nodevm')
+   * @property {object} [options.envVariables={}] - Environment variables
+   * @property {object} [options.runtimeVariables={}] - Runtime variables
+   * @property {object} [options.processEnvVars={}] - Process environment variables (deep cloned)
+   * @property {string} [options.collectionPath] - Path to the collection
+   * @property {function} [options.historyLogger] - History logger function
+   * @property {function} [options.setVisualizations] - Visualizations setter function
+   * @property {object} [options.secretVariables={}] - Secret variables (deep cloned)
+   * @property {object} [options.collectionVariables={}] - Collection-level variables
+   * @property {object} [options.folderVariables={}] - Folder-level variables
+   * @property {object} [options.requestVariables={}] - Request-level variables
+   * @property {object} [options.globalEnvironmentVariables={}] - Global environment variables
+   * @property {object} [options.oauth2CredentialVariables={}] - OAuth2 credential variables
+   * @property {object} [options.iterationDetails] - Iteration details for runner
+   * @property {string} [options.collectionName] - Name of the collection
+   * @property {object} [options.promptVariables={}] - Prompt variables
+   * @property {object} [options.certsAndProxyConfig] - Configuration for bru.sendRequest (proxy, certs, TLS)
+   * @property {string} [options.certsAndProxyConfig.collectionPath] - Path to the collection
+   * @property {object} [options.certsAndProxyConfig.options] - TLS and proxy options
+   * @property {object} [options.certsAndProxyConfig.clientCertificates] - Client certificate configuration
+   * @property {object} [options.certsAndProxyConfig.collectionLevelProxy] - Collection-level proxy settings
+   * @property {object} [options.certsAndProxyConfig.systemProxyConfig] - System proxy configuration
+   * @property {string} [options.requestUrl] - The URL of the current request (used for cookie access)
+   * @property {function} [options.onConsoleLog] - Console callback `(type, args) => void` to route warnings to the UI
    */
-  constructor(runtime, envVariables, runtimeVariables, processEnvVars, collectionPath, historyLogger, setVisualizations, secretVariables, collectionVariables, folderVariables, requestVariables, globalEnvironmentVariables, oauth2CredentialVariables, iterationDetails, collectionName, promptVariables, certsAndProxyConfig) {
+  constructor({
+    runtime,
+    envVariables,
+    runtimeVariables,
+    processEnvVars,
+    collectionPath,
+    historyLogger,
+    setVisualizations,
+    secretVariables,
+    collectionVariables,
+    folderVariables,
+    requestVariables,
+    globalEnvironmentVariables,
+    oauth2CredentialVariables,
+    iterationDetails,
+    collectionName,
+    promptVariables,
+    certsAndProxyConfig,
+    requestUrl,
+    onConsoleLog
+  }) {
     this.envVariables = envVariables || {};
     this.runtimeVariables = runtimeVariables || {};
     this.promptVariables = promptVariables || {};
@@ -41,58 +100,18 @@ class Bru {
     this.collectionPath = collectionPath;
     this.historyLogger = historyLogger;
     this.setVisualizations = setVisualizations;
+    this.onConsoleLog = onConsoleLog || null;
     this.collectionName = collectionName;
     // Use createSendRequest with config if provided, otherwise use default sendRequest
     this.sendRequest = certsAndProxyConfig ? createSendRequest(certsAndProxyConfig) : sendRequest;
     this.runtime = runtime;
-    this.cookies = {
-      jar: () => {
-        const cookieJar = createCookieJar();
-
-        return {
-          getCookie: (url, cookieName, callback) => {
-            const interpolatedUrl = this.interpolate(url);
-            return cookieJar.getCookie(interpolatedUrl, cookieName, callback);
-          },
-
-          getCookies: (url, callback) => {
-            const interpolatedUrl = this.interpolate(url);
-            return cookieJar.getCookies(interpolatedUrl, callback);
-          },
-
-          setCookie: (url, nameOrCookieObj, valueOrCallback, maybeCallback) => {
-            const interpolatedUrl = this.interpolate(url);
-            return cookieJar.setCookie(interpolatedUrl, nameOrCookieObj, valueOrCallback, maybeCallback);
-          },
-
-          setCookies: (url, cookiesArray, callback) => {
-            const interpolatedUrl = this.interpolate(url);
-            return cookieJar.setCookies(interpolatedUrl, cookiesArray, callback);
-          },
-
-          // Clear entire cookie jar
-          clear: (callback) => {
-            return cookieJar.clear(callback);
-          },
-
-          // Delete cookies for a specific URL/domain
-          deleteCookies: (url, callback) => {
-            const interpolatedUrl = this.interpolate(url);
-            return cookieJar.deleteCookies(interpolatedUrl, callback);
-          },
-
-          deleteCookie: (url, cookieName, callback) => {
-            const interpolatedUrl = this.interpolate(url);
-            return cookieJar.deleteCookie(interpolatedUrl, cookieName, callback);
-          },
-
-          hasCookie: (url, cookieName, callback) => {
-            const interpolatedUrl = this.interpolate(url);
-            return cookieJar.hasCookie(interpolatedUrl, cookieName, callback);
-          }
-        };
-      }
-    };
+    this.requestUrl = requestUrl;
+    this.cookies = new CookieList({
+      getUrl: () => this.interpolate(this.requestUrl),
+      interpolate: (str) => this.interpolate(str),
+      createCookieJar,
+      getCookiesForUrl
+    });
     // Holds variables that are marked as persistent by scripts
     this.persistentEnvVariables = {};
     // Holds credential IDs to be reset after script execution
@@ -414,9 +433,41 @@ class Bru {
     return this.secretVariables?.[`$secrets.${key}`];
   }
 
+  /**
+   * Render a visualization in the response pane.
+   *
+   * @param {'table' | 'html'} type - The visualization type.
+   * @param {Object} data - Shape depends on `type`:
+   *
+   *   **When `type` is `'table'`:**
+   *   @param {string}  data.provider             - `'ag-grid'` or `'react-table'`.
+   *   @param {Object}  data.props                - Props forwarded to the grid component.
+   *   @param {Array}   data.props.columnDefinitions - (ag-grid) Column definitions.
+   *   @param {Array}   data.props.rowData           - (ag-grid) Row data.
+   *
+   *   **When `type` is `'html'`** (raw mode):
+   *   @param {string}  data.content              - Pre-rendered HTML string.
+   *
+   *   **When `type` is `'html'`** (Handlebars template mode):
+   *   @param {string}  data.template             - Handlebars template string (required).
+   *   @param {Object}  [data.data={}]            - Context object passed to the compiled template.
+   *   @param {Object}  [data.options]            - Handlebars compile options.
+   *   @param {boolean} [data.options.noEscape]    - Disable HTML escaping.
+   *   @param {boolean} [data.options.strict]      - Throw on missing variables.
+   *   @param {boolean} [data.options.assumeObjects] - Skip null checks on nested paths.
+   *   @param {boolean} [data.options.dangerouslyAllowAllOptions] - Bypass the safe-options
+   *     allowlist (forwards all remaining options directly to `Handlebars.compile`).
+   *
+   * @throws {Error} If `type` is falsy.
+   * @throws {Error} If `type` is `'html'` and neither `data.content` nor `data.template` is provided.
+   * @throws {Error} If template exceeds `MAX_TEMPLATE_LENGTH`.
+   */
   visualize(type, data) {
-    if (type == 'table') {
-      if (data?.provider == 'ag-grid') {
+    if (!type) {
+      throw new Error('visualization type is required');
+    }
+    if (type === 'table') {
+      if (data?.provider === 'ag-grid') {
         if (!data?.props?.columnDefinitions) {
           throw new Error(`columns definitions are required`);
         }
@@ -424,17 +475,63 @@ class Bru {
           throw new Error(`row data is required`);
         }
         this.setVisualizations({ uid: uuid(), type, data });
-      } else if (data?.provider == 'react-table') {
+      } else if (data?.provider === 'react-table') {
         this.setVisualizations({ uid: uuid(), type, data });
       }
-    } else if (type == 'html') {
-      if (!data?.content) {
-        throw new Error(`html content is required`);
+    } else if (type === 'html') {
+      if (typeof data?.template === 'string') {
+        // Handlebars template mode (translated from pm.visualizer.set)
+        if (data.template.length > MAX_TEMPLATE_LENGTH) {
+          throw new Error(`template exceeds maximum length of ${MAX_TEMPLATE_LENGTH} characters`);
+        }
+        // Isolated instance so globally-registered helpers can't be exploited (SSTI prevention)
+        const hbs = Handlebars.create();
+        // Allowlist safe compile options to prevent re-enabling prototype traversal (CVE-2019-19919)
+        let compileOptions;
+        if (data.options?.dangerouslyAllowAllOptions) {
+          const { dangerouslyAllowAllOptions, ...rest } = data.options;
+          compileOptions = rest;
+        } else {
+          compileOptions = {};
+          if (data.options) {
+            const blocked = [];
+            for (const key of Object.keys(data.options)) {
+              if (SAFE_HBS_OPTIONS.has(key)) {
+                compileOptions[key] = data.options[key];
+              } else {
+                blocked.push(key);
+              }
+            }
+            if (blocked.length > 0) {
+              const msg = `bru.visualize: the following compile options were blocked and ignored: ${blocked.map((k) => `"${k}"`).join(', ')}. `
+                + 'Use { dangerouslyAllowAllOptions: true } in options to bypass the allowlist.';
+              if (this.onConsoleLog) {
+                this.onConsoleLog('warn', [msg]);
+              } else {
+                console.warn(msg);
+              }
+            }
+          }
+        }
+        const compiled = hbs.compile(data.template, compileOptions);
+        const renderedHtml = compiled(data.data || {});
+        this.setVisualizations({
+          uid: uuid(), type,
+          data: { content: renderedHtml, rawData: data.data || {} }
+        });
+      } else if (data?.content) {
+        // Existing raw HTML mode
+        this.setVisualizations({ uid: uuid(), type, data });
+      } else {
+        throw new Error('html content or template is required');
       }
-      this.setVisualizations({ uid: uuid(), type, data });
     }
   }
 
+  clearVisualizations() {
+    this.setVisualizations({ type: VISUALIZATION_CLEAR });
+  }
+
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -488,3 +585,4 @@ class IterationDataManager {
 }
 
 module.exports = Bru;
+module.exports.VISUALIZATION_CLEAR = VISUALIZATION_CLEAR;

package/src/bruno-request.js

@@ -98,6 +98,8 @@ class BrunoRequest {
   getAuthMode() {
     if (this.req?.oauth2) {
       return 'oauth2';
+    } else if (this.req?.oauth1config) {
+      return 'oauth1';
     } else if (this.headers?.['Authorization']?.startsWith('Bearer')) {
       return 'bearer';
     } else if (this.headers?.['Authorization']?.startsWith('Basic') || this.req?.auth?.username) {

package/src/cookie-list.js

@@ -0,0 +1,272 @@
+const PropertyList = require('./property-list');
+
+/**
+ * CookieList — the `bru.cookies` API for reading and writing cookies in scripts.
+ *
+ * Extends PropertyList in dynamic mode: the cookie list is freshly read from the
+ * cookie jar on every access, and write operations delegate to the jar rather
+ * than mutating an in-memory array.
+ *
+ * ---
+ *
+ * ## Cookie object shape
+ *
+ * Every cookie surfaced by this list is a plain object:
+ *
+ * ```js
+ * { key, value, domain, path, secure, httpOnly, expires }
+ * ```
+ *
+ * ---
+ *
+ * ## Read methods (inherited from ReadOnlyPropertyList)
+ *
+ * | Method             | Description                                      | Example return value                  |
+ * |--------------------|--------------------------------------------------|---------------------------------------|
+ * | `get(name)`        | Value of the first cookie with `key === name`    | `'abc123'`                            |
+ * | `one(name)`        | Full cookie object for `key === name`            | `{ key: 'sid', value: 'abc123', … }`  |
+ * | `all()`            | Cloned array of all cookie objects               | `[{ key: 'sid', … }, …]`             |
+ * | `idx(index)`       | Cookie at positional index                       | `{ key: 'sid', … }`                   |
+ * | `count()`          | Number of cookies for the current request URL    | `3`                                   |
+ *
+ * ## Search methods (inherited)
+ *
+ * | Method             | Description                                      | Example return value |
+ * |--------------------|--------------------------------------------------|----------------------|
+ * | `has(name)`        | `true` if a cookie with that key exists          | `true`               |
+ * | `has(name, value)` | `true` if key exists **and** value matches        | `false`              |
+ * | `find(predicate)`  | First cookie matching the predicate function     | `{ key: 'sid', … }` |
+ * | `filter(predicate)`| Array of cookies matching the predicate          | `[{ key: … }, …]`   |
+ * | `indexOf(item)`    | Index of a structurally-equal cookie, or `-1`    | `0`                  |
+ *
+ * ## Iteration methods (inherited)
+ *
+ * | Method                  | Description                                  |
+ * |-------------------------|----------------------------------------------|
+ * | `each(fn)`              | Calls `fn(cookie, index)` for every cookie   |
+ * | `map(fn)`               | Returns a new array of mapped values         |
+ * | `reduce(fn, initial?)`  | Reduces cookies to a single value            |
+ *
+ * ## Transform methods (inherited)
+ *
+ * | Method        | Description                                         | Example return value               |
+ * |---------------|-----------------------------------------------------|-------------------------------------|
+ * | `toObject()`  | `{ key: value }` map of all cookies                 | `{ sid: 'abc123', lang: 'en' }`     |
+ * | `toString()`  | Semicolon-separated `key=value` string               | `'sid=abc123; lang=en'`             |
+ * | `toJSON()`    | Same as `all()` — suitable for `JSON.stringify()`    | `[{ key: 'sid', … }]`              |
+ *
+ * ## Write methods (CookieList overrides)
+ *
+ * | Method                   | Description                                          |
+ * |--------------------------|------------------------------------------------------|
+ * | `add(cookieObj, cb?)`    | Alias for `upsert()` — sets a cookie in the jar      |
+ * | `upsert(cookieObj, cb?)` | Sets (or replaces) a cookie in the jar                |
+ * | `remove(name, cb?)`      | Deletes a single cookie by name (no-op if missing)    |
+ * | `delete(name, cb?)`      | Alias for `remove()`                                  |
+ * | `clear(cb?)`             | Removes **all** cookies for the current request URL   |
+ *
+ * ## Jar access
+ *
+ * | Method  | Description                                                              |
+ * |---------|--------------------------------------------------------------------------|
+ * | `jar()` | Returns a jar handle with URL interpolation for cross-URL cookie access  |
+ *
+ * The jar handle exposes: `getCookie`, `getCookies`, `setCookie`, `setCookies`,
+ * `deleteCookie`, `deleteCookies`, `hasCookie`, and `clear`.
+ */
+class CookieList extends PropertyList {
+  /**
+   * @param {object} options
+   * @param {Function} options.getUrl - Returns the interpolated request URL (or falsy if unavailable)
+   * @param {Function} options.interpolate - Interpolates variables in a string
+   * @param {Function} options.createCookieJar - Factory that returns a cookie jar instance
+   * @param {Function} options.getCookiesForUrl - Returns cookies array for a given URL
+   */
+  constructor({ getUrl, interpolate, createCookieJar, getCookiesForUrl }) {
+    super({
+      keyProperty: 'key',
+      dataSource: () => {
+        const url = getUrl();
+        if (!url) return [];
+        // Normalize tough-cookie Cookie instances to plain objects to avoid
+        // circular references and exposing internal library structures.
+        return getCookiesForUrl(url).map(({ key, value, domain, path, secure, httpOnly, expires }) =>
+          ({ key, value, domain, path, secure, httpOnly, expires })
+        );
+      }
+    });
+    this._getUrl = getUrl;
+    this._interpolateFn = interpolate;
+    // Factory function — returns a wrapper around the module-level cookie jar singleton
+    this._createCookieJar = createCookieJar;
+  }
+
+  // ── Write methods (cookie jar delegation) ─────────────────────────────
+
+  /**
+   * Add a cookie to the jar (alias for {@link CookieList#upsert}).
+   *
+   * @param {object} cookieObj - Cookie object with at least `key` and `value`.
+   * @param {Function} [callback] - Optional `(error) => void` callback. If omitted, returns a Promise.
+   * @returns {Promise<void>|void} A Promise when no callback is given.
+   * @example
+   * // Promise usage
+   * await bru.cookies.add({ key: 'lang', value: 'en' });
+   *
+   * // Callback usage
+   * bru.cookies.add({ key: 'lang', value: 'en' }, (err) => { if (err) throw err; });
+   */
+  add(cookieObj, callback) {
+    return this.upsert(cookieObj, callback);
+  }
+
+  /**
+   * Set (or replace) a cookie in the jar for the current request URL.
+   *
+   * If a cookie with the same key already exists for this URL, it is overwritten.
+   * Rejects with an error if `cookieObj` is not a non-null object.
+   *
+   * @param {object} cookieObj - Cookie object with at least `key` and `value`.
+   * @param {Function} [callback] - Optional `(error) => void` callback. If omitted, returns a Promise.
+   * @returns {Promise<void>|void} A Promise when no callback is given.
+   * @example
+   * await bru.cookies.upsert({ key: 'sid', value: 'abc123', secure: true });
+   */
+  upsert(cookieObj, callback) {
+    if (!cookieObj || typeof cookieObj !== 'object') {
+      const error = new Error('cookieObj must be a non-null object');
+      if (callback) return callback(error);
+      return Promise.reject(error);
+    }
+    const url = this._getUrl();
+    if (!url) {
+      if (callback) return callback(undefined);
+      return Promise.resolve();
+    }
+    const jar = this._createCookieJar();
+    return jar.setCookie(url, cookieObj, callback);
+  }
+
+  /**
+   * Remove a single cookie by name from the current request URL.
+   *
+   * A no-op if `name` is falsy or if no cookie with that name exists
+   * (analogous to `Map.prototype.delete`).
+   *
+   * @param {string} name - The cookie key to remove.
+   * @param {Function} [callback] - Optional `(error) => void` callback. If omitted, returns a Promise.
+   * @returns {Promise<void>|void} A Promise when no callback is given.
+   * @example
+   * await bru.cookies.remove('sid');
+   */
+  remove(name, callback) {
+    const url = this._getUrl();
+    if (!url || !name) {
+      if (callback) return callback(undefined);
+      return Promise.resolve();
+    }
+    const jar = this._createCookieJar();
+    return jar.deleteCookie(url, name, callback);
+  }
+
+  /**
+   * Remove cookies scoped to the current request URL only.
+   * Unlike jar().clear() which removes ALL cookies globally, this only
+   * removes cookies matching the current request's domain and path.
+   */
+  clear(callback) {
+    const url = this._getUrl();
+    if (!url) {
+      if (callback) return callback(undefined);
+      return Promise.resolve();
+    }
+    const jar = this._createCookieJar();
+    return jar.deleteCookies(url, callback);
+  }
+
+  /**
+   * Delete a cookie by name (alias for {@link CookieList#remove}).
+   *
+   * @param {string} name - The cookie key to delete.
+   * @param {Function} [callback] - Optional `(error) => void` callback. If omitted, returns a Promise.
+   * @returns {Promise<void>|void} A Promise when no callback is given.
+   * @example
+   * await bru.cookies.delete('sid');
+   */
+  delete(name, callback) {
+    return this.remove(name, callback);
+  }
+
+  // ── Cookie-specific method ────────────────────────────────────────────
+
+  /**
+   * Returns a jar handle for cross-URL cookie operations.
+   *
+   * Unlike the CookieList methods (which are scoped to the current request URL),
+   * the jar handle lets you read/write cookies for **any** URL. All URL arguments
+   * are automatically interpolated with environment/collection variables.
+   *
+   * @returns {{ getCookie, getCookies, setCookie, setCookies, deleteCookie, deleteCookies, hasCookie, clear }}
+   * @example
+   * const jar = bru.cookies.jar();
+   *
+   * // Read a cookie from a different URL
+   * const token = await jar.getCookie('{{authBaseUrl}}/login', 'access_token');
+   *
+   * // Set a cookie on a specific URL
+   * await jar.setCookie('{{apiBaseUrl}}', { key: 'sid', value: 'abc' });
+   * await jar.setCookie('{{apiBaseUrl}}', 'theme', 'dark');
+   *
+   * // Check if a cookie exists
+   * const exists = await jar.hasCookie('{{apiBaseUrl}}', 'sid');
+   *
+   * // Clear ALL cookies globally
+   * await jar.clear();
+   */
+  jar() {
+    const cookieJar = this._createCookieJar();
+
+    return {
+      getCookie: (url, cookieName, callback) => {
+        const interpolatedUrl = this._interpolateFn(url);
+        return cookieJar.getCookie(interpolatedUrl, cookieName, callback);
+      },
+
+      getCookies: (url, callback) => {
+        const interpolatedUrl = this._interpolateFn(url);
+        return cookieJar.getCookies(interpolatedUrl, callback);
+      },
+
+      setCookie: (url, nameOrCookieObj, valueOrCallback, maybeCallback) => {
+        const interpolatedUrl = this._interpolateFn(url);
+        return cookieJar.setCookie(interpolatedUrl, nameOrCookieObj, valueOrCallback, maybeCallback);
+      },
+
+      setCookies: (url, cookiesArray, callback) => {
+        const interpolatedUrl = this._interpolateFn(url);
+        return cookieJar.setCookies(interpolatedUrl, cookiesArray, callback);
+      },
+
+      clear: (callback) => {
+        return cookieJar.clear(callback);
+      },
+
+      deleteCookies: (url, callback) => {
+        const interpolatedUrl = this._interpolateFn(url);
+        return cookieJar.deleteCookies(interpolatedUrl, callback);
+      },
+
+      deleteCookie: (url, cookieName, callback) => {
+        const interpolatedUrl = this._interpolateFn(url);
+        return cookieJar.deleteCookie(interpolatedUrl, cookieName, callback);
+      },
+
+      hasCookie: (url, cookieName, callback) => {
+        const interpolatedUrl = this._interpolateFn(url);
+        return cookieJar.hasCookie(interpolatedUrl, cookieName, callback);
+      }
+    };
+  }
+}
+
+module.exports = CookieList;

package/src/index.js

@@ -3,7 +3,21 @@ const TestRuntime = require('./runtime/test-runtime');
 const VarsRuntime = require('./runtime/vars-runtime');
 const AssertRuntime = require('./runtime/assert-runtime');
 const { runScriptInNodeVm } = require('./sandbox/node-vm');
-const { formatErrorWithContext, SCRIPT_TYPES } = require('./utils/error-formatter');
+const {
+  formatErrorWithContext,
+  formatErrorWithContextV2,
+  SCRIPT_TYPES,
+  parseErrorLocation,
+  adjustLineNumber,
+  resolveSegmentError,
+  getSourceContext,
+  adjustStackTrace,
+  getErrorTypeName,
+  findScriptBlockStartLine,
+  findScriptBlockEndLine,
+  findYmlScriptBlockStartLine,
+  findYmlScriptBlockEndLine
+} = require('./utils/error-formatter');
 
 module.exports = {
   ScriptRuntime,
@@ -12,5 +26,16 @@ module.exports = {
   AssertRuntime,
   runScriptInNodeVm,
   formatErrorWithContext,
-  SCRIPT_TYPES
+  formatErrorWithContextV2,
+  SCRIPT_TYPES,
+  parseErrorLocation,
+  adjustLineNumber,
+  resolveSegmentError,
+  getSourceContext,
+  adjustStackTrace,
+  getErrorTypeName,
+  findScriptBlockStartLine,
+  findScriptBlockEndLine,
+  findYmlScriptBlockStartLine,
+  findYmlScriptBlockEndLine
 };