@recapi/client 0.5.1 → 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.1/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
@@ -327,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
@@ -398,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
@@ -542,8 +545,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 +653,10 @@ 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

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.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

@@ -508,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
@@ -588,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.
      *