@zerohash-sdk/fund-react 1.2.0

package/README.md

@@ -0,0 +1,147 @@
+# @zerohash-sdk/crypto-sell-react
+
+A React SDK that enables frontend React applications to seamlessly integrate with the Connect Crypto Sell product.
+
+Connect Crypto Sell provides a secure, customizable flow for selling crypto assets directly within your application.
+
+## Requirements
+
+- React 18.0.0 or higher
+- React DOM 18.0.0 or higher
+
+## Installation
+
+```bash
+npm install @zerohash-sdk/crypto-sell-react
+```
+
+## Getting Started
+
+Follow these simple steps to integrate Connect Crypto Sell into your React application:
+
+### 1. Import the CryptoSell Component
+
+```tsx
+import { CryptoSell } from '@zerohash-sdk/crypto-sell-react';
+```
+
+### 2. Add the CryptoSell Component to Your App
+
+```tsx
+function App() {
+  const jwt = 'your-jwt-token'; // Obtain this from your backend
+
+  return (
+    <CryptoSell
+      jwt={jwt}
+      env="prod" // or "cert" for testing
+      theme="auto" // 'auto' (default), 'light', or 'dark'
+    />
+  );
+}
+```
+
+### 3. Configure Event Callbacks (Optional)
+
+Listen to events from the Crypto Sell SDK to handle user interactions:
+
+```tsx
+function App() {
+  const jwt = 'your-jwt-token';
+
+  const handleCompleted = ({ amountSold, assetSymbol }) => {
+    console.log('Sell completed:', amountSold, assetSymbol);
+  };
+
+  const handleError = ({ errorCode, reason }) => {
+    console.log('Crypto sell error:', errorCode, 'Reason:', reason);
+  };
+
+  const handleClose = () => {
+    console.log('Crypto sell widget closed');
+  };
+
+  const handleEvent = ({ type, data }) => {
+    console.log('Crypto sell event:', type, 'Data:', data);
+  };
+
+  const handleLoaded = () => {
+    console.log('Crypto sell widget loaded and ready');
+  };
+
+  return (
+    <CryptoSell
+      jwt={jwt}
+      env="prod"
+      theme="auto"
+      onCompleted={handleCompleted}
+      onError={handleError}
+      onClose={handleClose}
+      onEvent={handleEvent}
+      onLoaded={handleLoaded}
+    />
+  );
+}
+```
+
+## Complete Example
+
+Here's a full example of integrating Connect Crypto Sell into your React application:
+
+```tsx
+import React from 'react';
+import { CryptoSell } from '@zerohash-sdk/crypto-sell-react';
+
+function App() {
+  // JWT token should be obtained from your backend
+  const jwt = 'your-jwt-token';
+
+  return (
+    <div className="App">
+      <h1>My Crypto App</h1>
+
+      <CryptoSell
+        jwt={jwt}
+        env="prod" // 'prod' (default), 'cert', 'dev', or 'local'
+        theme="auto" // 'auto' (default), 'light', or 'dark'
+        onCompleted={({ amountSold, assetSymbol }) => {
+          console.log('Sold:', amountSold, assetSymbol);
+        }}
+        onError={({ errorCode, reason }) => {
+          console.log('Error:', errorCode, 'Reason:', reason);
+        }}
+        onClose={() => {
+          console.log('Crypto sell widget closed');
+        }}
+        onEvent={({ type, data }) => {
+          console.log('Event type:', type, 'Event data:', data);
+        }}
+        onLoaded={() => {
+          console.log('Crypto sell widget loaded and ready');
+        }}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+## API Reference
+
+### CryptoSell Component Props
+
+| Prop          | Type                                    | Required | Default  | Description                                        |
+| ------------- | --------------------------------------- | -------- | -------- | -------------------------------------------------- |
+| `jwt`         | `string`                                | Yes      | -        | JWT token for authentication with Connect          |
+| `env`         | `"prod" \| "cert" \| "dev" \| "local"`  | No       | `"prod"` | Target environment                                 |
+| `theme`       | `"auto" \| "light" \| "dark"`           | No       | `"auto"` | Theme mode for the interface                       |
+| `onCompleted` | `({ amountSold, assetSymbol }) => void` | No       | -        | Callback when the sell flow completes successfully |
+| `onError`     | `({ errorCode, reason }) => void`       | No       | -        | Callback for error events                          |
+| `onClose`     | `() => void`                            | No       | -        | Callback when the widget is closed                 |
+| `onEvent`     | `({ type, data }) => void`              | No       | -        | Callback for general events                        |
+| `onLoaded`    | `() => void`                            | No       | -        | Callback when the widget is loaded and ready       |
+
+## More Information & Support
+
+For comprehensive documentation or support about Connect, visit our [Documentation Page](https://docs.zerohash.com/).

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+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 Connect Fund service.
+ *
+ * - `"local"` - Local development environment (http://localhost:4204)
+ * - `"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;
+};
+
+/**
+ * A React wrapper component for the Connect Fund product.
+ *
+ * @param props - Component properties
+ * @param jwt - JWT token for authentication (required)
+ * @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 sell 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
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with production environment (default)
+ * <Fund jwt="your-jwt-token" />
+ *
+ * // Using cert environment for testing
+ * <Fund jwt="your-jwt-token" env="cert" />
+ *
+ * // Force dark theme
+ * <Fund jwt="your-jwt-token" theme="dark" />
+ *
+ * // With callback functions
+ * <Fund
+ *   jwt="your-jwt-token"
+ *   theme="auto"
+ *   onLoaded={() => console.log('Crypto sell loaded and ready')}
+ *   onCompleted={({ amountSold, assetSymbol }) => console.log('Sold', amountSold, assetSymbol)}
+ *   onClose={() => console.log('Crypto sell closed')}
+ *   onError={({ errorCode, reason }) => console.error('Error:', errorCode, reason)}
+ *   onEvent={(event) => console.log('Event:', event)}
+ * />
+ * ```
+ *
+ * @returns React component that renders the Connect Fund interface
+ */
+export declare const Fund: default_2.FC<FundProps>;
+
+declare type FundCompletedData = {
+    /** Deposit address for the asset */
+    depositAddress?: string;
+    /** Network used for the deposit */
+    network?: string;
+    /** Asset symbol (e.g. 'BTC.BITCOIN') */
+    assetSymbol?: string;
+    /** Amount to be deposited */
+    amount?: string;
+};
+
+/**
+ * Fund event structure
+ */
+declare type FundEvent = AppEvent<FundEventType>;
+
+/**
+ * Fund event type literals
+ */
+declare type FundEventType = string;
+
+declare interface FundProps {
+    /**
+     * JWT token used for authentication with the Connect Fund service.
+     * This token should be obtained from your backend and contain the necessary
+     * claims for user identification and authorization.
+     *
+     * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+     */
+    jwt: string;
+    /**
+     * Target environment for the Connect Fund 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
+     *
+     * @example
+     * ```tsx
+     * // Use production (default)
+     * <Fund jwt={token} />
+     *
+     * // Use cert for testing
+     * <Fund jwt={token} env="cert" />
+     * ```
+     */
+    env?: Environment;
+    /**
+     * Theme mode for the Connect Fund interface.
+     *
+     * @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)
+     * <Fund jwt={token} />
+     *
+     * // Force dark theme
+     * <Fund jwt={token} theme="dark" />
+     * ```
+     */
+    theme?: Theme;
+    /**
+     * Runs the SDK in Pay mode.
+     *
+     * - Uses the `pay-sdk` app id and `app:internal:pay` scope when talking to trade-api.
+     * - Signs the `account_funding_pay` terms agreement.
+     * - Polls deposit status by `transactionId` (single-deposit endpoint) instead of
+     *   by `deposit_address` (list endpoint).
+     *
+     * @default false
+     */
+    isPay?: boolean;
+    /**
+     * Callback invoked when the fund flow is successfully completed.
+     *
+     * @param data - Details about the completed deposit (asset symbol, network, amount, deposit address)
+     *
+     * @example
+     * ```tsx
+     * <Fund
+     *   jwt={token}
+     *   onCompleted={({ assetSymbol, amount }) =>
+     *     console.log(`Deposited ${amount} ${assetSymbol}`)
+     *   }
+     * />
+     * ```
+     */
+    onCompleted?: (data: FundCompletedData) => void;
+    /**
+     * Callback invoked when an error occurs during the fund flow.
+     *
+     * @param error - Error details including error code and reason
+     *
+     * @example
+     * ```tsx
+     * <Fund
+     *   jwt={token}
+     *   onError={({ errorCode, reason }) =>
+     *     console.error('Fund error:', errorCode, reason)
+     *   }
+     * />
+     * ```
+     */
+    onError?: (error: ErrorPayload) => void;
+    /**
+     * Callback invoked when the user closes the crypto sell widget.
+     *
+     * @example
+     * ```tsx
+     * <Fund
+     *   jwt={token}
+     *   onClose={() => setShowFund(false)}
+     * />
+     * ```
+     */
+    onClose?: () => void;
+    /**
+     * Callback invoked when the crypto sell widget has finished loading and is ready.
+     *
+     * @example
+     * ```tsx
+     * <Fund
+     *   jwt={token}
+     *   onLoaded={() => setIsLoading(false)}
+     * />
+     * ```
+     */
+    onLoaded?: () => void;
+    /**
+     * Callback invoked for general application events during the fund flow.
+     *
+     * @param event - Event object containing the event type and associated data
+     *
+     * @example
+     * ```tsx
+     * <Fund
+     *   jwt={token}
+     *   onEvent={(event) => console.log('Crypto sell event:', event)}
+     * />
+     * ```
+     */
+    onEvent?: (event: FundEvent) => void;
+}
+
+/**
+ * Theme mode for the Connect Fund interface.
+ *
+ * - `"auto"` - Automatically detect system preference (light/dark mode)
+ * - `"light"` - Force light theme
+ * - `"dark"` - Force dark theme
+ */
+declare type Theme = 'auto' | 'light' | 'dark';
+
+export { }

