@commercengine/pos 0.1.0

package/README.md

@@ -0,0 +1,552 @@
+# @commercengine/pos
+
+TypeScript SDK for the Commerce Engine Point of Sale (POS) API. This package provides a complete interface to manage POS operations including authentication, cart management, orders, promotions, and customer interactions.
+
+## Installation
+
+```bash
+npm install @commercengine/pos
+# or
+yarn add @commercengine/pos
+# or
+pnpm add @commercengine/pos
+```
+
+## Quick Start
+
+```typescript
+import { PosSDK } from '@commercengine/pos';
+
+// Initialize the SDK
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+});
+
+// Login with email (returns OTP token)
+const { data: loginData, error: loginError } = await pos.pos.loginWithEmail({
+  device_id: 'device-123',
+  email: 'cashier@store.com'
+});
+
+if (loginError) {
+  console.error('Login failed:', loginError);
+  return;
+}
+
+// Verify OTP to get access tokens
+const { data: authData, error: authError } = await pos.pos.verifyOtp({
+  otp_token: loginData.otp_token,
+  otp: '123456'
+});
+
+if (authError) {
+  console.error('OTP verification failed:', authError);
+  return;
+}
+
+// Now you can make authenticated requests
+const { data: cartData, error: cartError } = await pos.pos.createCart({
+  currency: 'USD'
+});
+
+if (cartData) {
+  console.log('Cart created:', cartData);
+}
+```
+
+## Configuration Options
+
+The `PosSDK` constructor accepts a `PosSDKOptions` object with the following configuration:
+
+### Required Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `storeId` | `string` | Your Commerce Engine store ID |
+| `apiKey` | `string` | API key for authentication endpoints (required for all POS operations) |
+
+### Optional Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `environment` | `Environment` | API environment (`Environment.Production`, `Environment.Staging`, `Environment.Development`) |
+| `baseUrl` | `string` | Custom base URL (overrides environment setting) |
+| `accessToken` | `string` | Initial access token (if you already have one) |
+| `refreshToken` | `string` | Initial refresh token (requires `tokenStorage`) |
+| `tokenStorage` | `TokenStorage` | Automatic token management (recommended) |
+| `onTokensUpdated` | `function` | Callback when tokens are refreshed |
+| `onTokensCleared` | `function` | Callback when tokens are cleared/expired |
+| `timeout` | `number` | Request timeout in milliseconds |
+| `defaultHeaders` | `SupportedDefaultHeaders` | Default headers for all requests |
+| `debug` | `boolean` | Enable debug logging |
+| `logger` | `DebugLoggerFn` | Custom debug logger function |
+
+### BaseSDKOptions (inherited from @commercengine/sdk-core)
+
+The POS SDK extends the base SDK configuration with these inherited options:
+
+- **baseUrl**: Custom API base URL
+- **timeout**: Request timeout (default: 30000ms)  
+- **defaultHeaders**: Default headers applied to all requests
+- **debug**: Enable request/response logging
+- **logger**: Custom logger function for debug output
+
+### Advanced Configuration
+
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  environment: Environment.Production,
+  
+  // Token Management
+  accessToken: 'initial-access-token',     // Initial access token
+  refreshToken: 'initial-refresh-token',   // Initial refresh token (requires tokenStorage)
+  
+  // Custom base URL (optional, overrides environment)
+  baseUrl: 'https://your-custom-api.example.com',
+  
+  // Request Configuration
+  timeout: 10000,                          // Request timeout in milliseconds
+  
+  // Default Headers (auto applied to all applicable requests)
+  defaultHeaders: {
+    customer_group_id: '01JHS28V83KDWTRBXXJQRTEKA0', // For pricing and promotions
+  },
+  
+  // Debug and Logging
+  debug: true,                             // Enable detailed request/response logging
+  logger: console.log,                     // Custom logger function
+});
+```
+
+### Supported Default Headers
+
+```typescript
+interface SupportedDefaultHeaders {
+  /**
+   * Customer group ID used for pricing and promotions
+   */
+  customer_group_id?: string;
+}
+```
+
+## Token Management
+
+The POS SDK supports three token management strategies:
+
+### 1. Automatic Token Management (Recommended)
+
+```typescript
+import { PosSDK, BrowserTokenStorage } from '@commercengine/pos';
+
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  tokenStorage: new BrowserTokenStorage(), // or new MemoryTokenStorage()
+  onTokensUpdated: (accessToken, refreshToken) => {
+    console.log('Tokens updated');
+  },
+  onTokensCleared: () => {
+    console.log('User logged out');
+  }
+});
+```
+
+### 2. Manual Token Management
+
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  accessToken: 'existing-access-token'
+});
+
+// Update tokens manually
+await pos.setTokens('new-access-token', 'new-refresh-token');
+```
+
+### 3. Initialize with Existing Tokens
+
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  accessToken: 'existing-access-token',
+  refreshToken: 'existing-refresh-token',
+  tokenStorage: new BrowserTokenStorage() // Enables automatic refresh
+});
+```
+
+## Token Storage Options
+
+### BrowserTokenStorage
+Stores tokens in `localStorage` with customizable prefix:
+
+```typescript
+import { BrowserTokenStorage } from '@commercengine/pos';
+
+const storage = new BrowserTokenStorage('my_pos_'); // prefix: default 'pos_'
+```
+
+### MemoryTokenStorage  
+Stores tokens in memory (lost on page refresh):
+
+```typescript
+import { MemoryTokenStorage } from '@commercengine/pos';
+
+const storage = new MemoryTokenStorage();
+```
+
+### Custom TokenStorage
+Implement the `TokenStorage` interface for custom storage:
+
+```typescript
+import { TokenStorage } from '@commercengine/pos';
+
+class CustomTokenStorage implements TokenStorage {
+  async getAccessToken(): Promise<string | null> { /* ... */ }
+  async setAccessToken(token: string): Promise<void> { /* ... */ }
+  async getRefreshToken(): Promise<string | null> { /* ... */ }
+  async setRefreshToken(token: string): Promise<void> { /* ... */ }
+  async clearTokens(): Promise<void> { /* ... */ }
+}
+```
+
+## Authentication Flow
+
+The POS SDK uses a two-step authentication process:
+
+### Step 1: Login (Request OTP)
+
+```typescript
+// Login with email
+const { data: emailData, error: emailError } = await pos.pos.loginWithEmail({
+  device_id: 'unique-device-id',
+  email: 'user@example.com'
+});
+
+if (emailError) {
+  console.error('Email login failed:', emailError);
+  return;
+}
+
+// Login with phone
+const { data: phoneData, error: phoneError } = await pos.pos.loginWithPhone({
+  device_id: 'unique-device-id',
+  phone: '+1234567890'
+});
+
+// Login with WhatsApp
+const { data: whatsappData, error: whatsappError } = await pos.pos.loginWithWhatsapp({
+  device_id: 'unique-device-id',
+  phone: '+1234567890'
+});
+```
+
+### Step 2: Verify OTP
+
+```typescript
+const { data: authData, error: authError } = await pos.pos.verifyOtp({
+  otp_token: emailData.otp_token,
+  otp: '123456'
+});
+
+if (authError) {
+  console.error('OTP verification failed:', authError);
+  return;
+}
+
+// Access token and refresh token are now automatically stored
+// if tokenStorage is configured
+console.log('Authentication successful:', authData);
+```
+
+### Device Pairing
+
+For new devices, you may need to pair first:
+
+```typescript
+const { data: pairData, error: pairError } = await pos.pos.pairDevice({
+  pairing_code: 'ABC123'
+});
+
+if (pairError) {
+  console.error('Device pairing failed:', pairError);
+  return;
+}
+
+console.log('Device paired successfully:', pairData);
+```
+
+## API Operations
+
+The POS SDK provides access to all POS operations through the `pos` property:
+
+### Authentication
+- `loginWithEmail()` - Login with email address
+- `loginWithPhone()` - Login with phone number  
+- `loginWithWhatsapp()` - Login with WhatsApp
+- `pairDevice()` - Pair a new device
+- `verifyOtp()` - Verify OTP and get tokens
+- `refreshToken()` - Refresh access token
+
+### Cart Management
+- `createCart()` - Create a new cart
+- `getCart()` - Get cart details
+- `updateCart()` - Update cart information
+- `deleteCart()` - Delete cart
+
+### Cart Items (coming soon)
+- Add/remove/update line items
+- Apply discounts and promotions
+
+### Orders
+- `createOrder()` - Create order from cart
+
+### Promotions & Coupons
+- `listPromotions()` - Get available promotions
+- `evaluatePromotions()` - Calculate promotion discounts
+- `listCoupons()` - Get available coupons
+- `applyCoupon()` - Apply coupon to cart
+- `removeCoupon()` - Remove coupon from cart
+
+### Gift Cards & Loyalty
+- `redeemGiftCard()` - Apply gift card to cart
+- `removeGiftCard()` - Remove gift card from cart
+- `redeemLoyaltyPoints()` - Apply loyalty points
+- `removeLoyaltyPoints()` - Remove loyalty points
+
+### Fulfillment
+- `updateFulfillmentPreference()` - Set pickup/delivery options
+- `getFulfillmentOptions()` - Get available fulfillment methods
+
+## User Information
+
+Access user information from JWT tokens:
+
+```typescript
+// Get complete user information
+const userInfo = await pos.getUserInfo();
+console.log(userInfo?.email, userInfo?.device, userInfo?.location);
+
+// Get specific information
+const userId = await pos.getUserId();
+const deviceId = await pos.getDeviceId(); 
+const locationId = await pos.getLocationId();
+const role = await pos.getRole();
+
+// Check authentication status
+const isLoggedIn = await pos.isLoggedIn();
+const isAuthenticated = await pos.isAuthenticated();
+```
+
+## Error Handling
+
+The SDK returns `ApiResult<T>` objects with consistent error handling:
+
+```typescript
+const { data, error, response } = await pos.pos.createCart({ currency: 'USD' });
+
+if (error) {
+  console.error('Error:', error.message);
+  console.error('HTTP Status:', response?.status);
+} else {
+  console.log('Cart created:', data);
+}
+
+// Alternative pattern - checking for data
+if (data) {
+  console.log('Cart created:', data);
+} else {
+  console.error('Failed to create cart:', error);
+}
+```
+
+## Environment Configuration
+
+### Production (Default)
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  // Uses production environment by default
+});
+```
+
+### Staging
+```typescript
+import { PosSDK, Environment } from '@commercengine/pos';
+
+const pos = new PosSDK({
+  storeId: 'your-store-id', 
+  apiKey: 'your-api-key',
+  environment: Environment.Staging
+});
+```
+
+### Custom Base URL
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key', 
+  baseUrl: 'https://custom-api.yourstore.com/api/v1/your-store-id/storefront'
+});
+```
+
+## Debug Mode
+
+Enable debug logging to troubleshoot API requests:
+
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  debug: true,
+  logger: (message, data) => {
+    console.log(`[POS SDK] ${message}`, data);
+  }
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type safety:
+
+```typescript
+import type { 
+  PosCreateCartBody,
+  PosCreateCartContent,
+  UserInfo,
+  TokenStorage 
+} from '@commercengine/pos';
+
+// All API methods are fully typed
+const cart: ApiResult<PosCreateCartContent> = await pos.pos.createCart({
+  currency: 'USD' // TypeScript validates this structure
+});
+```
+
+## Best Practices
+
+### 1. Always Use Token Storage
+Enable automatic token management to handle expiry and refresh:
+
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  tokenStorage: new BrowserTokenStorage()
+});
+```
+
+### 2. Handle Token Events
+Listen for token events to update your application state:
+
+```typescript
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key',
+  tokenStorage: new BrowserTokenStorage(),
+  onTokensUpdated: (accessToken, refreshToken) => {
+    // User successfully authenticated or tokens refreshed
+    updateUIForLoggedInState();
+  },
+  onTokensCleared: () => {
+    // Tokens expired or user logged out
+    redirectToLogin();
+  }
+});
+```
+
+### 3. Error Handling Pattern
+Always check for error before accessing data:
+
+```typescript
+const { data, error, response } = await pos.pos.getCart({ cart_id: 'cart-123' });
+
+if (error) {
+  if (response?.status === 404) {
+    // Cart not found
+    showMessage('Cart not found');
+  } else {
+    // Other error
+    showErrorMessage(error.message);
+  }
+} else {
+  displayCart(data);
+}
+```
+
+### 4. Use Device IDs Consistently
+Keep device IDs consistent across sessions:
+
+```typescript
+// Store device ID in localStorage
+const deviceId = localStorage.getItem('pos_device_id') || generateDeviceId();
+localStorage.setItem('pos_device_id', deviceId);
+
+// Use in all authentication calls  
+await pos.pos.loginWithEmail({
+  device_id: deviceId,
+  email: 'user@example.com'
+});
+```
+
+## Migration from Other SDKs
+
+If you're migrating from the storefront SDK:
+
+### Key Differences
+- **API Key Required**: POS SDK requires `apiKey` for all operations
+- **Two-Step Auth**: Login returns OTP token, must verify with `verifyOtp()`
+- **Device Context**: All operations are scoped to a specific device and location
+- **No Anonymous Mode**: POS SDK requires explicit authentication
+
+### Updated Initialization
+```typescript
+// Old (storefront)
+const storefront = new StorefrontSDK({
+  storeId: 'your-store-id'
+  // apiKey was optional
+});
+
+// New (POS) 
+const pos = new PosSDK({
+  storeId: 'your-store-id',
+  apiKey: 'your-api-key' // Now required
+});
+```
+
+## Package Information
+
+- **Version**: 0.0.0 (pre-release)
+- **License**: All rights reserved
+- **Dependencies**: 
+  - `@commercengine/sdk-core` - Core SDK functionality
+  - `jose` - JWT token handling
+  - `openapi-fetch` - Type-safe API client
+
+## Development
+
+### Generate Types
+Types are auto-generated from the OpenAPI specification:
+
+```bash
+pnpm run codegen
+```
+
+### Build
+```bash
+pnpm run build
+```
+
+### Type Checking
+```bash
+pnpm run check-exports
+```
+
+## Support
+
+For issues, questions, or feature requests, please contact the Commerce Engine team or check the main repository documentation.