@use-stall/core 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,477 @@
+# Stall Core SDK
+
+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 Core SDK provides an adapter-based architecture that allows you to:
+
+- **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
+
+```
+┌─────────────────────────────────────┐
+│        Your Application             │
+└──────────────┬──────────────────────┘
+               │
+       ┌───────▼──────────────────┐
+       │  initializeStallCore()
+       │  Returns: CoreConfig
+       └───────┬──────────────────┘
+               │          
+    ┌──────────▼──────────┐
+    │   Service Layer     │
+    ├─────────────────────┤
+    │ - products          │
+    │ - orders            │
+    │ - customers         │
+    │ - variants          │
+    │ - inventory_levels  │
+    │ - promotions        │
+    │ - refunds           │
+    │ - payments          │
+    │ - tax_regions       │
+    │ - locations         │
+    │ - fulfillments      │
+    │ - ... and more      │
+    └──────────┬──────────┘
+               │
+    ┌──────────▼──────────────────┐
+    │  Adapter Module (Cached)    │
+    │  ┌───────────────────────┐  │
+    │  │ - Products module     │  │
+    │  │ - Orders module       │  │
+    │  │ - Customers module    │  │
+    │  │ - All modules         │  │
+    │  └───────────────────────┘  │
+    │                             │
+    │  Storage: IndexedDB + Dexie │
+    │  TTL: 4 hours (configurable)│
+    └──────────┬──────────────────┘
+               │
+    ┌──────────▼──────────────────┐
+    │   Connector Loader          │
+    │  (Dynamic Module Import)    │
+    └──────────┬──────────────────┘
+               │
+    ┌──────────▼──────────────────┐
+    │  Commerce Platform API      │
+    │  (WooCommerce, Shopify,     │
+    │  Medusa,Google Sheets etc.) │
+    └─────────────────────────────┘
+```
+
+## Installation
+
+```bash
+bun install @use-stall/core
+```
+
+## Quick Start
+
+### Initialize the SDK
+
+```typescript
+import { initializeStallCore, products, orders, customers } from '@use-stall/core';
+
+// 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,
+  },
+});
+```
+
+### Use Any Service
+
+```typescript
+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);
+}
+```
+
+## Available Services
+
+### Core CRUD Operations
+
+Each service module provides 8 standard operations:
+
+- **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
+
+### Inventory & Catalog
+
+```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'] });
+```
+
+### Order Management
+
+```typescript
+// 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 } });
+```
+
+### Customer Management
+
+```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' });
+```
+
+### Promotions
+
+```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' } });
+```
+
+### Payment Management
+
+```typescript
+// 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 } });
+```
+
+### Tax & Location
+
+```typescript
+// 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' } });
+```
+
+### Fulfillment
+
+```typescript
+// 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' } });
+```
+
+## Adapter Architecture
+
+### How It Works
+
+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)
+
+### Cache Behavior
+
+```typescript
+// First call - fetches from URL
+const products1 = await products.list({ sdk: stall, query: 'laptop' });
+
+// Subsequent calls within TTL - uses cache
+const products2 = await products.list({ sdk: stall, query: 'shoes' });
+const products3 = await products.list({ sdk: stall, query: 'hats' });
+
+// Force refresh
+await stall.refreshAdapter(); // Clears cache, fetches fresh module
+```
+
+## Error Handling
+
+All service methods are wrapped in try-catch blocks and propagate errors:
+
+```typescript
+try {
+  const product = await products.retrieve({ sdk: stall, id: 'invalid_id' });
+} catch (error) {
+  console.error('Failed to retrieve product:', error.message);
+}
+```
+
+## Type Safety
+
+All services use TypeScript types from `@use-stall/types`:
+
+```typescript
+import type {
+  UnifiedProductType,
+  UnifiedOrderType,
+  UnifiedCustomerType,
+  UnifiedVariantsType,
+  UnifiedInventoryLevelType,
+  UnifiedCollectionType,
+  UnifiedCategoryType,
+  UnifiedPromotion,
+  UnifiedOrderNote,
+  UnifiedOrderRefundType,
+  UnifiedPaymentProviderType,
+  UnifiedPaymentCollectionType,
+  UnifiedTaxRegionType,
+  UnifiedTaxRateType,
+  UnifiedLocationType,
+  UnifiedFulfillmentType,
+} from '@use-stall/types';
+```
+
+## Configuration
+
+### StallCoreConfigOptions
+
+```typescript
+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;
+    api_key?: string;
+    [key: string]: any;
+  };
+}
+```
+
+### CoreConfig (Returned from initialization)
+
+```typescript
+interface CoreConfig {
+  options: StallCoreConfigOptions;
+  adapter: () => Promise<AdapterModuleType>;      // Get or fetch adapter
+  refreshAdapter: () => Promise<AdapterModuleType>; // Force refresh
+}
+```
+
+## Best Practices
+
+1. **Initialize once**: Create the SDK instance once and reuse it
+
+```typescript
+const stall = initializeStallCore({ ... });
+// Use stall across your application
+```
+
+2. **Use the service imports**: Import services from the main package
+
+```typescript
+import { products, orders, customers } from '@use-stall/core';
+```
+
+3. **Handle errors properly**: Always wrap calls in try-catch
+
+```typescript
+try {
+  const result = await products.list({ sdk: stall, query: 'search' });
+} catch (error) {
+  // Handle error
+}
+```
+
+4. **Leverage bulk operations**: For multiple operations, use bulk methods
+
+```typescript
+// Better than multiple create() calls
+const items = await products.bulk_create({
+  sdk: stall,
+  data: [
+    { name: 'Product 1' },
+    { name: 'Product 2' },
+    { name: 'Product 3' },
+  ]
+});
+```
+
+5. **Type your data**: Use TypeScript types for safety
+
+```typescript
+import type { UnifiedProductType } from '@use-stall/types';
+
+const product: UnifiedProductType = {
+  id: 'prod_123',
+  name: 'My Product',
+  // ... other fields
+};
+
+await products.create({ sdk: stall, data: product });
+```
+
+## File Structure
+
+```
+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)
+```
+
+## 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
+
+## License
+
+MIT