# Workbook Tasks API Documentation

## Overview

The Workbook Tasks API provides endpoints for managing daily task lists with scheduling, completion tracking, comments, and employee assignments. Task lists are scheduled by day of week with configurable start times.

## Base URL

```
/api/:typeNum/workbook/tasks
```

Where `:typeNum` is the store identifier (e.g., `pc00`, `ou01`).

## Authentication

All endpoints require store access. The user must have access to the specified store.

**Permissions:**
- **Read task lists, update status, add comments**: Any employee with store access
- **Create/Update lists, manage assignments, update schedules**: Requires `uri_store_settings` or `workbook_manage_tasks` permission

---

## Endpoints

### 1. Get Today's Task Lists

Retrieves all task lists scheduled for the current day of the week.

```
GET /api/:typeNum/workbook/tasks/lists/
```

#### Example Request

```bash
curl -X GET "https://buyerkiosk.com/api/pc00/workbook/tasks/lists/"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "lists": [
    {
      "id": 1,
      "groupId": 5,
      "groupName": "Opening Tasks",
      "displayName": "Morning Opening",
      "scheduledDays": "MON TUE WED THU FRI SAT SUN",
      "startTime": "08:00:00",
      "effectiveStartTime": "08:00:00",
      "sortOrder": 1,
      "isActive": true,
      "totalCount": 12,
      "completedCount": 8,
      "completionPercentage": 67,
      "tasks": [
        {
          "id": 101,
          "taskName": "Turn on lights",
          "comment": "Check all sections",
          "taskGroup": 5,
          "priority": 1,
          "sortOrder": 1,
          "recurOn": "MON TUE WED THU FRI SAT SUN",
          "completionId": 501,
          "status": 2,
          "completedBy": 45,
          "completedAt": "2025-12-01 08:15:32",
          "completionNotes": null,
          "completedByFirstName": "John",
          "completedByLastName": "Smith",
          "assignedToEmployeeId": null,
          "dueDate": null,
          "dueTime": null
        }
      ]
    }
  ]
}
```

#### Task List Object Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Task list configuration ID |
| `groupId` | int | Task group ID (links to tasks) |
| `groupName` | string | Task group name |
| `displayName` | string\|null | Optional display override |
| `scheduledDays` | string | Days scheduled (e.g., "MON TUE WED") |
| `startTime` | string | Default start time (HH:MM:SS) |
| `effectiveStartTime` | string | Actual start time for today (may differ by day) |
| `sortOrder` | int | Display order |
| `isActive` | bool | Whether list is active |
| `totalCount` | int | Total number of tasks |
| `completedCount` | int | Number of completed tasks |
| `completionPercentage` | int | Percentage complete (0-100) |
| `tasks` | array | Array of task objects |

#### Task Object Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Task ID |
| `taskName` | string | Task name/title |
| `comment` | string\|null | Task description/instructions |
| `taskGroup` | int | Parent task group ID |
| `priority` | int | Priority level |
| `sortOrder` | int | Display order within list |
| `recurOn` | string | Days this task recurs |
| `completionId` | int\|null | Today's completion record ID |
| `status` | int\|null | Today's status: `0`=Not Started, `1`=In Progress, `2`=Completed |
| `completedBy` | int\|null | Employee ID who completed |
| `completedAt` | string\|null | Completion timestamp |
| `completionNotes` | string\|null | Notes about completion |
| `completedByFirstName` | string\|null | Completer's first name |
| `completedByLastName` | string\|null | Completer's last name |
| `assignedToEmployeeId` | int\|null | Assigned employee ID |
| `dueDate` | string\|null | Assignment due date |
| `dueTime` | string\|null | Assignment due time |

---

### 2. Get Active Task List

Retrieves the currently active task list based on current time, plus incomplete carryover tasks from earlier lists.

```
GET /api/:typeNum/workbook/tasks/lists/active/
```

#### Example Request

```bash
curl -X GET "https://buyerkiosk.com/api/pc00/workbook/tasks/lists/active/"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "activeList": {
    "id": 2,
    "groupId": 6,
    "groupName": "Midday Tasks",
    "displayName": null,
    "startTime": "12:00:00",
    "effectiveStartTime": "12:00:00",
    "totalCount": 8,
    "completedCount": 3,
    "completionPercentage": 38,
    "tasks": [...]
  },
  "carryoverTasks": [
    {
      "id": 105,
      "taskName": "Restock fitting rooms",
      "status": 0,
      "carryoverFromList": "Opening Tasks",
      "carryoverFromListId": 1,
      "originalStartTime": "08:00:00"
    }
  ],
  "nextListTime": "17:00:00",
  "nextListName": "Closing Tasks"
}
```

#### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `activeList` | object\|null | Currently active task list (null if none started) |
| `carryoverTasks` | array | Incomplete tasks from earlier lists |
| `nextListTime` | string\|null | Start time of next upcoming list |
| `nextListName` | string\|null | Name of next upcoming list |

#### Carryover Task Additional Fields

| Field | Type | Description |
|-------|------|-------------|
| `carryoverFromList` | string | Name of original list |
| `carryoverFromListId` | int | ID of original list |
| `originalStartTime` | string | When task was originally due |

---

### 3. Get Task List by ID

Retrieves a specific task list with its tasks.

```
GET /api/:typeNum/workbook/tasks/lists/:listId/
```

#### Example Request

```bash
curl -X GET "https://buyerkiosk.com/api/pc00/workbook/tasks/lists/1/"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "list": {
    "id": 1,
    "groupId": 5,
    "groupName": "Opening Tasks",
    "tasks": [...],
    "completionPercentage": 67
  }
}
```

#### Error Response (HTTP 404)

```json
{
  "error": "Task list not found"
}
```

---

### 4. Update Task Status

Updates the completion status of a task for a specific date.

```
POST /api/:typeNum/workbook/tasks/:taskId/status/
```

#### Request Body

```json
{
  "status": 2,
  "date": "2025-12-01",
  "employeeId": 45,
  "notes": "Completed early",
  "completedAt": "2025-12-01 08:30:00"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | int | Yes | `0`=Not Started, `1`=In Progress, `2`=Completed |
| `date` | string | No | Date (Y-m-d), defaults to today |
| `employeeId` | int | No | Employee completing the task |
| `notes` | string | No | Completion notes |
| `completedAt` | string | No | Custom completion time (for editing) |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/pc00/workbook/tasks/101/status/" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 2,
    "employeeId": 45,
    "notes": "All lights working"
  }'
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "debug": {
    "taskId": 101,
    "date": "2025-12-01",
    "status": 2,
    "completionId": 501
  }
}
```

#### Error Responses

**Invalid Status (HTTP 400)**
```json
{
  "error": "Invalid status. Must be 0 (Not Started), 1 (In Progress), or 2 (Completed)"
}
```

**Task Not Found (HTTP 404)**
```json
{
  "error": "Task not found"
}
```

---

### 5. Add Task Comment

Adds a comment to a task for a specific date.

```
POST /api/:typeNum/workbook/tasks/:taskId/comment/
```

#### Request Body

```json
{
  "comment": "Found a burnt out bulb in section B",
  "date": "2025-12-01",
  "employeeId": 45
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `comment` | string | Yes | Comment text (max 1000 characters) |
| `date` | string | No | Date (Y-m-d), defaults to today |
| `employeeId` | int | Yes | Employee adding the comment |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/pc00/workbook/tasks/101/comment/" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Need to order replacement bulbs",
    "employeeId": 45
  }'
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "commentId": 15
}
```

#### Error Responses

**Missing Comment (HTTP 400)**
```json
{
  "error": "Comment is required"
}
```

**Comment Too Long (HTTP 400)**
```json
{
  "error": "Comment exceeds maximum length of 1000 characters"
}
```

---

### 6. Get Task Comments

Retrieves all comments for a task on a specific date.

```
GET /api/:typeNum/workbook/tasks/:taskId/comments/
```

#### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `date` | string | today | Date to get comments for (Y-m-d) |

#### Example Request

```bash
curl -X GET "https://buyerkiosk.com/api/pc00/workbook/tasks/101/comments/?date=2025-12-01"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "comments": [
    {
      "id": 15,
      "taskId": 101,
      "date": "2025-12-01",
      "employeeId": 45,
      "employeeFirstName": "John",
      "employeeLastName": "Smith",
      "comment": "Need to order replacement bulbs",
      "createdAt": "2025-12-01 08:20:15"
    }
  ]
}
```

---

### 7. Get Completed Tasks

