npm package: @sky-mavis/nana-app-sdk
Description: SDK for building mini apps that run inside the NanaPay wallet
Latest version: 0.1.2

# @sky-mavis/nana-app-sdk

SDK for building mini apps that run inside the NanaPay wallet. Works in two modes automatically:

- **Injected** -- app runs inside the wallet's WebView with `window.ethereum` injected
- **Universal Link** -- app runs in an external browser, redirects into the wallet via `https://nanapay.co/open`

The SDK detects the mode on first call. You never need to check or switch manually.

## Installation

```bash
npm install @sky-mavis/nana-app-sdk
```

## Quick Start

```ts
import { connect, signMessage, sendTransaction, disconnect } from '@sky-mavis/nana-app-sdk'

// 1. Connect and request permissions in one step
const { address, chainId, permissions } = await connect({
  requiredPermissions: ['address'],
  defaultPermissions: ['address', 'signMessage', 'sendTransaction'],
})

// 2. Sign a message (requires signMessage permission)
const signature = await signMessage('Hello from my mini app!')

// 3. Send a transaction (requires sendTransaction permission)
const txHash = await sendTransaction({
  to: '0x1234...abcd',
  value: '1000000000000000000', // 1 RON in wei
})

// 4. Disconnect when done
await disconnect()
```

## API Reference

### `connect(options?)`

Connect to the wallet. Accepts optional permission configuration.

```ts
const { address, chainId, permissions } = await connect({
  requiredPermissions: ['address'],
  defaultPermissions: ['address', 'email', 'signMessage', 'sendTransaction'],
})
```

**`ConnectOptions`**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `requiredPermissions` | `Permission[]` | `['address']` | Permissions the user must grant |
| `defaultPermissions` | `Permission[]` | All permissions | Pre-selected permissions shown to the user |

Returns `Promise<ConnectResult>` with `{ address: string, chainId: number, permissions: Record<Permission, boolean> }`.

### `requestPermissions(permissions)`

Request specific permissions from the user. A permission approval sheet is shown to the user.

```ts
const granted = await requestPermissions(['address', 'email', 'signMessage'])
// { address: true, email: true, signMessage: false }
```

Available permissions: `address`, `email`, `name`, `signMessage`, `sendTransaction`.

### `getUserInfo(fields)`

Get user information for the requested fields. Requires corresponding permissions (`email`, `name`, `address`).

```ts
const info = await getUserInfo(['email', 'name', 'address'])
// { email: 'user@example.com', name: 'Alice', address: '0x...' }
```

### `signMessage(message)`

Request the user to sign a message. Requires `signMessage` permission. Shows a confirmation sheet.

```ts
const signature = await signMessage('Please sign this message')
```

### `sendTransaction(tx)`

Request the user to send a transaction. Requires `sendTransaction` permission. Shows a confirmation sheet.

```ts
const txHash = await sendTransaction({
  to: '0x1234...abcd',
  value: '1000000000000000000',
  data: '0x',       // optional
  gasLimit: '21000', // optional
})
```

### `getProvider()`

Get the low-level EIP-1193 compatible provider for advanced use cases.

```ts
const provider = await getProvider()
const blockNumber = await provider.request({ method: 'eth_blockNumber' })
```

### `disconnect()`

Disconnect and reset the SDK. Resets the internal singleton so the next call re-detects the mode.

```ts
await disconnect()
```

### `detectMode()`

Check which mode the SDK will use without initializing. Useful for conditional UI. Returns a Promise because it performs EIP-6963 provider discovery.

```ts
import { detectMode } from '@sky-mavis/nana-app-sdk'

const mode = await detectMode()
if (mode === 'injected') {
  // Running inside the wallet WebView
} else {
  // Running in an external browser
}
```

### `configure(config)`

Optional. Override defaults before first use. Must be called before any other SDK function.

```ts
import { configure } from '@sky-mavis/nana-app-sdk'

configure({
  walletUrl: 'https://custom-wallet.example.com',
})
```

Only relevant for universal-link mode. If not called, defaults to `https://nanapay.co`.

## Supported RPC Methods

These are the wallet RPC methods available through `getProvider().request()`:

| Method | Permission | User Approval |
|--------|-----------|---------------|
| `wallet_connect` | None | Yes |
| `eth_chainId` | None | No |
| `eth_accounts` | `address` | No |
| `personal_sign` | `signMessage` | Yes |
| `eth_sendTransaction` | `sendTransaction` | Yes |
| `wallet_getUserInfo` | `email`/`name` | No |
| `wallet_requestPermissions` | None | Yes |
| `wallet_getPermissions` | None | No |
| `wallet_revokePermissions` | None | No |

## Permissions

| Permission | Description |
|-----------|-------------|
| `address` | View the user's wallet address |
| `email` | View the user's email address |
| `name` | View the user's display name |
| `signMessage` | Request message signatures |
| `sendTransaction` | Request transaction approvals |

## Advanced: EIP-6963 Provider Discovery

For custom integrations, you can access the underlying EIP-6963 discovery functions:

```ts
import { getNanapayProvider, requestProviders, NANAPAY_RDNS } from '@sky-mavis/nana-app-sdk'

// Get the NanaPay provider directly
const provider = await getNanapayProvider()

// Or discover all EIP-6963 providers
const providers = await requestProviders()
```

Constants exported: `NANAPAY_RDNS`, `EIP6963_DISCOVERY_DELAY`, `ALL_PERMISSIONS`, `DEFAULT_WALLET_URL`

## Build

```bash
npm run build       # TypeScript check + Vite library build
npm run typecheck   # TypeScript check only
npm run dev         # Watch mode
npm run lint        # ESLint check
npm run lint:fix    # ESLint with auto-fix
```

Output: `dist/index.mjs` (ESM), `dist/index.cjs` (CJS), `dist/index.d.ts` (types).

## License

MIT