washday-sdk 1.0.2 → 1.1.0

package/docs/modules/attendance.md

@@ -0,0 +1,404 @@
+# 📋 Attendance Module
+
+The Attendance module provides comprehensive employee time tracking functionality including clock-in/out, shift management, and reporting capabilities.
+
+## 🚀 Quick Start
+
+```typescript
+import { WashdayClient } from 'washday-sdk';
+
+const client = new WashdayClient('your-api-token');
+
+// Clock in
+await client.attendance.clockIn({
+    storeId: 'store-id-here',
+    notes: 'Starting shift'
+});
+
+// Check status
+const status = await client.attendance.getStatus();
+console.log(status); // { active: true, clockInTime: '2025-01-01T08:00:00.000Z' }
+```
+
+## 📝 Available Methods
+
+### 1. Clock In
+Clock in to start a work shift at a specific store.
+
+```typescript
+const clockInResult = await client.attendance.clockIn({
+    storeId: 'store-id-here',           // Required: Store where employee is clocking in
+    userId: 'user-id-here',             // Optional: Defaults to token user
+    ipAddress: '192.168.1.1',           // Optional: Client IP address
+    notes: 'Starting shift'             // Optional: Additional notes
+});
+
+// Response
+console.log(clockInResult);
+// {
+//   status: 201,
+//   data: {
+//     attendanceRecord: {
+//       _id: 'record-id',
+//       employee: 'user-id',
+//       store: 'store-id',
+//       type: 'IN',
+//       timestamp: '2025-01-01T08:00:00.000Z',
+//       notes: 'Starting shift'
+//     },
+//     message: 'Entrada registrada exitosamente'
+//   }
+// }
+```
+
+### 2. Clock Out
+Clock out to end the current work shift. The system automatically uses the same store as the last clock-in.
+
+```typescript
+const clockOutResult = await client.attendance.clockOut({
+    userId: 'user-id-here',             // Optional: Defaults to token user
+    ipAddress: '192.168.1.1',           // Optional: Client IP address
+    notes: 'End of shift'               // Optional: Additional notes
+});
+
+// Response
+console.log(clockOutResult);
+// {
+//   status: 201,
+//   data: {
+//     clockOutEntry: { /* OUT record */ },
+//     clockInEntry: { /* matching IN record */ },
+//     shiftDuration: {
+//       hours: 8,
+//       minutes: 30,
+//       totalMinutes: 510
+//     }
+//   }
+// }
+```
+
+### 3. Get Attendance Status
+Check if an employee has an active shift (clocked in without clocking out).
+
+```typescript
+const statusResult = await client.attendance.getStatus({
+    storeId: 'store-id-here'            // Optional: Check specific store, omit for all stores
+});
+
+// Active shift response
+console.log(statusResult);
+// {
+//   active: true,
+//   clockInTime: '2025-01-01T08:00:00.000Z',
+//   clockInStore: 'store-id'
+// }
+
+// No active shift response
+// {
+//   active: false
+// }
+```
+
+### 4. Get Attendance History
+Retrieve attendance records with filtering and pagination.
+
+```typescript
+const historyResult = await client.attendance.getHistory({
+    storeId: 'store-id-here',           // Optional: Filter by store
+    startDate: '2025-01-01',            // Optional: Start date (YYYY-MM-DD)
+    endDate: '2025-01-31',              // Optional: End date (YYYY-MM-DD)
+    pageNum: '1',                       // Optional: Page number (default: 1)
+    limit: '50'                         // Optional: Records per page (default: 50)
+});
+
+// Response
+console.log(historyResult);
+// {
+//   attendanceRecords: [
+//     {
+//       _id: 'record-1',
+//       employee: { name: 'John Doe', _id: 'user-id' },
+//       store: { name: 'Main Store', _id: 'store-id' },
+//       type: 'IN',
+//       timestamp: '2025-01-01T08:00:00.000Z',
+//       notes: 'Starting shift'
+//     },
+//     {
+//       _id: 'record-2',
+//       employee: { name: 'John Doe', _id: 'user-id' },
+//       store: { name: 'Main Store', _id: 'store-id' },
+//       type: 'OUT',
+//       timestamp: '2025-01-01T17:00:00.000Z',
+//       notes: 'End of shift'
+//     }
+//   ],
+//   totalRecords: 100,
+//   currentPage: 1,
+//   totalPages: 2
+// }
+```
+
+### 5. Get Store Report
+Generate a comprehensive attendance report for a specific store.
+
+```typescript
+const reportResult = await client.attendance.getStoreReport('store-id-here', {
+    startDate: '2025-01-01',            // Optional: Report start date
+    endDate: '2025-01-31',              // Optional: Report end date
+    pageNum: '1',                       // Optional: Page number
+    limit: '100'                        // Optional: Records per page
+});
+
+// Response
+console.log(reportResult);
+// {
+//   storeId: 'store-id',
+//   storeName: 'Main Store',
+//   employees: [
+//     {
+//       employee: {
+//         _id: 'user-id',
+//         name: 'John Doe',
+//         email: 'john@example.com'
+//       },
+//       records: [
+//         { type: 'IN', timestamp: '...', notes: '...' },
+//         { type: 'OUT', timestamp: '...', notes: '...' }
+//       ],
+//       totalHours: 160,
+//       totalShifts: 20
+//     }
+//   ],
+//   dateRange: {
+//     startDate: '2025-01-01T00:00:00.000Z',
+//     endDate: '2025-01-31T23:59:59.000Z'
+//   }
+// }
+```
+
+### 6. Update Attendance Entry
+Update an existing attendance record (typically admin-only functionality).
+
+```typescript
+const updateResult = await client.attendance.updateById('attendance-record-id', {
+    timestamp: '2025-01-01T09:00:00.000Z',  // Optional: Correct the timestamp
+    notes: 'Corrected time',                // Optional: Update notes
+    editorId: 'admin-user-id'               // Optional: Who made the edit
+});
+
+// Response
+console.log(updateResult);
+// {
+//   status: 200,
+//   data: {
+//     updatedRecord: {
+//       _id: 'record-id',
+//       timestamp: '2025-01-01T09:00:00.000Z',
+//       notes: 'Corrected time',
+//       editedBy: 'admin-user-id',
+//       editedAt: '2025-01-01T10:00:00.000Z'
+//     }
+//   }
+// }
+```
+
+## 🎯 TypeScript Interfaces
+
+```typescript
+import { 
+    IAttendanceRecord, 
+    IAttendanceHistory, 
+    IAttendanceStatus, 
+    IAttendanceReport 
+} from 'washday-sdk';
+
+interface IAttendanceRecord {
+    _id?: string;
+    employee: IUser | string;
+    store: IStore | string;
+    type: 'IN' | 'OUT';
+    timestamp: Date;
+    ipAddress?: string;
+    notes?: string;
+    editedBy?: IUser | string;
+    editedAt?: Date;
+    autoClosed?: boolean;        // Set to true if automatically closed by system
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+interface IAttendanceStatus {
+    active: boolean;
+    clockInTime?: Date;          // Only present if active is true
+    clockInStore?: IStore | string;  // Store where employee clocked in
+}
+
+interface IAttendanceHistory {
+    attendanceRecords: IAttendanceRecord[];
+    totalRecords?: number;
+    currentPage?: number;
+    totalPages?: number;
+}
+
+interface IAttendanceReport {
+    storeId: string;
+    storeName?: string;
+    employees: {
+        employee: IUser | string;
+        records: IAttendanceRecord[];
+        totalHours?: number;
+        totalShifts?: number;
+    }[];
+    dateRange?: {
+        startDate: Date;
+        endDate: Date;
+    };
+}
+```
+
+## 📊 Error Handling
+
+The attendance module returns standard HTTP status codes and error messages:
+
+```typescript
+try {
+    const result = await client.attendance.clockIn({
+        storeId: 'store-id',
+        notes: 'Starting work'
+    });
+    console.log('Success:', result.data);
+} catch (error) {
+    console.error('Error:', error.response?.data?.errors || error.message);
+    
+    // Handle specific error cases
+    if (error.response?.status === 400) {
+        // Validation error examples:
+        // - Already clocked in
+        // - Invalid store ID
+        // - User not found
+        console.log('Validation error:', error.response.data.errors);
+    } else if (error.response?.status === 401) {
+        // Authentication error
+        console.log('Please check your API token');
+    } else if (error.response?.status === 403) {
+        // Permission error
+        console.log('Insufficient permissions');
+    } else if (error.response?.status === 500) {
+        // Server error
+        console.log('Internal server error');
+    }
+}
+```
+
+### Common Error Scenarios
+
+| Error | Status | Description | Solution |
+|-------|--------|-------------|----------|
+| Already clocked in | 400 | Employee has active shift | Clock out first |
+| No active shift | 400 | Trying to clock out without clock-in | Clock in first |
+| Invalid store | 400 | Store ID doesn't exist | Verify store ID |
+| User not found | 400 | User ID doesn't exist | Verify user ID |
+| Unauthorized | 401 | Invalid API token | Check authentication |
+| Forbidden | 403 | Insufficient permissions | Check user permissions |
+
+## 🔧 Advanced Features
+
+### Auto Clock-Out Configuration
+The attendance system supports automatic clock-out after a configurable number of hours per store:
+
+```typescript
+// This is managed through store configuration endpoints
+const store = await client.stores.getStoreById('store-id');
+console.log(store.attendanceConfig);
+// {
+//   maxShiftHours: 12,              // Auto clock-out after 12 hours
+//   requireClockInOnLogin: false,   // Force clock-in on POS login
+//   autoClosedFlag: true            // Enable auto clock-out feature
+// }
+```
+
+### Multi-Store Support
+- Employees can work across multiple stores
+- Clock-out automatically occurs in the same store as the last clock-in
+- History and reports can be filtered by store or show all stores
+- Status checks can be store-specific or global
+
+### IP Address Tracking
+IP addresses are automatically captured when available for:
+- Security auditing
+- Location verification
+- Fraud prevention
+
+### Shift Duration Calculation
+The system automatically calculates shift durations:
+- Hours and minutes worked
+- Total minutes for easy calculations
+- Handles overnight shifts correctly
+
+## 📋 Best Practices
+
+### For Client Applications
+1. **Always check status before actions**:
+   ```typescript
+   const status = await client.attendance.getStatus();
+   if (status.active) {
+       // Show clock-out button
+   } else {
+       // Show clock-in button
+   }
+   ```
+
+2. **Handle errors gracefully**:
+   ```typescript
+   try {
+       await client.attendance.clockIn({ storeId });
+   } catch (error) {
+       if (error.response?.status === 400) {
+           // Show user-friendly message
+           alert('You are already clocked in');
+       }
+   }
+   ```
+
+3. **Use pagination for large datasets**:
+   ```typescript
+   const history = await client.attendance.getHistory({
+       limit: '50',
+       pageNum: '1'
+   });
+   ```
+
+### For Managers/Admins
+1. **Regular report generation**:
+   ```typescript
+   const weeklyReport = await client.attendance.getStoreReport(storeId, {
+       startDate: getWeekStart(),
+       endDate: getWeekEnd()
+   });
+   ```
+
+2. **Monitor auto-closed shifts**:
+   ```typescript
+   const history = await client.attendance.getHistory({
+       storeId,
+       startDate: 'today'
+   });
+   
+   const autoClosedShifts = history.attendanceRecords.filter(
+       record => record.autoClosed
+   );
+   ```
+
+### Performance Optimization
+1. **Use store-specific queries when possible**
+2. **Implement proper pagination for large date ranges**
+3. **Cache status information for short periods**
+4. **Use appropriate date ranges to limit data volume**
+
+## 🚨 Important Notes
+
+- **Clock-out enforcement**: The system enforces that clock-out occurs in the same store as the corresponding clock-in
+- **Auto clock-out**: Shifts are automatically closed after the configured maximum hours
+- **Data integrity**: All records are immutable once created (updates create edit logs)
+- **Time zones**: All timestamps are stored in UTC and should be converted to local time for display
+- **Permissions**: Some operations (like editing records) require administrative permissions 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "washday-sdk",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Washday utilities functions and API",
   "main": "dist/index.js",
