@brunyee-studio/onus-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,40 @@
+import {
+  MAX_ENVELOPE_BYTES,
+  REPLAY_ID_RE,
+  SDK_NAME,
+  SDK_VERSION,
+  buildEnvelope,
+  buildSentryAuthHeader,
+  captureCustomEvent,
+  captureEvent,
+  captureException,
+  captureMessage,
+  eventId,
+  flush,
+  getActiveReplayId,
+  init,
+  isEnabled,
+  parseDsn,
+  resetForTest,
+  setActiveReplayId
+} from "./chunk-SLWBPQ6C.js";
+export {
+  MAX_ENVELOPE_BYTES,
+  REPLAY_ID_RE,
+  SDK_NAME,
+  SDK_VERSION,
+  buildEnvelope,
+  buildSentryAuthHeader,
+  captureCustomEvent,
+  captureEvent,
+  captureException,
+  captureMessage,
+  eventId,
+  flush,
+  getActiveReplayId,
+  init,
+  isEnabled,
+  parseDsn,
+  resetForTest,
+  setActiveReplayId
+};

package/dist/replay-D7ejwI0s.d.ts

@@ -0,0 +1,126 @@
+/**
+ * DSN parsing for @onus/sdk (ONUS-68).
+ *
+ * Mirrors `src/lib/ingest/dsn.ts` semantics (the server side of the same
+ * protocol): `{PROTOCOL}://{PUBLIC_KEY}@{HOST}/{NUMERIC_PROJECT_ID}` with no
+ * sub-path. The envelope endpoint derives as `{protocol}://{host}/api/{id}/envelope/`.
+ */
+interface ParsedDsn {
+    /** Public key — sent as `sentry_key` in the X-Sentry-Auth header. */
+    key: string;
+    host: string;
+    /** Numeric ingest project id embedded in the flat DSN. */
+    projectId: string;
+    /** POST target for envelope payloads. */
+    envelopeUrl: string;
+    /** Origin used for CORS/referer comparisons. */
+    origin: string;
+}
+/**
+ * Parse `{protocol}://{key}@{host}/{numericId}`. Returns null for anything
+ * malformed — a broken DSN disables the SDK (no network sends), matching
+ * stock Sentry behavior of failing safe.
+ */
+declare function parseDsn(raw: string | undefined | null): ParsedDsn | null;
+/** Build the `X-Sentry-Auth` header value the ingest routes parse. */
+declare function buildSentryAuthHeader(dsn: ParsedDsn, clientVersion: string): string;
+
+/**
+ * Sentry-compatible envelope building for @onus/sdk (ONUS-68).
+ *
+ * Wire contract (`src/app/api/[projectId]/envelope/route.ts`):
+ * - first line: JSON envelope header (event_id, sent_at, sdk)
+ * - then per item: a JSON item header line (`{"type":...}`), a blank line,
+ *   and the payload (JSON or raw bytes for gzipped replay recordings).
+ * - replay segments pair a `replay_event` item with a `replay_recording`
+ *   item exactly as `extractReplayFrom` expects; the replay id must match
+ *   the strict `[a-zA-Z0-9_-]{1,64}` regex the persist layer enforces.
+ * - error events carry `contexts.replay.replay_id` for error↔replay linking.
+ */
+/** 1 MiB wire cap enforced by the ingest routes. */
+declare const MAX_ENVELOPE_BYTES: number;
+/** Strict replay-id regex enforced by `src/lib/ingest/replay.ts`. */
+declare const REPLAY_ID_RE: RegExp;
+type EnvelopeItem = {
+    type: 'event';
+    payload: Record<string, unknown>;
+} | {
+    type: 'replay_event';
+    payload: Record<string, unknown>;
+} | {
+    type: 'replay_recording';
+    payload: string;
+    length: number;
+};
+/** Server-side requirement (ONUS-41): every event carries an `event_id`. */
+declare function eventId(): string;
+/**
+ * Serialize an envelope as text. Returns null when the payload would exceed
+ * the server's 1 MiB wire cap — callers drop the event instead of guaranteed
+ * rejection (mirrors the SDK-side guard in Sentry's transport).
+ */
+declare function buildEnvelope(header: {
+    event_id: string;
+    sent_at: string;
+    sdk: {
+        name: string;
+        version: string;
+    };
+}, items: EnvelopeItem[]): string | null;
+
+interface ReplayOptions {
+    dsn?: string;
+    environment?: string;
+    release?: string;
+    /**
+     * @onus/analytics session id (or getter) attached to each replay_event so
+     * the sessions surface can link playback (ONUS-155). A getter is evaluated
+     * per segment flush so rotated session ids stay fresh.
+     */
+    sessionId?: string | (() => string | null | undefined);
+    /** rrweb record options (eventsPerSecond caps, etc.); kept passthrough. */
+    recordOptions?: Record<string, unknown>;
+    /**
+     * How long buffered rrweb events wait before flushing as one segment
+     * envelope (ms, default 5000 — Sentry's segment cadence). Batching keeps a
+     * single interaction from producing one POST per DOM mutation.
+     */
+    segmentIntervalMs?: number;
+    /** Buffered events that force an immediate segment flush (default 100). */
+    maxEventsPerSegment?: number;
+    /** Test seam: recorder + fetch injection (defaults to lazy rrweb import). */
+    recorderFactory?: () => Promise<Recorder | null>;
+    fetchImpl?: typeof fetch;
+}
+/** Minimal structural subset of rrweb's record function used here. */
+interface Recorder {
+    stop: () => void;
+    /**
+     * Optional test hook: receives the wired record options (including `emit`)
+     * so an injected recorder can drive the buffering path end-to-end.
+     */
+    wire?: (opts: unknown) => void;
+}
+interface ReplayState {
+    replayId: string;
+    stop: (() => void) | null;
+    /** Buffered rrweb events awaiting the next segment flush. */
+    buffer: unknown[];
+    /** Pending interval flush (one envelope per flush, not per event). */
+    timer: ReturnType<typeof setTimeout> | null;
+}
+/**
+ * Start session replay. No-op (returns null) when replay is already running,
+ * the DSN is invalid, the recorder factory fails, or rrweb cannot be loaded.
+ */
+declare function startSessionReplay(options?: ReplayOptions): Promise<string | null>;
+/** Stop replay. No-op when not running. Flushes any buffered tail. */
+declare function stopSessionReplay(): void;
+/** Currently active replay id (null when off). */
+declare function activeReplayId(): string | null;
+/** Test seam. */
+declare function resetReplayForTest(): void;
+/** Build + send one segment envelope (replay_event + replay_recording pair). */
+declare function emitSegment(dsn: NonNullable<ReturnType<typeof parseDsn>>, options: ReplayOptions, state: ReplayState, event: unknown, segmentId: number, timestamp: string): Promise<boolean>;
+
+export { type EnvelopeItem as E, MAX_ENVELOPE_BYTES as M, type ParsedDsn as P, type Recorder as R, REPLAY_ID_RE as a, buildEnvelope as b, buildSentryAuthHeader as c, type ReplayOptions as d, eventId as e, activeReplayId as f, emitSegment as g, stopSessionReplay as h, parseDsn as p, resetReplayForTest as r, startSessionReplay as s };

