@bowmark/web 1.12.2 → 1.14.0

package/dist/guard.d.ts

@@ -0,0 +1,64 @@
+/** What is wrong with a value, and WHERE. The path is Playwright's format —
+ * `a.inner[1].property` — because naming the offending path is the difference
+ * between a caller fixing the bug in a minute and bisecting their own arguments. */
+export interface WireProblem {
+    /** Dotted/bracketed path from the root. Empty string at the root. */
+    path: string;
+    /** What was found and why the wire refuses it, in one clause. */
+    reason: string;
+}
+/** Walk `value` and return the FIRST thing the wire refuses, or `null` when it is
+ * clean.
+ *
+ * `undefined` is allowed, at the root and at a key — it is what an absent optional
+ * property is, and refusing it would refuse every legal partial object. It is
+ * DROPPED on the way across, which `Wire<T>` states in the type. */
+export declare function wireProblem(value: unknown): WireProblem | null;
+/** Refuse the whole argument list before a byte leaves the process.
+ *
+ * Throws `BowmarkError` with code `wire_refused`, naming the exact position:
+ * `bowmark.hotels.search(args[0].checkIn)`. Failure is loud here for the reason EF
+ * Core made silent client-side fallback an error: a boundary that quietly accepts
+ * something it will mangle produces behaviour that only breaks in production, and
+ * getting better at serialization later must not silently change a caller's
+ * results. */
+export declare function assertWireSafeArgs(label: string, args: readonly unknown[]): void;
+/** Refuse an argument list the declared signature does not accept, and refuse a path
+ * this package has never heard of.
+ *
+ * Runs AFTER `assertWireSafeArgs`, deliberately. A `Date` and a `Map` are refused by
+ * the wire guard with a message about JSON, which is the right explanation; reaching
+ * the shape check first would report the same value as "expected a string" and send
+ * the caller looking for the wrong bug.
+ *
+ * ── FAILING CLOSED, and the two things it must NOT close on ─────────────────
+ *
+ * The rule is "refuse what the table knows is wrong; pass anything it cannot know",
+ * and both halves cost something real, so both are stated.
+ *
+ * **A known unit with an unknown FUNCTION is refused.** The table is authoritative
+ * about a unit it carries, so `bowmark.music.searchHarder(…)` is a typo or an
+ * install older than the function. The compile-time surface already refuses that
+ * call — it is a `Property does not exist` error against the same generated data —
+ * so anybody reaching this line came through `as any`, plain JavaScript or a stale
+ * package, and a refusal naming the manifest version is a better answer for all
+ * three than a request that succeeds against declarations they do not have. The
+ * cost, named rather than hidden: this package is published on its own cadence, so
+ * a caller on version N cannot reach a function the library gained in N+1 even
+ * though the api would serve it. `run(script)` reaches anything and is untyped by
+ * construction, so nothing is unreachable.
+ *
+ * **An unknown UNIT passes straight through, and that is not a hedge.** A Shopify
+ * family MEMBER — `bowmark.providers.gymshark.search(…)` — is deliberately absent
+ * from every manifest: `listProviders()` excludes members by design and always
+ * will, because there are half a million of them. So an unknown unit is the NORMAL
+ * case for most of the library, not a stale one, and refusing it would have this
+ * package refuse the largest part of what it is a client for. Found by running the
+ * Phase 5 session suite, whose worked example is gymshark.
+ *
+ * **An `unchecked` function passes through too** — one whose declared argument is a
+ * bare destructuring pattern. It is an EXPLICIT null in the table rather than an
+ * absence, and that distinction is what makes the first rule safe at all: 20 real
+ * functions have no readable argument shape, and refusing them would delete them
+ * from the runtime as well as from the types. */
+export declare function assertArgShape(label: string, path: readonly string[], args: readonly unknown[]): void;

package/dist/guard.js

