@connect-xyz/auth-react 0.12.0

package/README.md

@@ -0,0 +1,139 @@
+# @connect-xyz/auth-react
+
+A React SDK that enables frontend React applications to seamlessly integrate with the Connect Auth product.
+
+Connect Auth provides a secure, customizable authentication flow for crypto deposits. Learn more in the [Connect Auth documentation](https://docs.zerohash.com/docs/auth).
+
+## Requirements
+
+- React 18.0.0 or higher
+- React DOM 18.0.0 or higher
+
+## Installation
+
+```bash
+npm install @connect-xyz/auth-react
+```
+
+## Getting Started
+
+Follow these simple steps to integrate Connect Auth into your React application:
+
+### 1. Import the Auth Component
+
+```tsx
+import { Auth } from '@connect-xyz/auth-react';
+```
+
+### 2. Add the Auth Component to Your App
+
+```tsx
+function App() {
+  const jwt = 'your-jwt-token'; // Obtain this from your backend authentication
+
+  return (
+    <Auth
+      jwt={jwt}
+      env="production" // or "sandbox" for testing
+    />
+  );
+}
+```
+
+### 3. Configure Event Callbacks (Optional)
+
+Listen to events from the Auth SDK to handle user interactions:
+
+```tsx
+function App() {
+  const jwt = 'your-jwt-token';
+
+  const handleError = ({ errorCode, reason }) => {
+    console.log('Auth error occurred:', errorCode, 'Reason:', reason);
+  };
+
+  const handleClose = () => {
+    console.log('Auth widget closed');
+  };
+
+  const handleDeposit = ({ data }) => {
+    console.log('Deposit data:', data);
+  };
+
+  const handleEvent = ({ type, data }) => {
+    console.log('Auth event:', type, 'Data:', data);
+  };
+
+  return (
+    <Auth
+      jwt={jwt}
+      env="production"
+      onError={handleError}
+      onClose={handleClose}
+      onDeposit={handleDeposit}
+      onEvent={handleEvent}
+    />
+  );
+}
+```
+
+For detailed information about callback events and their payloads, see the [Auth SDK Callbacks documentation](https://docs.zerohash.com/docs/auth-standalone#4-organization-frontend-listens-to-auth-sdk-callbacks).
+
+## Complete Example
+
+Here's a full example of integrating Connect Auth into your React application:
+
+```tsx
+import React from 'react';
+import { Auth } from '@connect-xyz/auth-react';
+
+function App() {
+  // JWT token should be obtained from your backend
+  const jwt = 'your-jwt-token';
+
+  // Choose environment: "production" for live apps, "sandbox" for testing
+  const environment = 'production';
+
+  return (
+    <div className="App">
+      <h1>My Crypto App</h1>
+
+      <Auth
+        jwt={jwt}
+        env={environment}
+        onError={({ errorCode, reason }) => {
+          console.log('Error:', errorCode, 'Reason:', reason);
+        }}
+        onClose={() => {
+          console.log('Auth widget closed');
+        }}
+        onDeposit={({ data }) => {
+          console.log('Deposit successful:', data);
+        }}
+        onEvent={({ type, data }) => {
+          console.log('Event type:', type, 'Event data:', data);
+        }}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+## API Reference
+
+### Auth Component Props
+
+| Prop        | Type                              | Required | Default        | Description                                    |
+| ----------- | --------------------------------- | -------- | -------------- | ---------------------------------------------- |
+| `jwt`       | `string`                          | Yes      | -              | JWT token for authentication with Connect Auth |
+| `env`       | `"production" \| "sandbox"`       | No       | `"production"` | Target environment                             |
+| `onError`   | `({ errorCode, reason }) => void` | No       | -              | Callback for error events                      |
+| `onClose`   | `() => void`                      | No       | -              | Callback when the widget is closed             |
+| `onDeposit` | `({ data }) => void`              | No       | -              | Callback for deposit received                  |
+| `onEvent`   | `({ type, data }) => void`        | No       | -              | Callback for general events                    |
+
+## More Information & Support
+
+For comprehensive documentation or support about Connect Auth, visit our [ Documentation Page](https://docs.zerohash.com/).

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+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;
+};
+
+/**
+ * A React wrapper component for the Connect Auth product.
+ *
+ * @param props - Component properties
+ * @param jwt - JWT token for authentication (required)
+ * @param env - Target environment ("sandbox" | "production", defaults to "production")
+ * @param onError - Callback function for error handling
+ * @param onClose - Callback function for close events
+ * @param onDeposit - Callback function for deposit events
+ * @param onEvent - Callback function for general events
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with production environment (default)
+ * <Auth jwt="your-jwt-token" />
+ *
+ * // Using sandbox environment for testing
+ * <Auth jwt="your-jwt-token" env="sandbox" />
+ *
+ * // With callback functions
+ * <Auth
+ *   jwt="your-jwt-token"
+ *   onError={({ errorCode, reason }) => console.error('Auth error:', errorCode, 'Reason:', reason)}
+ *   onClose={() => console.log('Auth closed')}
+ *   onDeposit={({ data }) => console.log('Deposit completed:', data.depositId, 'Status:', data.status.value)}
+ *   onEvent={({ type, data }) => console.log('Event:', type, 'Deposit ID:', data.depositId)}
+ * />
+ * ```
+ *
+ * @returns React component that renders the Connect Auth interface
+ */
+export declare const Auth: default_2.FC<AuthWrapperProps>;
+
+/**
+ * Callback function types for Connect Auth components
+ * Extends common callbacks with auth-specific callbacks
+ */
+declare type AuthCallbacks = CommonCallbacks<AuthEvent> & {
+    /** Called when a deposit action occurs */
+    onDeposit?: (deposit: DepositCompletedPayload) => void;
+};
+
+/**
+ * Auth event structure for auth-specific events
+ */
+declare type AuthEvent = AppEvent<AuthEventType, DepositSubmittedEventData>;
+
+/**
+ * Auth event type literals
+ */
+declare type AuthEventType = 'deposit.submitted';
+
+/**
+ * Props for the Auth component
+ */
+declare interface AuthWrapperProps extends AuthCallbacks {
+    /**
+     * JWT token used for authentication with the Connect Auth service.
+     * This token should be obtained from your authentication system and
+     * contain the necessary claims for user identification and authorization.
+     *
+     * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+     */
+    jwt: string;
+    /**
+     * Target environment for the Connect Auth service.
+     *
+     * @default "production"
+     *
+     * Available environments:
+     * - `"sandbox"` - Certificate/testing environment for integration testing
+     * - `"production"` - Live production environment for real applications
+     *
+     * @example
+     * ```tsx
+     * // Use production (default)
+     * <Auth jwt={token} />
+     *
+     * // Use sandbox for testing
+     * <Auth jwt={token} env="sandbox" />
+     * ```
+     */
+    env?: Environment;
+}
+
+/**
+ * Common callback function types shared across all Connect apps
+ * @template TEvent - The event type for onEvent callback
+ */
+declare type CommonCallbacks<TEvent = AppEvent> = {
+    /** Called when an error occurs */
+    onError?: (error: ErrorPayload) => void;
+    /** Called when the component is closed */
+    onClose?: () => void;
+    /** Called when a general event occurs */
+    onEvent?: (event: TEvent) => void;
+};
+
+/**
+ * Deposit completed payload structure for deposit callbacks
+ */
+declare type DepositCompletedPayload = {
+    /** Data associated with the deposit */
+    data: {
+        /** Unique identifier for the deposit */
+        depositId: string;
+        /** Current status of the deposit */
+        status: DepositStatus;
+        /** Asset identifier (e.g., 'btc', 'eth') */
+        assetId: string;
+        /** Network identifier (e.g., 'bitcoin', 'ethereum') */
+        networkId: string;
+        /** Amount being deposited */
+        amount: string;
+    };
+};
+
+/**
+ * Deposit status object structure
+ */
+declare type DepositStatus = {
+    /** Status value */
+    value: string;
+    /** Human-readable details about the status */
+    details: string;
+    /** Timestamp when the status occurred (ISO 8601 format) */
+    occurredAt: string;
+};
+
+/**
+ * Deposit submitted event data
+ */
+declare type DepositSubmittedEventData = {
+    /** Unique identifier for the deposit */
+    depositId: string;
+};
+
+/**
+ * Available environments for the Connect Auth service.
+ *
+ * - `"sandbox"` - Certificate/testing environment for integration and testing
+ * - `"production"` - Live production environment for real applications
+ */
+declare type Environment = 'sandbox' | 'production';
+
+/**
+ * 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;
+};
+
+export { }

package/dist/index.js

@@ -0,0 +1,35 @@
+import l, { useRef as m, useEffect as p } from "react";
+const h = {
+  sandbox: "https://sdk.sandbox.connect.xyz/auth-web/index.js",
+  production: "https://sdk.connect.xyz/auth-web/index.js"
+}, x = "connect-auth-script", a = "connect-auth", y = (n = "production") => h[n], R = ({
+  jwt: n,
+  env: c = "production",
+  onError: r,
+  onClose: o,
+  onDeposit: s,
+  onEvent: i,
+  ...f
+}) => {
+  const d = m(null);
+  return p(() => {
+    const t = d.current;
+    t && (r && (t.onError = r), o && (t.onClose = o), s && (t.onDeposit = s), i && (t.onEvent = i));
+  }, [r, o, s, i]), p(() => {
+    const t = y(c), u = `${x}-${c}`;
+    if (document.getElementById(u))
+      return;
+    const e = document.createElement("script");
+    e.id = u, e.src = t, e.type = "module", e.async = !0, e.onerror = () => {
+      console.error(`Failed to load the script for ${a} from ${c} environment.`);
+    }, document.head.appendChild(e);
+  }, [c]), l.createElement(a, {
+    ref: d,
+    jwt: n,
+    env: c,
+    ...f
+  });
+};
+export {
+  R as Auth
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@connect-xyz/auth-react",
+  "version": "0.12.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "nx": {
+    "name": "auth-react"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}