zilmate 1.7.2 → 1.7.5

package/src/doc/escalation-checklist.md

@@ -1,97 +1,97 @@
-# Escalation Checklist
-
-Use this checklist before escalating to engineering, operations, compliance, or payments.
-
-## Required Information
-
-- User type: worker or venue.
-- User email or phone.
-- Country.
-- City/town.
-- Page or feature.
-- Exact error message.
-- Time and date of issue.
-- Browser/device if relevant.
-- Screenshots if available.
-
-## Shift Escalation
-
-Include:
-
-- Shift role.
-- Shift date/time.
-- Venue/company name.
-- Worker name.
-- Application status.
-- Shift status.
-- Clock-in/out records.
-- Payment ID if available.
-
-## Verification Escalation
-
-Include:
-
-- Country.
-- Verification provider: Ghana/Hubtel or Didit.
-- Current status.
-- Whether front/back/liveness completed.
-- Whether account name matches ID name.
-- Any rejection reason.
-
-Do not include full ID number in normal support tickets.
-
-## Payment Escalation
-
-Include:
-
-- Provider: Hubtel, Paystack, Razorpay, Stripe.
-- Amount and currency.
-- Reference/checkout ID/payment ID.
-- User ID.
-- Shift ID if related.
-- Provider response.
-- Whether money was captured, pending, failed, refunded, or paid out.
-
-## SMS Escalation
-
-Include:
-
-- Audience: workers, venues, or both.
-- Test or batch.
-- Sender ID.
-- Normalized phone number.
-- Hubtel response details.
-- Gateway PM2 log line.
-- Whether account has SMS credit.
-
-## Fraud Or Abuse Escalation
-
-Escalate immediately if:
-
-- Duplicate accounts suspected.
-- Same ID used by multiple accounts.
-- Same payout account used by multiple unrelated workers.
-- Referral farming suspected.
-- Worker changes name around verification.
-- Venue asks users to pay off-platform.
-- Harassment, threats, unsafe venue, or unsafe worker behavior reported.
-
-## Engineering Escalation Format
-
-Use this format:
-
-```text
-Issue:
-User type:
-Country/city:
-User ID/email:
-Shift ID/payment ID:
-Expected behavior:
-Actual behavior:
-Exact error:
-Steps to reproduce:
-Logs/response:
-Impact:
-Urgency:
-```
-
+# Escalation Checklist
+
+Use this checklist before escalating to engineering, operations, compliance, or payments.
+
+## Required Information
+
+- User type: worker or venue.
+- User email or phone.
+- Country.
+- City/town.
+- Page or feature.
+- Exact error message.
+- Time and date of issue.
+- Browser/device if relevant.
+- Screenshots if available.
+
+## Shift Escalation
+
+Include:
+
+- Shift role.
+- Shift date/time.
+- Venue/company name.
+- Worker name.
+- Application status.
+- Shift status.
+- Clock-in/out records.
+- Payment ID if available.
+
+## Verification Escalation
+
+Include:
+
+- Country.
+- Verification provider: Ghana/Hubtel or Didit.
+- Current status.
+- Whether front/back/liveness completed.
+- Whether account name matches ID name.
+- Any rejection reason.
+
+Do not include full ID number in normal support tickets.
+
+## Payment Escalation
+
+Include:
+
+- Provider: Hubtel, Paystack, Razorpay, Stripe.
+- Amount and currency.
+- Reference/checkout ID/payment ID.
+- User ID.
+- Shift ID if related.
+- Provider response.
+- Whether money was captured, pending, failed, refunded, or paid out.
+
+## SMS Escalation
+
+Include:
+
+- Audience: workers, venues, or both.
+- Test or batch.
+- Sender ID.
+- Normalized phone number.
+- Hubtel response details.
+- Gateway PM2 log line.
+- Whether account has SMS credit.
+
+## Fraud Or Abuse Escalation
+
+Escalate immediately if:
+
+- Duplicate accounts suspected.
+- Same ID used by multiple accounts.
+- Same payout account used by multiple unrelated workers.
+- Referral farming suspected.
+- Worker changes name around verification.
+- Venue asks users to pay off-platform.
+- Harassment, threats, unsafe venue, or unsafe worker behavior reported.
+
+## Engineering Escalation Format
+
+Use this format:
+
+```text
+Issue:
+User type:
+Country/city:
+User ID/email:
+Shift ID/payment ID:
+Expected behavior:
+Actual behavior:
+Exact error:
+Steps to reproduce:
+Logs/response:
+Impact:
+Urgency:
+```
+

