npm package: @omny-sync/sdk
Description: SDK for integrating vibe coding stores with Omni-Sync Platform
Author: Omni-Sync Platform
Latest version: 0.1.0

# @omni-sync/sdk

SDK for integrating vibe coding stores with Omni-Sync Platform.

## Installation

```bash
npm install @omni-sync/sdk
# or
pnpm add @omni-sync/sdk
# or
yarn add @omni-sync/sdk
```

## Quick Start

```typescript
import { OmniSyncClient } from '@omni-sync/sdk';

const omni = new OmniSyncClient({
  apiKey: process.env.OMNI_SYNC_API_KEY!,
});

// Get products
const { data: products } = await omni.getProducts();

// Create an order
const order = await omni.createOrder({
  items: [
    { productId: products[0].id, quantity: 2, price: 99.99 }
  ],
  customer: { email: 'customer@example.com', name: 'John Doe' },
  totalAmount: 199.98,
});
```

## Products

```typescript
// List products with pagination
const { data, meta } = await omni.getProducts({
  page: 1,
  limit: 20,
  status: 'active',
  search: 'shirt',
});

// Get single product
const product = await omni.getProduct('prod_123');

// Create product
const newProduct = await omni.createProduct({
  name: 'Blue T-Shirt',
  sku: 'TSHIRT-BLUE-M',
  basePrice: 29.99,
  status: 'active',
});

// Update product
const updated = await omni.updateProduct('prod_123', {
  salePrice: 24.99,
});

// Delete product
await omni.deleteProduct('prod_123');
```

## Orders

```typescript
// Create order (auto-deducts inventory, syncs to all platforms)
const order = await omni.createOrder({
  items: [
    { productId: 'prod_123', quantity: 1, price: 29.99 },
    { productId: 'prod_456', quantity: 2, price: 49.99 },
  ],
  customer: {
    email: 'john@example.com',
    name: 'John Doe',
    phone: '+1234567890',
  },
  totalAmount: 129.97,
});

// List orders
const { data: orders } = await omni.getOrders({
  status: 'pending',
});

// Update order status
await omni.updateOrder('order_123', { status: 'shipped' });
```

## Inventory

```typescript
// Get current inventory
const inventory = await omni.getInventory('prod_123');
console.log(`Available: ${inventory.available}`);

// Update inventory (syncs to all platforms)
await omni.updateInventory('prod_123', { quantity: 50 });
```

## Webhooks

Receive real-time updates when products, orders, or inventory change on any connected platform.

### Setup webhook endpoint

```typescript
// api/webhooks/omni-sync/route.ts (Next.js App Router)
import { verifyWebhook, createWebhookHandler } from '@omni-sync/sdk';

const handler = createWebhookHandler({
  'product.updated': async (event) => {
    console.log('Product updated:', event.entityId);
    // Invalidate cache, update UI, etc.
  },
  'inventory.updated': async (event) => {
    console.log('Stock changed:', event.data);
  },
  'order.created': async (event) => {
    console.log('New order from:', event.platform);
  },
});

export async function POST(req: Request) {
  const signature = req.headers.get('x-omni-signature');
  const body = await req.json();
  
  // Verify signature
  if (!verifyWebhook(body, signature, process.env.OMNI_SYNC_WEBHOOK_SECRET!)) {
    return new Response('Invalid signature', { status: 401 });
  }
  
  // Process event
  await handler(body);
  
  return new Response('OK');
}
```

### Webhook Events

| Event | Description |
|-------|-------------|
| `product.created` | New product created |
| `product.updated` | Product details changed |
| `product.deleted` | Product removed |
| `inventory.updated` | Stock levels changed |
| `order.created` | New order received |
| `order.updated` | Order status changed |

## Environment Variables

```env
OMNI_SYNC_API_KEY=omni_your_api_key_here
OMNI_SYNC_WEBHOOK_SECRET=your_webhook_secret_here
```

## Error Handling

```typescript
import { OmniSyncClient, OmniSyncError } from '@omni-sync/sdk';

try {
  const product = await omni.getProduct('invalid_id');
} catch (error) {
  if (error instanceof OmniSyncError) {
    console.error(`API Error: ${error.message} (${error.statusCode})`);
  }
}
```

## TypeScript Support

Full TypeScript support with exported types:

```typescript
import type { 
  Product, 
  Order, 
  CreateProductDto,
  WebhookEvent 
} from '@omni-sync/sdk';
```

## License

MIT