washday-sdk 1.0.2 → 1.1.1

package/docs/examples/common-use-cases.md

@@ -0,0 +1,487 @@
+# 📋 Common Use Cases
+
+This guide provides practical examples for common scenarios you'll encounter when integrating with the Washday API.
+
+## 🏢 Store Management
+
+### Get Store Information
+```typescript
+const client = new WashdayClient('your-token');
+
+// Get a specific store
+const store = await client.stores.getStoreById('store-id');
+console.log(`Store: ${store.data.name} - ${store.data.city}`);
+
+// Get all active stores
+const stores = await client.stores.getStores({ isActive: 'true' });
+stores.data.forEach(store => {
+    console.log(`${store.name}: ${store.phone}`);
+});
+```
+
+### Update Store Settings
+```typescript
+// Update store configuration
+await client.stores.updateStoreById('store-id', {
+    phone: '+1-555-0123',
+    allowPrePaid: true,
+    attendanceConfig: {
+        maxShiftHours: 10,
+        requireClockInOnLogin: true
+    }
+});
+```
+
+## 👥 Employee Management
+
+### Complete Attendance Workflow
+```typescript
+async function manageEmployeeShift(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    // Check if employee is already clocked in
+    const status = await client.attendance.getStatus({ storeId });
+    
+    if (status.active) {
+        console.log('Employee is already clocked in');
+        
+        // Clock out
+        const clockOut = await client.attendance.clockOut({
+            notes: 'End of shift'
+        });
+        
+        console.log(`Shift duration: ${clockOut.data.shiftDuration.hours}h ${clockOut.data.shiftDuration.minutes}m`);
+    } else {
+        // Clock in
+        await client.attendance.clockIn({
+            storeId,
+            notes: 'Starting shift'
+        });
+        console.log('Successfully clocked in');
+    }
+}
+```
+
+### Generate Attendance Report
+```typescript
+async function generateWeeklyReport(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    const startDate = new Date();
+    startDate.setDate(startDate.getDate() - 7);
+    
+    const report = await client.attendance.getStoreReport(storeId, {
+        startDate: startDate.toISOString().split('T')[0],
+        endDate: new Date().toISOString().split('T')[0]
+    });
+    
+    console.log(`Weekly Report for ${report.data.storeName}`);
+    report.data.employees.forEach(emp => {
+        console.log(`${emp.employee.name}: ${emp.totalHours} hours, ${emp.totalShifts} shifts`);
+    });
+}
+```
+
+## 🛒 Customer & Order Processing
+
+### Create Customer and First Order
+```typescript
+async function createCustomerWithOrder(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    // Create customer
+    const customer = await client.customers.create({
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        phone: '+1234567890',
+        address: '123 Main St, City, State',
+        isActive: true
+    });
+    
+    // Create order for the customer
+    const order = await client.orders.createOrderUsersApp({
+        customer: customer.data._id,
+        store: storeId,
+        delivery: true,
+        pickup: false,
+        express: false,
+        phone: customer.data.phone,
+        address: customer.data.address,
+        products: [
+            {
+                storeProductId: 'product-id',
+                quantity: 2,
+                properties: ['Large', 'Cotton']
+            }
+        ],
+        status: 'pending',
+        paymentMethod: 'cash',
+        notifyBy: 'email'
+    });
+    
+    console.log(`Created order ${order.data.sequence} for ${customer.data.name}`);
+}
+```
+
+### Process Orders in Bulk
+```typescript
+async function processOrdersBatch(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    // Get all pending orders
+    const pendingOrders = await client.orders.getList({
+        storeId,
+        status: 'pending',
+        limit: '50'
+    });
+    
+    console.log(`Processing ${pendingOrders.data.length} pending orders`);
+    
+    // Accept all pending orders
+    for (const order of pendingOrders.data) {
+        try {
+            await client.orders.setOrderAcceptedBySequence(order.sequence, storeId);
+            console.log(`✅ Accepted order ${order.sequence}`);
+        } catch (error) {
+            console.error(`❌ Failed to accept order ${order.sequence}:`, error.message);
+        }
+    }
+}
+```
+
+### Order Status Updates
+```typescript
+async function updateOrderLifecycle(sequence: string, storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    try {
+        // Accept order
+        await client.orders.setOrderAcceptedBySequence(sequence, storeId);
+        console.log('Order accepted');
+        
+        // Mark as cleaning
+        await client.orders.setOrderCleaningBySequence(sequence, storeId);
+        console.log('Order in cleaning');
+        
+        // Mark as cleaned and ready
+        await client.orders.setOrderCleanedBySequence(sequence, storeId, {
+            cleanedDateTime: new Date().toISOString(),
+            readyDateTime: new Date().toISOString()
+        });
+        console.log('Order cleaned and ready');
+        
+        // Mark as collected
+        await client.orders.setOrderCollectedBySequence(sequence, storeId, {
+            collectedDateTime: new Date().toISOString()
+        });
+        console.log('Order collected');
+        
+    } catch (error) {
+        console.error('Failed to update order:', error.message);
+    }
+}
+```
+
+## 💰 Financial Operations
+
+### Daily Cash-Up Process
+```typescript
+async function performDailyCashUp(storeId: string, cashierBoxId: string) {
+    const client = new WashdayClient('your-token');
+    
+    // Get cash-up preview data
+    const previewData = await client.cashup.getPreviewDataForCashClose(storeId, cashierBoxId);
+    
+    console.log('Daily totals:');
+    console.log(`Cash from orders: $${previewData.data.cashFromOrders}`);
+    console.log(`Card from orders: $${previewData.data.cardFromOrders}`);
+    
+    // Perform cash-up
+    const cashUp = await client.cashup.create(storeId, cashierBoxId, {
+        cashierBox: cashierBoxId,
+        startingCash: 100.00,
+        declaredCash: previewData.data.expectedCash,
+        declaredCard: previewData.data.cardFromOrders,
+        declaredTransfer: previewData.data.transferFromOrders || 0,
+        cashToBank: 500.00,
+        notes: 'Daily cash-up completed'
+    });
+    
+    console.log(`Cash-up completed. Variance: $${cashUp.data.variance}`);
+}
+```
+
+### Payment Processing
+```typescript
+async function addPaymentToOrder(orderId: string, storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    // Get order details
+    const order = await client.orders.getById(orderId);
+    const amountDue = order.data.total - order.data.amountPaid;
+    
+    if (amountDue > 0) {
+        // Add payment line
+        await client.orders.createPaymentLine(orderId, {
+            amountPaid: amountDue,
+            cashierBox: 'cashier-box-id',
+            paymentMethod: 'card',
+            paymentDate: new Date()
+        });
+        
+        console.log(`Added payment of $${amountDue} to order ${order.data.sequence}`);
+    }
+}
+```
+
+## 📊 Reporting & Analytics
+
+### Generate Sales Report
+```typescript
+async function generateMonthlySalesReport(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    const startDate = new Date();
+    startDate.setMonth(startDate.getMonth() - 1);
+    startDate.setDate(1);
+    
+    const endDate = new Date();
+    endDate.setDate(0); // Last day of previous month
+    
+    const salesReport = await client.reports.getSalesReport(storeId, {
+        fromDate: startDate.toISOString().split('T')[0],
+        toDate: endDate.toISOString().split('T')[0],
+        type: 'daily'
+    });
+    
+    console.log('Monthly Sales Report:');
+    salesReport.data.forEach(day => {
+        console.log(`${day.date}: $${day.total} (${day.orders} orders)`);
+    });
+}
+```
+
+### Export Data to CSV
+```typescript
+async function exportCustomersData(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    const csvData = await client.csvExports.exportCustomersList({
+        fromDate: '2025-01-01',
+        toDate: '2025-01-31',
+        limit: '1000',
+        pageNum: '1'
+    });
+    
+    // Save CSV data to file
+    const fs = require('fs');
+    fs.writeFileSync('customers-export.csv', csvData);
+    console.log('Customer data exported to customers-export.csv');
+}
+```
+
+## 🔄 Real-Time Operations
+
+### Monitor Order Updates
+```typescript
+async function monitorOrderUpdates(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    // Poll for new orders every 30 seconds
+    setInterval(async () => {
+        try {
+            const recentOrders = await client.orders.getList({
+                storeId,
+                fromDate: new Date(Date.now() - 30000).toISOString(), // Last 30 seconds
+                status: 'pending'
+            });
+            
+            if (recentOrders.data.length > 0) {
+                console.log(`${recentOrders.data.length} new orders received`);
+                
+                // Process each new order
+                for (const order of recentOrders.data) {
+                    console.log(`New order: ${order.sequence} - ${order.customer.name}`);
+                    // Auto-accept order
+                    await client.orders.setOrderAcceptedBySequence(order.sequence, storeId);
+                }
+            }
+        } catch (error) {
+            console.error('Error monitoring orders:', error.message);
+        }
+    }, 30000);
+}
+```
+
+### Sync Inventory Levels
+```typescript
+async function syncInventoryLevels(storeId: string) {
+    const client = new WashdayClient('your-token');
+    
+    // Get current inventory
+    const inventory = await client.inventory.getInventory(storeId);
+    
+    // Check for low stock items
+    const lowStockItems = inventory.data.filter(item => 
+        item.stock <= item.alertOnStock
+    );
+    
+    if (lowStockItems.length > 0) {
+        console.log('Low stock alert:');
+        lowStockItems.forEach(item => {
+            console.log(`${item.product.name}: ${item.stock} units (Alert level: ${item.alertOnStock})`);
+        });
+        
+        // Optionally add stock automatically
+        for (const item of lowStockItems) {
+            await client.inventory.addStock(storeId, item._id, {
+                newStock: item.alertOnStock * 2, // Restock to double the alert level
+                date: new Date().toISOString()
+            });
+            console.log(`Restocked ${item.product.name}`);
+        }
+    }
+}
+```
+
+## 🚨 Error Handling Patterns
+
+### Robust API Calls with Retry Logic
+```typescript
+async function robustApiCall<T>(
+    apiCall: () => Promise<T>,
+    maxRetries: number = 3,
+    delay: number = 1000
+): Promise<T> {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            return await apiCall();
+        } catch (error) {
+            console.log(`Attempt ${attempt} failed:`, error.message);
+            
+            if (attempt === maxRetries) {
+                throw error;
+            }
+            
+            // Wait before retrying
+            await new Promise(resolve => setTimeout(resolve, delay * attempt));
+        }
+    }
+    throw new Error('All retries failed');
+}
+
+// Usage
+const orders = await robustApiCall(() => 
+    client.orders.getList({ storeId: 'store-id' })
+);
+```
+
+### Batch Operations with Error Handling
+```typescript
+async function processBatchWithErrorHandling<T>(
+    items: T[],
+    processor: (item: T) => Promise<void>,
+    batchSize: number = 10
+) {
+    const results = [];
+    
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        
+        const batchPromises = batch.map(async (item, index) => {
+            try {
+                await processor(item);
+                return { success: true, item, error: null };
+            } catch (error) {
+                console.error(`Failed to process item ${i + index}:`, error.message);
+                return { success: false, item, error: error.message };
+            }
+        });
+        
+        const batchResults = await Promise.all(batchPromises);
+        results.push(...batchResults);
+        
+        // Optional delay between batches
+        if (i + batchSize < items.length) {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+    
+    return results;
+}
+```
+
+## 🔧 Performance Optimization
+
+### Pagination Helper
+```typescript
+async function getAllPages<T>(
+    fetcher: (pageNum: string, limit: string) => Promise<{ data: T[], totalPages: number }>,
+    limit: number = 50
+): Promise<T[]> {
+    const allItems: T[] = [];
+    let currentPage = 1;
+    let totalPages = 1;
+    
+    do {
+        const response = await fetcher(currentPage.toString(), limit.toString());
+        allItems.push(...response.data);
+        totalPages = response.totalPages;
+        currentPage++;
+    } while (currentPage <= totalPages);
+    
+    return allItems;
+}
+
+// Usage
+const allOrders = await getAllPages((page, limit) => 
+    client.orders.getList({ 
+        storeId: 'store-id', 
+        pageNum: page, 
+        limit 
+    })
+);
+```
+
+### Caching Wrapper
+```typescript
+class CachedWashdayClient {
+    private client: WashdayClient;
+    private cache: Map<string, { data: any, expiry: number }> = new Map();
+    private defaultTtl: number = 5 * 60 * 1000; // 5 minutes
+    
+    constructor(token: string) {
+        this.client = new WashdayClient(token);
+    }
+    
+    async getWithCache<T>(
+        key: string,
+        fetcher: () => Promise<T>,
+        ttl: number = this.defaultTtl
+    ): Promise<T> {
+        const cached = this.cache.get(key);
+        
+        if (cached && cached.expiry > Date.now()) {
+            return cached.data;
+        }
+        
+        const data = await fetcher();
+        this.cache.set(key, {
+            data,
+            expiry: Date.now() + ttl
+        });
+        
+        return data;
+    }
+    
+    async getStoreById(storeId: string) {
+        return this.getWithCache(
+            `store:${storeId}`,
+            () => this.client.stores.getStoreById(storeId),
+            10 * 60 * 1000 // 10 minutes for store data
+        );
+    }
+}
+```
+
+These examples should cover most common scenarios you'll encounter when building applications with the Washday SDK. Each example includes proper error handling and follows best practices for production use. 

