@recapi/client 0.6.1 → 0.6.3

package/README.md

@@ -35,7 +35,7 @@ are, gzipped, and browsers cache them for a year:
 
 ```html
 <script type="module">
-  import { createClient } from 'https://api.example.com/sdk/0.6.1/index.js';
+  import { createClient } from 'https://api.example.com/sdk/0.6.3/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,6 +327,18 @@ repository root on any machine with Docker and python3:
 ./scripts/e2e_woocommerce.sh
 ```
 
+The file's `Version:` header is that version, so a plugin fix an advisory has
+to name needs a new SDK version (a change to the file alone doesn't move it).
+Its `Update URI:` header, on your API's host, tells WordPress (5.8 or later;
+the plugin needs 6.3) that its updates don't come from the WordPress.org
+directory, so a same-named plugin listed there isn't offered as an update. The
+last part is WordPress.org's documented behaviour, on its side of the update
+check: the end-to-end test shows WordPress reading the header, sending it with
+the check, asking the host's `update_plugins_{hostname}` filter and offering
+nothing, and can't show what WordPress.org would do with a same-named listing.
+Nothing answers that filter yet, so a shop gets no update notice. A snippet
+install has neither header's effect: both are comments there.
+
 ### Magento
 
 The Magento 2 module ([`sdk/php/magento`](../php/magento/README.md)) prints
@@ -493,7 +505,7 @@ for (const item of items) {
 | `historyConfig` | spec defaults | `{ halfLifeSeconds, topK, recentSize }`; must match the server |
 | `consent` | `true` | storage consent, see [Consent](#consent-and-eprivacy) |
 | `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 |
+| `onError` | `console.warn` for lost events only | 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
@@ -536,7 +548,8 @@ for (const item of items) {
   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.
+  `onError` ([without one](#event-delivery): lost events to `console.warn`), 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.
@@ -654,6 +667,13 @@ 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`.
 
+Without an `onError`, events lost for good (a batch refused as above,
+`event_rejected`, `queue_overflow`) print one `console.warn` line per error
+code per client, so a wrong key shows in the console without flooding a
+visitor's. Failures that can still succeed, storage errors and the errors
+`recommend()` falls back from print nothing. With an `onError`, nothing is
+printed.
+
 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
@@ -778,23 +798,37 @@ const storage = {
   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 });
+const client = createClient({ apiKey, baseUrl, project: 'myproject', storage });
 ```
 
+React Native has no page-hide event, so send the queue when the app leaves
+the screen: call `client.flush()` when `AppState` changes to `background`.
+`popular()` and the fallback list work on React Native below 0.80 as well,
+whose `URLSearchParams` has no working `set`. We read that class in React
+Native's 0.79 and 0.80 sources and test against a copy of its behaviour; the
+library has not been run on a device.
+
 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),
+full JSDoc: 58 KB raw in five files, 20 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
+minification they are 8.5 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-11-04: version 0.6.3. Without an `onError`, events lost for good (a
+  batch refused for good, `event_rejected`, `queue_overflow`) print one
+  `console.warn` line per error code per client ([Event delivery](#event-delivery)).
+- 2026-11-03: version 0.6.2. `popular()` and the fallback list of
+  `recommend()` no longer throw on React Native below 0.80, whose
+  `URLSearchParams.set` is not implemented. Query strings are unchanged
+  everywhere else.
 - 2026-11-02: version 0.6.1. The client draws its anonymous id at the
   first call instead of in `createClient`, so a back end on Cloudflare
   Workers may create it at module scope (it threw "Disallowed operation

package/index.d.ts

@@ -83,7 +83,11 @@ export interface ClientOptions {
    * 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. */
+  /**
+   * Receives errors from background work (flushes, storage) and those
+   * `recommend()` fell back from. Without it, events lost for good print one
+   * `console.warn` line per error code.
+   */
   onError?: (error: unknown) => void;
   /** Clock in unix ms. */
   now?: () => number;

package/package.json

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

@@ -84,7 +84,8 @@ const PUBLIC_KEY_PREFIX = 'rk_pub_';
  *   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.
+ *   and the errors `recommend()` fell back from. Without it, events lost for
+ *   good print one `console.warn` line per error code.
  * @property {() => number} [now] Clock in unix ms.
  * @property {typeof fetch} [fetch]
  * @property {(ms: number) => Promise<void>} [sleep] Backoff sleep (tests).
@@ -115,9 +116,16 @@ export function createClient(options) {
   const maxBatch = Math.min(Math.max(1, options.maxBatch ?? 100), MAX_EVENTS_PER_REQUEST);
   const maxQueue = Math.max(MAX_EVENTS_PER_REQUEST, maxBatch);
   const config = resolveConfig(options.historyConfig);
-  const report = (error) => {
+  const warned = new Set();
+  // `lost`: events are gone for good. Without an onError nothing else would
+  // say so; once per code, or a visitor's console fills up.
+  const report = (error, lost) => {
     try {
-      options.onError?.(error);
+      if (options.onError) options.onError(error);
+      else if (lost && !warned.has(error.code)) {
+        warned.add(error.code);
+        globalThis.console?.warn(`recapi: events lost: ${error.code}: ${error.message}`);
+      }
     } catch {
       // A faulty error handler must not break tracking.
     }
@@ -242,7 +250,7 @@ export function createClient(options) {
 
   function dropOverflow() {
     const dropped = queue.splice(0, queue.length - maxQueue).length;
-    report(new RecapiError('queue_overflow', `dropped ${dropped} oldest events`));
+    report(new RecapiError('queue_overflow', `dropped ${dropped} oldest events`), true);
   }
 
   function schedule() {
@@ -266,13 +274,13 @@ export function createClient(options) {
       report(new RecapiError('event_rejected', `${response.rejected.length} event(s) rejected`, {
         status: 202,
         details: response.rejected.map((r) => ({ ...r, event: events[r.index] }))
-      }));
+      }), true);
     }
   }
 
   /** Puts a failed batch back at the head of the queue if it may succeed later. */
   function handleSendError(error, events) {
-    report(error);
+    report(error, !error.retryable);
     if (error instanceof RecapiError && error.retryable) {
       queue.unshift(...events);
       if (queue.length > maxQueue) dropOverflow();
@@ -314,8 +322,9 @@ export function createClient(options) {
   }
 
   /**
-   * Sends all queued events. Never rejects: failures go to `onError`, and
-   * retryable batches stay queued for the next automatic flush.
+   * Sends all queued events. Never rejects: failures go to `onError` (without
+   * one, events lost for good to `console.warn`), and retryable batches stay
+   * queued for the next automatic flush.
    *
    * @returns {Promise<void>}
    */

package/src/transport.js

@@ -78,11 +78,12 @@ export function createTransport({ baseUrl, apiKey, fetch, timeoutMs: defaultTime
 
   /** @param {RequestOptions} options */
   async function request({ method, path, query, body, auth = 'header', keepalive = false, cache, timeoutMs }) {
+    // append, not set: React Native below 0.80 throws on set, and these names are unique.
     const params = new URLSearchParams();
     for (const [name, value] of Object.entries(query ?? {})) {
-      if (value !== undefined) params.set(name, String(value));
+      if (value !== undefined) params.append(name, String(value));
     }
-    if (auth === 'query') params.set('key', apiKey);
+    if (auth === 'query') params.append('key', apiKey);
     const qs = params.toString();
     const url = `${root}${path}${qs ? `?${qs}` : ''}`;