Retrieves all completed tasks for a specific date.

```
GET /api/:typeNum/workbook/tasks/completed/
```

#### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `date` | string | today | Date to get completed tasks for (Y-m-d) |

#### Example Request

```bash
curl -X GET "https://buyerkiosk.com/api/pc00/workbook/tasks/completed/?date=2025-12-01"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "date": "2025-12-01",
  "tasks": [
    {
      "id": 101,
      "taskName": "Turn on lights",
      "comment": "Check all sections",
      "taskGroup": 5,
      "listName": "Opening Tasks",
      "status": 2,
      "completedBy": 45,
      "completedAt": "2025-12-01 08:15:32",
      "completionNotes": "All lights working",
      "completedByFirstName": "John",
      "completedByLastName": "Smith"
    }
  ]
}
```

---

### 8. Get Task Completion Details

Retrieves completion details for a specific task (useful for editing).

```
GET /api/:typeNum/workbook/tasks/:taskId/completion/
```

#### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `date` | string | today | Date to get completion for (Y-m-d) |

#### Example Request

```bash
curl -X GET "https://buyerkiosk.com/api/pc00/workbook/tasks/101/completion/?date=2025-12-01"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "date": "2025-12-01",
  "task": {
    "id": 101,
    "taskName": "Turn on lights",
    "comment": "Check all sections",
    "taskGroup": 5,
    "listName": "Opening Tasks",
    "completionId": 501,
    "status": 2,
    "completedBy": 45,
    "completedAt": "2025-12-01 08:15:32",
    "completionNotes": "All lights working",
    "completedByFirstName": "John",
    "completedByLastName": "Smith"
  }
}
```

---

### 9. Get Schedule Configuration

Retrieves the full schedule configuration for all task lists across all days.

```
GET /api/:typeNum/workbook/tasks/schedule/
```

#### Example Request

```bash
curl -X GET "https://buyerkiosk.com/api/pc00/workbook/tasks/schedule/"
```

#### Success Response (HTTP 200)

```json
{
  "success": true,
  "schedule": [
    {
      "listId": 1,
      "displayName": "Morning Opening",
      "groupName": "Opening Tasks",
      "days": {
        "SUN": {
          "id": 1,
          "startTime": "09:00:00",
          "isActive": true
        },
        "MON": {
          "id": 2,
          "startTime": "08:00:00",
          "isActive": true
        },
        "TUE": {
          "id": 3,
          "startTime": "08:00:00",
          "isActive": true
        }
      }
    }
  ]
}
```

---

### 10. Update Schedule (Admin)

Updates the schedule for a specific task list.

```
PUT /api/:typeNum/workbook/tasks/schedule/:listId/
```

**Requires:** `uri_store_settings` or `workbook_manage_tasks` permission

#### Request Body

```json
{
  "days": {
    "SUN": "09:00:00",
    "MON": {
      "startTime": "08:00:00",
      "isActive": true
    },
    "TUE": {
      "startTime": "08:00:00",
      "isActive": true
    },
    "SAT": {
      "startTime": "10:00:00",
      "isActive": false
    }
  }
}
```

Each day can be either:
- A string time value (e.g., `"09:00:00"`) - assumes `isActive: true`
- An object with `startTime` and optional `isActive` fields

#### Example Request

```bash
curl -X PUT "https://buyerkiosk.com/api/pc00/workbook/tasks/schedule/1/" \
  -H "Content-Type: application/json" \
  -d '{
    "days": {
      "MON": "07:30:00",
      "TUE": "07:30:00"
    }
  }'
```

#### Success Response (HTTP 200)

```json
{
  "success": true
}
```

#### Error Response (HTTP 400)

```json
{
  "error": "Invalid day: MONDAY"
}
```

Valid days: `SUN`, `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`

---

### 11. Create Task List (Admin)

Creates a new task list configuration.

```
POST /api/:typeNum/workbook/tasks/lists/
```

**Requires:** `uri_store_settings` or `workbook_manage_tasks` permission

#### Request Body

