swype-sdk/README.md

Official SDK for integrating Swype payment and credit services

# Swype SDK

A React SDK for seamless KYC, card activation, and credit management flows. Integrate Swype's widgets, hooks, and utilities into your app with minimal setup.

---

## 1. SDK Initialization & Authentication

To use the SDK, you must initialize it **after authenticating the user** with an EIP-712 signature. The authentication is valid for 1 hour; after that, a new signature is required.

**Requirements:**

- User's EOA address (wallet)
- EIP-712 signature (generated via wallet)
- API key (from Swype)
- Deadline (timestamp, 1 hour in the future)

**Example (React, using wagmi):**

```tsx
import { useAccount, useSignTypedData } from "wagmi";
import { initializeSwypeSDK, generateAuthSign } from "swype-sdk";

const { address } = useAccount();
const { signTypedDataAsync } = useSignTypedData();

async function authenticateAndInit() {
  // 1. Generate EIP-712 signature
  const { signature, deadline } = await generateAuthSign(
    address,
    signTypedDataAsync
  );

  // 2. Initialize SDK
  await initializeSwypeSDK({
    apiKey: "<YOUR_API_KEY>",
    baseUrl: "https://dev.console.fi",
    apiPath: "/v1/vendor",
    eoaAddress: address,
    signature,
    deadline,
  });
}
```

> **Note:** After 1 hour, you must prompt the user to sign again and re-initialize the SDK.

---

## 2. Widgets

The SDK provides ready-to-use React components for KYC and card management.

### **KycModal**

- **Props:**
  - `eoaAddress: string` (required)
  - `onClose?: () => void`
  - `onComplete?: () => void`
- **Description:**
  Handles the full KYC flow, including SumSub integration, consent, and pending/approved states. Callbacks are triggered on close or completion.

  **Behavior by User Status:**

  - **'initiated' / 'userNotExisting':** Shows the Submit KYC Modal for the user to start KYC.
  - **'pending':** Shows the Rain KYC Pending Modal, indicating KYC is under review.
  - **'approved':** The KYC is complete. The integrator must now call the `delegateCard` function to delegate credit and create the card. After delegation, refetch card status and show the dashboard with owned card details.

  > **Note:** The KycModal does not handle card delegation. For 'approved' status, you must trigger the delegation flow in your app using the SDK's `delegateCard` utility.

### **ManageCardModal**

- **Props:**
  - `title: string`
  - `onClose: () => void`
  - `callbacks: CardDetailsCallbacks`
  - `address: string`
  - `chainId: number`
- **Description:**  
  Lets users view card details, reveal secrets, freeze/unfreeze, and change PIN. Integrates with SDK hooks for state and actions.

---

## 3. Hooks

The SDK exposes hooks for accessing user/card/credit/transaction data:

### **useCardData**

Returns:

```ts
{
  status: CardStatus | null,
  userCard: UserCard | null,
  isUserCardDelegated: boolean,
  isLoading: boolean,
  error: string | null
}
```

### **useCreditData**

Returns:

```ts
{
  creditInfo: {
    card: CreditInformationResponse | null,
    aave: CreditInformationResponse | null,
    euler: CreditInformationResponse | null
  },
  isLoading: boolean,
  error: string | null
}
```

### **useGetTransactions**

Returns:

```ts
{
  transactions: Transaction[],
  isLoading: boolean,
  error: string | null,
  hasNext: boolean,
  loadMore: () => Promise<void>,
  refetch: () => Promise<void>,
  fetchOnchainDetails: (transactionID: string) => Promise<OnchainTransactionDetailsResponse>
}
```

---

## 4. Utility Functions

### **delegateCard**

```ts
async function delegateCard(params: DelegateCardParams): Promise<void>;
```

- **Description:**  
  Handles the full card delegation flow: gets delegation transaction data, executes the transaction, creates the card, generates a signature, links the card, verifies, and refetches data.
- **Params:**
  - `creditType`: "aave-v3" | "euler"
  - `creditLimit`: number
  - `sendTransactionAsync`: callback for sending the transaction
  - `signTypedDataAsync`: callback for EIP-712 signature
  - `userParams?`: { vaults: string[] }

---

## 5. Types

The SDK exports the following types for type safety and integration:

- `CardStatus`: Status of the user's card/KYC (e.g., 'initiated', 'pending', 'approved', etc.)
- `CreditDelegationRequest`: Parameters for requesting a credit delegation transaction (credit type, from address, credit limit, etc.)
- `UserCard`: Structure representing a user's card (cardID, status, type, last4, etc.)
- `Transaction`
- `OnchainTransactionDetail`
- ...and more (see `src/api/types.ts` for full list).

---

**For more details, see the code comments and type definitions in the SDK.**

## Development Setup

### Initial Setup (One-time)

1. **Build the SDK first:**

   ```bash
   cd swype-sdk
   npm run build:all
   ```

2. **Link the SDK for development:**

   ```bash
   cd swype-sdk
   yarn link
   ```

3. **In the Next.js app, use the linked SDK:**
   ```bash
   cd swype-nextjs
   yarn remove swype-sdk  # Remove any existing installation
   yarn add link:../swype-sdk  # Add the linked version
   ```

### Hot Reload Development

To develop the SDK with hot reload:

1. **Terminal 1 - Run SDK in watch mode:**

   ```bash
   cd swype-sdk
   npm run dev
   ```

2. **Terminal 2 - Run the Next.js app:**
   ```bash
   cd swype-nextjs
   yarn dev
   ```

**Important Notes:**

- If hot reload isn't working, restart the Next.js dev server
- The Next.js config has been updated to watch symlinked packages
- Make sure both terminals are running for hot reload to work

Now any changes you make to the SDK files will automatically rebuild and be reflected in the Next.js app.

### Troubleshooting

If hot reload stops working:

1. Stop both dev servers
2. Clear Next.js cache: `rm -rf swype-nextjs/.next`
3. Restart both dev servers

### Build Commands

- `npm run dev` - Run in development mode with hot reload
- `npm run build` - Build TypeScript files only
- `npm run build:css` - Build CSS files only
- `npm run build:all` - Build everything (TypeScript + CSS)

### CSS Isolation

All styles are automatically scoped under `.swype-sdk-root` using PostCSS to prevent conflicts with the host application.

### Project Structure

```
swype-sdk/
├── src/
│   ├── api/          # API service layer
│   ├── components/   # Reusable components
│   ├── hooks/        # Custom React hooks
│   ├── stores/       # Zustand stores
│   ├── utils/        # Utility functions
│   ├── widgets/      # Main widget components
│   └── styles.css    # Tailwind CSS entry
├── dist/             # Built files
├── postcss.config.js # PostCSS configuration
└── tailwind.config.js # Tailwind configuration
```