@bubblegum-ai/node 0.0.6-alpha.0 → 0.0.6-alpha.1

package/README.md

@@ -63,6 +63,28 @@ const r = await bg.recover({ failedSelector: "#login-btn", intent: "Click Login"
 // r.status === "recovered" when Bubblegum healed it
 ```
 
+### Parameterised dates/times (dynamic-value tokens)
+
+For date pickers (or any field) that need a value computed at run time, drop a
+`{{ ... }}` token into the step value instead of a literal that goes stale:
+
+```ts
+// Relative date in the app's display format:
+await bg.act('Enter "{{today+7d|%d/%m/%Y}}" into Start date');     // -> 23/06/2026
+await bg.act('Enter "{{now+2h|%d/%m/%Y %H:%M}}" into Appointment'); // -> 16/06/2026 04:00
+await bg.act('Enter "{{tomorrow|%d/%m/%Y}}" into End date');
+```
+
+- **Bases:** `today`, `now`, `tomorrow`, `yesterday`.
+- **Offsets (chainable, signed):** `+7d` `-3d` `+2w` `+1mo` `-1y` `+2h` `+30min` `+45s`
+  (`mo` = months, `min` = minutes — spelled out so a bare `m` is never ambiguous).
+- **Format:** anything after `|` is a `strftime` pattern. Defaults are
+  `%Y-%m-%d` for date bases and `%Y-%m-%d %H:%M` for `now`.
+
+Token-free values (and any `{{...}}` that isn't a recognised expression) are
+passed through unchanged, so existing literal steps are unaffected. Expansion
+happens engine-side, so it works identically for web, mobile, and CDP attach.
+
 ### Mobile
 
 ```ts
@@ -110,12 +132,44 @@ otherwise. CDP attach is Chromium-only.
 | `bg.isVisible / isChecked / selectedValue(target)` | `Promise<boolean \| string>` | |
 | `bg.explain(instruction)` | `Promise<string>` | dry-run rationale |
 | `bg.summary()` | `Promise<SessionSummary>` | |
+| `bg.report(opts)` | `Promise<ReportResult>` | write Allure/HTML/JSON/JUnit from the run |
 | `bg.close()` | `Promise<void>` | closes the session + bridge |
 
 `options` is forwarded verbatim to the engine (`timeout_ms`, `selector`,
 `action_type`, `value`, `assertion_type`, `expected_value`, `max_cost_level`, …),
 matching the Python how-to guides.
 
+### Reports (Allure / HTML / JSON / JUnit)
+
+The engine remembers every step a session runs, so you can emit the same reports
+the Python/pytest path produces — no pytest required. Call `bg.report(...)` once
+near the end (in a `finally`, before `close()`):
+
+```ts
+try {
+  await bg.act('Enter "tom" into Username');
+  await bg.act("Click Login");
+  await bg.verify("Dashboard is visible");
+} finally {
+  await bg.report({
+    html: "reports/run.html",      // single-file HTML
+    allure: "allure-results",      // Allure 2 dir -> `allure serve allure-results`
+    junit: "reports/junit.xml",    // CI ingestion
+    json: "reports/run.json",      // machine-readable
+    title: "Smoke run",
+    suiteName: "h365-portal",
+  });
+  await bg.close();
+}
+```
+
+Each format is optional; pass `true` instead of a path to use the default name
+(`bubblegum_report.html` / `.json` / `.xml`, `allure-results/`). Paths are
+resolved relative to the **engine process's working directory** (where the bridge
+was spawned — normally your project root). Returns
+`{ written: { html: "/abs/…", … }, steps }`. Requires the engine to advertise
+`report.write` (Bubblegum ≥ 0.0.6); older engines throw a clear error.
+
 ### Advanced: `BridgeClient`
 
 `Bubblegum` wraps a lower-level `BridgeClient` (`bg.bridge`) that you can use
@@ -129,11 +183,26 @@ The client pins to a compatible engine. It refuses to start against a
 keep serving older clients (additive-first). This package's major/minor track the
 engine; install a matching `bubblegum-ai`.
 
+## Module formats (ESM + CommonJS)
+
+This package ships **both** ES modules and CommonJS, so it works whether your
+test runner loads ESM or CJS — no `.mts` rename or loader flags needed:
+
+```ts
+import { Bubblegum } from "@bubblegum-ai/node";        // ESM / TypeScript
+```
+```js
+const { Bubblegum } = require("@bubblegum-ai/node");   // CommonJS (e.g. Jest default)
+```
+
+Node picks `dist/esm` for `import` and `dist/cjs` for `require` via the package
+`exports` map; TypeScript types resolve for both.
+
 ## Develop
 
 ```bash
 npm install
-npm run build      # tsc -> dist/
+npm run build      # tsc -> dist/esm (ESM) + dist/cjs (CommonJS)
 npm test           # build + node:test (no Python needed; mock transport)
 npm run typecheck
 ```

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,SAAS,EAIV,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kDAAkD;IAClD,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACzC,oFAAoF;IACpF,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACzC,0BAA0B;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,YAAiB,GAAG,SAAS,CA2BvE;AAOD,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kFAAkF;IAClF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,sDAAsD;IACtD,aAAa,CAAC,EAAE,SAAS,CAAC;gBAEd,IAAI,GAAE,mBAAwB;IAM1C,OAAO,CAAC,MAAM;IAoBd,OAAO,CAAC,OAAO;IAOf,4FAA4F;IAC5F,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAYtF,gFAAgF;IAC1E,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;IAarC,2EAA2E;IAC3E,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/cjs/client.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeClient = void 0;
+exports.spawnBridgeTransport = spawnBridgeTransport;
+const node_child_process_1 = require("node:child_process");
+const node_readline_1 = require("node:readline");
+const errors_js_1 = require("./errors.js");
+const protocol_js_1 = require("./protocol.js");
+/** Spawn the Python bridge as a child process and frame JSON-RPC over its stdio. */
+function spawnBridgeTransport(opts = {}) {
+    const command = opts.command ?? "python";
+    const args = opts.args ?? ["-m", "bubblegum.bridge"];
+    const child = (0, node_child_process_1.spawn)(command, args, {
+        cwd: opts.cwd,
+        env: opts.env,
+        stdio: ["pipe", "pipe", "inherit"], // engine logs/errors pass through to our stderr
+    });
+    const rl = (0, node_readline_1.createInterface)({ input: child.stdout });
+    return {
+        send(line) {
+            child.stdin.write(line + "\n");
+        },
+        onLine(cb) {
+            rl.on("line", cb);
+        },
+        onClose(cb) {
+            child.on("error", (err) => cb(err));
+            child.on("exit", () => cb());
+        },
+        async close() {
+            rl.close();
+            child.stdin.end();
+            if (child.exitCode === null)
+                child.kill();
+        },
+    };
+}
+/**
+ * Low-level JSON-RPC client over a {@link Transport}: assigns request ids,
+ * correlates responses, surfaces engine errors as {@link BridgeError}, and
+ * negotiates the protocol version via {@link BridgeClient.handshake}.
+ */
+class BridgeClient {
+    transport;
+    pending = new Map();
+    nextId = 1;
+    closed = false;
+    /** Populated after a successful {@link handshake}. */
+    handshakeInfo;
+    constructor(opts = {}) {
+        this.transport = opts.transport ?? spawnBridgeTransport(opts.spawn);
+        this.transport.onLine((line) => this.onLine(line));
+        this.transport.onClose((err) => this.onClose(err));
+    }
+    onLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            return; // ignore non-JSON noise on the channel
+        }
+        if (typeof msg.id !== "number")
+            return; // we only issue numeric ids
+        const pending = this.pending.get(msg.id);
+        if (!pending)
+            return;
+        this.pending.delete(msg.id);
+        if ((0, protocol_js_1.isErrorResponse)(msg)) {
+            pending.reject(new errors_js_1.BridgeError(msg.error.code, msg.error.message, msg.error.data));
+        }
+        else {
+            pending.resolve(msg.result);
+        }
+    }
+    onClose(err) {
+        this.closed = true;
+        const reason = err ?? new errors_js_1.BridgeError(protocol_js_1.ErrorCodes.InternalError, "bridge connection closed");
+        for (const [, pending] of this.pending)
+            pending.reject(reason);
+        this.pending.clear();
+    }
+    /** Issue a request and resolve with its `result` (or reject with a {@link BridgeError}). */
+    request(method, params = {}) {
+        if (this.closed) {
+            return Promise.reject(new errors_js_1.BridgeError(protocol_js_1.ErrorCodes.InternalError, "bridge is closed"));
+        }
+        const id = this.nextId++;
+        const payload = { jsonrpc: "2.0", id, method, params };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.transport.send(JSON.stringify(payload));
+        });
+    }
+    /** Negotiate with the engine; throws if its protocol version is unsupported. */
+    async handshake() {
+        const info = await this.request("handshake");
+        if (!protocol_js_1.SUPPORTED_PROTOCOL_VERSIONS.includes(info.protocol_version)) {
+            throw new errors_js_1.BridgeError(protocol_js_1.ErrorCodes.Unsupported, `engine protocol v${info.protocol_version} is not supported by this client ` +
+                `(supports: ${protocol_js_1.SUPPORTED_PROTOCOL_VERSIONS.join(", ")}). Upgrade @bubblegum-ai/node.`);
+        }
+        this.handshakeInfo = info;
+        return info;
+    }
+    /** True if the engine advertised the given capability in its handshake. */
+    hasCapability(name) {
+        return this.handshakeInfo?.capabilities.includes(name) ?? false;
+    }
+    async close() {
+        await this.transport.close();
+        this.onClose();
+    }
+}
+exports.BridgeClient = BridgeClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

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

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAM1D"}