package/src/doc/payments-and-payouts.md

@@ -1,82 +1,82 @@
-# Payments And Payouts
-
-Use this guide to support billing setup, shift payment, worker payout, profile promotion, and country-specific payment rails.
-
-## Payment Provider By Market
-
-- Ghana: Hubtel for checkout, SMS, worker payout, and Ghana-specific flows.
-- Nigeria, Kenya, South Africa: Paystack where configured.
-- India: Razorpay.
-- UK, US, and other markets: Stripe where configured.
-
-## Venue Billing
-
-Venues may need to connect billing before posting or paying for shifts.
-
-Ghana venue billing:
-
-- Uses Hubtel gateway `/api/checkout/initiate`.
-- Requires gateway `SUPABASE_SERVICE_ROLE_KEY` to be a real service_role key.
-- Requires Hubtel checkout credentials and account number.
-- Writes checkout/payment state into `payments`.
-
-Common errors:
-
-- `SUPABASE_SERVICE_ROLE_KEY must have role service_role, not anon`: gateway env uses anon key. Replace with Supabase service role key and restart PM2.
-- `Could not find worker_amount column`: live `payments` schema missing compatibility column. Add column and reload schema.
-- Upstream 500: check gateway PM2 logs and Hubtel response body.
-
-## Worker Payout
-
-Workers must have valid payout details before payout can complete.
-
-Ghana worker payout:
-
-- Mobile money or bank details.
-- Phone/account name should be verified where possible.
-- Hubtel sends money or bank transfer through gateway.
-
-Other markets:
-
-- Paystack recipients/subaccounts for supported African countries.
-- Razorpay fund accounts for India.
-- Stripe Connect for Stripe markets.
-
-## Profile Promotion
-
-Workers can pay to promote their profile for 7 days.
-
-Provider routing:
-
-- Ghana: Hubtel checkout.
-- Paystack countries: Paystack checkout.
-- India: Razorpay checkout.
-- Other markets: Stripe checkout.
-
-If profile promotion payment succeeds but profile is not promoted:
-
-- Check payment verification function for the provider.
-- Check `profile_promotions`.
-- Check `workers.promoted_until`.
-- Escalate if provider captured payment but app did not update.
-
-## Refunds And Disputes
-
-Do not promise refunds until status is confirmed.
-
-Escalate when:
-
-- Worker no-show.
-- Venue cancels after worker acceptance.
-- Worker cancels after acceptance.
-- Payment captured but shift canceled.
-- Duplicate charge.
-- Wrong amount.
-
-## Payment Safety Rules
-
-- Never ask users for full card numbers.
-- Never share service_role keys, API keys, Basic Auth tokens, or gateway tokens.
-- Never manually mark payment captured without provider evidence.
-- Always record provider, reference, amount, currency, and user ID in escalations.
-
+# Payments And Payouts
+
+Use this guide to support billing setup, shift payment, worker payout, profile promotion, and country-specific payment rails.
+
+## Payment Provider By Market
+
+- Ghana: Hubtel for checkout, SMS, worker payout, and Ghana-specific flows.
+- Nigeria, Kenya, South Africa: Paystack where configured.
+- India: Razorpay.
+- UK, US, and other markets: Stripe where configured.
+
+## Venue Billing
+
+Venues may need to connect billing before posting or paying for shifts.
+
+Ghana venue billing:
+
+- Uses Hubtel gateway `/api/checkout/initiate`.
+- Requires gateway `SUPABASE_SERVICE_ROLE_KEY` to be a real service_role key.
+- Requires Hubtel checkout credentials and account number.
+- Writes checkout/payment state into `payments`.
+
+Common errors:
+
+- `SUPABASE_SERVICE_ROLE_KEY must have role service_role, not anon`: gateway env uses anon key. Replace with Supabase service role key and restart PM2.
+- `Could not find worker_amount column`: live `payments` schema missing compatibility column. Add column and reload schema.
+- Upstream 500: check gateway PM2 logs and Hubtel response body.
+
+## Worker Payout
+
+Workers must have valid payout details before payout can complete.
+
+Ghana worker payout:
+
+- Mobile money or bank details.
+- Phone/account name should be verified where possible.
+- Hubtel sends money or bank transfer through gateway.
+
+Other markets:
+
+- Paystack recipients/subaccounts for supported African countries.
+- Razorpay fund accounts for India.
+- Stripe Connect for Stripe markets.
+
+## Profile Promotion
+
+Workers can pay to promote their profile for 7 days.
+
+Provider routing:
+
+- Ghana: Hubtel checkout.
+- Paystack countries: Paystack checkout.
+- India: Razorpay checkout.
+- Other markets: Stripe checkout.
+
+If profile promotion payment succeeds but profile is not promoted:
+
+- Check payment verification function for the provider.
+- Check `profile_promotions`.
+- Check `workers.promoted_until`.
+- Escalate if provider captured payment but app did not update.
+
+## Refunds And Disputes
+
+Do not promise refunds until status is confirmed.
+
+Escalate when:
+
+- Worker no-show.
+- Venue cancels after worker acceptance.
+- Worker cancels after acceptance.
+- Payment captured but shift canceled.
+- Duplicate charge.
+- Wrong amount.
+
+## Payment Safety Rules
+
+- Never ask users for full card numbers.
+- Never share service_role keys, API keys, Basic Auth tokens, or gateway tokens.
+- Never manually mark payment captured without provider evidence.
+- Always record provider, reference, amount, currency, and user ID in escalations.
+

