npm package: @nekuda/wallet
Description: Nekuda Wallet SDK
Author: Nekuda AI
Latest version: 0.2.4

# Nekuda Wallet

The official React SDK for integrating nekuda's wallet component into your AI agent application. Let your users save and manage payment credentials that your AI agent can use for automated purchases.

Full documentation is available at [nekuda Docs](https://docs.nekuda.ai/frontend/wallet/overview).

## Overview

The React nekuda-js SDK provides a complete wallet component for managing payment methods, contact information, and shipping addresses. Card data is tokenized and stored securely via PCI-compliant iframes, keeping you out of PCI scope.

### Requirements
- Node.js 20.0.0 or higher
- React 18+ or React 19
- Valid nekuda public key from [app.nekuda.ai](https://app.nekuda.ai)

## Key Features

- **Complete Wallet UI** - Payment methods, contact info, and shipping address management
- **PCI-compliant Security** - Card data never touches your frontend via isolated iframes
- **Customizable Theming** - Light, dark, and minimal themes with full style override support
- **Mobile Responsive** - Automatically adapts to mobile screens
- **Type-safe** - Full TypeScript support with type definitions included

## Installation

```bash
# npm
npm install @nekuda/wallet

# yarn
yarn add @nekuda/wallet
```

## Quick Start

```jsx
import { WalletProvider, NekudaWallet } from '@nekuda/wallet';

function UserSettings() {
  const userId = currentUser.id; // Your user's ID

  return (
    <WalletProvider publicKey="pk_test_..." userId={userId}>
      <NekudaWallet />
    </WalletProvider>
  );
}
```

Get your public key from [app.nekuda.ai](https://app.nekuda.ai). Users can now save and manage payment methods. Your backend can retrieve them via the nekuda backend SDK.

## What You Get

The `NekudaWallet` component provides:

1. **Payment Methods Tab** - Add, edit, delete, and set default cards
2. **Settings Tab** - Manage contact information and shipping address
3. **Secure Collection** - All card data collected via PCI-compliant iframes
4. **Tokenization** - Cards are tokenized and stored server-side

## Frontend to Backend Flow

```jsx
// Frontend: User adds card via wallet
<WalletProvider publicKey="pk_test_..." userId="user_123">
  <NekudaWallet />
</WalletProvider>
```

```python
# Backend: Retrieve card when AI agent needs to make purchase
from nekuda import NekudaClient, MandateData

client = NekudaClient.from_env()
user = client.user("user_123")  # Same userId

# 3-step mandate flow
mandate_resp = user.create_mandate(MandateData(...))
reveal_resp = user.request_card_reveal_token(mandate_resp.mandate_id)
card = user.reveal_card_details(reveal_resp.reveal_token)

# AI agent now has: card.card_number, card.cvv, card.card_expiry_date
```

Frontend stores cards (tokenized). Backend retrieves cards (full details) for your AI agent to complete purchases.

## Key Concepts

### `userId`
Your user's unique identifier from your system (e.g., database ID). Must be consistent across frontend and backend. nekuda doesn't generate this - you provide it.

### `publicKey`
Your public API key (`pk_test_...` or `pk_live_...`) from [app.nekuda.ai](https://app.nekuda.ai). Safe to use in frontend code. Only allows card collection, not retrieval.

**Never use your secret key (`sk_*`) in frontend code** - it's for backend only.

## Accessing Payment Method Metadata

Use `useWallet()` to access non-sensitive card metadata in your React components:

```jsx
import { useWallet } from '@nekuda/wallet';

function Dashboard() {
  const wallet = useWallet();
  const defaultCard = wallet.payments.list.find(pm => pm.isDefault);

  return (
    <div>
      <p>{wallet.payments.list.length} cards saved</p>
      {defaultCard && (
        <p>Default: •••• {defaultCard.lastFourDigits}</p>
      )}
    </div>
  );
}
```

**Available fields**: `id`, `lastFourDigits`, `expiryDate`, `cardType`, `cardHolderName`, `isDefault`, `billingAddress`, timestamps.

Full card numbers and CVVs are never exposed. Backend SDK only.

## Customization

Choose from three styling modes:

```jsx
// Pre-built themes (light, dark, minimal)
<NekudaWallet mode="themed" theme="dark" />

// Custom style overrides
<NekudaWallet mode="custom" styles={yourCustomStyles} />

// Headless mode - full control over appearance
<NekudaWallet mode="headless" />
```

See [Styling & Theming](https://docs.nekuda.ai/frontend/wallet/styling-theming) for complete customization options.

## Component Props

### `<WalletProvider>` (Required)

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `publicKey` | `string` | ✅ | Your nekuda public API key (`pk_test_...` or `pk_live_...`) |
| `userId` | `string` | ✅ | Your user's unique identifier from your system |
| `debug` | `boolean` | | Enable debug logging (default: `false`) |

### `<NekudaWallet>` (All props optional)

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `mode` | `'themed' \| 'headless' \| 'custom'` | `'themed'` | Styling mode |
| `theme` | `'light' \| 'dark' \| 'minimal'` | `'light'` | Pre-built theme when `mode="themed"` |
| `className` | `string` | | CSS class name for container |
| `styles` | `Partial<WalletStyles>` | | Custom style overrides |
| `showSettings` | `boolean` | `true` | Show Settings tab (contact/shipping) |
| `defaultContact` | `Partial<IdentityData>` | | Pre-fill contact information |
| `defaultShipping` | `Partial<AddressData>` | | Pre-fill shipping address |
| `defaultBilling` | `Partial<AddressData>` | | Pre-fill billing address for new cards |
| `onError` | `(error: Error) => void` | | Callback when any operation fails |
| `onContactChange` | `(data: IdentityData) => void` | | Callback when contact info updated |
| `onShippingChange` | `(data: AddressData) => void` | | Callback when shipping updated |
| `renderEmptyState` | `() => ReactNode` | | Custom component when no saved cards |

## Security & PCI Compliance

Card inputs render in secure iframes at `collect.nekuda.ai` - your frontend cannot access them. The wallet only shows tokenized data (last 4 digits, expiry, name). Full card numbers and CVVs are never transmitted to your frontend.

**Key separation:**
- **Public key** (`pk_*`): Frontend collection only
- **Secret key** (`sk_*`): Backend retrieval only

HTTPS required in production. This design keeps you out of PCI scope.

## Documentation

- [Wallet Overview](https://docs.nekuda.ai/frontend/wallet/overview) - Complete guide and setup
- [Integration Patterns](https://docs.nekuda.ai/frontend/wallet/integration-patterns) - Real-world examples
- [Payment Methods Tab](https://docs.nekuda.ai/frontend/wallet/payment-methods-tab) - Card management features
- [Settings Tab](https://docs.nekuda.ai/frontend/wallet/settings-tab) - Contact and shipping management
- [Styling & Theming](https://docs.nekuda.ai/frontend/wallet/styling-theming) - Customize appearance
- [Backend SDK](https://docs.nekuda.ai/nekuda-sdk/getting-started) - Retrieve card details for AI agent

## Support

- 📧 Email: [support@nekuda.ai](mailto:support@nekuda.ai)
- 📖 Docs: [docs.nekuda.ai](https://docs.nekuda.ai)
- 🌐 Portal: [app.nekuda.ai](https://app.nekuda.ai)

## License

MIT License - see LICENSE file for details.