@zerohash-sdk/travel-rule-react 0.1.0

package/README.md

@@ -0,0 +1,7 @@
+# @zerohash-sdk/travel-rule-react
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test @zerohash-sdk/travel-rule-react` to execute the unit tests via [Vitest](https://vitest.dev/).

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { default as default_2 } from 'react';
+
+/**
+ * Generic app event structure
+ * @template TType - Event type string
+ * @template TData - Event data payload
+ */
+declare type AppEvent<TType extends string = string, TData = Record<string, unknown>> = {
+    /** The type of event that occurred */
+    type: TType;
+    /** Data associated with the event */
+    data: TData;
+};
+
+/**
+ * Available environments for the Zerohash Travel Rule service.
+ *
+ * - `"local"` - Local development environment (http://localhost:4211)
+ * - `"dev"` - Development environment for early-stage testing
+ * - `"cert"` - Certificate/staging environment for integration testing
+ * - `"prod"` - Live production environment for real applications
+ */
+declare type Environment = 'local' | 'dev' | 'cert' | 'prod';
+
+/**
+ * Generic error codes for all Connect applications
+ */
+declare enum ErrorCode {
+    /** Network connectivity error */
+    NETWORK_ERROR = 'network_error',
+    /** Authentication or session expired error */
+    AUTH_ERROR = 'auth_error',
+    /** Resource not found error */
+    NOT_FOUND_ERROR = 'not_found_error',
+    /** Validation error from user input */
+    VALIDATION_ERROR = 'validation_error',
+    /** Server error (5xx) */
+    SERVER_ERROR = 'server_error',
+    /** Client error (4xx) */
+    CLIENT_ERROR = 'client_error',
+    /** Unknown or unexpected error */
+    UNKNOWN_ERROR = 'unknown_error',
+}
+
+/**
+ * Generic error payload structure for error callbacks
+ */
+declare type ErrorPayload = {
+    /** Error code indicating the type of error */
+    errorCode: ErrorCode;
+    /** Human-readable reason for the error */
+    reason: string;
+};
+
+/**
+ * Theme mode for the Zerohash Travel Rule interface.
+ *
+ * - `"auto"` - Automatically detect system preference (light/dark mode)
+ * - `"light"` - Force light theme
+ * - `"dark"` - Force dark theme
+ */
+declare type Theme = 'auto' | 'light' | 'dark';
+
+/**
+ * A React wrapper component for the Zerohash Travel Rule product.
+ *
+ * @param props - Component properties
+ * @param jwt - JWT token for authentication (required)
+ * @param depositId - Deposit id the submission is tied to (required, TRD §4.1)
+ * @param env - Target environment ("local" | "dev" | "cert" | "prod", defaults to "prod")
+ * @param theme - Theme mode ("auto" | "light" | "dark", defaults to "auto")
+ * @param onCompleted - Callback invoked when the flow is successfully completed
+ * @param onError - Callback invoked when an error occurs
+ * @param onClose - Callback invoked when the user closes the widget
+ * @param onLoaded - Callback invoked when the widget has finished loading
+ * @param onEvent - Callback invoked for general application events
+ *
+ * @returns React component that renders the Zerohash Travel Rule interface
+ */
+export declare const TravelRule: default_2.FC<TravelRuleProps>;
+
+declare type TravelRuleCompletedData = {
+    /** Deposit id the travel-rule submission is tied to */
+    deposit_id: string;
+    /** ISO-8601 timestamp of the travel-rule submission */
+    submitted_at: string;
+};
+
+/**
+ * Travel Rule event structure
+ */
+declare type TravelRuleEvent = AppEvent<TravelRuleEventType>;
+
+/**
+ * Travel Rule event type literals
+ */
+declare type TravelRuleEventType = string;
+
+declare interface TravelRuleProps {
+    /**
+     * JWT token used for authentication with the Zerohash Travel Rule service.
+     * This token should be obtained from your backend and contain the necessary
+     * claims for user identification and authorization.
+     *
+     * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+     */
+    jwt: string;
+    /**
+     * Deposit id the travel-rule submission is tied to. Required — every
+     * travel-rule submission is scoped to a specific deposit (TRD §4.1 host
+     * handoff contract). Init-only: post-mount changes are ignored, matching
+     * the behaviour of `env`.
+     *
+     * @example "deposit-abc123"
+     */
+    depositId: string;
+    /**
+     * Target environment for the Zerohash Travel Rule service.
+     *
+     * @default "prod"
+     *
+     * Available environments:
+     * - `"local"` - Local development environment
+     * - `"dev"` - Development environment
+     * - `"cert"` - Certificate/staging environment for integration testing
+     * - `"prod"` - Live production environment for real applications
+     */
+    env?: Environment;
+    /**
+     * Theme mode for the Zerohash Travel Rule interface.
+     *
+     * @default "auto"
+     *
+     * Available themes:
+     * - `"auto"` - Automatically detect system preference (light/dark mode)
+     * - `"light"` - Force light theme
+     * - `"dark"` - Force dark theme
+     */
+    theme?: Theme;
+    /**
+     * Callback invoked when the travel-rule flow is successfully completed.
+     *
+     * @param data - Details about the completed submission, including deposit_id and submitted_at
+     */
+    onCompleted?: (data: TravelRuleCompletedData) => void;
+    /**
+     * Callback invoked when an error occurs during the travel-rule flow.
+     *
+     * @param error - Error details including error code and reason
+     */
+    onError?: (error: ErrorPayload) => void;
+    /**
+     * Callback invoked when the user closes the travel-rule widget.
+     */
+    onClose?: () => void;
+    /**
+     * Callback invoked when the travel-rule widget has finished loading and is ready.
+     */
+    onLoaded?: () => void;
+    /**
+     * Callback invoked for general application events during the travel-rule flow.
+     *
+     * @param event - Event object containing the event type and associated data
+     */
+    onEvent?: (event: TravelRuleEvent) => void;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,253 @@
+import { jsxs as W, jsx as _ } from "react/jsx-runtime";
+import j, { useEffect as B, useState as z, useCallback as D, useRef as M } from "react";
+const $ = {
+  dev: "https://grafana-faro-collector.dev.0hash.com/collect",
+  cert: "https://grafana-faro-collector.cert.zerohash.com/collect",
+  prod: "https://grafana-faro-collector.zerohash.com/collect",
+  "eu-cert": "https://grafana-faro-collector.cert.zerohash.eu/collect",
+  "eu-prod": "https://grafana-faro-collector.zerohash.eu/collect",
+  sandbox: "https://grafana-faro-collector.cert.zerohash.com/collect",
+  production: "https://grafana-faro-collector.zerohash.com/collect"
+}, V = (e) => {
+  if (!e || typeof e != "string")
+    return null;
+  const t = e.split(".");
+  if (t.length < 2)
+    return null;
+  try {
+    const o = t[1].replace(/-/g, "+").replace(/_/g, "/"), r = o + "===".slice(0, (4 - o.length % 4) % 4), a = typeof atob < "u" ? atob(r) : Buffer.from(r, "base64").toString("utf-8"), c = JSON.parse(a)?.payload?.region;
+    if (typeof c != "string")
+      return null;
+    const n = c.toLowerCase();
+    return n === "us" || n === "eu" ? n : null;
+  } catch {
+    return null;
+  }
+}, U = (e, t) => V(t) !== "eu" ? e : e === "cert" ? "eu-cert" : e === "prod" ? "eu-prod" : e, P = (e) => {
+  if (!e || typeof e != "string")
+    return {};
+  const t = e.split(".");
+  if (t.length < 2)
+    return {};
+  try {
+    const o = t[1].replace(/-/g, "+").replace(/_/g, "/"), r = o + "===".slice(0, (4 - o.length % 4) % 4), a = typeof atob < "u" ? atob(r) : Buffer.from(r, "base64").toString("utf-8"), l = JSON.parse(a), c = l?.payload ?? {}, n = (s) => typeof s == "string" && s.length > 0 ? s : void 0;
+    return {
+      participantCode: n(c.participant_code),
+      platformName: n(c.platform_name),
+      platformCode: n(l.platform_code),
+      region: n(c.region)
+    };
+  } catch {
+    return {};
+  }
+}, L = (e, t, o) => {
+  const r = U(t, o);
+  return e[r] ?? e[t] ?? e.prod;
+}, J = (e, t, o) => {
+  const r = U(t, o);
+  return e[r] ?? e[t];
+}, x = () => {
+}, H = () => {
+  const e = new Uint8Array(8);
+  return globalThis.crypto.getRandomValues(e), Array.from(e, (t) => t.toString(16).padStart(2, "0")).join("");
+}, K = (e, t) => {
+  const o = H(), r = globalThis.__ZH_WEB_SDK_VERSION__, a = {};
+  e.claims.participantCode && (a.participant_code = e.claims.participantCode), e.claims.platformName && (a.platform_name = e.claims.platformName), e.claims.platformCode && (a.platform_code = e.claims.platformCode), e.claims.region && (a.region = e.claims.region), r && (a.zh_web_sdk_version = r);
+  const l = {
+    meta: {
+      app: { name: e.appName, version: t ?? "unknown", environment: e.env },
+      session: { id: o, attributes: a },
+      browser: typeof navigator < "u" ? { userAgent: navigator.userAgent } : void 0,
+      page: typeof window < "u" ? { url: window.location.origin } : void 0
+    },
+    logs: [
+      {
+        message: `Failed to load the script for ${e.webComponentTag} from ${e.env} environment.`,
+        level: "error",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        context: {
+          web_component: e.webComponentTag,
+          script_url: e.scriptUrl,
+          reason: e.reason,
+          tried_fallback: String(e.triedFallback),
+          elapsed_ms: String(e.elapsedMs)
+        }
+      }
+    ]
+  };
+  return { sessionId: o, payload: l };
+}, G = (e, t, o) => {
+  if (!e || typeof fetch > "u")
+    return;
+  const { sessionId: r, payload: a } = K(t, o);
+  try {
+    fetch(e, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-faro-session-id": r },
+      body: JSON.stringify(a),
+      keepalive: !0
+    }).catch(() => {
+    });
+  } catch {
+  }
+}, Z = (e) => {
+  const { webComponentTag: t, appName: o, appVersion: r, scriptUrls: a, fallbackScriptUrls: l, collectorUrls: c, env: n, jwt: s, timeoutMs: m = 15e3, onLoad: g, onError: h } = e;
+  if (typeof document > "u")
+    return x;
+  const d = `${t}-script-${n}`;
+  if (customElements.get(t) || document.getElementById(d))
+    return x;
+  const S = P(s), v = e.report ?? ((p) => G(c && J(c, n, s), p, r));
+  let f = !1, w = 0, C;
+  const R = () => {
+    C !== void 0 && clearTimeout(C);
+  }, k = (p, y, i) => {
+    if (f)
+      return;
+    const I = Math.round(performance.now() - w), N = {
+      webComponentTag: t,
+      appName: o,
+      env: n,
+      scriptUrl: y,
+      reason: p,
+      triedFallback: i,
+      elapsedMs: I,
+      claims: S
+    };
+    v(N);
+    const O = i ? void 0 : L(l ?? {}, n, s);
+    if (O && O !== y) {
+      E(O, !0);
+      return;
+    }
+    f = !0, R(), document.getElementById(d)?.remove(), h?.(N);
+  }, E = (p, y) => {
+    R(), w = performance.now();
+    const i = document.createElement("script");
+    i.id = d, i.src = p, i.type = "module", i.async = !0, i.onload = () => {
+      setTimeout(() => {
+        f || (customElements.get(t) ? (f = !0, R(), g?.()) : k("not-defined", p, y));
+      }, 0);
+    }, i.onerror = () => k("network", p, y), C = setTimeout(() => k("timeout", p, y), m), document.getElementById(d)?.remove(), document.head.appendChild(i);
+  }, T = L(a, n, s);
+  return T ? (E(T, !1), () => {
+    f = !0, R();
+  }) : x;
+}, u = {
+  local: "http://localhost:5173",
+  dev: "https://sdk-cdn.dev.0hash.com",
+  cert: "https://sdk-cdn.cert.zerohash.com",
+  prod: "https://sdk-cdn.zerohash.com",
+  "eu-cert": "https://sdk-cdn.cert.zerohash.eu",
+  "eu-prod": "https://sdk-cdn.zerohash.eu"
+}, q = (e, t, o = {}) => {
+  const { eu: r = !1, legacyAliases: a = !1, local: l = u.local } = o, c = (s) => `${s}/${e}/${t}`, n = {
+    local: c(l),
+    dev: c(u.dev),
+    cert: c(u.cert),
+    prod: c(u.prod)
+  };
+  return a && (n.sandbox = c(u.cert), n.production = c(u.prod)), r && (n["eu-cert"] = c(u["eu-cert"]), n["eu-prod"] = c(u["eu-prod"])), n;
+};
+var F;
+(function(e) {
+  e.NETWORK_ERROR = "network_error", e.AUTH_ERROR = "auth_error", e.NOT_FOUND_ERROR = "not_found_error", e.VALIDATION_ERROR = "validation_error", e.SERVER_ERROR = "server_error", e.CLIENT_ERROR = "client_error", e.UNKNOWN_ERROR = "unknown_error";
+})(F || (F = {}));
+const b = {
+  evergreen: "#00381D",
+  green: "#CCFFD0",
+  offBlack: "#1C1B1C",
+  grayLight: "#EBEBE9"
+}, Q = ({ onRetry: e }) => W("div", { role: "alert", style: {
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  gap: "8px",
+  maxWidth: "360px",
+  margin: "0 auto",
+  padding: "32px 24px",
+  textAlign: "center",
+  fontFamily: "inherit",
+  color: b.offBlack,
+  background: "#FFFFFF",
+  border: `1px solid ${b.grayLight}`,
+  borderRadius: "12px"
+}, children: [_("svg", { width: "32", height: "32", viewBox: "0 0 24 24", fill: "none", "aria-hidden": "true", children: _("path", { d: "M12 9v4m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z", stroke: b.evergreen, strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }), _("p", { style: { margin: 0, fontSize: "16px", fontWeight: 600 }, children: "Something went wrong" }), _("p", { style: { margin: 0, fontSize: "14px", opacity: 0.75 }, children: "We couldn't load this content. Please check your internet connection and try again." }), _("button", { type: "button", onClick: e, style: {
+  marginTop: "8px",
+  padding: "8px 20px",
+  fontSize: "14px",
+  fontWeight: 600,
+  fontFamily: "inherit",
+  color: b.green,
+  background: b.evergreen,
+  border: "none",
+  borderRadius: "8px",
+  cursor: "pointer"
+}, children: "Try again" })] }), X = (e, t) => {
+  B(() => {
+    const o = e.current;
+    if (o)
+      for (const [r, a] of Object.entries(t))
+        a !== void 0 && (o[r] = a);
+  });
+}, Y = (e) => {
+  const { webComponentTag: t, appName: o, appVersion: r, scriptUrls: a, fallbackScriptUrls: l, collectorUrls: c, env: n, jwt: s, timeoutMs: m } = e, [g, h] = z(!1), [d, S] = z(0);
+  B(() => (h(!1), Z({
+    webComponentTag: t,
+    appName: o ?? t,
+    appVersion: r,
+    scriptUrls: a,
+    fallbackScriptUrls: l,
+    collectorUrls: c ?? $,
+    env: n,
+    jwt: s,
+    timeoutMs: m,
+    onError: () => h(!0)
+  })), [
+    t,
+    o,
+    r,
+    a,
+    l,
+    c,
+    n,
+    s,
+    m,
+    d
+  ]);
+  const v = D(() => S((f) => f + 1), []);
+  return { loadFailed: g, retry: v };
+}, ee = q("travel-rule-web", "index.js", { eu: !0 }), A = "zerohash-travel-rule", re = ({
+  jwt: e,
+  depositId: t,
+  env: o = "prod",
+  theme: r,
+  onCompleted: a,
+  onError: l,
+  onClose: c,
+  onLoaded: n,
+  onEvent: s,
+  ...m
+}) => {
+  const g = M(null);
+  X(g, { theme: r, depositId: t, onCompleted: a, onError: l, onClose: c, onLoaded: n, onEvent: s });
+  const { loadFailed: h, retry: d } = Y({
+    webComponentTag: A,
+    scriptUrls: ee,
+    env: o,
+    jwt: e
+  });
+  return h ? /* @__PURE__ */ _(Q, { onRetry: d }) : j.createElement(A, {
+    ref: g,
+    jwt: e,
+    env: o,
+    theme: r,
+    // Also mirror the kebab-case attribute so pre-mount seeding works even
+    // if the browser upgrades the element before the property setter runs.
+    "deposit-id": t,
+    ...m
+  });
+};
+export {
+  re as TravelRule
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@zerohash-sdk/travel-rule-react",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "nx": {
+    "name": "travel-rule-react"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}