@recapi/client 0.3.0 → 0.5.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.3.0/index.js';
+  import { createClient } from 'https://api.example.com/sdk/0.5.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
@@ -64,7 +64,7 @@ const observer = new IntersectionObserver(async (entries) => {
   if (!entries.some((entry) => entry.isIntersecting)) return;
   observer.disconnect();
   const { items } = await recapi.recommend({ count: 8, tagsAny: ['sports'] });
-  render(slot, items);                // [{ itemId, score, slot, metadata }]
+  render(slot, items);                // [{ itemId, score, slot, why, metadata }]
 }, { rootMargin: '0px 0px 400px 0px' });
 observer.observe(slot);
 
@@ -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
@@ -250,6 +262,17 @@ 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`).
 
+### Magento
+
+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. 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
 
 ```js
@@ -269,6 +292,23 @@ 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.
 
+### Showing why an item is listed
+
+Every item carries `why`, a short [reason code](../../docs/api.md#reason-codes)
+that names no item of the visitor's history, so any page can show it. Pick
+your own words, and show no label for a code you don't know (new ones may
+come):
+
+```js
+const LABELS = {
+  for_you: 'Picked for you', similar: 'Similar items', next: 'Up next',
+  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
+}
+```
+
 ## API
 
 ### `createClient(options)`
@@ -285,7 +325,7 @@ Timers do not keep a Node process alive. Call `await client.flush()` or
 | `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 |
 
@@ -308,17 +348,17 @@ Timers do not keep a Node process alive. Call `await client.flush()` or
   control characters. A stored history entry whose id breaks the rule,
   left by an earlier SDK version, is dropped when the page loads.
 - **`recommend({ count, tagsAny, tagsAll, exclude, contextItemId, placement, discovery })`**
-  resolves to `{ recommendationId, fallback, items: [{ itemId, score, slot, metadata }] }`.
+  resolves to `{ recommendationId, fallback, items: [{ itemId, score, slot, why, metadata }] }`.
   `metadata` is the object you stored with the item
   ([Item metadata](../../docs/api.md#item-metadata): name, picture, link,
   price…), absent when it has none, so you can render the list without a
-  lookup.
+  lookup. `why` is the item's [reason code](#showing-why-an-item-is-listed).
   It never retries and waits at most 1.5 s (less if `timeoutMs` is lower):
   a late recommendation is worthless. See [Fallback](#fallback) for what
   happens when the call fails. The user's rejected items (the newest 200)
   are added to `exclude`, after yours, up to the API's limit of 500. The SDK does not send `explain`, which needs
   a secret key: call the API from your backend for that.
-- **`popular({ tagsAny, tagsAll, count })`** resolves to `{ items: [{ itemId, score, metadata }] }`.
+- **`popular({ tagsAny, tagsAll, count })`** resolves to `{ items: [{ itemId, score, why, metadata }] }`.
   A public key goes in `?key=`, so the response can be cached by a CDN and
   the request needs no CORS preflight. A secret key (Node) goes in the
   `Authorization` header, because the API refuses a secret key in a URL.
@@ -525,8 +565,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
 
@@ -560,6 +613,15 @@ minifier, to keep zero dev dependencies.
 
 ## Changes
 
+- 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)).
 - 2026-10-31: version 0.3.0. Recommended and popular items carry the
   item's `metadata` (name, picture, link, price… stored with
   `PUT /v1/items`) when it has some, fallback lists included

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;
@@ -99,6 +102,10 @@ export interface RecommendParams {
   discovery?: number;
 }
 
+/** 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 & {});
+
 /** The object stored with the item (`PUT /v1/items`, `metadata`): name, picture, link, price... */
 export type ItemMetadata = Record<string, unknown>;
 
@@ -106,6 +113,8 @@ export interface RecommendedItem {
   itemId: string;
   score: number;
   slot: 'exploit' | 'explore' | 'backfill' | string;
+  /** Why the item is listed, to label it for visitors (docs/api.md, "Reason codes"). New codes may be added. */
+  why?: ReasonCode;
   /** Absent when the item has no metadata. */
   metadata?: ItemMetadata;
 }
@@ -130,7 +139,7 @@ export interface PopularParams {
 }
 
 export interface PopularResult {
-  items: Array<{ itemId: string; score: number; metadata?: ItemMetadata }>;
+  items: Array<{ itemId: string; score: number; why?: ReasonCode; metadata?: ItemMetadata }>;
 }
 
 /**

package/package.json

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

@@ -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.
@@ -127,8 +128,14 @@ export function createClient(options) {
     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 +407,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 +423,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(() => {
@@ -448,7 +457,7 @@ export function createClient(options) {
      * @param {{ count?: number, tagsAny?: string[], tagsAll?: string[], exclude?: string[],
      *   contextItemId?: string, placement?: string, discovery?: number }} [params]
      * @returns {Promise<{ recommendationId: string | null, fallback: boolean,
-     *   items: Array<{ itemId: string, score: number, slot: string, metadata?: object }> }>}
+     *   items: Array<{ itemId: string, score: number, slot: string, why?: string, metadata?: object }> }>}
      */
     async recommend(params = {}) {
       const deadline = Math.min(timeoutMs, RECOMMEND_TIMEOUT_MS);
@@ -476,7 +485,7 @@ export function createClient(options) {
      * preflight; a secret key stays in the `Authorization` header.
      *
      * @param {{ tagsAny?: string[], tagsAll?: string[], count?: number }} [params]
-     * @returns {Promise<{ items: Array<{ itemId: string, score: number, metadata?: object }> }>}
+     * @returns {Promise<{ items: Array<{ itemId: string, score: number, why?: string, metadata?: object }> }>}
      */
     async popular(params = {}) {
       const items = await fetchPopular(params);
@@ -492,12 +501,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 +542,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();
@@ -585,12 +597,15 @@ export function createClient(options) {
 }
 
 /**
- * An item of a list as the SDK returns it. `metadata` (the shop's own
- * object, set with the item) is there only when the item has some, so an
- * item without it keeps the shape it had before metadata existed.
+ * An item of a list as the SDK returns it. `why` (the reason code) and
+ * `metadata` (the shop's own object, set with the item) are there only when
+ * the API sent them, so an item keeps the shape it had before they existed.
  */
-function toItem({ item_id: itemId, score, metadata }, slot) {
+function toItem({ item_id: itemId, score, why, metadata }, slot) {
   const item = slot === undefined ? { itemId, score } : { itemId, score, slot };
+  if (typeof why === 'string' && why !== '') {
+    item.why = why;
+  }
   if (metadata !== null && typeof metadata === 'object' && !Array.isArray(metadata) && Object.keys(metadata).length > 0) {
     item.metadata = metadata;
   }