@use-stall/core 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,562 @@
+# Stall Universal Connector 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.
+
+## Overview
+
+The Stall SDK provides a plugin-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
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│        Your Application             │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│      StallSDK (Main Entry)          │
+│  - Firebase-style initialization    │
+│  - Service management               │
+└──────────────┬──────────────────────┘
+               │
+        ┌──────┴──────┐
+        │             │
+┌───────▼─────┐  ┌────▼──────────┐
+│   Orders    │  │   Products    │
+│  Service    │  │   Service     │
+└───────┬─────┘  └────┬──────────┘
+        │             │
+        └──────┬──────┘
+               │
+     ┌─────────▼──────────┐
+     │  Plugin Manager    │
+     │  - Lifecycle       │
+     │  - Verification    │
+     └─────────┬──────────┘
+               │
+     ┌─────────▼──────────┐
+     │ Connector Loader   │
+     │ - Public URL       │
+     │ - Caching          │
+     └─────────┬──────────┘
+               │
+     ┌─────────▼──────────┐
+     │  Plugin Instance   │
+     │  (WooCommerce,     │
+     │   Shopify, 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
+
+```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
+
+```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(),
+  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
+
+```typescript
+// Create an order
+const result = await stall.orders.createOrder(unifiedOrder);
+
+// Get an order
+const result = await stall.orders.getOrder('order_id');
+
+// Update an order
+const result = await stall.orders.updateOrder('order_id', { status: 'completed' });
+
+// Delete/cancel an order
+const result = await stall.orders.deleteOrder('order_id');
+
+// List orders
+const result = await stall.orders.listOrders({ limit: 20, offset: 0 });
+
+// Create a refund
+const result = await stall.orders.createRefund('order_id', refundData);
+
+// Get a refund
+const result = await stall.orders.getRefund('refund_id');
+
+// List refunds
+const result = await stall.orders.listRefunds('order_id');
+```
+
+### Products Service
+
+```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 });
+
+// Delete a product
+const result = await stall.products.deleteProduct('product_id');
+
+// List products
+const result = await stall.products.listProducts({ 
+  limit: 50,
+  category: 'electronics' 
+});
+```
+
+## Types
+
+### Unified Types
+
+The SDK uses unified types from `@use-stall/types`:
+
+```typescript
+import type { 
+  UnifiedOrderType,
+  UnifiedProductType,
+  UnifiedOrderRefundType,
+  ConnectorConfigurationType,
+} from '@use-stall/core';
+```
+
+### Response Format
+
+All operations return a standardized response:
+
+```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;
+  };
+}
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling with specific error codes:
+
+```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);
+  }
+}
+```
+
+### Error Codes
+
+- **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`
+
+## Creating Custom Connector Plugins
+
+Connector plugins implement the `IConnectorPlugin` interface:
+
+```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
+    },
+  };
+
+  products = {
+    // Similar implementation for products
+  };
+
+  customers = {
+    // Similar implementation for customers
+  };
+
+  inventory = {
+    // Similar implementation for inventory
+  };
+
+  refunds = {
+    // Similar implementation for refunds
+  };
+
+  payments = {
+    // Similar implementation for payments
+  };
+}
+```
+
+## Logging
+
+The SDK includes built-in logging. Control the log level during initialization:
+
+```typescript
+const stall = await StallSDK.initialize({
+  // ... config
+  options: {
+    logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error'
+  },
+});
+```
+
+You can also use the logger directly:
+
+```typescript
+import { createLogger } from '@use-stall/core';
+
+const logger = createLogger('MyApp', 'info');
+logger.info('Application started');
+logger.debug('Debug information');
+logger.warn('Warning message');
+logger.error('Error occurred', error);
+```
+
+## Configuration
+
+### ConnectorConfigurationType
+
+```typescript
+interface ConnectorConfigurationType {
+  id: string;
+  integration_id: string;
+  created_at: number;
+  updated_at: number;
+  configuration: {
+    endpoint: string;
+    username?: string;
+    password?: string;
+    token?: string;
+    api_key_header?: string;
+    api_key_value?: string;
+    [key: string]: any;
+  };
+}
+```
+
+### StallSDKOptions
+
+Extends `ConnectorConfigurationType` from `@use-stall/types`:
+
+```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
+  };
+}
+```
+
+## Best Practices
+
+1. **Always check the response**: Every SDK operation returns a `ConnectorResponse` that includes a `success` flag.
+
+```typescript
+const result = await stall.orders.createOrder(order);
+if (result.success) {
+  // Handle success
+} else {
+  // Handle error
+  console.error(result.error?.code, result.error?.message);
+}
+```
+
+2. **Use TypeScript types**: Leverage the unified types to ensure type safety.
+
+```typescript
+import type { UnifiedOrderType } from '@use-stall/core';
+
+const order: UnifiedOrderType = {
+  id: 'order_123',
+  // ... other required fields
+};
+```
+
+3. **Handle module support checking**: Not all connectors support all modules.
+
+```typescript
+if (stall.isModuleSupported('inventory')) {
+  // Safe to use inventory operations
+}
+```
+
+4. **Verify connection on startup**: Always verify the connector is properly configured.
+
+```typescript
+const isConnected = await stall.verify();
+if (!isConnected) {
+  throw new Error('Failed to connect to connector');
+}
+```
+
+5. **Cache plugins when appropriate**: For better performance, enable plugin caching.
+
+```typescript
+options: {
+  cachePlugins: true, // Default: true
+}
+```
+
+## Development with Mock Plugin
+
+For local development and testing, use the `MockConnectorPlugin`:
+
+```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()
+);
+```
+
+## Environment Variables
+
+Recommended environment variables for production:
+
+```bash
+# Connector URL (optional, defaults to https://connectors.myapp.xyz)
+CONNECTOR_URL=https://connectors.myapp.xyz
+
+# 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',
+  },
+});
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues, questions, or contributions, please visit the Stall GitHub repository.