@recapi/client 0.5.0 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@ are, gzipped, and browsers cache them for a year:
 
 ```html
 <script type="module">
-  import { createClient } from 'https://api.example.com/sdk/0.5.0/index.js';
+  import { createClient } from 'https://api.example.com/sdk/0.6.0/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
@@ -245,6 +245,31 @@ does when its consent API fails to load. It declares compatibility with
 WooCommerce's order tables (HPOS) and checkout blocks when installed as a
 plugin, and registers with the WP Consent API.
 
+With a secret key pasted on WooCommerce → recapi (stored as the
+`recapi_secret_key` option, not autoloaded, and never printed back), the
+plugin describes the shop's products itself. Each product changed in a
+request (`woocommerce_new_product`, `woocommerce_update_product`, a stock
+status change, a variation's change as its parent's, a status change such as
+trashing or a scheduled product going live, a deletion) is read again at
+the end of the request and sent once the page is out, as one
+`PUT /v1/items/{item_id}` or one `POST /v1/items:batch`: one try of at most
+2 s through WordPress's HTTP API, a failure logged to WooCommerce → Status →
+Logs (source `recapi`), so a recapi outage never fails a save. A WP-Cron
+event (`recapi_sync`, daily, first run when the key is saved) sends the
+whole catalog, 200 products read and 1,000 sent at a time, oldest first,
+with three tries per batch against an outage; the page shows when it last
+ran, how many products it sent and why any were refused. Every item is
+complete: `active` only while the product is published, not hidden from the
+catalog, purchasable and in stock (the Store API cards' rule), its category
+names as `tags` (not "Uncategorized"), its creation date as `published_at`,
+and `name`, `url`, `picture` (the `woocommerce_thumbnail` size) and `price`
+(as the shop displays it, in its currency) as `metadata`, shrunk below
+2,048 bytes as the Magento module does (picture first, then the name). The
+row then draws every card from it, with no Store API call. Only items that
+changed are billed. The plugin uses WordPress's HTTP API rather than the PHP
+library so it stays one file (a snippet holds it) and follows the site's
+proxy settings.
+
 Have past orders? Download them from WooCommerce → recapi and upload the
 file on Import data. The plugin writes the last 90 days of processing and
 completed orders as the dashboard's `user_id,item_id,level,timestamp` CSV,
@@ -302,7 +327,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
@@ -373,6 +398,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
@@ -516,7 +544,19 @@ so a batch already in flight when the user navigates away still arrives.
   from `GET /v1/users/{id}/history`. Merging adds up the decayed scores
   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.
+  events count twice. The snapshot also holds the anonymous browsing of
+  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.
@@ -613,6 +653,14 @@ minifier, to keep zero dev dependencies.
 
 ## Changes
 
+- 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
+  that check waits for the first read or write, which only consent allows.
 - 2026-11-01: version 0.5.0. Do Not Track and Global Privacy Control are
   respected by default: the SDK then stores nothing and sends no events or
   visitor ids, and still asks for recommendations

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.0",
+  "version": "0.6.0",
   "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

@@ -121,8 +121,16 @@ export function createClient(options) {
     }
   };
   const transport = createTransport({ baseUrl, apiKey, fetch: fetchImpl, timeoutMs });
+  // 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;
+  const storage = () => (adapter ??= defaultStorage(report));
   const store = createStore(
-    options.storage ?? defaultStorage(report),
+    {
+      getItem: (key) => storage().getItem(key),
+      setItem: (key, value) => storage().setItem(key, value),
+      removeItem: (key) => storage().removeItem(key)
+    },
     storageKey(options.project ?? apiKey.slice(0, 16)),
     decodePersisted,
     report
@@ -500,7 +508,8 @@ 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
@@ -580,6 +589,20 @@ export function createClient(options) {
       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() {
+      if (consent) reload();
+      return anonId;
+    },
+
     /**
      * Removes listeners and timers, then flushes what is queued.
      *