heraldex-onramp-sdk 2.0.0

package/Readme.md

@@ -0,0 +1,123 @@
+# Herald Exchange Onramp SDK Widget
+
+Herald Exchange Onramp SDK Widget is a simple component for React applications.
+
+## Installation
+
+You can install Herald Exchange Onramp SDK Widget via npm:
+
+```bash
+npm install herald-exchange-onramp-widget
+# or
+yarn add herald-exchange-onramp-widget
+```
+
+## Usage
+
+To use widget in your React application, follow these steps:
+
+```tsx
+import { BuyCryptoWidget } from "herald-exchange-onramp-widget";
+```
+
+Initialize the widget:
+
+> To Generate API Key Please Visit : [Herald Exchange](https://app.herald.exchange/login).  
+> Supported Token Types : ["USDT", "USDC", "ETH", "BNB", "MATIC", "SOL", "TRX"]
+
+```tsx
+<BuyCryptoWidget
+  clientReferenceID={YOUR_CLIENT_REFERENCE_ID}
+  apiKey={YOUR_API_KEY}
+  redirectUrl={REDIRECT_URL}
+  buyParameters={{ from_amount: "25", token_type: "TRX" }}
+/>
+```
+
+> **Note:**
+>
+> - In development mode, the widget operates on **testnet** and runs in a sandbox environment.
+> - Transactions are simulated based on the fromAmount value:
+>   - 100 → Success
+>   - 200 → Failure
+>   - Any other value → Initiated
+> - ⚠️ Ensure your application is deployed in a **production environment** when going live to enable accurate transaction tracking and wallet interactions.
+
+## 🔧 Props
+
+### `apiKey` (required)
+
+- **Type**: `string`
+
+- **Description**: A unique API key generated via the [Herald Exchange App](https://app.herald.exchange/login).
+
+- This key is used to authenticate and authorize the widget.
+
+- Example: `4bb06e2fdbfb8e392a0ab49e4d9819ae072dcef82d79af7893625a5ff1416f`
+
+---
+
+### `mode` (optional)
+
+- Type: string
+
+- Allowed Values: "development" | "production"
+
+- Default: "development"
+
+- Description: Specifies the environment in which the widget runs.
+
+  - "development" is used for testing and debugging purposes.
+
+  - "production" should be used in live environments for optimized performance.
+
+---
+
+### `clientReferenceID` (required)
+
+- **Type**: `string`
+
+- **Description**: A unique identifier (UUID) generated via the [Herald Exchange App](https://app.herald.exchange/login), used to associate a transaction with a specific user or session.
+
+- Helps track user activity and transaction flow.
+
+- Example: `34edd6d6-eb12-422f-bd0e-63c5733527`
+
+---
+
+### `redirectUrl` (optional)
+
+- **Type**: `string`
+
+- **Description**: The URL to which the user will be redirected **after completing the transaction**.
+
+- A **callback** will be made to this URL along with the **transaction result or status** as query parameters or payload (depending on the integration).
+
+- Example: `https://yourapp.com/transaction-complete`
+
+---
+
+### `buyParameters` (required)
+
+- **Type**:
+
+```ts
+{
+  from_amount: string;
+  token_type: string;
+}
+```
+
+- **Description**: Defines the default configuration for the buy flow.
+
+  - from_amount: A string representing the default amount to be displayed in the input field (e.g., "25").
+
+  - token_type: The token that should be selected by default for purchase (e.g., "USDC").
+
+⚠️ If the passed token_type is not active, the widget will automatically fall back to the first activated token.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type BuyParamsType = {
+    from_amount?: string;
+    token_type?: string;
+};
+type CallBackResponse = {
+    status: "success" | "failed";
+    message: string;
+    data: {
+        transaction_id: string | number;
+        from_currency: string;
+        to_currency: string;
+        network_type?: string;
+        from_value: string | number;
+        to_value: number | string;
+        explorer_url?: string;
+        wallet_address?: string;
+        exchange_rate: number | string;
+        transaction_hash?: string;
+    };
+};
+
+type WidgetComponentProps = {
+    apiKey: string;
+    buyParameters?: BuyParamsType;
+    clientReferenceID: string;
+    mode?: "development" | "production";
+    callback: (data: CallBackResponse) => void;
+    redirect?: boolean;
+    redirectUrl?: string;
+};
+declare const WidgetComponent: ({ apiKey, redirectUrl, buyParameters, clientReferenceID, mode, callback, redirect, }: WidgetComponentProps) => react_jsx_runtime.JSX.Element;
+
+export { WidgetComponent as BuyCryptoWidget };