@recapi/client 0.0.0-stage → 0.1.2

package/index.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Type declarations for `@recapi/client`. Hand-written; keep in sync with
+ * `src/`.
+ */
+
+/** Synchronous key/value store with the `localStorage` shape. */
+export interface StorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/** History parameters from docs/history-spec.md. */
+export interface HistoryConfig {
+  halfLifeSeconds: number;
+  topK: number;
+  recentSize: number;
+}
+
+export interface TopEntry {
+  /** Score valid at time `t`. */
+  s: number;
+  /** Unix ms of the last in-order interaction. */
+  t: number;
+}
+
+export interface RecentEntry {
+  item: string;
+  t: number;
+}
+
+export interface HistoryState {
+  top: Map<string, TopEntry>;
+  /** Oldest to newest. */
+  recent: RecentEntry[];
+  /** Rejected items and the unix ms of each rejection. */
+  rejected: Map<string, number>;
+  /** Newest event applied to the recent list, or `null` when unknown. */
+  lastT: number | null;
+}
+
+/** `[item_id, weight rounded to 4 decimals, age in seconds]`. */
+export type WireEntry = [item: string, weight: number, ageSeconds: number];
+
+export interface WireHistory {
+  history: WireEntry[];
+  recent: string[];
+  /** Rejected items, oldest first; `recommend()` sends them in `exclude`. */
+  rejected: string[];
+}
+
+/** Server-side history snapshot (`history` field of a recommendation response). */
+export interface ServerSnapshot {
+  top: Array<[item: string, weight: number]>;
+  recent: string[];
+  /** Absent from servers that predate rejections. */
+  rejected?: string[];
+  as_of: number;
+}
+
+export interface ClientOptions {
+  /** Public key (`rk_pub_…`) in browsers. */
+  apiKey: string;
+  /** Your recapi API origin, e.g. `https://api.example.com`. */
+  baseUrl: string;
+  /** Defaults to localStorage when usable, otherwise in-memory. */
+  storage?: StorageAdapter;
+  /** Storage namespace; defaults to the first 16 characters of the API key. */
+  project?: string;
+  /** Default placement for `recommend()`. */
+  placement?: string;
+  /** Default 2000. */
+  flushIntervalMs?: number;
+  /** Default 100, at most 1000. */
+  maxBatch?: number;
+  /** Per-request timeout, default 5000; `recommend()` waits at most 1500. */
+  timeoutMs?: number;
+  historyConfig?: Partial<HistoryConfig>;
+  /** Initial storage consent, default `true`. */
+  consent?: boolean;
+  /** Start without consent when Do Not Track / Global Privacy Control is on. */
+  respectDoNotTrack?: boolean;
+  /** Receives errors from background work (flushes, storage) and those `recommend()` fell back from. */
+  onError?: (error: unknown) => void;
+  /** Clock in unix ms. */
+  now?: () => number;
+  fetch?: typeof fetch;
+  /** Backoff sleep, for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface RecommendParams {
+  count?: number;
+  tagsAny?: string[];
+  tagsAll?: string[];
+  exclude?: string[];
+  contextItemId?: string;
+  placement?: string;
+  discovery?: number;
+}
+
+export interface RecommendedItem {
+  itemId: string;
+  score: number;
+  slot: 'exploit' | 'explore' | 'backfill' | string;
+}
+
+export interface RecommendResult {
+  /** `null` when `fallback` is true: there is nothing to attribute. */
+  recommendationId: string | null;
+  /**
+   * True when recapi was unreachable, slow (1.5 s) or failing (5xx) and
+   * `items` are popular items (slot `backfill`) instead. When recapi is down
+   * altogether (the popular request failed too), `items` is empty: hide the
+   * slot.
+   */
+  fallback: boolean;
+  items: RecommendedItem[];
+}
+
+export interface PopularParams {
+  tagsAny?: string[];
+  tagsAll?: string[];
+  count?: number;
+}
+
+export interface PopularResult {
+  items: Array<{ itemId: string; score: number }>;
+}
+
+/**
+ * Shop names for the recommended scale: view 3, cart 5, purchase 10. Any catalog can pass the integers instead (3 opened,
+ * 5 strong interest, 10 the action that matters most). `reject` (-10) is an explicit "not interested", never a skip.
+ */
+export type LevelName = 'view' | 'cart' | 'purchase' | 'reject';
+
+export interface RecapiClient {
+  track(itemId: string, level: number | LevelName, options?: { recommendationId?: string | null }): void;
+  /** Falls back to popular items on a network error, a timeout or a 5xx (an empty list if those fail too); rejects on 4xx and 429. */
+  recommend(params?: RecommendParams): Promise<RecommendResult>;
+  popular(params?: PopularParams): Promise<PopularResult>;
+  identify(userId: string, options?: { history?: ServerSnapshot }): void;
+  reset(): void;
+  setConsent(value: boolean): void;
+  /** Never rejects; failures go to `onError`. */
+  flush(): Promise<void>;
+  getHistory(): WireHistory;
+  destroy(): Promise<void>;
+}
+
+export function createClient(options: ClientOptions): RecapiClient;
+
+export class RecapiError extends Error {
+  constructor(
+    code: string,
+    message: string,
+    extra?: { status?: number; retryAfterMs?: number; details?: unknown; cause?: unknown }
+  );
+  readonly name: 'RecapiError';
+  /** API code (`invalid_request`, `rate_limited`, …) or client code (`network`, `timeout`, `invalid_response`, `event_rejected`, `queue_overflow`). */
+  code: string;
+  /** HTTP status, 0 when no response was received. */
+  status: number;
+  retryAfterMs?: number;
+  details?: unknown;
+  readonly retryable: boolean;
+}
+
+export function memoryStorage(): StorageAdapter;
+export function localStorageAdapter(onError?: (error: unknown) => void): StorageAdapter | null;
+
+export const DEFAULT_CONFIG: Readonly<HistoryConfig>;
+export function resolveConfig(partial?: Partial<HistoryConfig>): HistoryConfig;
+export function emptyHistory(): HistoryState;
+export function applyEvent(
+  state: HistoryState,
+  event: { item: string; level: number; t: number },
+  config: HistoryConfig
+): HistoryState;
+export function weightAt(entry: TopEntry, T: number, config: HistoryConfig): number;
+export function sortedEntries(
+  state: HistoryState,
+  T: number,
+  config: HistoryConfig
+): Array<{ item: string; weight: number; t: number }>;
+export function toWire(state: HistoryState, T: number, config: HistoryConfig): WireHistory;
+export function fromSnapshot(snapshot: ServerSnapshot, config: HistoryConfig): HistoryState;
+export function merge(a: HistoryState, b: HistoryState, T: number, config: HistoryConfig): HistoryState;

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@recapi/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Browser and Node client for the recapi recommendation API: local decayed history, event batching, attribution.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "MIT"
+}