@recapi/client 0.2.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.2.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
@@ -57,8 +57,16 @@ recapi.track('item-42', 'view');
 // resolves with popular items instead, and with an empty list if recapi is
 // down altogether (hide the slot): no try/catch needed. Give the widget's
 // container a CSS min-height so the page doesn't jump when the items arrive.
-const { items } = await recapi.recommend({ count: 8, tagsAny: ['sports'] });
-render(items);                        // [{ itemId, score, slot }]
+// Below the fold, ask only once it nears the screen: each list is billed
+// and counted as shown, and many visitors never scroll that far.
+const slot = document.getElementById('recommendations');
+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, why, metadata }]
+}, { rootMargin: '0px 0px 400px 0px' });
+observer.observe(slot);
 
 // Later, the user clicks a recommended item and lands on its page (a
 // view). No need to pass the recommendation id: the SDK remembers which
@@ -82,7 +90,13 @@ in two places, both shown with your address in the dashboard's quick start:
   `product.handle` and `customer.id`, which a section reads as the layout
   does, and it stays far below the setting's 50 KB. It identifies a
   logged-in customer, tracks product views and fills any `<div id="recapi-recommendations">` with 4 product
-  cards it loads from Shopify's `/products/<handle>.js`. The product handle
+  cards it loads from Shopify's `/products/<handle>.js`. Like the row of
+  Shopify's own themes, it asks for them only once the div comes within
+  400px of the screen (an `IntersectionObserver`, at once in a browser
+  without one): each list is billed and counted as an impression, and a
+  visitor who never scrolls down saw none. The view goes at page load. A
+  shop moving from an earlier snippet sees fewer served lists and its CTR
+  rise once, since lists nobody reached no longer count. The product handle
   is the item id. recapi has no catalog of a Shopify shop, so the snippet
   asks for 6 and skips products that are sold out (`available: false`) or
   deleted (404). All 6 count as one served list: CTR and lift are per list,
@@ -116,6 +130,16 @@ in two places, both shown with your address in the dashboard's quick start:
   pixel writes it back only if the page didn't change it since the pixel
   read it (its event is sent either way).
 
+Every Online Store 2.0 theme already shows Shopify's own product
+recommendations on the product page ("Related products", "You may also
+like" or "Product recommendations",
+[built from orders, descriptions and collections](https://shopify.dev/docs/storefronts/themes/product-merchandising/recommendations/related-products)).
+The quick start tells the merchant to hide that section with its eye icon
+(one click to undo) and put the Custom Liquid section with the `<div>` in
+its place, and the same in a cart that shows Shopify's complementary
+products: two rows split the clicks and dilute a pilot's lift. It stays
+hidden for the whole test.
+
 Both files pass the same [`project`](#createclientoptions), which the quick start fills
 in for your environment, so they share the visitor's state whichever public
 key each holds: keys are shown once, and a pixel added later with a new key
@@ -172,9 +196,33 @@ product pages stored and is credited to the recommendation clicked: no
 pixel and no cart attribute. Page caches serve product pages as stored
 HTML, so the plugin prints only what is the same for every visitor (the
 product id, the Store API's address); only the order-received page, which
-caches skip, prints the order. The widget fills
-`<div id="recapi-recommendations">` like the Shopify snippet's, loading the
-6 recommended products in one request to WooCommerce's public Store API
+caches skip, prints the order.
+
+The plugin prints the row's `<div id="recapi-recommendations">` in place of
+WooCommerce's Related products on product pages, so a shop on any theme
+shows it with no editing and never two rows (two split the clicks and slow
+the lift's verdict); deactivating the plugin brings Related products back.
+Classic themes: from `template_redirect`, it swaps
+`woocommerce_output_related_products` on
+`woocommerce_after_single_product_summary` (priority 20) for the div, only
+on product pages and only if the theme still has it there (a theme that
+removed it keeps its choice). Block themes: `render_block` filters return
+the div for the Related Products block and for a Product Collection showing
+`woocommerce/product-collection/related`. Elsewhere (page builders, the cart
+page, themes that print related products their own way) the `[recapi]`
+shortcode prints it. The div is printed once per page, and if the merchant
+pasted one too, the script fills the first and removes the others.
+
+In Related products' place the row keeps their heading: WooCommerce's
+translated "Related products" through the
+`woocommerce_product_related_products_heading` filter its own template
+applies, so a theme's wording carries over (an empty value shows no title).
+The script inserts it as `<h2 class="recapi-heading">` before the div once
+the cards fill, as text, so a row that stays hidden leaves no title. The
+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
 [WP Consent API](https://wordpress.org/plugins/wp-consent-api/)
@@ -202,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
@@ -221,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)`
@@ -260,13 +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 }] }`.
+  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. `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 }] }`.
+- **`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.
@@ -508,8 +585,15 @@ 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
+  ([Client methods](#client-methods)).
 - 2026-10-30: version 0.2.0, the same code as 0.1.2: the first version
-  published to npm by GitHub Actions (trusted publishing), with provenance.
+  published to npm by GitHub Actions (trusted publishing).
 - 2026-10-26: version 0.1.2. When `GET /v1/popular` fails too (recapi is
   down altogether), `recommend()` resolves with an empty list
   (`fallback: true`) instead of rejecting, and reports both errors to

package/index.d.ts

@@ -99,10 +99,21 @@ 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>;
+
 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;
 }
 
 export interface RecommendResult {
@@ -125,7 +136,7 @@ export interface PopularParams {
 }
 
 export interface PopularResult {
-  items: Array<{ itemId: string; score: number }>;
+  items: Array<{ itemId: string; score: number; why?: ReasonCode; metadata?: ItemMetadata }>;
 }
 
 /**

package/package.json

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

@@ -323,7 +323,7 @@ export function createClient(options) {
     }
 
     const recommendationId = response.recommendation_id;
-    const items = response.items.map(({ item_id: itemId, score, slot }) => ({ itemId, score, slot }));
+    const items = response.items.map((item) => toItem(item, item.slot));
     mutate(() => {
       const t = now();
       for (const { itemId } of items) {
@@ -360,7 +360,7 @@ export function createClient(options) {
     return items
       .filter(({ item_id: itemId }) => !skip.has(itemId))
       .slice(0, n)
-      .map(({ item_id: itemId, score }) => ({ itemId, score, slot: 'backfill' }));
+      .map((item) => toItem(item, 'backfill'));
   }
 
   /**
@@ -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 }> }>}
+     *   items: Array<{ itemId: string, score: number, slot: string, why?: string, metadata?: object }> }>}
      */
     async recommend(params = {}) {
       const deadline = Math.min(timeoutMs, RECOMMEND_TIMEOUT_MS);
@@ -476,11 +476,11 @@ 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 }> }>}
+     * @returns {Promise<{ items: Array<{ itemId: string, score: number, why?: string, metadata?: object }> }>}
      */
     async popular(params = {}) {
       const items = await fetchPopular(params);
-      return { items: items.map(({ item_id: itemId, score }) => ({ itemId, score })) };
+      return { items: items.map((item) => toItem(item)) };
     },
 
     /**
@@ -584,6 +584,22 @@ export function createClient(options) {
   };
 }
 
+/**
+ * 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, 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;
+  }
+  return item;
+}
+
 /**
  * Whether `recommend()` should fall back to popular items: recapi could not
  * answer in time or failed on its side. A 429 is the tenant's own limit