package/docs/getting-started.md

@@ -0,0 +1,237 @@
+# 🚀 Getting Started
+
+This guide will help you get up and running with the Washday SDK in just a few minutes.
+
+## 📦 Installation
+
+### NPM
+```bash
+npm install washday-sdk
+```
+
+### Yarn
+```bash
+yarn add washday-sdk
+```
+
+### CDN (Browser)
+```html
+<script src="https://unpkg.com/washday-sdk@latest/dist/index.js"></script>
+```
+
+## 🔑 Authentication
+
+Before using the SDK, you'll need an API token from your Washday dashboard.
+
+### Getting Your API Token
+1. Log into your Washday admin panel
+2. Navigate to **Settings** > **API Keys**
+3. Generate a new API token
+4. Copy the token (keep it secure!)
+
+### Initialize the Client
+
+```typescript
+import { WashdayClient } from 'washday-sdk';
+
+const client = new WashdayClient('your-api-token-here');
+```
+
+## 🎯 First API Call
+
+Let's make your first API call to check if everything is working:
+
+```typescript
+import { WashdayClient } from 'washday-sdk';
+
+async function testConnection() {
+    const client = new WashdayClient('your-api-token');
+    
+    try {
+        // Get your stores
+        const stores = await client.stores.getStores({ isActive: 'true' });
+        console.log('Connected! Your stores:', stores.data);
+    } catch (error) {
+        console.error('Connection failed:', error.message);
+    }
+}
+
+testConnection();
+```
+
+## 🏢 Common Setup Patterns
+
+### Single Store Application
+```typescript
+const client = new WashdayClient('your-api-token');
+const STORE_ID = 'your-store-id';
+
+// Now you can use STORE_ID in all store-specific calls
+const orders = await client.orders.getList({ storeId: STORE_ID });
+```
+
+### Multi-Store Application
+```typescript
+const client = new WashdayClient('your-api-token');
+
+// Get all active stores first
+const stores = await client.stores.getStores({ isActive: 'true' });
+
+// Use stores dynamically
+for (const store of stores.data) {
+    const orders = await client.orders.getList({ storeId: store._id });
+    console.log(`${store.name} has ${orders.data.length} orders`);
+}
+```
+
+### Environment Configuration
+```typescript
+// Use environment variables for security
+const client = new WashdayClient(process.env.WASHDAY_API_TOKEN);
+```
+
+## 📝 Basic Examples
+
+### Customer Management
+```typescript
+// Create a new customer
+const newCustomer = await client.customers.create({
+    name: 'John Doe',
+    email: 'john@example.com',
+    phone: '+1234567890',
+    isActive: true
+});
+
+// Get customer by ID
+const customer = await client.customers.getCustomerById(newCustomer.data._id);
+
+// Update customer
+await client.customers.updateById(customer.data._id, {
+    name: 'John Smith'
+});
+```
+
+### Order Processing
+```typescript
+// Get pending orders
+const pendingOrders = await client.orders.getList({
+    storeId: 'your-store-id',
+    status: 'pending'
+});
+
+// Update order status
+await client.orders.setOrderAcceptedBySequence(
+    'ORDER-123',
+    'your-store-id'
+);
+```
+
+### Employee Attendance
+```typescript
+// Clock in employee
+await client.attendance.clockIn({
+    storeId: 'your-store-id',
+    notes: 'Starting morning shift'
+});
+
+// Check current status
+const status = await client.attendance.getStatus();
+console.log('Currently clocked in:', status.active);
+
+// Clock out
+await client.attendance.clockOut({
+    notes: 'End of shift'
+});
+```
+
+## 🔧 TypeScript Support
+
+The SDK is built with TypeScript and provides full type definitions:
+
+```typescript
+import { WashdayClient, ICustomer, IOrder } from 'washday-sdk';
+
+const client = new WashdayClient('your-token');
+
+// Types are automatically inferred
+const customer: ICustomer = await client.customers.getCustomerById('customer-id');
+const orders: IOrder[] = await client.orders.getList({ storeId: 'store-id' });
+```
+
+## 🚨 Error Handling
+
+Always wrap your API calls in try-catch blocks:
+
+```typescript
+try {
+    const result = await client.customers.create({
+        name: 'John Doe',
+        email: 'invalid-email' // This will cause a validation error
+    });
+} catch (error) {
+    if (error.response) {
+        // API returned an error response
+        console.error('API Error:', error.response.status);
+        console.error('Details:', error.response.data.errors);
+    } else {
+        // Network or other error
+        console.error('Network Error:', error.message);
+    }
+}
+```
+
+## 🎛️ Configuration Options
+
+### Request Timeout
+```typescript
+// Configure axios defaults (the SDK uses axios internally)
+import axios from 'axios';
+
+axios.defaults.timeout = 10000; // 10 seconds
+```
+
+### Base URL (for self-hosted instances)
+```typescript
+import axiosInstance from 'washday-sdk/dist/api/axiosInstance';
+
+// Only needed if you're using a self-hosted Washday instance
+axiosInstance.defaults.baseURL = 'https://your-washday-instance.com';
+```
+
+## 📚 Next Steps
+
+Now that you're set up, explore specific modules:
+
+- [**Attendance Module**](./modules/attendance.md) - Employee time tracking
+- [**Orders Module**](./modules/orders.md) - Order management
+- [**Customers Module**](./modules/customers.md) - Customer data
+- [**Common Examples**](./examples/common-use-cases.md) - Real-world scenarios
+
+## 🆘 Troubleshooting
+
+### Common Issues
+
+**Invalid API Token**
+```
+Error: Request failed with status code 401
+```
+Solution: Check that your API token is correct and active.
+
+**Store Not Found**
+```
+Error: Request failed with status code 400
+Details: ["Store ID is required"]
+```
+Solution: Ensure you're passing a valid `storeId` parameter.
+
+**Network Issues**
+```
+Error: Network Error
+```
+Solution: Check your internet connection and firewall settings.
+
+### Getting Help
+
+- 📖 Check the specific module documentation
+- 🔍 Look at the [examples](./examples/) folder
+- 💬 Contact support with your API logs