@goliapkg/sentori-react-native 1.1.0 → 1.3.0

package/src/capture.ts

@@ -1,5 +1,8 @@
 import {
   type CaptureMessageOptions,
+  hashIdentities,
+  type LinkBy,
+  logger,
   type MessageLevel,
   safeFn,
   sealTrail,
@@ -96,8 +99,61 @@ export const __resetScreenshotBudgetForTests = (): void => {
  *
  * Pass `null` to clear (e.g. on sign-out).
  */
-export const setUser = (user: User | null): void => {
-  _user = user;
+/**
+ * Public user identity API.
+ *
+ *   sentori.setUser({ id: 'usr_123', name: 'Lihao', linkBy: {
+ *     email: 'lihao@example.com',
+ *     googleSub: '108293…',
+ *   } })
+ *
+ * The `linkBy` map is for **cross-project lookup** (see v2.3 design,
+ * §5 in docs/design/sdk-v2.3-redesign.md). Each value gets hashed
+ * client-side via `crypto.subtle.digest('SHA-256', …)` BEFORE
+ * leaving the device. Raw email / phone / sub **never** reach
+ * Sentori; the server can't recover them.
+ *
+ * Hashing is async (WebCrypto is async). `setUser` itself returns
+ * void synchronously so host code stays one-line; the hash work
+ * runs in the background and is committed to scope when ready. If
+ * a `captureException` fires BEFORE the hash settles, the event
+ * carries `id` + `name` only (no linkHashes that cycle) — the next
+ * event picks them up. This is fine in practice because the host
+ * sets the user once near startup, well before any captures.
+ *
+ * If `crypto.subtle` is unavailable in the runtime, the hash
+ * promise rejects and `linkBy` is silently dropped (NEVER rule —
+ * SDK failure must not propagate to host code).
+ */
+type SetUserInput = (User & { linkBy?: LinkBy }) | null;
+
+export const setUser = (input: SetUserInput): void => {
+  if (input == null) {
+    // `null` (explicit clear) or `undefined` (callers occasionally
+    // pass through optional state). Both clear the scope user.
+    _user = null;
+    return;
+  }
+  // Stage 1: commit id + name + anonymous immediately so the next
+  // captured event picks them up even if hashing is still in flight.
+  const { linkBy: rawLinkBy, ...stable } = input;
+  _user = { ...stable };
+
+  // Stage 2: hash any linkBy values async; commit to scope when done.
+  if (rawLinkBy && Object.keys(rawLinkBy).length > 0) {
+    void hashIdentities(rawLinkBy)
+      .then((linkHashes) => {
+        // Re-merge to guard against setUser being called again
+        // between stage 1 and stage 2 — if the user changed, drop
+        // the now-stale hash.
+        if (_user && _user.id === stable.id) {
+          _user = { ..._user, linkHashes };
+        }
+      })
+      .catch((e) => {
+        logger.warn('identity', 'linkBy hash failed; identities dropped:', e);
+      });
+  }
 };
 
 export const getUser = (): User | null => _user;
@@ -178,17 +234,13 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
   // makes it visible in Metro that the snapshot at captureException
   // time really is empty (no breadcrumb events fired yet) vs. having
   // been silently dropped on the wire. Production builds gate out.
-  if (typeof __DEV__ !== 'undefined' && __DEV__) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      '[sentori] captureException',
+  logger.debug('capture', 'captureException',
       'eventId=', event.id,
       'breadcrumbs=', crumbs.length,
       'wantScreenshot=', config.screenshotsEnabled && extras?.screenshot !== false,
       'wantSessionTrail=', config.sessionTrailEnabled,
       'wantReplay=', isReplayRunning(),
     );
-  }
 
   // Phase 26 sub-B: a captured error promotes the current session to
   // `errored` so the next AppState=background ping reports unhealthy.
@@ -234,22 +286,16 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
       // indistinguishable from `replay: off` even though the ticks
       // were healthy upstream. Insight 2026-05-18 verify shape made
       // this gap painful to triage.
-      // eslint-disable-next-line no-console
-      console.warn(
-        '[sentori] replay drain empty (no frames buffered at captureException)',
+      logger.debug('capture', 'replay drain empty (no frames buffered at captureException)',
         'eventId=', event.id,
       );
     }
-    if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        '[sentori] enqueue',
+    logger.debug('capture', 'enqueue',
         'eventId=', event.id,
         'attachments=', event.attachments?.length ?? 0,
         'kinds=', (event.attachments ?? []).map((a) => a.kind).join(',') || '(none)',
         'breadcrumbsAtEnqueue=', __peekBreadcrumbCount(),
       );
-    }
     enqueue(event);
   };
   void pipeline();
