@buoy-gg/sentry 0.0.0-stage → 7.0.77

package/lib/typescript/drops/dropStore.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Bounded ring buffer of drop records, plus the pure helpers that turn SDK
+ * artifacts into them.
+ *
+ * The parsing lives here rather than in the capture layer so it can be
+ * tested without a Sentry client: each helper takes the raw shape the SDK
+ * produces and returns records, with no I/O and no globals.
+ */
+import type { DropRecord, DropReason } from "./types";
+type Listener = () => void;
+export declare function recordDrop(drop: Omit<DropRecord, "id">): void;
+/**
+ * The reported drops left after subtracting the ones already observed, and
+ * the tally updated in place. Pure apart from `tally`, so it tests without a
+ * store.
+ */
+export declare function reconcileReported(tally: Map<string, number>, drops: Omit<DropRecord, "id">[]): Omit<DropRecord, "id">[];
+/** Note an observed drop in a tally, for `reconcileReported`. */
+export declare function tallyObserved(tally: Map<string, number>, drop: Omit<DropRecord, "id">): void;
+/** Record SDK-reported drops, minus the ones already recorded as observed. */
+export declare function recordReportedDrops(drops: Omit<DropRecord, "id">[]): void;
+export declare function subscribeDrops(listener: Listener): () => void;
+export declare function getDrops(): DropRecord[];
+export declare function clearDrops(): void;
+/** Replace the whole list from a remote snapshot (desktop mirror mode). */
+export declare function replaceDrops(next: DropRecord[]): void;
+export declare function dropsFromClientReport(payload: unknown, timestamp: number): Omit<DropRecord, "id">[];
+/** Read the RN discard reason off a transaction event, if it carries one. */
+export declare function rnDiscardReason(event: unknown): string | null;
+export declare function dropFromRnDiscard(reason: string, name: string, timestamp: number): Omit<DropRecord, "id">;
+/**
+ * Native SDK log line → drop record, or null when the line isn't about a drop.
+ *
+ * This is the only channel through which a native rate limit or an oversized
+ * payload reaches JS, and it only flows when `debug: true`. Matching is kept
+ * to unambiguous signals — a status code or an explicit "discard"/"dropp"
+ * verb — because native log text varies by SDK version and platform, and a
+ * loose matcher inventing drops is worse than missing one.
+ */
+export declare function dropFromNativeLog(message: string, timestamp: number): Omit<DropRecord, "id"> | null;
+/** Group drops by reason for the summary, most units first. */
+export declare function summarizeDrops(drops: DropRecord[]): {
+    reason: DropReason;
+    units: number;
+    records: number;
+}[];
+export {};
+//# sourceMappingURL=dropStore.d.ts.map

package/lib/typescript/drops/dropStore.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Drop attribution answers "why isn't my event in Sentry", so a wrong
+ * mapping here sends someone hunting the wrong layer. These pin the
+ * translation from each SDK artifact to a reason.
+ */
+export {};
+//# sourceMappingURL=dropStore.test.d.ts.map

package/lib/typescript/drops/observe.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Watch the client for drops.
+ *
+ * Three seams, because no single one sees everything:
+ *
+ *  1. **Wrapped `beforeSend` / `beforeSendTransaction`** — the only way to
+ *     observe the most common cause of a missing event. We replace the
+ *     option with a wrapper that calls the original, records a drop when it
+ *     returns null, and passes the result through untouched. The user's
+ *     callback keeps full authority; we never change its answer.
+ *  2. **`beforeEnvelope` client reports** — the SDK's own tally of what it
+ *     discarded, one envelope late.
+ *  3. **`onNativeLog`** — native rate limits and oversize rejections, which
+ *     reach JS through no other channel.
+ *
+ * Everything here is wrapped in try/catch: this sits on the error-reporting
+ * path, and a drop watcher that throws would suppress the very events it
+ * exists to explain.
+ */
+/**
+ * Install the drop watchers on a client. Idempotent per client.
+ *
+ * Returns true when at least one seam was attached, so the caller can
+ * report whether drop attribution is actually live.
+ */
+export declare function observeDrops(client: unknown): boolean;
+/**
+ * Feed a native SDK log line to the watcher. Wired from the host app's
+ * `onNativeLog` (which the SDK only calls when `debug: true`) — exported so
+ * an app can forward its own handler's lines without giving up the callback.
+ */
+export declare function noteNativeLog(message: string): void;
+//# sourceMappingURL=observe.d.ts.map

