@connect-xyz/withdraw-react 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# @connect-xyz/withdraw-react
+
+A React SDK that enables frontend React applications to seamlessly integrate with the Connect Withdraw product.
+
+Connect Withdraw provides a secure way for end users to withdraw their funds. Learn more in the [Connect Withdraw documentation](https://docs.zerohash.com/docs/withdraw).
+
+## Requirements
+
+- React 18.0.0 or higher
+- React DOM 18.0.0 or higher
+
+## Installation
+
+```bash
+npm install @connect-xyz/withdraw-react
+```
+
+## Getting Started
+
+Follow these simple steps to integrate Withdraw into your React application:
+
+### 1. Import the Withdraw Component
+
+```tsx
+import { Withdraw } from '@connect-xyz/withdraw-react';
+```
+
+### 2. Add the Withdraw Component to Your App
+
+```tsx
+function App() {
+  const jwt = 'your-jwt-token'; // Obtain this from your backend authentication
+
+  return (
+    <Withdraw
+      jwt={jwt}
+      env="production" // or "sandbox" for testing
+    />
+  );
+}
+```
+
+### 3. Configure Event Callbacks (Optional)
+
+Listen to events from the Withdraw SDK to handle user interactions:
+
+```tsx
+function App() {
+  const jwt = 'your-jwt-token';
+
+  const handleError = ({ errorCode, reason }) => {
+    console.log('Withdraw error occurred:', errorCode, 'Reason:', reason);
+  };
+
+  const handleClose = () => {
+    console.log('Withdraw widget closed');
+  };
+
+  const handleWithdrawal = ({ data }) => {
+    console.log('Withdrawal data:', data);
+  };
+
+  const handleEvent = ({ type, data }) => {
+    console.log('Withdraw event:', type, 'Data:', data);
+  };
+
+  return (
+    <Withdraw
+      jwt={jwt}
+      env="production"
+      onError={handleError}
+      onClose={handleClose}
+      onWithdrawal={handleWithdrawal}
+      onEvent={handleEvent}
+    />
+  );
+}
+```
+
+For detailed information about callback events and their payloads, see the [Connect SDKs Callbacks documentation](https://docs.zerohash.com/docs/front-end-callbacks).
+
+## Complete Example
+
+Here's a full example of integrating Connect Withdraw into your React application:
+
+```tsx
+import React from 'react';
+import { Withdraw } from '@connect-xyz/withdraw-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>
+
+      <Withdraw
+        jwt={jwt}
+        env={environment}
+        onError={({ errorCode, reason }) => {
+          console.log('Error:', errorCode, 'Reason:', reason);
+        }}
+        onClose={() => {
+          console.log('Withdraw widget closed');
+        }}
+        onWithdrawal={({ data }) => {
+          console.log('Withdrawal successful:', data);
+        }}
+        onEvent={({ type, data }) => {
+          console.log('Event type:', type, 'Event data:', data);
+        }}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+## API Reference
+
+### Withdraw Component Props
+
+| Prop           | Type                              | Required | Default        | Description                                        |
+| -------------- | --------------------------------- | -------- | -------------- | -------------------------------------------------- |
+| `jwt`          | `string`                          | Yes      | -              | JWT token for authentication with Connect Withdraw |
+| `env`          | `"production" \| "sandbox"`       | No       | `"production"` | Target environment                                 |
+| `theme`        | `"auto" \| "light" \| "dark"`     | No       | `"auto"`       | Theme mode for the interface                       |
+| `onError`      | `({ errorCode, reason }) => void` | No       | -              | Callback for error events                          |
+| `onClose`      | `() => void`                      | No       | -              | Callback when the widget is closed                 |
+| `onWithdrawal` | `({ data }) => void`              | No       | -              | Callback for withdrawal completed                  |
+| `onEvent`      | `({ type, data }) => void`        | No       | -              | Callback for general events                        |
+
+## More Information & Support
+
+For comprehensive documentation or support about Connect Withdraw, visit our [Documentation Page](https://docs.zerohash.com/docs/withdraw).

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+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;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * Available environments for the Connect Withdraw 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;
+};
+
+/**
+ * Theme mode for the Connect Withdraw 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 Connect Withdraw product.
+ *
+ * @param props - Component properties
+ * @param jwt - JWT token for authentication (required)
+ * @param env - Target environment ("sandbox" | "production", defaults to "production")
+ * @param theme - Theme mode ("auto" | "light" | "dark", defaults to "auto")
+ * @param onError - Callback function for error handling
+ * @param onClose - Callback function for close events
+ * @param onWithdrawal - Callback function for withdrawal events
+ * @param onEvent - Callback function for general events
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with production environment (default)
+ * <Withdraw jwt="your-jwt-token" />
+ *
+ * // Using sandbox environment for testing
+ * <Withdraw jwt="your-jwt-token" env="sandbox" />
+ *
+ * // Force dark theme
+ * <Withdraw jwt="your-jwt-token" theme="dark" />
+ *
+ * // With callback functions
+ * <Withdraw
+ *   jwt="your-jwt-token"
+ *   theme="auto"
+ *   onError={({ errorCode, reason }) => console.error('Withdraw error:', errorCode, 'Reason:', reason)}
+ *   onClose={() => console.log('Withdraw closed')}
+ *   onWithdrawal={({ data }) => console.log('Withdrawal completed:', data.withdrawalId, 'Status:', data.status.value)}
+ *   onEvent={({ type, data }) => console.log('Event:', type, 'Withdrawal ID:', data.withdrawalId)}
+ * />
+ * ```
+ *
+ * @returns React component that renders the Connect Withdraw interface
+ */
+export declare const Withdraw: default_2.FC<WithdrawWrapperProps>;
+
+declare type WithdrawalCompletedPayload = {
+    /** Data associated with the withdrawal */
+    data: {
+        /** Unique identifier for the withdrawal */
+        withdrawalId: string;
+        /** Current status of the withdrawal */
+        status: WithdrawalStatus;
+        /** Asset identifier (e.g., 'btc', 'eth') */
+        assetId: string;
+        /** Network identifier (e.g., 'bitcoin', 'ethereum') */
+        networkId: string;
+        /** Amount being withdrawn */
+        amount?: string;
+    };
+};
+
+/**
+ * Withdrawal initiated event data
+ */
+declare type WithdrawalInitiatedEventData = {
+    /** Unique identifier for the withdrawal */
+    withdrawalId: string;
+};
+
+declare type WithdrawalStatus = {
+    /** Status value */
+    value: string;
+    /** Human-readable details about the status */
+    details: string;
+    /** Timestamp when the status occurred (ISO 8601 format) */
+    occurredAt: string;
+};
+
+/**
+ * Callback function types for Connect Withdraw components
+ * Extends common callbacks with withdraw-specific callbacks
+ */
+declare type WithdrawCallbacks = CommonCallbacks<WithdrawEvent> & {
+    /** Called when a withdrawal action occurs */
+    onWithdrawal?: (withdrawal: WithdrawalCompletedPayload) => void;
+};
+
+/**
+ * Withdraw event structure
+ */
+declare type WithdrawEvent = AppEvent<WithdrawEventType, WithdrawalInitiatedEventData>;
+
+/**
+ * Withdraw event type literals
+ */
+declare type WithdrawEventType = 'withdrawal.initiated' | 'withdrawal.submitted' | 'withdrawal.completed';
+
+/**
+ * Props for the Withdraw component
+ */
+declare interface WithdrawWrapperProps extends WithdrawCallbacks {
+    /**
+     * JWT token used for authentication with the Connect Withdraw 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.
+     *
+     * @default "production"
+     *
+     * Available environments:
+     * - `"sandbox"` - Certificate/testing environment for integration testing
+     * - `"production"` - Live production environment for real applications
+     *
+     * @example
+     * ```tsx
+     * // Use production (default)
+     * <Withdraw jwt={token} />
+     *
+     * // Use sandbox for testing
+     * <Withdraw jwt={token} env="sandbox" />
+     * ```
+     */
+    env?: Environment;
+    /**
+     * Theme mode.
+     *
+     * @default "auto"
+     *
+     * Available themes:
+     * - `"auto"` - Automatically detect system preference (light/dark mode)
+     * - `"light"` - Force light theme
+     * - `"dark"` - Force dark theme
+     *
+     * @example
+     * ```tsx
+     * // Auto-detect system preference (default)
+     * <Withdraw jwt={token} />
+     *
+     * // Force dark theme
+     * <Withdraw jwt={token} theme="dark" />
+     *
+     * // Force light theme
+     * <Withdraw jwt={token} theme="light" />
+     * ```
+     */
+    theme?: Theme;
+}
+
+export { }

package/dist/index.js

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

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@connect-xyz/withdraw-react",
+  "version": "0.1.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": "withdraw-react"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}