# KROW Workforce Platform - API Documentation

**Version:** 2.0
**Last Updated:** 2025-11-11
**Project:** KROW Workforce Control Tower

## Table of Contents
1. [Overview](#overview)
2. [Authentication](#authentication)
3. [Entity Schemas](#entity-schemas)
4. [SDK Operations](#sdk-operations)
5. [Core Integrations](#core-integrations)
6. [Data Models Reference](#data-models-reference)
7. [Code Examples](#code-examples)
8. [Best Practices](#best-practices)
9. [Security Considerations](#security-considerations)
10. [Rate Limits & Quotas](#rate-limits--quotas)
11. [Changelog](#changelog)
12. [Support & Resources](#support--resources)

---

## Overview
KROW Workforce is a comprehensive workforce management platform built on Base44. This documentation provides complete API specifications for all entities, SDK methods, and integration endpoints.

### Base44 Client Import
```javascript
import { base44 } from "@/api/base44Client";
```

---

## Authentication

### User Authentication Methods
```javascript
// Get current authenticated user
const user = await base44.auth.me();

// Update current user
await base44.auth.updateMe({
  full_name: "John Doe",
  custom_field: "value"
});

// Logout
base44.auth.logout(redirectUrl?: string);

// Redirect to login
base44.auth.redirectToLogin(nextUrl?: string);

// Check authentication status
const isAuthenticated = await base44.auth.isAuthenticated();
```

### User Object Structure
```json
{
  "id": "string",
  "email": "string",
  "full_name": "string",
  "role": ""admin" | "user"",
  "user_role": "string", // Custom role field
  "created_date": "timestamp",
  "updated_date": "timestamp",
  // ... custom fields
}
```

---

## Entity Schemas

### 1. User Entity (Built-in)
Description: Core user entity with authentication and role management.

| Field Name | Type      | Description             | Validation                               |
| :--------- | :-------- | :---------------------- | :--------------------------------------- |
| `id`       | `string`  | Unique user identifier  | Auto-generated, unique                   |
| `email`    | `string`  | User email address      | Required, unique, email format           |
| `full_name`| `string`  | User's full name        | Required                                 |
| `role`     | `string`  | Base role               | Enum: "admin", "user"                    |
| `user_role`| `string`  | Custom application role | Optional, custom values                  |
| `created_date`| `timestamp`| Account creation date   | Auto-generated                           |
| `updated_date`| `timestamp`| Last update timestamp   | Auto-updated                             |

JSON Schema:
```json
{
  "type": "object",
  "properties": {
    "email": {"type": "string", "format": "email"},
    "full_name": {"type": "string"},
    "role": {"type": "string", "enum": ["admin", "user"]},
    "user_role": {"type": "string"}
  }
}
```

Security Rules:
- Only admin users can list, update, or delete other users
- Regular users can only view and update their own user record
- These rules are automatically enforced

### 2. Event Entity
Description: Core event/order management entity for workforce scheduling.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique event identifier | Auto-generated                                                          |
| `event_name`| `string`  | Name of the event       | Required                                                                |
| `is_recurring`| `boolean`| Whether event recurs    | Default: false                                                          |
| `recurrence_type`| `string`| Type of recurrence      | Enum: "single", "date_range", "scatter"                                 |
| `recurrence_start_date`| `date`| Start date for recurring events| Optional                                                                |
| `recurrence_end_date`| `date`| End date for recurring events  | Optional                                                                |
| `scatter_dates`| `array` | Specific dates for scatter recurring| Array of date strings                                                   |
| `business_id`| `string`  | Associated business ID  | Optional                                                                |
| `business_name`| `string`  | Business name           | Optional                                                                |
| `vendor_id`| `string`  | Vendor ID if created by vendor| Optional                                                                |
| `vendor_name`| `string`  | Vendor name             | Optional                                                                |
| `hub`      | `string`  | Hub location            | Optional                                                                |
| `contract_type`| `string`| Contract type           | Enum: "W2", "1099", "Temp", "Contract"                                  |
| `po_reference`| `string`| Purchase order reference| Optional                                                                |
| `status`   | `string`  | Event status            | Enum: "Draft", "Active", "Pending", "Assigned", "Confirmed", "Completed", "Canceled" |
| `date`     | `date`    | Event date              | Optional                                                                |
| `shifts`   | `array`   | Array of shift objects  | Optional                                                                |
| `addons`   | `object`  | Additional services/features| Optional                                                                |
| `total`    | `number`  | Total cost              | Optional                                                                |
| `client_name`| `string`  | Client contact name     | Optional                                                                |
| `client_email`| `string`| Client email            | Optional                                                                |
| `client_phone`| `string`| Client phone            | Optional                                                                |
| `notes`    | `string`  | Additional notes        | Optional                                                                |
| `requested`| `number`  | Total staff requested   | Optional                                                                |
| `assigned_staff`| `array`| Array of assigned staff | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |
| `created_by`| `string`  | Creator email           | Auto-populated                                                          |

Shifts Structure:
```json
{
  "shift_name": "string",
  "shift_contact": "string",
  "location_address": "string",
  "roles": [
    {
      "role": "string",
      "department": "string",
      "count": "number",
      "start_time": "string",
      "end_time": "string",
      "hours": "number",
      "uniform": "string",
      "break_minutes": "number",
      "cost_per_hour": "number",
      "total_value": "number",
      "vendor_name": "string",
      "vendor_id": "string"
    }
  ]
}
```

### 3. Staff Entity
Description: Employee/workforce member management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique staff identifier | Auto-generated                                                          |
| `employee_name`| `string`| Full name               | Required                                                                |
| `vendor_id`| `string`  | Associated vendor ID    | Optional                                                                |
| `vendor_name`| `string`| Vendor company name     | Optional                                                                |
| `manager`  | `string`  | Manager's name          | Optional                                                                |
| `contact_number`| `string`| Primary contact number  | Optional                                                                |
| `phone`    | `string`  | Additional phone        | Optional                                                                |
| `email`    | `string`  | Email address           | Email format                                                            |
| `department`| `string` | Department              | Enum: "Operations", "Sales", "HR", "Finance", "IT", "Marketing", "Customer Service", "Logistics" |
| `hub_location`| `string`| Hub/office location     | Optional                                                                |
| `event_location`| `string`| Event location          | Optional                                                                |
| `address`  | `string`  | Employee address        | Optional                                                                |
| `city`     | `string`  | City                    | Optional                                                                |
| `position` | `string`  | Primary job position/skill| Optional                                                                |
| `position_2`| `string` | Secondary job position/skill| Optional                                                                |
| `profile_type`| `string`| Skill profile level     | Enum: "Skilled", "Beginner", "Cross-Trained"                            |
| `employment_type`| `string`| Employment type         | Enum: "Full Time", "Part Time", "On call", "Weekends", "Specific Days", "Seasonal", "Medical Leave" |
| `english`  | `string`  | English proficiency     | Enum: "Fluent", "Intermediate", "Basic", "None"                         |
| `english_required`| `boolean`| English required        | Optional                                                                |
| `rating`   | `number`  | Performance rating      | Min: 0, Max: 5                                                          |
| `shift_coverage_percentage`| `number`| Shift coverage %        | Min: 0, Max: 100                                                        |
| `cancellation_count`| `number`| Number of cancellations | Min: 0                                                                  |
| `no_show_count`| `number`| Number of no-shows      | Min: 0                                                                  |
| `total_shifts`| `number`| Total shifts assigned   | Min: 0                                                                  |
| `reliability_score`| `number`| Reliability score       | Min: 0, Max: 100                                                        |
| `background_check_status`| `string`| Background check status | Enum: "pending", "cleared", "failed", "expired", "not_required"         |
| `background_check_date`| `date`| Last background check date| Optional                                                                |
| `certifications`| `array`| List of certifications  | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |
| `created_by`| `string`  | Creator email           | Auto-populated                                                          |

### 4. Vendor Entity
Description: Vendor/supplier management and onboarding.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique vendor identifier| Auto-generated                                                          |
| `vendor_number`| `string`| Vendor Number (VN-####) | Required, Pattern: `^VN-[0-9]{4}$`                                      |
| `legal_name`| `string` | Legal business name     | Required                                                                |
| `doing_business_as`| `string`| DBA/Trade name          | Optional                                                                |
| `region`   | `string`  | Geographic region       | Enum: "National", "Bay Area", "Southern California", "Northern California", "West", "East", "Midwest", "South" |
| `state`    | `string`  | Primary state           | Optional                                                                |
| `city`     | `string`  | Primary city            | Optional                                                                |
| `service_specialty`| `string`| Service specialty       | Optional                                                                |
| `workforce_count`| `number`| Total workforce count   | Optional                                                                |
| `platform_type`| `string`| Technology integration level| Enum: "Full Platform", "Building platform (KROW)", "Partial Tech", "Traditional" |
| `tax_id`   | `string`  | Federal Tax ID/EIN      | Optional                                                                |
| `business_type`| `string`| Business entity type    | Enum: "Corporation", "LLC", "Partnership", "Sole Proprietorship"        |
| `primary_contact_name`| `string`| Primary contact         | Optional                                                                |
| `primary_contact_email`| `string`| Primary email           | Required, Email format                                                  |
| `primary_contact_phone`| `string`| Primary phone           | Optional                                                                |
| `billing_address`| `string`| Billing address         | Optional                                                                |
| `service_address`| `string`| Service/office address  | Optional                                                                |
| `coverage_regions`| `array`| Geographic coverage     | Array of strings                                                        |
| `eligible_roles`| `array`| Roles/positions provided| Array of strings                                                        |
| `insurance_certificate`| `string`| URL to insurance cert   | Optional                                                                |
| `insurance_expiry`| `date`| Insurance expiration    | Optional                                                                |
| `w9_document`| `string` | URL to W9 form          | Optional                                                                |
| `coi_document`| `string` | URL to COI              | Optional                                                                |
| `approval_status`| `string`| Vendor approval status  | Enum: "pending", "approved", "suspended", "terminated"                  |
| `approved_date`| `date` | Approval date           | Optional                                                                |
| `approved_by`| `string` | Approver                | Optional                                                                |
| `is_active`| `boolean` | Active status           | Default: true                                                           |
| `notes`    | `string`  | Internal notes          | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 5. VendorRate Entity
Description: Vendor pricing and rate management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique rate identifier  | Auto-generated                                                          |
| `vendor_id`| `string`  | Vendor ID               | Optional                                                                |
| `vendor_name`| `string`| Vendor name             | Required                                                                |
| `category` | `string`  | Service category        | Enum: "Kitchen and Culinary", "Concessions", "Facilities", "Bartending", "Security", "Event Staff", "Management", "Technical", "Other" |
| `role_name`| `string`  | Role/position name      | Required                                                                |
| `employee_wage`| `number`| Employee base wage/hour | Required, Min: 0                                                        |
| `markup_percentage`| `number`| Markup percentage       | Min: 0, Max: 100                                                        |
| `vendor_fee_percentage`| `number`| Vendor fee percentage   | Min: 0, Max: 100                                                        |
| `client_rate`| `number` | Final rate to client    | Required, Min: 0                                                        |
| `is_active`| `boolean` | Active status           | Default: true                                                           |
| `minimum_wage_compliance`| `boolean`| Meets minimum wage      | Optional                                                                |
| `pricing_status`| `string`| Pricing analysis        | Enum: "optimal", "underpriced", "overpriced", "competitive"             |
| `market_average`| `number`| Market average rate     | Optional                                                                |
| `notes`    | `string`  | Additional notes        | Optional                                                                |
| `available_to_clients`| `array`| Client IDs with access  | Array of strings                                                        |
| `client_visibility`| `string`| Visibility setting      | Enum: "all", "specific", "none"                                         |
| `competitive_status`| `boolean`| Competitive pricing     | Default: false                                                          |
| `csta_compliant`| `boolean`| CA Staffing Agency compliant| Default: false                                                          |
| `compliance_verified`| `boolean`| Compliance verified     | Default: false                                                          |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 6. Invoice Entity
Description: Invoice and billing management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique invoice identifier| Auto-generated                                                          |
| `invoice_number`| `string`| Unique invoice number   | Required                                                                |
| `manager_name`| `string`| Manager/client name     | Optional                                                                |
| `hub`      | `string`  | Hub location            | Optional                                                                |
| `cost_center`| `string` | Cost center/department  | Optional                                                                |
| `event_id` | `string`  | Related event ID        | Optional                                                                |
| `event_name`| `string` | Event name              | Optional                                                                |
| `business_name`| `string`| Client/Business name    | Required                                                                |
| `vendor_name`| `string`| Vendor name             | Optional                                                                |
| `amount`   | `number`  | Invoice amount          | Required, Min: 0                                                        |
| `item_count`| `number` | Number of items         | Min: 0                                                                  |
| `status`   | `string`  | Invoice status          | Enum: "Open", "Disputed", "Resolved", "Verified", "Overdue", "Reconciled", "Paid", "Confirmed", "Pending" |
| `issue_date`| `date`   | Invoice issue date      | Required                                                                |
| `due_date` | `date`    | Payment due date        | Required                                                                |
| `paid_date`| `date`    | Payment received date   | Optional                                                                |
| `payment_method`| `string`| Payment method          | Enum: "Credit Card", "ACH", "Wire Transfer", "Check", "Cash"            |
| `notes`    | `string`  | Additional notes        | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 7. Business Entity
Description: Client business/company management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique business identifier| Auto-generated                                                          |
| `business_name`| `string`| Business/client company name| Required                                                                |
| `company_logo`| `string`| URL to company logo     | Optional                                                                |
| `contact_name`| `string`| Primary contact person  | Required                                                                |
| `email`    | `string`  | Business email          | Email format                                                            |
| `phone`    | `string`  | Business phone          | Optional                                                                |
| `hub_building`| `string`| Hub/building name       | Optional                                                                |
| `address`  | `string`  | Street address          | Optional                                                                |
| `city`     | `string`  | City                    | Optional                                                                |
| `area`     | `string`  | Geographic area         | Enum: "Bay Area", "Southern California", "Northern California", "Central Valley", "Other" |
| `sector`   | `string`  | Sector/industry         | Enum: "Bon Appétit", "Eurest", "Aramark", "Epicurean Group", "Chartwells", "Other" |
| `rate_group`| `string` | Pricing tier            | Required, Enum: "Standard", "Premium", "Enterprise", "Custom"           |
| `status`   | `string`  | Business status         | Enum: "Active", "Inactive", "Pending"                                   |
| `notes`    | `string`  | Additional notes        | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 8. Certification Entity
Description: Employee certification and compliance tracking.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique certification ID | Auto-generated                                                          |
| `employee_id`| `string`| Staff member ID         | Optional                                                                |
| `employee_name`| `string`| Staff member name       | Required                                                                |
| `vendor_id`| `string`  | Vendor ID               | Optional                                                                |
| `vendor_name`| `string`| Vendor name             | Optional                                                                |
| `certification_name`| `string`| Certification name      | Required                                                                |
| `certification_type`| `string`| Type of certification   | Enum: "Legal", "Operational", "Safety", "Training", "License", "Other"  |
| `status`   | `string`  | Current status          | Enum: "current", "expiring_soon", "expired", "pending_validation"       |
| `issue_date`| `date`   | Issue date              | Optional                                                                |
| `expiry_date`| `date`  | Expiration date         | Required                                                                |
| `issuer`   | `string`  | Issuing authority       | Optional                                                                |
| `certificate_number`| `string`| Certificate ID          | Optional                                                                |
| `document_url`| `string`| Uploaded certificate URL| Optional                                                                |
| `validation_status`| `string`| Validation status       | Enum: "approved", "pending_expert_review", "rejected", "ai_verified", "ai_flagged", "manual_review_needed" |
| `ai_validation_result`| `object`| AI validation results   | Optional                                                                |
| `validated_by`| `string`| Validator               | Optional                                                                |
| `validated_date`| `date`| Validation date         | Optional                                                                |
| `is_required_for_role`| `boolean`| Required for role       | Default: false                                                          |
| `days_until_expiry`| `number`| Auto-calculated days    | Optional                                                                |
| `alert_sent`| `boolean` | Expiry alert sent       | Default: false                                                          |
| `notes`    | `string`  | Additional notes        | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 9. Team Entity
Description: Team and organization management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique team identifier  | Auto-generated                                                          |
| `team_name`| `string`  | Name of the team        | Required                                                                |
| `owner_id` | `string`  | Team owner user ID      | Required                                                                |
| `owner_name`| `string` | Team owner name         | Required                                                                |
| `owner_role`| `string` | Role of team owner      | Required, Enum: "admin", "procurement", "operator", "sector", "client", "vendor", "workforce" |
| `company_logo`| `string`| URL to company logo     | Optional                                                                |
| `full_name`| `string`  | Primary contact name    | Optional                                                                |
| `email`    | `string`  | Contact email           | Email format                                                            |
| `phone`    | `string`  | Contact phone           | Optional                                                                |
| `address`  | `string`  | Company address         | Optional                                                                |
| `city`     | `string`  | City                    | Optional                                                                |
| `zip_code` | `string`  | ZIP code                | Optional                                                                |
| `vendor_id`| `string`  | Vendor ID if applicable | Optional                                                                |
| `departments`| `array` | Available departments   | Array of strings                                                        |
| `total_members`| `number`| Total team members      | Default: 0                                                              |
| `active_members`| `number`| Active members          | Default: 0                                                              |
| `total_hubs`| `number` | Total hubs              | Default: 0                                                              |
| `favorite_staff_count`| `number`| Favorite staff count    | Default: 0                                                              |
| `blocked_staff_count`| `number`| Blocked staff count     | Default: 0                                                              |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 10. Conversation Entity
Description: Messaging and communication management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique conversation ID  | Auto-generated                                                          |
| `participants`| `array` | Array of participant objects| Required                                                                |
| `conversation_type`| `string`| Type of conversation    | Required, Enum: "client-vendor", "staff-client", "staff-admin", "vendor-admin", "client-admin", "group-staff", "group-event-staff" |
| `is_group` | `boolean` | Is group conversation   | Default: false                                                          |
| `group_name`| `string` | Group name              | Optional                                                                |
| `related_to`| `string` | Related entity ID       | Optional                                                                |
| `related_type`| `string`| Related entity type     | Enum: "event", "staff", "business", "general"                           |
| `subject`  | `string`  | Conversation subject    | Optional                                                                |
| `last_message`| `string`| Preview of last message | Optional                                                                |
| `last_message_at`| `timestamp`| Last message timestamp  | Optional                                                                |
| `unread_count`| `number`| Unread message count    | Default: 0                                                              |
| `status`   | `string`  | Conversation status     | Enum: "active", "archived", "closed"                                    |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 11. Message Entity
Description: Individual messages within conversations.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique message identifier| Auto-generated                                                          |
| `conversation_id`| `string`| Conversation ID         | Required                                                                |
| `sender_id`| `string`  | Sender ID               | Optional                                                                |
| `sender_name`| `string`| Sender name             | Required                                                                |
| `sender_role`| `string`| Sender role             | Enum: "client", "vendor", "staff", "admin"                              |
| `content`  | `string`  | Message content         | Required                                                                |
| `read_by`  | `array`   | User IDs who read       | Array of strings                                                        |
| `attachments`| `array` | Attached files          | Array of objects                                                        |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 12. ActivityLog Entity
Description: Activity and notification tracking.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique activity identifier| Auto-generated                                                          |
| `title`    | `string`  | Notification title      | Required                                                                |
| `description`| `string`| Detailed description    | Required                                                                |
| `activity_type`| `string`| Type of activity        | Required, Enum: "event_created", "event_updated", "event_rescheduled", "event_canceled", "staff_assigned", "staff_removed", "invoice_paid", "invoice_created", "message_received", "order_created", "order_updated" |
| `related_entity_type`| `string`| Related entity type     | Enum: "event", "staff", "invoice", "message", "order", "user"           |
| `related_entity_id`| `string`| Related entity ID       | Optional                                                                |
| `action_link`| `string`| Link to related item    | Optional                                                                |
| `action_label`| `string`| Action button label     | Optional                                                                |
| `user_id`  | `string`  | User this is for        | Required                                                                |
| `is_read`  | `boolean` | Read status             | Default: false                                                          |
| `icon_type`| `string`  | Icon to display         | Enum: "calendar", "user", "invoice", "message", "alert", "check"        |
| `icon_color`| `string` | Icon color theme        | Enum: "blue", "red", "green", "yellow", "purple"                        |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 13. Enterprise Entity
Description: Enterprise organization management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique enterprise ID    | Auto-generated                                                          |
| `enterprise_number`| `string`| Enterprise Number (EN-####)| Required, Pattern: `^EN-[0-9]{4}$`                                      |
| `enterprise_name`| `string`| Enterprise name         | Required                                                                |
| `enterprise_code`| `string`| Short code identifier   | Required                                                                |
| `brand_family`| `array` | Brands under enterprise | Array of strings                                                        |
| `headquarters_address`| `string`| HQ address              | Optional                                                                |
| `global_policies`| `object`| Global policies         | Optional                                                                |
| `sector_registry`| `array`| Sector IDs              | Array of strings                                                        |
| `rate_guardrails`| `object`| Rate limits             | Optional                                                                |
| `primary_contact_name`| `string`| Contact name            | Optional                                                                |
| `primary_contact_email`| `string`| Contact email           | Email format                                                            |
| `is_active`| `boolean` | Active status           | Default: true                                                           |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 14. Sector Entity
Description: Sector/branch management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique sector identifier| Auto-generated                                                          |
| `sector_number`| `string`| Sector Number (SN-####) | Required, Pattern: `^SN-[0-9]{4}$`                                      |
| `sector_name`| `string` | Sector/brand name       | Required                                                                |
| `sector_code`| `string` | Short code identifier   | Required                                                                |
| `parent_enterprise_id`| `string`| Parent enterprise ID    | Optional                                                                |
| `parent_enterprise_name`| `string`| Parent enterprise name  | Optional                                                                |
| `sector_type`| `string` | Sector business type    | Enum: "Food Service", "Facilities", "Healthcare", "Education", "Corporate", "Sports & Entertainment" |
| `client_portfolio`| `array`| Partner/client IDs      | Array of strings                                                        |
| `sector_policies`| `object`| Sector-specific policies| Optional                                                                |
| `approved_vendors`| `array`| Approved vendor IDs     | Array of strings                                                        |
| `is_active`| `boolean` | Active status           | Default: true                                                           |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 15. Partner Entity
Description: Partner/client organization management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique partner identifier| Auto-generated                                                          |
| `partner_name`| `string`| Partner/client name     | Required                                                                |
| `partner_number`| `string`| Partner Number (PN-####)| Required, Pattern: `^PN-[0-9]{4}$`                                      |
| `partner_type`| `string`| Partner type            | Enum: "Corporate", "Education", "Healthcare", "Sports & Entertainment", "Government" |
| `sector_id`| `string`  | Sector ID               | Optional                                                                |
| `sector_name`| `string`| Sector name             | Optional                                                                |
| `primary_contact_name`| `string`| Primary contact         | Optional                                                                |
| `primary_contact_email`| `string`| Primary email           | Email format                                                            |
| `primary_contact_phone`| `string`| Primary phone           | Optional                                                                |
| `billing_address`| `string`| Billing address         | Optional                                                                |
| `sites`    | `array`   | Partner sites/locations | Array of objects                                                        |
| `allowed_vendors`| `array`| Allowed vendor IDs      | Array of strings                                                        |
| `rate_exceptions`| `array`| Rate exceptions         | Array of objects                                                        |
| `cost_centers`| `array` | Cost centers/PO numbers | Array of strings                                                        |
| `payment_terms`| `string`| Payment terms           | Default: "Net 30"                                                       |
| `is_active`| `boolean` | Active status           | Default: true                                                           |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 16. Order Entity
Description: Order management system.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique order identifier | Auto-generated                                                          |
| `order_number`| `string`| Order Number (ORD-####) | Required, Pattern: `^ORD-[0-9]{4,6}$`                                   |
| `partner_id`| `string` | Partner/Client ID       | Required                                                                |
| `partner_name`| `string`| Partner/Client name     | Optional                                                                |
| `site_id`  | `string`  | Site/location ID        | Optional                                                                |
| `site_name`| `string`  | Site/location name      | Optional                                                                |
| `site_address`| `string`| Event/site address      | Optional                                                                |
| `sector_id`| `string`  | Sector ID               | Optional                                                                |
| `enterprise_id`| `string`| Enterprise ID           | Optional                                                                |
| `order_type`| `string` | Type of order           | Enum: "Standard", "Last Minute", "Emergency", "Recurring"               |
| `cost_center`| `string`| Cost center             | Optional                                                                |
| `po_number`| `string`  | Purchase order number   | Optional                                                                |
| `roles_requested`| `array`| Roles and headcount     | Array of objects                                                        |
| `tags`     | `array`   | Order tags/labels       | Array of strings                                                        |
| `point_of_contact`| `object`| On-site contact         | Optional                                                                |
| `sla_targets`| `object`| SLA targets             | Optional                                                                |
| `order_status`| `string`| Order status            | Enum: "Draft", "Submitted", "Confirmed", "In Progress", "Completed", "Cancelled" |
| `submitted_date`| `timestamp`| Submission date         | Optional                                                                |
| `confirmed_date`| `timestamp`| Confirmation date       | Optional                                                                |
| `special_instructions`| `string`| Special instructions    | Optional                                                                |
| `total_estimated_cost`| `number`| Estimated total cost    | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

### 17. Shift Entity
Description: Shift scheduling and management.

| Field Name | Type      | Description             | Validation                                                              |
| :--------- | :-------- | :---------------------- | :---------------------------------------------------------------------- |
| `id`       | `string`  | Unique shift identifier | Auto-generated                                                          |
| `event_id` | `string`  | Associated event ID     | Optional                                                                |
| `shift_name`| `string` | Name of the shift       | Required                                                                |
| `manager_id`| `string` | Manager staff ID        | Optional                                                                |
| `manager_name`| `string`| Manager name            | Optional                                                                |
| `location` | `string`  | Shift location          | Optional                                                                |
| `start_date`| `timestamp`| Shift start date/time   | Required                                                                |
| `end_date` | `timestamp`| Shift end date/time     | Optional                                                                |
| `unpaid_break`| `number`| Unpaid break in minutes | Optional                                                                |
| `count`    | `number`  | Number of staff needed  | Optional                                                                |
| `assigned` | `number`  | Number of staff assigned| Optional                                                                |
| `uniform_type`| `string`| Required uniform type   | Optional                                                                |
| `price`    | `number`  | Price per staff member  | Optional                                                                |
| `amount`   | `number`  | Total amount for shift  | Optional                                                                |
| `assigned_staff`| `array`| List of assigned staff  | Array of objects                                                        |
| `role`     | `string`  | Role for this shift     | Optional                                                                |
| `department`| `string` | Department              | Optional                                                                |
| `created_date`| `timestamp`| Creation date           | Auto-generated                                                          |
| `updated_date`| `timestamp`| Last update             | Auto-updated                                                            |

---

## SDK Operations

### Standard Entity Operations
All entities support the following base operations:

#### List All Records
```javascript
// List all records (default limit: 50)
const records = await base44.entities.EntityName.list();

// List with sorting (descending by created_date)
const records = await base44.entities.EntityName.list('-created_date');

// List with sorting and limit
const records = await base44.entities.EntityName.list('-created_date', 20);
```

#### Filter Records
```javascript
// Filter by single field
const records = await base44.entities.EntityName.filter({
  status: 'Active'
});

// Filter with multiple conditions
const records = await base44.entities.EntityName.filter({
  status: 'Active',
  created_by: user.email
});

// Filter with sorting and limit
const records = await base44.entities.EntityName.filter(
  { status: 'Active' },
  '-created_date',
  10
);

// Filter with operators
const records = await base44.entities.EntityName.filter({
  rating: { $gte: 4.5 },
  total: { $lte: 1000 }
});
```

#### Create Record
```javascript
// Create single record
const newRecord = await base44.entities.EntityName.create({
  field1: 'value1',
  field2: 'value2'
});

// Returns created record with id
```

#### Bulk Create Records
```javascript
// Create multiple records
const newRecords = await base44.entities.EntityName.bulkCreate([
  { field1: 'value1' },
  { field1: 'value2' },
  { field1: 'value3' }
]);

// Returns array of created records
```

#### Update Record
```javascript
// Update by ID
const updatedRecord = await base44.entities.EntityName.update(recordId, {
  field1: 'new value'
});

// Returns updated record
```

#### Delete Record
```javascript
// Delete by ID
await base44.entities.EntityName.delete(recordId);
```

#### Get Entity Schema
```javascript
// Get JSON schema (without built-in fields)
const schema = await base44.entities.EntityName.schema();

// Useful for dynamic form generation
```

### Entity-Specific Examples

#### Event Operations
```javascript
// List recent events
const events = await base44.entities.Event.list('-date', 50);

// Filter vendor's events
const myEvents = await base44.entities.Event.filter({
  vendor_id: user.id,
  status: 'Active'
}, '-date', 20);

// Create new event
const newEvent = await base44.entities.Event.create({
  event_name: 'Corporate Luncheon',
  business_name: 'Acme Corp',
  date: '2025-12-01',
  status: 'Draft',
  requested: 15
});

// Update event status
await base44.entities.Event.update(eventId, {
  status: 'Confirmed'
});
```

#### Staff Operations
```javascript
// List all active staff
const staff = await base44.entities.Staff.list('-created_date');

// Filter by vendor
const vendorStaff = await base44.entities.Staff.filter({
  vendor_id: vendorId
});

// Filter by rating
const topStaff = await base44.entities.Staff.filter({
  rating: { $gte: 4.5 }
}, '-rating', 10);

// Create staff member
const newStaff = await base44.entities.Staff.create({
  employee_name: 'John Doe',
  vendor_name: 'ABC Staffing',
  position: 'Server',
  employment_type: 'Part Time'
});

// Update staff rating
await base44.entities.Staff.update(staffId, {
  rating: 4.8,
  reliability_score: 95
});
```

#### Invoice Operations
```javascript
// List unpaid invoices
const unpaid = await base44.entities.Invoice.filter({
  status: 'Open'
}, '-due_date');

// Get client's invoices
const clientInvoices = await base44.entities.Invoice.filter({
  business_name: clientName
});

// Create invoice
const invoice = await base44.entities.Invoice.create({
  invoice_number: 'INV-2025-001',
  business_name: 'Client Corp',
  amount: 5000,
  status: 'Open',
  issue_date: '2025-01-01',
  due_date: '2025-01-31'
});

// Mark as paid
await base44.entities.Invoice.update(invoiceId, {
  status: 'Paid',
  paid_date: new Date().toISOString()
});
```

#### Conversation & Message Operations
```javascript
// List active conversations
const conversations = await base44.entities.Conversation.filter({
  status: 'active',
  participants: { $contains: userId }
}, '-last_message_at');

// Create conversation
const conversation = await base44.entities.Conversation.create({
  participants: [
    { id: user1Id, name: user1Name, role: 'client' },
    { id: user2Id, name: user2Name, role: 'vendor' }
  ],
  conversation_type: 'client-vendor',
  subject: 'Event #123 Discussion',
  status: 'active'
});

// Send message
const message = await base44.entities.Message.create({
  conversation_id: conversationId,
  sender_id: userId,
  sender_name: userName,
  sender_role: 'client',
  content: 'Hello, can we discuss the event details?'
});

// Mark as read
await base44.entities.Message.update(messageId, {
  read_by: [...existingReadBy, userId]
});
```

---

## Core Integrations

### Integration: InvokeLLM
Description: Generate responses from an LLM with optional web context or file attachments.

| Parameter                 | Type      | Required | Description                                            |
| :------------------------ | :-------- | :------- | :----------------------------------------------------- |
| `prompt`                  | `string`  | Yes      | The prompt to send to the LLM                          |
| `add_context_from_internet`| `boolean` | No       | Fetch context from Google Search, Maps, News (default: false) |
| `response_json_schema`    | `object`  | No       | JSON schema for structured output                      |
| `file_urls`               | `string[]`| No       | Array of file URLs for additional context              |

Returns:
- If `response_json_schema` specified: `object` (parsed JSON)
- Otherwise: `string`

Examples:
```javascript
// Simple text response
const response = await base44.integrations.Core.InvokeLLM({
  prompt: "Summarize the top 3 benefits of workforce automation"
});

// Structured JSON response
const data = await base44.integrations.Core.InvokeLLM({
  prompt: "Extract key information about Apple Inc.",
  add_context_from_internet: true,
  response_json_schema: {
    type: "object",
    properties: {
      stock_price: { type: "number" },
      ceo: { type: "string" },
      headquarters: { type: "string" },
      recent_news: {
        type: "array",
        items: { type: "string" }
      }
    }
  }
});

// With file context
const analysis = await base44.integrations.Core.InvokeLLM({
  prompt: "Analyze this invoice and extract line items",
  file_urls: [invoiceFileUrl],
  response_json_schema: {
    type: "object",
    properties: {
      line_items: {
        type: "array",
        items: {
          type: "object",
          properties: {
            description: { type: "string" },
            quantity: { type: "number" },
            rate: { type: "number" },
            amount: { type: "number" }
          }
        }
      },
      total: { type: "number" }
    }
  }
});
```

### Integration: SendEmail
Description: Send an email to a user.

| Parameter | Type      | Required | Description                                            |
| :-------- | :-------- | :------- | :----------------------------------------------------- |
| `to`      | `string`  | Yes      | Recipient email address                                |
| `subject` | `string`  | Yes      | Email subject line                                     |
| `body`    | `string`  | Yes      | Email body (supports HTML)                             |
| `from_name`| `string` | No       | Sender name (defaults to app name)                     |

Returns: `void`

Example:
```javascript
await base44.integrations.Core.SendEmail({
  to: 'client@example.com',
  subject: 'Your Event Has Been Confirmed',
  body: `
    <h2>Event Confirmation</h2>
    <p>Hello ${clientName},</p>
    <p>Your event "${eventName}" has been confirmed for ${eventDate}.</p>
    <p>Staff assigned: ${staffCount}</p>
    <p>Thank you for using KROW Workforce!</p>
  `,
  from_name: 'KROW Workforce Team'
});
```

### Integration: UploadFile
Description: Upload a file to public storage.

| Parameter | Type   | Required | Description             |
| :-------- | :----- | :------- | :---------------------- |
| `file`    | `File` | Yes      | File object to upload   |

Returns:
```json
{
  "file_url": "string"  // Public URL to the uploaded file
}
```

Example:
```javascript
// From file input
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const { file_url } = await base44.integrations.Core.UploadFile({
  file: file
});

// Use the URL
await base44.entities.Staff.update(staffId, {
  profile_picture: file_url
});
```

### Integration: UploadPrivateFile
Description: Upload a file to private storage (requires signed URL for access).

| Parameter | Type   | Required | Description             |
| :-------- | :----- | :------- | :---------------------- |
| `file`    | `File` | Yes      | File object to upload   |

Returns:
```json
{
  "file_uri": "string"  // Private file URI (not directly accessible)
}
```

Example:
```javascript
// Upload private document
const { file_uri } = await base44.integrations.Core.UploadPrivateFile({
  file: sensitiveDocument
});

// Store the URI
await base44.entities.Vendor.update(vendorId, {
  w9_document: file_uri
});

// Later, create signed URL for access
const { signed_url } = await base44.integrations.Core.CreateFileSignedUrl({
  file_uri: file_uri,
  expires_in: 3600  // 1 hour
});
```

### Integration: CreateFileSignedUrl
Description: Create a temporary signed URL for accessing a private file.

| Parameter  | Type      | Required | Description                                            |
| :--------- | :-------- | :------- | :----------------------------------------------------- |
| `file_uri` | `string`  | Yes      | Private file URI                                       |
| `expires_in`| `number` | No       | Expiration time in seconds (default: 300)              |

Returns:
```json
{
  "signed_url": "string"  // Temporary URL for file access
}
```

Example:
```javascript
// Create 1-hour signed URL
const { signed_url } = await base44.integrations.Core.CreateFileSignedUrl({
  file_uri: vendor.w9_document,
  expires_in: 3600
});

// Use signed URL
window.open(signed_url, '_blank');
```

### Integration: ExtractDataFromUploadedFile
Description: Extract structured data from uploaded files (CSV, PDF, images).

| Parameter   | Type      | Required | Description                                            |
| :---------- | :-------- | :------- | :----------------------------------------------------- |
| `file_url`  | `string`  | Yes      | URL to uploaded file                                   |
| `json_schema`| `object` | Yes      | JSON schema defining expected data structure           |

Returns:
```json
{
  "status": ""success" | "error"",
  "details": "string | null",  // Error details if status is error
  "output": "object[] | object | null"  // Extracted data if successful
}
```

Example:
```javascript
// Upload CSV of staff members
const { file_url } = await base44.integrations.Core.UploadFile({
  file: csvFile
});

// Extract data
const result = await base44.integrations.Core.ExtractDataFromUploadedFile({
  file_url: file_url,
  json_schema: {
    type: "array",
    items: {
      type: "object",
      properties: {
        employee_name: { type: "string" },
        email: { type: "string" },
        position: { type: "string" },
        department: { type: "string" },
        phone: { type: "string" }
      }
    }
  }
});

if (result.status === "success") {
  // Bulk create staff from extracted data
  await base44.entities.Staff.bulkCreate(result.output);
}
```

### Integration: GenerateImage
Description: Generate an AI image from a text prompt.

| Parameter | Type      | Required | Description                                            |
| :-------- | :-------- | :------- | :----------------------------------------------------- |
| `prompt`  | `string`  | Yes      | Detailed image description                             |

Returns:
```json
{
  "url": "string"  // URL to generated image
}
```

Example:
```javascript
// Generate event banner
const { url } = await base44.integrations.Core.GenerateImage({
  prompt: "Professional corporate event banner with elegant food service theme, blue and white color scheme, modern minimalist design"
});

// Use the generated image
await base44.entities.Event.update(eventId, {
  banner_image: url
});
```

---

## Data Models Reference

### Complete Event Object Example
```json
{
  "id": "evt_1234567890",
  "event_name": "Google Campus Lunch Service",
  "is_recurring": true,
  "recurrence_type": "date_range",
  "recurrence_start_date": "2025-01-01",
  "recurrence_end_date": "2025-12-31",
  "business_id": "bus_0987654321",
  "business_name": "Google",
  "vendor_id": "vnd_1122334455",
  "vendor_name": "Elite Staffing Solutions",
  "hub": "Mountain View Campus",
  "contract_type": "W2",
  "po_reference": "PO-2025-001",
  "status": "Active",
  "date": "2025-01-15",
  "shifts": [
    {
      "shift_name": "Lunch Shift",
      "shift_contact": "John Manager",
      "location_address": "1600 Amphitheatre Parkway",
      "roles": [
        {
          "role": "Server",
          "department": "Food Service",
          "count": 10,
          "start_time": "11:00",
          "end_time": "15:00",
          "hours": 4,
          "uniform": "White shirt, black pants",
          "break_minutes": 30,
          "cost_per_hour": 25,
          "total_value": 1000,
          "vendor_name": "Elite Staffing Solutions",
          "vendor_id": "vnd_1122334455"
        },
        {
          "role": "Cook",
          "department": "Kitchen",
          "count": 5,
          "start_time": "10:00",
          "end_time": "16:00",
          "hours": 6,
          "uniform": "Chef whites",
          "break_minutes": 30,
          "cost_per_hour": 30,
          "total_value": 900,
          "vendor_name": "Elite Staffing Solutions",
          "vendor_id": "vnd_1122334455"
        }
      ]
    }
  ],
  "addons": {
    "goal": {
      "enabled": true,
      "text": "Maintain 95% customer satisfaction"
    },
    "portal_access": true,
    "meal_provided": true,
    "travel_time": false,
    "tips": {
      "enabled": true,
      "amount": "pooled"
    }
  },
  "total": 1900,
  "requested": 15,
  "assigned_staff": [
    {
      "staff_id": "stf_111",
      "staff_name": "Maria Garcia",
      "role": "Server",
      "confirmed": true
    },
    {
      "staff_id": "stf_222",
      "staff_name": "John Smith",
      "role": "Cook",
      "confirmed": true
    }
  ],
  "client_name": "Sarah Johnson",
  "client_email": "sarah.johnson@google.com",
  "client_phone": "(650) 555-0123",
  "notes": "Ensure all staff arrive 15 minutes early",
  "created_date": "2025-01-01T10:00:00Z",
  "updated_date": "2025-01-10T14:30:00Z",
  "created_by": "admin@krow.com"
}
```

### Complete Staff Object Example
```json
{
  "id": "stf_9876543210",
  "employee_name": "Maria Garcia",
  "vendor_id": "vnd_1122334455",
  "vendor_name": "Elite Staffing Solutions",
  "manager": "Fernando Lopez",
  "contact_number": "(415) 555-0199",
  "phone": "(415) 555-0200",
  "email": "maria.garcia@email.com",
  "department": "Operations",
  "hub_location": "San Francisco Bay Area",
  "event_location": "Various",
  "address": "123 Main St, Apt 4B",
  "city": "San Francisco",
  "position": "Server",
  "position_2": "Bartender",
  "initial": "MG",
  "profile_type": "Skilled",
  "employment_type": "Part Time",
  "english": "Fluent",
  "english_required": true,
  "check_in": "2025-01-15",
  "rating": 4.8,
  "shift_coverage_percentage": 95,
  "cancellation_count": 2,
  "no_show_count": 0,
  "total_shifts": 47,
  "reliability_score": 96,
  "background_check_status": "cleared",
  "background_check_date": "2024-06-15",
  "certifications": [
    {
      "name": "Food Handler Certificate",
      "issued_date": "2024-06-01",
      "expiry_date": "2026-06-01",
      "issuer": "ServSafe"
    },
    {
      "name": "Alcohol Service Permit",
      "issued_date": "2024-07-01",
      "expiry_date": "2025-07-01",
      "issuer": "CA ABC"
    }
  ],
  "notes": "Excellent customer service skills. Prefers weekend shifts.",
  "created_date": "2024-01-10T09:00:00Z",
  "updated_date": "2025-01-15T16:45:00Z",
  "created_by": "vendor@elitestaffing.com"
}
```

### Complete Vendor Object Example
```json
{
  "id": "vnd_1122334455",
  "vendor_number": "VN-0042",
  "legal_name": "Elite Staffing Solutions Inc.",
  "doing_business_as": "Elite Staffing",
  "region": "Bay Area",
  "state": "California",
  "city": "San Francisco",
  "service_specialty": "Event Staffing & Hospitality Services",
  "workforce_count": 250,
  "platform_type": "Full Platform",
  "tax_id": "12-3456789",
  "business_type": "Corporation",
  "primary_contact_name": "Robert Chen",
  "primary_contact_email": "robert.chen@elitestaffing.com",
  "primary_contact_phone": "(415) 555-0100",
  "billing_address": "456 Business Plaza, Suite 200, San Francisco, CA 94102",
  "service_address": "456 Business Plaza, Suite 200, San Francisco, CA 94102",
  "coverage_regions": [
    "San Francisco",
    "Oakland",
    "San Jose",
    "Peninsula",
    "East Bay"
  ],
  "eligible_roles": [
    "Server",
    "Bartender",
    "Cook",
    "Dishwasher",
    "Event Manager",
    "Catering Staff"
  ],
  "insurance_certificate": "https://storage.example.com/certs/elite-insurance.pdf",
  "insurance_expiry": "2025-12-31",
  "w9_document": "https://storage.example.com/docs/elite-w9.pdf",
  "coi_document": "https://storage.example.com/docs/elite-coi.pdf",
  "approval_status": "approved",
  "approved_date": "2024-01-15",
  "approved_by": "admin@krow.com",
  "is_active": true,
  "notes": "Preferred vendor for tech company events. Excellent track record.",
  "created_date": "2024-01-10T10:00:00Z",
  "updated_date": "2025-01-05T11:20:00Z"
}
```

---

## Code Examples

### Example 1: Create Event with Staff Assignment
```javascript
import { base44 } from "@/api/base44Client";

async function createEventAndAssignStaff() {
  // Get current user
  const user = await base44.auth.me();
  
  // Create new event
  const event = await base44.entities.Event.create({
    event_name: "Corporate Holiday Party",
    business_name: "Acme Corporation",
    date: "2025-12-20",
    hub: "Downtown Office",
    status: "Draft",
    requested: 20,
    shifts: [
      {
        shift_name: "Evening Service",
        location_address: "123 Corporate Plaza",
        roles: [
          {
            role: "Server",
            department: "Food Service",
            count: 15,
            start_time: "18:00",
            end_time: "23:00",
            hours: 5,
            cost_per_hour: 28,
            total_value: 2100
          },
          {
            role: "Bartender",
            department: "Bar Service",
            count: 5,
            start_time: "17:30",
            end_time: "23:30",
            hours: 6,
            cost_per_hour: 32,
            total_value: 960
          }
        ]
      }
    ],
    total: 3060,
    client_name: user.full_name,
    client_email: user.email
  });
  
  // Find available staff
  const availableStaff = await base44.entities.Staff.filter({
    position: "Server",
    rating: { $gte: 4.5 },
    employment_type: { $in: ["Part Time", "Full Time"] }
  }, '-rating', 15);
  
  // Assign staff to event
  const assignedStaff = availableStaff.map(staff => ({
    staff_id: staff.id,
    staff_name: staff.employee_name,
    role: "Server",
    confirmed: false
  }));
  
  await base44.entities.Event.update(event.id, {
    assigned_staff: assignedStaff,
    status: "Pending"
  });
  
  // Create activity log
  await base44.entities.ActivityLog.create({
    title: "Event Created",
    description: `New event "${event.event_name}" created and staff assigned`,
    activity_type: "event_created",
    related_entity_type: "event",
    related_entity_id: event.id,
    user_id: user.id,
    is_read: false,
    icon_type: "calendar",
    icon_color: "blue"
  });
  
  return event;
}
```

### Example 2: Send Invoice Reminder Emails
```javascript
import { base44 } from "@/api/base44Client";

async function sendInvoiceReminders() {
  // Get overdue invoices
  const today = new Date();
  const overdueInvoices = await base44.entities.Invoice.filter({
    status: { $in: ["Open", "Overdue"] },
    due_date: { $lt: today.toISOString().split('T')[0] }
  });
  
  // Send reminder for each
  for (const invoice of overdueInvoices) {
    // Update status
    await base44.entities.Invoice.update(invoice.id, {
      status: "Overdue"
    });
    
    // Get business contact
    const business = await base44.entities.Business.filter({
      business_name: invoice.business_name
    });
    
    if (business.length > 0) {
      const contact = business[0];
      
      // Send email
      await base44.integrations.Core.SendEmail({
        to: contact.email,
        subject: `Payment Reminder: Invoice ${invoice.invoice_number}`,
        body: `
          <h2>Payment Reminder</h2>
          <p>Dear ${contact.contact_name},</p>
          <p>This is a friendly reminder that invoice <strong>${invoice.invoice_number}</strong> 
          for <strong>$${invoice.amount.toLocaleString()}</strong> is now overdue.</p>
          <p><strong>Due Date:</strong> ${invoice.due_date}</p>
          <p><strong>Amount:</strong> $${invoice.amount.toLocaleString()}</p>
          <p>Please process payment at your earliest convenience.</p>
          <p>Thank you,<br>KROW Workforce Team</p>
        `,
        from_name: "KROW Accounts Receivable"
      });
      
      // Log activity
      await base44.entities.ActivityLog.create({
        title: "Invoice Reminder Sent",
        description: `Reminder sent for invoice ${invoice.invoice_number}`,
        activity_type: "invoice_created",
        related_entity_type: "invoice",
        related_entity_id: invoice.id,
        user_id: contact.id || "system",
        icon_type: "invoice",
        icon_color: "yellow"
      });
    }
  }
  
  return overdueInvoices.length;
}
```

### Example 3: AI-Powered Staff Recommendation
```javascript
import { base44 } from "@/api/base44Client";

async function getStaffRecommendations(eventId) {
  // Get event details
  const events = await base44.entities.Event.filter({ id: eventId });
  const event = events[0];
  
  // Get all available staff
  const allStaff = await base44.entities.Staff.list();
  
  // Use AI to analyze and recommend
  const recommendations = await base44.integrations.Core.InvokeLLM({
    prompt: `
      Analyze this event and recommend the best staff members.
      
      Event Details:
      - Name: ${event.event_name}
      - Date: ${event.date}
      - Location: ${event.hub}
      - Roles Needed: ${JSON.stringify(event.shifts)}
      
      Available Staff:
      ${JSON.stringify(allStaff.map(s => ({
        id: s.id,
        name: s.employee_name,
        position: s.position,
        rating: s.rating,
        reliability: s.reliability_score,
        experience: s.total_shifts
      })))}
      
      Recommend the top staff for each role based on:
      1. Position match
      2. Rating and reliability
      3. Experience level
      4. Availability patterns
      
      Provide reasoning for each recommendation.
    `,
    response_json_schema: {
      type: "object",
      properties: {
        recommendations: {
          type: "array",
          items: {
            type: "object",
            properties: {
              staff_id: { type: "string" },
              staff_name: { type: "string" },
              role: { type: "string" },
              score: { type: "number" },
              reasoning: { type: "string" }
            }
          }
        },
        overall_analysis: { type: "string" }
      }
    }
  });
  
  return recommendations;
}
```

### Example 4: Bulk Import Staff from CSV
```javascript
import { base44 } from "@/api/base44Client";

async function importStaffFromCSV(file) {
  // Upload file
  const { file_url } = await base44.integrations.Core.UploadFile({
    file: file
  });
  
  // Extract data
  const result = await base44.integrations.Core.ExtractDataFromUploadedFile({
    file_url: file_url,
    json_schema: {
      type: "array",
      items: {
        type: "object",
        properties: {
          employee_name: { type: "string" },
          email: { type: "string" },
          phone: { type: "string" },
          position: { type: "string" },
          department: { type: "string" },
          employment_type: { type: "string" },
          vendor_name: { type: "string" }
        },
        required: ["employee_name"]
      }
    }
  });
  
  if (result.status === "error") {
    throw new Error(result.details);
  }
  
  // Bulk create staff
  const createdStaff = await base44.entities.Staff.bulkCreate(
    result.output.map(staff => ({
      ...staff,
      rating: 0,
      reliability_score: 0,
      total_shifts: 0,
      background_check_status: "pending"
    }))
  );
  
  // Create activity logs
  await base44.entities.ActivityLog.create({
    title: "Bulk Staff Import",
    description: `${createdStaff.length} staff members imported from CSV`,
    activity_type: "staff_assigned",
    user_id: (await base44.auth.me()).id,
    icon_type: "user",
    icon_color: "green"
  });
  
  return createdStaff;
}
```

### Example 5: Generate Performance Report
```javascript
import { base44 } from "@/api/base44Client";

async function generateVendorPerformanceReport(vendorId) {
  // Get vendor details
  const vendors = await base44.entities.Vendor.filter({ id: vendorId });
  const vendor = vendors[0];
  
  // Get vendor's staff
  const staff = await base44.entities.Staff.filter({
    vendor_id: vendorId
  });
  
  // Get vendor's events
  const events = await base44.entities.Event.filter({
    vendor_id: vendorId,
    status: "Completed"
  });
  
  // Calculate metrics
  const totalStaff = staff.length;
  const avgRating = staff.reduce((sum, s) => sum + (s.rating || 0), 0) / totalStaff;
  const avgReliability = staff.reduce((sum, s) => sum + (s.reliability_score || 0), 0) / totalStaff;
  const totalEvents = events.length;
  const totalRevenue = events.reduce((sum, e) => sum + (e.total || 0), 0);
  
  // Use AI to generate insights
  const report = await base44.integrations.Core.InvokeLLM({
    prompt: `
      Generate a comprehensive performance report for this vendor:
      
      Vendor: ${vendor.legal_name}
      Workforce Size: ${totalStaff}
      Average Staff Rating: ${avgRating.toFixed(2)}/5.0
      Average Reliability: ${avgReliability.toFixed(1)}%
      Events Completed: ${totalEvents}
      Total Revenue: $${totalRevenue.toLocaleString()}
      
      Staff Performance Distribution:
      ${JSON.stringify(staff.map(s => ({
        name: s.employee_name,
        rating: s.rating,
        reliability: s.reliability_score,
        shifts: s.total_shifts
      })))}
      
      Provide:
      1. Overall performance summary
      2. Key strengths
      3. Areas for improvement
      4. Specific recommendations
      5. Comparison to industry benchmarks
    `,
    response_json_schema: {
      type: "object",
      properties: {
        summary: { type: "string" },
        grade: { type: "string" },
        strengths: {
          type: "array",
          items: { type: "string" }
        },
        improvements: {
          type: "array",
          items: { type: "string" }
        },
        recommendations: {
          type: "array",
          items: { type: "string" }
        },
        benchmark_comparison: { type: "string" }
      }
    }
  });
  
  return {
    vendor,
    metrics: {
      totalStaff,
      avgRating,
      avgReliability,
      totalEvents,
      totalRevenue
    },
    analysis: report
  };
}
```

---

## Best Practices

### 1. Error Handling
```javascript
try {
  const event = await base44.entities.Event.create(eventData);
  // Success handling
} catch (error) {
  console.error("Failed to create event:", error);
  // Show user-friendly error message
  toast({
    title: "❌ Error",
    description: "Failed to create event. Please try again.",
    variant: "destructive"
  });
}
```

### 2. Query Optimization
```javascript
// ❌ Bad: Fetch all then filter in memory
const allEvents = await base44.entities.Event.list();
const vendorEvents = allEvents.filter(e => e.vendor_id === vendorId);

// ✅ Good: Filter at database level
const vendorEvents = await base44.entities.Event.filter({
  vendor_id: vendorId
});
```

### 3. Pagination
```javascript
// Fetch in batches
const pageSize = 50;
let page = 0;
let allRecords = [];

while (true) {
  const batch = await base44.entities.Event.list(
    '-created_date',
    pageSize,
    page * pageSize
  );
  
  if (batch.length === 0) break;
  
  allRecords = [...allRecords, ...batch];
  page++;
}
```

### 4. Caching with React Query
```javascript
import { useQuery } from "@tanstack/react-query";

function useEvents() {
  return useQuery({
    queryKey: ['events'],
    queryFn: () => base44.entities.Event.list('-date'),
    initialData: [],
    staleTime: 5 * 60 * 1000,  // 5 minutes
    cacheTime: 10 * 60 * 1000  // 10 minutes
  });
}
```

### 5. Batch Operations
```javascript
// ❌ Bad: Multiple sequential creates
for (const staff of staffList) {
  await base44.entities.Staff.create(staff);
}

// ✅ Good: Single bulk create
await base44.entities.Staff.bulkCreate(staffList);
```

---

## Security Considerations

### 1. User Entity Access Control
- Only admin users can access other users' data
- Regular users can only view/update their own records
- Built-in security rules are automatically enforced

### 2. Private Files
- Use `UploadPrivateFile` for sensitive documents
- Always use signed URLs with appropriate expiration
- Never expose private file URIs directly

### 3. Email Validation
- Always validate email formats before sending
- Use proper HTML escaping in email bodies
- Consider rate limiting for bulk emails

### 4. Data Validation
- Validate all input data before entity operations
- Use enum constraints where applicable
- Implement client-side validation before API calls

---

## Rate Limits & Quotas

### Standard Limits
- Entity Operations: 1000 requests/minute
- LLM Invocations: 100 requests/minute
- File Uploads: 100 MB per file
- Email Sending: 1000 emails/day

### Best Practices for Limits
- Implement exponential backoff for retries
- Cache frequently accessed data
- Use bulk operations when possible
- Monitor usage via activity logs

---

## Changelog

### Version 2.0 (2025-01-11)
- Complete entity schema documentation
- Added 17 entity schemas with full field specifications
- Comprehensive SDK operation examples
- Core integration specifications
- Advanced code examples
- Best practices and security guidelines

### Version 1.0 (2024-12-01)
- Initial API documentation
- Basic entity schemas
- Core integration endpoints

---

## Support & Resources

- **Documentation**
  - Platform Docs: `https://docs.base44.com`
  - API Reference: `https://api.base44.com/docs`
  - Community Forum: `https://community.base44.com`
- **Contact**
  - Technical Support: `support@krow.com`
  - Sales Inquiries: `sales@krow.com`
  - General Questions: `info@krow.com`

© 2025 KROW Workforce. All rights reserved.