@@ -278,28 +324,20 @@ async function captureAndAttachReplay(event: Event, ndjson: string): Promise<voi
       { source: 'js' },
     );
     if (!meta) {
-      if (typeof __DEV__ !== 'undefined' && __DEV__) {
-        // eslint-disable-next-line no-console
-        console.warn(
-          '[sentori] replay upload returned null',
+      logger.debug('capture', 'replay upload returned null',
           'eventId=', event.id,
           'ndjsonBytes=', ndjson.length,
         );
-      }
       return;
     }
     if (!event.attachments) event.attachments = [];
     event.attachments.push(meta);
   } catch (e) {
-    if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        '[sentori] replay attachment threw',
+    logger.debug('capture', 'replay attachment threw',
         'eventId=', event.id,
         'ndjsonBytes=', ndjson.length,
         e,
       );
-    }
   }
 }
 
@@ -444,31 +482,20 @@ async function captureAndAttachScreenshot(event: Event): Promise<void> {
   try {
     blob = await captureScreenshot();
   } catch (e) {
-    if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      // eslint-disable-next-line no-console
-      console.warn('[sentori] screenshot capture threw', e);
-    }
+    logger.debug('capture', 'screenshot capture threw', e);
   }
   if (!blob) {
-    if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        '[sentori] screenshot blob null — native module missing or capture returned null',
+    logger.debug('capture', 'screenshot blob null — native module missing or capture returned null',
         'eventId=', event.id,
       );
-    }
     addBreadcrumb({ type: 'custom', data: { reason: 'screenshot-capture-failed' } });
     return;
   }
-  if (typeof __DEV__ !== 'undefined' && __DEV__) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      '[sentori] screenshot blob ok, uploading',
+  logger.debug('capture', 'screenshot blob ok, uploading',
       'eventId=', event.id,
       'mediaType=', blob.mediaType,
       'base64Bytes=', blob.base64.length,
     );
-  }
   const attachment: AttachmentMeta | null = await uploadAttachment(
     event.id,
     'screenshot',
@@ -476,10 +503,7 @@ async function captureAndAttachScreenshot(event: Event): Promise<void> {
     { source: 'js' },
   );
   if (!attachment) {
-    if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      // eslint-disable-next-line no-console
-      console.warn('[sentori] screenshot upload returned null', 'eventId=', event.id);
-    }
+    logger.debug('capture', 'screenshot upload returned null', 'eventId=', event.id);
     addBreadcrumb({ type: 'custom', data: { reason: 'screenshot-upload-failed' } });
     return;
   }

package/src/compat/sentry.ts

