omni-sync-sdk 0.2.0 → 0.3.0

package/README.md

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

package/dist/index.d.mts

@@ -1,8 +1,41 @@
 interface OmniSyncClientOptions {
     /**
-     * API Key for authentication (starts with "omni_")
+     * Connection ID for vibe-coded sites (starts with "vc_").
+     * This is the simplest way to connect - just use your Connection ID!
+     * Safe to use in frontend applications.
+     *
+     * @example
+     * ```typescript
+     * // Vibe-coded site usage - simplest option!
+     * const omni = new OmniSyncClient({
+     *   connectionId: 'vc_abc123xyz...',
+     * });
+     * const products = await omni.getProducts();
+     * ```
      */
-    apiKey: string;
+    connectionId?: string;
+    /**
+     * Store ID for public storefront access (no API key needed).
+     * Use this for frontend/browser applications.
+     *
+     * @example
+     * ```typescript
+     * // Frontend usage - safe to expose
+     * const omni = new OmniSyncClient({ storeId: 'store_abc123' });
+     * ```
+     */
+    storeId?: string;
+    /**
+     * API Key for admin/backend access (starts with "omni_").
+     * Keep this secret - never expose in frontend code!
+     *
+     * @example
+     * ```typescript
+     * // Backend usage - keep secret
+     * const omni = new OmniSyncClient({ apiKey: process.env.OMNI_API_KEY });
+     * ```
+     */
+    apiKey?: string;
     /**
      * Base URL of the Omni-Sync API
      * @default "https://api.omni-sync.com"
@@ -14,6 +47,24 @@ interface OmniSyncClientOptions {
      */
     timeout?: number;
 }
