@recapi/client 0.3.0 → 0.4.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.4.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);
 
@@ -250,6 +250,14 @@ 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.
+
 ### Node
 
 ```js
@@ -269,6 +277,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)`
@@ -308,17 +333,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.
@@ -560,6 +585,9 @@ minifier, to keep zero dev dependencies.
 
 ## Changes
 
+- 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

@@ -99,6 +99,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 +110,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 +136,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.4.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

@@ -448,7 +448,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 +476,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);
@@ -585,12 +585,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;
   }