@recapi/client 0.0.0-stage → 0.2.0

package/src/history.js

@@ -0,0 +1,500 @@
+/**
+ * Decayed user history, implemented exactly as docs/history-spec.md so the
+ * SDK, the Go server and the Python trainer produce the same numbers.
+ *
+ * All functions are pure: they never mutate their inputs and return a new
+ * state, which keeps the client free to reload/replace state from storage.
+ *
+ * @module history
+ */
+
+/**
+ * @typedef {object} HistoryConfig
+ * @property {number} halfLifeSeconds Time for a score to halve.
+ * @property {number} topK Max items kept in the weighted history.
+ * @property {number} recentSize Max items kept in the recent list.
+ */
+
+/**
+ * @typedef {object} TopEntry
+ * @property {number} s Score valid at time `t`.
+ * @property {number} t Unix ms of the last in-order interaction.
+ */
+
+/**
+ * @typedef {object} RecentEntry
+ * @property {string} item
+ * @property {number} t Unix ms of the interaction that placed the item here.
+ *   Not part of the wire format; kept so two recent lists can be merged.
+ */
+
+/**
+ * @typedef {object} HistoryState
+ * @property {Map<string, TopEntry>} top A Map (not an object) so item ids
+ *   such as `__proto__` cannot collide with prototype properties.
+ * @property {RecentEntry[]} recent Oldest to newest.
+ * @property {Map<string, number>} rejected Items the user rejected, with the
+ *   unix ms of the rejection. Never recommended until a newer positive event.
+ * @property {number|null} lastT Unix ms of the newest event applied to the
+ *   recent list; `null` when unknown (empty or hydrated from a snapshot).
+ */
+
+/**
+ * @typedef {[item: string, weight: number, ageSeconds: number]} WireEntry
+ */
+
+/**
+ * @typedef {object} ServerSnapshot
+ * @property {Array<[string, number]>} top
+ * @property {string[]} recent
+ * @property {string[]} [rejected] Absent from servers older than rejections.
+ * @property {number} as_of Unix ms at which the `top` weights are valid.
+ */
+
+/** Spec defaults; the server uses the same values unless configured otherwise. */
+export const DEFAULT_CONFIG = Object.freeze({
+  halfLifeSeconds: 604800,
+  topK: 50,
+  recentSize: 20
+});
+
+/**
+ * Most rejection marks kept (the newest), so a user who rejects a lot cannot
+ * grow the stored history for ever. Not a setting: the spec fixes it.
+ */
+export const REJECTED_SIZE = 200;
+
+/**
+ * Fills missing fields with spec defaults so callers can override a single
+ * parameter (e.g. a shorter half-life for news sites).
+ *
+ * @param {Partial<HistoryConfig>} [partial]
+ * @returns {HistoryConfig}
+ */
+export function resolveConfig(partial = {}) {
+  const config = { ...DEFAULT_CONFIG, ...partial };
+  for (const key of Object.keys(DEFAULT_CONFIG)) {
+    if (!(Number.isFinite(config[key]) && config[key] > 0)) {
+      throw new TypeError(`historyConfig.${key} must be a positive number`);
+    }
+  }
+  return config;
+}
+
+/**
+ * @returns {HistoryState}
+ */
+export function emptyHistory() {
+  return { top: new Map(), recent: [], rejected: new Map(), lastT: null };
+}
+
+/**
+ * True when there is nothing to send, which is when the server falls back to
+ * its own stored history. Rejections alone don't count: the server still
+ * has the user's positive events, and it excludes both sets.
+ *
+ * @param {HistoryState} state
+ * @returns {boolean}
+ */
+export function isEmpty(state) {
+  return state.top.size === 0 && state.recent.length === 0;
+}
+
+function decay(config, dtMs) {
+  return Math.exp((-Math.LN2 / config.halfLifeSeconds) * (dtMs / 1000));
+}
+
+/**
+ * Weight of an entry decayed to time `T`.
+ *
+ * @param {TopEntry} entry
+ * @param {number} T Unix ms.
+ * @param {HistoryConfig} config
+ * @returns {number}
+ */
+export function weightAt(entry, T, config) {
+  return entry.s * decay(config, T - entry.t);
+}
+
+/**
+ * Entries sorted by weight at `T` descending, ties by item id ascending (code
+ * unit order, which matches Go and Python byte-wise comparison for ASCII ids).
+ *
+ * @param {HistoryState} state
+ * @param {number} T Unix ms.
+ * @param {HistoryConfig} config
+ * @returns {Array<{ item: string, weight: number, t: number }>}
+ */
+export function sortedEntries(state, T, config) {
+  return rank(state.top, T, config);
+}
+
+/**
+ * @param {Map<string, TopEntry>} top
+ * @param {number} T
+ * @param {HistoryConfig} config
+ */
+function rank(top, T, config) {
+  const entries = [];
+  for (const [item, entry] of top) {
+    entries.push({ item, weight: weightAt(entry, T, config), t: entry.t });
+  }
+  return entries.sort((a, b) => b.weight - a.weight || compareIds(a.item, b.item));
+}
+
+function compareIds(a, b) {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+}
+
+/**
+ * @param {Map<string, TopEntry>} top
+ * @param {number} T
+ * @param {HistoryConfig} config
+ */
+function prune(top, T, config) {
+  if (top.size <= config.topK) return top;
+  const kept = rank(top, T, config).slice(0, config.topK);
+  return new Map(kept.map(({ item }) => [item, top.get(item)]));
+}
+
+/**
+ * Keeps the newest {@link REJECTED_SIZE} marks; the order is oldest mark
+ * first, ties by item id, as in the spec.
+ *
+ * @param {Map<string, number>} rejected
+ */
+function pruneRejected(rejected) {
+  if (rejected.size <= REJECTED_SIZE) return rejected;
+  return new Map(rejectedOrder(rejected).slice(-REJECTED_SIZE).map((item) => [item, rejected.get(item)]));
+}
+
+/** @param {Map<string, number>} rejected */
+function rejectedOrder(rejected) {
+  return [...rejected.keys()].sort((a, b) => rejected.get(a) - rejected.get(b) || compareIds(a, b));
+}
+
+/**
+ * A rejection drops the item's score and recent position and marks it,
+ * unless a newer positive event on it was already applied. Dropped, not
+ * lowered: a lowered score would decay back towards 0 and the item would
+ * return. It never moves the recent list's clock (`lastT`).
+ *
+ * @param {HistoryState} state
+ * @param {string} item
+ * @param {number} t
+ * @returns {HistoryState}
+ */
+function reject(state, item, t) {
+  const current = state.top.get(item);
+  if (current && current.t > t) return state;
+  const top = new Map(state.top);
+  top.delete(item);
+  const rejected = new Map(state.rejected);
+  rejected.set(item, Math.max(t, rejected.get(item) ?? t));
+  return {
+    top,
+    recent: state.recent.filter((entry) => entry.item !== item),
+    rejected: pruneRejected(rejected),
+    lastT: state.lastT
+  };
+}
+
+/**
+ * Applies one interaction. Level 0 (impression) returns the state unchanged,
+ * a negative level is a rejection. Events older than the newest one already
+ * applied ("out of order") still add their decayed weight but never touch the
+ * recent list, so the result does not depend on network reordering more than
+ * the spec allows.
+ *
+ * @param {HistoryState} state
+ * @param {{ item: string, level: number, t: number }} event `t` in unix ms.
+ * @param {HistoryConfig} config
+ * @returns {HistoryState}
+ */
+export function applyEvent(state, { item, level, t }, config) {
+  if (level === 0) return state;
+  if (level < 0) return reject(state, item, t);
+
+  let rejected = state.rejected;
+  if (rejected.has(item)) {
+    if (t < rejected.get(item)) return state;
+    rejected = new Map(rejected);
+    rejected.delete(item);
+  }
+
+  const top = new Map(state.top);
+  const current = top.get(item);
+  if (!current) {
+    top.set(item, { s: level, t });
+  } else if (t >= current.t) {
+    top.set(item, { s: current.s * decay(config, t - current.t) + level, t });
+  } else {
+    top.set(item, { s: current.s + level * decay(config, current.t - t), t: current.t });
+  }
+
+  const inOrder = state.lastT === null || t >= state.lastT;
+  let recent = state.recent;
+  if (inOrder) {
+    recent = state.recent.filter((entry) => entry.item !== item);
+    recent.push({ item, t });
+    recent = recent.slice(-config.recentSize);
+  }
+
+  return {
+    top: prune(top, t, config),
+    recent,
+    rejected,
+    lastT: inOrder ? t : state.lastT
+  };
+}
+
+/**
+ * Wire format of a recommendation request: weights decayed to `T` and
+ * rounded to 4 decimals, integer age in seconds (clamped at 0 so a skewed
+ * clock never yields negative ages). `rejected` (oldest mark first) is sent
+ * in the request's `exclude`.
+ *
+ * @param {HistoryState} state
+ * @param {number} T Unix ms of the request.
+ * @param {HistoryConfig} config
+ * @returns {{ history: WireEntry[], recent: string[], rejected: string[] }}
+ */
+export function toWire(state, T, config) {
+  const history = sortedEntries(state, T, config)
+    .slice(0, config.topK)
+    .map(({ item, weight, t }) => /** @type {WireEntry} */ ([
+      item,
+      Math.round(weight * 1e4) / 1e4,
+      Math.max(0, Math.floor((T - t) / 1000))
+    ]));
+  const recent = state.recent.slice(-config.recentSize).map((entry) => entry.item);
+  return { history, recent, rejected: rejectedOrder(state.rejected) };
+}
+
+/**
+ * Builds a state from the server's fallback snapshot. Each top entry becomes
+ * `{ s: weight, t: as_of }` as the spec requires, each rejected item a mark
+ * at `as_of`. `lastT` is left unknown
+ * rather than set to `as_of`: `as_of` is the server clock, and a device clock
+ * running behind it would otherwise treat every new local event as out of
+ * order and freeze the recent list.
+ *
+ * Invalid entries are skipped instead of rejecting the whole snapshot.
+ *
+ * @param {ServerSnapshot} snapshot
+ * @param {HistoryConfig} config
+ * @returns {HistoryState}
+ */
+export function fromSnapshot(snapshot, config) {
+  const asOf = snapshot?.as_of;
+  if (!Number.isFinite(asOf)) return emptyHistory();
+
+  const top = new Map();
+  for (const entry of Array.isArray(snapshot.top) ? snapshot.top : []) {
+    if (Array.isArray(entry) && isId(entry[0]) && isWeight(entry[1])) {
+      top.set(entry[0], { s: entry[1], t: asOf });
+    }
+  }
+  const seen = new Set();
+  const recent = [];
+  for (const item of Array.isArray(snapshot.recent) ? snapshot.recent : []) {
+    if (isId(item) && !seen.has(item)) {
+      seen.add(item);
+      recent.push({ item, t: asOf });
+    }
+  }
+  const rejected = new Map();
+  for (const item of Array.isArray(snapshot.rejected) ? snapshot.rejected : []) {
+    if (isId(item)) rejected.set(item, asOf);
+  }
+  return {
+    top: prune(top, asOf, config),
+    recent: recent.slice(-config.recentSize),
+    rejected: pruneRejected(rejected),
+    lastT: null
+  };
+}
+
+/**
+ * Merges two histories built from disjoint events (e.g. the anonymous device
+ * history and the account history fetched at login). Summing assumes the
+ * events are disjoint: merging a history with itself doubles every weight.
+ *
+ * Top: per item, the sum of both decayed scores. The sum is expressed at the
+ * later of the two `t`s, which keeps the true last-interaction time (and so
+ * the wire `age_seconds`) instead of resetting it to the merge time; the
+ * weight at any later time equals the sum of the two weights.
+ *
+ * Recent: union of both lists ordered by interaction time (oldest first); an
+ * item in both lists takes its most recent time. Equal times keep `a`'s order
+ * before `b`'s. The last `recentSize` items are kept.
+ *
+ * Rejected: union of both marks (the newer time when in both). As in
+ * {@link applyEvent}, a mark older than the item's merged top entry is
+ * dropped; otherwise the item leaves the top and the recent list.
+ *
+ * @param {HistoryState} a
+ * @param {HistoryState} b
+ * @param {number} T Unix ms of the merge, used for pruning.
+ * @param {HistoryConfig} config
+ * @returns {HistoryState}
+ */
+export function merge(a, b, T, config) {
+  const top = new Map(a.top);
+  for (const [item, entry] of b.top) {
+    const other = top.get(item);
+    if (!other) {
+      top.set(item, entry);
+      continue;
+    }
+    const t = Math.max(entry.t, other.t);
+    top.set(item, { s: weightAt(entry, t, config) + weightAt(other, t, config), t });
+  }
+
+  const rejected = new Map(a.rejected);
+  for (const [item, t] of b.rejected) rejected.set(item, Math.max(t, rejected.get(item) ?? t));
+  for (const [item, t] of rejected) {
+    const entry = top.get(item);
+    if (entry && entry.t > t) rejected.delete(item);
+    else top.delete(item);
+  }
+
+  const byItem = new Map();
+  [...a.recent, ...b.recent].forEach((entry, order) => {
+    const existing = byItem.get(entry.item);
+    if (!existing || entry.t > existing.t) byItem.set(entry.item, { ...entry, order });
+  });
+  // Rejected items go before the trim, so they don't cost the list its places.
+  const recent = [...byItem.values()]
+    .filter(({ item }) => !rejected.has(item))
+    .sort((x, y) => x.t - y.t || x.order - y.order)
+    .slice(-config.recentSize)
+    .map(({ item, t }) => ({ item, t }));
+
+  const times = [a.lastT, b.lastT].filter((t) => t !== null);
+  return {
+    top: prune(top, T, config),
+    recent,
+    rejected: pruneRejected(rejected),
+    lastT: times.length ? Math.max(...times) : null
+  };
+}
+
+/**
+ * Merges a server snapshot ({@link fromSnapshot}) into the local history,
+ * as {@link merge} does, except for the items this device rejected. The
+ * snapshot dates its scores `as_of`, which only says their events came
+ * before it; a local rejection is usually one the server hasn't stored yet
+ * (still queued, or tracked before login). Compared with `as_of`, it would
+ * lose to the very events the user then said no to, so it wins instead.
+ *
+ * @param {HistoryState} local
+ * @param {HistoryState} snapshot
+ * @param {number} T Unix ms of the merge, used for pruning.
+ * @param {HistoryConfig} config
+ * @returns {HistoryState}
+ */
+export function mergeSnapshot(local, snapshot, T, config) {
+  const top = new Map([...snapshot.top].filter(([item]) => !local.rejected.has(item)));
+  return merge(local, { ...snapshot, top }, T, config);
+}
+
+/**
+ * Compact JSON-safe form for storage. Kept separate from the wire format
+ * because storage needs raw `{s, t}` (not rounded weights) to stay exact.
+ *
+ * @param {HistoryState} state
+ * @returns {{ top: Array<[string, number, number]>, recent: Array<[string, number]>,
+ *   rejected: Array<[string, number]>, lastT: number|null }}
+ */
+export function encodeState(state) {
+  return {
+    top: [...state.top].map(([item, { s, t }]) => [item, s, t]),
+    recent: state.recent.map(({ item, t }) => [item, t]),
+    rejected: [...state.rejected],
+    lastT: state.lastT
+  };
+}
+
+/**
+ * Inverse of {@link encodeState}. Returns `null` on any malformed field so
+ * the caller discards corrupt storage instead of sending garbage. A state
+ * stored before rejections existed has no `rejected` and decodes as none.
+ *
+ * An entry whose id the API refuses is dropped and the rest kept: earlier
+ * SDKs counted characters, not bytes, and stored such ids, which made every
+ * recommendation request fail until they aged out. Discarding the whole
+ * state would also lose the device's anonymous id.
+ *
+ * @param {any} raw Parsed JSON of unknown shape.
+ * @returns {HistoryState|null}
+ */
+export function decodeState(raw) {
+  if (!raw || !Array.isArray(raw.top) || !Array.isArray(raw.recent)) return null;
+  if (raw.lastT !== null && !Number.isFinite(raw.lastT)) return null;
+
+  const top = new Map();
+  for (const entry of raw.top) {
+    if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !isWeight(entry[1]) || !Number.isFinite(entry[2])) {
+      return null;
+    }
+    if (isId(entry[0])) top.set(entry[0], { s: entry[1], t: entry[2] });
+  }
+  const recent = [];
+  for (const entry of raw.recent) {
+    if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !Number.isFinite(entry[1])) return null;
+    if (isId(entry[0])) recent.push({ item: entry[0], t: entry[1] });
+  }
+  if (raw.rejected !== undefined && !Array.isArray(raw.rejected)) return null;
+  const rejected = new Map();
+  for (const entry of raw.rejected ?? []) {
+    if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !Number.isFinite(entry[1])) return null;
+    if (isId(entry[0])) rejected.set(entry[0], entry[1]);
+  }
+  return { top, recent, rejected: pruneRejected(rejected), lastT: raw.lastT };
+}
+
+/** The API's limit on item and user ids, in bytes of UTF-8. */
+const MAX_ID_BYTES = 256;
+
+// Go's unicode.IsControl, which the API applies to every id: C0, DEL and C1.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/**
+ * Ids the API accepts (item and user ids): 1–256 bytes of UTF-8 without
+ * control characters. Counting characters instead let a 200-character
+ * Cyrillic or CJK id into the history, and the API refused every request
+ * that carried it.
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isId(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_ID_BYTES || CONTROL.test(value)) {
+    return false;
+  }
+  // A UTF-16 code unit is at most 3 bytes of UTF-8 (a surrogate pair, two
+  // units, is 4), so ids of up to 64 units fit without counting.
+  return value.length <= 64 || utf8Length(value) <= MAX_ID_BYTES;
+}
+
+/**
+ * A lone surrogate counts 3 bytes: JSON sends it escaped, and the API
+ * decodes it as U+FFFD.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function utf8Length(text) {
+  let bytes = 0;
+  for (const char of text) {
+    const code = /** @type {number} */ (char.codePointAt(0));
+    bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+  }
+  return bytes;
+}
+
+function isWeight(value) {
+  return Number.isFinite(value) && value >= 0;
+}