package/dist/replay.d.ts

@@ -0,0 +1 @@
+export { a as REPLAY_ID_RE, R as Recorder, d as ReplayOptions, f as activeReplayId, g as emitSegment, p as parseDsn, r as resetReplayForTest, s as startSessionReplay, h as stopSessionReplay } from './replay-D7ejwI0s.js';

package/dist/replay.js

@@ -0,0 +1,174 @@
+import {
+  REPLAY_ID_RE,
+  SDK_NAME,
+  buildEnvelope,
+  eventId,
+  parseDsn,
+  sendEnvelope
+} from "./chunk-SLWBPQ6C.js";
+
+// src/replay.ts
+var active = null;
+async function startSessionReplay(options = {}) {
+  if (active) return active.replayId;
+  const dsn = parseDsn(options.dsn);
+  if (!dsn) return null;
+  const replayId = eventId().replace(/-/g, "");
+  const state = { replayId, stop: null, buffer: [], timer: null };
+  active = state;
+  let record = null;
+  if (options.recorderFactory) {
+    let recorder;
+    try {
+      recorder = await options.recorderFactory();
+    } catch {
+      active = null;
+      return null;
+    }
+    if (!recorder) {
+      active = null;
+      return null;
+    }
+    record = (_opts) => {
+      recorder.wire?.(_opts);
+      return () => recorder.stop();
+    };
+  } else {
+    try {
+      const mod = await import("rrweb");
+      const fn = mod.record;
+      if (typeof fn !== "function") {
+        active = null;
+        return null;
+      }
+      record = fn;
+    } catch {
+      active = null;
+      return null;
+    }
+  }
+  const segmentIntervalMs = options.segmentIntervalMs ?? 5e3;
+  const maxEventsPerSegment = options.maxEventsPerSegment ?? 100;
+  const narrowedDsn = dsn;
+  async function flushBuffer() {
+    if (state.timer !== null) {
+      clearTimeout(state.timer);
+      state.timer = null;
+    }
+    if (state.buffer.length === 0) return;
+    const events = state.buffer;
+    state.buffer = [];
+    await emitSegment(
+      narrowedDsn,
+      options,
+      state,
+      events,
+      ++segmentCounter,
+      (/* @__PURE__ */ new Date()).toISOString()
+    );
+  }
+  const stop = record({
+    emit: (event) => {
+      state.buffer.push(event);
+      if (state.buffer.length >= maxEventsPerSegment) {
+        void flushBuffer();
+        return;
+      }
+      if (state.timer === null) {
+        state.timer = setTimeout(() => {
+          state.timer = null;
+          void flushBuffer();
+        }, segmentIntervalMs);
+      }
+    },
+    ...options.recordOptions
+  });
+  state.stop = typeof stop === "function" ? () => {
+    stop();
+    void flushBuffer();
+  } : null;
+  if (typeof window !== "undefined") {
+    window.addEventListener(
+      "pagehide",
+      () => {
+        void flushBuffer();
+      },
+      { once: true }
+    );
+  }
+  return replayId;
+}
+var segmentCounter = 0;
+function stopSessionReplay() {
+  const stopping = active;
+  active = null;
+  if (!stopping) return;
+  stopping.stop?.();
+  if (stopping.timer !== null) {
+    clearTimeout(stopping.timer);
+    stopping.timer = null;
+  }
+  stopping.buffer.length = 0;
+}
+function activeReplayId() {
+  return active?.replayId ?? null;
+}
+function resetReplayForTest() {
+  active?.stop?.();
+  active = null;
+  segmentCounter = 0;
+}
+function resolveSessionId(options) {
+  const raw = typeof options.sessionId === "function" ? options.sessionId() : options.sessionId;
+  return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+async function emitSegment(dsn, options, state, event, segmentId, timestamp) {
+  const recordingText = `{"segment_id":${segmentId}}
+${JSON.stringify(event ?? [])}`;
+  const sessionId = resolveSessionId(options);
+  const items = [
+    {
+      type: "replay_event",
+      payload: {
+        segment_id: segmentId,
+        replay_id: state.replayId,
+        timestamp,
+        ...sessionId ? { session_id: sessionId } : {},
+        ...options.environment ? { environment: options.environment } : {},
+        ...options.release ? { release: options.release } : {}
+      }
+    },
+    {
+      type: "replay_recording",
+      payload: recordingText,
+      // Byte length (not UTF-16 code units) — the server validates the
+      // declared length against payload bytes.
+      length: new TextEncoder().encode(recordingText).length
+    }
+  ];
+  const serialized = buildEnvelope(
+    {
+      event_id: eventId(),
+      sent_at: timestamp,
+      sdk: { name: SDK_NAME, version: "0.1.0" }
+    },
+    items
+  );
+  if (!serialized) return false;
+  const result = await sendEnvelope({
+    url: dsn.envelopeUrl,
+    authHeader: `Sentry sentry_key=${dsn.key}, sentry_version=7, sentry_client=onus.javascript/0.1.0`,
+    body: serialized,
+    fetchImpl: options.fetchImpl
+  });
+  return result.ok;
+}
+export {
+  REPLAY_ID_RE,
+  activeReplayId,
+  emitSegment,
+  parseDsn,
+  resetReplayForTest,
+  startSessionReplay,
+  stopSessionReplay
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@brunyee-studio/onus-sdk",
+  "version": "0.1.0",
+  "description": "Official Onus browser SDK: errors, session replay, and custom events via the Sentry-compatible envelope protocol",
+  "license": "MIT",
+  "author": "Brunyee Studio",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./replay": {
+      "types": "./dist/replay.d.ts",
+      "import": "./dist/replay.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.1",
+    "jsdom": "^26.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^5.0.1"
+  },
+  "peerDependencies": {
+    "rrweb": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "rrweb": {
+      "optional": true
+    }
+  }
+}