feat: add documentation for GCP migration and Base44 API export
This commit adds two new documentation files: - `docs/03-backend-api-specification-v3.md`: This document defines the backend API to be built on the Firebase/GCP ecosystem, replacing the Base44 backend. It is based on the comprehensive Base44 API documentation (v3.0) and will guide the development of the new backend using Firebase Data Connect and Cloud Functions. - `docs/07-reference-base44-api-export-v3.md`: This document provides complete API specifications for all entities, SDK methods, and integration endpoints of the KROW Workforce platform built on Base44.
This commit is contained in:
bwnyasse
3
.gitignore
vendored
3
.gitignore
vendored
@@ -39,6 +39,9 @@ frontend-web/.vite/
|
||||
|
||||
# Mobile (Flutter)
|
||||
# ----------------------------------------------------------------
|
||||
# Android
|
||||
.gradle/
|
||||
|
||||
mobile-apps/*/.dart_tool/
|
||||
mobile-apps/*/.pub-cache/
|
||||
mobile-apps/*/build/
|
||||
|
||||
1420
docs/03-backend-api-specification-v3.md
Normal file
1420
docs/03-backend-api-specification-v3.md
Normal file
File diff suppressed because it is too large
Load Diff
705
docs/07-reference-base44-api-export-v3.md
Normal file
705
docs/07-reference-base44-api-export-v3.md
Normal file
@@ -0,0 +1,705 @@
|
||||
# KROW Workforce Platform - API Documentation
|
||||
|
||||
**Version:** 3.0 (Auto-Updated)
|
||||
**Last Updated:** 2025-11-20
|
||||
**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)
|
||||
|
||||
---
|
||||
|
||||
## 1. 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";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 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",
|
||||
"created_date": "timestamp",
|
||||
"updated_date": "timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 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 |
|
||||
|
||||
**Security Rules:**
|
||||
* Only admin users can list, update, or delete other users.
|
||||
* Regular users can only view and update their own user record.
|
||||
|
||||
### 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_rapid` | boolean | RAPID/urgent order flag | Default: false |
|
||||
| `is_recurring` | boolean | Whether event recurs | Default: false |
|
||||
| `is_multi_day` | boolean | Multi-day event flag | 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 |
|
||||
| `multi_day_start_date` | date | Multi-day start date | Optional |
|
||||
| `multi_day_end_date` | date | Multi-day end date | Optional |
|
||||
| `buffer_time_before` | number | Buffer time before (minutes) | Default: 0 |
|
||||
| `buffer_time_after` | number | Buffer time after (minutes) | Default: 0 |
|
||||
| `conflict_detection_enabled`| boolean | Enable conflict detection | Default: true |
|
||||
| `detected_conflicts` | array | Array of detected conflicts | Array of conflict objects |
|
||||
| `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 |
|
||||
| `event_location` | string | Event location address | 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 |
|
||||
| `invoice_id` | string | Associated invoice ID | Optional |
|
||||
| `notes` | string | Additional notes | Optional |
|
||||
| `requested` | number | Total staff requested | Default: 0 |
|
||||
| `assigned_staff` | array | Array of assigned staff | Optional |
|
||||
|
||||
**Detected Conflicts Structure:**
|
||||
```json
|
||||
{
|
||||
"conflict_type": "staff_overlap" | "venue_overlap" | "time_buffer",
|
||||
"severity": "low" | "medium" | "high" | "critical",
|
||||
"description": "string",
|
||||
"conflicting_event_id": "string",
|
||||
"staff_id": "string",
|
||||
"detected_at": "timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
### 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 |
|
||||
| `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 |
|
||||
| `track` | string | Track information | Optional |
|
||||
| `position` | string | Primary 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" |
|
||||
| `rating` | number | Staff performance rating (0-5 stars) | Min: 0, Max: 5 |
|
||||
| `reliability_score` | number | Overall reliability score (0-100) | Min: 0, Max: 100 |
|
||||
| `background_check_status`| string | Background check status | Enum: "pending", "cleared", "failed", "expired", "not_required" |
|
||||
|
||||
### 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 |
|
||||
| `region` | string | Geographic region | Enum: "National", "Bay Area", "Southern California", "Northern California", "West", "East", "Midwest", "South" |
|
||||
| `platform_type` | string | Technology integration level | Enum: "Full Platform", "Building platform (KROW)", "Partial Tech", "Traditional" |
|
||||
| `primary_contact_email` | string | Primary email | Required, Email format |
|
||||
| `approval_status` | string | Vendor approval status | Enum: "pending", "approved", "suspended", "terminated" |
|
||||
| `is_active` | boolean | Is vendor currently active | Default: true |
|
||||
|
||||
### 5. VendorRate Entity
|
||||
**Description:** Vendor pricing and rate management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique rate identifier | Auto-generated |
|
||||
| `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 |
|
||||
|
||||
### 6. VendorDefaultSettings Entity
|
||||
**Description:** Default markup and fee settings for vendors.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique settings identifier | Auto-generated |
|
||||
| `vendor_name` | string | Name of the vendor | Required |
|
||||
| `default_markup_percentage`| number | Default markup percentage | Required, Min: 0, Max: 100 |
|
||||
| `default_vendor_fee_percentage`| number | Default vendor fee percentage | Required, Min: 0, Max: 100 |
|
||||
|
||||
### 7. 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 |
|
||||
| `amount` | number | Grand total invoice amount | Required, Min: 0 |
|
||||
| `status` | string | Current invoice status | Enum: "Draft", "Pending Review", "Approved", "Disputed", "Under Review", "Resolved", "Overdue", "Paid", "Reconciled", "Cancelled" |
|
||||
| `issue_date` | date | Invoice issue date | Required |
|
||||
| `due_date` | date | Payment due date | Required |
|
||||
| `disputed_items` | array | List of disputed staff entry indices | Optional |
|
||||
| `is_auto_generated` | boolean | Whether invoice was auto-generated | Default: false |
|
||||
|
||||
### 8. 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 |
|
||||
| `contact_name` | string | Primary contact person | Required |
|
||||
| `email` | string | Business email | Email format |
|
||||
| `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" |
|
||||
|
||||
### 9. Certification Entity
|
||||
**Description:** Employee certification and compliance tracking.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique certification ID | Auto-generated |
|
||||
| `employee_name` | string | Staff member name | Required |
|
||||
| `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" |
|
||||
| `expiry_date` | date | Expiration date | Required |
|
||||
| `validation_status` | string | Validation status | Enum: "approved", "pending_expert_review", "rejected", "ai_verified", "ai_flagged", "manual_review_needed" |
|
||||
|
||||
### 10. Team Entity
|
||||
**Description:** Team and organization management with role-based isolation.
|
||||
|
||||
| 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" |
|
||||
| `favorite_staff` | array | Array of favorite staff | Array of objects |
|
||||
| `blocked_staff` | array | Array of blocked staff | Array of objects |
|
||||
|
||||
### 11. TeamMember Entity
|
||||
**Description:** Team member management within teams.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique member identifier | Auto-generated |
|
||||
| `team_id` | string | ID of the team this member belongs to | Required |
|
||||
| `member_name` | string | Name of the team member | Required |
|
||||
| `email` | string | Member email | Required, Email format |
|
||||
| `role` | string | Role in the team | Enum: "admin", "manager", "member", "viewer" |
|
||||
| `is_active` | boolean | Whether the member is active | Default: true |
|
||||
|
||||
### 12. TeamHub Entity
|
||||
**Description:** Team hub/location management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique hub identifier | Auto-generated |
|
||||
| `team_id` | string | ID of the team | Required |
|
||||
| `hub_name` | string | Name of the hub/location | Required |
|
||||
| `departments` | array | Departments within this hub | Array of objects with `department_name`, `cost_center` |
|
||||
|
||||
### 13. TeamMemberInvite Entity
|
||||
**Description:** Team member invitation management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique invite identifier | Auto-generated |
|
||||
| `team_id` | string | Team ID | Required |
|
||||
| `invite_code` | string | Unique invite code | Required |
|
||||
| `email` | string | Invitee email | Required, Email format |
|
||||
| `invite_status` | string | Invite status | Enum: "pending", "accepted", "expired", "cancelled" |
|
||||
|
||||
### 14. Conversation Entity
|
||||
**Description:** Messaging and communication management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique conversation ID | Auto-generated |
|
||||
| `participants` | array | Array of participant IDs/emails | Required |
|
||||
| `conversation_type` | string | Type of conversation | Required, Enum: "client-vendor", "staff-client", "staff-admin", "vendor-admin", "client-admin", "group-staff", "group-event-staff" |
|
||||
| `related_to` | string | ID of related entity | Optional |
|
||||
| `status` | string | Conversation status | Enum: "active", "archived", "closed" |
|
||||
|
||||
### 15. Message Entity
|
||||
**Description:** Individual messages within conversations.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique message identifier | Auto-generated |
|
||||
| `conversation_id` | string | ID of the conversation | Required |
|
||||
| `sender_name` | string | Name of the sender | Required |
|
||||
| `content` | string | Message content | Required |
|
||||
| `read_by` | array | Array of user IDs who have read the message | Array of strings |
|
||||
|
||||
### 16. 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", "staff_assigned", "invoice_paid", etc. |
|
||||
| `user_id` | string | ID of the user this notification is for | Required |
|
||||
| `is_read` | boolean | Whether the notification has been read | Default: false |
|
||||
|
||||
### 17. Enterprise Entity
|
||||
**Description:** Enterprise organization management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique enterprise ID | Auto-generated |
|
||||
| `enterprise_number`| string | Enterprise Number format EN-#### | Required, Pattern: `^EN-[0-9]{4}$` |
|
||||
| `enterprise_name` | string | Enterprise name (e.g., Compass) | Required |
|
||||
| `enterprise_code` | string | Short code identifier | Required |
|
||||
|
||||
### 18. Sector Entity
|
||||
**Description:** Sector/branch management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique sector identifier | Auto-generated |
|
||||
| `sector_number` | string | Sector Number format SN-#### | Required, Pattern: `^SN-[0-9]{4}$` |
|
||||
| `sector_name` | string | Sector/brand name (e.g., Bon Appétit) | Required |
|
||||
| `sector_type` | string | Sector business type | Enum: "Food Service", "Facilities", "Healthcare", "Education", "Corporate", "Sports & Entertainment" |
|
||||
|
||||
### 19. 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 format PN-#### | Required, Pattern: `^PN-[0-9]{4}$` |
|
||||
| `partner_type` | string | Partner type | Enum: "Corporate", "Education", "Healthcare", "Sports & Entertainment", "Government" |
|
||||
|
||||
### 20. Order Entity
|
||||
**Description:** Order management system.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique order identifier | Auto-generated |
|
||||
| `order_number` | string | Order Number format ORD-#### | Required, Pattern: `^ORD-[0-9]{4,6}$` |
|
||||
| `partner_id` | string | Partner/Client ID | Required |
|
||||
| `order_type` | string | Type of order | Enum: "Standard", "Last Minute", "Emergency", "Recurring" |
|
||||
| `order_status` | string | Order status | Enum: "Draft", "Submitted", "Confirmed", "In Progress", "Completed", "Cancelled" |
|
||||
|
||||
### 21. Shift Entity
|
||||
**Description:** Shift scheduling and management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique shift identifier | Auto-generated |
|
||||
| `shift_name` | string | Name of the shift | Required |
|
||||
| `start_date` | timestamp | Shift start date/time | Required |
|
||||
| `end_date` | timestamp | Shift end date/time | Optional |
|
||||
| `assigned_staff` | array | List of assigned staff | Array of objects |
|
||||
|
||||
### 22. Assignment Entity
|
||||
**Description:** Worker assignment and tracking.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique assignment identifier | Auto-generated |
|
||||
| `assignment_number` | string | Assignment Number format ASN-#### | Pattern: `^ASN-[0-9]{4,6}$` |
|
||||
| `order_id` | string | Associated order ID | Required |
|
||||
| `workforce_id` | string | Assigned worker ID | Required |
|
||||
| `vendor_id` | string | Vendor providing the worker | Required |
|
||||
| `role` | string | Role assigned | Required |
|
||||
| `assignment_status` | string | Assignment status | Enum: "Pending", "Confirmed", "Checked In", "In Progress", "Completed", "Cancelled", "No Show" |
|
||||
| `scheduled_start` | timestamp | Scheduled start time | Required |
|
||||
|
||||
### 23. Workforce Entity
|
||||
**Description:** Worker/contractor management.
|
||||
|
||||
| Field Name | Type | Description | Validation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | string | Unique workforce identifier | Auto-generated |
|
||||
| `workforce_number` | string | Worker Number format WF-#### | Required, Pattern: `^WF-[0-9]{4,6}$` |
|
||||
| `vendor_id` | string | Vendor who manages this worker | Required |
|
||||
| `first_name` | string | Worker first name | Required |
|
||||
| `last_name` | string | Worker last name | Required |
|
||||
| `employment_type` | string | Employment classification | Enum: "W2", "1099", "Temporary", "Contract" |
|
||||
|
||||
---
|
||||
|
||||
## 4. SDK Operations
|
||||
|
||||
All entities support the following base operations. Replace `EntityName` with the specific entity (e.g., `Event`, `Staff`, `Invoice`).
|
||||
|
||||
### List & Filter
|
||||
```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');
|
||||
|
||||
// Filter with multiple conditions
|
||||
const records = await base44.entities.EntityName.filter({
|
||||
status: 'Active',
|
||||
created_by: user.email
|
||||
});
|
||||
|
||||
// Filter with operators ($gte, $lte, $in, $contains)
|
||||
const records = await base44.entities.EntityName.filter({
|
||||
rating: { $gte: 4.5 },
|
||||
total: { $lte: 1000 }
|
||||
});
|
||||
```
|
||||
|
||||
### CRUD Operations
|
||||
```javascript
|
||||
// Create
|
||||
const newRecord = await base44.entities.EntityName.create({
|
||||
field1: 'value1',
|
||||
field2: 'value2'
|
||||
});
|
||||
|
||||
// Bulk Create
|
||||
const newRecords = await base44.entities.EntityName.bulkCreate([
|
||||
{ field1: 'value1' },
|
||||
{ field1: 'value2' }
|
||||
]);
|
||||
|
||||
// Update
|
||||
const updatedRecord = await base44.entities.EntityName.update(recordId, {
|
||||
field1: 'new value'
|
||||
});
|
||||
|
||||
// Delete
|
||||
await base44.entities.EntityName.delete(recordId);
|
||||
|
||||
// Get Schema
|
||||
const schema = await base44.entities.EntityName.schema();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Core Integrations
|
||||
|
||||
### InvokeLLM
|
||||
Generates a response from an LLM with a prompt.
|
||||
|
||||
| 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 |
|
||||
| `response_json_schema` | object | No | JSON schema for structured output |
|
||||
| `file_urls` | string[] | No | Array of file URLs for context |
|
||||
|
||||
```javascript
|
||||
const data = await base44.integrations.Core.InvokeLLM({
|
||||
prompt: "Give me data on Apple",
|
||||
add_context_from_internet: true,
|
||||
response_json_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
stock_price: { type: "number" },
|
||||
ceo: { type: "string" }
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### SendEmail
|
||||
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 |
|
||||
|
||||
### File Operations
|
||||
|
||||
* **UploadFile:** Upload a file to public storage.
|
||||
* **UploadPrivateFile:** Upload a file to private storage (requires signed URL).
|
||||
* **CreateFileSignedUrl:** Create a temporary signed URL for accessing a private file.
|
||||
|
||||
```javascript
|
||||
// Upload private document
|
||||
const { file_uri } = await base44.integrations.Core.UploadPrivateFile({
|
||||
file: sensitiveDocument
|
||||
});
|
||||
|
||||
// Create signed URL
|
||||
const { signed_url } = await base44.integrations.Core.CreateFileSignedUrl({
|
||||
file_uri: file_uri,
|
||||
expires_in: 3600
|
||||
});
|
||||
```
|
||||
|
||||
### ExtractDataFromUploadedFile
|
||||
Extract structured data from uploaded files (CSV, PDF, images).
|
||||
|
||||
```javascript
|
||||
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" }
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Data Models Reference
|
||||
|
||||
### Complete Event Object Example
|
||||
```json
|
||||
{
|
||||
"id": "evt_1234567890",
|
||||
"event_name": "Google Campus Lunch Service",
|
||||
"is_recurring": true,
|
||||
"status": "Active",
|
||||
"date": "2025-01-15",
|
||||
"shifts": [
|
||||
{
|
||||
"shift_name": "Lunch Shift",
|
||||
"roles": [
|
||||
{
|
||||
"role": "Server",
|
||||
"count": 10,
|
||||
"hours": 4,
|
||||
"cost_per_hour": 25,
|
||||
"total_value": 1000
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"assigned_staff": [
|
||||
{
|
||||
"staff_id": "stf_111",
|
||||
"staff_name": "Maria Garcia",
|
||||
"confirmed": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Code Examples
|
||||
|
||||
### Example: Create Event with Staff Assignment
|
||||
```javascript
|
||||
import { base44 } from "@/api/base44Client";
|
||||
|
||||
async function createEventAndAssignStaff() {
|
||||
const user = await base44.auth.me();
|
||||
|
||||
// 1. Create Event
|
||||
const event = await base44.entities.Event.create({
|
||||
event_name: "Corporate Holiday Party",
|
||||
date: "2025-12-20",
|
||||
status: "Draft",
|
||||
requested: 20,
|
||||
shifts: [{
|
||||
shift_name: "Evening Service",
|
||||
roles: [{ role: "Server", count: 15, cost_per_hour: 28 }]
|
||||
}],
|
||||
client_email: user.email
|
||||
});
|
||||
|
||||
// 2. Find Staff
|
||||
const availableStaff = await base44.entities.Staff.filter({
|
||||
position: "Server",
|
||||
rating: { $gte: 4.5 }
|
||||
}, '-rating', 15);
|
||||
|
||||
// 3. Assign Staff
|
||||
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"
|
||||
});
|
||||
|
||||
return event;
|
||||
}
|
||||
```
|
||||
|
||||
### Example: AI-Powered Staff Recommendation
|
||||
```javascript
|
||||
import { base44 } from "@/api/base44Client";
|
||||
|
||||
async function getStaffRecommendations(eventId) {
|
||||
const events = await base44.entities.Event.filter({ id: eventId });
|
||||
const event = events[0];
|
||||
const allStaff = await base44.entities.Staff.list();
|
||||
|
||||
const recommendations = await base44.integrations.Core.InvokeLLM({
|
||||
prompt: `Analyze this event (${event.event_name}) and recommend staff based on rating and reliability.`,
|
||||
response_json_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
recommendations: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
staff_id: { type: "string" },
|
||||
score: { type: "number" },
|
||||
reasoning: { type: "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
return recommendations;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Best Practices
|
||||
|
||||
1. **Error Handling:** Always wrap calls in `try/catch` blocks and provide user-friendly error messages.
|
||||
2. **Query Optimization:** Filter data at the database level (using `.filter()`) rather than fetching all records and filtering in memory.
|
||||
3. **Pagination:** Use the `limit` and `offset` parameters in `.list()` for large datasets to improve performance.
|
||||
4. **Caching:** Use libraries like React Query to cache SDK responses and reduce API calls.
|
||||
5. **Batch Operations:** Prefer `bulkCreate` over looping through single create calls.
|
||||
6. **Team Isolation:** Rely on the built-in `owner_id` filtering. Do not attempt to bypass cross-layer visibility rules (e.g., Vendors should not see Procurement teams).
|
||||
|
||||
---
|
||||
|
||||
## 9. Security Considerations
|
||||
|
||||
* **User Entity Access Control:** Built-in rules enforce that only admins can modify other users. Regular users are restricted to their own records.
|
||||
* **Team Isolation:** Complete data isolation across organizational layers (Vendor, Procurement, Operator, Client) is enforced via `owner_id`.
|
||||
* **Private Files:** Always use `UploadPrivateFile` for sensitive documents (W9, Insurance, etc.) and generate temporary signed URLs for access.
|
||||
* **Input Validation:** While the API performs validation, always validate email formats and required fields on the client side before making requests.
|
||||
|
||||
---
|
||||
|
||||
## 10. Rate Limits & Quotas
|
||||
|
||||
| Operation | Limit |
|
||||
| :--- | :--- |
|
||||
| **Entity Operations** | 1000 requests/minute |
|
||||
| **LLM Invocations** | 100 requests/minute |
|
||||
| **File Uploads** | 100 MB per file |
|
||||
| **Email Sending** | 1000 emails/day |
|
||||
|
||||
*Tip: Implement exponential backoff for retries if you hit these limits.*
|
||||
|
||||
---
|
||||
|
||||
## 11. Changelog
|
||||
|
||||
**Version 3.0 (2025-11-20)**
|
||||
* Added Team, TeamMember, TeamHub, TeamMemberInvite entities.
|
||||
* Added Assignment and Workforce entities.
|
||||
* Enhanced Invoice entity with dispute tracking.
|
||||
* Updated Event entity (Conflict detection, Multi-day).
|
||||
|
||||
**Version 2.0 (2025-01-11)**
|
||||
* Complete entity schema documentation.
|
||||
* Core integration specifications.
|
||||
|
||||
---
|
||||
|
||||
## 12. Support & Resources
|
||||
|
||||
* **Platform Docs:** [https://docs.base44.com](https://docs.base44.com)
|
||||
* **API Reference:** [https://api.base44.com/docs](https://api.base44.com/docs)
|
||||
* **Technical Support:** support@krow.com
|
||||
|
||||
© 2025 KROW Workforce. All rights reserved.
|
||||
Reference in New Issue
Block a user