@recapi/client 0.5.1 → 0.6.1

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.5.1/index.js';
+  import { createClient } from 'https://api.example.com/sdk/0.6.1/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)
@@ -327,7 +469,7 @@ come):
 ```js
 const LABELS = {
   for_you: 'Picked for you', similar: 'Similar items', next: 'Up next',
-  trending: 'Trending now', popular: 'Popular', new: 'New',
+  bought_together: 'Often bought together', trending: 'Trending now', popular: 'Popular', new: 'New',
 };
 for (const item of items) {
   const label = LABELS[item.why];     // undefined for explore, more and future codes: no label
@@ -398,6 +540,9 @@ for (const item of items) {
 - **`getHistory()`** returns `{ history, recent, rejected }` exactly as the
   next request would send it (`rejected` goes into `exclude`). Use it for
   debugging.
+- **`getAnonId()`** returns this device's anonymous id, the `anon_id` its
+  events carry, or `null` without consent and under Do Not Track. See
+  [Login and logout](#login-and-logout).
 - **`destroy()`** removes listeners and timers, then flushes.
 
 ### Errors
@@ -542,8 +687,18 @@ so a batch already in flight when the user navigates away still arrives.
   item by item. Use it only when the snapshot does not already contain
   this device's events, typically right after login. Otherwise those
   events count twice. The snapshot also holds the anonymous browsing of
-  the devices the user logged in on before: on such a device, what was
-  browsed there since would count twice.
+  the devices the user logged in on before, this one included when it was
+  not `reset()` at logout. Send `getAnonId()` with the login request and
+  have your backend ask for `GET /v1/users/{id}/history?anon_id=…`: the
+  snapshot then leaves out this device's own browsing.
+
+  ```js
+  // Browser, at login:
+  const res = await fetch('/login', { method: 'POST', body: JSON.stringify({ ...form, anonId: recapi.getAnonId() }) });
+  recapi.identify(userId, { history: (await res.json()).recapiHistory });
+  // Backend, with the secret key:
+  // GET /v1/users/{userId}/history?anon_id={anonId}   (leave anon_id out when it is null)
+  ```
 - Merge rule for the recent lists: take the union of both lists and order
   it by interaction time, oldest first. An item in both lists takes its
   latest time. Then keep the last 20.
@@ -640,6 +795,16 @@ minifier, to keep zero dev dependencies.
 
 ## Changes
 
+- 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
+  reset at logout.
 - 2026-11-01: version 0.5.1. Without consent, and under Do Not Track, the
   SDK no longer touches `localStorage` at all: before, it wrote and removed a
   probe key when the client was created, to check that storage works. Now
@@ -681,8 +846,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/index.d.ts

@@ -104,7 +104,8 @@ export interface RecommendParams {
 
 /** An item's reason code: map the ones you want to your own label, show none for an unknown one. */
 export type ReasonCode =
-  | 'for_you' | 'similar' | 'next' | 'trending' | 'popular' | 'new' | 'explore' | 'more' | (string & {});
+  | 'for_you' | 'similar' | 'next' | 'bought_together' | 'trending' | 'popular' | 'new' | 'explore' | 'more'
+  | (string & {});
 
 /** The object stored with the item (`PUT /v1/items`, `metadata`): name, picture, link, price... */
 export type ItemMetadata = Record<string, unknown>;
@@ -159,6 +160,8 @@ export interface RecapiClient {
   /** Never rejects; failures go to `onError`. */
   flush(): Promise<void>;
   getHistory(): WireHistory;
+  /** This device's anonymous id; null without consent or under Do Not Track. */
+  getAnonId(): string | null;
   destroy(): Promise<void>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recapi/client",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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);
@@ -508,13 +525,15 @@ export function createClient(options) {
      * `options.history` takes a server snapshot (from
      * `GET /v1/users/{id}/history`, fetched by your backend with the secret
      * key) and merges it into the local history. Only pass a snapshot that
-     * does not already contain this device's events, or they count twice.
+     * does not already contain this device's events, or they count twice:
+     * fetch it with this device's `getAnonId()`.
      * Does nothing under Do Not Track: requests name nobody.
      *
      * @param {string} id
      * @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(() => {
@@ -537,6 +556,7 @@ export function createClient(options) {
      * ids they were tracked with.
      */
     reset() {
+      start();
       history = emptyHistory();
       userId = null;
       shown = new Map();
@@ -556,6 +576,7 @@ export function createClient(options) {
      * @param {boolean} value
      */
     setConsent(value) {
+      start();
       if (quiet || value === consent) return;
       consent = Boolean(value);
       if (!consent) {
@@ -584,10 +605,26 @@ export function createClient(options) {
      * @returns {{ history: Array<[string, number, number]>, recent: string[], rejected: string[] }}
      */
     getHistory() {
+      start();
       if (consent) reload();
       return toWire(history, now(), config);
     },
 
+    /**
+     * This device's anonymous id, the `anon_id` its events carry: null
+     * without consent or under Do Not Track. Send it with the login request,
+     * so your backend asks `GET /v1/users/{id}/history?anon_id=…` for the
+     * snapshot it passes to `identify()`: that snapshot then leaves out this
+     * device's browsing, which the local history holds already.
+     *
+     * @returns {string | null}
+     */
+    getAnonId() {
+      start();
+      if (consent) reload();
+      return anonId;
+    },
+
     /**
      * Removes listeners and timers, then flushes what is queued.
      *
@@ -684,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,7 +77,7 @@ 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 }) {
     const params = new URLSearchParams();
     for (const [name, value] of Object.entries(query ?? {})) {
       if (value !== undefined) params.set(name, String(value));
@@ -88,6 +89,7 @@ export function createTransport({ baseUrl, apiKey, fetch, timeoutMs: defaultTime
     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);