crumbtrail-react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crumbtrail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,226 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CrumbtrailErrorBoundary: () => CrumbtrailErrorBoundary,
+  useBugState: () => useBugState
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/use-bug-state.ts
+var import_react = require("react");
+var REDACTED_VALUE = "[REDACTED]";
+var SENSITIVE_NAME_RE = /(^|[^a-z0-9])(access[-_]?token|api[-_]?key|auth|authorization|bearer|card[-_]?number|client[-_]?secret|cookie|credential(s)?|creds|csrf|cvv|cvc|id[-_]?token|jsessionid|jwt|mfa|otp|pass[-_]?phrase|pass(code|word)?|passwd|password[-_]?confirmation|pin|private[-_]?key|pwd|refresh[-_]?token|secret|security[-_]?code|session|session[-_]?id|sid|ssn|token|verification[-_]?code|xsrf)([^a-z0-9]|$)/i;
+var PII_NAME_RE = /(^|[^a-z0-9])(email|phone|address|dob|birthdate|postal|zip)([^a-z0-9]|$)/i;
+var SENSITIVE_COMPACT_NAMES = /* @__PURE__ */ new Set([
+  "accesskey",
+  "accesstoken",
+  "accesstokens",
+  "apikey",
+  "apikeys",
+  "apisecret",
+  "apisecrets",
+  "auth",
+  "authentication",
+  "authenticationinfo",
+  "authkey",
+  "authtoken",
+  "authorization",
+  "authorizationinfo",
+  "bearer",
+  "cardnumber",
+  "clientsecret",
+  "clientsecrets",
+  "cookie",
+  "credentials",
+  "creds",
+  "csrf",
+  "csrfkey",
+  "csrftoken",
+  "cvc",
+  "cvv",
+  "idtoken",
+  "idtokens",
+  "jsessionid",
+  "jwt",
+  "mfa",
+  "otp",
+  "passcode",
+  "passphrase",
+  "passwd",
+  "password",
+  "passwordconfirmation",
+  "passwords",
+  "pin",
+  "privatekey",
+  "proxyauthentication",
+  "proxyauthenticationinfo",
+  "pwd",
+  "refreshtoken",
+  "refreshtokens",
+  "secret",
+  "secrets",
+  "securitycode",
+  "session",
+  "sessionid",
+  "sessiontoken",
+  "sessiontokens",
+  "sid",
+  "ssn",
+  "token",
+  "tokenkey",
+  "tokens",
+  "verificationcode",
+  "xapikey",
+  "xauthkey",
+  "xauthtoken",
+  "xcsrf",
+  "xcsrfkey",
+  "xcsrftoken",
+  "xsrf",
+  "xsrfkey",
+  "xsrftoken",
+  "xxsrf",
+  "xxsrfkey",
+  "xxsrftoken"
+]);
+var SENSITIVE_COMPACT_SUFFIXES = [
+  "accesstoken",
+  "accesstokens",
+  "apikey",
+  "apikeys",
+  "apisecret",
+  "apisecrets",
+  "authtoken",
+  "clientsecret",
+  "clientsecrets",
+  "csrftoken",
+  "idtoken",
+  "idtokens",
+  "privatekey",
+  "refreshtoken",
+  "refreshtokens",
+  "sessiontoken",
+  "sessiontokens",
+  "xsrftoken"
+];
+var TOKEN_RE = /\b(?:Bearer|Token|Basic)\s+[A-Za-z0-9._~+/=-]{8,}\b|\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b|(?:sk|pk|rk|ghp|gho|ghu|ghs|glpat|xox[baprs])[-_][A-Za-z0-9_.=-]{12,}|\b[A-Fa-f0-9]{32,}\b|\b[A-Za-z0-9_-]{40,}\b/gi;
+var JSON_LIKE_KEY_RE = /["']?([A-Za-z0-9_.-]{1,120})["']?\s*:/g;
+function isSensitiveName(name) {
+  const normalized = name.replace(/([a-z])([A-Z])/g, "$1_$2");
+  const compact = normalized.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return SENSITIVE_NAME_RE.test(name) || PII_NAME_RE.test(name) || SENSITIVE_NAME_RE.test(normalized) || PII_NAME_RE.test(normalized) || SENSITIVE_COMPACT_NAMES.has(compact) || SENSITIVE_COMPACT_SUFFIXES.some(
+    (suffix) => compact.length > suffix.length && compact.endsWith(suffix)
+  );
+}
+function redactJsonLikeString(value) {
+  const trimmed = value.trim();
+  if (!/[{[]/.test(value)) return void 0;
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(value);
+      return JSON.stringify(redactReactSnapshot(parsed));
+    } catch {
+    }
+  }
+  JSON_LIKE_KEY_RE.lastIndex = 0;
+  for (const match of value.matchAll(JSON_LIKE_KEY_RE)) {
+    const key = match[1];
+    if (key && isSensitiveName(key)) return REDACTED_VALUE;
+  }
+  return void 0;
+}
+function redactReactSnapshot(value, keyName) {
+  if (keyName && isSensitiveName(keyName)) return REDACTED_VALUE;
+  if (typeof value === "string") {
+    const jsonLike = redactJsonLikeString(value);
+    if (jsonLike !== void 0) return jsonLike;
+    if (/^\s*[^:=\n\r]{1,120}\s*[:=]/.test(value)) {
+      return value.replace(
+        /^(\s*[^:=\n\r]{1,120}\s*[:=]).*$/s,
+        (_match, key) => {
+          return isSensitiveName(key) ? `${key}${REDACTED_VALUE}` : value.replace(TOKEN_RE, REDACTED_VALUE);
+        }
+      );
+    }
+    return value.replace(TOKEN_RE, REDACTED_VALUE);
+  }
+  if (Array.isArray(value))
+    return value.map((entry) => redactReactSnapshot(entry));
+  if (value && typeof value === "object") {
+    const output = {};
+    for (const [key, entry] of Object.entries(
+      value
+    )) {
+      output[key] = redactReactSnapshot(entry, key);
+    }
+    return output;
+  }
+  return value;
+}
+function useBugState(logger, name, value, options = {}) {
+  const valueRef = (0, import_react.useRef)(value);
+  valueRef.current = value;
+  (0, import_react.useEffect)(() => {
+    if (!logger || typeof logger.registerStateProvider !== "function") return;
+    return logger.registerStateProvider(
+      name,
+      () => options.captureRawState ? valueRef.current : redactReactSnapshot(valueRef.current)
+    );
+  }, [logger, name, options.captureRawState]);
+}
+
+// src/error-boundary.ts
+var import_react2 = require("react");
+var CrumbtrailErrorBoundary = class extends import_react2.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+  static getDerivedStateFromError(_error) {
+    return { hasError: true };
+  }
+  componentDidCatch(error, errorInfo) {
+    this.props.logger.addEvent({
+      type: "err",
+      data: {
+        msg: redactReactSnapshot(error.message),
+        stack: redactReactSnapshot(error.stack),
+        componentStack: redactReactSnapshot(errorInfo.componentStack),
+        source: "react-error-boundary"
+      }
+    });
+  }
+  resetError() {
+    this.setState({ hasError: false });
+  }
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback ?? null;
+    }
+    return this.props.children;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CrumbtrailErrorBoundary,
+  useBugState
+});

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+import { Component, ReactNode, ErrorInfo } from 'react';
+
+interface BugStateLogger {
+    registerStateProvider(name: string, provider: () => unknown): () => void;
+}
+interface UseBugStateOptions {
+    captureRawState?: boolean;
+}
+declare function useBugState(logger: BugStateLogger | null | undefined, name: string, value: unknown, options?: UseBugStateOptions): void;
+
+interface CrumbtrailErrorBoundaryProps {
+    logger: BugStateLogger & {
+        addEvent(partial: {
+            type: string;
+            data: Record<string, unknown>;
+        }): void;
+    };
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+declare class CrumbtrailErrorBoundary extends Component<CrumbtrailErrorBoundaryProps, State> {
+    constructor(props: CrumbtrailErrorBoundaryProps);
+    static getDerivedStateFromError(_error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    resetError(): void;
+    render(): ReactNode;
+}
+
+export { type BugStateLogger, CrumbtrailErrorBoundary, type CrumbtrailErrorBoundaryProps, useBugState };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { Component, ReactNode, ErrorInfo } from 'react';
+
+interface BugStateLogger {
+    registerStateProvider(name: string, provider: () => unknown): () => void;
+}
+interface UseBugStateOptions {
+    captureRawState?: boolean;
+}
+declare function useBugState(logger: BugStateLogger | null | undefined, name: string, value: unknown, options?: UseBugStateOptions): void;
+
+interface CrumbtrailErrorBoundaryProps {
+    logger: BugStateLogger & {
+        addEvent(partial: {
+            type: string;
+            data: Record<string, unknown>;
+        }): void;
+    };
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+declare class CrumbtrailErrorBoundary extends Component<CrumbtrailErrorBoundaryProps, State> {
+    constructor(props: CrumbtrailErrorBoundaryProps);
+    static getDerivedStateFromError(_error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    resetError(): void;
+    render(): ReactNode;
+}
+
+export { type BugStateLogger, CrumbtrailErrorBoundary, type CrumbtrailErrorBoundaryProps, useBugState };

package/dist/index.js

@@ -0,0 +1,198 @@
+// src/use-bug-state.ts
+import { useEffect, useRef } from "react";
+var REDACTED_VALUE = "[REDACTED]";
+var SENSITIVE_NAME_RE = /(^|[^a-z0-9])(access[-_]?token|api[-_]?key|auth|authorization|bearer|card[-_]?number|client[-_]?secret|cookie|credential(s)?|creds|csrf|cvv|cvc|id[-_]?token|jsessionid|jwt|mfa|otp|pass[-_]?phrase|pass(code|word)?|passwd|password[-_]?confirmation|pin|private[-_]?key|pwd|refresh[-_]?token|secret|security[-_]?code|session|session[-_]?id|sid|ssn|token|verification[-_]?code|xsrf)([^a-z0-9]|$)/i;
+var PII_NAME_RE = /(^|[^a-z0-9])(email|phone|address|dob|birthdate|postal|zip)([^a-z0-9]|$)/i;
+var SENSITIVE_COMPACT_NAMES = /* @__PURE__ */ new Set([
+  "accesskey",
+  "accesstoken",
+  "accesstokens",
+  "apikey",
+  "apikeys",
+  "apisecret",
+  "apisecrets",
+  "auth",
+  "authentication",
+  "authenticationinfo",
+  "authkey",
+  "authtoken",
+  "authorization",
+  "authorizationinfo",
+  "bearer",
+  "cardnumber",
+  "clientsecret",
+  "clientsecrets",
+  "cookie",
+  "credentials",
+  "creds",
+  "csrf",
+  "csrfkey",
+  "csrftoken",
+  "cvc",
+  "cvv",
+  "idtoken",
+  "idtokens",
+  "jsessionid",
+  "jwt",
+  "mfa",
+  "otp",
+  "passcode",
+  "passphrase",
+  "passwd",
+  "password",
+  "passwordconfirmation",
+  "passwords",
+  "pin",
+  "privatekey",
+  "proxyauthentication",
+  "proxyauthenticationinfo",
+  "pwd",
+  "refreshtoken",
+  "refreshtokens",
+  "secret",
+  "secrets",
+  "securitycode",
+  "session",
+  "sessionid",
+  "sessiontoken",
+  "sessiontokens",
+  "sid",
+  "ssn",
+  "token",
+  "tokenkey",
+  "tokens",
+  "verificationcode",
+  "xapikey",
+  "xauthkey",
+  "xauthtoken",
+  "xcsrf",
+  "xcsrfkey",
+  "xcsrftoken",
+  "xsrf",
+  "xsrfkey",
+  "xsrftoken",
+  "xxsrf",
+  "xxsrfkey",
+  "xxsrftoken"
+]);
+var SENSITIVE_COMPACT_SUFFIXES = [
+  "accesstoken",
+  "accesstokens",
+  "apikey",
+  "apikeys",
+  "apisecret",
+  "apisecrets",
+  "authtoken",
+  "clientsecret",
+  "clientsecrets",
+  "csrftoken",
+  "idtoken",
+  "idtokens",
+  "privatekey",
+  "refreshtoken",
+  "refreshtokens",
+  "sessiontoken",
+  "sessiontokens",
+  "xsrftoken"
+];
+var TOKEN_RE = /\b(?:Bearer|Token|Basic)\s+[A-Za-z0-9._~+/=-]{8,}\b|\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b|(?:sk|pk|rk|ghp|gho|ghu|ghs|glpat|xox[baprs])[-_][A-Za-z0-9_.=-]{12,}|\b[A-Fa-f0-9]{32,}\b|\b[A-Za-z0-9_-]{40,}\b/gi;
+var JSON_LIKE_KEY_RE = /["']?([A-Za-z0-9_.-]{1,120})["']?\s*:/g;
+function isSensitiveName(name) {
+  const normalized = name.replace(/([a-z])([A-Z])/g, "$1_$2");
+  const compact = normalized.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return SENSITIVE_NAME_RE.test(name) || PII_NAME_RE.test(name) || SENSITIVE_NAME_RE.test(normalized) || PII_NAME_RE.test(normalized) || SENSITIVE_COMPACT_NAMES.has(compact) || SENSITIVE_COMPACT_SUFFIXES.some(
+    (suffix) => compact.length > suffix.length && compact.endsWith(suffix)
+  );
+}
+function redactJsonLikeString(value) {
+  const trimmed = value.trim();
+  if (!/[{[]/.test(value)) return void 0;
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(value);
+      return JSON.stringify(redactReactSnapshot(parsed));
+    } catch {
+    }
+  }
+  JSON_LIKE_KEY_RE.lastIndex = 0;
+  for (const match of value.matchAll(JSON_LIKE_KEY_RE)) {
+    const key = match[1];
+    if (key && isSensitiveName(key)) return REDACTED_VALUE;
+  }
+  return void 0;
+}
+function redactReactSnapshot(value, keyName) {
+  if (keyName && isSensitiveName(keyName)) return REDACTED_VALUE;
+  if (typeof value === "string") {
+    const jsonLike = redactJsonLikeString(value);
+    if (jsonLike !== void 0) return jsonLike;
+    if (/^\s*[^:=\n\r]{1,120}\s*[:=]/.test(value)) {
+      return value.replace(
+        /^(\s*[^:=\n\r]{1,120}\s*[:=]).*$/s,
+        (_match, key) => {
+          return isSensitiveName(key) ? `${key}${REDACTED_VALUE}` : value.replace(TOKEN_RE, REDACTED_VALUE);
+        }
+      );
+    }
+    return value.replace(TOKEN_RE, REDACTED_VALUE);
+  }
+  if (Array.isArray(value))
+    return value.map((entry) => redactReactSnapshot(entry));
+  if (value && typeof value === "object") {
+    const output = {};
+    for (const [key, entry] of Object.entries(
+      value
+    )) {
+      output[key] = redactReactSnapshot(entry, key);
+    }
+    return output;
+  }
+  return value;
+}
+function useBugState(logger, name, value, options = {}) {
+  const valueRef = useRef(value);
+  valueRef.current = value;
+  useEffect(() => {
+    if (!logger || typeof logger.registerStateProvider !== "function") return;
+    return logger.registerStateProvider(
+      name,
+      () => options.captureRawState ? valueRef.current : redactReactSnapshot(valueRef.current)
+    );
+  }, [logger, name, options.captureRawState]);
+}
+
+// src/error-boundary.ts
+import { Component } from "react";
+var CrumbtrailErrorBoundary = class extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+  static getDerivedStateFromError(_error) {
+    return { hasError: true };
+  }
+  componentDidCatch(error, errorInfo) {
+    this.props.logger.addEvent({
+      type: "err",
+      data: {
+        msg: redactReactSnapshot(error.message),
+        stack: redactReactSnapshot(error.stack),
+        componentStack: redactReactSnapshot(errorInfo.componentStack),
+        source: "react-error-boundary"
+      }
+    });
+  }
+  resetError() {
+    this.setState({ hasError: false });
+  }
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback ?? null;
+    }
+    return this.props.children;
+  }
+};
+export {
+  CrumbtrailErrorBoundary,
+  useBugState
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "crumbtrail-react",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "happy-dom": "^17.4.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/crumbtrail-dev/crumbtrail-js/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/crumbtrail-dev/crumbtrail-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crumbtrail-dev/crumbtrail-js.git",
+    "directory": "packages/react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}