package/dist/cjs/errors.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeError = void 0;
+/** An error returned by the bridge (a JSON-RPC error response) or a transport failure. */
+class BridgeError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "BridgeError";
+        this.code = code;
+        this.data = data;
+    }
+}
+exports.BridgeError = BridgeError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAAA,0FAA0F;AAC1F,MAAa,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAS;IACb,IAAI,CAAW;IAExB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAc;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAVD,kCAUC"}

package/dist/{index.d.ts → cjs/index.d.ts}

@@ -13,5 +13,5 @@ export type { Transport, SpawnOptions, BridgeClientOptions } from "./client.js";
 export { BridgeError } from "./errors.js";
 export { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, ErrorCodes, } from "./protocol.js";
 export type { Handshake, JsonRpcResponse } from "./protocol.js";
-export type { StepResult, StepStatus, ResolvedTarget, ErrorInfo, SessionSummary, StepOptions, } from "./types.js";
+export type { StepResult, StepStatus, ResolvedTarget, ErrorInfo, SessionSummary, StepOptions, ReportOptions, ReportResult, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEvF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhE,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,SAAS,EACT,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @bubblegum-ai/node — Node/TypeScript client for the Bubblegum engine.
+ *
+ * Drives AI-powered, natural-language Playwright/Appium test steps from JS/TS by
+ * spawning the Python `bubblegum bridge` and speaking its JSON-RPC protocol. The
+ * Python engine stays the single source of truth for grounding; this package is
+ * a thin, typed proxy. See ../../docs/distribution-npm-and-pypi.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCodes = exports.SUPPORTED_PROTOCOL_VERSIONS = exports.PROTOCOL_VERSION = exports.BridgeError = exports.spawnBridgeTransport = exports.BridgeClient = exports.Bubblegum = void 0;
+var session_js_1 = require("./session.js");
+Object.defineProperty(exports, "Bubblegum", { enumerable: true, get: function () { return session_js_1.Bubblegum; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "BridgeClient", { enumerable: true, get: function () { return client_js_1.BridgeClient; } });
+Object.defineProperty(exports, "spawnBridgeTransport", { enumerable: true, get: function () { return client_js_1.spawnBridgeTransport; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "BridgeError", { enumerable: true, get: function () { return errors_js_1.BridgeError; } });
+var protocol_js_1 = require("./protocol.js");
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_js_1.PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "SUPPORTED_PROTOCOL_VERSIONS", { enumerable: true, get: function () { return protocol_js_1.SUPPORTED_PROTOCOL_VERSIONS; } });
+Object.defineProperty(exports, "ErrorCodes", { enumerable: true, get: function () { return protocol_js_1.ErrorCodes; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAGlB,yCAAiE;AAAxD,yGAAA,YAAY,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAG3C,yCAA0C;AAAjC,wGAAA,WAAW,OAAA;AAEpB,6CAIuB;AAHrB,+GAAA,gBAAgB,OAAA;AAChB,0HAAA,2BAA2B,OAAA;AAC3B,yGAAA,UAAU,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,cAAe,CAAC;AAExD,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,qEAAqE;AACrE,eAAO,MAAM,UAAU;;;;;;;;;CASb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D;AAED,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAEpE,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,GAAG,IAAI,oBAAoB,CAEjF;AAED,wCAAwC;AACxC,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB"}

package/dist/cjs/protocol.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Wire protocol for the Bubblegum bridge — the TypeScript mirror of
+ * `bubblegum/bridge/protocol.py`. Keep these in lockstep with the Python side.
+ *
+ * The client negotiates against the engine via `handshake`: it feature-detects
+ * on `capabilities` and refuses to run against a `protocol_version` it does not
+ * support, so a newer engine can keep serving an older client (additive-first).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCodes = exports.PROTOCOL_VERSION = exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
+exports.isErrorResponse = isErrorResponse;
+/** Protocol versions this client speaks. v1 = the 0.1.0 bridge slice. */
+exports.SUPPORTED_PROTOCOL_VERSIONS = [1];
+/** The latest protocol version this client was written against. */
+exports.PROTOCOL_VERSION = 1;
+/** JSON-RPC 2.0 + bridge error codes (mirror of the Python side). */
+exports.ErrorCodes = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+    SessionNotFound: -32001,
+    EngineError: -32002,
+    Unsupported: -32003,
+};
+function isErrorResponse(msg) {
+    return msg.error !== undefined;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/cjs/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA2CH,0CAEC;AA3CD,yEAAyE;AAC5D,QAAA,2BAA2B,GAAG,CAAC,CAAC,CAAU,CAAC;AAExD,mEAAmE;AACtD,QAAA,gBAAgB,GAAG,CAAC,CAAC;AAElC,qEAAqE;AACxD,QAAA,UAAU,GAAG;IACxB,UAAU,EAAE,CAAC,KAAK;IAClB,cAAc,EAAE,CAAC,KAAK;IACtB,cAAc,EAAE,CAAC,KAAK;IACtB,aAAa,EAAE,CAAC,KAAK;IACrB,aAAa,EAAE,CAAC,KAAK;IACrB,eAAe,EAAE,CAAC,KAAK;IACvB,WAAW,EAAE,CAAC,KAAK;IACnB,WAAW,EAAE,CAAC,KAAK;CACX,CAAC;AAyBX,SAAgB,eAAe,CAAC,GAAoB;IAClD,OAAQ,GAA4B,CAAC,KAAK,KAAK,SAAS,CAAC;AAC3D,CAAC"}

package/dist/{session.d.ts → cjs/session.d.ts}

@@ -1,5 +1,5 @@
 import { BridgeClient, BridgeClientOptions } from "./client.js";
-import { SessionSummary, StepOptions, StepResult } from "./types.js";
+import { ReportOptions, ReportResult, SessionSummary, StepOptions, StepResult } from "./types.js";
 export type Channel = "web" | "mobile";
 export interface LaunchOptions extends BridgeClientOptions {
     /** "web" (default) or "mobile". */
@@ -79,6 +79,18 @@ export declare class Bubblegum {
     selectedValue(target: string): Promise<string>;
     explain(instruction: string): Promise<string>;
     summary(): Promise<SessionSummary>;
+    /**
+     * Write reports (Allure / HTML / JSON / JUnit) from every step this session
+     * ran, using the engine's own reporters — the same output the Python/pytest
+     * path produces. Call it once near the end of your run (e.g. in `finally`,
+     * before `close()`):
+     *
+     * ```ts
+     * await bg.report({ html: "reports/run.html", allure: "allure-results" });
+     * // -> { written: { html: "/abs/...", allure: "/abs/..." }, steps: 12 }
+     * ```
+     */
+    report(opts: ReportOptions): Promise<ReportResult>;
     /** Close the engine session and tear down the bridge process. */
     close(): Promise<void>;
 }

package/dist/cjs/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAElG,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEvC,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACxD,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC;IACnE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAF5B,OAAO;IAKP,iFAAiF;WACpE,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,SAAS,CAAC;IA2BjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IAItD,gEAAgE;IAChE,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQpE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQvE,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQxE,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IASzC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3C,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ9C,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQnD,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;IAIlC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAyBlD,iEAAiE;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/cjs/session.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bubblegum = void 0;
+const client_js_1 = require("./client.js");
+const errors_js_1 = require("./errors.js");
+const protocol_js_1 = require("./protocol.js");
+/**
+ * The ergonomic, engine-owned session. `launch()` spawns the bridge, negotiates
+ * the protocol, and opens a session whose Playwright/Appium handle lives inside
+ * the Python engine; every call here is a thin proxy to the same four primitives
+ * the Python SDK exposes, returning the identical `StepResult` shape.
+ *
+ * ```ts
+ * const bg = await Bubblegum.launch({ url: "https://example.com/login" });
+ * try {
+ *   await bg.act('Enter "tom" into Username');
+ *   await bg.act("Click Login");
+ *   await bg.verify("Dashboard is visible");
+ * } finally {
+ *   await bg.close();
+ * }
+ * ```
+ */
+class Bubblegum {
+    client;
+    sessionId;
+    constructor(client, sessionId) {
+        this.client = client;
+        this.sessionId = sessionId;
+    }
+    /** Spawn the bridge, handshake, and open a session (engine-owned by default). */
+    static async launch(opts = {}) {
+        const client = new client_js_1.BridgeClient(opts);
+        try {
+            await client.handshake();
+            if (opts.cdpEndpoint && !client.hasCapability("channel.web.cdp")) {
+                throw new errors_js_1.BridgeError(protocol_js_1.ErrorCodes.Unsupported, "this engine does not support CDP attach (channel.web.cdp); upgrade bubblegum-ai");
+            }
+            const { session_id } = await client.request("session.open", {
+                channel: opts.channel ?? "web",
+                url: opts.url,
+                headless: opts.headless ?? true,
+                dry_run: opts.dryRun ?? false,
+                appium_url: opts.appiumUrl,
+                capabilities: opts.capabilities,
+                cdp_endpoint: opts.cdpEndpoint,
+                page_index: opts.pageIndex,
+            });
+            return new Bubblegum(client, session_id);
+        }
+        catch (err) {
+            await client.close();
+            throw err;
+        }
+    }
+    /**
+     * Attach the engine to a browser your test already controls, over CDP
+     * (client-owned mode). Launch your Chromium with a remote-debugging port and
+     * pass its endpoint:
+     *
+     * ```ts
+     * const browser = await chromium.launch({ args: ["--remote-debugging-port=9222"] });
+     * const bg = await Bubblegum.attach({ cdpEndpoint: "http://localhost:9222" });
+     * await bg.act("Click Login"); // drives the page your test opened
+     * ```
+     */
+    static attach(opts) {
+        return Bubblegum.launch({ ...opts, channel: "web" });
+    }
+    /** The bridge client (for advanced use / capability checks). */
+    get bridge() {
+        return this.client;
+    }
+    act(instruction, options) {
+        return this.client.request("act", {
+            session_id: this.sessionId,
+            instruction,
+            options,
+        });
+    }
+    verify(instruction, options) {
+        return this.client.request("verify", {
+            session_id: this.sessionId,
+            instruction,
+            options,
+        });
+    }
+    extract(instruction, options) {
+        return this.client.request("extract", {
+            session_id: this.sessionId,
+            instruction,
+            options,
+        });
+    }
+    recover(args) {
+        return this.client.request("recover", {
+            session_id: this.sessionId,
+            failed_selector: args.failedSelector,
+            intent: args.intent,
+            options: args.options,
+        });
+    }
+    async isVisible(target) {
+        const r = await this.client.request("is_visible", {
+            session_id: this.sessionId,
+            target,
+        });
+        return r.value;
+    }
+    async isChecked(target) {
+        const r = await this.client.request("is_checked", {
+            session_id: this.sessionId,
+            target,
+        });
+        return r.value;
+    }
+    async selectedValue(target) {
+        const r = await this.client.request("selected_value", {
+            session_id: this.sessionId,
+            target,
+        });
+        return r.value;
+    }
+    async explain(instruction) {
+        const r = await this.client.request("explain", {
+            session_id: this.sessionId,
+            instruction,
+        });
+        return r.explanation;
+    }
+    summary() {
+        return this.client.request("summary", { session_id: this.sessionId });
+    }
+    /**
+     * Write reports (Allure / HTML / JSON / JUnit) from every step this session
+     * ran, using the engine's own reporters — the same output the Python/pytest
+     * path produces. Call it once near the end of your run (e.g. in `finally`,
+     * before `close()`):
+     *
+     * ```ts
+     * await bg.report({ html: "reports/run.html", allure: "allure-results" });
+     * // -> { written: { html: "/abs/...", allure: "/abs/..." }, steps: 12 }
+     * ```
+     */
+    report(opts) {
+        if (!this.client.hasCapability("report.write")) {
+            throw new errors_js_1.BridgeError(protocol_js_1.ErrorCodes.Unsupported, "this engine does not support report generation (report.write); upgrade bubblegum-ai");
+        }
+        const resolve = (v, fallback) => v === true ? fallback : v || undefined;
+        const params = { session_id: this.sessionId };
+        const html = resolve(opts.html, "bubblegum_report.html");
+        const json = resolve(opts.json, "bubblegum_report.json");
+        const junit = resolve(opts.junit, "bubblegum_report.xml");
+        const allure = resolve(opts.allure, "allure-results");
+        if (html)
+            params.html = html;
+        if (json)
+            params.json = json;
+        if (junit)
+            params.junit = junit;
+        if (allure)
+            params.allure = allure;
+        if (opts.title)
+            params.title = opts.title;
+        if (opts.suiteName)
+            params.suite_name = opts.suiteName;
+        return this.client.request("report.write", params);
+    }
+    /** Close the engine session and tear down the bridge process. */
+    async close() {
+        try {
+            await this.client.request("session.close", { session_id: this.sessionId });
+        }
+        finally {
+            await this.client.close();
+        }
+    }
+}
+exports.Bubblegum = Bubblegum;
+//# sourceMappingURL=session.js.map

package/dist/cjs/session.js.map

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

package/dist/{types.d.ts → cjs/types.d.ts}

@@ -37,4 +37,33 @@ export interface SessionSummary {
 }
 /** Per-call options forwarded verbatim to the engine SDK (timeout_ms, selector, …). */
 export type StepOptions = Record<string, unknown>;
+/**
+ * Which reports to write from the session's accumulated step results.
+ *
+ * Each field is either an output path, or `true` to use the default name
+ * (`bubblegum_report.html` / `.json` / `.xml`, and `allure-results/` for
+ * Allure). Omit a field to skip that format. Paths are resolved relative to the
+ * engine process's working directory.
+ */
+export interface ReportOptions {
+    /** Single-file HTML report. */
+    html?: string | boolean;
+    /** Machine-readable JSON report. */
+    json?: string | boolean;
+    /** JUnit XML (for CI test-report ingestion). */
+    junit?: string | boolean;
+    /** Allure 2 results *directory* (view with `allure serve <dir>`). */
+    allure?: string | boolean;
+    /** Report title (HTML/JSON). */
+    title?: string;
+    /** Suite name (Allure/JUnit). */
+    suiteName?: string;
+}
+/** Result of {@link Bubblegum.report}: resolved paths written, and step count. */
+export interface ReportResult {
+    /** Format → resolved absolute path (or directory, for Allure). */
+    written: Record<string, string>;
+    /** Number of steps included in the report. */
+    steps: number;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/cjs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnF,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/cjs/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * TypeScript mirror of the engine's result schemas (`bubblegum/core/schemas.py`).
+ *
+ * Kept intentionally close to the Pydantic models. `[key: string]: unknown`
+ * index signatures let newer engine fields flow through without breaking the
+ * client (additive-first), while the named fields stay strongly typed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}