package/src/doc/shift-lifecycle-and-disputes.md

@@ -1,95 +1,95 @@
-# Shift Lifecycle And Disputes
-
-This guide explains how shifts move through the platform and how support should handle attendance, cancellations, no-shows, disputes, and completion.
-
-## Shift Statuses
-
-Typical statuses:
-
-- Draft: venue started but has not posted.
-- Open: workers can apply.
-- Filled: venue accepted a worker.
-- In progress: worker clocked in.
-- Completed: work done and ready for completion/payment processing.
-- Cancelled: shift no longer happening.
-
-## Standby Shifts
-
-Standby shifts should not display as normal available paid shifts immediately. They should only become relevant when the primary worker does not show or the venue activates standby need.
-
-Escalate if:
-
-- Worker sees primary and standby shift at the same time.
-- Standby shift shows `0` pay and still allows normal application.
-
-## Applications
-
-Workers apply for shifts. Venues review applications, match score, trust details, ratings, role history, videos, and certifications.
-
-Support should check:
-
-- Application status: pending, accepted, declined, withdrawn.
-- Shift owner.
-- Worker identity verification status.
-- Worker role match.
-
-## Acceptance
-
-When a venue accepts a worker:
-
-- Worker should see accepted shift.
-- Worker and venue should be able to message.
-- Ghana workers should receive SMS if phone is valid.
-- Venue should see attendance/arrival state where available.
-
-## Clock In And Clock Out
-
-Clock-in can happen by:
-
-- Venue QR code.
-- Worker manual clock-in where allowed.
-
-Expected behavior:
-
-- Once clocked in, shift should show active.
-- Returning to the shift page should not ask for clock-in again.
-- Clock-out should close the active time entry.
-
-Escalate if duplicate time entries appear or status resets.
-
-## No-Shows
-
-Each worker no-show should reduce reliability by `-3`.
-
-Support should:
-
-- Confirm shift date/time.
-- Confirm venue marked no-show.
-- Check messages/arrival evidence.
-- Escalate disputes if worker contests.
-
-## Cancellations
-
-Worker cancellation can affect reliability and fees. Venue cancellation can trigger refund/worker compensation rules depending on timing.
-
-Escalate if:
-
-- Worker bypasses cancellation rules.
-- Venue is charged incorrectly.
-- Refund is stuck.
-- Worker says venue canceled but marked worker no-show.
-
-## Disputes
-
-Collect:
-
-- Shift ID or role/date/venue.
-- Worker and venue user IDs if available.
-- Timeline.
-- Messages.
-- Clock-in/out records.
-- Payment records.
-- Screenshots if user has them.
-
-Do not decide high-risk disputes without admin review.
-
+# Shift Lifecycle And Disputes
+
+This guide explains how shifts move through the platform and how support should handle attendance, cancellations, no-shows, disputes, and completion.
+
+## Shift Statuses
+
+Typical statuses:
+
+- Draft: venue started but has not posted.
+- Open: workers can apply.
+- Filled: venue accepted a worker.
+- In progress: worker clocked in.
+- Completed: work done and ready for completion/payment processing.
+- Cancelled: shift no longer happening.
+
+## Standby Shifts
+
+Standby shifts should not display as normal available paid shifts immediately. They should only become relevant when the primary worker does not show or the venue activates standby need.
+
+Escalate if:
+
+- Worker sees primary and standby shift at the same time.
+- Standby shift shows `0` pay and still allows normal application.
+
+## Applications
+
+Workers apply for shifts. Venues review applications, match score, trust details, ratings, role history, videos, and certifications.
+
+Support should check:
+
+- Application status: pending, accepted, declined, withdrawn.
+- Shift owner.
+- Worker identity verification status.
+- Worker role match.
+
+## Acceptance
+
+When a venue accepts a worker:
+
+- Worker should see accepted shift.
+- Worker and venue should be able to message.
+- Ghana workers should receive SMS if phone is valid.
+- Venue should see attendance/arrival state where available.
+
+## Clock In And Clock Out
+
+Clock-in can happen by:
+
+- Venue QR code.
+- Worker manual clock-in where allowed.
+
+Expected behavior:
+
+- Once clocked in, shift should show active.
+- Returning to the shift page should not ask for clock-in again.
+- Clock-out should close the active time entry.
+
+Escalate if duplicate time entries appear or status resets.
+
+## No-Shows
+
+Each worker no-show should reduce reliability by `-3`.
+
+Support should:
+
+- Confirm shift date/time.
+- Confirm venue marked no-show.
+- Check messages/arrival evidence.
+- Escalate disputes if worker contests.
+
+## Cancellations
+
+Worker cancellation can affect reliability and fees. Venue cancellation can trigger refund/worker compensation rules depending on timing.
+
+Escalate if:
+
+- Worker bypasses cancellation rules.
+- Venue is charged incorrectly.
+- Refund is stuck.
+- Worker says venue canceled but marked worker no-show.
+
+## Disputes
+
+Collect:
+
+- Shift ID or role/date/venue.
+- Worker and venue user IDs if available.
+- Timeline.
+- Messages.
+- Clock-in/out records.
+- Payment records.
+- Screenshots if user has them.
+
+Do not decide high-risk disputes without admin review.
+

