@recapi/client 0.0.0-stage → 0.1.2

package/src/transport.js

@@ -0,0 +1,195 @@
+/**
+ * HTTP layer: fetch with timeout, JSON, error mapping and retry.
+ *
+ * Page-hide flushing uses `fetch(..., { keepalive: true })` rather than
+ * `navigator.sendBeacon`: a beacon cannot carry the `Authorization` header and
+ * the API only accepts `?key=` on `GET /v1/popular`. A keepalive fetch
+ * survives page unload like a beacon does, as long as in-flight keepalive
+ * bodies stay under the browser's 64 KiB budget.
+ *
+ * @module transport
+ */
+
+/** Keepalive requests above the browser's 64 KiB budget are rejected outright. */
+const KEEPALIVE_MAX_BYTES = 60000;
+
+const CODE_BY_STATUS = {
+  400: 'invalid_request',
+  401: 'unauthorized',
+  403: 'forbidden',
+  404: 'not_found',
+  413: 'too_large',
+  429: 'rate_limited'
+};
+
+/**
+ * Every failure surfaced by the SDK. `status` is 0 when no HTTP response was
+ * received (`network`, `timeout`) or the error is client-side.
+ */
+export class RecapiError extends Error {
+  /**
+   * @param {string} code API error code (`invalid_request`, `rate_limited`…)
+   *   or a client code (`network`, `timeout`, `invalid_response`,
+   *   `event_rejected`, `queue_overflow`).
+   * @param {string} message
+   * @param {{ status?: number, retryAfterMs?: number, details?: unknown, cause?: unknown }} [extra]
+   */
+  constructor(code, message, { status = 0, retryAfterMs, details, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'RecapiError';
+    this.code = code;
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+    this.details = details;
+  }
+
+  /**
+   * Whether trying again later can succeed. `quota_exceeded` is a 429 too,
+   * but retrying it only burns requests until the quota resets.
+   *
+   * @returns {boolean}
+   */
+  get retryable() {
+    if (this.code === 'network' || this.code === 'timeout') return true;
+    if (this.status === 429) return this.code !== 'quota_exceeded';
+    return this.status >= 500;
+  }
+}
+
+/**
+ * @typedef {object} RequestOptions
+ * @property {'GET' | 'POST'} method
+ * @property {string} path
+ * @property {Record<string, string | number | undefined>} [query]
+ * @property {unknown} [body]
+ * @property {'header' | 'query'} [auth] `query` sends `?key=` so GET
+ *   responses are CDN-cacheable and need no CORS preflight.
+ * @property {boolean} [keepalive] Let the request outlive the page.
+ * @property {number} [timeoutMs]
+ */
+
+/**
+ * @param {{ baseUrl: string, apiKey: string, fetch: typeof fetch, timeoutMs: number }} options
+ * @returns {{ request: (options: RequestOptions) => Promise<any> }}
+ */
+export function createTransport({ baseUrl, apiKey, fetch, timeoutMs: defaultTimeoutMs }) {
+  const root = baseUrl.replace(/\/+$/, '');
+
+  /** @param {RequestOptions} options */
+  async function request({ method, path, query, body, auth = 'header', keepalive = false, timeoutMs }) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query ?? {})) {
+      if (value !== undefined) params.set(name, String(value));
+    }
+    if (auth === 'query') params.set('key', apiKey);
+    const qs = params.toString();
+    const url = `${root}${path}${qs ? `?${qs}` : ''}`;
+
+    const headers = { Accept: 'application/json' };
+    if (auth === 'header') headers.Authorization = `Bearer ${apiKey}`;
+    const init = { method, headers };
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(body);
+      if (keepalive && byteLength(init.body) <= KEEPALIVE_MAX_BYTES) init.keepalive = true;
+    }
+
+    const controller = typeof AbortController === 'function' ? new AbortController() : null;
+    if (controller) init.signal = controller.signal;
+    const ms = timeoutMs ?? defaultTimeoutMs;
+    const timer = controller ? setTimeout(() => controller.abort(), ms) : null;
+
+    try {
+      let response;
+      try {
+        response = await fetch(url, init);
+      } catch (error) {
+        throw transportError(error, controller, ms);
+      }
+      let text;
+      try {
+        text = await response.text();
+      } catch (error) {
+        throw transportError(error, controller, ms);
+      }
+      const json = parseJson(text);
+      if (!response.ok) throw httpError(response, json);
+      return json;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  return { request };
+}
+
+function byteLength(text) {
+  return typeof TextEncoder === 'function' ? new TextEncoder().encode(text).length : text.length * 3;
+}
+
+function transportError(error, controller, ms) {
+  if (controller?.signal.aborted) {
+    return new RecapiError('timeout', `request timed out after ${ms} ms`, { cause: error });
+  }
+  return new RecapiError('network', error?.message || 'network error', { cause: error });
+}
+
+function parseJson(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function httpError(response, json) {
+  const status = response.status;
+  const code = json?.error?.code || CODE_BY_STATUS[status] || (status >= 500 ? 'internal' : 'http_error');
+  const message = json?.error?.message || `HTTP ${status}`;
+  return new RecapiError(code, message, { status, retryAfterMs: retryAfter(response) });
+}
+
+function retryAfter(response) {
+  const header = response.headers?.get?.('retry-after');
+  const seconds = header ? Number(header) : NaN;
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+}
+
+/**
+ * Retries `fn` on retryable {@link RecapiError}s with exponential backoff
+ * and jitter (honouring `Retry-After`, capped at `maxDelayMs`). Only used for
+ * events: a recommendation that arrives seconds late is useless, so
+ * `recommend()` fails fast and falls back to popular items instead.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {{ retries?: number, baseDelayMs?: number, maxDelayMs?: number,
+ *   sleep?: (ms: number) => Promise<void>, random?: () => number }} [options]
+ * @returns {Promise<T>}
+ */
+export async function withRetry(fn, {
+  retries = 3,
+  baseDelayMs = 500,
+  maxDelayMs = 8000,
+  sleep = defaultSleep,
+  random = Math.random
+} = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt >= retries || !(error instanceof RecapiError) || !error.retryable) throw error;
+      const backoff = baseDelayMs * 2 ** attempt * (0.5 + random() / 2);
+      await sleep(Math.min(maxDelayMs, error.retryAfterMs ?? backoff));
+    }
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}