@brunyee-studio/onus-sdk 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# @brunyee-studio/onus-sdk
+
+Official Onus browser SDK for **errors, session replay, and custom events** — speaks Onus' Sentry-compatible envelope protocol (`/api/{ingest_project_id}/envelope/`).
+
+For the PostHog-style product-analytics pipeline (pageviews, autocapture, identity, trends/funnels), use [`@brunyee-studio/onus-analytics`](../analytics) instead.
+
+## Install
+
+```bash
+pnpm add @brunyee-studio/onus-sdk
+```
+
+```js
+import { init, captureException } from '@brunyee-studio/onus-sdk';
+
+init({
+  dsn: 'https://<public-key>@<ingest-host>/<numeric-project-id>',
+  release: '1.0.0',
+  environment: 'production',
+  // Record every user's session automatically (see "Session replay"):
+  replays: { sampleRate: 1 },
+});
+
+try {
+  risky();
+} catch (e) {
+  captureException(e);
+}
+```
+
+The DSN is public by design (Sentry doctrine); abuse is handled server-side via rate limits and the optional per-key origin allowlist. A missing or malformed DSN disables all network sends — the SDK fails safe.
+
+## Session replay
+
+Two ways to record. **Auto-start (recommended)** — pass a `replays` block to
+`init()`; every session records by default and sampling is an opt-down:
+
+```js
+init({
+  dsn,
+  replays: {
+    sampleRate: 1, // fraction of sessions recorded (default 1 = all users)
+    // sessionId: () => analytics.get_session_id(), // link playback to analytics sessions
+    // recordOptions: { maskAllInputs: true },      // rrweb privacy passthrough
+  },
+});
+```
+
+Errors captured afterwards carry `contexts.replay.replay_id` automatically —
+no extra wiring. `enabled: false` (or omitting the block) opts out entirely.
+
+Manual control still works via the separate entrypoint:
+
+```js
+import { startSessionReplay, stopSessionReplay } from '@brunyee-studio/onus-sdk/replay';
+
+const replayId = await startSessionReplay({ dsn, environment: 'production' });
+// Errors captured afterwards carry contexts.replay.replay_id automatically.
+```
+
+`rrweb` is an **optional peer dependency** — the recorder bundle is lazy-loaded only when recording actually starts, so apps that disable replay never download it. Replay segments are emitted as paired `replay_event` + `replay_recording` envelope items (gzipped) exactly as the ingest routes and the private Storage bucket expect. When capturing all users, review privacy masking (`recordOptions`, e.g. `maskAllInputs`) before enabling in production; replays expire per the team's retention setting (90 days by default).
+
+## Transport semantics
+
+- POSTs envelopes with `X-Sentry-Auth` (`sentry_key` = your public key).
+- Gzips bodies via `CompressionStream` when available; the ingest route sniffs magic bytes and also accepts identity bodies.
+- Honors `429` + `retry-after` with capped backoff (per-key rate limits).
+- Envelopes over the server's 1 MiB wire cap are dropped client-side.
+- `navigator.sendBeacon` is available for unload-time delivery (`?sentry_key=` query fallback, since beacons cannot set headers).
+
+## Tree-shaking & debug flag
+
+- Import only what you use; the replay recorder is isolated in `@brunyee-studio/onus-sdk/replay`.
+- Debug logging is gated behind the compile-time flag `__ONUS_DEBUG__`. Strip it in production bundlers:
+
+```js
+// webpack
+new webpack.DefinePlugin({ __ONUS_DEBUG__: false });
+// esbuild / tsup
+define: {
+  __ONUS_DEBUG__: 'false';
+}
+```
+
+## Browser support
+
+| Browser    | Minimum |
+| ---------- | ------- |
+| Chrome     | 90      |
+| Edge       | 90      |
+| Firefox    | 90      |
+| Safari     | 15.4    |
+| iOS Safari | 15.4    |
+
+Requires `crypto.randomUUID` **or** `crypto.getRandomValues` (event ids), `fetch`, and optionally `CompressionStream` (gzip) / `navigator.sendBeacon` (unload delivery). Older browsers degrade gracefully: identity bodies instead of gzip, fetch instead of beacon.
+
+**Version policy:** we support the current major line with fixes.
+
+## Publishing
+
+`@brunyee-studio/onus-sdk` releases through the same semantic-release pipeline as `packages/cli`. Only `dist/` and `README.md` are published (`files` in `package.json`).

package/dist/chunk-SLWBPQ6C.js