@@ -0,0 +1,482 @@
+/**
+ * v2.3 W6.3 — Sentry-compatible API surface.
+ *
+ * Drop-in for code (or LLM-generated code) written against
+ * `@sentry/react-native`. Every Sentry call maps to exactly one
+ * Sentori-native call internally. Translation differences (e.g.
+ * `Sentry.setUser({ ip_address })` — Sentori never stores IP) fire
+ * a one-shot console hint at `info` level, deduplicated per
+ * (api, dropped_field).
+ *
+ * Why this exists: LLMs have seen a LOT of Sentry code; letting
+ * them write the same syntax against Sentori is one less thing
+ * Sentori asks the host to think about. Combined with the v2.3
+ * "free bonus" stance — host adds Sentori without unlearning
+ * anything.
+ *
+ * Usage:
+ *
+ *   import * as Sentry from '@goliapkg/sentori-react-native/compat'
+ *
+ *   Sentry.init({ dsn: 'https://<token>@<host>/<projectId>', ... })
+ *   Sentry.captureException(err)
+ *   Sentry.setUser({ id, email })   // email → linkBy.email (hashed)
+ *
+ * The compat layer holds NO state of its own — it's a thin shim
+ * over the same Sentori internals. Mixing `Sentry.*` and
+ * `sentori.*` calls in the same app works fine.
+ *
+ * See `docs/design/sdk-v2.3-redesign.md` §4 for the full
+ * translation table + design rationale.
+ */
+
+import { logger } from '@goliapkg/sentori-core'
+
+import { addBreadcrumb as nativeAddBreadcrumb } from '../breadcrumbs'
+import {
+  captureException as nativeCaptureException,
+  captureMessage as nativeCaptureMessage,
+  setTag as nativeSetTag,
+  setTags as nativeSetTags,
+  setUser as nativeSetUser,
+} from '../capture'
+import { type InitOptions, init as nativeInit } from '../init'
+
+// ── one-shot warn dedup ───────────────────────────────────────────────────
+
+const _warnedOnce = new Set<string>()
+function warnOnce(key: string, msg: string): void {
+  if (_warnedOnce.has(key)) return
+  _warnedOnce.add(key)
+  logger.info('compat', msg)
+}
+
+// ── DSN parsing ───────────────────────────────────────────────────────────
+
+type SentryInitOpts = {
+  dsn: string
+  environment?: string
+  release?: string
+  tracesSampleRate?: number
+  sampleRate?: number
+  attachStacktrace?: boolean
+  autoSessionTracking?: boolean
+  /** Sentry's `debug: true` ≈ Sentori's `logLevel: 'debug'`. */
+  debug?: boolean
+  /** Catch-all for fields Sentori either ignores or doesn't map yet. */
+  [other: string]: unknown
+}
+
+function parseDsn(dsn: string): { token: string; ingestUrl: string } {
+  // Sentry DSN shape: `https://<key>@<host>[:port][/<projectId>]`
+  // Sentori cares about `<key>` (must be `st_pk_…`) and `<host>`.
+  let url: URL
+  try {
+    url = new URL(dsn)
+  } catch {
+    throw new Error(`Sentory compat: dsn is not a valid URL: ${dsn}`)
+  }
+  const key = url.username
+  if (!key) {
+    throw new Error(`Sentory compat: dsn missing token in user-info component`)
+  }
+  if (!key.startsWith('st_pk_')) {
+    throw new Error(
+      `Sentory compat: dsn token must start with 'st_pk_' (got prefix '${key.slice(0, 8)}…'). ` +
+        `Sentori does not parse Sentry-issued tokens — generate a Sentori project token via the dashboard.`,
+    )
+  }
+  // strip user-info to reconstruct the ingest origin
+  const ingestUrl = `${url.protocol}//${url.host}`
+  return { token: key, ingestUrl }
+}
+
+// ── Sentry.init ───────────────────────────────────────────────────────────
+
+export function init(opts: SentryInitOpts): void {
+  const { token, ingestUrl } = parseDsn(opts.dsn)
+
+  const sentoriOpts: InitOptions = {
+    token,
+    release: opts.release ?? '',
+    ingestUrl,
+    ...(opts.environment ? { environment: opts.environment } : {}),
+    sample: {
+      ...(opts.tracesSampleRate !== undefined ? { traces: opts.tracesSampleRate } : {}),
+      ...(opts.sampleRate !== undefined ? { errors: opts.sampleRate } : {}),
+    },
+    ...(opts.debug ? { logLevel: 'debug' as const } : {}),
+  }
+
+  // Empty release is the most common Sentry-init mistake; warn but
+  // continue.
+  if (!sentoriOpts.release) {
+    warnOnce(
+      'init:no-release',
+      'Sentry.init() with no `release` — Sentori requires release for grouping + drop-down menus to make sense. Set `release: "myapp@1.2.3"` for production cuts.',
+    )
+    // Sentori's init throws when release is empty; provide a
+    // reasonable fallback so the rest of the code path works in dev.
+    sentoriOpts.release = `unspecified@${Date.now()}`
+  }
+
+  // Pass-through informational hints for ignored fields.
+  for (const ignored of [
+    'attachStacktrace',
+    'autoSessionTracking',
+    'integrations',
+    'beforeSend',
+    'beforeBreadcrumb',
+    'maxBreadcrumbs',
+  ]) {
+    if (ignored in opts) {
+      warnOnce(
+        `init:ignored:${ignored}`,
+        `Sentry.init({ ${ignored} }) ignored. ` +
+          `${getIgnoredHint(ignored)}`,
+      )
+    }
+  }
+
+  nativeInit(sentoriOpts)
+}
+
+function getIgnoredHint(field: string): string {
+  switch (field) {
+    case 'attachStacktrace':
+      return 'Sentori always sends stack traces — no toggle.'
+    case 'autoSessionTracking':
+      return "Sentori sessions are on by default; toggle via `init({ capture: { sessions: true|false } })`."
+    case 'integrations':
+      return 'Sentori uses `init({ capture: {...} })` toggles instead of Integration classes — see the docs.'
+    case 'beforeSend':
+    case 'beforeBreadcrumb':
+      return 'Sentori does not support an arbitrary beforeSend hook today. Server-side PII scrubbing is automatic.'
+    case 'maxBreadcrumbs':
+      return 'Sentori uses a fixed 100-slot ring buffer.'
+    default:
+      return ''
+  }
+}
+
+// ── Severity / level enum ─────────────────────────────────────────────────
+
+/** Sentry's severity values, surfaced as strings (Sentori only
+ *  uses 5 levels). `Log` and `Critical` collapse to `'info'` and
+ *  `'fatal'` respectively. */
+export const Severity = {
+  Fatal: 'fatal' as const,
+  Critical: 'fatal' as const,
+  Error: 'error' as const,
+  Warning: 'warning' as const,
+  Log: 'info' as const,
+  Info: 'info' as const,
+  Debug: 'debug' as const,
+}
+
+type SentryLevelString =
+  | 'critical'
+  | 'debug'
+  | 'error'
+  | 'fatal'
+  | 'info'
+  | 'log'
+  | 'warning'
+
+type SentoriLevel = 'debug' | 'error' | 'fatal' | 'info' | 'warning'
+
+function mapLevel(level: SentryLevelString | undefined): SentoriLevel | undefined {
+  if (!level) return undefined
+  switch (level) {
+    case 'critical':
+      warnOnce(
+        'severity:critical',
+        "Sentry.Severity.Critical → mapped to 'fatal' (Sentori's 5-level syslog-style scale).",
+      )
+      return 'fatal'
+    case 'log':
+      warnOnce(
+        'severity:log',
+        "Sentry.Severity.Log → mapped to 'info' (Sentori's 5-level scale has no separate Log).",
+      )
+      return 'info'
+    default:
+      return level as SentoriLevel
+  }
+}
+
+// ── captureException ──────────────────────────────────────────────────────
+
+type SentryCaptureContext = {
+  tags?: Record<string, string>
+  extra?: Record<string, unknown>
+  level?: SentryLevelString
+  fingerprint?: string[]
+  user?: SentrySetUserInput
+}
+
+export function captureException(
+  err: unknown,
+  hint?: { captureContext?: SentryCaptureContext } | SentryCaptureContext,
+): void {
+  // Sentry v8+ takes the context inline (Hint); earlier versions
+  // wrapped it in `{ captureContext: {...} }`. Accept both.
+  const ctx: SentryCaptureContext | undefined = (() => {
+    if (!hint) return undefined
+    if ('captureContext' in (hint as { captureContext?: unknown })) {
+      return (hint as { captureContext?: SentryCaptureContext }).captureContext
+    }
+    return hint as SentryCaptureContext
+  })()
+
+  if (ctx?.extra) {
+    warnOnce(
+      'captureException:extra',
+      'Sentry.captureException(err, { extra }) → `extra` mapped to `tags` (Sentori does not have a separate extra namespace).',
+    )
+  }
+  if (ctx?.user) {
+    // Apply the per-call user via setUser (Sentori takes the
+    // current scope user automatically).
+    setUser(ctx.user)
+  }
+
+  const mergedTags = {
+    ...(ctx?.tags ?? {}),
+    ...(ctx?.extra
+      ? Object.fromEntries(
+          Object.entries(ctx.extra).map(([k, v]) => [k, String(v)]),
+        )
+      : {}),
+  }
+
+  nativeCaptureException(err as Error, {
+    ...(Object.keys(mergedTags).length > 0 ? { tags: mergedTags } : {}),
+    ...(ctx?.fingerprint ? { fingerprint: ctx.fingerprint } : {}),
+  })
+}
+
+// ── captureMessage ────────────────────────────────────────────────────────
+
+export function captureMessage(
+  msg: string,
+  levelOrCtx?: SentryCaptureContext | SentryLevelString,
+): void {
+  let level: SentoriLevel | undefined
+  let tags: Record<string, string> | undefined
+  if (typeof levelOrCtx === 'string') {
+    level = mapLevel(levelOrCtx)
+  } else if (levelOrCtx) {
+    level = mapLevel(levelOrCtx.level)
+    tags = levelOrCtx.tags
+  }
+  nativeCaptureMessage(msg, {
+    ...(level ? { level } : {}),
+    ...(tags ? { tags } : {}),
+  })
+}
+
+// ── setUser ───────────────────────────────────────────────────────────────
+
+type SentrySetUserInput = {
+  id?: string
+  email?: string
+  username?: string
+  ip_address?: string
+  segment?: string
+  [other: string]: unknown
+} | null
+
+export function setUser(user: SentrySetUserInput): void {
+  if (user == null) {
+    nativeSetUser(null)
+    return
+  }
+  const { id, email, username, ip_address, segment, ...rest } = user
+
+  if (ip_address !== undefined) {
+    warnOnce(
+      'setUser:ip_address',
+      'Sentry.setUser({ ip_address }) → dropped. Sentori never stores IP (privacy by design).',
+    )
+  }
+  if (segment !== undefined) {
+    warnOnce(
+      'setUser:segment',
+      'Sentry.setUser({ segment }) → mapped to tag `user.segment`. Set via setTag for clarity.',
+    )
+    if (typeof segment === 'string') nativeSetTag('user.segment', segment)
+  }
+
+  const linkBy: Record<string, string> = {}
+  if (email) linkBy.email = email
+  if (username) linkBy.username = username
+
+  // Surface any other fields the host bolted on (Sentry historically
+  // accepted arbitrary keys) — they pass through as tags.
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== undefined && v !== null) nativeSetTag(`user.${k}`, String(v))
+  }
+
+  nativeSetUser({
+    ...(id ? { id } : {}),
+    ...(Object.keys(linkBy).length > 0 ? { linkBy } : {}),
+  })
+}
+
+// ── setTag / setTags ──────────────────────────────────────────────────────
+
+// Re-export Sentori-native semantics; identical signatures.
+export const setTag = nativeSetTag
+export const setTags = nativeSetTags
+
+// ── addBreadcrumb ─────────────────────────────────────────────────────────
+
+type SentryBreadcrumb = {
+  category?: string
+  message?: string
+  level?: SentryLevelString
+  type?: 'default' | 'error' | 'http' | 'info' | 'navigation' | 'query' | 'user' | string
+  data?: Record<string, unknown>
+  timestamp?: number
+}
+
+type SentoriBreadcrumbType = 'custom' | 'log' | 'nav' | 'net' | 'user'
+
+function mapCategoryToType(category: string | undefined): SentoriBreadcrumbType | undefined {
+  if (!category) return undefined
+  if (['auth', 'click', 'gesture', 'input', 'touch', 'ui'].includes(category)) return 'user'
+  if (['fetch', 'http', 'xhr'].includes(category)) return 'net'
+  if (['nav', 'navigation', 'route'].includes(category)) return 'nav'
+  if (['console', 'log', 'sentry'].includes(category)) return 'log'
+  return 'custom'
+}
+
+function mapSentryType(t: string | undefined): SentoriBreadcrumbType | undefined {
+  if (!t) return undefined
+  switch (t) {
+    case 'http':
+      return 'net'
+    case 'navigation':
+      return 'nav'
+    case 'user':
+    case 'log':
+    case 'custom':
+      return t
+    default:
+      return 'custom'
+  }
+}
+
+export function addBreadcrumb(crumb: SentryBreadcrumb): void {
+  if (!crumb.message) {
+    crumb.message = crumb.category ?? crumb.type ?? '(no message)'
+  }
+  if (crumb.category && !crumb.type) {
+    warnOnce(
+      'breadcrumb:category',
+      'Sentry.addBreadcrumb({ category }) → mapped to `type` via well-known table; the category string itself is preserved under `data.category`.',
+    )
+  }
+  // RN SDK shape: { type, data }. No top-level `message` —
+  // Sentry's message goes into data.message.
+  nativeAddBreadcrumb({
+    type: mapSentryType(crumb.type) ?? mapCategoryToType(crumb.category) ?? 'custom',
+    data: {
+      message: crumb.message,
+      ...(crumb.data ?? {}),
+      ...(crumb.category ? { category: crumb.category } : {}),
+      ...(crumb.level ? { level: mapLevel(crumb.level) } : {}),
+    },
+  })
+}
+
+// ── flush / close ─────────────────────────────────────────────────────────
+
+// Re-export Sentori native flush + close — same signatures.
+export { close, flush } from '../lifecycle'
+
+// ── startTransaction / startSpan / withScope ──────────────────────────────
+
+// Trace mapping is non-trivial (Sentry's transaction object exposes
+// startChild, etc.). v2.3 ships a minimum-viable Sentry trace
+// surface that supports startTransaction returning a Sentori Span
+// object with a partial Sentry-style API (.startChild, .finish).
+// Anything beyond that throws a clear error directing to the native
+// `sentori.startSpan` / `sentori.withScopedSpan`.
+
+import { startSpan } from '@goliapkg/sentori-core'
+
+type SentrySpanOpts = {
+  op?: string
+  name?: string
+  description?: string
+  tags?: Record<string, string>
+}
+
+export function startTransaction(opts: SentrySpanOpts): {
+  finish: (status?: 'cancelled' | 'error' | 'ok') => void
+  setStatus: (status: 'cancelled' | 'error' | 'ok') => void
+  setTag: (k: string, v: string) => void
+  startChild: (childOpts: SentrySpanOpts) => unknown
+} {
+  warnOnce(
+    'startTransaction',
+    'Sentry.startTransaction() → mapped to sentori.startSpan() with op as name. Native equivalent: sentori.startTrace(name) or sentori.startSpan({ name }).',
+  )
+  const name = opts.name ?? opts.op ?? 'transaction'
+  const span = startSpan(name, {
+    parent: null,
+    tags: opts.tags,
+  })
+  return {
+    finish: (status) => span.finish({ status: status === 'ok' ? 'ok' : 'error' }),
+    setStatus: (status) => { span.setTag('status', status) },
+    setTag: (k, v) => { span.setTag(k, v) },
+    startChild: (childOpts) => {
+      return startSpan(childOpts.name ?? childOpts.op ?? 'child', {
+        tags: childOpts.tags,
+      })
+    },
+  }
+}
+
+// ── withScope / configureScope (no-op scoping; same state as native) ─────
+
+type ScopeProxy = {
+  setTag: (k: string, v: string) => void
+  setTags: (rec: Record<string, string>) => void
+  setUser: (u: SentrySetUserInput) => void
+  setExtra: (k: string, v: unknown) => void
+  setLevel: (l: SentryLevelString) => void
+}
+
+function scopeProxy(): ScopeProxy {
+  return {
+    setTag: nativeSetTag,
+    setTags: nativeSetTags,
+    setUser,
+    setExtra: (k, v) => nativeSetTag(`extra.${k}`, String(v)),
+    setLevel: () => {
+      warnOnce(
+        'scope:setLevel',
+        'Sentry.withScope(s => s.setLevel(…)) → not supported. Sentori levels travel on capture call, not on scope.',
+      )
+    },
+  }
+}
+
+export function withScope<T>(fn: (scope: ScopeProxy) => T): T {
+  // Sentori has no Hub; tags set inside `fn` persist (best-effort
+  // approximation of Sentry semantics). For most callers this is
+  // fine; tighter isolation needs an actual Hub which we don't ship.
+  warnOnce(
+    'withScope',
+    'Sentry.withScope() → tag mutations are NOT auto-reverted on scope exit. Use sentori.setTag/clearTags explicitly for tight isolation.',
+  )
+  return fn(scopeProxy())
+}
+
+export function configureScope(fn: (scope: ScopeProxy) => void): void {
+  fn(scopeProxy())
+}