554dc9f9e3
This commit establishes the new monorepo architecture for the KROW Workforce platform. Key changes include: - Reorganized project into `frontend-web`, `mobile-apps`, `firebase`, `scripts`, and `secrets` directories. - Updated `Makefile` to support the new monorepo layout and automate Base44 export integration. - Fixed `scripts/prepare-export.js` for ES module compatibility and global component import resolution. - Created and updated `CONTRIBUTING.md` for developer onboarding. - Restructured, renamed, and translated all `docs/` files for clarity and consistency. - Implemented an interactive internal launchpad with diagram viewing capabilities. - Configured base Firebase project files (`firebase.json`, security rules). - Updated `README.md` to reflect the new project structure and documentation overview.
1732 lines
80 KiB
Markdown
1732 lines
80 KiB
Markdown
# 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. |