@use-stall/core 0.0.2 → 0.0.3

package/README.md

@@ -1,16 +1,17 @@
-# Stall Universal Connector SDK
+# Stall Core SDK
 
-A universal, type-safe SDK for integrating multiple commerce connectors (WooCommerce, Shopify, Medusa, etc.) with a unified interface. The SDK enables seamless communication with various data sources while maintaining a consistent API across all connectors.
+A universal, type-safe, adapter-based SDK for integrating multiple e-commerce connectors (WooCommerce, Shopify, Medusa, etc.) with a unified interface. The SDK uses a dynamic adapter architecture with IndexedDB caching for optimal performance.
 
 ## Overview
 
-The Stall SDK provides a plugin-based architecture that allows you to:
+The Stall Core SDK provides an adapter-based architecture that allows you to:
 
-- **Load connector plugins** dynamically from a public connector URL
-- **Standardize operations** across different commerce platforms
-- **Work with unified types** for orders, products, customers, and more
-- **Handle authentication** transparently across different auth methods
-- **Manage errors** consistently with detailed error codes and messages
+- **Load connector adapters dynamically** from a remote URL with automatic caching
+- **Standardize operations** across different e-commerce platforms
+- **Work with unified types** for products, orders, customers, inventory, and more
+- **Implement CRUD + bulk operations** with a consistent API
+- **Handle errors gracefully** with try-catch wrapped operations
+- **Cache adapter modules** in IndexedDB with TTL-based invalidation
 
 ## Architecture
 
@@ -19,544 +20,458 @@ The Stall SDK provides a plugin-based architecture that allows you to:
 │        Your Application             │
 └──────────────┬──────────────────────┘
                │
-┌──────────────▼──────────────────────┐
-│      StallSDK (Main Entry)          │
-│  - Firebase-style initialization    │
-│  - Service management               │
-└──────────────┬──────────────────────┘
-               │
-        ┌──────┴──────┐
-        │             │
-┌───────▼─────┐  ┌────▼──────────┐
-│   Orders    │  │   Products    │
-│  Service    │  │   Service     │
-└───────┬─────┘  └────┬──────────┘
-        │             │
-        └──────┬──────┘
+       ┌───────▼──────────────────┐
+       │  initializeStallCore()
+       │  Returns: CoreConfig
+       └───────┬──────────────────┘
+               │          
+    ┌──────────▼──────────┐
+    │   Service Layer     │
+    ├─────────────────────┤
+    │ - products          │
+    │ - orders            │
+    │ - customers         │
+    │ - variants          │
+    │ - inventory_levels  │
+    │ - promotions        │
+    │ - refunds           │
+    │ - payments          │
+    │ - tax_regions       │
+    │ - locations         │
+    │ - fulfillments      │
+    │ - ... and more      │
+    └──────────┬──────────┘
                │
-     ┌─────────▼──────────┐
-     │  Plugin Manager    │
-     │  - Lifecycle       │
-     │  - Verification    │
-     └─────────┬──────────┘
+    ┌──────────▼──────────────────┐
+    │  Adapter Module (Cached)    │
+    │  ┌───────────────────────┐  │
+    │  │ - Products module     │  │
+    │  │ - Orders module       │  │
+    │  │ - Customers module    │  │
+    │  │ - All modules         │  │
+    │  └───────────────────────┘  │
+    │                             │
+    │  Storage: IndexedDB + Dexie │
+    │  TTL: 4 hours (configurable)│
+    └──────────┬──────────────────┘
                │
-     ┌─────────▼──────────┐
-     │ Connector Loader   │
-     │ - Public URL       │
-     │ - Caching          │
-     └─────────┬──────────┘
+    ┌──────────▼──────────────────┐
+    │   Connector Loader          │
+    │  (Dynamic Module Import)    │
+    └──────────┬──────────────────┘
                │
