@bowmark/web 1.12.2 → 1.14.0

package/src/guard.ts

@@ -1,198 +0,0 @@
-// 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";
-
-/** 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;
-}
-
-const PLAIN_PROTOTYPES: ReadonlyArray<object | null> = [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: unknown): WireProblem | null {
-  return walk(value, "", new Set<object>());
-}
-
-function walk(value: unknown, path: string, seen: Set<object>): WireProblem | null {
-  const bad = (reason: string): WireProblem => ({ 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 as object;
-  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) as object | null;
-    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 as Record<string, unknown>)[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: object): string {
-  const name = (Object.getPrototypeOf(object) as { constructor?: { name?: string } } | null)
-    ?.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: string, args: readonly unknown[]): void {
-  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: string,
-  path: readonly string[],
-  args: readonly unknown[],
-): void {
-  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/src/session.ts

@@ -1,194 +0,0 @@
-/// <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,
-  type ClientOptions,
-  type ClosedSession,
-  callInSession,
-  closeSession,
-  openSession,
-  resolveClient,
-} from "./transport.js";
-
-/** What a proxy node does when it is finally called. */
-type Dispatch = (path: string[], args: unknown[]) => Promise<unknown>;
-
-/** 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: Dispatch): BowmarkLibrary {
-  const node = (path: string[]): unknown => {
-    // 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: unknown[]) {
-        return dispatch(path, args);
-      },
-    });
-  };
-  return node([]) as BowmarkLibrary;
-}
-
-/** One dispatch: validate the path, refuse a non-wire argument, then send it. */
-function dispatchThrough(send: (path: string[], args: unknown[]) => Promise<unknown>): Dispatch {
-  // `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);
-  };
-}
-
-/** 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 async function session<T>(
-  callback: (bowmark: BowmarkLibrary, handle: SessionHandle) => Promise<T>,
-  opts: ClientOptions = {},
-): Promise<T> {
-  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: unknown) => {
-      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: ClientOptions = {}): Promise<{
-  bowmark: BowmarkLibrary;
-  sessionId: string;
-  expiresAt: string;
-  close(): Promise<ClosedSession | null>;
-}> {
-  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: ClientOptions = {}): BowmarkLibrary {
-  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: unknown) => {
-          resolved.onLog?.(`[bowmark] could not close session ${opened.sessionId}: ${String(err)}`);
-          return null;
-        });
-      }
-    }),
-  );
-}