# Arcadia Game SDK

SDK for integrating Arcadia wallet and payment features into Web3 games.

## Features

- ✅ **Wallet Integration** - Get wallet address, check connection status
- ✅ **Payment Processing** - Pay-to-play and in-game purchases
- ✅ **Iframe Support** - Works seamlessly in Arcadia iframes
- ✅ **Non-Iframe Support** - Works with direct API calls for native apps
- ✅ **Stats Tracking** - Track playtime and online status (non-iframe mode)

## Installation

### NPM

```bash
npm install @arcadiasol/sdk
```

### CDN

```html
<script src="https://cdn.jsdelivr.net/npm/@arcadiasol/sdk@latest/dist/umd/arcadia-game-sdk.js"></script>
```

## Quick Start

### Iframe Mode (Web Games)

```typescript
import ArcadiaSDK from '@arcadiasol/sdk';

const arcadia = new ArcadiaSDK({
  gameId: 'your-game-id',
});

await arcadia.init();

// Get wallet address
const walletAddress = await arcadia.getWalletAddress();

// Pay to play
const result = await arcadia.payment.payToPlay(0.1, 'SOL');
```

### Non-Iframe Mode (Native Apps / External Games)

```typescript
import ArcadiaSDK from '@arcadiasol/sdk';

const arcadia = new ArcadiaSDK({
  gameId: 'your-game-id',
  apiBaseURL: 'https://arcadia.com', // Required for non-iframe
  authToken: 'your-auth-token', // Optional: if you have auth token
  walletAddress: 'your-wallet-address', // Optional: if you know wallet address
});

await arcadia.init();

// Get wallet address
const walletAddress = await arcadia.getWalletAddress();

// Track playtime
await arcadia.stats.updatePlaytime(1.5, 'playing');

// Update online status
await arcadia.stats.updateOnlineStatus(true);

// Pay to play (requires transaction signature)
// Note: You must sign the transaction yourself in non-iframe mode
const txSignature = await signTransaction(...); // Your signing logic
const result = await arcadia.payment.payToPlay(0.1, 'SOL', txSignature);
```

### React Native Example

```typescript
import ArcadiaSDK from '@arcadiasol/sdk';

// Initialize SDK for React Native
const arcadia = new ArcadiaSDK({
  gameId: 'your-game-id',
  apiBaseURL: 'https://arcadia.com', // Required
  authToken: await getAuthToken(), // From your auth system
  walletAddress: await getWalletAddress(), // From your wallet SDK
});

await arcadia.init();

// Use SDK methods (same as non-iframe mode)
const walletAddress = await arcadia.getWalletAddress();
await arcadia.stats.updatePlaytime(1.5, 'playing');
await arcadia.stats.updateOnlineStatus(true);

// Payments require you to sign transactions first
const transaction = await buildTransaction(...);
const txSignature = await signTransaction(transaction);
const result = await arcadia.payment.payToPlay(0.1, 'SOL', txSignature);
```

## API Reference

### Constructor

```typescript
new ArcadiaSDK(config: SDKConfig)
```

**Config Options:**
- `gameId` (string, required) - Your game identifier
- `parentOrigin` (string, optional) - Parent window origin for iframe security
- `timeout` (number, optional) - Request timeout in milliseconds (default: 30000)
- `apiBaseURL` (string, optional) - Base URL for API calls (required for non-iframe)
- `authToken` (string, optional) - Pre-authenticated token (non-iframe mode)
- `walletAddress` (string, optional) - Wallet address (non-iframe mode)

### Methods

#### `init(): Promise<void>`

Initialize SDK. Must be called after creating SDK instance.

#### `getWalletAddress(): Promise<string | null>`

Get connected wallet address. Returns `null` if not connected.

#### `isWalletConnected(): Promise<boolean>`

Check if wallet is connected.

#### `onWalletChange(callback: Function): void`

Listen for wallet connection changes.

#### `payment.payToPlay(amount, token, txSignature?)`

Pay to play. `txSignature` required for non-iframe mode.

**Parameters:**
- `amount` (number) - Payment amount
- `token` (string) - Token type: 'SOL', 'USDC', or custom token symbol/mint address
- `txSignature` (string, optional) - Transaction signature (required for non-iframe mode)

#### `payment.purchaseItem(itemId, amount, token, txSignature?)`

Purchase in-game item. `txSignature` required for non-iframe mode.

**Parameters:**
- `itemId` (string) - Item identifier
- `amount` (number) - Payment amount
- `token` (string) - Token type: 'SOL', 'USDC', or custom token symbol/mint address
- `txSignature` (string, optional) - Transaction signature (required for non-iframe mode)

#### `stats.updatePlaytime(hours, status?)`

Update playtime (non-iframe mode only).

#### `stats.updateOnlineStatus(isOnline)`

Update online status (non-iframe mode only).

## Environment Detection

The SDK automatically detects if it's running in an iframe:

- **Iframe Mode**: Uses `postMessage` for communication
- **Non-Iframe Mode**: Uses REST API calls (requires `apiBaseURL`)

## Examples

See `/examples` directory for complete examples.

## Documentation

Full documentation: https://docs.arcadia.com/sdk