@@ -0,0 +1,326 @@
+// src/dsn.ts
+function parseDsn(raw) {
+  if (!raw) return null;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  const key = url.username.split(":")[0] ?? "";
+  if (!key) return null;
+  const segments = url.pathname.split("/").filter((s) => s !== "");
+  if (segments.length !== 1) return null;
+  const projectId = segments[0] ?? "";
+  if (!/^\d+$/.test(projectId)) return null;
+  return {
+    key,
+    host: url.host,
+    projectId,
+    envelopeUrl: `${url.protocol}//${url.host}/api/${projectId}/envelope/`,
+    origin: url.origin
+  };
+}
+function buildSentryAuthHeader(dsn, clientVersion) {
+  return `Sentry sentry_key=${dsn.key}, sentry_version=7, sentry_client=onus.javascript/${clientVersion}`;
+}
+
+// src/envelope.ts
+var MAX_ENVELOPE_BYTES = 1024 * 1024;
+var REPLAY_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+function eventId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function itemHeader(type, length) {
+  const header = { type, length };
+  return JSON.stringify(header);
+}
+function buildEnvelope(header, items) {
+  const parts = [JSON.stringify(header)];
+  for (const item of items) {
+    parts.push(itemHeader(item.type, item.type === "replay_recording" ? item.length : void 0));
+    if (item.type === "replay_recording") {
+      parts.push(item.payload);
+    } else {
+      parts.push(JSON.stringify(item.payload));
+    }
+  }
+  const serialized = parts.join("\n");
+  if (new TextEncoder().encode(serialized).byteLength > MAX_ENVELOPE_BYTES) {
+    return null;
+  }
+  return serialized;
+}
+function withReplayContext(event, replayId) {
+  if (!replayId || !REPLAY_ID_RE.test(replayId)) return event;
+  const contexts = {
+    ...event["contexts"],
+    replay: { replay_id: replayId }
+  };
+  return { ...event, contexts };
+}
+
+// src/transport.ts
+async function gzipText(text) {
+  const CS = globalThis.CompressionStream;
+  if (!CS || typeof Response === "undefined") return null;
+  try {
+    const body = new Response(text).body;
+    if (!body) return null;
+    const buf = await new Response(body.pipeThrough(new CS("gzip"))).arrayBuffer();
+    return new Uint8Array(buf);
+  } catch {
+    return null;
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function sendEnvelope(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const maxRetries = opts.maxRetries ?? 1;
+  const backoffMs = opts.backoffMs ?? 500;
+  const sleep = opts.delayImpl ?? delay;
+  const gz = await gzipText(opts.body);
+  const headers = {
+    "Content-Type": "application/x-sentry-envelope",
+    "X-Sentry-Auth": opts.authHeader,
+    ...gz ? { "Content-Encoding": "gzip" } : {}
+  };
+  for (let attempt = 0; ; attempt++) {
+    let res;
+    try {
+      res = await fetchImpl(opts.url, {
+        method: "POST",
+        headers,
+        body: gz ?? opts.body,
+        // Analytics-style telemetry: never block page unload on the response.
+        keepalive: true
+      });
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : "network error" };
+    }
+    if (res.ok) return { ok: true, status: res.status };
+    if (res.status === 429 && attempt < maxRetries) {
+      const retryAfter = Number(res.headers.get("retry-after") ?? "");
+      const wait = Math.min(
+        Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : backoffMs * (attempt + 1),
+        1e4
+      );
+      await sleep(wait);
+      continue;
+    }
+    if (res.status === 429) {
+      const retryAfter = Number(res.headers.get("retry-after") ?? "");
+      return {
+        ok: false,
+        status: 429,
+        retryAfterSeconds: Number.isFinite(retryAfter) ? retryAfter : void 0,
+        error: "rate limited"
+      };
+    }
+    return { ok: false, status: res.status, error: `ingest responded ${res.status}` };
+  }
+}
+
+// src/client.ts
+var SDK_NAME = "onus.javascript";
+var SDK_VERSION = "0.1.0";
+var autoReplayStart = null;
+var state = null;
+var pending = [];
+var MAX_PENDING = 100;
+function debugLog(...args) {
+  if (false) {
+    console.debug("[onus]", ...args);
+  }
+}
+function dispatch(items, eventIdValue) {
+  if (!state?.dsn) return Promise.resolve(false);
+  const serialized = buildEnvelope(
+    {
+      event_id: eventIdValue,
+      sent_at: (/* @__PURE__ */ new Date()).toISOString(),
+      sdk: { name: SDK_NAME, version: SDK_VERSION }
+    },
+    items
+  );
+  if (!serialized) {
+    debugLog("envelope exceeded 1 MiB cap; dropped", eventIdValue);
+    return Promise.resolve(false);
+  }
+  const send = sendEnvelope({
+    url: state.dsn.envelopeUrl,
+    authHeader: state.authHeader,
+    body: serialized,
+    fetchImpl: state.options.fetchImpl
+  });
+  const tracked = send.then((r) => {
+    if (!r.ok) debugLog("send failed", r.status, r.error);
+    return r.ok;
+  });
+  pending.push(tracked);
+  if (pending.length > MAX_PENDING) pending.shift();
+  return tracked;
+}
+function init(options) {
+  const dsn = parseDsn(options.dsn);
+  if (!dsn) {
+    debugLog("no valid dsn; SDK is disabled (no network sends)");
+  }
+  state = {
+    dsn,
+    options,
+    authHeader: dsn ? buildSentryAuthHeader(dsn, SDK_VERSION) : "",
+    replayId: null
+  };
+  autoReplayStart = null;
+  if (options.replays && options.replays.enabled !== false && dsn) {
+    autoReplayStart = startAutoReplay(options.replays, options);
+  }
+}
+async function startAutoReplay(replays, options) {
+  try {
+    const rate = typeof replays.sampleRate === "number" && replays.sampleRate >= 0 && replays.sampleRate <= 1 ? replays.sampleRate : 1;
+    if (Math.random() >= rate) return;
+    const replay = await import("./replay.js");
+    const replayId = await replay.startSessionReplay({
+      dsn: options.dsn,
+      environment: replays.environment ?? options.environment,
+      release: replays.release ?? options.release,
+      sessionId: replays.sessionId,
+      segmentIntervalMs: replays.segmentIntervalMs,
+      maxEventsPerSegment: replays.maxEventsPerSegment,
+      recordOptions: replays.recordOptions,
+      recorderFactory: replays.recorderFactory,
+      fetchImpl: replays.fetchImpl ?? options.fetchImpl
+    });
+    if (replayId) setActiveReplayId(replayId);
+  } catch (e) {
+    debugLog("replay auto-start failed", e);
+  }
+}
+function isEnabled() {
+  return state?.dsn !== null && state?.dsn !== void 0;
+}
+function resetForTest() {
+  state = null;
+  pending.length = 0;
+  autoReplayStart = null;
+}
+function baseEvent(error) {
+  return {
+    platform: "javascript",
+    environment: state?.options.environment ?? "production",
+    ...state?.options.release ? { release: state.options.release } : {},
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...error
+  };
+}
+function captureException(exception, hint) {
+  const id = eventId();
+  const event = withReplayContext(baseEvent({ level: "error", ...hint }), state?.replayId ?? null);
+  event["event_id"] = id;
+  event["exception"] = exceptionPayload(exception);
+  void dispatch([{ type: "event", payload: event }], id);
+  return id;
+}
+function exceptionPayload(exception) {
+  if (exception instanceof Error) {
+    return {
+      values: [
+        {
+          type: exception.name,
+          value: exception.message,
+          stacktrace: exception.stack ? { frames: parseStackFrames(exception.stack) } : void 0
+        }
+      ]
+    };
+  }
+  return { values: [{ value: String(exception) }] };
+}
+function parseStackFrames(stack) {
+  const frames = [];
+  for (const line of stack.split("\n")) {
+    const m = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?\s*$/.exec(line);
+    if (!m) continue;
+    frames.push({
+      function: m[1] ?? void 0,
+      filename: m[2],
+      lineno: Number(m[3]),
+      colno: Number(m[4])
+    });
+  }
+  return frames.reverse();
+}
+function captureMessage(message, hint) {
+  const id = eventId();
+  const event = withReplayContext(
+    baseEvent({ message, level: "info", ...hint }),
+    state?.replayId ?? null
+  );
+  event["event_id"] = id;
+  void dispatch([{ type: "event", payload: event }], id);
+  return id;
+}
+function captureEvent(event) {
+  const id = eventId();
+  const payload = withReplayContext(baseEvent(event), state?.replayId ?? null);
+  payload["event_id"] = id;
+  void dispatch([{ type: "event", payload }], id);
+  return id;
+}
+function captureCustomEvent(name, props) {
+  const id = eventId();
+  const event = baseEvent({
+    message: name,
+    level: "info",
+    tags: { __onus_custom: name },
+    extra: props ?? {}
+  });
+  event["event_id"] = id;
+  void dispatch([{ type: "event", payload: event }], id);
+  return id;
+}
+function setActiveReplayId(replayId) {
+  if (state) state.replayId = replayId && /^[a-zA-Z0-9_-]{1,64}$/.test(replayId) ? replayId : null;
+}
+function getActiveReplayId() {
+  return state?.replayId ?? null;
+}
+async function flush() {
+  if (autoReplayStart) await autoReplayStart;
+  await Promise.allSettled(pending.splice(0, pending.length));
+  return isEnabled();
+}
+
+export {
+  parseDsn,
+  buildSentryAuthHeader,
+  MAX_ENVELOPE_BYTES,
+  REPLAY_ID_RE,
+  eventId,
+  buildEnvelope,
+  sendEnvelope,
+  SDK_NAME,
+  SDK_VERSION,
+  init,
+  isEnabled,
+  resetForTest,
+  captureException,
+  captureMessage,
+  captureEvent,
+  captureCustomEvent,
+  setActiveReplayId,
+  getActiveReplayId,
+  flush
+};