-     ┌─────────▼──────────┐
-     │  Plugin Instance   │
-     │  (WooCommerce,     │
-     │   Shopify, etc.)   │
-     └────────────────────┘
+    ┌──────────▼──────────────────┐
+    │  Commerce Platform API      │
+    │  (WooCommerce, Shopify,     │
+    │  Medusa,Google Sheets etc.) │
+    └─────────────────────────────┘
 ```
 
 ## Installation
 
-The SDK is part of `@use-stall/core`. Install it with:
-
 ```bash
-npm install @use-stall/core
-# or
 bun install @use-stall/core
 ```
 
 ## Quick Start
 
-### Basic Usage
+### Initialize the SDK
 
 ```typescript
-import { StallSDK } from '@use-stall/core';
-import { MockConnectorPlugin } from '@use-stall/core';
-
-// Initialize the SDK with a mock connector for testing
-const stall = await StallSDK.initializeWithPlugin(
-  {
-    id: 'config_123',
-    integration_id: 'mock',
-    created_at: Date.now(),
-    updated_at: Date.now(),
-    configuration: {
-      endpoint: 'https://example.com/api',
-    },
-  },
-  new MockConnectorPlugin()
-);
-
-// Create an order
-const orderResult = await stall.orders.createOrder({
-  id: 'order_123',
-  order_number: 'ORD-001',
-  status: 'pending',
-  total: 99.99,
-  // ... other order fields
-});
-
-if (orderResult.success) {
-  console.log('Order created:', orderResult.data);
-} else {
-  console.error('Failed to create order:', orderResult.error);
-}
-```
-
-### Remote Plugin Loading from Public URL
+import { initializeStallCore, products, orders, customers } from '@use-stall/core';
 
-```typescript
-import { StallSDK } from '@use-stall/core';
-
-// Initialize with public connector URL
-// Default: https://connectors.myapp.xyz/{integration_id}/index.js
-const stall = await StallSDK.initialize({
-  id: 'config_123',
-  integration_id: 'woocommerce',
-  created_at: Date.now(),
-  updated_at: Date.now(),
+// Initialize with connector configuration
+const stall = initializeStallCore({
+  connector_url: 'https://connectors.myapp.xyz/woocommerce',
+  version: '1.0.0',
   configuration: {
     endpoint: 'https://myshop.com',
     token: process.env.WOOCOMMERCE_TOKEN,
   },
-  options: {
-    logLevel: 'info',
-    cachePlugins: true,
-    // connectorUrl is optional, defaults to https://connectors.myapp.xyz
-  },
 });
-
-// Verify connection
-const isConnected = await stall.verify();
-console.log('Connected:', isConnected);
-
-// Get metadata
-const metadata = stall.getMetadata();
-console.log('Connector:', metadata.name, metadata.version);
-
-// List products
-const products = await stall.products.listProducts({ limit: 10 });
-if (products.success) {
-  console.log('Products:', products.data);
-}
 ```
 
-## Services
-
-### Orders Service
+### Use Any Service
 
 ```typescript
-// Create an order
-const result = await stall.orders.createOrder(unifiedOrder);
-
-// Get an order
-const result = await stall.orders.getOrder('order_id');
+try {
+  // Products
+  const productList = await products.list({ sdk: stall, query: 'laptop' });
+  const product = await products.retrieve({ sdk: stall, id: 'prod_123' });
+  const newProduct = await products.create({
+    sdk: stall,
+    data: { name: 'New Product', price: 99.99 }
+  });
+  const updated = await products.update({
+    sdk: stall,
+    id: 'prod_123',
+    data: { price: 89.99 }
+  });
+  await products.delete({ sdk: stall, id: 'prod_123' });
+
+  // Bulk operations
+  const created = await products.bulk_create({
+    sdk: stall,
+    data: [{ name: 'Product 1' }, { name: 'Product 2' }]
+  });
+  const updated = await products.bulk_update({
+    sdk: stall,
+    data: [
+      { id: 'prod_1', data: { name: 'Updated 1' } },
+      { id: 'prod_2', data: { name: 'Updated 2' } },
+    ]
+  });
+  await products.bulk_delete({ sdk: stall, ids: ['prod_1', 'prod_2'] });
+} catch (error) {
+  console.error('Operation failed:', error);
+}
+```
 
-// Update an order
-const result = await stall.orders.updateOrder('order_id', { status: 'completed' });
+## Available Services
 
-// Delete/cancel an order
-const result = await stall.orders.deleteOrder('order_id');
+### Core CRUD Operations
 
-// List orders
-const result = await stall.orders.listOrders({ limit: 20, offset: 0 });
+Each service module provides 8 standard operations:
 
-// Create a refund
-const result = await stall.orders.createRefund('order_id', refundData);
+- **list(props)** - Get array of items with query search
+- **retrieve(props)** - Get single item by ID
+- **create(props)** - Create new item
+- **update(props)** - Update existing item
+- **delete(props)** - Delete item by ID
+- **bulk_create(props)** - Create multiple items
+- **bulk_update(props)** - Update multiple items
+- **bulk_delete(props)** - Delete multiple items
 
-// Get a refund
-const result = await stall.orders.getRefund('refund_id');
+### Inventory & Catalog
 
-// List refunds
-const result = await stall.orders.listRefunds('order_id');
+```typescript
+// Products
+const productList = await products.list({ sdk: stall, query: 'laptop' });
+const product = await products.retrieve({ sdk: stall, id: 'prod_123' });
+const newProduct = await products.create({ sdk: stall, data: { name: 'New Product' } });
+const updated = await products.update({ sdk: stall, id: 'prod_123', data: { price: 99.99 } });
+await products.delete({ sdk: stall, id: 'prod_123' });
+const bulkProducts = await products.bulk_create({ sdk: stall, data: [...] });
+const updatedBulk = await products.bulk_update({ sdk: stall, data: [...] });
+await products.bulk_delete({ sdk: stall, ids: ['prod_1', 'prod_2'] });
+
+// Variants
+const variantList = await variants.list({ sdk: stall, query: 'color-red' });
+const variant = await variants.retrieve({ sdk: stall, id: 'var_123' });
+
+// Categories
+const categoryList = await categories.list({ sdk: stall, query: 'electronics' });
+const category = await categories.retrieve({ sdk: stall, id: 'cat_123' });
+
+// Collections
+const collectionList = await collections.list({ sdk: stall, query: 'featured' });
+const collection = await collections.retrieve({ sdk: stall, id: 'coll_123' });
+const newCollection = await collections.create({ sdk: stall, data: { title: 'Summer Sale' } });
+
+// Inventory Levels
+const inventoryList = await inventory_levels.list({ sdk: stall, query: 'low' });
+const inventory = await inventory_levels.retrieve({ sdk: stall, id: 'inv_123' });
+const newInventory = await inventory_levels.create({ sdk: stall, data: { quantity: 100 } });
+const updatedInventory = await inventory_levels.update({ sdk: stall, id: 'inv_123', data: { quantity: 150 } });
+await inventory_levels.delete({ sdk: stall, id: 'inv_123' });
+const bulkInventory = await inventory_levels.bulk_create({ sdk: stall, data: [...] });
+const updatedBulkInventory = await inventory_levels.bulk_update({ sdk: stall, data: [...] });
+await inventory_levels.bulk_delete({ sdk: stall, ids: ['inv_1', 'inv_2'] });
 ```
 
-### Products Service
+### Order Management
 
 ```typescript
-// Create a product
-const result = await stall.products.createProduct(unifiedProduct);
-
-// Get a product
-const result = await stall.products.getProduct('product_id');
-
-// Update a product
-const result = await stall.products.updateProduct('product_id', { price: 199.99 });
+// Orders
+const orderList = await orders.list({ sdk: stall, query: 'pending' });
+const order = await orders.retrieve({ sdk: stall, id: 'order_123' });
+const newOrder = await orders.create({ sdk: stall, data: { customer_id: 'cust_123' } });
+const updatedOrder = await orders.update({ sdk: stall, id: 'order_123', data: { status: 'shipped' } });
+await orders.delete({ sdk: stall, id: 'order_123' });
+
+// Order Notes
+const noteList = await order_notes.list({ sdk: stall, query: 'urgent' });
+const note = await order_notes.retrieve({ sdk: stall, id: 'note_123' });
+const newNote = await order_notes.create({ sdk: stall, data: { text: 'Handle with care' } });
+
+// Refunds
+const refundList = await refunds.list({ sdk: stall, query: 'pending' });
+const refund = await refunds.retrieve({ sdk: stall, id: 'ref_123' });
+const newRefund = await refunds.create({ sdk: stall, data: { amount: 99.99 } });
+```
 
-// Delete a product
-const result = await stall.products.deleteProduct('product_id');
+### Customer Management
 
-// List products
-const result = await stall.products.listProducts({ 
-  limit: 50,
-  category: 'electronics' 
-});
+```typescript
+// Customers
+const customers_list = await customers.list({ sdk: stall, query: 'john' });
+const customer = await customers.retrieve({ sdk: stall, id: 'cust_123' });
+const newCustomer = await customers.create({ sdk: stall, data: { email: 'john@example.com' } });
+const updatedCustomer = await customers.update({ sdk: stall, id: 'cust_123', data: { phone: '+1234567890' } });
+await customers.delete({ sdk: stall, id: 'cust_123' });
 ```
 
-## Types
+### Promotions
 
-### Unified Types
+```typescript
+// Promotions
+const promotionList = await promotions.list({ sdk: stall, query: 'active' });
+const promotion = await promotions.retrieve({ sdk: stall, id: 'promo_123' });
+const newPromotion = await promotions.create({ sdk: stall, data: { code: 'SUMMER20' } });
+```
 
-The SDK uses unified types from `@use-stall/types`:
+### Payment Management
 
 ```typescript
-import type { 
-  UnifiedOrderType,
-  UnifiedProductType,
-  UnifiedOrderRefundType,
-  ConnectorConfigurationType,
-} from '@use-stall/core';
+// Payment Providers
+const providerList = await payment_providers.list({ sdk: stall, query: 'stripe' });
+const provider = await payment_providers.retrieve({ sdk: stall, id: 'pay_prov_123' });
+const newProvider = await payment_providers.create({ sdk: stall, data: { name: 'PayPal' } });
+const updatedProvider = await payment_providers.update({ sdk: stall, id: 'pay_prov_123', data: { status: 'active' } });
+await payment_providers.delete({ sdk: stall, id: 'pay_prov_123' });
+
+// Payments
+const paymentList = await payments.list({ sdk: stall, query: 'successful' });
+const payment = await payments.retrieve({ sdk: stall, id: 'pay_123' });
+const newPayment = await payments.create({ sdk: stall, data: { amount: 199.99 } });
 ```
 
-### Response Format
-
-All operations return a standardized response:
+### Tax & Location
 
 ```typescript
-interface ConnectorResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: {
-    code: string;
-    message: string;
-    details?: Record<string, any>;
-  };
-  metadata?: {
-    timestamp: number;
-    connector_id: string;
-    operation: string;
-    request_id: string;
-  };
-}
+// Tax Regions
+const taxRegionList = await tax_regions.list({ sdk: stall, query: 'US' });
+const taxRegion = await tax_regions.retrieve({ sdk: stall, id: 'tax_reg_123' });
+const newTaxRegion = await tax_regions.create({ sdk: stall, data: { country: 'US' } });
+
+// Tax Rates
+const taxRateList = await tax_rates.list({ sdk: stall, query: 'standard' });
+const taxRate = await tax_rates.retrieve({ sdk: stall, id: 'tax_rate_123' });
+const newTaxRate = await tax_rates.create({ sdk: stall, data: { rate: 0.1 } });
+
+// Locations
+const locationList = await locations.list({ sdk: stall, query: 'warehouse' });
+const location = await locations.retrieve({ sdk: stall, id: 'loc_123' });
+const newLocation = await locations.create({ sdk: stall, data: { name: 'Main Warehouse' } });
 ```
 
-## Error Handling
-
-The SDK provides comprehensive error handling with specific error codes:
+### Fulfillment
 
 ```typescript
-import { StallConnectorError, ErrorCodes } from '@use-stall/core';
-
-try {
-  const result = await stall.orders.createOrder(order);
-  if (!result.success) {
-    switch (result.error?.code) {
-      case ErrorCodes.INVALID_CREDENTIALS:
-        console.error('Invalid connector credentials');
-        break;
-      case ErrorCodes.RATE_LIMITED:
-        console.error('Rate limit exceeded');
-        break;
-      case ErrorCodes.OPERATION_TIMEOUT:
-        console.error('Operation timed out');
-        break;
-      default:
-        console.error('Operation failed:', result.error?.message);
-    }
-  }
-} catch (error) {
-  if (error instanceof StallConnectorError) {
-    console.error('Connector error:', error.code, error.message);
-  }
-}
+// Fulfillments
+const fulfillmentList = await fulfillments.list({ sdk: stall, query: 'pending' });
+const fulfillment = await fulfillments.retrieve({ sdk: stall, id: 'ful_123' });
+const newFulfillment = await fulfillments.create({ sdk: stall, data: { order_id: 'order_123' } });
 ```
 
-### Error Codes
+## Adapter Architecture
 
-- **Configuration Errors**: `INVALID_CONFIGURATION`, `MISSING_CREDENTIALS`, `INVALID_CREDENTIALS`
-- **Plugin Errors**: `PLUGIN_LOAD_FAILED`, `PLUGIN_NOT_FOUND`
-- **Operation Errors**: `OPERATION_FAILED`, `OPERATION_TIMEOUT`, `OPERATION_NOT_SUPPORTED`
-- **Network Errors**: `NETWORK_ERROR`, `REQUEST_FAILED`, `RATE_LIMITED`
-- **Validation Errors**: `VALIDATION_FAILED`, `INVALID_DATA`, `MISSING_REQUIRED_FIELD`
-- **Auth Errors**: `UNAUTHORIZED`, `FORBIDDEN`, `TOKEN_EXPIRED`
-- **Server Errors**: `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE`
+### How It Works
 
-## Creating Custom Connector Plugins
+1. **Initialization**: `initializeStallCore()` creates a `CoreConfig` object with your connector settings
+2. **Adapter Loading**: First service call triggers `sdk.adapter()` which:
+   - Checks IndexedDB cache for existing adapter module
+   - If cache exists and valid (TTL not expired): returns cached module
+   - If cache missing or expired: fetches fresh module from connector URL
+   - Stores module in IndexedDB with timestamp
+3. **Module Execution**: Adapter module is imported dynamically and executes the requested operation
+4. **Caching**: Subsequent calls reuse the cached module (up to 4 hours by default)
 
-Connector plugins implement the `IConnectorPlugin` interface:
+### Cache Behavior
 
 ```typescript
-import type { IConnectorPlugin, ConnectorResponse, ConnectorPluginConfig } from '@use-stall/core';
-import type { UnifiedOrderType, UnifiedProductType } from '@use-stall/types';
-
-export class MyConnectorPlugin implements IConnectorPlugin {
-  metadata = {
-    id: 'my-connector',
-    name: 'My Connector',
-    version: '1.0.0',
-    description: 'My custom connector',
-  };
-
-  async initialize(config: ConnectorPluginConfig): Promise<void> {
-    // Initialize your connector with the provided configuration
-    this.endpoint = config.configuration.endpoint;
-    this.token = config.configuration.token;
-  }
-
-  async verify(): Promise<ConnectorResponse<boolean>> {
-    // Verify the connector can connect to the external service
-    try {
-      await this.makeRequest('GET', '/status');
-      return { success: true, data: true };
-    } catch (error) {
-      return {
-        success: false,
-        error: { code: 'CONNECTION_FAILED', message: error.message },
-      };
-    }
-  }
-
-  getSupportedModules(): string[] {
-    return ['orders', 'products', 'customers', 'inventory'];
-  }
-
-  orders = {
-    create: async (order: UnifiedOrderType): Promise<ConnectorResponse<any>> => {
-      // Map from unified format to connector-specific format
-      const connectorOrder = this.mapOrderToConnectorFormat(order);
-      
-      try {
-        const response = await this.makeRequest('POST', '/orders', connectorOrder);
-        return {
-          success: true,
-          data: this.mapOrderToUnifiedFormat(response),
-        };
-      } catch (error) {
-        return {
-          success: false,
-          error: { code: 'CREATE_FAILED', message: error.message },
-        };
-      }
-    },
-
-    get: async (orderId: string): Promise<ConnectorResponse<any>> => {
-      // Implementation
-    },
-
-    update: async (orderId: string, order: Partial<UnifiedOrderType>) => {
-      // Implementation
-    },
-
-    delete: async (orderId: string) => {
-      // Implementation
-    },
-
-    list: async (options?: any) => {
-      // Implementation
-    },
-  };
+// First call - fetches from URL
+const products1 = await products.list({ sdk: stall, query: 'laptop' });
 
-  products = {
-    // Similar implementation for products
-  };
-
-  customers = {
-    // Similar implementation for customers
-  };
+// Subsequent calls within TTL - uses cache
+const products2 = await products.list({ sdk: stall, query: 'shoes' });
+const products3 = await products.list({ sdk: stall, query: 'hats' });
 
-  inventory = {
-    // Similar implementation for inventory
-  };
-
-  refunds = {
-    // Similar implementation for refunds
-  };
-
-  payments = {
-    // Similar implementation for payments
-  };
-}
+// Force refresh
+await stall.refreshAdapter(); // Clears cache, fetches fresh module
 ```
 
-## Logging
+## Error Handling
 
-The SDK includes built-in logging. Control the log level during initialization:
+All service methods are wrapped in try-catch blocks and propagate errors:
 
 ```typescript
-const stall = await StallSDK.initialize({
-  // ... config
-  options: {
-    logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error'
-  },
-});
+try {
+  const product = await products.retrieve({ sdk: stall, id: 'invalid_id' });
+} catch (error) {
+  console.error('Failed to retrieve product:', error.message);
+}
 ```
 
-You can also use the logger directly:
+## Type Safety
 
-```typescript
-import { createLogger } from '@use-stall/core';
+All services use TypeScript types from `@use-stall/types`:
 
-const logger = createLogger('MyApp', 'info');
-logger.info('Application started');
-logger.debug('Debug information');
-logger.warn('Warning message');
-logger.error('Error occurred', error);
+```typescript
+import type {
+  UnifiedProductType,
+  UnifiedOrderType,
+  UnifiedCustomerType,
+  UnifiedVariantsType,
+  UnifiedInventoryLevelType,
+  UnifiedCollectionType,
+  UnifiedCategoryType,
+  UnifiedPromotion,
+  UnifiedOrderNote,
+  UnifiedOrderRefundType,
+  UnifiedPaymentProviderType,
+  UnifiedPaymentCollectionType,
+  UnifiedTaxRegionType,
+  UnifiedTaxRateType,
+  UnifiedLocationType,
+  UnifiedFulfillmentType,
+} from '@use-stall/types';
 ```
 
 ## Configuration
 
-### ConnectorConfigurationType
+### StallCoreConfigOptions
 
 ```typescript
-interface ConnectorConfigurationType {
-  id: string;
-  integration_id: string;
-  created_at: number;
-  updated_at: number;
-  configuration: {
+interface StallCoreConfigOptions {
+  connector_url: string;  // URL to fetch adapter module from
+  version: string;        // SDK/adapter version
+  configuration: {        // Connector-specific credentials
     endpoint: string;
+    token?: string;
     username?: string;
     password?: string;
-    token?: string;
-    api_key_header?: string;
-    api_key_value?: string;
+    api_key?: string;
     [key: string]: any;
   };
 }
 ```
 
-### StallSDKOptions
-
-Extends `ConnectorConfigurationType` from `@use-stall/types`:
+### CoreConfig (Returned from initialization)
 
 ```typescript
-interface StallSDKOptions extends ConnectorConfigurationType {
-  // Inherits: id, integration_id, created_at, updated_at, configuration
-  
-  options?: {
-    timeout?: number;
-    retries?: number;
-    logLevel?: 'debug' | 'info' | 'warn' | 'error';
-    cachePlugins?: boolean;
-    connectorUrl?: string; // Base URL for public connector plugins
-                           // Default: https://connectors.myapp.xyz
-  };
-}
-```
-
-### ConnectorConfigurationType
-
-```typescript
-interface ConnectorConfigurationType {
-  id: string;                    // Configuration ID
-  integration_id: string;        // Integration type (woocommerce, shopify, etc.)
-  created_at: number;            // Timestamp
-  updated_at: number;            // Timestamp
-  configuration: {
-    endpoint: string;            // Platform API endpoint
-    username?: string;           // Basic auth username
-    password?: string;           // Basic auth password
-    token?: string;              // Bearer token
-    api_key_header?: string;     // API key header name
-    api_key_value?: string;      // API key value
-    [key: string]: any;         // Custom fields
-  };
+interface CoreConfig {
+  options: StallCoreConfigOptions;
+  adapter: () => Promise<AdapterModuleType>;      // Get or fetch adapter
+  refreshAdapter: () => Promise<AdapterModuleType>; // Force refresh
 }
 ```
 
 ## Best Practices
 
-1. **Always check the response**: Every SDK operation returns a `ConnectorResponse` that includes a `success` flag.
+1. **Initialize once**: Create the SDK instance once and reuse it
 
 ```typescript
-const result = await stall.orders.createOrder(order);
-if (result.success) {
-  // Handle success
-} else {
-  // Handle error
-  console.error(result.error?.code, result.error?.message);
-}
+const stall = initializeStallCore({ ... });
+// Use stall across your application
 ```
 
-2. **Use TypeScript types**: Leverage the unified types to ensure type safety.
+2. **Use the service imports**: Import services from the main package
 
 ```typescript
-import type { UnifiedOrderType } from '@use-stall/core';
-
-const order: UnifiedOrderType = {
-  id: 'order_123',
-  // ... other required fields
-};
+import { products, orders, customers } from '@use-stall/core';
 ```
 
-3. **Handle module support checking**: Not all connectors support all modules.
+3. **Handle errors properly**: Always wrap calls in try-catch
 
 ```typescript
-if (stall.isModuleSupported('inventory')) {
-  // Safe to use inventory operations
+try {
+  const result = await products.list({ sdk: stall, query: 'search' });
+} catch (error) {
+  // Handle error
 }
 ```
 
-4. **Verify connection on startup**: Always verify the connector is properly configured.
+4. **Leverage bulk operations**: For multiple operations, use bulk methods
 
 ```typescript
-const isConnected = await stall.verify();
-if (!isConnected) {
-  throw new Error('Failed to connect to connector');
-}
+// Better than multiple create() calls
+const items = await products.bulk_create({
+  sdk: stall,
+  data: [
+    { name: 'Product 1' },
+    { name: 'Product 2' },
+    { name: 'Product 3' },
+  ]
+});
 ```
 
-5. **Cache plugins when appropriate**: For better performance, enable plugin caching.
+5. **Type your data**: Use TypeScript types for safety
 
 ```typescript
-options: {
-  cachePlugins: true, // Default: true
-}
-```
+import type { UnifiedProductType } from '@use-stall/types';
 
-## Development with Mock Plugin
-
-For local development and testing, use the `MockConnectorPlugin`:
+const product: UnifiedProductType = {
+  id: 'prod_123',
+  name: 'My Product',
+  // ... other fields
+};
 
-```typescript
-import { MockConnectorPlugin, StallSDK } from '@use-stall/core';
-
-const mockStall = await StallSDK.initializeWithPlugin(
-  {
-    id: 'config_test',
-    integration_id: 'mock',
-    created_at: Date.now(),
-    updated_at: Date.now(),
-    configuration: { /* ... */ },
-  },
-  new MockConnectorPlugin()
-);
+await products.create({ sdk: stall, data: product });
 ```
 
-## Environment Variables
-
-Recommended environment variables for production:
-
-```bash
-# Connector URL (optional, defaults to https://connectors.myapp.xyz)
-CONNECTOR_URL=https://connectors.myapp.xyz
+## File Structure
 
-# Connector-specific credentials (these go in the configuration object)
-WOOCOMMERCE_TOKEN=your_token
-SHOPIFY_TOKEN=your_token
-MEDUSA_API_KEY=your_api_key
 ```
-
-Example usage:
-
-```typescript
-const stall = await StallSDK.initialize({
-  id: 'config_123',
-  integration_id: 'woocommerce',
-  created_at: Date.now(),
-  updated_at: Date.now(),
-  configuration: {
-    endpoint: 'https://myshop.com',
-    token: process.env.WOOCOMMERCE_TOKEN,
-  },
-  options: {
-    connectorUrl: process.env.CONNECTOR_URL || 'https://connectors.myapp.xyz',
-  },
-});
+core/src/
+├── core/
+│   ├── init.ts          (Initialization logic)
+│   └── sdk.ts           (Main exports + documentation)
+├── services/            (Service modules - one per entity)
+│   ├── products.service.ts
+│   ├── orders.service.ts
+│   ├── customers.service.ts
+│   ├── collections.service.ts
+│   ├── categories.service.ts
+│   ├── variants.service.ts
+│   ├── inventory-levels.service.ts
+│   ├── promotions.service.ts
+│   ├── order-notes.service.ts
+│   ├── refunds.service.ts
+│   ├── payment-providers.service.ts
+│   ├── payments.service.ts
+│   ├── tax-regions.service.ts
+│   ├── tax-rates.service.ts
+│   ├── locations.service.ts
+│   └── fulfillments.service.ts
+├── types/
+│   └── core.d.ts        (TypeScript definitions)
+├── db/
+│   ├── db.ts            (Dexie database setup)
+│   ├── schema.ts        (Database schema)
+│   └── helpers.ts       (Database helpers)
+└── index.ts             (Main entry point)
 ```
 
-## License
-
-MIT
+## Service Summary
+
+| Service | Purpose | Operations |
+|---------|---------|-----------|
+| `products` | Product management | CRUD + bulk |
+| `variants` | Product variants | CRUD + bulk |
+| `categories` | Product categories | CRUD + bulk |
+| `collections` | Product collections | CRUD + bulk |
+| `inventory_levels` | Inventory tracking | CRUD + bulk |
+| `orders` | Order management | CRUD + bulk |
+| `order_notes` | Order comments/notes | CRUD + bulk |
+| `refunds` | Refund management | CRUD + bulk |
+| `customers` | Customer management | CRUD + bulk |
+| `promotions` | Promotions/discounts | CRUD + bulk |
+| `payment_providers` | Payment providers | CRUD + bulk |
+| `payments` | Payment transactions | CRUD + bulk |
+| `tax_regions` | Tax configuration | CRUD + bulk |
+| `tax_rates` | Tax rates | CRUD + bulk |
+| `locations` | Store locations | CRUD + bulk |
+| `fulfillments` | Order fulfillment | CRUD + bulk |
+
+## Development
+
+Built with Bun and TypeScript. The SDK uses:
+
+- **Dexie.js** for IndexedDB management
+- **@use-stall/types** for unified type definitions
+- **TypeScript** for type safety
 
-## Support
+## License
 
-For issues, questions, or contributions, please visit the Stall GitHub repository.
+MIT