@commercengine/pos 0.1.3 → 0.3.0

package/README.md

@@ -24,7 +24,7 @@ const pos = new PosSDK({
 });
 
 // Login with email (returns OTP token)
-const { data: loginData, error: loginError } = await pos.pos.loginWithEmail({
+const { data: loginData, error: loginError } = await pos.loginWithEmail({
   device_id: 'device-123',
   email: 'cashier@store.com'
 });
@@ -35,7 +35,7 @@ if (loginError) {
 }
 
 // Verify OTP to get access tokens
-const { data: authData, error: authError } = await pos.pos.verifyOtp({
+const { data: authData, error: authError } = await pos.verifyOtp({
   otp_token: loginData.otp_token,
   otp: '123456'
 });
@@ -46,8 +46,14 @@ if (authError) {
 }
 
 // Now you can make authenticated requests
-const { data: cartData, error: cartError } = await pos.pos.createCart({
-  currency: 'USD'
+const { data: cartData, error: cartError } = await pos.createCart({
+  items: [
+    {
+      product_id: "01H9XYZ12345ABCDE",
+      variant_id: null,
+      quantity: 2
+    }
+  ]
 });
 
 if (cartData) {
@@ -222,7 +228,7 @@ The POS SDK uses a two-step authentication process:
 
 ```typescript
 // Login with email
-const { data: emailData, error: emailError } = await pos.pos.loginWithEmail({
+const { data: emailData, error: emailError } = await pos.loginWithEmail({
   device_id: 'unique-device-id',
   email: 'user@example.com'
 });
@@ -233,13 +239,13 @@ if (emailError) {
 }
 
 // Login with phone
-const { data: phoneData, error: phoneError } = await pos.pos.loginWithPhone({
+const { data: phoneData, error: phoneError } = await pos.loginWithPhone({
   device_id: 'unique-device-id',
   phone: '+1234567890'
 });
 
 // Login with WhatsApp
-const { data: whatsappData, error: whatsappError } = await pos.pos.loginWithWhatsapp({
+const { data: whatsappData, error: whatsappError } = await pos.loginWithWhatsapp({
   device_id: 'unique-device-id',
   phone: '+1234567890'
 });
@@ -248,7 +254,7 @@ const { data: whatsappData, error: whatsappError } = await pos.pos.loginWithWhat
 ### Step 2: Verify OTP
 
 ```typescript
-const { data: authData, error: authError } = await pos.pos.verifyOtp({
+const { data: authData, error: authError } = await pos.verifyOtp({
   otp_token: emailData.otp_token,
   otp: '123456'
 });
@@ -268,7 +274,7 @@ console.log('Authentication successful:', authData);
 For new devices, you may need to pair first:
 
 ```typescript
-const { data: pairData, error: pairError } = await pos.pos.pairDevice({
+const { data: pairData, error: pairError } = await pos.pairDevice({
   pairing_code: 'ABC123'
 });
 
@@ -282,7 +288,7 @@ console.log('Device paired successfully:', pairData);
 
 ## API Operations
 
-The POS SDK provides access to all POS operations through the `pos` property:
+The POS SDK provides access to all POS operations directly on the SDK instance:
 
 ### Authentication
 - `loginWithEmail()` - Login with email address
@@ -290,38 +296,74 @@ The POS SDK provides access to all POS operations through the `pos` property:
 - `loginWithWhatsapp()` - Login with WhatsApp
 - `pairDevice()` - Pair a new device
 - `verifyOtp()` - Verify OTP and get tokens
-- `refreshToken()` - Refresh access token
+- `refreshAccessToken()` - Refresh access token
+- `logout()` - Logout from POS device
 
 ### Cart Management
-- `createCart()` - Create a new cart
+- `createCart()` - Create a new cart with items
 - `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
+- `updateCart()` - Add/update/remove cart items
+- `deleteCart()` - Delete entire cart
+- `createCartAddress()` - Set billing/shipping addresses
+- `updateCartCustomer()` - Associate customer with cart
 
 ### Promotions & Coupons
 - `listPromotions()` - Get available promotions
-- `evaluatePromotions()` - Calculate promotion discounts
+- `evaluatePromotions()` - Calculate promotion discounts for cart
 - `listCoupons()` - Get available coupons
 - `applyCoupon()` - Apply coupon to cart
 - `removeCoupon()` - Remove coupon from cart
+- `evaluateCoupons()` - Check applicable/inapplicable coupons
 
-### Gift Cards & Loyalty
-- `redeemGiftCard()` - Apply gift card to cart
-- `removeGiftCard()` - Remove gift card from cart
-- `redeemLoyaltyPoints()` - Apply loyalty points
-- `removeLoyaltyPoints()` - Remove loyalty points
+### Credit Balance & Loyalty
+- `redeemCreditBalance()` - Apply credit balance to cart
+- `removeCreditBalance()` - Remove credit balance from cart
+- `redeemLoyaltyPoints()` - Apply loyalty points to cart
+- `removeLoyaltyPoints()` - Remove loyalty points from cart
 
 ### Fulfillment
 - `updateFulfillmentPreference()` - Set pickup/delivery options
 - `getFulfillmentOptions()` - Get available fulfillment methods
 
+### Orders
+- `createOrder()` - Create order from cart
+- `listOrders()` - List orders (Admin)
+- `getOrderDetail()` - Get order details (Admin)
+- `listOrderActivity()` - Get order activity log (Admin)
+- `getOrderInvoice()` - Get order invoice (Admin)
+- `getOrderReceipt()` - Get order receipt (Admin)
+- `getOrderShipments()` - Get order shipments (Admin)
+
+### Catalog & Products
+- `listCategories()` - List product categories
+- `listProducts()` - List products with filtering
+- `getProductDetail()` - Get product details
+- `listProductVariants()` - Get product variants
+- `getVariantDetail()` - Get variant details
+- `listProductReviews()` - Get product reviews
+- `searchProducts()` - Search products with filters
+- `listCrosssellProducts()` - Get cross-sell recommendations
+- `listSimilarProducts()` - Get similar product recommendations
+- `listUpsellProducts()` - Get up-sell recommendations
+- `listSkus()` - List all SKUs
+
+### Inventory (Admin)
+- `listInventories()` - List inventory levels
+- `listInventoryActivities()` - List inventory activities
+- `getInventoryDetail()` - Get inventory details
+
+### Customers (Admin)
+- `getCustomers()` - List customers
+- `getCustomer()` - Get customer details
+
+### Shipments (Admin)
+- `listShipments()` - List shipments
+- `getShipment()` - Get shipment details
+- `updateShipment()` - Update shipment status
+- `getShipmentInvoice()` - Get shipment invoice
+- `checkInventory()` - Check inventory for order
+- `refundShortfall()` - Process refund for shortfall
+
 ## User Information
 
 Access user information from JWT tokens:
@@ -347,7 +389,15 @@ const isAuthenticated = await pos.isAuthenticated();
 The SDK returns `ApiResult<T>` objects with consistent error handling:
 
 ```typescript
-const { data, error, response } = await pos.pos.createCart({ currency: 'USD' });
+const { data, error, response } = await pos.createCart({
+  items: [
+    {
+      product_id: "01H9XYZ12345ABCDE",
+      variant_id: null,
+      quantity: 2
+    }
+  ]
+});
 
 if (error) {
   console.error('Error:', error.message);
@@ -412,19 +462,39 @@ const pos = new PosSDK({
 
 ## TypeScript Support
 
-The SDK is written in TypeScript and provides full type safety:
+The SDK is written in TypeScript and provides full type safety with advanced schema handling:
+
+### Schema-Specific Typing
+The POS SDK handles both regular storefront operations and admin operations with proper type safety. When both schemas define the same endpoint (like `/pos/orders`), the SDK automatically uses the appropriate schema based on the operation:
+
+```typescript
+// Regular POS operation (POST) - uses storefront schema
+await pos.createOrder({ cart_id: "cart-123" });
+
+// Admin POS operation (GET) - uses admin schema  
+await pos.listOrders({ page: 1, limit: 10 });
+```
+
+This ensures you get proper TypeScript autocompletion and validation for each operation without any type conflicts.
 
 ```typescript
 import type { 
   PosCreateCartBody,
   PosCreateCartContent,
   UserInfo,
-  TokenStorage 
+  TokenStorage,
+  ApiResult
 } from '@commercengine/pos';
 
 // All API methods are fully typed
-const cart: ApiResult<PosCreateCartContent> = await pos.pos.createCart({
-  currency: 'USD' // TypeScript validates this structure
+const cart: ApiResult<PosCreateCartContent> = await pos.createCart({
+  items: [
+    {
+      product_id: "01H9XYZ12345ABCDE",
+      variant_id: null,
+      quantity: 2
+    }
+  ] // TypeScript validates this structure
 });
 ```
 
@@ -464,7 +534,7 @@ const pos = new PosSDK({
 Always check for error before accessing data:
 
 ```typescript
-const { data, error, response } = await pos.pos.getCart({ cart_id: 'cart-123' });
+const { data, error, response } = await pos.getCart({ id: 'cart-123' });
 
 if (error) {
   if (response?.status === 404) {
@@ -488,7 +558,7 @@ const deviceId = localStorage.getItem('pos_device_id') || generateDeviceId();
 localStorage.setItem('pos_device_id', deviceId);
 
 // Use in all authentication calls  
-await pos.pos.loginWithEmail({
+await pos.loginWithEmail({
   device_id: deviceId,
   email: 'user@example.com'
 });