omni-sync-sdk 0.1.0

package/README.md

@@ -0,0 +1,191 @@
+# @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