@debugkit/sdk 0.1.0 → 0.2.0

package/README.md

@@ -4,11 +4,13 @@ Log errors and events from your app into **your own** cloud. This is the client
 [deBug](https://github.com/Abantu-Digital/deBug): events go to an ingest function you deploy
 in Firebase or AWS, and a dashboard you run yourself tells you what is failing and why.
 
-- About 3 KB gzipped, with no runtime dependencies in your bundle.
+- About 6 KB gzipped, with no runtime dependencies in your bundle.
 - Works with React, React Native (bare and Expo), Expo Router, TanStack Start/Router, Next.js
   and plain Node.
-- Captures crashes, unhandled rejections and render errors automatically. Batches, retries,
-  and queues events while offline.
+- **Works on its own once initialised:** crashes, failed requests, sessions and the steps
+  leading up to each error are recorded without any extra code. See
+  [What it records by itself](#what-it-records-by-itself).
+- Batches, retries, rate-limits, and queues events while offline.
 
 ## Install
 
@@ -32,6 +34,56 @@ hooks, and they all share the same `deBug` client.
 Your ingest endpoint and key come from your deBug deployment. During development, point at a
 dashboard running in demo mode: `http://localhost:4400/api/ingest` with key `pk_local`.
 
+## What it records by itself
+
+Calling `init()` (or `initExpo`, `initReactNative`, `initNode`) turns on everything in this
+table. The manual API below is for what only you know: which part of the app a step belongs to,
+and whether it succeeded.
+
+| | Browser | React Native / Expo | Node |
+|---|---|---|---|
+| Uncaught errors and unhandled rejections | ✓ | ✓ (fatal crashes marked critical) | ✓ (flushes, then exits like Node) |
+| Render errors | with `DebugErrorBoundary` | with `DebugErrorBoundary` | |
+| **Failed requests** (5xx, timeouts, network failures) as errors, every request as a breadcrumb | fetch, XHR | fetch, XHR (axios too) | fetch, `node:http` (axios, SDKs), plus 5xx your server sends |
+| **Sessions**: crash-free and error-free rates per release | one per page load | new session after 30 min in the background | one per process |
+| Navigation breadcrumbs | any router (History API) | add `useDebugExpoRouter` or `trackReactNavigation` | |
+| Clicks on buttons and links, by their label | ✓ | | |
+| `console.warn` / `console.error` as breadcrumbs | ✓ | ✓ | off by default |
+| Foreground/background, online/offline | ✓ | foreground/background | |
+| Device, OS, app version, network type on every event | ✓ | ✓ | ✓ |
+
+Every error carries the last 30 breadcrumbs, so the dashboard shows what happened just
+before it: the screen, the click, the request that failed.
+
+**Privacy.** Query strings and fragments are dropped from every URL before anything is
+recorded, and ids in paths become `:id` (`/v1/orders/8812?token=…` becomes `/v1/orders/:id`).
+Request and response bodies, headers and what users type are never read. Use `beforeSend` to
+scrub anything else.
+
+**Noise control.** At most 60 errors a minute are sent (`maxErrorsPerMinute`), and one repeating
+error gets at most a sixth of that. Breadcrumbs that repeat are collapsed into one. `sampleRate`
+keeps a fraction of errors and events. Sessions and fatal crashes are never sampled out, so
+crash-free rates stay accurate.
+
+### Tuning it
+
+```ts
+deBug.init({
+  endpoint, ingestKey, app: { id: "your-app", version: "2.4.0" },
+  autoCapture: { console: false, clicks: false }, // or `false` to turn everything off
+  network: {
+    flows: [["/v2/auth/", "auth.login"], [/\/payments\//, "checkout.payment"]], // tag requests by URL
+    ignoreUrls: ["analytics.example.com"],
+    isFailure: (status) => status >= 500 || status === 429, // default: 500 and above
+    slowMs: 3000, // slower requests get a warning breadcrumb
+  },
+  sampleRate: 1,
+  maxErrorsPerMinute: 60,
+});
+```
+
+Requests to your ingest endpoint and to the Metro and Expo dev servers are never recorded.
+
 ## Expo
 
 ```tsx

package/dist/{chunk-3UN5VMQU.js → chunk-3WRI3DI2.js}

@@ -1,4 +1,4 @@
-import { deBug, __publicField } from './chunk-VIJ5USKQ.js';
+import { deBug, __publicField } from './chunk-5C7KJJNO.js';
 import { Component, useEffect } from 'react';
 
 var DebugErrorBoundary = class extends Component {
@@ -29,13 +29,13 @@ var DebugErrorBoundary = class extends Component {
 };
 function useDebugNavigation(path, client = deBug) {
   useEffect(() => {
-    if (path) client.breadcrumb("navigation", path);
+    if (path) client.navigated(path);
   }, [path, client]);
 }
 function trackTanStackRouter(router, client = deBug) {
-  return router.subscribe("onResolved", ({ toLocation }) => client.breadcrumb("navigation", toLocation.pathname));
+  return router.subscribe("onResolved", ({ toLocation }) => client.navigated(toLocation.pathname));
 }
 
 export { DebugErrorBoundary, trackTanStackRouter, useDebugNavigation };
-//# sourceMappingURL=chunk-3UN5VMQU.js.map
-//# sourceMappingURL=chunk-3UN5VMQU.js.map
+//# sourceMappingURL=chunk-3WRI3DI2.js.map
+//# sourceMappingURL=chunk-3WRI3DI2.js.map

package/dist/chunk-3WRI3DI2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react.tsx"],"names":[],"mappings":";;;AAqBO,IAAM,kBAAA,GAAN,cAAiC,SAAA,CAA0C;AAAA,EAA3E,WAAA,GAAA;AAAA,IAAA,KAAA,CAAA,GAAA,SAAA,CAAA;AACL,IAAA,aAAA,CAAA,IAAA,EAAA,OAAA,EAAe,EAAE,OAAO,IAAA,EAAK,CAAA;AAgB7B,IAAA,aAAA,CAAA,IAAA,EAAA,OAAA,EAAQ,MAAM,IAAA,CAAK,QAAA,CAAS,EAAE,KAAA,EAAO,MAAM,CAAA,CAAA;AAAA,EAAA;AAAA,EAd3C,OAAO,yBAAyB,KAAA,EAAqB;AACnD,IAAA,OAAO,EAAE,KAAA,EAAM;AAAA,EACjB;AAAA,EAEA,iBAAA,CAAkB,OAAc,IAAA,EAAiB;AA5BnD,IAAA,IAAA,EAAA,EAAA,EAAA,EAAA,EAAA;AA6BI,IAAA,MAAM,MAAA,GAAA,CAAS,EAAA,GAAA,IAAA,CAAK,KAAA,CAAM,MAAA,KAAX,IAAA,GAAA,EAAA,GAAqB,KAAA;AACpC,IAAA,IAAI,KAAK,cAAA,EAAgB;AACvB,MAAA,MAAA,CAAO,UAAA,CAAW,IAAA,EAAM,oBAAA,EAAsB,EAAE,gBAAgB,IAAA,CAAK,cAAA,CAAe,IAAA,EAAK,CAAE,KAAA,CAAM,CAAA,EAAG,IAAI,CAAA,IAAK,OAAO,CAAA;AAAA,IACtH;AACA,IAAA,MAAA,CAAO,KAAA,CAAM,KAAA,EAAO,EAAE,IAAA,EAAM,KAAK,KAAA,CAAM,IAAA,EAAM,OAAA,EAAS,KAAA,EAAO,IAAA,EAAM,EAAE,MAAA,EAAQ,gBAAA,IAAoB,CAAA;AACjG,IAAA,KAAK,OAAO,KAAA,EAAM;AAClB,IAAA,CAAA,EAAA,GAAA,CAAA,EAAA,GAAA,IAAA,CAAK,KAAA,EAAM,OAAA,KAAX,IAAA,GAAA,MAAA,GAAA,EAAA,CAAA,IAAA,CAAA,EAAA,EAAqB,KAAA,EAAO,IAAA,CAAA;AAAA,EAC9B;AAAA,EAIA,MAAA,GAAS;AACP,IAAA,MAAM,EAAE,KAAA,EAAM,GAAI,IAAA,CAAK,KAAA;AACvB,IAAA,IAAI,CAAC,KAAA,EAAO,OAAO,IAAA,CAAK,KAAA,CAAM,QAAA;AAC9B,IAAA,MAAM,EAAE,QAAA,EAAS,GAAI,IAAA,CAAK,KAAA;AAC1B,IAAA,OAAO,OAAO,QAAA,KAAa,UAAA,GAAa,QAAA,CAAS,EAAE,KAAA,EAAO,KAAA,EAAO,IAAA,CAAK,KAAA,EAAO,CAAA,GAAK,QAAA,IAAA,IAAA,GAAA,QAAA,GAAY,IAAA;AAAA,EAChG;AACF;AAGO,SAAS,kBAAA,CAAmB,IAAA,EAA0B,MAAA,GAAsB,KAAA,EAAO;AACxF,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,EAAM,MAAA,CAAO,SAAA,CAAU,IAAI,CAAA;AAAA,EACjC,CAAA,EAAG,CAAC,IAAA,EAAM,MAAM,CAAC,CAAA;AACnB;AAYO,SAAS,mBAAA,CAAoB,MAAA,EAAoB,MAAA,GAAsB,KAAA,EAAO;AACnF,EAAA,OAAO,MAAA,CAAO,SAAA,CAAU,YAAA,EAAc,CAAC,EAAE,UAAA,EAAW,KAAM,MAAA,CAAO,SAAA,CAAU,UAAA,CAAW,QAAQ,CAAC,CAAA;AACjG","file":"chunk-3WRI3DI2.js","sourcesContent":["import { Component, useEffect, type ErrorInfo, type ReactNode } from \"react\";\nimport { deBug, type DebugClient } from \"./index\";\n\nexport interface DebugErrorBoundaryProps {\n  children?: ReactNode;\n  /** What to render after a crash. A function gets the error and a reset callback. */\n  fallback?: ReactNode | ((props: { error: Error; reset: () => void }) => ReactNode);\n  /** Part of the app this boundary protects, e.g. \"checkout\". */\n  flow?: string;\n  client?: DebugClient;\n  onError?: (error: Error, info: ErrorInfo) => void;\n}\n\ninterface State {\n  error: Error | null;\n}\n\n/**\n * Catches render errors that React would otherwise swallow (or turn into a white/red screen)\n * and reports them. Works in React DOM and React Native.\n */\nexport class DebugErrorBoundary extends Component<DebugErrorBoundaryProps, State> {\n  state: State = { error: null };\n\n  static getDerivedStateFromError(error: Error): State {\n    return { error };\n  }\n\n  componentDidCatch(error: Error, info: ErrorInfo) {\n    const client = this.props.client ?? deBug;\n    if (info.componentStack) {\n      client.breadcrumb(\"ui\", \"React render error\", { componentStack: info.componentStack.trim().slice(0, 1500) }, \"error\");\n    }\n    client.error(error, { flow: this.props.flow, handled: false, tags: { source: \"error-boundary\" } });\n    void client.flush();\n    this.props.onError?.(error, info);\n  }\n\n  reset = () => this.setState({ error: null });\n\n  render() {\n    const { error } = this.state;\n    if (!error) return this.props.children;\n    const { fallback } = this.props;\n    return typeof fallback === \"function\" ? fallback({ error, reset: this.reset }) : (fallback ?? null);\n  }\n}\n\n/** Adds a navigation breadcrumb whenever `path` changes. Works with any router. */\nexport function useDebugNavigation(path: string | undefined, client: DebugClient = deBug) {\n  useEffect(() => {\n    if (path) client.navigated(path);\n  }, [path, client]);\n}\n\n/** Minimal shape of a TanStack Router instance (avoids a hard dependency). */\ninterface RouterLike {\n  subscribe(event: \"onResolved\", fn: (e: { toLocation: { pathname: string; href?: string } }) => void): () => void;\n}\n\n/**\n * Records a breadcrumb for every navigation in a TanStack Router app:\n *   const router = createRouter({ routeTree }); trackTanStackRouter(router);\n * Returns an unsubscribe function.\n */\nexport function trackTanStackRouter(router: RouterLike, client: DebugClient = deBug) {\n  return router.subscribe(\"onResolved\", ({ toLocation }) => client.navigated(toLocation.pathname));\n}\n\nexport { deBug } from \"./index\";\n"]}