@recapi/client 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 recapi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,561 @@
-# Temporary Holding Version
+# @recapi/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+JavaScript client for the recapi recommendation API, for browsers and
+Node ≥ 18. Plain ES modules, no build step, no runtime dependencies.
+
+The SDK keeps the user's interaction history on the device and sends it
+with every recommendation request. Recommendations reflect the latest
+click at once, and the server does not need to look anything up. The SDK
+also batches events and attributes them to recommendations for you.
+
+## Install
+
+On a site without a build step (a theme, plain HTML), load the SDK from
+your recapi API with one tag. The API serves the files of `src/` as they
+are, gzipped, and browsers cache them for a year:
+
+```html
+<script type="module">
+  import { createClient } from 'https://api.example.com/sdk/0.1.2/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
+</script>
+```
+
+A module script runs after the page is parsed and never blocks it. The
+dashboard's quick start shows this tag with your API's address. A site
+with a Content-Security-Policy allows that address in `script-src` and
+`connect-src`. Each version's files never change: a later version gets a
+new path, and an older path redirects to it, so a pasted tag keeps
+working. New visitors then get the new version; a browser that cached the
+older files may keep running them for up to a year.
+
+With a bundler (Vite, webpack…), install the package instead:
+
+```sh
+npm install @recapi/client
+```
+
+## Quick start
+
+### Browser
+
+```js
+import { createClient } from '@recapi/client';   // or the /sdk/ URL above
+
+const recapi = createClient({
+  apiKey: 'rk_pub_…',               // public key only, never a secret key
+  baseUrl: 'https://api.example.com',
+  placement: 'homepage'
+});
+
+// The user opened an item: a product, an article, a video… (level 3).
+recapi.track('item-42', 'view');
+
+// Show recommendations. If recapi is slow or failing, recommend()
+// 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 }]
+
+// 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
+// recommendation showed this item, and later events on it (levels 5 and 10,
+// such as read to the end or bought) are attributed too, for 24 hours after
+// the click.
+recapi.track('item-77', 'view');
+```
+
+### Shopify
+
+Shopify's checkout runs no theme code, so a Shopify shop installs recapi
+in two places, both shown with your address in the dashboard's quick start:
+
+- [`shopify/theme.liquid`](shopify/theme.liquid), pasted in a *Custom
+  Liquid* section the theme editor adds to the footer group, so it runs on
+  every page; a theme update keeps editor sections but drops code edits
+  ([Updating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/updating-themes)).
+  A theme whose footer takes no sections gets it before `</body>` in
+  `layout/theme.liquid` instead, again after each update. Its Liquid is
+  `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
+  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,
+  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
+  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
+  Shopify's [Customer Privacy API](https://shopify.dev/docs/api/customer-privacy):
+  it keeps a history only with Analytics consent (the pixel's category;
+  where no consent is required Shopify reports it allowed) and fails closed
+  if the API doesn't load within 2 s. Without consent it stores nothing and
+  sends events without `anon_id`, and each card links to its product with
+  `?rec=<recommendation id>`, which the product page's view passes on, so a
+  click is still credited (see [Consent](#consent-and-eprivacy)). The page
+  then removes `rec` from its address (`history.replaceState`, other
+  parameters kept): recapi credits an explicit id to whoever sends it, so a
+  copied or shared link would credit strangers' visits and purchases to it.
+- [`shopify/pixel.js`](shopify/pixel.js), a custom pixel (Settings →
+  Customer events): on `product_added_to_cart` it tracks the product as a
+  `cart` (level 5, the default conversion level, so a pilot's conversion
+  lift counts carts, not only the rarer orders), and on `checkout_completed`
+  each bought product as a purchase, with the handle from the product's URL.
+  A pixel runs in a sandbox with storage of its own, so it loads the shop
+  page's SDK state through Shopify's asynchronous `browser.localStorage`,
+  the way [Custom storage](#custom-storage) preloads an async store: the
+  event carries the visitor's ids and the recommendation that showed the
+  item. On the storefront the theme snippet writes that state too, so the
+  pixel writes it back only if the page didn't change it since the pixel
+  read it (its event is sent either way).
+
+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
+still credits each add to cart to the visitor and their recommendation.
+Shopify's `product_added_to_cart` event carries only the cart line, not the
+cart's attributes
+([docs](https://shopify.dev/docs/api/web-pixels-api/standard-events/product_added_to_cart)),
+so a cart has no fallback like a purchase's below.
+
+Shopify doesn't promise that the checkout's pixel can read the
+storefront's storage, so the snippet also leaves the visitor's id and the
+recommendations they clicked (the SDK's stored `shown` entries with a click
+time, the 10 newest) in the cart, as a `_recapi` cart attribute: the leading
+`_` hides it from the buyer, but the merchant sees it in the order's
+details. The snippet writes it through `POST {root}cart/update.js` only with
+consent (it watches what the SDK stores), and only when it changes: a
+request per click on a card, none per page; a failed request is retried at
+the next change of the state. Withdrawing consent empties it. When the
+pixel's storage read comes back empty, `checkout_completed` rebuilds the
+state from `event.data.checkout.attributes`, so the purchase still carries
+the visitor and the recommendation; a stored state always wins, and a value
+the SDK can't read is ignored. An item shown again in a later list loses its
+click (as in storage), and orders that don't go through the online store's
+cart (POS, draft orders, subscription renewals) carry no attribute.
+
+`test/shopify.test.js` runs both files as the quick start shows them: a view,
+a click on a recommendation, an add to cart, then a purchase in the checkout. A change to
+them needs no new SDK version (they import the served one), but it changes
+what every new Shopify shop pastes. The quick start fills in the current
+version, your address and your project (`jssdk.Shopify`).
+
+### WooCommerce
+
+[`woocommerce/recapi.php`](woocommerce/recapi.php) is a one-file WordPress
+plugin (or a snippet for Code Snippets or WPCode) that prints the SDK on
+every page from `wp_footer`. The product id is the item id. It tracks:
+
+- a `view` on product pages, with `?rec=<recommendation id>` from a card's
+  link (then removed from the address, as on Shopify);
+- a `cart` (level 5) once per add to cart: on the classic product page's
+  form submit (the page reloads, so it counts at once), or on jQuery's
+  `added_to_cart` (Ajax buttons) or the blocks' `wc-blocks_added_to_cart`
+  after a click on a button with `data-product_id`. The blocks event
+  carries no product, and a page with a mini-cart block fires both for one
+  click, so the click is the product and the first event uses it up;
+- a `purchase` per order line on the order-received page (classic and block
+  checkout alike: `is_order_received_page()`), with the order key checked,
+  nothing for a failed or cancelled payment, and the order marked
+  (`_recapi_counted` meta) so a reload prints nothing. A logged-in buyer's
+  customer id is passed to `identify()` there.
+
+The checkout is the shop's own origin, so the purchase reads the state the
+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
+(`/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/)
+(`wp_has_consent('statistics')`, `wp_listen_for_consent_change`), which
+banner plugins feed and which reports allowed where no banner manages
+consent; without the API the plugin stores nothing, as the Shopify snippet
+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.
+
+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,
+one `purchase` per order line, dated when the order was paid (else
+placed). The buyer is the customer id `identify()` sends, a guest
+`woocommerce-` + `wp_hash()` of their email (keyed with the site's salts,
+so recapi never sees or can guess the email), or without an email
+`woocommerce-order-<id>`. Only shop managers (`manage_woocommerce`) with
+the page's nonce get the file, and it reads orders 200 at a time through
+`wc_get_orders` (HPOS or not). The import skips rows already uploaded and
+purchases the order-received page already sent.
+
+`test/woocommerce.test.js` prints pages through PHP (`test/wordpress.php`
+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`).
+
+### Node
+
+```js
+import { createClient, memoryStorage } from '@recapi/client';
+
+const recapi = createClient({
+  apiKey: process.env.RECAPI_KEY,
+  baseUrl: 'https://api.example.com',
+  storage: memoryStorage()            // the default in Node anyway
+});
+
+recapi.identify('cust-881');
+recapi.track('item-42', 10);          // the action that matters most: a purchase, a subscription…
+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.
+
+## API
+
+### `createClient(options)`
+
+| Option | Default | Notes |
+|---|---|---|
+| `apiKey` | required | `rk_pub_…` in browsers |
+| `baseUrl` | required | API origin |
+| `placement` | – | default placement for `recommend()` |
+| `storage` | localStorage, else memory | any `{ getItem, setItem, removeItem }` synchronous store |
+| `project` | first 16 chars of `apiKey` | storage namespace: key `recapi:v1:<project>` |
+| `flushIntervalMs` | `2000` | delay before queued events are sent |
+| `maxBatch` | `100` | events per request (max 1000); a full queue flushes at once |
+| `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 |
+| `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 |
+
+### Client methods
+
+- **`track(itemId, level, { recommendationId? })`**: `level` is any integer
+  0–10 of the [recommended scale](../../docs/api.md#interaction-levels) (3
+  opened, 5 strong interest, 10 the action that matters most), or one of its
+  shop names `'view'`, `'cart'` and `'purchase'` (3, 5 and 10). `'reject'`
+  (or any level -1 to -10) is an explicit "not interested": the item is
+  never recommended to this user again until a positive event on it. Use
+  it for a rejection control only, never for skips or bounces
+  ([Rejections](../../docs/api.md#rejections)). Updates the
+  local history at once and queues the event with `anon_id`, `user_id`, a
+  timestamp and a fresh `event_id` (the idempotency
+  key, reused on retries). Level 0 means an impression: it is sent but does
+  not change the history. Throws `RecapiError('invalid_request')` on bad
+  arguments, with the API's rules: an item id is 1–256 bytes of UTF-8
+  (128 characters of Cyrillic or accented Latin, 85 of CJK) without
+  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 }] }`.
+  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 }] }`.
+  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.
+  The [Fallback](#fallback) sends the key the same way.
+- **`identify(userId, { history? })`**: see [Login and logout](#login-and-logout).
+- **`reset()`**: logout. Clears the user id, history and attribution data,
+  and starts a new anonymous id. Events already queued keep the ids they
+  were tracked with.
+- **`setConsent(boolean)`**: grants or withdraws storage consent.
+- **`flush()`**: sends queued events now. Never rejects. Errors go to
+  `onError`, and batches that can still succeed stay queued.
+- **`getHistory()`** returns `{ history, recent, rejected }` exactly as the
+  next request would send it (`rejected` goes into `exclude`). Use it for
+  debugging.
+- **`destroy()`** removes listeners and timers, then flushes.
+
+### Errors
+
+Every failure is a `RecapiError` with `code`, `status` and `message`. The
+API error body supplies these when present. Client-side codes are
+`network`, `timeout`, `invalid_response`, `event_rejected` (some events in
+a 202 were rejected; see `details`) and `queue_overflow`. `status` is 0
+when no HTTP response was received. Use `error.retryable` to tell
+transient failures apart. `recommend()` resolves with popular items
+instead of rejecting on `network`, `timeout` and 5xx errors, and reports
+the error to `onError` (see [Fallback](#fallback)).
+
+### Fallback
+
+When recapi does not answer `recommend()` within 1.5 s, cannot be
+reached, or fails with a 5xx, the SDK asks `GET /v1/popular` with the same
+`tagsAny`, `tagsAll` and `count` (also within 1.5 s) and resolves with
+`{ recommendationId: null, fallback: true, items }`. The items have slot
+`backfill`. The items in `exclude` and the `contextItemId` item are left
+out, and the list still has `count` items when the catalog has enough, so
+the widget keeps its size. Nothing is recorded for attribution: events on these items carry no
+`recommendation_id`, so clicks and conversions on the dashboard count only
+real recommendations. The original error goes to `onError`.
+
+When `GET /v1/popular` fails too (recapi is down altogether), `recommend()`
+resolves with `{ recommendationId: null, fallback: true, items: [] }`, and
+both errors go to `onError`: hide the slot when `items` is empty. The page
+never needs a `catch` for an outage.
+
+`recommend()` still rejects, with no fallback, when:
+
+- the request is wrong or the key is not allowed: 400, 401, 403 (a
+  suspended tenant) and 404. These are integration bugs, so they stay
+  visible;
+- the tenant hit its limits: 429 `rate_limited` and 429 `quota_exceeded`.
+  These are limits to raise, not outages, and a fallback would hide them;
+- the response is malformed (`invalid_response`), for example a `baseUrl`
+  that points at your own site.
+
+## How it works
+
+### History
+
+The history follows [docs/history-spec.md](../../docs/history-spec.md)
+exactly, and the shared vectors in `spec/history_vectors.json` check it.
+Each item has a score that decays with a 7-day half-life. The SDK keeps
+the 50 heaviest items plus an ordered list of the 20 most recent distinct
+items. Requests carry `history: [[item_id, weight, age_s], …]` and
+`recent: [item_id, …]`. The pure functions (`applyEvent`, `toWire`,
+`fromSnapshot`, `merge`, …) are exported for server-side rendering and
+tests.
+
+Several tabs share one history: before each change, the SDK reads the
+latest stored state and writes the result back. If a write fails (quota
+exceeded, Safari private mode), the SDK keeps working from memory for the
+rest of the page.
+
+**Server snapshot.** When a request has an empty history and a `user_id`,
+the server scores it with its stored history (unless the tenant turned the
+server-side history off in the dashboard settings). It returns that history only
+to secret-key callers, because the history is personal data. Browsers using
+a public key therefore get the snapshot through your backend and
+`identify(userId, { history })`. When a snapshot does arrive (Node with a
+secret key), the SDK stores it only if it sent an empty history, so newer
+local data is never overwritten. Events tracked while that request was in
+flight are merged with the snapshot, not replaced by it, and so are the
+rejections the server may not have stored yet (see the merge rule below).
+A snapshot is merged once, because merging adds scores up: when two first
+`recommend()` calls run together (two placements on one page), both get it
+back and only one copy is kept. A reply's snapshot after
+`identify(userId, { history })` is skipped the same way. An empty snapshot
+(a user with nothing stored yet) leaves the next one trusted, and a new
+user id or `reset()` starts over.
+
+### Attribution
+
+`recommend()` remembers which recommendation showed each returned item.
+For 30 minutes after the display, any `track()` on that item carries that
+`recommendation_id` (impressions included), and the first one above
+level 0 is the click on it. After a click, the item's later events (an add
+to cart, a read to the end, a purchase) carry the id for 24 hours after the
+click. An item nobody
+clicked within 30 minutes was found some other way, and its events are no
+longer attributed. The dashboard counts a conversion only on an item
+clicked first (a level-5 event straight from the widget, such as an add to
+cart, counts as the click).
+
+This survives page loads when the SDK may use storage (see
+[Consent](#consent-and-eprivacy)). The map keeps at most 500 items, and
+the oldest are dropped first. An explicit `recommendationId` always wins;
+when it is the id of the recommendation that showed the item, it is the
+click on the item too.
+
+### Event delivery
+
+Events are sent in batches every `flushIntervalMs`, or as soon as
+`maxBatch` events are queued. Failed batches are retried with
+exponential backoff and jitter (3 retries, `Retry-After` honoured, at
+most 8 s between tries) on 429 `rate_limited`, 5xx, network errors and
+timeouts. If retries run out, the batch goes back in the queue and later
+flushes back off up to 60 s. The queue holds at most 1000 events, and the
+oldest are dropped first.
+
+Any other failure drops the whole batch and reports it to `onError`:
+400 `invalid_request`, 401, 403 (suspended tenant), 413, and 429
+`quota_exceeded`. The quota is checked per batch, so once the monthly
+event quota or spend cap is reached, events are lost until it resets or
+the plan changes. A 202 with some `rejected` events keeps the accepted
+ones, and the rejected ones are reported as `event_rejected`.
+
+When the page is hidden (`visibilitychange` → `hidden`, or `pagehide`),
+the SDK sends the queue at once using `fetch` with `keepalive: true`.
+It does not use `navigator.sendBeacon`, because a beacon cannot send the
+`Authorization` header and the API accepts `?key=` only on
+`GET /v1/popular`. A keepalive fetch also survives page unload, but the
+browser allows at most 64 KiB of keepalive bodies in flight per page, all
+requests together. The SDK marks a request keepalive only up to 60,000
+bytes (about 250 typical events). A default batch of 100 events is about
+24 KB, so about two full batches fit: keep `maxBatch` at 100 in
+browsers. The queue is flushed every `flushIntervalMs` (2 s), so it usually
+holds a few events. After a long network outage it can hold
+up to 1000 events. The queue lives in memory, so what does not fit in the
+budget is lost when the page closes. Every events request uses keepalive,
+so a batch already in flight when the user navigates away still arrives.
+
+### Login and logout
+
+- `identify(userId)` keeps the anonymous history, because it is the same
+  person before login. Switching from one user id to another starts a new
+  history and forgets which recommendations showed which items. A user id
+  follows the item id rule (1–256 bytes of UTF-8, no control characters);
+  `identify()` throws `RecapiError('invalid_request')` otherwise.
+- `identify(userId)` alone does not bring the user's history to a new
+  device. The server scores a request with its stored history only when
+  the request has no history at all. That is true on a fresh device until
+  the first `track()`. After that, only the local history counts. To carry
+  the full history over, pass a server snapshot, as below.
+- `identify(userId, { history: snapshot })` merges a server snapshot into
+  the local history. Your backend gets the snapshot with the secret key
+  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.
+- 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.
+- Merge rule for rejections: an item this device rejected stays rejected,
+  even if the snapshot scores it. The snapshot only says its events came
+  before `as_of`, and the rejection may not have reached the server yet.
+  A rejection in the snapshot wins over this device's events before
+  `as_of`; a later event on the item clears it.
+- `reset()` on logout.
+
+### Consent and ePrivacy
+
+Under the EU ePrivacy Directive (art. 5(3)), storing data on the user's
+device, or reading it back, generally needs prior consent unless it is
+strictly necessary. A recommendation history usually is not. Wire the SDK
+to your consent banner:
+
+```js
+const recapi = createClient({ apiKey, baseUrl, consent: cmp.hasConsent('personalisation') });
+cmp.onChange((granted) => recapi.setConsent(granted));
+```
+
+Without consent, the SDK never reads or writes storage and creates no
+anonymous id. The history and the attribution map live in memory for the
+current page only. A single-page app keeps attribution. On a multi-page
+site, a click that loads the item's page is not attributed unless you
+pass the id yourself, for example in the link:
+
+```js
+// On the listing page: link each item with its recommendation id
+// (null when the list is the popular fallback: then leave it out of the link).
+const { recommendationId, items } = await recapi.recommend({ count: 8 });
+// href = recommendationId ? `/p/${item.itemId}?rec=${recommendationId}` : `/p/${item.itemId}`
+
+// On the item's page:
+const url = new URL(location.href);
+const rec = url.searchParams.get('rec');
+recapi.track('item-77', 'view', { recommendationId: rec }); // null: automatic attribution
+// Then drop it, so a copied or shared address doesn't credit strangers to that list.
+if (rec !== null) {
+  url.searchParams.delete('rec');
+  history.replaceState(history.state, '', url);
+}
+```
+
+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.
+
+## Custom storage
+
+Any synchronous `{ getItem, setItem, removeItem }` works. Every call is
+guarded, so a throwing adapter never breaks the page. For an async store
+such as React Native AsyncStorage, preload the value into memory before
+creating the client, and write it back asynchronously:
+
+```js
+const key = 'recapi:v1:myproject';
+const cache = new Map([[key, await AsyncStorage.getItem(key)]]);
+const storage = {
+  getItem: (k) => cache.get(k) ?? null,
+  setItem: (k, v) => { cache.set(k, v); AsyncStorage.setItem(k, v); },
+  removeItem: (k) => { cache.delete(k); AsyncStorage.removeItem(k); }
+};
+createClient({ apiKey, baseUrl, project: 'myproject', storage });
+```
+
+Corrupt or unrecognised stored data is discarded. Bumping the `v1` in the
+key on a format change makes old data invisible.
+
+## Size budget
+
+Budget: **6 KB gzip** after minification. The sources ship unminified with
+full JSDoc: 53 KB raw in five files, 18 KB as the API serves them (gzip -9),
+and the browser caches them for a year. With comments stripped and no
+minification they are 7.2 KB gzip. A bundler's minifier should bring
+that under the budget, but this has not been measured: the repo has no
+minifier, to keep zero dev dependencies.
+
+## Changes
+
+- 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
+  `onError` ([Fallback](#fallback)).
+- 2026-10-26: version 0.1.1. A server snapshot is merged once: two first
+  `recommend()` calls running together (Node with a secret key) no longer
+  double the user's stored scores ([Server snapshot](#history)).
+- 2026-10-26: version 0.1.0 is served by the API at
+  `/sdk/0.1.0/<file>.js`, so a site installs it with one script tag
+  ([Install](#install)).
+- 2026-10-25: `recommend()` falls back to popular items by itself on a
+  timeout (now 1.5 s), a network error or a 5xx, and resolves with
+  `fallback: true` and `recommendationId: null`
+  ([Fallback](#fallback)). A `catch` that called `popular()` no longer
+  runs for these errors and can go; 4xx and 429 still reject. `popular()`
+  sends a secret key in the `Authorization` header instead of `?key=`, and
+  `track()` treats `recommendationId: null` like no id.
+
+## Development
+
+```sh
+npm test        # node --test, zero dev dependencies
+```
+
+The API embeds `src/*.js` (module `recapi/sdkjs`, `embed.go`) and serves
+them at `/sdk/<version>/`, where browsers cache them for a year. So a
+change to `src/` needs a new version: bump `version` in `package.json`,
+add the entry the failing Go test `TestSDKChangesNeedANewVersion` prints
+to `published.json` (the digest is `sha256sum src/*.js | sha256sum`, then
+each file's exports), and change the `/sdk/<version>/` paths in this
+README and `docs/api.md` (the quick start follows by itself). Never edit
+an existing entry of `published.json`.
+Once production runs that version, the release service publishes it to
+npm as `@recapi/client` ([deployment.md](../../docs/deployment.md#publishing-the-javascript-library)):
+nobody runs `npm publish` by hand.
+
+Every older path, whatever its version number, redirects to the new
+files, and a browser that still caches some of the older files (after a
+partial cache eviction, or a page load that spans a deploy) runs them next
+to the new ones: an older file then imports from a newer one. So options
+and every file's named exports, internal ones too, only grow, like the
+HTTP API: an export keeps its name and accepts what older callers pass,
+and a rename keeps the old name as an alias (`export { isId as isItemId }`).
+`TestSDKKeepsPublishedExports` fails when a published export or file is
+gone; parameters need a careful review, as no test sees them. Two copies
+of a file can then load side by side, which is why the files keep no
+mutable module-level state.
+
+## License
+
+MIT ([LICENSE](LICENSE)).