+interface StoreInfo {
+    id: string;
+    name: string;
+    currency: string;
+    language: string;
+}
+interface CustomerProfile {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    emailVerified: boolean;
+    acceptsMarketing: boolean;
+    addresses: CustomerAddress[];
+    createdAt: string;
+    updatedAt: string;
+}
 interface Product {
     id: string;
     name: string;
@@ -780,37 +831,99 @@ interface OmniSyncApiError {
 }
 
 /**
- * OmniSyncClient - SDK for integrating vibe coding stores with Omni-Sync Platform
+ * OmniSyncClient - SDK for integrating stores with Omni-Sync Platform
  *
- * @example
+ * Three modes of operation:
+ *
+ * **Vibe-Coded Mode (Simplest)** - Use connectionId for vibe-coded sites:
  * ```typescript
- * const omni = new OmniSyncClient({
- *   apiKey: process.env.OMNI_SYNC_API_KEY!,
- * });
+ * const omni = new OmniSyncClient({ connectionId: 'vc_abc123...' });
+ * const products = await omni.getProducts();
+ * ```
  *
- * // Get products
+ * **Storefront Mode (Frontend)** - Use storeId for public access:
+ * ```typescript
+ * const omni = new OmniSyncClient({ storeId: 'store_abc123' });
  * const products = await omni.getProducts();
+ * ```
  *
- * // Create an order
- * const order = await omni.createOrder({
- *   items: [{ productId: 'prod_123', quantity: 2, price: 99.99 }],
- *   customer: { email: 'customer@example.com', name: 'John Doe' },
- *   totalAmount: 199.98,
- * });
+ * **Admin Mode (Backend)** - Use apiKey for full access:
+ * ```typescript
+ * const omni = new OmniSyncClient({ apiKey: process.env.OMNI_API_KEY });
+ * const orders = await omni.getOrders();
  * ```
  */
 declare class OmniSyncClient {
-    private readonly apiKey;
+    private readonly apiKey?;
+    private readonly storeId?;
+    private readonly connectionId?;
     private readonly baseUrl;
     private readonly timeout;
+    private customerToken;
     constructor(options: OmniSyncClientOptions);
+    /**
+     * Check if client is in vibe-coded mode (using connectionId)
+     */
+    isVibeCodedMode(): boolean;
+    /**
+     * Check if client is in storefront mode (using storeId)
+     */
+    isStorefrontMode(): boolean;
+    /**
+     * Check if client is in admin mode (using apiKey)
+     */
+    isAdminMode(): boolean;
+    /**
+     * Set the customer authentication token (obtained from login/register).
+     * Required for accessing customer-specific data in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * const auth = await omni.loginCustomer('user@example.com', 'password');
+     * omni.setCustomerToken(auth.token);
+     *
+     * // Now can access customer data
+     * const profile = await omni.getMyProfile();
+     * ```
+     */
+    setCustomerToken(token: string | null): void;
+    /**
+     * Get the current customer token
+     */
+    getCustomerToken(): string | null;
+    /**
+     * Clear the customer token (logout)
+     */
+    clearCustomerToken(): void;
+    /**
+     * Make a request to the Admin API (requires apiKey)
+     */
+    private adminRequest;
+    /**
+     * Make a request to the Vibe-Coded API (public, uses connectionId)
+     */
+    private vibeCodedRequest;
+    /**
+     * Make a request to the Storefront API (public, uses storeId)
+     */
+    private storefrontRequest;
+    /**
+     * Smart request - uses storefront or admin API based on client mode
+     */
     private request;
+    /**
+     * Get store information
+     * Works in vibe-coded, storefront, and admin mode
+     */
+    getStoreInfo(): Promise<StoreInfo>;
     /**
      * Get a list of products with pagination
+     * Works in vibe-coded, storefront (public), and admin mode
      */
     getProducts(params?: ProductQueryParams): Promise<PaginatedResponse<Product>>;
     /**
      * Get a single product by ID
+     * Works in vibe-coded, storefront (public), and admin mode
      */
     getProduct(productId: string): Promise<Product>;
     /**
@@ -1201,16 +1314,6 @@ declare class OmniSyncClient {
      * Get the status of a sync job
      */
     getSyncStatus(jobId: string): Promise<SyncJob>;
-    /**
-     * Get information about the connected store
-     */
-    getStoreInfo(): Promise<{
-        id: string;
-        name: string;
-        currency: string;
-        language: string;
-        connectedPlatforms: ConnectorPlatform[];
-    }>;
     /**
      * Get a list of coupons with pagination
      */
@@ -1597,6 +1700,62 @@ declare class OmniSyncClient {
      * ```
      */
     completeCheckout(checkoutId: string): Promise<CompleteCheckoutResponse>;
+    /**
+     * Get the current customer's profile (requires customerToken)
+     * Only available in storefront mode
+     *
+     * @example
+     * ```typescript
+     * const auth = await omni.loginCustomer('user@example.com', 'password');
+     * omni.setCustomerToken(auth.token);
+     * const profile = await omni.getMyProfile();
+     * ```
+     */
+    getMyProfile(): Promise<CustomerProfile>;
+    /**
+     * Update the current customer's profile (requires customerToken)
+     * Only available in storefront mode
+     */
+    updateMyProfile(data: {
+        firstName?: string;
+        lastName?: string;
+        phone?: string;
+        acceptsMarketing?: boolean;
+    }): Promise<CustomerProfile>;
+    /**
+     * Get the current customer's orders (requires customerToken)
+     * Only available in storefront mode
+     */
+    getMyOrders(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Order>>;
+    /**
+     * Get the current customer's addresses (requires customerToken)
+     * Only available in storefront mode
+     */
+    getMyAddresses(): Promise<CustomerAddress[]>;
+    /**
+     * Add an address to the current customer (requires customerToken)
+     * Only available in storefront mode
+     */
+    addMyAddress(address: CreateAddressDto): Promise<CustomerAddress>;
+    /**
+     * Update a customer address (requires customerToken)
+     * Only available in storefront mode
+     */
+    updateMyAddress(addressId: string, data: UpdateAddressDto): Promise<CustomerAddress>;
+    /**
+     * Delete a customer address (requires customerToken)
+     * Only available in storefront mode
+     */
+    deleteMyAddress(addressId: string): Promise<void>;
+    /**
+     * Get the current customer's cart (requires customerToken)
+     * Creates a new cart if none exists
+     * Only available in storefront mode
+     */
+    getMyCart(): Promise<Cart>;
 }
 /**
  * Custom error class for Omni-Sync API errors
@@ -1617,7 +1776,7 @@ declare class OmniSyncError extends Error {
  *
  * @example
  * ```typescript
- * import { verifyWebhook } from '@omni-sync/sdk';
+ * import { verifyWebhook } from 'omni-sync-sdk';
  *
  * app.post('/webhooks/omni-sync', async (req, res) => {
  *   const signature = req.headers['x-omni-signature'];
@@ -1664,4 +1823,4 @@ declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType)
  */
 declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomerDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type InventoryInfo, type InventorySyncStatus, type MergeCartsDto, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };
+export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomerDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type InventoryInfo, type InventorySyncStatus, type MergeCartsDto, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StoreInfo, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };