From 68becc084b5442f3f5ac148632f678d4b279cf76 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 26 Feb 2026 10:38:41 -0500 Subject: [PATCH] small changes --- docs/api-contracts.md | 266 ----------------------------------------- docs/available_gql.txt | Bin 16316 -> 0 bytes 2 files changed, 266 deletions(-) delete mode 100644 docs/api-contracts.md delete mode 100644 docs/available_gql.txt diff --git a/docs/api-contracts.md b/docs/api-contracts.md deleted file mode 100644 index fd1f30e1..00000000 --- a/docs/api-contracts.md +++ /dev/null @@ -1,266 +0,0 @@ -# KROW Workforce API Contracts - -This document captures all API contracts used by the Staff and Client mobile applications. It serves as a single reference document to understand what each endpoint does, its expected inputs, returned outputs, and any non-obvious details. - ---- - -## Staff Application - -### Authentication / Onboarding Pages (Get Started, Intro, Phone Verification, Profile Setup, Personal Info) -#### Setup / User Validation API -| Field | Description | -|---|---| -| **Endpoint name** | `/getUserById` | -| **Purpose** | Retrieves the base user profile to determine authentication status and role access (e.g., if user is STAFF). | -| **Operation** | Query | -| **Inputs** | `id: UUID!` (Firebase UID) | -| **Outputs** | `User { id, email, phone, role }` | -| **Notes** | Required after OTP verification to route users. | - -#### Create Default User API -| Field | Description | -|---|---| -| **Endpoint name** | `/createUser` | -| **Purpose** | Inserts a base user record into the system during initial signup. | -| **Operation** | Mutation | -| **Inputs** | `id: UUID!`, `role: UserBaseRole` | -| **Outputs** | `id` of newly created User | -| **Notes** | Used explicitly during the "Sign Up" flow if the user doesn't exist. | - -#### Get Staff Profile API -| Field | Description | -|---|---| -| **Endpoint name** | `/getStaffByUserId` | -| **Purpose** | Finds the specific Staff record associated with the base user ID. | -| **Operation** | Query | -| **Inputs** | `userId: UUID!` | -| **Outputs** | `Staffs { id, userId, fullName, email, phone, photoUrl, status }` | -| **Notes** | Needed to verify if a complete staff profile exists before fully authenticating. | - -#### Update Staff Profile API -| Field | Description | -|---|---| -| **Endpoint name** | `/updateStaff` | -| **Purpose** | Saves onboarding data across Personal Info, Experience, and Preferred Locations pages. | -| **Operation** | Mutation | -| **Inputs** | `id: UUID!`, `fullName`, `email`, `phone`, `addres`, etc. | -| **Outputs** | `id` | -| **Notes** | Called incrementally during profile setup wizard. | - -### Home Page (worker_home_page.dart) & Benefits Overview -#### Load Today/Tomorrow Shifts -| Field | Description | -|---|---| -| **Endpoint name** | `/getApplicationsByStaffId` | -| **Purpose** | Retrieves applications (shifts) assigned to the current staff member within a specific date range. | -| **Operation** | Query | -| **Inputs** | `staffId: UUID!`, `dayStart: Timestamp`, `dayEnd: Timestamp` | -| **Outputs** | `Applications { shift, shiftRole, status, createdAt }` | -| **Notes** | The frontend filters the query response for `CONFIRMED` applications to display "Today's" and "Tomorrow's" shifts. | - -#### List Recommended Shifts -| Field | Description | -|---|---| -| **Endpoint name** | `/listShifts` | -| **Purpose** | Fetches open shifts that are available for the staff to apply to. | -| **Operation** | Query | -| **Inputs** | None directly mapped, but filters OPEN shifts purely on the client side at the time. | -| **Outputs** | `Shifts { id, title, orderId, cost, location, startTime, endTime, status }` | -| **Notes** | Limits output to 10 on the frontend. Should ideally rely on a `$status: OPEN` parameter. | - -#### Benefits Summary API -| Field | Description | -|---|---| -| **Endpoint name** | `/listBenefitsDataByStaffId` | -| **Purpose** | Retrieves accrued benefits (e.g., Sick time, Vacation) to display on the home screen. | -| **Operation** | Query | -| **Inputs** | `staffId: UUID!` | -| **Outputs** | `BenefitsDatas { vendorBenefitPlan { title, total }, current }` | -| **Notes** | Calculates `usedHours = total - current`. | - -### Find Shifts / Shift Details Pages (shifts_page.dart) -#### List Available Shifts Filtered -| Field | Description | -|---|---| -| **Endpoint name** | `/filterShifts` | -| **Purpose** | Used to fetch Open Shifts in specific regions when the worker searches in the "Find Shifts" tab. | -| **Operation** | Query | -| **Inputs** | `$status: ShiftStatus`, `$dateFrom: Timestamp`, `$dateTo: Timestamp` | -| **Outputs** | `Shifts { id, title, location, cost, durationDays, order { business, vendor } }` | -| **Notes** | - | - -#### Get Shift Details -| Field | Description | -|---|---| -| **Endpoint name** | `/getShiftById` | -| **Purpose** | Gets deeper details for a single shift including exact uniform/managers needed. | -| **Operation** | Query | -| **Inputs** | `id: UUID!` | -| **Outputs** | `Shift { id, title, hours, cost, locationAddress, workersNeeded ... }` | -| **Notes** | - | - -#### Apply To Shift -| Field | Description | -|---|---| -| **Endpoint name** | `/createApplication` | -| **Purpose** | Worker submits an intent to take an open shift. | -| **Operation** | Mutation | -| **Inputs** | `shiftId`, `staffId`, `status: APPLIED` | -| **Outputs** | `Application ID` | -| **Notes** | A shift status will switch to `CONFIRMED` via admin approval. | - -### Availability Page (availability_page.dart) -#### Get Default Availability -| Field | Description | -|---|---| -| **Endpoint name** | `/listStaffAvailabilitiesByStaffId` | -| **Purpose** | Fetches the standard Mon-Sun recurring availability for a staff member. | -| **Operation** | Query | -| **Inputs** | `staffId: UUID!` | -| **Outputs** | `StaffAvailabilities { dayOfWeek, isAvailable, startTime, endTime }` | -| **Notes** | - | - -#### Update Availability -| Field | Description | -|---|---| -| **Endpoint name** | `/updateStaffAvailability` (or `createStaffAvailability`) | -| **Purpose** | Upserts availability preferences. | -| **Operation** | Mutation | -| **Inputs** | `staffId`, `dayOfWeek`, `isAvailable`, `startTime`, `endTime` | -| **Outputs** | `id` | -| **Notes** | Called individually per day edited. | - -### Payments Page (payments_page.dart) -#### Get Recent Payments -| Field | Description | -|---|---| -| **Endpoint name** | `/listRecentPaymentsByStaffId` | -| **Purpose** | Loads the history of earnings and timesheets completed by the staff. | -| **Operation** | Query | -| **Inputs** | `staffId: UUID!` | -| **Outputs** | `Payments { amount, processDate, shiftId, status }` | -| **Notes** | Displays historical metrics under Earnings tab. | - -### Compliance / Profiles (Agreements, W4, I9, Documents) -#### Get Tax Forms -| Field | Description | -|---|---| -| **Endpoint name** | `/getTaxFormsByStaffId` | -| **Purpose** | Check the filing status of I9 and W4 forms. | -| **Operation** | Query | -| **Inputs** | `staffId: UUID!` | -| **Outputs** | `TaxForms { formType, isCompleted, updatedDate }` | -| **Notes** | Required for staff to be eligible for shifts. | - -#### Update Tax Forms -| Field | Description | -|---|---| -| **Endpoint name** | `/updateTaxForm` | -| **Purpose** | Submits state and filing for the given tax form type. | -| **Operation** | Mutation | -| **Inputs** | `id`, `dataPoints...` | -| **Outputs** | `id` | -| **Notes** | Updates compliance state. | - ---- - -## Client Application - -### Authentication / Intro (Sign In, Get Started) -#### Client User Validation API -| Field | Description | -|---|---| -| **Endpoint name** | `/getUserById` | -| **Purpose** | Retrieves the base user profile to determine authentication status and role access (e.g., if user is BUSINESS). | -| **Operation** | Query | -| **Inputs** | `id: UUID!` (Firebase UID) | -| **Outputs** | `User { id, email, phone, userRole }` | -| **Notes** | Must check if `userRole == BUSINESS` or `BOTH`. | - -#### Get Business Profile API -| Field | Description | -|---|---| -| **Endpoint name** | `/getBusinessByUserId` | -| **Purpose** | Maps the authenticated user to their client business context. | -| **Operation** | Query | -| **Inputs** | `userId: UUID!` | -| **Outputs** | `Business { id, businessName, email, contactName }` | -| **Notes** | Used to set the working scopes (Business ID) across the entire app. | - -### Hubs Page (client_hubs_page.dart, edit_hub.dart) -#### List Hubs -| Field | Description | -|---|---| -| **Endpoint name** | `/listTeamHubsByBusinessId` | -| **Purpose** | Fetches the primary working sites (Hubs) for a client. | -| **Operation** | Query | -| **Inputs** | `businessId: UUID!` | -| **Outputs** | `TeamHubs { id, hubName, address, contact, active }` | -| **Notes** | - | - -#### Update / Delete Hub -| Field | Description | -|---|---| -| **Endpoint name** | `/updateTeamHub` / `/deleteTeamHub` | -| **Purpose** | Edits or archives a Hub location. | -| **Operation** | Mutation | -| **Inputs** | `id: UUID!`, `hubName`, `address`, etc (for Update) | -| **Outputs** | `id` | -| **Notes** | - | - -### Orders Page (create_order, view_orders) -#### Create Order -| Field | Description | -|---|---| -| **Endpoint name** | `/createOrder` | -| **Purpose** | The client submits a new request for temporary staff (can result in multiple Shifts generated on the backend). | -| **Operation** | Mutation | -| **Inputs** | `businessId`, `eventName`, `orderType`, `status` | -| **Outputs** | `id` (Order ID) | -| **Notes** | This creates an order. Shift instances are subsequently created through secondary mutations. | - -#### List Orders -| Field | Description | -|---|---| -| **Endpoint name** | `/getOrdersByBusinessId` | -| **Purpose** | Retrieves all ongoing and past staff requests from the client. | -| **Operation** | Query | -| **Inputs** | `businessId: UUID!` | -| **Outputs** | `Orders { id, eventName, shiftCount, status }` | -| **Notes** | - | - -### Billing Pages (billing_page.dart, pending_invoices) -#### List Invoices -| Field | Description | -|---|---| -| **Endpoint name** | `/listInvoicesByBusinessId` | -| **Purpose** | Fetches "Pending", "Paid", and "Disputed" invoices for the client to review. | -| **Operation** | Query | -| **Inputs** | `businessId: UUID!` | -| **Outputs** | `Invoices { id, amountDue, issueDate, status }` | -| **Notes** | Used across all Billing view tabs. | - -#### Mark Invoice -| Field | Description | -|---|---| -| **Endpoint name** | `/updateInvoice` | -| **Purpose** | Marks an invoice as disputed or pays it (changes status). | -| **Operation** | Mutation | -| **Inputs** | `id: UUID!`, `status: InvoiceStatus` | -| **Outputs** | `id` | -| **Notes** | Disputing usually involves setting a memo or flag. | - -### Reports Page (reports_page.dart) -#### Get Coverage Stats -| Field | Description | -|---|---| -| **Endpoint name** | `/getCoverageStatsByBusiness` | -| **Purpose** | Provides data on fulfillments rates vs actual requests. | -| **Operation** | Query | -| **Inputs** | `businessId: UUID!` | -| **Outputs** | `Stats { totalRequested, totalFilled, percentage }` | -| **Notes** | Driven mostly by aggregated backend views. | - ---- - -*This document reflects the current state of Data Connect definitions implemented across the frontend and mapped manually by reviewing Repository and UI logic.* diff --git a/docs/available_gql.txt b/docs/available_gql.txt deleted file mode 100644 index 54380559d6447a33449d5445463fdd8f1596d534..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 16316 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