zigap-utils 2.0.3 → 2.0.5

package/README.md

@@ -1,276 +1,408 @@
 # zigap-utils
 
-It is a library that collects utils that help communicate between dapp and zigap.<br /> You can find out more at https://seoul-labs.gitbook.io/zigap-utils
+<div align="center">
 
-<br />
-<br />
+![Zigap Utils](https://img.shields.io/badge/zigap--utils-v1.0.0-blue?style=for-the-badge) ![License](https://img.shields.io/badge/license-ISC-green?style=for-the-badge) ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
 
-## Installation
+**A utility library that helps communicate between dapp and zigap**
 
+[📖 Documentation](https://seoul-labs.gitbook.io/zigap-utils) • [🚀 Installation](#installation) • [💡 Usage](#usage)
+
+</div>
+
+---
+
+## 📦 Installation
+
+```bash
+npm install zigap-utils
 ```
-npm i zigap-utils
+
+```bash
+yarn add zigap-utils
+```
+
+```bash
+pnpm add zigap-utils
 ```
 
-<br />
-<br />
+---
 
-## Usage
+## 🚀 Usage
 
-> \_ INDEX
->
-> 1. <b>Login</b>
-> 2. <b>Signature</b>
-> 3. <b>SendTransaction</b>
-> 4. <b>useZigap Hook</b>
+zigap-utils provides React components for seamless communication between dapp and zigap app.
 
-### 1. Login
+### 📋 Table of Contents
 
-```ts
-import { LoginQR } from 'zigap-utils';
-import type { LoginResultType } from 'zigap-utils/LoginQR/LoginQR.types'
+- [🔐 LoginQR](#-loginqr)
+- [✍️ SignatureQR](#️-signatureqr)
+- [💸 SendTransactionQR](#-sendtransactionqr)
+
+---
+
+## 🔐 LoginQR
+
+QR code component for user wallet login.
+
+### Basic Usage
+
+```tsx
+import { LoginQR, LoginResultType } from 'zigap-utils';
 
 const App = () => {
   const [result, setResult] = useState<LoginResultType | null>(null);
-  ...
 
   return (
     <div>
       <LoginQR
-        dapp='your Dapp Name'
-        url='http://sample.yours.com'
-        availableNetworks={['v2xphere, v3xphere']}
-        isShowLogo={false}
-        logoSize={25}
+        dapp='My Awesome Dapp'
+        url='https://myapp.com'
+        availableNetworks={['v2xphere', 'v3xphere']}
+        sigMessage='Welcome to My Dapp!'
         validSeconds={600}
-        sigMessage="hello world"
-        expire={{ type: 'EXTEND', seconds: 3600 }}
-        icon="http://sample.icon-url.com"
         onReceive={({ status, result }) => {
-          if(status === 'SUCCESS') {
-            // something to do after login (refresh page...)
-            // status type: 'REQUEST' | 'ACCOUNT' | 'SUCCESS' | 'ERROR'
-            // you can use result when status is 'SUCCESS'
+          if (status === 'SUCCESS') {
+            console.log('Login successful!', result);
             setResult(result as LoginResultType);
           }
         }}
       />
     </div>
   );
+};
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `dapp` | `string` | ✅ | - | dapp name |
+| `url` | `string` | ✅ | - | dapp URL |
+| `availableNetworks` | `('binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere')[]` | ✅ | - | supported networks |
+| `sigMessage` | `string` | ✅ | - | signature message |
+| `validSeconds` | `number` | ✅ | - | QR code valid time |
+| `onReceive` | `(res) => void` | ❌ | - | login result callback |
+| `expire` | `LoginExpireType` | ❌ | `{ type : 'NONE'}` | expiration settings |
+| `icon` | `string` | ❌ | - | dapp icon URL |
+| `processingMark` | `ProcessingMarkType` | ❌ | `{ type: 'DEFAULT' }` | processing display |
+| `qrDomain` | `string` | ❌ | `https://zigap.io` | QR domain |
+
+### Supported Networks
+
+- `'binance'` (bsc)
+- `'ethereum'` (eth)
+- `'v2xphere'` (xp)
+- `'v3xphere'` (xpt)
+
+### Status Values
+
+- `'SUCCESS'` - Login successful
+- `'REQUEST'` - Request in progress
+- `'ACCOUNT'` - Account selection in progress
+- `'ERROR'` - Error occurred
+
+### LoginResultType
+
+```tsx
+interface LoginResultType {
+  address: string;
+  network: string;
+  nickName: string;
+  token: string;
+  issuedDateTime: string;
+  expire: LoginExpireType;
+  isVerified: boolean;
 }
 ```
 
-<br />
+---
+
+## ✍️ SignatureQR
+
+QR code component for message signing.
 
-### 2. SignatureQR
+### Basic Usage
 
-```ts
-import { SignatureQR } from 'zigap-utils';
-import type { SignatureResultType } from 'zigap-utils/SignatureQR/SignatureQR.types'
+```tsx
+import { SignatureQR, SignatureResultType } from 'zigap-utils';
 
 const App = () => {
   const [result, setResult] = useState<SignatureResultType | null>(null);
 
-  ...
-
   return (
     <div>
       <SignatureQR
-        dapp='your Dapp Name'
-        url='http://sample.yours.com'
-        availableNetworks={['v2xphere, v3xphere']}
-        isShowLogo={false}
-        logoSize={25}
+        dapp='My Awesome Dapp'
+        url='https://myapp.com'
+        availableNetworks={['v2xphere', 'v3xphere']}
+        sigMessage='I agree to the terms and conditions'
         validSeconds={600}
-        sigMessage="hello world"
-        expire={{ type: 'EXTEND', seconds: 3600 }}
-        icon="http://sample.icon-url.com"
         onReceive={({ status, result }) => {
-          if(status === 'SUCCESS') {
-            // it is same with LoginQR. But you can see another type in zigap signature history.
-            // status type: 'REQUEST' | 'ACCOUNT' | 'SUCCESS' | 'ERROR'
-            // you can use result when status is 'SUCCESS'
+          if (status === 'SUCCESS') {
+            console.log('Signature successful!', result);
             setResult(result as SignatureResultType);
           }
         }}
       />
-    <div>
-  )
+    </div>
+  );
+};
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `dapp` | `string` | ✅ | - | dapp name |
+| `url` | `string` | ✅ | - | dapp URL |
+| `availableNetworks` | `('binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere')[]` | ✅ | - | supported networks |
+| `sigMessage` | `string` | ✅ | - | message to sign |
+| `validSeconds` | `number` | ✅ | - | QR code valid time |
+| `onReceive` | `(res) => void` | ❌ | - | signature result callback |
+| `expire` | `SignatureLoginExpireType` | ❌ | `{ type : 'NONE'}` | expiration settings |
+| `icon` | `string` | ❌ | - | dapp icon URL |
+| `processingMark` | `SignatureProcessingMarkType` | ❌ | `{ type: 'DEFAULT' }` | processing display |
+| `qrDomain` | `string` | ❌ | `https://zigap.io` | QR domain |
+
+### Supported Networks
+
+- `'binance'` (bsc)
+- `'ethereum'` (eth)
+- `'v2xphere'` (xp)
+- `'v3xphere'` (xpt)
+
+### Status Values
+
+- `'SUCCESS'` - Signature successful
+- `'REQUEST'` - Request in progress
+- `'ACCOUNT'` - Account selection in progress
+- `'ERROR'` - Error occurred
+
+### SignatureResultType
+
+```tsx
+interface SignatureResultType {
+  address: string;
+  network: string;
+  nickName: string;
+  token: string;
+  issuedDateTime: string;
+  expire: SignatureLoginExpireType;
+  isVerified: boolean;
 }
 ```
 
-<br />
+---
+
+## 💸 SendTransactionQR
 
-### 3. SendTransactionQR
+QR code component for transaction sending.
 
-```ts
-import { SendTransactionQR } from 'zigap-utils';
-import type { SendTransactionResultType } from 'zigap-utils/SendTransactionQR/SendTransactionQR.types'
+### Basic Usage
+
+```tsx
+import { SendTransactionQR, SendTransactionResultType } from 'zigap-utils';
 
 const App = () => {
   const [result, setResult] = useState<SendTransactionResultType | null>(null);
 
-  ...
-
   return (
     <div>
       <SendTransactionQR
-        dapp='your Dapp Name'
-        url='http://sample.yours.com'
-        availableNetworks={'v2xphere'} // It is string not array
-        isShowLogo={false}
-        logoSize={25}
+        dapp='My Awesome Dapp'
+        url='https://myapp.com'
+        availableNetworks='v2xphere'
         validSeconds={600}
-        sigMessage="hello world"
-        expire={{ type: 'EXTEND', seconds: 3600 }}
-        icon="http://sample.icon-url.com"
         transaction={{
           type: 0,
           to: '0x1234567890123456789012345678901234567890',
-          value: '1000000000000000000',
+          value: '1000000000000000000', // 1 XP
           gasLimit: '21000',
           gasPrice: '1000000000',
         }}
         onReceive={({ status, result }) => {
-          if(status === 'SUCCESS') {
-            // status type: 'REQUEST' | 'ACCOUNT' | 'SUCCESS' | 'ERROR'
-            // you can use result when status is 'SUCCESS'
+          if (status === 'SUCCESS') {
+            console.log('Transaction Complete!', result);
             setResult(result as SendTransactionResultType);
           }
         }}
       />
-    <div>
-  )
-}
+    </div>
+  );
+};
 ```
 
-<br />
-
-### 4. useZigap Hook
+### Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `dapp` | `string` | ✅ | - | dapp name |
+| `url` | `string` | ✅ | - | dapp URL |
+| `availableNetworks` | `'binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere'` | ✅ | - | supported network (single value) |
+| `validSeconds` | `number` | ✅ | - | QR code valid time |
+| `transaction` | `TransactionType` | ✅ | - | transaction configuration |
+| `onReceive` | `(res) => void` | ❌ | - | transaction result callback |
+| `icon` | `string` | ❌ | - | dapp icon URL |
+| `processingMark` | `ProcessingMarkType` | ❌ | `{ type: 'DEFAULT' }` | processing display |
+| `qrDomain` | `string` | ❌ | `https://zigap.io` | QR domain |
+
+### Supported Networks
+
+- `'binance'` (bsc)
+- `'ethereum'` (eth)
+- `'v2xphere'` (xp)
+- `'v3xphere'` (xpt)
+
+### TransactionType
+
+```tsx
+// Type 0: Legacy (pre-EIP-2718)
+interface TransactionType0 {
+  type: 0 | '0x0';
+  to: string;
+  data?: string;
+  value: string;
+  gasLimit: string;
+  gasPrice: string;
+  chainId?: number;
+}
 
-useZigap is a hook that fetches the information of the logged-in user in the zigap app and provides a logout function.
+// Type 1: EIP-2930 (access list)
+interface TransactionType1 {
+  type: 1 | '0x1';
+  to: string;
+  data?: string;
+  value: string;
+  gasLimit: string;
+  gasPrice: string;
+  accessList?: AccessList;
+  chainId?: number;
+}
 
-```ts
-import { useZigap } from 'zigap-utils';
+// Type 2: EIP-1559 (dynamic fees)
+interface TransactionType2 {
+  type: 2 | '0x2';
+  to: string;
+  data?: string;
+  value: string;
+  gasLimit: string;
+  maxFeePerGas: string;
+  maxPriorityFeePerGas: string;
+  chainId?: number;
+}
 
-const Component = () => {
-  const { userInfo, logout, isWindowLoaded } = useZigap();
+type TransactionType = TransactionType0 | TransactionType1 | TransactionType2;
+```
 
-  const handleLogout = () => {
-    if(isWindowLoaded) {
-      logout();
-      window.location.reload();
-    }
-  }
+### SendTransactionResultType
 
-  return (
-    <div>
-      <p>Address: {userInfo.address}</p>
-      <p>Network: {userInfo.network}</p>
-      <p>Nickname: {userInfo.nickName}</p>
-      <p>Token: {userInfo.token}</p>
-      <p>Issued DateTime: {userInfo.issuedDateTime}</p>
-      <p>Expire DateTime: {userInfo.expireDateTime}</p>
-
-      <button onClick={handleLogout}> LOGOUT </button>
-    </div>
-  );
+```tsx
+interface SendTransactionResultType {
+  txHash: string;
+  status: 0 | 1; // 0 : fail , 1 : success
+  error: string;
 }
 ```
 
-<br />
+### Status Values
+
+- `'SUCCESS'` - Transaction successful
+- `'REQUEST'` - Request in progress
+- `'ERROR'` - Error occurred
 
 ---
 
-<br />
-
-### `LoginQR` props
-
-| prop | type | description |
-| --- | --- | --- |
-| `dapp` | string | Name of the dapp to use |
-| `url` | string | The url of dapp to connect |
-| `availableNetworks` | string[] | 'binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere' |
-| `sigMessage` | string | Messages signed to verify the identity of the user |
-| `validSeconds` | number | QR code valid time(seconds) |
-| `onReceive` | (res) => void | Function called after login request |
-| `expire` | {type: "NONE / FIX / EXTEND", seconds: number} | time and type for user login to expire |
-| `icon` | string | Your dapp icon url to be displayed on zigap app |
-| `processingMark` | {type: "DEFAULT" / "CUSTOM" / "NONE", component: React.ReactNode} | How to show the QR image when it's being processed |
-
-<br>
-
-### `SignatureQR` props
-
-| prop | type | description |
-| --- | --- | --- |
-| `dapp` | string | Name of the dapp to use |
-| `url` | string | The url of dapp to connect |
-| `availableNetworks` | string[] | 'binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere' |
-| `sigMessage` | string | Messages signed to verify the identity of the user |
-| `validSeconds` | number | QR code valid time(seconds) |
-| `onReceive` | (res) => void | Function called after signature request |
-| `expire` | {type: "NONE / FIX / EXTEND", seconds: number} | time and type for signature to expire |
-| `icon` | string | Your dapp icon url to be displayed on zigap app |
-| `processingMark` | {type: "DEFAULT" / "CUSTOM" / "NONE", component: React.ReactNode} | How to show the QR image when it's being processed |
-
-<br>
-
-### `SendTransactionQR` props
-
-| prop | type | description |
-| --- | --- | --- |
-| `dapp` | string | Name of the dapp to use |
-| `url` | string | The url of dapp to connect |
-| `availableNetworks` | string | 'binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere' |
-| `validSeconds` | number | QR code valid time(seconds) |
-| `onReceive` | (res) => void | Function called after transaction request |
-| `expire` | {type: "NONE / FIX / EXTEND", seconds: number} | time and type for transaction to expire |
-| `icon` | string | Your dapp icon url to be displayed on zigap app |
-| `transaction` | object | Transaction details (type, to, value, gasLimit, gasPrice) |
-| `processingMark` | {type: "DEFAULT" / "CUSTOM" / "NONE", component: React.ReactNode} | How to show the QR image when it's being processed |
-
-<br>
-
-The `onReceive` callback provides the following statuses:
-
-- `SUCCESS` : process was successful.
-- `REQUEST` : process has been requested and is in progress.
-- `ACCOUNT` : Account selection or preparation is in progress.
-- `ERROR` : An error occurred during payment.
-
-#### Processing Mark Options
-
-- `DEFAULT` : Displays a default "processing..." message during process.
-- `CUSTOM` : Allows you to pass a custom React component to display during processing.
-- `NONE` : No visual indicator is shown during processing.
-
-#### Example Usage of processingMark
-
-To use a custom component:
-
-```js
-  <SendTransactionQR
-   ...
-   processingMark={{
-     type: 'CUSTOM',
-     component: <div>Loading your payment...</div>,
-   }}
- />
+## 🎨 Common Style Props
+
+Common style options available for all QR components.
+
+| Prop         | Type            | Default | Description                  |
+| ------------ | --------------- | ------- | ---------------------------- |
+| `size`       | `number`        | `128`   | QR code canvas size          |
+| `bgColor`    | `string`        | `#fff`  | background color             |
+| `fgColor`    | `string`        | `#000`  | foreground color             |
+| `style`      | `CSSProperties` | -       | custom CSS style             |
+| `isShowLogo` | `boolean`       | `false` | show Zigap logo in QR center |
+| `logoSize`   | `number`        | `30`    | logo size                    |
+
+### Example
+
+```tsx
+<LoginQR
+  // ... other props
+  size={200}
+  bgColor='#ffffff'
+  fgColor='#000000'
+  isShowLogo={true}
+  logoSize={40}
+  style={{ borderRadius: '8px' }}
+/>
 ```
 
-<br>
+---
+
+## ⚙️ Processing Mark Options
+
+Configure how to display during processing.
+
+### Options
+
+- `'DEFAULT'` - Shows default "processing..." message
+- `'CUSTOM'` - Allows custom React component
+- `'NONE'` - No visual indicator
+
+### Custom Component Example
+
+```tsx
+<SendTransactionQR
+  // ... other props
+  processingMark={{
+    type: 'CUSTOM',
+    component: (
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: '8px',
+        }}
+      >
+        <div className='spinner'></div>
+        <span>Processing payment...</span>
+      </div>
+    ),
+  }}
+/>
+```
+
+---
+
+## 📝 Expire Configuration
+
+Configure expiration time and type.
+
+```tsx
+// No expiration
+expire={{ type: 'NONE' }}
+
+// Fixed expiration time
+expire={{ type: 'FIX', seconds: 3600 }}
+
+// Extendable expiration time
+expire={{ type: 'EXTEND', seconds: 3600 }}
+```
+
+---
+
+## 📄 License
+
+ISC License
+
+---
 
-### `CommonStyle` props (optional)
+<div align="center">
 
-| prop         | type          | default value | description                             |
-| ------------ | ------------- | ------------- | --------------------------------------- |
-| `size`       | number        | 128           | canvas width                            |
-| `bgColor`    | string        | #fff          | background color                        |
-| `fgColor`    | string        | #000          | foreground color                        |
-| `style`      | CSSProperties |               | custom css style                        |
-| `isShowLogo` | boolean       | false         | Zigap logo in the middle of the QR code |
-| `logoSize`   | number        | 30            | logo width & height                     |
+**Made with by Seoul Labs**
 
-## License
+[📖 Documentation](https://seoul-labs.gitbook.io/zigap-utils)
 
-ISC
+</div>

package/dist/components/LoginQR/LoginQR.types.d.ts

@@ -45,7 +45,7 @@ export type ProcessingMarkType = {
 };
 export type LoginQRProps = {
     qrDomain?: string;
-    availableNetworks: string[];
+    availableNetworks: ('binance' | 'ethereum' | 'v2xphere' | 'v3xphere')[];
     dapp: string;
     url: string;
     sigMessage: string;

package/dist/components/SendTransactionQR/SendTransactionQR.types.d.ts

@@ -40,7 +40,7 @@ export type AccessList = {
 export type TransactionType = TransactionType0 | TransactionType1 | TransactionType2;
 export type SendTransactionResultType = {
     txHash: string;
-    status: string;
+    status: 0 | 1;
     error: string;
 };
 export type SendTransactionQRProps = {

package/dist/components/SignatureQR/SignatureQR.types.d.ts

@@ -45,7 +45,7 @@ export type SignatureProcessingMarkType = {
 };
 export type SignatureQRProps = {
     qrDomain?: string;
-    availableNetworks: string[];
+    availableNetworks: ('binance' | 'ethereum' | 'v2xphere' | 'v3xphere')[];
     dapp: string;
     url: string;
     sigMessage: string;