package/src/index.js

@@ -0,0 +1,20 @@
+/**
+ * Public entry point of `@recapi/client`.
+ *
+ * @module @recapi/client
+ */
+
+export { createClient } from './client.js';
+export { RecapiError } from './transport.js';
+export { memoryStorage, localStorageAdapter } from './storage.js';
+export {
+  DEFAULT_CONFIG,
+  resolveConfig,
+  emptyHistory,
+  applyEvent,
+  weightAt,
+  sortedEntries,
+  toWire,
+  fromSnapshot,
+  merge
+} from './history.js';

package/src/storage.js

@@ -0,0 +1,156 @@
+/**
+ * Storage adapters and the versioned, corruption-tolerant store the client
+ * persists its state in.
+ *
+ * Adapters are synchronous key/value stores (the `localStorage` shape) so the
+ * history is available immediately on page load without awaiting anything.
+ * Async stores such as React Native's AsyncStorage can be used by wrapping
+ * them in an in-memory cache that is preloaded before `createClient()`.
+ *
+ * @module storage
+ */
+
+/**
+ * @typedef {object} StorageAdapter
+ * @property {(key: string) => string | null} getItem
+ * @property {(key: string, value: string) => void} setItem
+ * @property {(key: string) => void} removeItem
+ */
+
+/** Bumped when the stored shape changes; old keys are then simply ignored. */
+export const STORAGE_VERSION = 1;
+
+/**
+ * In-memory adapter: the default in Node and the fallback when
+ * `localStorage` is unavailable. State lives as long as the process/page.
+ *
+ * @returns {StorageAdapter}
+ */
+export function memoryStorage() {
+  const data = new Map();
+  return {
+    getItem: (key) => (data.has(key) ? data.get(key) : null),
+    setItem: (key, value) => {
+      data.set(key, String(value));
+    },
+    removeItem: (key) => {
+      data.delete(key);
+    }
+  };
+}
+
+/**
+ * Wraps `window.localStorage`, or returns `null` when it is unusable.
+ * Merely reading `window.localStorage` throws when cookies are blocked, and
+ * Safari private mode / full quotas throw on `setItem`; every access is
+ * therefore guarded so storage problems never reach the host page. Failed
+ * writes are reported through `onError` and otherwise ignored (the in-memory
+ * state keeps working for the current page).
+ *
+ * @param {(error: unknown) => void} [onError]
+ * @returns {StorageAdapter | null}
+ */
+export function localStorageAdapter(onError = () => {}) {
+  let ls;
+  try {
+    ls = globalThis.localStorage;
+    if (!ls) return null;
+    const probe = '__recapi_probe__';
+    ls.setItem(probe, probe);
+    ls.removeItem(probe);
+  } catch {
+    return null;
+  }
+  return {
+    getItem(key) {
+      try {
+        return ls.getItem(key);
+      } catch (error) {
+        onError(error);
+        return null;
+      }
+    },
+    setItem(key, value) {
+      try {
+        ls.setItem(key, value);
+      } catch (error) {
+        onError(error);
+      }
+    },
+    removeItem(key) {
+      try {
+        ls.removeItem(key);
+      } catch (error) {
+        onError(error);
+      }
+    }
+  };
+}
+
+/**
+ * `localStorage` when usable, otherwise memory.
+ *
+ * @param {(error: unknown) => void} [onError]
+ * @returns {StorageAdapter}
+ */
+export function defaultStorage(onError) {
+  return localStorageAdapter(onError) ?? memoryStorage();
+}
+
+/**
+ * Key under which the client state is stored. Namespaced per project so two
+ * recapi tenants embedded on the same origin never share a history.
+ *
+ * @param {string} namespace
+ * @returns {string}
+ */
+export function storageKey(namespace) {
+  return `recapi:v${STORAGE_VERSION}:${namespace}`;
+}
+
+/**
+ * JSON store over an adapter. Even custom adapters may throw, so every call
+ * is guarded. Data that fails to parse or validate is removed so it cannot
+ * break every subsequent page load.
+ *
+ * @template T
+ * @param {StorageAdapter} adapter
+ * @param {string} key
+ * @param {(raw: unknown) => T | null} validate Returns `null` for corrupt data.
+ * @param {(error: unknown) => void} onError
+ * @returns {{ load: () => T | null, save: (value: unknown) => boolean, remove: () => void }}
+ *   `save` returns whether the write succeeded.
+ */
+export function createStore(adapter, key, validate, onError) {
+  const guard = (fn, fallback) => {
+    try {
+      return fn();
+    } catch (error) {
+      onError(error);
+      return fallback;
+    }
+  };
+  return {
+    load() {
+      const text = guard(() => adapter.getItem(key), null);
+      if (text === null || text === undefined) return null;
+      let value = null;
+      try {
+        value = validate(JSON.parse(text));
+      } catch {
+        value = null;
+      }
+      if (value === null) guard(() => adapter.removeItem(key));
+      return value;
+    },
+    save(value) {
+      return guard(() => {
+        adapter.setItem(key, JSON.stringify(value));
+        return true;
+      }, false);
+    },
+    remove() {
+      guard(() => adapter.removeItem(key));
+    }
+  };
+}