@recapi/client 0.4.0 → 0.5.1

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.4.0/index.js';
+  import { createClient } from 'https://api.example.com/sdk/0.5.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
@@ -103,7 +103,15 @@ in two places, both shown with your address in the dashboard's quick start:
   so they are unchanged. Each card shows the picture (resized by Shopify's
   CDN with `?width=400`), the title and `price_min` formatted with
   `Intl.NumberFormat` in `Shopify.currency.active` and the page's `lang`
-  (no price if either is missing). A default style makes them a product row
+  (no price if either is missing). An item whose
+  [metadata](../../docs/api.md#item-metadata) has a `name` and an http(s)
+  `url` skips that lookup: its card is drawn from `name`, `url`, `picture`
+  (http(s) only) and `price` (text shown as it is, or a number in the
+  shop's currency, `{{ shop.currency }}`, shown only to visitors browsing in
+  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
   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
@@ -224,7 +232,11 @@ shortcode shows none unless given one: `[recapi heading="You may also like"]`.
 The widget fills it like the Shopify snippet's, once it nears the screen,
 loading the 6 recommended products in one request to WooCommerce's public Store API
 (`/wc/store/v1/products?include=…`) and skipping those not purchasable or
-out of stock. Consent comes from the
+out of stock. Items whose [metadata](../../docs/api.md#item-metadata)
+has a `name` and an http(s) `url` are left out of that request and drawn
+from it, as in the Shopify snippet (a number `price` is in the shop's
+currency, `woocommerce_currency`, and shown only while the visitor browses
+in it), so a row whose items all carry metadata needs no Store API call. Consent comes from the
 [WP Consent API](https://wordpress.org/plugins/wp-consent-api/)
 (`wp_has_consent('statistics')`, `wp_listen_for_consent_change`), which
 banner plugins feed and which reports allowed where no banner manages
@@ -233,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,
@@ -256,7 +293,10 @@ The Magento 2 module ([`sdk/php/magento`](../php/magento/README.md)) prints
 the SDK on every storefront page for views and add-to-carts, and sends
 orders from the server with the PHP library. With consent, its script
 mirrors the visitor's id and clicked recommendations into a first-party
-cookie so the server's purchases are credited like the SDK's own.
+cookie so the server's purchases are credited like the SDK's own. On product
+pages it fills recapi's row, drawing each card from the item's `metadata`
+or, without it, from the store; the row is printed with the store's own
+products, which stay while recapi has none.
 
 ### Node
 
@@ -310,7 +350,7 @@ for (const item of items) {
 | `timeoutMs` | `5000` | per-request timeout; `recommend()` waits 1.5 s at most |
 | `historyConfig` | spec defaults | `{ halfLifeSeconds, topK, recentSize }`; must match the server |
 | `consent` | `true` | storage consent, see [Consent](#consent-and-eprivacy) |
-| `respectDoNotTrack` | `false` | start without consent when DNT or Global Privacy Control is on |
+| `respectDoNotTrack` | `true` | when DNT or Global Privacy Control is on: store nothing, send no events, see [Do Not Track](#do-not-track) |
 | `onError` | – | gets errors from background work (flushes, storage, rejected events) and those `recommend()` fell back from |
 | `now`, `fetch`, `sleep` | `Date.now`, global `fetch`, `setTimeout` | for tests |
 
@@ -501,7 +541,9 @@ 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: on such a device, what was
+  browsed there since would count twice.
 - 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.
@@ -550,8 +592,21 @@ if (rec !== null) {
 Events are still sent, without `anon_id`. Don't call `track()` if you
 need no network at all. Withdrawing consent deletes the stored data.
 Granting it merges the in-memory history into storage.
-`respectDoNotTrack: true` starts without consent when the browser sends
-DNT or Global Privacy Control.
+
+### Do Not Track
+
+When the browser sends Do Not Track (`navigator.doNotTrack === '1'`) or
+Global Privacy Control (`navigator.globalPrivacyControl === true`), the
+SDK follows nobody: it reads and writes no storage, `track()` and
+`identify()` do nothing, and `setConsent(true)` doesn't lift it (the
+browser's setting is the visitor's standing answer). `recommend()` and
+`popular()` still work: the request carries no visitor id and no history,
+so the list is popular, trending or similar items (with `contextItemId`).
+The Shopify and WooCommerce snippets and Magento's storefront script
+build on the SDK and behave the same (Magento's order observer runs on the
+server and still sends the purchase). A site with its own legal basis for tracking those visitors
+passes `respectDoNotTrack: false` and gets the behaviour of 0.4.0 and
+earlier.
 
 ## Custom storage
 
@@ -585,6 +640,16 @@ minifier, to keep zero dev dependencies.
 
 ## Changes
 
+- 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
+  ([Do Not Track](#do-not-track)). Before, `respectDoNotTrack` was off by
+  default and only stopped storage. Snippets pasted with an older version
+  get it too: older versions' paths redirect to the current one.
 - 2026-10-31: version 0.4.0. Recommended and popular items carry `why`,
   a reason code you can turn into a label for visitors
   ([Showing why an item is listed](#showing-why-an-item-is-listed)).

package/index.d.ts

@@ -78,7 +78,10 @@ export interface ClientOptions {
   historyConfig?: Partial<HistoryConfig>;
   /** Initial storage consent, default `true`. */
   consent?: boolean;
-  /** Start without consent when Do Not Track / Global Privacy Control is on. */
+  /**
+   * Default `true`: when Do Not Track / Global Privacy Control is on, store
+   * nothing, send no events and no visitor ids; recommendations still work.
+   */
   respectDoNotTrack?: boolean;
   /** Receives errors from background work (flushes, storage) and those `recommend()` fell back from. */
   onError?: (error: unknown) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recapi/client",
-  "version": "0.4.0",
+  "version": "0.5.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

@@ -80,8 +80,9 @@ const PUBLIC_KEY_PREFIX = 'rk_pub_';
  * @property {number} [timeoutMs] Per-request timeout.
  * @property {Partial<HistoryConfig>} [historyConfig]
  * @property {boolean} [consent] Initial storage consent (default `true`).
- * @property {boolean} [respectDoNotTrack] Start without consent when the
- *   browser sends Do Not Track or Global Privacy Control.
+ * @property {boolean} [respectDoNotTrack] When the browser sends Do Not
+ *   Track or Global Privacy Control (default `true`): store nothing, send no
+ *   events and no visitor ids; recommendations are still asked for.
  * @property {(error: unknown) => void} [onError] Receives background errors,
  *   and the errors `recommend()` fell back from.
  * @property {() => number} [now] Clock in unix ms.
@@ -120,15 +121,29 @@ 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
   );
 
-  let consent = options.consent ?? true;
-  if (options.respectDoNotTrack && doNotTrackEnabled()) consent = false;
+  // DNT and GPC ask sites not to follow the visitor, and the homepage
+  // promises our script listens: such a page sends recapi nothing about them
+  // and keeps nothing on the device, so its lists are popular or similar
+  // items only. A banner's consent doesn't lift it: the browser's answer is
+  // the visitor's standing one. `respectDoNotTrack: false` is for a site with
+  // its own legal basis.
+  const quiet = (options.respectDoNotTrack ?? true) && doNotTrackEnabled();
+  let consent = !quiet && (options.consent ?? true);
 
   /** @type {HistoryState} */
   let history = emptyHistory();
@@ -400,6 +415,7 @@ export function createClient(options) {
      *   `reject` is -10). A negative level is an explicit rejection ("not
      *   interested"): the item is never recommended to this user again until
      *   a positive event on it. Don't send skips or bounces as rejections.
+     *   Does nothing under Do Not Track (see `respectDoNotTrack`).
      * @param {{ recommendationId?: string | null }} [options] Overrides the
      *   automatic attribution. `null` (a fallback list's id) is no override.
      */
@@ -415,6 +431,7 @@ export function createClient(options) {
           "level must be an integer between -10 and 10, or 'view', 'cart', 'purchase' or 'reject'"
         );
       }
+      if (quiet) return;
       const t = now();
       let attributed = recommendationId;
       mutate(() => {
@@ -492,12 +509,14 @@ export function createClient(options) {
      * `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 nothing under Do Not Track: requests name nobody.
      *
      * @param {string} id
      * @param {{ history?: ServerSnapshot }} [options]
      */
     identify(id, { history: snapshot } = {}) {
       if (!isId(id)) throw new RecapiError('invalid_request', 'userId must be 1-256 bytes of UTF-8 without control characters');
+      if (quiet) return;
       mutate(() => {
         if (userId && userId !== id) {
           history = emptyHistory();
@@ -531,12 +550,13 @@ export function createClient(options) {
      * consent nothing is read from or written to storage and no anonymous id
      * exists; the history lives in memory for the current page only.
      * Withdrawing deletes the stored data. Granting merges any previously
-     * stored history with the in-memory one.
+     * stored history with the in-memory one. Does nothing under Do Not Track:
+     * nothing is stored whatever the banner says.
      *
      * @param {boolean} value
      */
     setConsent(value) {
-      if (value === consent) return;
+      if (quiet || value === consent) return;
       consent = Boolean(value);
       if (!consent) {
         store.remove();