Merge pull request #64 from Oloodi/58-webbase44-frontend-update-from-export---1
feat: add documentation for GCP migration and Base44 API export
This commit is contained in:
José Salazar
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