@starko-one/sdk 0.0.0-stage → 0.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +248 -0
  2. package/LICENSE +17 -0
  3. package/NOTICE +58 -0
  4. package/README.md +81 -2
  5. package/dist/api-BAFm4Lxj.d.ts +558 -0
  6. package/dist/api-DNrctwJu.d.cts +558 -0
  7. package/dist/browser/index.cjs +168 -0
  8. package/dist/browser/index.d.cts +131 -0
  9. package/dist/browser/index.d.ts +131 -0
  10. package/dist/browser/index.js +7 -0
  11. package/dist/build/rollup.cjs +22 -0
  12. package/dist/build/rollup.d.cts +34 -0
  13. package/dist/build/rollup.d.ts +34 -0
  14. package/dist/build/rollup.js +3 -0
  15. package/dist/build/vite.cjs +51 -0
  16. package/dist/build/vite.d.cts +23 -0
  17. package/dist/build/vite.d.ts +23 -0
  18. package/dist/build/vite.js +46 -0
  19. package/dist/build/webpack.cjs +18 -0
  20. package/dist/build/webpack.d.cts +39 -0
  21. package/dist/build/webpack.d.ts +39 -0
  22. package/dist/build/webpack.js +3 -0
  23. package/dist/chunk-2PM4FRM5.cjs +431 -0
  24. package/dist/chunk-335HNCOJ.js +249 -0
  25. package/dist/chunk-3AW5B2WW.js +115 -0
  26. package/dist/chunk-3R5TQAWD.js +216 -0
  27. package/dist/chunk-6H5MOPTQ.cjs +1230 -0
  28. package/dist/chunk-7TKNT3QJ.cjs +2487 -0
  29. package/dist/chunk-A4WLNFMU.cjs +220 -0
  30. package/dist/chunk-ALYFFOPR.cjs +134 -0
  31. package/dist/chunk-BVVFVRMO.js +1113 -0
  32. package/dist/chunk-CIHNKN62.cjs +15 -0
  33. package/dist/chunk-CMGCH6HD.js +1212 -0
  34. package/dist/chunk-D6QAPQ7L.cjs +56 -0
  35. package/dist/chunk-DUO5V6WZ.js +213 -0
  36. package/dist/chunk-EC2WZ6PG.js +90 -0
  37. package/dist/chunk-EFURLFJT.cjs +187 -0
  38. package/dist/chunk-EROUORMY.js +53 -0
  39. package/dist/chunk-LXBXFOAP.cjs +96 -0
  40. package/dist/chunk-MF6SA6DB.js +563 -0
  41. package/dist/chunk-N5R6ORIB.js +413 -0
  42. package/dist/chunk-N6R6BWHK.cjs +142 -0
  43. package/dist/chunk-QAGGN2T7.cjs +225 -0
  44. package/dist/chunk-QV4HRIDD.cjs +659 -0
  45. package/dist/chunk-TKNDYQB3.cjs +583 -0
  46. package/dist/chunk-UI5YC4TH.js +131 -0
  47. package/dist/chunk-VEHZYLK6.cjs +1151 -0
  48. package/dist/chunk-VNCWOGTI.js +12 -0
  49. package/dist/chunk-VWNIOGE6.js +180 -0
  50. package/dist/chunk-WDKRKGYF.js +608 -0
  51. package/dist/chunk-XOZIXBUK.js +2462 -0
  52. package/dist/chunk-ZS3K3SDR.cjs +258 -0
  53. package/dist/cli/index.cjs +2780 -0
  54. package/dist/common-DLFAqL2d.d.cts +36 -0
  55. package/dist/common-DbSXkaw6.d.ts +36 -0
  56. package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
  57. package/dist/dedupe-DoYiSx-9.d.ts +13 -0
  58. package/dist/handler-BcnsnvhF.d.cts +82 -0
  59. package/dist/handler-qHzilC9T.d.ts +82 -0
  60. package/dist/index.cjs +309 -0
  61. package/dist/index.d.cts +187 -0
  62. package/dist/index.d.ts +187 -0
  63. package/dist/index.js +4 -0
  64. package/dist/next/client.cjs +113 -0
  65. package/dist/next/client.d.cts +26 -0
  66. package/dist/next/client.d.ts +26 -0
  67. package/dist/next/client.js +41 -0
  68. package/dist/next/config.cjs +277 -0
  69. package/dist/next/config.d.cts +193 -0
  70. package/dist/next/config.d.ts +193 -0
  71. package/dist/next/config.js +263 -0
  72. package/dist/next/index.cjs +148 -0
  73. package/dist/next/index.d.cts +32 -0
  74. package/dist/next/index.d.ts +32 -0
  75. package/dist/next/index.js +59 -0
  76. package/dist/node/index.cjs +257 -0
  77. package/dist/node/index.d.cts +145 -0
  78. package/dist/node/index.d.ts +145 -0
  79. package/dist/node/index.js +83 -0
  80. package/dist/options-BUhWuWJX.d.cts +79 -0
  81. package/dist/options-BUhWuWJX.d.ts +79 -0
  82. package/dist/react/index.cjs +107 -0
  83. package/dist/react/index.d.cts +84 -0
  84. package/dist/react/index.d.ts +84 -0
  85. package/dist/react/index.js +103 -0
  86. package/dist/scope-D1ouJm2h.d.cts +628 -0
  87. package/dist/scope-D1ouJm2h.d.ts +628 -0
  88. package/dist/server-edge-7624N3WF.cjs +51 -0
  89. package/dist/server-edge-BEEXWL7T.js +48 -0
  90. package/dist/server-node-ET4LIPEC.cjs +27 -0
  91. package/dist/server-node-TQUVMZUC.js +24 -0
  92. package/dist/session-C_WzbEN2.d.cts +4 -0
  93. package/dist/session-C_WzbEN2.d.ts +4 -0
  94. package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
  95. package/dist/session-propagation-RM5py1bp.d.ts +30 -0
  96. package/dist/starko.min.js +6 -0
  97. package/docs/browser.md +386 -0
  98. package/docs/configuration.md +310 -0
  99. package/docs/nextjs.md +488 -0
  100. package/docs/node.md +427 -0
  101. package/docs/other-backends.md +232 -0
  102. package/docs/privacy.md +112 -0
  103. package/docs/react.md +187 -0
  104. package/docs/source-maps.md +482 -0
  105. package/docs/troubleshooting.md +263 -0
  106. package/docs/widget.md +84 -0
  107. package/docs/wire-format.md +547 -0
  108. package/package.json +191 -4
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Which upload protocol:
3
+ * - `"auto"` (default): the bulk upload when the server has it, else v1. Decided once per upload, on the server's answer to the first `bulk/check`.
4
+ * - `"bulk"`: the bulk upload only (maps go straight from the build to Starko's storage through signed URLs); fails when the server does not have it.
5
+ * - `"v1"`: every map through the Starko host, in parts (`check` → `upload` → `complete`).
6
+ */
7
+ type UploadProtocol = "auto" | "bulk" | "v1";
8
+
9
+ /** A path pattern: a glob (`*`, `**`, `?`) or a RegExp, matched against the file's path relative to the output directory, with `/` separators. */
10
+ type PathPattern = string | RegExp;
11
+ /**
12
+ * Options shared by the Rollup, Vite and webpack plugins and `withStarko`.
13
+ *
14
+ * Source maps and your original source: a plugin only ever switches source
15
+ * maps on for you when your config did not ask for them, and the maps it
16
+ * switched on are always removed from the build output after the upload
17
+ * attempt, whatever its outcome (success, failure, timeout, error, dry run),
18
+ * together with any `sourceMappingURL` comment pointing at them. Maps your
19
+ * own config produced are yours: they are kept unless
20
+ * `deleteSourcemapsAfterUpload` is true. Without an API key nothing is
21
+ * changed at all.
22
+ */
23
+ interface StarkoBuildOptions {
24
+ /** Secret key with the `sourcemaps:write` scope. Default: `STARKO_API_KEY`. Without one the plugin changes nothing (no source maps switched on, no injection, no upload) and warns once. */
25
+ apiKey?: string;
26
+ /** Starko host. Default: `STARKO_HOST`, then `https://v2.starko.one`. */
27
+ host?: string;
28
+ /** Release (app version) of this build. Default: `STARKO_RELEASE`, the CI commit, `git rev-parse HEAD`. */
29
+ release?: string;
30
+ /** Inject and upload. Default: production builds only (each plugin documents what that means for its bundler). */
31
+ enabled?: boolean;
32
+ /**
33
+ * What happens to the source maps after the upload attempt:
34
+ * - not set (default): the maps the plugin switched on are deleted; maps your config produced are kept.
35
+ * - `true`: every source map is deleted (and the `sourceMappingURL` comments pointing at them), whatever the upload's outcome. Not in a dry run.
36
+ * - `false`: maps your config produced are kept. Maps the plugin switched on are STILL deleted: `false` never leaves maps you did not ask for in the output.
37
+ */
38
+ deleteSourcemapsAfterUpload?: boolean;
39
+ /** Bundles to process. Default: every `.js`, `.mjs` and `.cjs` file. */
40
+ include?: PathPattern | PathPattern[];
41
+ /** Bundles to skip. Default: anything under `node_modules`. */
42
+ exclude?: PathPattern | PathPattern[];
43
+ /** Inject, then log what would be uploaded without sending anything. Maps the plugin switched on are still deleted; yours are left alone. */
44
+ dryRun?: boolean;
45
+ /** No logging. Failures still fail the build when `failOnError` is set. */
46
+ silent?: boolean;
47
+ /** Fail the build when the upload fails. Default false: a failed upload (or any error in the plugin) logs a warning and the build succeeds. */
48
+ failOnError?: boolean;
49
+ /**
50
+ * Deadline for the whole upload step, in milliseconds. Default 180000 (3
51
+ * minutes). When it passes the upload stops with a warning saying how far
52
+ * it got, and the build goes on; the next build continues from there (a
53
+ * map the server has completed is never sent again). The first upload of
54
+ * an app with thousands of source maps may need much longer: see "Large
55
+ * builds" in docs/source-maps.md.
56
+ */
57
+ uploadTimeoutMs?: number;
58
+ /**
59
+ * Source maps uploaded at the same time: with the bulk upload, uploads to
60
+ * Starko's storage (default 16); with v1, maps sent through the Starko
61
+ * host (default 8). At most 16; larger values are clamped.
62
+ */
63
+ uploadConcurrency?: number;
64
+ /**
65
+ * How source maps are sent. Default `"auto"`: straight to Starko's storage
66
+ * through short-lived signed URLs (the bulk upload) when the server
67
+ * offers it, else through the Starko host (`"v1"`), decided once per
68
+ * upload. When uploads to the storage host fail systematically (a proxy
69
+ * or a firewall that lets only the Starko host through), `"auto"` sends
70
+ * the remaining maps through v1 with a warning. `"bulk"` never uses v1
71
+ * (it fails instead); `"v1"` never contacts the storage host. See "Large
72
+ * builds" in docs/source-maps.md.
73
+ */
74
+ uploadProtocol?: UploadProtocol;
75
+ }
76
+ /** Who made the build emit source maps: the user's own config, or the plugin. */
77
+ type SourcemapOwner = "user" | "starko";
78
+
79
+ export type { SourcemapOwner as S, StarkoBuildOptions as a };
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Which upload protocol:
3
+ * - `"auto"` (default): the bulk upload when the server has it, else v1. Decided once per upload, on the server's answer to the first `bulk/check`.
4
+ * - `"bulk"`: the bulk upload only (maps go straight from the build to Starko's storage through signed URLs); fails when the server does not have it.
5
+ * - `"v1"`: every map through the Starko host, in parts (`check` → `upload` → `complete`).
6
+ */
7
+ type UploadProtocol = "auto" | "bulk" | "v1";
8
+
9
+ /** A path pattern: a glob (`*`, `**`, `?`) or a RegExp, matched against the file's path relative to the output directory, with `/` separators. */
10
+ type PathPattern = string | RegExp;
11
+ /**
12
+ * Options shared by the Rollup, Vite and webpack plugins and `withStarko`.
13
+ *
14
+ * Source maps and your original source: a plugin only ever switches source
15
+ * maps on for you when your config did not ask for them, and the maps it
16
+ * switched on are always removed from the build output after the upload
17
+ * attempt, whatever its outcome (success, failure, timeout, error, dry run),
18
+ * together with any `sourceMappingURL` comment pointing at them. Maps your
19
+ * own config produced are yours: they are kept unless
20
+ * `deleteSourcemapsAfterUpload` is true. Without an API key nothing is
21
+ * changed at all.
22
+ */
23
+ interface StarkoBuildOptions {
24
+ /** Secret key with the `sourcemaps:write` scope. Default: `STARKO_API_KEY`. Without one the plugin changes nothing (no source maps switched on, no injection, no upload) and warns once. */
25
+ apiKey?: string;
26
+ /** Starko host. Default: `STARKO_HOST`, then `https://v2.starko.one`. */
27
+ host?: string;
28
+ /** Release (app version) of this build. Default: `STARKO_RELEASE`, the CI commit, `git rev-parse HEAD`. */
29
+ release?: string;
30
+ /** Inject and upload. Default: production builds only (each plugin documents what that means for its bundler). */
31
+ enabled?: boolean;
32
+ /**
33
+ * What happens to the source maps after the upload attempt:
34
+ * - not set (default): the maps the plugin switched on are deleted; maps your config produced are kept.
35
+ * - `true`: every source map is deleted (and the `sourceMappingURL` comments pointing at them), whatever the upload's outcome. Not in a dry run.
36
+ * - `false`: maps your config produced are kept. Maps the plugin switched on are STILL deleted: `false` never leaves maps you did not ask for in the output.
37
+ */
38
+ deleteSourcemapsAfterUpload?: boolean;
39
+ /** Bundles to process. Default: every `.js`, `.mjs` and `.cjs` file. */
40
+ include?: PathPattern | PathPattern[];
41
+ /** Bundles to skip. Default: anything under `node_modules`. */
42
+ exclude?: PathPattern | PathPattern[];
43
+ /** Inject, then log what would be uploaded without sending anything. Maps the plugin switched on are still deleted; yours are left alone. */
44
+ dryRun?: boolean;
45
+ /** No logging. Failures still fail the build when `failOnError` is set. */
46
+ silent?: boolean;
47
+ /** Fail the build when the upload fails. Default false: a failed upload (or any error in the plugin) logs a warning and the build succeeds. */
48
+ failOnError?: boolean;
49
+ /**
50
+ * Deadline for the whole upload step, in milliseconds. Default 180000 (3
51
+ * minutes). When it passes the upload stops with a warning saying how far
52
+ * it got, and the build goes on; the next build continues from there (a
53
+ * map the server has completed is never sent again). The first upload of
54
+ * an app with thousands of source maps may need much longer: see "Large
55
+ * builds" in docs/source-maps.md.
56
+ */
57
+ uploadTimeoutMs?: number;
58
+ /**
59
+ * Source maps uploaded at the same time: with the bulk upload, uploads to
60
+ * Starko's storage (default 16); with v1, maps sent through the Starko
61
+ * host (default 8). At most 16; larger values are clamped.
62
+ */
63
+ uploadConcurrency?: number;
64
+ /**
65
+ * How source maps are sent. Default `"auto"`: straight to Starko's storage
66
+ * through short-lived signed URLs (the bulk upload) when the server
67
+ * offers it, else through the Starko host (`"v1"`), decided once per
68
+ * upload. When uploads to the storage host fail systematically (a proxy
69
+ * or a firewall that lets only the Starko host through), `"auto"` sends
70
+ * the remaining maps through v1 with a warning. `"bulk"` never uses v1
71
+ * (it fails instead); `"v1"` never contacts the storage host. See "Large
72
+ * builds" in docs/source-maps.md.
73
+ */
74
+ uploadProtocol?: UploadProtocol;
75
+ }
76
+ /** Who made the build emit source maps: the user's own config, or the plugin. */
77
+ type SourcemapOwner = "user" | "starko";
78
+
79
+ export type { SourcemapOwner as S, StarkoBuildOptions as a };
@@ -0,0 +1,107 @@
1
+ "use client";'use strict';
2
+
3
+ var chunkQV4HRIDD_cjs = require('../chunk-QV4HRIDD.cjs');
4
+ require('../chunk-N6R6BWHK.cjs');
5
+ var react = require('react');
6
+
7
+ var INITIAL = { hasError: false, error: void 0, componentStack: "", eventId: "" };
8
+ var BOUNDARY = /* @__PURE__ */ Symbol.for("starko.sdk.react.boundary");
9
+ var stackOf = (info) => {
10
+ try {
11
+ const s = info && typeof info === "object" ? info.componentStack : void 0;
12
+ return typeof s === "string" ? s : "";
13
+ } catch {
14
+ return "";
15
+ }
16
+ };
17
+ function captureReactError(error, componentStack, mechanism, before) {
18
+ try {
19
+ return chunkQV4HRIDD_cjs.withScope((scope) => {
20
+ if (before) {
21
+ try {
22
+ before(scope);
23
+ } catch {
24
+ }
25
+ }
26
+ if (componentStack) scope.setContext("react", { componentStack });
27
+ return chunkQV4HRIDD_cjs.captureException(error, { mechanism });
28
+ });
29
+ } catch {
30
+ return "";
31
+ }
32
+ }
33
+ var _a, _b;
34
+ var StarkoErrorBoundary = class extends (_b = react.Component, _a = BOUNDARY, _b) {
35
+ constructor() {
36
+ super(...arguments);
37
+ this[_a] = true;
38
+ this.state = INITIAL;
39
+ this.resetError = () => {
40
+ const { error, componentStack, eventId } = this.state;
41
+ this.setState(INITIAL);
42
+ if (this.props.onReset) this.props.onReset(error, componentStack, eventId);
43
+ };
44
+ }
45
+ static getDerivedStateFromError(error) {
46
+ return { hasError: true, error };
47
+ }
48
+ componentDidCatch(error, info) {
49
+ const componentStack = stackOf(info);
50
+ const { beforeCapture, onError, fallback } = this.props;
51
+ const eventId = captureReactError(
52
+ error,
53
+ componentStack,
54
+ { type: "react.error-boundary", handled: fallback !== void 0 && fallback !== null },
55
+ beforeCapture ? (scope) => beforeCapture(scope, error, componentStack) : void 0
56
+ );
57
+ this.setState({ componentStack, eventId });
58
+ if (onError) onError(error, componentStack, eventId);
59
+ }
60
+ render() {
61
+ if (!this.state.hasError) return this.props.children;
62
+ const { fallback } = this.props;
63
+ const { error, componentStack, eventId } = this.state;
64
+ if (typeof fallback === "function") return fallback({ error, componentStack, eventId, resetError: this.resetError });
65
+ return fallback ?? null;
66
+ }
67
+ };
68
+ StarkoErrorBoundary.displayName = "StarkoErrorBoundary";
69
+ function withErrorBoundary(WrappedComponent, boundaryProps = {}) {
70
+ const name = WrappedComponent.displayName || WrappedComponent.name || "Component";
71
+ const Wrapped = (props) => react.createElement(StarkoErrorBoundary, boundaryProps, react.createElement(WrappedComponent, props));
72
+ Wrapped.displayName = `starkoErrorBoundary(${name})`;
73
+ return Wrapped;
74
+ }
75
+ function reportGlobal(error) {
76
+ const g = globalThis;
77
+ if (typeof g.reportError === "function") return g.reportError(error);
78
+ const w = typeof window === "object" ? window : void 0;
79
+ if (w && typeof w.ErrorEvent === "function") {
80
+ const message = error && typeof error === "object" && typeof error.message === "string" ? String(error.message) : String(error);
81
+ const shouldLog = w.dispatchEvent(new w.ErrorEvent("error", { bubbles: true, cancelable: true, message, error }));
82
+ if (!shouldLog) return;
83
+ }
84
+ console.error(error);
85
+ }
86
+ function reactErrorHandler(callbacks = {}) {
87
+ const make = (type, handled, fallback, user) => function starkoRootErrorHandler(error, errorInfo) {
88
+ try {
89
+ const boundary = errorInfo && errorInfo.errorBoundary;
90
+ if (!(boundary && typeof boundary === "object" && boundary[BOUNDARY])) {
91
+ captureReactError(error, stackOf(errorInfo), { type, handled });
92
+ }
93
+ } catch {
94
+ }
95
+ if (user) user(error, errorInfo);
96
+ else fallback(error);
97
+ };
98
+ return {
99
+ onUncaughtError: make("react.onUncaughtError", false, reportGlobal, callbacks.onUncaughtError),
100
+ onCaughtError: make("react.onCaughtError", true, (e) => console.error(e), callbacks.onCaughtError),
101
+ onRecoverableError: make("react.onRecoverableError", true, reportGlobal, callbacks.onRecoverableError)
102
+ };
103
+ }
104
+
105
+ exports.StarkoErrorBoundary = StarkoErrorBoundary;
106
+ exports.reactErrorHandler = reactErrorHandler;
107
+ exports.withErrorBoundary = withErrorBoundary;
@@ -0,0 +1,84 @@
1
+ import { Component, ReactNode, ErrorInfo, ComponentType } from 'react';
2
+ import { S as Scope } from '../scope-D1ouJm2h.cjs';
3
+
4
+ /**
5
+ * `@starko-one/sdk/react`: React error boundary and React 19 root hooks.
6
+ * React (≥ 18; the root hooks need 19) is a peer dependency. This entry
7
+ * imports only the environment-free core: it reports to whichever client the
8
+ * app started (`@starko-one/sdk/browser`, `/next/client`, `/node`, or the
9
+ * script tag), and does nothing before one exists.
10
+ *
11
+ * <StarkoErrorBoundary fallback={({ error, resetError }) => <Oops onRetry={resetError} />}>
12
+ * <App />
13
+ * </StarkoErrorBoundary>
14
+ *
15
+ * createRoot(el, reactErrorHandler()); // React 19
16
+ *
17
+ * During server rendering React does not call error boundaries: the
18
+ * boundary renders its children and captures nothing.
19
+ */
20
+
21
+ interface FallbackRenderProps {
22
+ error: unknown;
23
+ componentStack: string;
24
+ /** The captured event's id ("" before the SDK started). */
25
+ eventId: string;
26
+ /** Clear the error and render the children again. */
27
+ resetError(): void;
28
+ }
29
+ interface StarkoErrorBoundaryProps {
30
+ children?: ReactNode;
31
+ /** Rendered instead of the children after an error: a node, or a function of the error. Without one, nothing is rendered. */
32
+ fallback?: ReactNode | ((props: FallbackRenderProps) => ReactNode);
33
+ /** Called after the error is captured. */
34
+ onError?(error: unknown, componentStack: string, eventId: string): void;
35
+ /** Called with the capture's scope before capturing: add tags, user, context. */
36
+ beforeCapture?(scope: Scope, error: unknown, componentStack: string): void;
37
+ /** Called when `resetError` clears the error. */
38
+ onReset?(error: unknown, componentStack: string, eventId: string): void;
39
+ }
40
+ interface State {
41
+ hasError: boolean;
42
+ error: unknown;
43
+ componentStack: string;
44
+ eventId: string;
45
+ }
46
+ /** Marks boundaries of any copy of this module, so the root hook can tell they capture themselves. */
47
+ declare const BOUNDARY: unique symbol;
48
+ declare class StarkoErrorBoundary extends Component<StarkoErrorBoundaryProps, State> {
49
+ static displayName: string;
50
+ readonly [BOUNDARY] = true;
51
+ state: State;
52
+ static getDerivedStateFromError(error: unknown): Partial<State>;
53
+ componentDidCatch(error: unknown, info: ErrorInfo): void;
54
+ resetError: () => void;
55
+ render(): ReactNode;
56
+ }
57
+ /** `Component` wrapped in a `StarkoErrorBoundary` with `boundaryProps`. */
58
+ declare function withErrorBoundary<P extends object>(WrappedComponent: ComponentType<P>, boundaryProps?: Omit<StarkoErrorBoundaryProps, "children">): ComponentType<P>;
59
+ type RootErrorInfo = {
60
+ componentStack?: string;
61
+ errorBoundary?: unknown;
62
+ };
63
+ type RootHook = (error: unknown, errorInfo: RootErrorInfo) => void;
64
+ interface ReactRootErrorHandlers {
65
+ onUncaughtError: RootHook;
66
+ onCaughtError: RootHook;
67
+ onRecoverableError: RootHook;
68
+ }
69
+ /**
70
+ * Handlers for React 19's root options:
71
+ *
72
+ * createRoot(el, reactErrorHandler());
73
+ * createRoot(el, { ...reactErrorHandler({ onCaughtError: myLogger }), identifierPrefix: "x" });
74
+ *
75
+ * Each one captures (uncaught: unhandled; caught and recoverable: handled;
76
+ * the component stack in `contexts.react`), then calls your callback for
77
+ * that hook, or does what React does by default without one (uncaught and
78
+ * recoverable errors are reported to the page, caught errors logged with
79
+ * `console.error`), so passing these handlers changes nothing else. An error
80
+ * caught by a `StarkoErrorBoundary` is left to the boundary (one event).
81
+ */
82
+ declare function reactErrorHandler(callbacks?: Partial<ReactRootErrorHandlers>): ReactRootErrorHandlers;
83
+
84
+ export { type FallbackRenderProps, type ReactRootErrorHandlers, StarkoErrorBoundary, type StarkoErrorBoundaryProps, reactErrorHandler, withErrorBoundary };
@@ -0,0 +1,84 @@
1
+ import { Component, ReactNode, ErrorInfo, ComponentType } from 'react';
2
+ import { S as Scope } from '../scope-D1ouJm2h.js';
3
+
4
+ /**
5
+ * `@starko-one/sdk/react`: React error boundary and React 19 root hooks.
6
+ * React (≥ 18; the root hooks need 19) is a peer dependency. This entry
7
+ * imports only the environment-free core: it reports to whichever client the
8
+ * app started (`@starko-one/sdk/browser`, `/next/client`, `/node`, or the
9
+ * script tag), and does nothing before one exists.
10
+ *
11
+ * <StarkoErrorBoundary fallback={({ error, resetError }) => <Oops onRetry={resetError} />}>
12
+ * <App />
13
+ * </StarkoErrorBoundary>
14
+ *
15
+ * createRoot(el, reactErrorHandler()); // React 19
16
+ *
17
+ * During server rendering React does not call error boundaries: the
18
+ * boundary renders its children and captures nothing.
19
+ */
20
+
21
+ interface FallbackRenderProps {
22
+ error: unknown;
23
+ componentStack: string;
24
+ /** The captured event's id ("" before the SDK started). */
25
+ eventId: string;
26
+ /** Clear the error and render the children again. */
27
+ resetError(): void;
28
+ }
29
+ interface StarkoErrorBoundaryProps {
30
+ children?: ReactNode;
31
+ /** Rendered instead of the children after an error: a node, or a function of the error. Without one, nothing is rendered. */
32
+ fallback?: ReactNode | ((props: FallbackRenderProps) => ReactNode);
33
+ /** Called after the error is captured. */
34
+ onError?(error: unknown, componentStack: string, eventId: string): void;
35
+ /** Called with the capture's scope before capturing: add tags, user, context. */
36
+ beforeCapture?(scope: Scope, error: unknown, componentStack: string): void;
37
+ /** Called when `resetError` clears the error. */
38
+ onReset?(error: unknown, componentStack: string, eventId: string): void;
39
+ }
40
+ interface State {
41
+ hasError: boolean;
42
+ error: unknown;
43
+ componentStack: string;
44
+ eventId: string;
45
+ }
46
+ /** Marks boundaries of any copy of this module, so the root hook can tell they capture themselves. */
47
+ declare const BOUNDARY: unique symbol;
48
+ declare class StarkoErrorBoundary extends Component<StarkoErrorBoundaryProps, State> {
49
+ static displayName: string;
50
+ readonly [BOUNDARY] = true;
51
+ state: State;
52
+ static getDerivedStateFromError(error: unknown): Partial<State>;
53
+ componentDidCatch(error: unknown, info: ErrorInfo): void;
54
+ resetError: () => void;
55
+ render(): ReactNode;
56
+ }
57
+ /** `Component` wrapped in a `StarkoErrorBoundary` with `boundaryProps`. */
58
+ declare function withErrorBoundary<P extends object>(WrappedComponent: ComponentType<P>, boundaryProps?: Omit<StarkoErrorBoundaryProps, "children">): ComponentType<P>;
59
+ type RootErrorInfo = {
60
+ componentStack?: string;
61
+ errorBoundary?: unknown;
62
+ };
63
+ type RootHook = (error: unknown, errorInfo: RootErrorInfo) => void;
64
+ interface ReactRootErrorHandlers {
65
+ onUncaughtError: RootHook;
66
+ onCaughtError: RootHook;
67
+ onRecoverableError: RootHook;
68
+ }
69
+ /**
70
+ * Handlers for React 19's root options:
71
+ *
72
+ * createRoot(el, reactErrorHandler());
73
+ * createRoot(el, { ...reactErrorHandler({ onCaughtError: myLogger }), identifierPrefix: "x" });
74
+ *
75
+ * Each one captures (uncaught: unhandled; caught and recoverable: handled;
76
+ * the component stack in `contexts.react`), then calls your callback for
77
+ * that hook, or does what React does by default without one (uncaught and
78
+ * recoverable errors are reported to the page, caught errors logged with
79
+ * `console.error`), so passing these handlers changes nothing else. An error
80
+ * caught by a `StarkoErrorBoundary` is left to the boundary (one event).
81
+ */
82
+ declare function reactErrorHandler(callbacks?: Partial<ReactRootErrorHandlers>): ReactRootErrorHandlers;
83
+
84
+ export { type FallbackRenderProps, type ReactRootErrorHandlers, StarkoErrorBoundary, type StarkoErrorBoundaryProps, reactErrorHandler, withErrorBoundary };
@@ -0,0 +1,103 @@
1
+ "use client";import { withScope, captureException } from '../chunk-WDKRKGYF.js';
2
+ import '../chunk-3AW5B2WW.js';
3
+ import { Component, createElement } from 'react';
4
+
5
+ var INITIAL = { hasError: false, error: void 0, componentStack: "", eventId: "" };
6
+ var BOUNDARY = /* @__PURE__ */ Symbol.for("starko.sdk.react.boundary");
7
+ var stackOf = (info) => {
8
+ try {
9
+ const s = info && typeof info === "object" ? info.componentStack : void 0;
10
+ return typeof s === "string" ? s : "";
11
+ } catch {
12
+ return "";
13
+ }
14
+ };
15
+ function captureReactError(error, componentStack, mechanism, before) {
16
+ try {
17
+ return withScope((scope) => {
18
+ if (before) {
19
+ try {
20
+ before(scope);
21
+ } catch {
22
+ }
23
+ }
24
+ if (componentStack) scope.setContext("react", { componentStack });
25
+ return captureException(error, { mechanism });
26
+ });
27
+ } catch {
28
+ return "";
29
+ }
30
+ }
31
+ var _a, _b;
32
+ var StarkoErrorBoundary = class extends (_b = Component, _a = BOUNDARY, _b) {
33
+ constructor() {
34
+ super(...arguments);
35
+ this[_a] = true;
36
+ this.state = INITIAL;
37
+ this.resetError = () => {
38
+ const { error, componentStack, eventId } = this.state;
39
+ this.setState(INITIAL);
40
+ if (this.props.onReset) this.props.onReset(error, componentStack, eventId);
41
+ };
42
+ }
43
+ static getDerivedStateFromError(error) {
44
+ return { hasError: true, error };
45
+ }
46
+ componentDidCatch(error, info) {
47
+ const componentStack = stackOf(info);
48
+ const { beforeCapture, onError, fallback } = this.props;
49
+ const eventId = captureReactError(
50
+ error,
51
+ componentStack,
52
+ { type: "react.error-boundary", handled: fallback !== void 0 && fallback !== null },
53
+ beforeCapture ? (scope) => beforeCapture(scope, error, componentStack) : void 0
54
+ );
55
+ this.setState({ componentStack, eventId });
56
+ if (onError) onError(error, componentStack, eventId);
57
+ }
58
+ render() {
59
+ if (!this.state.hasError) return this.props.children;
60
+ const { fallback } = this.props;
61
+ const { error, componentStack, eventId } = this.state;
62
+ if (typeof fallback === "function") return fallback({ error, componentStack, eventId, resetError: this.resetError });
63
+ return fallback ?? null;
64
+ }
65
+ };
66
+ StarkoErrorBoundary.displayName = "StarkoErrorBoundary";
67
+ function withErrorBoundary(WrappedComponent, boundaryProps = {}) {
68
+ const name = WrappedComponent.displayName || WrappedComponent.name || "Component";
69
+ const Wrapped = (props) => createElement(StarkoErrorBoundary, boundaryProps, createElement(WrappedComponent, props));
70
+ Wrapped.displayName = `starkoErrorBoundary(${name})`;
71
+ return Wrapped;
72
+ }
73
+ function reportGlobal(error) {
74
+ const g = globalThis;
75
+ if (typeof g.reportError === "function") return g.reportError(error);
76
+ const w = typeof window === "object" ? window : void 0;
77
+ if (w && typeof w.ErrorEvent === "function") {
78
+ const message = error && typeof error === "object" && typeof error.message === "string" ? String(error.message) : String(error);
79
+ const shouldLog = w.dispatchEvent(new w.ErrorEvent("error", { bubbles: true, cancelable: true, message, error }));
80
+ if (!shouldLog) return;
81
+ }
82
+ console.error(error);
83
+ }
84
+ function reactErrorHandler(callbacks = {}) {
85
+ const make = (type, handled, fallback, user) => function starkoRootErrorHandler(error, errorInfo) {
86
+ try {
87
+ const boundary = errorInfo && errorInfo.errorBoundary;
88
+ if (!(boundary && typeof boundary === "object" && boundary[BOUNDARY])) {
89
+ captureReactError(error, stackOf(errorInfo), { type, handled });
90
+ }
91
+ } catch {
92
+ }
93
+ if (user) user(error, errorInfo);
94
+ else fallback(error);
95
+ };
96
+ return {
97
+ onUncaughtError: make("react.onUncaughtError", false, reportGlobal, callbacks.onUncaughtError),
98
+ onCaughtError: make("react.onCaughtError", true, (e) => console.error(e), callbacks.onCaughtError),
99
+ onRecoverableError: make("react.onRecoverableError", true, reportGlobal, callbacks.onRecoverableError)
100
+ };
101
+ }
102
+
103
+ export { StarkoErrorBoundary, reactErrorHandler, withErrorBoundary };