spaps-sdk/README.md

Sweet Potato Authentication & Payment Service SDK - Zero-config client for SPAPS

# @spaps/sdk

> Sweet Potato Authentication & Payment Service SDK

Zero-config client for SPAPS authentication and payments. Works automatically with local development mode.

## Installation

```bash
npm install @spaps/sdk
# or
yarn add @spaps/sdk
```

## Quick Start

```javascript
import { SPAPSClient } from '@spaps/sdk';
// or
const { SPAPSClient } = require('@spaps/sdk');

// Auto-detects local mode - no API key needed for localhost!
const spaps = new SPAPSClient({
  apiUrl: 'http://localhost:3300' // Optional, auto-detected
});

// Login
const { data } = await spaps.login('user@example.com', 'password');
console.log('User:', data.user);

// Check authentication
if (spaps.isAuthenticated()) {
  const user = await spaps.getUser();
  console.log('Current user:', user.data);
}
```

## Features

### 🚀 Zero Configuration
- **Auto-detects local mode** - No API key needed for localhost
- **Auto-refreshes tokens** - Handles expired tokens automatically
- **TypeScript support** - Full type definitions included

### 🔐 Authentication Methods
```javascript
// Email/Password
await spaps.login(email, password);
await spaps.register(email, password);

// Wallet Authentication
await spaps.walletSignIn(walletAddress, signature, message, 'solana');

// Token Management
await spaps.refresh();
await spaps.logout();

// Get User
const user = await spaps.getUser();
```

### 💳 Stripe Integration
```javascript
// Create checkout session
const session = await spaps.createCheckoutSession(priceId, successUrl);
window.location.href = session.data.url;

// Manage subscription
const subscription = await spaps.getSubscription();
await spaps.cancelSubscription();
```

### 📊 Usage Tracking
```javascript
// Check balance
const balance = await spaps.getUsageBalance();
console.log(`Credits: ${balance.data.balance}`);

// Record usage
await spaps.recordUsage('api-call', 1);
```

## Configuration

### Production Mode
```javascript
const spaps = new SPAPSClient({
  apiUrl: 'https://api.sweetpotato.com',
  apiKey: 'spaps_your_api_key_here',
  timeout: 10000 // Optional timeout in ms
});
```

### Local Development Mode (Auto-detected)
```javascript
const spaps = new SPAPSClient();
// Automatically uses http://localhost:3300 with no API key
```

### Environment Variables
```bash
# .env
SPAPS_API_URL=https://api.sweetpotato.com
SPAPS_API_KEY=spaps_your_api_key_here

# Next.js
NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.com
```

## Helper Methods

```javascript
// Check if authenticated
spaps.isAuthenticated() // boolean

// Get current access token
spaps.getAccessToken() // string | undefined

// Set access token manually
spaps.setAccessToken(token)

// Check if in local mode
spaps.isLocalMode() // boolean

// Health check
await spaps.health()
```

## Import Styles

All these work:
```javascript
// ES6 Import
import { SPAPSClient } from '@spaps/sdk';
import SPAPSClient from '@spaps/sdk';

// CommonJS
const { SPAPSClient } = require('@spaps/sdk');
const SPAPSClient = require('@spaps/sdk');

// Alternative names
import { SPAPS } from '@spaps/sdk';
import { SweetPotatoSDK } from '@spaps/sdk';
```

## Error Handling

```javascript
try {
  await spaps.login(email, password);
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Invalid credentials');
  } else if (error.response?.status === 429) {
    console.error('Rate limited');
  } else {
    console.error('Error:', error.message);
  }
}
```

## License

MIT