```json
{
  "groupId": 5,
  "displayName": "Morning Opening",
  "scheduledDays": "MON TUE WED THU FRI",
  "startTime": "08:00:00",
  "sortOrder": 1
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `groupId` | int | Yes | Task group ID to link |
| `displayName` | string | No | Optional display name |
| `scheduledDays` | string | No | Days to show (default: all days) |
| `startTime` | string | No | Default start time (HH:MM:SS) |
| `sortOrder` | int | No | Display order (default: 0) |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/pc00/workbook/tasks/lists/" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": 5,
    "displayName": "Weekend Opening",
    "scheduledDays": "SAT SUN",
    "startTime": "10:00:00"
  }'
```

#### Success Response (HTTP 201)

```json
{
  "success": true,
  "listId": 3
}
```

---

### 12. Update Task List (Admin)

Updates a task list configuration.

```
PUT /api/:typeNum/workbook/tasks/lists/:listId/
```

**Requires:** `uri_store_settings` or `workbook_manage_tasks` permission

#### Request Body

All fields are optional - only include fields you want to update:

```json
{
  "displayName": "Updated Name",
  "scheduledDays": "MON TUE WED THU FRI SAT",
  "startTime": "07:30:00",
  "sortOrder": 2,
  "isActive": false
}
```

#### Example Request

```bash
curl -X PUT "https://buyerkiosk.com/api/pc00/workbook/tasks/lists/1/" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'
```

#### Success Response (HTTP 200)

```json
{
  "success": true
}
```

---

### 13. Assign Task (Admin)

Assigns a task to a specific employee.

```
POST /api/:typeNum/workbook/tasks/:taskId/assign/
```

**Requires:** `uri_store_settings` or `workbook_manage_tasks` permission

#### Request Body

```json
{
  "employeeId": 45,
  "dueDate": "2025-12-01",
  "dueTime": "12:00:00"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `employeeId` | int\|null | No | Employee ID (null = unassigned/all) |
| `dueDate` | string | No | Due date (Y-m-d), defaults to today |
| `dueTime` | string | No | Due time (HH:MM:SS) |

#### Example Request

```bash
curl -X POST "https://buyerkiosk.com/api/pc00/workbook/tasks/101/assign/" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": 45,
    "dueDate": "2025-12-01",
    "dueTime": "10:00:00"
  }'
```

#### Success Response (HTTP 201)

```json
{
  "success": true,
  "assignmentId": 25
}
```

---

## Task Status Values

| Value | Name | Description |
|-------|------|-------------|
| `0` | Not Started | Task has not been started |
| `1` | In Progress | Task is being worked on |
| `2` | Completed | Task is finished |

---

## Day of Week Values

Use these three-letter codes for `scheduledDays` and schedule configuration:

| Code | Day |
|------|-----|
| `SUN` | Sunday |
| `MON` | Monday |
| `TUE` | Tuesday |
| `WED` | Wednesday |
| `THU` | Thursday |
| `FRI` | Friday |
| `SAT` | Saturday |

---

## Real-Time Updates (Ably)

The Tasks API publishes real-time events via Ably when changes occur:

| Event | Trigger |
|-------|---------|
| `workbook:task:complete` | Task marked as completed |
| `workbook:task:progress` | Task marked as in progress |
| `workbook:task:uncomplete` | Task status reset to not started |
| `workbook:task:comment` | Comment added to task |

Subscribe to the store's workbook channel to receive these events.

---

## Error Responses

All endpoints may return these common errors:

**Access Denied (HTTP 403)**
```json
{
  "error": "Access denied"
}
```

**Permission Denied (HTTP 403)**
```json
{
  "error": "Access denied. Requires workbook_manage_tasks permission"
}
```

**Server Error (HTTP 500)**
```json
{
  "error": "Failed to retrieve task lists"
}
```

---

## Usage Notes

1. **Active List Logic**: The active list is determined by finding the most recent `startTime` that has already passed for the current day.

2. **Carryover Tasks**: Incomplete tasks from earlier lists appear in `carryoverTasks` and should be displayed prominently (typically in red) to indicate they are overdue.

3. **Date-Based Completion**: Task completion is tracked per date. The same task can have different completion states on different days.

4. **Schedule Override**: Each day can have a different start time via the schedule configuration. The `effectiveStartTime` reflects this.

5. **Task Recurrence**: Tasks have a `recurOn` field that determines which days they appear. Only tasks matching the current day are returned.

6. **Caching**: Task data is cached in Redis. The cache is automatically invalidated when status updates occur.

7. **Timezone**: All times are interpreted in the store's configured timezone.