package/lib/typescript/drops/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Drop attribution — why an event never reached Sentry.
+ *
+ * The SDK discards events at a dozen points between `captureException` and
+ * the wire, and almost all of them are silent: `beforeSend` returning null,
+ * a sample-rate roll, dedupe, an event processor, a native 429. "My event
+ * isn't in Sentry" is the single most common Sentry support thread, and
+ * today the only way to answer it is reading debug logs.
+ *
+ * Each reason below is a place the SDK can drop something, phrased as the
+ * answer a developer actually needs.
+ */
+export type DropReason = 
+/** A `beforeSend` / `beforeSendTransaction` callback returned null. */
+"before_send"
+/** `sampleRate` / `tracesSampleRate` rolled against it. */
+ | "sample_rate"
+/** An event processor or integration returned null (dedupe, inbound filters). */
+ | "event_processor"
+/** RN tracing discarded a transaction it considered empty. */
+ | "rn_discard"
+/** The SDK's own client report said the backend/transport dropped it. */
+ | "client_report"
+/** Native transport rejected it — rate limit, oversize, cache eviction. */
+ | "native"
+/** Recorded by a client report under a reason this tool doesn't model. */
+ | "other";
+export interface DropRecord {
+    id: number;
+    timestamp: number;
+    reason: DropReason;
+    /** What was dropped: "error", "transaction", "span", "log"… */
+    category: string;
+    /** How many units this record accounts for (client reports batch them). */
+    quantity: number;
+    /** One line naming the specific event where we can identify it. */
+    detail: string;
+    /**
+     * Where the finding came from, so a reader can judge it:
+     * `observed` — we watched it happen (wrapped callback, discard attribute).
+     * `reported` — the SDK told us after the fact (client report, native log).
+     */
+    source: "observed" | "reported";
+}
+/** Human copy for each reason: what it means and what to do about it. */
+export declare const DROP_REASON_META: Record<DropReason, {
+    label: string;
+    explanation: string;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @buoy-gg/sentry — Sentry SDK inspector for React Native.
+ *
+ * Sees every envelope the app's Sentry SDK sends (via the client's public
+ * `beforeEnvelope` hook), with per-item types, sizes, and payloads — so you
+ * know exactly what leaves the device before it costs you quota.
+ */
+export { sentryToolPreset, createSentryTool } from "./preset";
+export { SentryRoot } from "./SentryRoot";
+export { installSentryCapture, attachToClient, parseEnvelope } from "./capture/attach";
+export { SentryModal } from "./components/SentryModal";
+export { SentryIcon, SENTRY_ICON_COLOR } from "./components/SentryIcon";
+export { SentryHeader } from "./devtools/SentryHeader";
+export { SentryBody } from "./devtools/SentryBody";
+export { useSentryController, formatBytes, type SentryController, type SentryView, type SentryTab, } from "./devtools/useSentryController";
+export { SentryCostView } from "./devtools/SentryCostView";
+export { SentryToolView } from "./devtools/SentryToolView";
+export { SENTRY_PLANS, SENTRY_PLANS_VERIFIED_ON, DEFAULT_PLAN_ID, CATEGORY_META, getPlan, type SentryPlan, type QuotaCategory, } from "./quota/plans";
+export { computeUsage, projectMonthly, quotaFraction, type UsageReport, type UsageTotals, type UsageContributor, } from "./quota/usage";
+export { SentryDropsView } from "./devtools/SentryDropsView";
+export { getDrops, subscribeDrops, clearDrops, replaceDrops, summarizeDrops, dropsFromClientReport, dropFromNativeLog, dropFromRnDiscard, rnDiscardReason, } from "./drops/dropStore";
+export { observeDrops, noteNativeLog } from "./drops/observe";
+export { DROP_REASON_META, type DropRecord, type DropReason, } from "./drops/types";
+export { SentryAuditView } from "./devtools/SentryAuditView";
+export { auditConfig, worstSeverity, type AuditFinding, type AuditInput, type AuditableOptions, type FindingSeverity, type FindingCategory, } from "./audit/rules";
+export { scanForPii, PII_KIND_LABEL, type PiiFinding, type PiiKind } from "./audit/pii";
+export { sentrySyncAdapter } from "./sync/sentrySyncAdapter";
+export { subscribe, getEnvelopes, getAttachStatus, clearEnvelopes, replaceEnvelopes, replaceAttachStatus, replaceUsage, getMirroredUsage, onClear, } from "./store/sentryEnvelopeStore";
+export type { CapturedEnvelope, CapturedEnvelopeItem, EnvelopeOrigin, SentryAttachStatus, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/preset.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pre-configured Sentry tool for FloatingDevTools.
+ *
+ * @example
+ * ```tsx
+ * import { sentryToolPreset } from '@buoy-gg/sentry';
+ *
+ * <FloatingDevTools apps={[sentryToolPreset]} />
+ * ```
+ */
+import React from "react";
+import { SentryModal } from "./components/SentryModal";
+export declare const sentryToolPreset: {
+    id: string;
+    name: string;
+    description: string;
+    slot: "both";
+    icon: ({ size, color }: {
+        size: number;
+        color?: string;
+    }) => React.JSX.Element;
+    component: typeof SentryModal;
+};
+/** Create a custom Sentry tool configuration. */
+export declare const createSentryTool: (options?: (Record<never, never> & import("@buoy-gg/shared-ui").ToolPresetOverrides) | undefined) => {
+    id: string;
+    name: string;
+    description: string;
+    slot: "both";
+    icon: ({ size, color }: {
+        size: number;
+        color?: string;
+    }) => React.JSX.Element;
+    component: typeof SentryModal;
+};
+//# sourceMappingURL=preset.d.ts.map

package/lib/typescript/quota/plans.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sentry billing units and plan quotas.
+ *
+ * Sentry bills on RECEIPT, not on storage: an event their server-side
+ * dynamic sampling later discards is still billed. That is what makes a
+ * device-side meter meaningful — every unit counted here is a unit the app
+ * has already committed to paying for, and the only lever that removes it
+ * without losing data is client-side config.
+ *
+ * Quotas move. They're data, not logic, so they can be corrected without
+ * touching the meter — see `SENTRY_PLANS`. Figures are the published
+ * monthly allowances as of 2026-09; `verifiedOn` is stamped so a stale
+ * table is visible rather than silently wrong.
+ */
+/** The categories Sentry meters separately. Each has its own quota. */
+export type QuotaCategory = "errors" | "spans" | "replays" | "logBytes" | "attachmentBytes";
+export interface SentryPlan {
+    id: string;
+    name: string;
+    /** Monthly allowance per category. `0` means the plan cannot use it at all. */
+    quota: Record<QuotaCategory, number>;
+}
+/** When the numbers below were last checked against sentry.io/pricing. */
+export declare const SENTRY_PLANS_VERIFIED_ON = "2026-09";
+export declare const SENTRY_PLANS: SentryPlan[];
+export declare const DEFAULT_PLAN_ID = "developer";
+export declare function getPlan(planId: string): SentryPlan;
+/** Display metadata for each category, in the order the meter shows them. */
+export declare const CATEGORY_META: {
+    key: QuotaCategory;
+    label: string;
+    /** How the raw number should be rendered. */
+    format: "count" | "bytes";
+    /** One line on what actually produces this unit — the actionable half. */
+    hint: string;
+}[];
+//# sourceMappingURL=plans.d.ts.map

package/lib/typescript/quota/usage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Turn captured envelopes into Sentry billing units, and project a month.
+ *
+ * The mapping is deliberately literal — each rule is how Sentry actually
+ * meters that item, and a wrong rule here makes the whole meter a lie:
+ *
+ *  - `event`        → 1 error, unless it's a feedback event (not metered as one)
+ *  - `transaction`  → its span count (root + children), NOT one unit
+ *  - `replay_event` → 1 replay session
+ *  - `log`          → payload bytes
+ *  - `attachment`   → payload bytes
+ *
+ * Envelope types with no line here (session, client_report, profile) are
+ * either unmetered or metered on a plan dimension this tool doesn't model
+ * yet; they're deliberately absent rather than guessed at.
+ */
+import type { CapturedEnvelope } from "../types";
+import type { QuotaCategory } from "./plans";
+export type UsageTotals = Record<QuotaCategory, number>;
+/** One source of billable volume, for the "what is expensive" breakdown. */
+export interface UsageContributor {
+    /** Human label — the transaction name, or the item type. */
+    label: string;
+    category: QuotaCategory;
+    /** Units this source contributed. */
+    units: number;
+    /** How many envelopes it appeared in. */
+    occurrences: number;
+}
+export interface UsageReport {
+    totals: UsageTotals;
+    /** Wall-clock ms between the first and last captured envelope. */
+    windowMs: number;
+    /** Biggest contributors, most units first (already category-aware). */
+    contributors: UsageContributor[];
+}
+export declare function computeUsage(envelopes: CapturedEnvelope[]): UsageReport;
+/** Rate window floor. Projecting from a 2-second sample produces a number
+ * with no meaning; below this the UI shows the raw session instead. */
+export declare const MIN_PROJECTION_WINDOW_MS = 30000;
+/**
+ * Extrapolate the observed rate to a month.
+ *
+ * This is honest about what it is: a straight-line projection of ONE
+ * session on ONE device. It answers "if usage kept up at the rate I just
+ * watched" — useful for catching a config that is orders of magnitude off,
+ * not for forecasting a bill. `usable` says whether the window was long
+ * enough to mean anything.
+ */
+export declare function projectMonthly(report: UsageReport): {
+    usable: boolean;
+    totals: UsageTotals;
+};
+/** Fraction of a quota used, or `null` when the plan disallows the category. */
+export declare function quotaFraction(used: number, quota: number): number | null;
+//# sourceMappingURL=usage.d.ts.map

package/lib/typescript/quota/usage.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The billing math is the tool's whole claim to usefulness: if a transaction
+ * counts as one unit instead of its spans, the meter under-reports the single
+ * most surprising line on a Sentry bill by an order of magnitude. These pin
+ * each metering rule, not the plumbing around it.
+ */
+export {};
+//# sourceMappingURL=usage.test.d.ts.map

package/lib/typescript/store/sanitize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * sanitizePayload — deep-convert a captured Sentry payload into JSON-safe values.
+ *
+ * Envelope payloads are usually already plain JSON (they're about to be
+ * serialized onto the wire), but they can carry Errors, bigints, functions in
+ * hint-derived fields, and — in pathological beforeSend mutations — cycles.
+ * Both the external-sync snapshot and on-device persistence need plain JSON,
+ * so this produces a structural copy with cycles broken and strings capped.
+ *
+ * Same shape as @buoy-gg/console's sanitizer; Sentry payloads run deeper
+ * (event → contexts → trace → data …) so the depth cap is higher.
+ */
+/** Max chars of one string kept for inspection / on the wire. */
+export declare const SNAPSHOT_STRING_LIMIT: number;
+export declare function capString(value: string, limit?: number): string;
+/** Deep-sanitize one payload value into JSON-safe values. */
+export declare function sanitizePayload(payload: unknown): unknown;
+//# sourceMappingURL=sanitize.d.ts.map

package/lib/typescript/store/sentryEnvelopeStore.d.ts

@@ -0,0 +1,49 @@
+/**
+ * sentryEnvelopeStore
+ *
+ * Bounded ring buffer of Sentry envelopes captured on their way out of the
+ * app, plus the attach status of the capture layer. Consumed by the UI via
+ * `useSyncExternalStore` and by the external-sync adapter for the desktop
+ * dashboard (which mirrors this same store through `replaceEnvelopes`).
+ *
+ * The store never touches the Sentry SDK — recording is fed by
+ * `capture/attach.ts`. Everything here must be cheap and crash-proof: it sits
+ * on the app's error-reporting path, and a capture layer that breaks the
+ * thing it observes is worse than no capture at all.
+ *
+ * The buffer, listeners, clear-forwarding, frame-coalesced emit and the
+ * "push to the dashboard NOW" hook all come from shared `createToolStore`;
+ * this module only adds the attach status and the public function API.
+ */
+import type { CapturedEnvelope, SentryAttachStatus } from "../types";
+type Listener = () => void;
+/** Append one captured envelope to the buffer. Error envelopes are pushed to
+ * the dashboard immediately: an envelope carrying a fatal is likely the app's
+ * last send. */
+export declare function recordEnvelope(envelope: Omit<CapturedEnvelope, "id">, options?: {
+    urgent?: boolean;
+}): void;
+/** Update the capture layer's attach status. */
+export declare function setAttachStatus(next: SentryAttachStatus): void;
+/** Subscribe to changes (envelopes or status). Returns an unsubscribe function. */
+export declare function subscribe(listener: Listener): () => void;
+/** Current snapshot (stable reference between mutations for useSyncExternalStore). */
+export declare function getEnvelopes(): CapturedEnvelope[];
+/** Current attach status. */
+export declare function getAttachStatus(): SentryAttachStatus;
+/** Clear all captured envelopes. Fires onClear listeners (e.g. to forward the
+ * clear to a remote device when running in mirror mode). */
+export declare function clearEnvelopes(): void;
+/** Replace the whole envelope list from a remote snapshot. */
+export declare function replaceEnvelopes(next: CapturedEnvelope[]): void;
+/** Usage totals from a remote snapshot, or null when computing locally. */
+export declare function getMirroredUsage(): unknown;
+/** Supply usage totals from a remote snapshot (desktop mirror mode). */
+export declare function replaceUsage(next: unknown): void;
+/** Replace the attach status from a remote snapshot. */
+export declare function replaceAttachStatus(next: SentryAttachStatus): void;
+/** Register a listener fired when clearEnvelopes() is called. Returns an
+ * unsubscribe function. Used by the dashboard to forward clears to the device. */
+export declare function onClear(listener: Listener): () => void;
+export {};
+//# sourceMappingURL=sentryEnvelopeStore.d.ts.map

package/lib/typescript/sync/sentrySyncAdapter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * sentrySyncAdapter — streams captured envelopes from the device to the
+ * desktop dashboard via @buoy-gg/external-sync.
+ *
+ * Structurally matches external-sync's `ToolSyncAdapter` WITHOUT importing the
+ * package (no hard dependency — auto-discovery in @buoy-gg/core picks it up by
+ * export name and announces the "sentry" capability).
+ *
+ * Envelopes are the fattest payloads any Buoy tool ships (a single event with
+ * breadcrumbs and contexts is tens of KB), so the same wire discipline as the
+ * console tool applies: per-entry caps, a snapshot budget walked newest-first,
+ * and a WeakMap wire cache keyed on entry identity (entries are never mutated).
+ */
+import { type UsageTotals } from "../quota/usage";
+import type { DropRecord } from "../drops/types";
+import type { CapturedEnvelope, SentryAttachStatus } from "../types";
+interface SentrySnapshot {
+    status: SentryAttachStatus;
+    envelopes: CapturedEnvelope[];
+    /**
+     * Billing units for the FULL buffer, computed before the wire budget trims
+     * envelopes — so the desktop and an MCP client read the same totals the
+     * device shows, not a total silently short by whatever didn't fit.
+     */
+    usage: {
+        session: UsageTotals;
+        projectedMonthly: UsageTotals | null;
+        windowMs: number;
+        topContributors: {
+            label: string;
+            category: string;
+            units: number;
+        }[];
+    };
+    /** Why events went missing. Capped: the summary carries the whole picture,
+     * the records are the recent detail. */
+    drops: {
+        summary: {
+            reason: string;
+            units: number;
+            records: number;
+        }[];
+        recent: DropRecord[];
+    };
+}
+/**
+ * The newest drops for the wire, errors kept. Dropped tracing spans and
+ * transactions ("no_parent_span") arrive by the hundred; a plain last-50
+ * slice pushed the one dropped error — the answer to "why isn't this in
+ * Sentry?" — off the wire after a long session.
+ */
+export declare function wireDrops(drops: DropRecord[]): DropRecord[];
+export declare const sentrySyncAdapter: {
+    version: number;
+    getSnapshot(): SentrySnapshot;
+    subscribe(onChange: () => void): () => void;
+    actions: {
+        clearEnvelopes(): {
+            cleared: true;
+        };
+    };
+};
+export {};
+//# sourceMappingURL=sentrySyncAdapter.d.ts.map

package/lib/typescript/sync/sentrySyncAdapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sentrySyncAdapter.test.d.ts.map

package/lib/typescript/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared types for the Sentry inspector.
+ *
+ * A "captured envelope" is one Sentry envelope observed on its way out of the
+ * app (via the client's `beforeEnvelope` hook — the same tee point Sentry's
+ * own Spotlight integration uses). Envelopes are the SDK's wire unit: a small
+ * JSON header plus a list of items (event / transaction / log / …), each with
+ * its own header and payload.
+ */
+/** Where a captured envelope came from. The JS layer is the only source today;
+ * `native` arrives with the sidecar listener (native crashes, sessions, replay). */
+export type EnvelopeOrigin = "js" | "native";
+/** One item inside a captured envelope. */
+export interface CapturedEnvelopeItem {
+    /** Sentry envelope item type: `event`, `transaction`, `client_report`, `log`,
+     * `attachment`, `profile`, `session`, … (open set — new SDKs add types). */
+    type: string;
+    /** Approximate serialized size of the item payload in bytes. */
+    bytes: number;
+    /** One-line human summary (error headline, transaction name, log count, …). */
+    summary: string;
+    /** `transaction` items only: number of spans this transaction carries
+     * (children + the root). Spans are Sentry's billing unit for tracing. */
+    spanCount?: number;
+    /**
+     * The item payload, deep-sanitized to JSON-safe values and size-capped for
+     * inspection. Missing for binary payloads (attachments, replay recordings).
+     */
+    payload?: unknown;
+    /** True when the payload was binary (stored as size only, no content). */
+    binary?: boolean;
+}
+/** One envelope observed leaving the app. */
+export interface CapturedEnvelope {
+    /** Monotonic id, unique per captured envelope. */
+    id: number;
+    /** Capture time in ms since epoch. */
+    timestamp: number;
+    /** Which SDK layer produced it. */
+    origin: EnvelopeOrigin;
+    /** `event_id` from the envelope header, when present. */
+    eventId?: string;
+    /** The envelope header, sanitized (dsn, sdk, sent_at, trace, …). */
+    header?: unknown;
+    /** The items the envelope carries, in order. */
+    items: CapturedEnvelopeItem[];
+    /** Sum of item payload bytes (headers excluded — they're noise at this scale). */
+    totalBytes: number;
+}
+/** Where the capture layer currently stands with the host app's Sentry SDK. */
+export type SentryAttachStatus = 
+/** Capture installed, no attach attempt has resolved yet. */
+"searching"
+/** Subscribed to a live Sentry client's `beforeEnvelope`. */
+ | "attached"
+/** `@sentry/react-native` isn't resolvable and no `getClient` was provided. */
+ | "sdk-not-found"
+/** The SDK module exists but no client appeared before the retry window closed
+ * (Sentry.init was never called, or it's disabled). */
+ | "no-client";
+//# sourceMappingURL=types.d.ts.map