glitchgrab 1.30.0 → 1.31.0

package/dist/index.d.ts

@@ -35,6 +35,21 @@ interface ReportPayload {
     deviceInfo?: DeviceInfo;
     metadata?: Record<string, string>;
 }
+/** Extra context for an error your app already caught — see `captureError` */
+interface CaptureErrorOptions {
+    /** React component stack, e.g. from `componentDidCatch` / `onCaughtError` */
+    componentStack?: string;
+    /**
+     * Next.js error digest. In production Next replaces server-boundary error
+     * messages with a generic string — the digest is the only thing that tells
+     * two different crashes apart, so it also feeds the dedup signature.
+     */
+    digest?: string;
+    /** Which boundary caught it, e.g. `"next-app-router"` — attached as metadata */
+    boundary?: string;
+    /** Extra metadata merged into the report */
+    metadata?: Record<string, string>;
+}
 interface ReportResult {
     success: boolean;
     reportId?: string;
@@ -44,6 +59,34 @@ interface ReportResult {
     intent?: string;
     message?: string;
 }
+interface FeedbackPayload {
+    token: string;
+    /** 1–5 stars */
+    rating: number;
+    message?: string;
+    pageUrl?: string;
+    userAgent?: string;
+    metadata?: Record<string, string>;
+}
+interface FeedbackResult {
+    success: boolean;
+    feedbackId?: string;
+    rating?: number;
+    createdAt?: string;
+    message?: string;
+}
+/** One stored feedback entry, as returned by the read endpoint. */
+interface GlitchgrabFeedback {
+    id: string;
+    rating: number;
+    message: string | null;
+    pageUrl: string | null;
+    /** Whether the repo owner published this entry for public display */
+    approved: boolean;
+    reporterPrimaryKey: string;
+    reporterName: string;
+    createdAt: string;
+}
 type BreadcrumbType = "console" | "navigation" | "api" | "click" | "error" | "custom";
 interface Breadcrumb {
     type: BreadcrumbType;
@@ -62,6 +105,26 @@ interface DeviceInfo {
     colorScheme: string;
     devicePixelRatio: number;
 }
+/**
+ * Machine state at the moment of the crash, as opposed to `DeviceInfo`, which
+ * describes the machine itself. Most fields are Chromium-only and simply absent
+ * elsewhere — never assume one is present.
+ */
+interface RuntimeInfo {
+    /** ms since this page loaded */
+    timeOnPageMs: number;
+    /** How many errors the SDK has already auto-captured in this page session */
+    errorCount: number;
+    /** `document.visibilityState` — a crash in a background tab reads differently */
+    visibility: string;
+    jsHeapUsedMb?: number;
+    jsHeapLimitMb?: number;
+    /** `navigator.connection.effectiveType` — "4g", "3g", "2g", "slow-2g" */
+    connectionType?: string;
+    downlinkMbps?: number;
+    rttMs?: number;
+    saveData?: boolean;
+}
 interface CapturedContext {
     url: string;
     userAgent: string;
@@ -69,6 +132,12 @@ interface CapturedContext {
     visitedPages: string[];
     breadcrumbs: Breadcrumb[];
     deviceInfo: DeviceInfo | null;
+    /** Runtime health snapshot — null when unavailable (SSR) */
+    runtime: RuntimeInfo | null;
+    /** Key-values the host app attached via `setContext` */
+    appContext: Record<string, string>;
+    /** Build identifier this crash came from, if known */
+    release?: string;
 }
 interface GlitchgrabSession {
     /** Primary key of the user in your database (required) */
@@ -103,17 +172,69 @@ interface GlitchgrabProviderProps {
      * signatures that aren't app bugs — e.g. browser extension bridge errors.
      */
     ignoreErrors?: (string | RegExp)[];
+    /**
+     * Build identifier attached to every report — a version, a tag, a commit SHA.
+     * Tells you which deploy introduced a crash. Falls back to
+     * `NEXT_PUBLIC_APP_VERSION`, `NEXT_PUBLIC_RELEASE`, then
+     * `NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA` when not passed.
+     */
+    release?: string;
+    /**
+     * App-owned context attached to every report — orgId, plan, role, feature
+     * flags. Merged with anything set imperatively via `setContext`.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Extra origins whose failed-request bodies may be recorded in breadcrumbs,
+     * e.g. `["https://api.myapp.com"]`. Same-origin requests are always recorded;
+     * third-party APIs are excluded by default because their error envelopes carry
+     * data you don't control and shouldn't forward into a GitHub issue.
+     */
+    responseBodyOrigins?: string[];
 }
 interface ReportButtonProps {
     position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
     label?: string;
     className?: string;
 }
+interface FeedbackButtonProps {
+    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    label?: string;
+    className?: string;
+    /** Heading inside the dialog (default: "How are we doing?") */
+    title?: string;
+    /** Placeholder for the message box */
+    placeholder?: string;
+    /** Shown after a successful submit */
+    thanksMessage?: string;
+}
 interface UseGlitchgrabReturn {
     /** Report a bug programmatically */
     reportBug: (description: string, metadata?: Record<string, string>) => Promise<ReportResult | null>;
     /** Report with a specific type */
     report: (type: ReportType, description: string, metadata?: Record<string, string>) => Promise<ReportResult | null>;
+    /**
+     * Report an error your app already caught — a framework error boundary
+     * (`app/error.tsx`, React Router `errorElement`, Remix `ErrorBoundary`) or a
+     * `try/catch`. These never reach `window.onerror`, so auto-capture misses them.
+     * Sends `SDK_AUTO`. Fire-and-forget, never throws.
+     */
+    captureError: (error: unknown, options?: CaptureErrorOptions) => void;
+    /**
+     * Attach a key-value to every future report — orgId, plan, role, feature flag.
+     * Pass `null` to remove a key. Survives navigation and provider remounts.
+     */
+    setContext: (key: string, value: unknown) => void;
+    /** Set several context keys at once. Merges; does not replace. */
+    setContexts: (values: Record<string, unknown>) => void;
+    /**
+     * Save a 1–5 star rating your end-user left about your app. Stored by
+     * Glitchgrab and shown on your Feedback page — never becomes a GitHub issue.
+     * Returns null on any failure (never throws).
+     */
+    sendFeedback: (rating: number, message?: string, metadata?: Record<string, string>) => Promise<FeedbackResult | null>;
+    /** Open the built-in feedback dialog (stars + message) programmatically */
+    openFeedbackDialog: () => void;
     /** Add a custom breadcrumb */
     addBreadcrumb: (message: string, data?: Record<string, string>) => void;
     /** Open the ReportButton modal programmatically (captures screenshot + shows dialog) */
@@ -144,11 +265,14 @@ interface UseGlitchgrabReturn {
  *
  * @example
  * ```tsx
- * const { reportBug, report, addBreadcrumb } = useGlitchgrab();
+ * const { reportBug, report, captureError, addBreadcrumb } = useGlitchgrab();
  *
  * // Report a bug
  * reportBug("Login button crashes on mobile");
  *
+ * // Report an error your own boundary already caught (e.g. app/error.tsx)
+ * captureError(error, { digest: error.digest, boundary: "next-app-router" });
+ *
  * // Report a feature request
  * report("FEATURE_REQUEST", "Add dark mode");
  *
@@ -188,6 +312,31 @@ declare function ReportButton({ position, label, className, children, }: ReportB
     }) => ReactNode;
 }): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Trigger for the built-in feedback dialog (stars + message).
+ *
+ * The dialog itself lives inside `GlitchgrabProvider` — this is only the visible
+ * trigger. Open it programmatically with `useGlitchgrab().openFeedbackDialog()`,
+ * or skip the dialog entirely and call `sendFeedback(rating, message)` from your
+ * own UI.
+ *
+ * @example
+ * ```tsx
+ * // Default floating button
+ * <FeedbackButton />
+ *
+ * // Your own trigger
+ * <FeedbackButton>
+ *   {({ onClick }) => <button onClick={onClick}>Rate us</button>}
+ * </FeedbackButton>
+ * ```
+ */
+declare function FeedbackButton({ position, label, className, children, }: FeedbackButtonProps & {
+    children?: (props: {
+        onClick: () => void;
+    }) => ReactNode;
+}): react_jsx_runtime.JSX.Element | null;
+
 interface ErrorBoundaryProps {
     token: string;
     baseUrl?: string;
@@ -207,6 +356,52 @@ declare class GlitchgrabErrorBoundary extends React.Component<ErrorBoundaryProps
     render(): React.ReactNode;
 }
 
+/**
+ * Report an error your app already caught — a framework error boundary
+ * (`app/error.tsx`, `app/global-error.tsx`, React Router `errorElement`, Remix
+ * `ErrorBoundary`), a `componentDidCatch`, or a `try/catch` you want filed.
+ *
+ * These never reach `window.onerror`, so provider auto-capture cannot see them.
+ *
+ * Fire-and-forget. Never throws, never blocks the fallback UI render. No-ops if
+ * no `GlitchgrabProvider` has rendered yet (nothing to authenticate with).
+ *
+ * @example
+ * ```tsx
+ * // app/global-error.tsx — renders outside the provider tree
+ * "use client";
+ * import { captureError } from "glitchgrab";
+ *
+ * export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
+ *   useEffect(() => {
+ *     captureError(error, { digest: error.digest, boundary: "next-global-error" });
+ *   }, [error]);
+ *   return <html><body><p>Something went wrong</p></body></html>;
+ * }
+ * ```
+ */
+declare function captureError(error: unknown, options?: CaptureErrorOptions): void;
+
+/**
+ * App-owned context: key-values the host app attaches once and every report
+ * carries thereafter — orgId, plan, role, active feature flags. The SDK cannot
+ * guess these, and they are usually the difference between "a crash" and "a
+ * crash for enterprise tenants on the new billing flow".
+ *
+ * Module-level, not React state, so it survives the provider unmount that
+ * `global-error.tsx` causes and is readable from non-React call sites.
+ */
+/**
+ * Attach one key-value to every future report. Passing `null`/`undefined`
+ * removes the key — so a value that goes away (user logs out of an org) stops
+ * being reported instead of going stale.
+ */
+declare function setContext(key: string, value: unknown): void;
+/** Set several keys at once. Merges — it does not replace what's already set. */
+declare function setContexts(values: Record<string, unknown>): void;
+declare function getAppContext(): Record<string, string>;
+declare function clearAppContext(): void;
+
 interface GlitchgrabReport {
     id: string;
     source: string;
@@ -299,7 +494,60 @@ declare function useGlitchgrabActions({ token, onSuccess, onError, }: {
     error: string | null;
 };
 
-declare function initBreadcrumbs(max?: number): void;
+interface FeedbackQuery {
+    token: string;
+    /** Only entries the repo owner published — use this for a public testimonials wall */
+    approvedOnly?: boolean;
+    /** Only this end-user's feedback (their primary key in your DB) */
+    userId?: string;
+    /** Floor on the star rating, 1–5 */
+    minRating?: number;
+    /** Max results (default 50, max 100) */
+    limit?: number;
+    baseUrl?: string;
+}
+/**
+ * Standalone fetcher — use with TanStack Query or any data fetching library.
+ *
+ * ```tsx
+ * const { data } = useQuery({
+ *   queryKey: ["testimonials"],
+ *   queryFn: () => fetchGlitchgrabFeedback({
+ *     token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
+ *     approvedOnly: true,
+ *     minRating: 4,
+ *   }),
+ * });
+ * ```
+ */
+declare function fetchGlitchgrabFeedback(query: FeedbackQuery): Promise<GlitchgrabFeedback[]>;
+/**
+ * Hook to read back the feedback your end-users left — render it as a
+ * testimonials wall, or show a user their own past ratings.
+ *
+ * ```tsx
+ * const { feedback, isLoading, error, refetch } = useGlitchgrabFeedback({
+ *   token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
+ *   approvedOnly: true,
+ * });
+ * ```
+ */
+declare function useGlitchgrabFeedback(query: FeedbackQuery): {
+    feedback: GlitchgrabFeedback[];
+    isLoading: boolean;
+    isFetching: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+interface BreadcrumbOptions {
+    /**
+     * Additional origins to capture error response bodies from, e.g.
+     * `["https://api.myapp.com"]`. Same-origin requests are always captured.
+     */
+    responseBodyOrigins?: string[];
+}
+declare function initBreadcrumbs(max?: number, options?: BreadcrumbOptions): void;
 declare function addBreadcrumb(type: BreadcrumbType, message: string, data?: Record<string, string>): void;
 declare function getBreadcrumbs(): Breadcrumb[];
 declare function clearBreadcrumbs(): void;
@@ -330,6 +578,15 @@ declare function captureContext(visitedPages: string[]): CapturedContext;
  * Never throws — returns null on failure.
  */
 declare function sendReport(payload: ReportPayload, baseUrl?: string): Promise<ReportResult | null>;
+/**
+ * Save a star rating your end-user left about your app.
+ * Never throws — returns null on failure.
+ *
+ * Unlike `sendReport`, this is always a deliberate user action with a dialog
+ * open in front of them, so it retries on transient failure but skips the
+ * sendBeacon fallback: the caller needs a real result to show a thank-you.
+ */
+declare function sendFeedback(payload: FeedbackPayload, baseUrl?: string): Promise<FeedbackResult | null>;
 interface EnhanceContext {
     url?: string;
     visitedPages?: string[];
@@ -349,8 +606,14 @@ declare function computeSignature(params: {
     errorMessage: string | undefined;
     pageUrl: string | undefined;
     errorStack?: string | undefined;
+    /**
+     * Next.js error digest. Production strips server-boundary errors to a generic
+     * message with no useful stack, so without the digest every distinct server
+     * crash on one page collapses into a single signature.
+     */
+    digest?: string | undefined;
 }): string;
 declare function shouldSkipDuplicate(signature: string, windowMs?: number, now?: number): boolean;
 declare function clearDedupCache(): void;
 
-export { type Breadcrumb, type BreadcrumbType, type CapturedContext, type DeviceInfo, GLITCHGRAB_SHORTCUT, GLITCHGRAB_SHORTCUT_MAC, type GlitchgrabConfig, GlitchgrabErrorBoundary, GlitchgrabProvider, type GlitchgrabProviderProps, type GlitchgrabReport, type GlitchgrabSession, ReportButton, type ReportButtonProps, type ReportPayload, type ReportResult, type ReportSeverity, type ReportType, type UseGlitchgrabReturn, addBreadcrumb, captureContext, captureDeviceInfo, clearBreadcrumbs, clearDedupCache, computeSignature, enhanceText, fetchGlitchgrabReports, getBreadcrumbs, getShortcutLabel, initBreadcrumbs, matchesShortcut, sanitizeUrl, sendReport, shouldSkipDuplicate, useGlitchgrab, useGlitchgrabActions, useGlitchgrabReports };
+export { type Breadcrumb, type BreadcrumbType, type CaptureErrorOptions, type CapturedContext, type DeviceInfo, FeedbackButton, type FeedbackButtonProps, type FeedbackPayload, type FeedbackQuery, type FeedbackResult, GLITCHGRAB_SHORTCUT, GLITCHGRAB_SHORTCUT_MAC, type GlitchgrabConfig, GlitchgrabErrorBoundary, type GlitchgrabFeedback, GlitchgrabProvider, type GlitchgrabProviderProps, type GlitchgrabReport, type GlitchgrabSession, ReportButton, type ReportButtonProps, type ReportPayload, type ReportResult, type ReportSeverity, type ReportType, type RuntimeInfo, type UseGlitchgrabReturn, addBreadcrumb, captureContext, captureDeviceInfo, captureError, clearAppContext, clearBreadcrumbs, clearDedupCache, computeSignature, enhanceText, fetchGlitchgrabFeedback, fetchGlitchgrabReports, getAppContext, getBreadcrumbs, getShortcutLabel, initBreadcrumbs, matchesShortcut, sanitizeUrl, sendFeedback, sendReport, setContext, setContexts, shouldSkipDuplicate, useGlitchgrab, useGlitchgrabActions, useGlitchgrabFeedback, useGlitchgrabReports };