package/src/doc/support-macros.md

@@ -1,40 +1,40 @@
-# Support Macros
-
-Use these as starting points. Personalize them with the user name, shift, country, or provider.
-
-## Worker Cannot See Shifts
-
-Hi {{name}}, I can help. ZiloShift shows workers shifts in their saved city and matching roles. Please check that your country, city, town, and roles are saved under Profile. If those are correct and you still cannot see same-city shifts, send us the role and city you expect to see and we will investigate.
-
-## Worker Verification Pending
-
-Hi {{name}}, your verification may still be syncing. Ghana workers must complete front card, back card, liveness, and name match checks. Non-Ghana workers complete Didit verification. If you completed everything and still see pending, send us the time you verified and the account email so we can review the verification record.
-
-## Ghana Card Name Mismatch
-
-Hi {{name}}, the name on your ZiloShift account must match the name on your Ghana Card. This protects workers and venues from identity misuse. If your account name was entered incorrectly, we need to escalate it for review instead of changing it directly.
-
-## Venue Billing Failed
-
-Hi {{name}}, billing setup did not complete. I’ll check the payment provider connection for your country and the exact error returned. Ghana venues use Hubtel checkout, so if the checkout page did not open or returned an upstream error, we may need engineering to review the gateway logs.
-
-## Venue Cannot See Applicants
-
-Hi {{name}}, I’ll check whether the shift is open, whether workers have applied, and whether the applicant matching finished loading. If the applicant page stays blank for more than a few seconds, we’ll treat it as a loading issue and escalate it.
-
-## Worker Accepted For Shift
-
-Hi {{name}}, congratulations on being accepted. Please open the shift details and Messages to coordinate with the venue. On the day of the shift, clock in using the venue QR code or the available clock-in button, then clock out when finished.
-
-## SMS Campaign Test Failed
-
-The test SMS reached the gateway but Hubtel rejected it. Please check the returned details for phone format, sender ID length, SMS account credit, recipient blacklist status, or credential issues.
-
-## Payment Delay
-
-Hi {{name}}, I can check the payment status. Payout depends on the shift being completed, the venue/payment provider confirming funds, and your payout details being valid. Please send the shift date, venue/company name, and the payout method you selected.
-
-## Dispute Received
-
-Hi {{name}}, thanks for explaining. We’ll review the shift timeline, messages, clock-in/out records, and payment status before making a decision. Please send any screenshots or details that show what happened.
-
+# Support Macros
+
+Use these as starting points. Personalize them with the user name, shift, country, or provider.
+
+## Worker Cannot See Shifts
+
+Hi {{name}}, I can help. ZiloShift shows workers shifts in their saved city and matching roles. Please check that your country, city, town, and roles are saved under Profile. If those are correct and you still cannot see same-city shifts, send us the role and city you expect to see and we will investigate.
+
+## Worker Verification Pending
+
+Hi {{name}}, your verification may still be syncing. Ghana workers must complete front card, back card, liveness, and name match checks. Non-Ghana workers complete Didit verification. If you completed everything and still see pending, send us the time you verified and the account email so we can review the verification record.
+
+## Ghana Card Name Mismatch
+
+Hi {{name}}, the name on your ZiloShift account must match the name on your Ghana Card. This protects workers and venues from identity misuse. If your account name was entered incorrectly, we need to escalate it for review instead of changing it directly.
+
+## Venue Billing Failed
+
+Hi {{name}}, billing setup did not complete. I’ll check the payment provider connection for your country and the exact error returned. Ghana venues use Hubtel checkout, so if the checkout page did not open or returned an upstream error, we may need engineering to review the gateway logs.
+
+## Venue Cannot See Applicants
+
+Hi {{name}}, I’ll check whether the shift is open, whether workers have applied, and whether the applicant matching finished loading. If the applicant page stays blank for more than a few seconds, we’ll treat it as a loading issue and escalate it.
+
+## Worker Accepted For Shift
+
+Hi {{name}}, congratulations on being accepted. Please open the shift details and Messages to coordinate with the venue. On the day of the shift, clock in using the venue QR code or the available clock-in button, then clock out when finished.
+
+## SMS Campaign Test Failed
+
+The test SMS reached the gateway but Hubtel rejected it. Please check the returned details for phone format, sender ID length, SMS account credit, recipient blacklist status, or credential issues.
+
+## Payment Delay
+
+Hi {{name}}, I can check the payment status. Payout depends on the shift being completed, the venue/payment provider confirming funds, and your payout details being valid. Please send the shift date, venue/company name, and the payout method you selected.
+
+## Dispute Received
+
+Hi {{name}}, thanks for explaining. We’ll review the shift timeline, messages, clock-in/out records, and payment status before making a decision. Please send any screenshots or details that show what happened.
+