+  "type": "module",
   "scripts": {
-    "test": "test",
+    "test": "jest",
     "build": "tsc",
-    "publish": "npm run build && npm publish --access public"
+    "publishVersion": "npm run build && npm publish --access public"
   },
   "keywords": [
     "washday"
@@ -14,10 +15,17 @@
   "author": "Washday",
   "license": "ISC",
   "devDependencies": {
+    "@babel/core": "^7.24.4",
+    "@babel/preset-env": "^7.24.4",
+    "@babel/preset-typescript": "^7.24.1",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
     "typescript": "^5.4.4"
   },
   "dependencies": {
     "axios": "^1.6.8",
-    "joi": "^17.12.3"
+    "joi": "^17.12.3",
+    "moment": "^2.30.1",
+    "uuid": "^11.1.0"
   }
 }

package/src/api/attendance/delete.ts

@@ -0,0 +1 @@
+// No delete endpoints implemented for attendance module 

package/src/api/attendance/get.ts

@@ -0,0 +1,81 @@
+import { WashdayClientInstance } from "../../interfaces/Api";
+import axiosInstance from "../axiosInstance";
+
+const ATTENDANCE_API = 'api/attendance';
+
+export const getHistory = async function (this: WashdayClientInstance, params: {
+    storeId?: string;
+    startDate?: string;
+    endDate?: string;
+    pageNum?: string;
+    limit?: string;
+}): Promise<any> {
+    try {
+        const config = {
+            headers: { Authorization: `Bearer ${this.apiToken}` }
+        };
+        
+        let queryParams = '';
+        if (params.storeId) queryParams += `storeId=${params.storeId}&`;
+        if (params.startDate) queryParams += `startDate=${params.startDate}&`;
+        if (params.endDate) queryParams += `endDate=${params.endDate}&`;
+        if (params.pageNum) queryParams += `pageNum=${params.pageNum}&`;
+        if (params.limit) queryParams += `limit=${params.limit}&`;
+        
+        // Remove trailing '&'
+        queryParams = queryParams.slice(0, -1);
+        
+        const url = queryParams ? `${ATTENDANCE_API}/history?${queryParams}` : `${ATTENDANCE_API}/history`;
+        return await axiosInstance.get(url, config);
+    } catch (error) {
+        console.error('Error fetching attendance history:', error);
+        throw error;
+    }
+};
+
+export const getStatus = async function (this: WashdayClientInstance, params?: {
+    storeId?: string;
+}): Promise<any> {
+    try {
+        const config = {
+            headers: { Authorization: `Bearer ${this.apiToken}` }
+        };
+        
+        let queryParams = '';
+        if (params?.storeId) queryParams += `storeId=${params.storeId}`;
+        
+        const url = queryParams ? `${ATTENDANCE_API}/status?${queryParams}` : `${ATTENDANCE_API}/status`;
+        return await axiosInstance.get(url, config);
+    } catch (error) {
+        console.error('Error fetching attendance status:', error);
+        throw error;
+    }
+};
+
+export const getStoreReport = async function (this: WashdayClientInstance, storeId: string, params?: {
+    startDate?: string;
+    endDate?: string;
+    pageNum?: string;
+    limit?: string;
+}): Promise<any> {
+    try {
+        const config = {
+            headers: { Authorization: `Bearer ${this.apiToken}` }
+        };
+        
+        let queryParams = '';
+        if (params?.startDate) queryParams += `startDate=${params.startDate}&`;
+        if (params?.endDate) queryParams += `endDate=${params.endDate}&`;
+        if (params?.pageNum) queryParams += `pageNum=${params.pageNum}&`;
+        if (params?.limit) queryParams += `limit=${params.limit}&`;
+        
+        // Remove trailing '&'
+        queryParams = queryParams.slice(0, -1);
+        
+        const url = queryParams ? `${ATTENDANCE_API}/store/${storeId}/report?${queryParams}` : `${ATTENDANCE_API}/store/${storeId}/report`;
+        return await axiosInstance.get(url, config);
+    } catch (error) {
+        console.error('Error fetching store attendance report:', error);
+        throw error;
+    }
+}; 