package/dist/index.js

@@ -0,0 +1,42 @@
+import x, { useRef as b, useEffect as l } from "react";
+const y = {
+  local: "http://localhost:5173/fund-web/index.js",
+  dev: "https://connect-sdk.dev.0hash.com/fund-web/index.js",
+  cert: "https://sdk.sandbox.connect.xyz/fund-web/index.js",
+  prod: "https://sdk.connect.xyz/fund-web/index.js"
+}, I = "zerohash-fund-script", a = "zerohash-fund", R = (c = "prod") => y[c], w = ({
+  jwt: c,
+  env: r = "prod",
+  theme: h,
+  isPay: n = !1,
+  onCompleted: s,
+  onError: o,
+  onClose: d,
+  onLoaded: i,
+  onEvent: f,
+  ...m
+}) => {
+  const u = b(null);
+  return l(() => {
+    const t = u.current;
+    t && (s && (t.onCompleted = s), o && (t.onError = o), d && (t.onClose = d), i && (t.onLoaded = i), f && (t.onEvent = f), t.isPay = n);
+  }, [s, o, d, i, f, n]), l(() => {
+    const t = R(r), p = `${I}-${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]), x.createElement(a, {
+    ref: u,
+    jwt: c,
+    env: r,
+    theme: h,
+    ispay: n ? "true" : void 0,
+    ...m
+  });
+};
+export {
+  w as Fund
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@zerohash-sdk/fund-react",
+  "version": "1.2.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": "fund-react"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}