@recapi/client 0.6.0 → 0.6.2

package/README.md

@@ -1,13 +1,32 @@
 # @recapi/client
 
 JavaScript client for the recapi recommendation API, for browsers and
-Node ≥ 18. Plain ES modules, no build step, no runtime dependencies.
+Node ≥ 18. Plain ES modules, no build step, no runtime dependencies
+(from CommonJS or Jest: [see here](#commonjs-typescript-and-jest)).
 
 The SDK keeps the user's interaction history on the device and sends it
 with every recommendation request. Recommendations reflect the latest
 click at once, and the server does not need to look anything up. The SDK
 also batches events and attributes them to recommendations for you.
 
+## Supported browsers
+
+The current and previous two major versions of Chrome, Edge and Firefox,
+and Safari 15.4 or later on macOS and iOS (every iPhone browser runs
+Safari's engine). The code needs at least Chrome and Edge 93, Firefox 92
+and Safari 15.4 (`Object.hasOwn`; `??=` and `||=` need less): a change that
+needs a newer browser moves this floor and says so under [Changes](#changes).
+
+On every change to the library, CI runs what a shop page relies on in
+Chromium, Firefox and WebKit, Safari's engine
+([`scripts/e2e/browsers.test.js`](../../scripts/e2e/browsers.test.js)): the
+lists of `recommend()` and `popular()`, a view and a cart credited to the
+recommendation, the history after a reload, the queued events sent when the
+page is left or hidden, consent and Global Privacy Control. That WebKit is
+Playwright's Linux build, not Safari on an iPhone: the engine is the same,
+but Safari's own storage rules (data deleted after seven days without a
+visit, private browsing) are not part of it.
+
 ## Install
 
 On a site without a build step (a theme, plain HTML), load the SDK from
@@ -16,7 +35,7 @@ are, gzipped, and browsers cache them for a year:
 
 ```html
 <script type="module">
-  import { createClient } from 'https://api.example.com/sdk/0.6.0/index.js';
+  import { createClient } from 'https://api.example.com/sdk/0.6.2/index.js';
 
   const recapi = createClient({ apiKey: 'rk_pub_…', baseUrl: 'https://api.example.com' });
   recapi.track('item-42', 'view');    // and the calls of the quick start below
@@ -111,7 +130,11 @@ in two places, both shown with your address in the dashboard's quick start:
   it; others get Shopify's converted price from the lookup). A row whose
   items all carry metadata then costs one request instead of seven. The
   snippet can't send metadata: the shop sends it with `PUT /v1/items`, and
-  marks a sold-out product inactive there, since no lookup checks it. A default style makes them a product row
+  marks a sold-out product inactive there, since no lookup checks it. The
+  products export upload and the product webhooks (the quick start's step 4,
+  [API](../../docs/api.md#post-v1shopifywebhooks--shopifys-product-webhooks))
+  fill it without code; a card whose metadata says `available: false` (maybe
+  sold out) is looked up instead. A default style makes them a product row
   in the theme's colours and fonts; all its selectors sit inside
   `:where(#recapi-recommendations …)`, which has no specificity, so any of
   the theme's rules overrides it. It follows the shop's cookie banner through
@@ -150,8 +173,8 @@ hidden for the whole test.
 
 Both files pass the same [`project`](#createclientoptions), which the quick start fills
 in for your environment, so they share the visitor's state whichever public
-key each holds: keys are shown once, and a pixel added later with a new key
-still credits each add to cart to the visitor and their recommendation.
+key each holds: the quick start fills both with the same key, but a pixel added
+later with another key still credits each add to cart to the visitor and their recommendation.
 Shopify's `product_added_to_cart` event carries only the cart line, not the
 cart's attributes
 ([docs](https://shopify.dev/docs/api/web-pixels-api/standard-events/product_added_to_cart)),
@@ -287,6 +310,23 @@ stands in for WordPress, run by `scripts/php.sh`) and runs the printed
 script against the SDK. The quick start fills in the current version and
 your address (`jssdk.WooCommerce`).
 
+`scripts/e2e_woocommerce.sh` (CI job `woocommerce`) runs the plugin on a
+real, throwaway shop: WordPress and WooCommerce in Docker at pinned
+versions, twice: the newest (WordPress 7.1.4, WooCommerce 11.2.1, PHP 8.5)
+and the oldest the plugin's header declares (WordPress 6.3, WooCommerce 8.3,
+PHP 7.4), the plugin taken from the quick start of a new recapi shop with
+its public key pasted, then a guest's browser (Playwright) on a product
+page, a card of recapi's row, the add to cart and the block checkout
+(`scripts/e2e/woocommerce.test.js`). It fails unless recapi has the
+catalog the secret key sent, the view, the click with its recommendation,
+the cart and exactly one purchase for the order, and a PHP warning or
+deprecation from the plugin in WordPress's debug log fails it. Run it from the
+repository root on any machine with Docker and python3:
+
+```sh
+./scripts/e2e_woocommerce.sh
+```
+
 ### Magento
 
 The Magento 2 module ([`sdk/php/magento`](../php/magento/README.md)) prints
@@ -317,6 +357,108 @@ await recapi.destroy();               // flushes queued events before exit
 Timers do not keep a Node process alive. Call `await client.flush()` or
 `await client.destroy()` before exiting, or queued events are lost.
 
+### Serverless and edge
+
+A request handler never exits: once the response is out, Cloudflare
+Workers cancel the 2 s timer that would send the queue, Vercel suspends
+the function and AWS Lambda freezes it. Events still queued then are lost,
+with no error. Send the queue after the response with the host's own call:
+
+- Cloudflare Workers: `ctx.waitUntil(visitor.flush())`, as below.
+- Next.js 15.1 or later (route handlers, server actions, server
+  components): `after(() => visitor.flush())`, with `after` from
+  `next/server`. On Vercel without Next.js, `waitUntil(visitor.flush())`
+  from `@vercel/functions`.
+- AWS Lambda: `await visitor.flush()` before the handler returns.
+
+A client is one visitor, like a browser tab: its history, user id and
+attribution belong to whoever it was used for, and one isolate serves many
+requests at once. Share a client only for lists that are no one's, such as
+popular items, and make one per request for a visitor's events and
+recommendations. `consent: false` keeps such a client from drawing a new
+anonymous id each time; it sends the user id you give `identify()`.
+
+```js
+// Cloudflare Workers
+import { env } from 'cloudflare:workers';
+import { createClient } from '@recapi/client';
+
+const options = { apiKey: env.RECAPI_KEY, baseUrl: 'https://api.example.com' };
+const shared = createClient(options);   // popular items: they are no one's
+
+export default {
+  async fetch(request, env, ctx) {
+    const visitor = createClient({ ...options, consent: false });
+    visitor.identify('cust-881');
+    visitor.track('item-42', 'purchase');
+    ctx.waitUntil(visitor.flush());     // sends the events after the response
+    const { items } = await shared.popular({ count: 4 });
+    return Response.json(items);
+  }
+};
+```
+
+`make test` runs this block as it stands here in workerd, the Workers
+runtime. A client may be created at module scope, where Workers allow no
+random values or timers: it draws its anonymous id at the first call.
+Outside a page, `popular()` asks with `cache: 'no-store'`, so Next.js
+neither keeps one answer for every visitor (Next.js 14) nor fetches the
+list once at build time for a static page (15 and later). On Workers
+older than compatibility date 2024-11-11, which refuse that option, it
+asks without it.
+
+### CommonJS, TypeScript and Jest
+
+The package is ES modules only. A project of ES modules (`"type":
+"module"`, `.mjs`) imports it as above; a CommonJS one loads it by Node
+version. On Node 20.19+ or 22.12+, plain `require` works:
+
+```js
+// CommonJS, Node 20.19+ or 22.12+
+const { createClient } = require('@recapi/client');
+
+const recapi = createClient({ apiKey: process.env.RECAPI_KEY, baseUrl: 'https://api.example.com' });
+```
+
+On Node 18, or 20 before 20.19, `require` throws `ERR_REQUIRE_ESM`. Load
+the library once with `import()`, which CommonJS has on every Node, then
+`await recapi` where you use it: `(await recapi).track('item-42', 'view')`.
+
+```js
+// CommonJS, Node 18 and later
+const recapi = import('@recapi/client').then(({ createClient }) =>
+  createClient({ apiKey: process.env.RECAPI_KEY, baseUrl: 'https://api.example.com' }));
+```
+
+`make test` runs both blocks as they stand here, on Node 18 and the
+current Node.
+
+TypeScript compiled to CommonJS turns `import { createClient } from
+'@recapi/client'` into a `require`, so it needs Node 20.19+ or 22.12+ too.
+On Node 18 write the `import()` above, with `"module": "nodenext"` in
+`tsconfig.json` (NestJS's scaffold has it): under `"module": "commonjs"`,
+TypeScript turns `import()` into a `require` as well.
+
+Jest runs tests through its own module loader and leaves `node_modules`
+uncompiled, so a test that reaches the library fails with "Must use import
+to load ES Module" ("Cannot use import statement outside a module" before
+Jest 30). Jest 30 started with `node --experimental-vm-modules` on Node
+24.9 or later, as NestJS 12's `npm test` does, loads it as is: change
+nothing there. Anywhere else, let Jest compile the library:
+
+```js
+// jest.config.js, or the "jest" key of package.json
+transformIgnorePatterns: ['/node_modules/(?!@recapi/)'],
+```
+
+Jest then compiles it with the transform it uses for `.js` files. With
+ts-jest, that transform's pattern must match `.js` (NestJS's
+`'^.+\\.(t|j)s$': 'ts-jest'` does). With Jest's default babel-jest, add a
+`babel.config.js` with `presets: [['@babel/preset-env', { targets: {
+node: 'current' } }]]`. Don't add the line where nothing was needed:
+there ts-jest's output fails with "exports is not defined". Vitest loads
+the library as is.
+
 ### Showing why an item is listed
 
 Every item carries `why`, a short [reason code](../../docs/api.md#reason-codes)
@@ -636,9 +778,16 @@ const storage = {
   setItem: (k, v) => { cache.set(k, v); AsyncStorage.setItem(k, v); },
   removeItem: (k) => { cache.delete(k); AsyncStorage.removeItem(k); }
 };
-createClient({ apiKey, baseUrl, project: 'myproject', storage });
+const client = createClient({ apiKey, baseUrl, project: 'myproject', storage });
 ```
 
+React Native has no page-hide event, so send the queue when the app leaves
+the screen: call `client.flush()` when `AppState` changes to `background`.
+`popular()` and the fallback list work on React Native below 0.80 as well,
+whose `URLSearchParams` has no working `set`. We read that class in React
+Native's 0.79 and 0.80 sources and test against a copy of its behaviour; the
+library has not been run on a device.
+
 Corrupt or unrecognised stored data is discarded. Bumping the `v1` in the
 key on a format change makes old data invisible.
 
@@ -653,6 +802,16 @@ minifier, to keep zero dev dependencies.
 
 ## Changes
 
+- 2026-11-03: version 0.6.2. `popular()` and the fallback list of
+  `recommend()` no longer throw on React Native below 0.80, whose
+  `URLSearchParams.set` is not implemented. Query strings are unchanged
+  everywhere else.
+- 2026-11-02: version 0.6.1. The client draws its anonymous id at the
+  first call instead of in `createClient`, so a back end on Cloudflare
+  Workers may create it at module scope (it threw "Disallowed operation
+  called within global scope"). Outside a page, `popular()` asks with
+  `cache: 'no-store'`, so Next.js no longer serves a frozen list. Recipes
+  per host: [Serverless and edge](#serverless-and-edge).
 - 2026-11-01: version 0.6.0. `getAnonId()` returns the device's anonymous
   id, for the backend to fetch the login snapshot without this device's own
   browsing (`?anon_id=`), which would otherwise count twice on a device not
@@ -698,8 +857,18 @@ minifier, to keep zero dev dependencies.
 
 ```sh
 npm test        # node --test, zero dev dependencies
+../../scripts/node18.sh --test test/*.test.js   # the same on Node 18, the floor
 ```
 
+`make test` and CI run the tests on Node 18 as well as the current Node,
+so a built-in newer than the `engines` floor (`Object.groupBy`,
+`Promise.withResolvers`, `toSorted`…) fails there. Raising the floor
+means changing `engines`, this README's first lines and
+`docs/development.md` together.
+
+The same steps in real browsers (Chromium, Firefox, WebKit): see
+[Testing](../../docs/development.md#testing).
+
 The API embeds `src/*.js` (module `recapi/sdkjs`, `embed.go`) and serves
 them at `/sdk/<version>/`, where browsers cache them for a year. So a
 change to `src/` needs a new version: bump `version` in `package.json`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recapi/client",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Browser and Node client for the recapi recommendation API: local decayed history, event batching, attribution.",
   "type": "module",
   "main": "./src/index.js",

package/src/client.js

@@ -91,7 +91,9 @@ const PUBLIC_KEY_PREFIX = 'rk_pub_';
  */
 
 /**
- * Creates a client. Nothing is sent until `track()`/`recommend()` is called.
+ * Creates a client. Nothing is sent until `track()`/`recommend()` is called,
+ * and nothing is stored or drawn at random before the first call, so a back
+ * end may create it at module scope (Cloudflare Workers forbid both there).
  *
  * @param {ClientOptions} options
  */
@@ -121,6 +123,7 @@ export function createClient(options) {
     }
   };
   const transport = createTransport({ baseUrl, apiKey, fetch: fetchImpl, timeoutMs });
+  const popularCache = serverCacheMode();
   // The default adapter probes localStorage with a write, so it is picked at
   // the first storage access: never before consent, nor under Do Not Track.
   let adapter = options.storage;
@@ -166,8 +169,19 @@ export function createClient(options) {
   let destroyed = false;
   /** False after a failed write: storage is then stale and memory is the truth. */
   let synced = true;
+  let started = false;
 
-  if (consent) {
+  /**
+   * Loads the stored state, or makes and stores the anonymous id, on the
+   * first call rather than in `createClient`: Cloudflare Workers forbid
+   * random values at module scope, where a back end creates its client. A
+   * page calls the client before it sends anything, so the id is the same
+   * and stored before the first event either way.
+   */
+  function start() {
+    if (started) return;
+    started = true;
+    if (!consent) return;
     reload();
     if (!anonId) {
       anonId = uuid();
@@ -388,6 +402,7 @@ export function createClient(options) {
       method: 'GET',
       path: '/v1/popular',
       auth: apiKey.startsWith(PUBLIC_KEY_PREFIX) ? 'query' : 'header',
+      cache: popularCache,
       timeoutMs: deadline,
       query: { tags_any: tagsAny?.join(','), tags_all: tagsAll?.join(','), count }
     });
@@ -420,6 +435,7 @@ export function createClient(options) {
      *   automatic attribution. `null` (a fallback list's id) is no override.
      */
     track(itemId, level, { recommendationId: explicit } = {}) {
+      start();
       // A fallback list has a null id, and a page passing it on must not
       // send `null` or lose the item's earlier, real attribution.
       const recommendationId = explicit ?? undefined;
@@ -468,6 +484,7 @@ export function createClient(options) {
      *   items: Array<{ itemId: string, score: number, slot: string, why?: string, metadata?: object }> }>}
      */
     async recommend(params = {}) {
+      start();
       const deadline = Math.min(timeoutMs, RECOMMEND_TIMEOUT_MS);
       try {
         return await personalised(params, deadline);
@@ -516,6 +533,7 @@ export function createClient(options) {
      * @param {{ history?: ServerSnapshot }} [options]
      */
     identify(id, { history: snapshot } = {}) {
+      start();
       if (!isId(id)) throw new RecapiError('invalid_request', 'userId must be 1-256 bytes of UTF-8 without control characters');
       if (quiet) return;
       mutate(() => {
@@ -538,6 +556,7 @@ export function createClient(options) {
      * ids they were tracked with.
      */
     reset() {
+      start();
       history = emptyHistory();
       userId = null;
       shown = new Map();
@@ -557,6 +576,7 @@ export function createClient(options) {
      * @param {boolean} value
      */
     setConsent(value) {
+      start();
       if (quiet || value === consent) return;
       consent = Boolean(value);
       if (!consent) {
@@ -585,6 +605,7 @@ export function createClient(options) {
      * @returns {{ history: Array<[string, number, number]>, recent: string[], rejected: string[] }}
      */
     getHistory() {
+      start();
       if (consent) reload();
       return toWire(history, now(), config);
     },
@@ -599,6 +620,7 @@ export function createClient(options) {
      * @returns {string | null}
      */
     getAnonId() {
+      start();
       if (consent) reload();
       return anonId;
     },
@@ -699,6 +721,26 @@ function compact(object) {
   return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
 }
 
+/**
+ * fetch's cache mode for `GET /v1/popular`: `no-store` outside a page.
+ * Next.js keeps a server fetch's answer for every visitor (14), or fetches
+ * once at build time for a static page (15 and later), and the list then
+ * never changes. A page keeps the browser's own cache, which follows the
+ * API's 60 s max-age. None where fetch refuses the field: Workers before
+ * compatibility date 2024-11-11 throw on any `cache`, even `no-store`.
+ *
+ * @returns {RequestCache | undefined}
+ */
+function serverCacheMode() {
+  if (globalThis.document !== undefined) return undefined;
+  try {
+    new Request('http://localhost/', { cache: 'no-store' });
+    return 'no-store';
+  } catch {
+    return undefined;
+  }
+}
+
 function doNotTrackEnabled() {
   const nav = globalThis.navigator;
   return nav?.doNotTrack === '1' || nav?.globalPrivacyControl === true;

package/src/transport.js

@@ -65,6 +65,7 @@ export class RecapiError extends Error {
  * @property {'header' | 'query'} [auth] `query` sends `?key=` so GET
  *   responses are CDN-cacheable and need no CORS preflight.
  * @property {boolean} [keepalive] Let the request outlive the page.
+ * @property {RequestCache} [cache] fetch's cache mode; the runtime's default when unset.
  * @property {number} [timeoutMs]
  */
 
@@ -76,18 +77,20 @@ export function createTransport({ baseUrl, apiKey, fetch, timeoutMs: defaultTime
   const root = baseUrl.replace(/\/+$/, '');
 
   /** @param {RequestOptions} options */
-  async function request({ method, path, query, body, auth = 'header', keepalive = false, timeoutMs }) {
+  async function request({ method, path, query, body, auth = 'header', keepalive = false, cache, timeoutMs }) {
+    // append, not set: React Native below 0.80 throws on set, and these names are unique.
     const params = new URLSearchParams();
     for (const [name, value] of Object.entries(query ?? {})) {
-      if (value !== undefined) params.set(name, String(value));
+      if (value !== undefined) params.append(name, String(value));
     }
-    if (auth === 'query') params.set('key', apiKey);
+    if (auth === 'query') params.append('key', apiKey);
     const qs = params.toString();
     const url = `${root}${path}${qs ? `?${qs}` : ''}`;
 
     const headers = { Accept: 'application/json' };
     if (auth === 'header') headers.Authorization = `Bearer ${apiKey}`;
     const init = { method, headers };
+    if (cache) init.cache = cache;
     if (body !== undefined) {
       headers['Content-Type'] = 'application/json';
       init.body = JSON.stringify(body);