@@ -0,0 +1,174 @@
+// The argument guard — refuse a value the wire cannot carry BEFORE the request.
+//
+// ── This is a deliberate COPY of `wireProblem` in `packages/schema/src/wire.ts` ──
+//
+// Not an import, and not an oversight. `@bowmark/schema` is a workspace package;
+// importing it would put `"@bowmark/schema": "workspace:*"` in the published
+// `package.json` and the tarball would not install for anyone outside this repo.
+// The package's zero-dependency promise is the reason this file exists at all.
+//
+// A copy drifts, so the copy is CHECKED: `tests/unit/bowmark-web-guard.test.ts`
+// runs both implementations over one fixture table and asserts identical
+// `{ path, reason }` for every entry. A new refusal in `wire.ts` that is not
+// mirrored here fails that test by name.
+//
+// Why a walk and not a `try { JSON.stringify(args) }`: stringify throws on exactly
+// two things, a circular structure and a `BigInt`. Everything else it "handles"
+// lossily — `Date` → string, `Map`/`Set` → `{}`, class instance → plain object,
+// function-valued key → dropped — so a try/catch catches almost nothing. Temporal
+// shipped that exact bug, diagnosed it as a typing problem, and closed it won't-fix.
+import { VALIDATORS } from "./generated/validators.js";
+import { BowmarkError } from "./transport.js";
+import { argsProblem, lookupParams } from "./validate.js";
+const PLAIN_PROTOTYPES = [Object.prototype, null];
+/** Walk `value` and return the FIRST thing the wire refuses, or `null` when it is
+ * clean.
+ *
+ * `undefined` is allowed, at the root and at a key — it is what an absent optional
+ * property is, and refusing it would refuse every legal partial object. It is
+ * DROPPED on the way across, which `Wire<T>` states in the type. */
+export function wireProblem(value) {
+    return walk(value, "", new Set());
+}
+function walk(value, path, seen) {
+    const bad = (reason) => ({ path, reason });
+    if (value === null || value === undefined)
+        return null;
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return null;
+        case "number":
+            // JSON.stringify turns these into `null` without complaint, which is the
+            // silent-lossy class this guard exists to catch.
+            return Number.isFinite(value) ? null : bad(`the number ${String(value)} has no JSON form`);
+        case "bigint":
+            return bad("a bigint has no JSON form (JSON.stringify throws on one)");
+        case "function":
+            return bad("a function cannot cross the wire — code never crosses, only data");
+        case "symbol":
+            return bad("a symbol has no JSON form");
+    }
+    const object = value;
+    if (seen.has(object))
+        return bad("a circular reference");
+    seen.add(object);
+    try {
+        if (Array.isArray(object)) {
+            for (let i = 0; i < object.length; i++) {
+                const problem = walk(object[i], `${path}[${i}]`, seen);
+                if (problem)
+                    return problem;
+            }
+            return null;
+        }
+        // A NOMINAL refusal, and the only one available at runtime. `Wire<T>` cannot
+        // express it — TypeScript has no nominal typing — so a Date, a Map, a class
+        // instance and anything else carrying its own prototype is refused here rather
+        // than being quietly flattened into a plain object or a string.
+        const prototype = Object.getPrototypeOf(object);
+        if (!PLAIN_PROTOTYPES.includes(prototype)) {
+            return bad(`a ${constructorName(object)} instance — only plain objects and arrays cross`);
+        }
+        for (const key of Object.keys(object)) {
+            const child = object[key];
+            const childPath = path ? `${path}.${key}` : key;
+            // A function- or symbol-valued key is DROPPED rather than refused: that is
+            // what JSON.stringify does, and `Wire<T>` removes the key from its key set to
+            // say so. Refusing here would make a legal object with a method unusable.
+            if (typeof child === "function" || typeof child === "symbol")
+                continue;
+            const problem = walk(child, childPath, seen);
+            if (problem)
+                return problem;
+        }
+        return null;
+    }
+    finally {
+        seen.delete(object);
+    }
+}
+function constructorName(object) {
+    const name = Object.getPrototypeOf(object)
+        ?.constructor?.name;
+    return name && name.length > 0 ? name : "non-plain-object";
+}
+/** Refuse the whole argument list before a byte leaves the process.
+ *
+ * Throws `BowmarkError` with code `wire_refused`, naming the exact position:
+ * `bowmark.hotels.search(args[0].checkIn)`. Failure is loud here for the reason EF
+ * Core made silent client-side fallback an error: a boundary that quietly accepts
+ * something it will mangle produces behaviour that only breaks in production, and
+ * getting better at serialization later must not silently change a caller's
+ * results. */
+export function assertWireSafeArgs(label, args) {
+    for (let i = 0; i < args.length; i++) {
+        const problem = wireProblem(args[i]);
+        if (!problem)
+            continue;
+        const where = problem.path
+            ? problem.path.startsWith("[")
+                ? `args[${i}]${problem.path}`
+                : `args[${i}].${problem.path}`
+            : `args[${i}]`;
+        throw new BowmarkError(`${label} was not called: ${where} is ${problem.reason}. ` +
+            "Only JSON — plain objects, arrays, strings, finite numbers, booleans and null — crosses to a capability.", { code: "wire_refused", path: label });
+    }
+}
+/** Refuse an argument list the declared signature does not accept, and refuse a path
+ * this package has never heard of.
+ *
+ * Runs AFTER `assertWireSafeArgs`, deliberately. A `Date` and a `Map` are refused by
+ * the wire guard with a message about JSON, which is the right explanation; reaching
+ * the shape check first would report the same value as "expected a string" and send
+ * the caller looking for the wrong bug.
+ *
+ * ── FAILING CLOSED, and the two things it must NOT close on ─────────────────
+ *
+ * The rule is "refuse what the table knows is wrong; pass anything it cannot know",
+ * and both halves cost something real, so both are stated.
+ *
+ * **A known unit with an unknown FUNCTION is refused.** The table is authoritative
+ * about a unit it carries, so `bowmark.music.searchHarder(…)` is a typo or an
+ * install older than the function. The compile-time surface already refuses that
+ * call — it is a `Property does not exist` error against the same generated data —
+ * so anybody reaching this line came through `as any`, plain JavaScript or a stale
+ * package, and a refusal naming the manifest version is a better answer for all
+ * three than a request that succeeds against declarations they do not have. The
+ * cost, named rather than hidden: this package is published on its own cadence, so
+ * a caller on version N cannot reach a function the library gained in N+1 even
+ * though the api would serve it. `run(script)` reaches anything and is untyped by
+ * construction, so nothing is unreachable.
+ *
+ * **An unknown UNIT passes straight through, and that is not a hedge.** A Shopify
+ * family MEMBER — `bowmark.providers.gymshark.search(…)` — is deliberately absent
+ * from every manifest: `listProviders()` excludes members by design and always
+ * will, because there are half a million of them. So an unknown unit is the NORMAL
+ * case for most of the library, not a stale one, and refusing it would have this
+ * package refuse the largest part of what it is a client for. Found by running the
+ * Phase 5 session suite, whose worked example is gymshark.
+ *
+ * **An `unchecked` function passes through too** — one whose declared argument is a
+ * bare destructuring pattern. It is an EXPLICIT null in the table rather than an
+ * absence, and that distinction is what makes the first rule safe at all: 20 real
+ * functions have no readable argument shape, and refusing them would delete them
+ * from the runtime as well as from the types. */
+export function assertArgShape(label, path, args) {
+    const found = lookupParams(VALIDATORS, path);
+    if (found.kind === "unknown-function") {
+        throw new BowmarkError(`${label} was not called: this package's declarations were generated from library ` +
+            `manifest ${VALIDATORS.version.slice(0, 12)}, which has no such function on that unit. ` +
+            `If it is newer than this package, upgrade @bowmark/web; if you meant a different name, ` +
+            `the typed surface will offer it. \`run(script)\` reaches anything, typed or not.`, { code: "unknown_function", path: label });
+    }
+    if (found.kind === "unknown-unit" || found.kind === "unchecked")
+        return;
+    const unit = VALIDATORS.units[path.slice(0, -1).join(".")];
+    const problem = argsProblem(found.params, args, unit?.defs ?? {});
+    if (!problem)
+        return;
+    throw new BowmarkError(`${label} was not called: ${problem.path} is ${problem.reason}.`, {
+        code: "bad_argument",
+        path: label,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/// <reference path="./generated/library.d.ts" />
+import { type ClientOptions, type RunEnvelope } from "./transport.js";
+export { type WireProblem, wireProblem } from "./guard.js";
+export { client, openManagedSession, type SessionHandle, session } from "./session.js";
+export { type AuthNeed, BowmarkError, BowmarkNeedsUserError, type CallEnvelope, type ClientOptions, type ClosedSession, type FetchLike, type Handoff, type OpenedSession, type RunEnvelope, } from "./transport.js";
+/** The whole callable library, typed. `await bowmark.music.search("aphex twin")`.
+ *
+ * Each call opens its own one-shot session, which is right for ONE call and wrong
+ * for several: two calls get two instances and two cookie jars, so a cart filled by
+ * the first does not exist for the second. Reach for `session()` the moment a flow
+ * has a second step.
+ *
+ * Configuration comes from `BOWMARK_API_KEY` and `BOWMARK_API_URL`, read at CALL
+ * time. `client({ apiKey })` is the explicit form. */
+export declare const bowmark: BowmarkLibrary;
+/** Run a SCRIPT, as a string, in our sandbox — the agent path, and the
+ * zero-dependency `curl` path given a client.
+ *
+ * Not deprecated and not hidden: an LLM emits text natively, so a tool call carrying
+ * a script is the right shape for one. It is also **untyped by construction** — a
+ * template literal gets no typechecking, so the generated types cover `session()`
+ * and `bowmark`, never this. A person writing TypeScript wants `session()`.
+ *
+ * Returns the envelope rather than throwing: a script is composite, so `status`,
+ * `logs` and `result` are read together. `needs_user` carries a handoff URL in
+ * `meta.handoff`. */
+export declare function run<T = unknown>(script: string, opts?: ClientOptions): Promise<RunEnvelope<T>>;
+export type Library = BowmarkLibrary;
+export type Providers = BowmarkProviders;

package/{src/index.ts → dist/index.js}

@@ -1,5 +1,4 @@
 /// <reference path="./generated/library.d.ts" />
-
 // @bowmark/web — real TypeScript for the whole `bowmark.*` surface, plus the client
 // that executes it on our servers.
 //
@@ -15,25 +14,11 @@
 // process. `bowmark` inside a `run()` script string is the sandbox's own global,
 // running in an isolate on ours. The types are generated once and describe both, so
 // the two must stay in sync — see `packages/runtime/src/namespace.ts`.
-
 import { client } from "./session.js";
-import { type ClientOptions, postRun, type RunEnvelope, resolveClient } from "./transport.js";
-
-export { type WireProblem, wireProblem } from "./guard.js";
-export { client, openManagedSession, type SessionHandle, session } from "./session.js";
-export {
-  type AuthNeed,
-  BowmarkError,
-  BowmarkNeedsUserError,
-  type CallEnvelope,
-  type ClientOptions,
-  type ClosedSession,
-  type FetchLike,
-  type Handoff,
-  type OpenedSession,
-  type RunEnvelope,
-} from "./transport.js";
-
+import { postRun, resolveClient } from "./transport.js";
+export { wireProblem } from "./guard.js";
+export { client, openManagedSession, session } from "./session.js";
+export { BowmarkError, BowmarkNeedsUserError, } from "./transport.js";
 /** The whole callable library, typed. `await bowmark.music.search("aphex twin")`.
  *
  * Each call opens its own one-shot session, which is right for ONE call and wrong
@@ -43,8 +28,7 @@ export {
  *
  * Configuration comes from `BOWMARK_API_KEY` and `BOWMARK_API_URL`, read at CALL
  * time. `client({ apiKey })` is the explicit form. */
-export const bowmark: BowmarkLibrary = client();
-
+export const bowmark = client();
 /** Run a SCRIPT, as a string, in our sandbox — the agent path, and the
  * zero-dependency `curl` path given a client.
  *
@@ -56,16 +40,6 @@ export const bowmark: BowmarkLibrary = client();
  * Returns the envelope rather than throwing: a script is composite, so `status`,
  * `logs` and `result` are read together. `needs_user` carries a handoff URL in
  * `meta.handoff`. */
-export function run<T = unknown>(
-  script: string,
-  opts: ClientOptions = {},
-): Promise<RunEnvelope<T>> {
-  return postRun<T>(resolveClient(opts), script);
+export function run(script, opts = {}) {
+    return postRun(resolveClient(opts), script);
 }
-
-// ALIASES, not re-exports. A global from an ambient file is not a local declaration,
-// so `export type { BowmarkLibrary }` is `TS2661`. Aliasing is what lets a consumer
-// name the type without the ambient file being on their `types` path — which is the
-// whole point of the client half being importable and the catalog half being ambient.
-export type Library = BowmarkLibrary;
-export type Providers = BowmarkProviders;

package/dist/session.d.ts

@@ -0,0 +1,46 @@
+import { type ClientOptions, type ClosedSession } from "./transport.js";
+/** Everything a session block hands its callback. */
+export interface SessionHandle {
+    /** The server-side id. Present so a caller can quote it in a bug report or find
+     * the run in a trace. */
+    readonly sessionId: string;
+    /** ISO instant after which the session is gone and its calls 410. */
+    readonly expiresAt: string;
+}
+/** Run a block of calls against ONE live instance.
+ *
+ * ```ts
+ * const total = await session(async (bm) => {
+ *   const found = await bm.providers.gymshark.search({ query: "hoodie" });
+ *   await bm.providers.gymshark.addToCart({ variantId: found.products[0].variantId });
+ *   return (await bm.providers.gymshark.getCart()).itemCount;
+ * });
+ * ```
+ *
+ * **Each call is a round trip.** Stated rather than hidden, because a surface that
+ * looks like a local function call and is actually stateful is the leaky abstraction
+ * Cap'n Web is most criticised for, and it is how a caller writes an N+1 without
+ * noticing.
+ *
+ * The session closes in a `finally`, so a throw inside the callback still releases
+ * it. Metering is per CALL on both surfaces — opening and closing cost nothing. */
+export declare function session<T>(callback: (bowmark: BowmarkLibrary, handle: SessionHandle) => Promise<T>, opts?: ClientOptions): Promise<T>;
+/** Open a session by hand, for a caller whose lifetime is not a block — a REPL, a
+ * long-lived server object, a test fixture.
+ *
+ * `session()` is the form to reach for; this one moves the `finally` to the caller,
+ * and a caller who forgets it holds a session until its TTL. */
+export declare function openManagedSession(opts?: ClientOptions): Promise<{
+    bowmark: BowmarkLibrary;
+    sessionId: string;
+    expiresAt: string;
+    close(): Promise<ClosedSession | null>;
+}>;
+/** The bare per-call form: every call opens its own one-shot session and closes it.
+ *
+ * Correct for a single call and WRONG for several — two calls get two instances and
+ * two cookie jars, so a cart filled by the first does not exist for the second, and
+ * the failure is silent (Shopify answers `POST /cart/add.js` with 200 and the line
+ * echoed back, then reports `item_count: 0`). Use `session()` for anything
+ * multi-step. */
+export declare function client(opts?: ClientOptions): BowmarkLibrary;

package/dist/session.js

@@ -0,0 +1,153 @@
+/// <reference path="./generated/library.d.ts" />
+// The session client — the surface a person actually uses.
+//
+// The caller's callback runs on the CALLER'S MACHINE, in ordinary JavaScript, and
+// each capability call is one typed round trip into one live instance on ours. Real
+// `if`, real `for`, real closures, real autocomplete, and no script string.
+//
+// The callback is never stringified and never shipped. `toString()` on a user
+// function returns whatever the CALLER'S build tooling emitted — istanbul's
+// `cov_npcpcae6x.f[2]++`, esbuild's `__name`, TypeScript downleveling's `tslib_1` —
+// so accepting a function would be shipping a footgun whose trigger is in somebody
+// else's toolchain. Playwright was asked to fix that class of bug and formally
+// declined. See `docs/decisions/2026-08-03-the-session-surface-and-why-run-string-stays.md`.
+import { assertArgShape, assertWireSafeArgs } from "./guard.js";
+import { BowmarkError, callInSession, closeSession, openSession, resolveClient, } from "./transport.js";
+/** Property names a proxy must NOT answer with another node.
+ *
+ * `then` is the load-bearing one: `await bowmark.music` would otherwise find a
+ * callable `then`, invoke it as a thenable, and hang forever on a path that was
+ * never a call. The other two round out the Promise protocol, and `toJSON` stops a
+ * node being silently serialized into somebody's log. */
+const NOT_A_PATH_SEGMENT = new Set(["then", "catch", "finally", "toJSON"]);
+/** Build the `bowmark`-shaped Proxy over a dispatcher.
+ *
+ * **The Proxy accepts every name at runtime** — `bowmark.anything.at.all()` builds a
+ * path and sends it. That is not a bug, it is why the generated types are
+ * load-bearing rather than decorative: the Proxy makes a correct call work without
+ * enumerating half a million names, and TypeScript makes a wrong one a compile
+ * error. Neither half is sufficient alone, and it is the same split
+ * `packages/runtime/src/namespace.ts` already ships inside the sandbox. */
+function libraryProxy(dispatch) {
+    const node = (path) => {
+        // The target is a FUNCTION so the proxy is callable at any depth. A plain
+        // object target makes `apply` an illegal trap and every call a TypeError.
+        const target = () => undefined;
+        return new Proxy(target, {
+            get(_target, property) {
+                if (typeof property !== "string")
+                    return undefined;
+                if (NOT_A_PATH_SEGMENT.has(property))
+                    return undefined;
+                return node([...path, property]);
+            },
+            apply(_target, _thisArg, args) {
+                return dispatch(path, args);
+            },
+        });
+    };
+    return node([]);
+}
+/** One dispatch: validate the path, refuse a non-wire argument, then send it. */
+function dispatchThrough(send) {
+    // `async`, so EVERY refusal is a rejected promise rather than a synchronous
+    // throw. A generated signature says the call returns a `Promise`, and a function
+    // that sometimes throws before returning one breaks `.catch()` — the caller's
+    // handler is never attached. Playwright's argument guard has the same shape for
+    // the same reason.
+    return async (path, args) => {
+        const label = ["bowmark", ...path].join(".");
+        // The api refuses a path shorter than two segments, and it is right to: every
+        // real call is `<unit>.<fn>` or `providers.<id>.<fn>`. Saying so here costs a
+        // round trip nothing and names the shape.
+        if (path.length < 2) {
+            throw new BowmarkError(`${label} is not a callable path. Call a function on a unit — bowmark.music.search(…) or bowmark.providers.gymshark.search(…).`, { code: "bad_path", path: label });
+        }
+        // BEFORE the request, deliberately. A guard that ran server-side would report
+        // a mangled value as a capability failure, after it had been metered.
+        //
+        // Two guards, in this order and not the other. `assertWireSafeArgs` answers
+        // "can this value cross at all" — a `Date`, a `Map`, a function — and its
+        // message is about JSON. `assertArgShape` answers "does it match what this
+        // function declares". Shape-first would report a `Date` as "expected a string"
+        // and point the caller at the wrong bug.
+        assertWireSafeArgs(label, args);
+        assertArgShape(label, path, args);
+        return send(path, args);
+    };
+}
+/** Run a block of calls against ONE live instance.
+ *
+ * ```ts
+ * const total = await session(async (bm) => {
+ *   const found = await bm.providers.gymshark.search({ query: "hoodie" });
+ *   await bm.providers.gymshark.addToCart({ variantId: found.products[0].variantId });
+ *   return (await bm.providers.gymshark.getCart()).itemCount;
+ * });
+ * ```
+ *
+ * **Each call is a round trip.** Stated rather than hidden, because a surface that
+ * looks like a local function call and is actually stateful is the leaky abstraction
+ * Cap'n Web is most criticised for, and it is how a caller writes an N+1 without
+ * noticing.
+ *
+ * The session closes in a `finally`, so a throw inside the callback still releases
+ * it. Metering is per CALL on both surfaces — opening and closing cost nothing. */
+export async function session(callback, opts = {}) {
+    const client = resolveClient(opts);
+    const opened = await openSession(client);
+    const proxy = libraryProxy(dispatchThrough((path, args) => callInSession(client, opened.sessionId, path, args)));
+    try {
+        return await callback(proxy, { sessionId: opened.sessionId, expiresAt: opened.expiresAt });
+    }
+    finally {
+        // Swallowed, and reported through `onLog` rather than thrown. A close that
+        // failed on top of a callback that threw would replace the caller's real error
+        // with a cleanup detail; the session's TTL reaps what this could not reach.
+        await closeSession(client, opened.sessionId).catch((err) => {
+            client.onLog?.(`[bowmark] could not close session ${opened.sessionId}: ${String(err)}`);
+            return null;
+        });
+    }
+}
+/** Open a session by hand, for a caller whose lifetime is not a block — a REPL, a
+ * long-lived server object, a test fixture.
+ *
+ * `session()` is the form to reach for; this one moves the `finally` to the caller,
+ * and a caller who forgets it holds a session until its TTL. */
+export async function openManagedSession(opts = {}) {
+    const client = resolveClient(opts);
+    const opened = await openSession(client);
+    return {
+        bowmark: libraryProxy(dispatchThrough((path, args) => callInSession(client, opened.sessionId, path, args))),
+        sessionId: opened.sessionId,
+        expiresAt: opened.expiresAt,
+        close: () => closeSession(client, opened.sessionId),
+    };
+}
+/** The bare per-call form: every call opens its own one-shot session and closes it.
+ *
+ * Correct for a single call and WRONG for several — two calls get two instances and
+ * two cookie jars, so a cart filled by the first does not exist for the second, and
+ * the failure is silent (Shopify answers `POST /cart/add.js` with 200 and the line
+ * echoed back, then reports `item_count: 0`). Use `session()` for anything
+ * multi-step. */
+export function client(opts = {}) {
+    return libraryProxy(dispatchThrough(async (path, args) => {
+        // Resolved per CALL, not once at construction. The exported `bowmark` is
+        // built at module load, and a consumer whose `fetch` or `BOWMARK_API_KEY`
+        // arrives after the import would otherwise be frozen against the environment
+        // as it stood at the top of their file.
+        const resolved = resolveClient(opts);
+        const opened = await openSession(resolved);
+        try {
+            return await callInSession(resolved, opened.sessionId, path, args);
+        }
+        finally {
+            await closeSession(resolved, opened.sessionId).catch((err) => {
+                resolved.onLog?.(`[bowmark] could not close session ${opened.sessionId}: ${String(err)}`);
+                return null;
+            });
+        }
+    }));
+}