npm package: @ponxa/potatobase-client
Description: Official JavaScript/TypeScript client for PotatoBase
Author: PotatoBase Team
Latest version: 0.1.2

# PotatoBase Client SDK

Official JavaScript/TypeScript client for PotatoBase - The DynamoDB platform built on SST v3.

## Installation

```bash
npm install @potatobase/client
# or
yarn add @potatobase/client
# or
pnpm add @potatobase/client
```

## Quick Start

```typescript
import { PotatoBaseClient } from '@potatobase/client';

// Initialize the client
const client = new PotatoBaseClient({
  apiUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.potatobase.dev',
  projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
  apiKey: process.env.NEXT_PUBLIC_API_KEY, // Optional, for frontend usage
});

// Access your tables
const products = client.table('products');
const orders = client.table('orders');

// Create a record
const product = await products.create({
  name: 'Awesome Product',
  price: 29.99,
  category: 'electronics'
});

// Query records
const electronics = await products.query({
  category: 'electronics'
});

// Get a single record
const product = await products.get('product-id');

// Update a record
await products.update('product-id', {
  price: 24.99
});

// Delete a record
await products.delete('product-id');
```

## Advanced Usage

### Batch Operations

```typescript
// Batch get multiple records
const products = await client.table('products').batchGet([
  'product-1',
  'product-2',
  'product-3'
]);

// Query with filters
const expensiveProducts = await client.table('products').query({
  category: 'electronics',
  minPrice: 100
});
```

### Real-time Updates (Coming Soon)

```typescript
// Subscribe to real-time changes
const unsubscribe = client.table('orders').subscribe(
  { status: 'pending' },
  (order) => {
    console.log('Order updated:', order);
  }
);

// Cleanup
unsubscribe();
```

## TypeScript Support

The SDK is written in TypeScript and provides full type safety:

```typescript
interface Product {
  productId: string;
  name: string;
  price: number;
  category: string;
}

const products = client.table<Product>('products');

// TypeScript will enforce the Product interface
const product = await products.create({
  name: 'Type-safe Product',
  price: 49.99,
  category: 'electronics'
});
```

## Environment Variables

Create a `.env.local` file in your project:

```env
NEXT_PUBLIC_API_URL=https://api.potatobase.dev
NEXT_PUBLIC_PROJECT_ID=your-project-id
NEXT_PUBLIC_API_KEY=your-api-key
```

## API Reference

### PotatoBaseClient

The main client class for interacting with PotatoBase.

#### Constructor Options

- `apiUrl` (string): The PotatoBase API endpoint
- `projectId` (string): Your project ID
- `apiKey` (string, optional): API key for frontend authentication

### Table Methods

All table operations return promises and support async/await:

- `create(data)`: Create a new record
- `get(id)`: Get a record by ID
- `update(id, data)`: Update a record
- `delete(id)`: Delete a record
- `query(params)`: Query records with filters
- `batchGet(ids)`: Get multiple records by IDs
- `list(options)`: List all records with pagination

## Error Handling

```typescript
try {
  const product = await products.get('non-existent-id');
} catch (error) {
  if (error.code === 'NOT_FOUND') {
    console.log('Product not found');
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/potatobase/client/blob/main/CONTRIBUTING.md) for details.

## License

MIT © PotatoBase Team

## Support

- Documentation: [https://docs.potatobase.dev](https://docs.potatobase.dev)
- GitHub Issues: [https://github.com/potatobase/client/issues](https://github.com/potatobase/client/issues)
- Discord: [Join our community](https://discord.gg/potatobase)