package/src/api/attendance/index.ts

@@ -0,0 +1,4 @@
+// export * as deleteModule from './delete';
+export * as getModule from './get';
+export * as postModule from './post';
+export * as putModule from './put'; 

package/src/api/attendance/post.ts

@@ -0,0 +1,37 @@
+import { WashdayClientInstance } from "../../interfaces/Api";
+import axiosInstance from "../axiosInstance";
+
+const ATTENDANCE_API = 'api/attendance';
+
+export const clockIn = async function (this: WashdayClientInstance, data: {
+    storeId: string;
+    userId?: string;
+    ipAddress?: string;
+    notes?: string;
+}): Promise<any> {
+    try {
+        const config = {
+            headers: { Authorization: `Bearer ${this.apiToken}` }
+        };
+        return await axiosInstance.post(`${ATTENDANCE_API}/clock-in`, data, config);
+    } catch (error) {
+        console.error('Error clock-in:', error);
+        throw error;
+    }
+};
+
+export const clockOut = async function (this: WashdayClientInstance, data: {
+    userId?: string;
+    ipAddress?: string;
+    notes?: string;
+}): Promise<any> {
+    try {
+        const config = {
+            headers: { Authorization: `Bearer ${this.apiToken}` }
+        };
+        return await axiosInstance.post(`${ATTENDANCE_API}/clock-out`, data, config);
+    } catch (error) {
+        console.error('Error clock-out:', error);
+        throw error;
+    }
+}; 

package/src/api/attendance/put.ts

@@ -0,0 +1,20 @@
+import { WashdayClientInstance } from "../../interfaces/Api";
+import axiosInstance from "../axiosInstance";
+
+const ATTENDANCE_API = 'api/attendance';
+
+export const updateById = async function (this: WashdayClientInstance, id: string, data: {
+    timestamp?: string;
+    notes?: string;
+    editorId?: string;
+}): Promise<any> {
+    try {
+        const config = {
+            headers: { Authorization: `Bearer ${this.apiToken}` }
+        };
+        return await axiosInstance.put(`${ATTENDANCE_API}/${id}`, data, config);
+    } catch (error) {
+        console.error('Error updating attendance entry:', error);
+        throw error;
+    }
+}; 

package/src/api/auth/index.ts

@@ -0,0 +1,3 @@
+// export * as deleteModule from './delete';
+export * as postModule from './post';
+// export * as putModule from './put';