About the project

Covered runs a house-cleaning cooperative's week. A day before each visit, the household's PayPal holds the pay. When a cleaner calls in sick, an agent finds who can cover, and the money stays with the visit. Whoever walks out of the house is paid about 25 seconds later.

The Bryntum board with the agent's plan as dashed bars

Inspiration

On 15 September 2026, Seattle's council passed Council Bill 121266, 9 to 0 (minutes). From 1 July 2027, a house cleaner's written agreement must state "the work cancellation policy, such as the acceptable notification period and any cancellation payment owed to the domestic worker", in English and in the worker's primary language, and the hiring entity must keep pay and hour records for three years (Ordinance 127508).

I audit payment systems for a living. When I read the bill, I saw two payment controls written as employment law. A cancellation policy is a promise unless the fee is collected before the cleaner travels. A pay record is paperwork unless it is the payment itself.

Covered makes both of them PayPal objects. The cancellation policy is an authorization. The pay record is a transaction id.

What it does

Covered is a web app for a house-cleaning cooperative. A coordinator plans the week on a board, members work from their phones, and households sign and pay from theirs.

The rule. The notice window and the payment hold are the same 24 hours. A day before each visit, Covered authorizes the visit's price, plus 30 minutes of possible extra time, on the household's saved PayPal, with no buyer present.

  • Cancel before the window: nothing was held.
  • Cancel inside it: the agreed fee is captured, the rest is released, and the fee goes to the member who kept the morning free.
  • Nobody opens the door: the lock-out fee is captured.
  • The visit happens: the member checks out on their phone, the visit is captured, and the member's share reaches their PayPal through Payouts.

The hold belongs to the visit, not to the member. At 07:10 on the demo Thursday, Sam writes that his son has a fever. Gemini reads the message, and a solver lists every valid way to cover his three homes. The agent picks one and explains why, and the plan appears on the board as dashed bars. Dana, the coordinator, approves. Marek takes the Okafors, who asked for the same cleaner, so they are asked first on their phone. Teresa takes the other two. Messages go out in Polish and Portuguese. The Okafors' $157.50 hold never moves. It pays Marek when he checks out: $140.00 captured, $17.50 released, $133.00 to Marek.

Dragging a visit: only the members who can take it light up

The board guards itself. Dana can drag a visit herself. While the bar is in the air, only the members who can really take it light up. Drop it on Joy and the board says why not: "does not work that day; no pets; would pass 20 h this week". The answers come from the same solver the agent uses, and the server checks again on the drop.

Late cancellation. At 13:30, Mr. Lindqvist cancels his 14:00 visit. His phone shows the $35.00 fee before he confirms. $35.00 is captured from the $87.50 hold, $52.50 is released, and Marek receives $33.25.

Income proof. Marek's statement lists every visit, the hours from his check-in and check-out, the payout and its PayPal transaction id. One button makes a signed, expiring link for a landlord: months, hours and totals, with no household names or addresses.

Sign-up. A new household describes the job in its own words. The member states their terms in their language, typed or as a voice note. Gemini drafts the agreement, and a checklist in code decides when it can be signed:

  • the terms the ordinance names: scope, location, schedule, rate, payment schedule, cancellation policy, expenses, classification, benefits and leave;
  • a rate at or above Seattle's minimum of $21.30 an hour (City of Seattle).

The household reads the agreement back in its own language, signs, and saves PayPal once on PayPal's own approval page.

Refused holds. If PayPal refuses a hold, the visit turns red on the board and the household's phone asks it to save PayPal again; the hold is then placed on the next sweep.

Disputes. If a household disputes a charge, the coordinator opens the evidence from the visit. It shows the agreed terms, the check-in and check-out times, and the hold, capture and payout ids, all built from the ledger.

How I built it

Architecture

PayPal. Six PayPal surfaces carry the product:

PayPal Use
Vault v3 The household saves PayPal once, at signing
Orders v2, intent: AUTHORIZE, vaulted, merchant-initiated The hold, 24 hours before each visit, buyer absent
Payments Capture at check-out; partial capture with final_capture for a late-cancel fee, which releases the rest; void when nobody can cover
Payouts The member's pay, polled until final
Transaction Search Reconciles the income statement
Webhooks Kept only when verify-webhook-signature confirms them, and tied to the visit by invoice id or sender batch id

Orders, Payments, Vault and Transaction Search use the PayPal Server SDK for TypeScript (@paypal/paypal-server-sdk, generated by APIMatic); Payouts and webhook verification use REST. Every money call carries a PayPal-Request-Id and an invoice id built from the visit and the demo run, and every payout a sender_batch_id built the same way.

APIMatic. I checked the client against APIMatic's PayPal Server SDK Context Plugin, and its TypeScript guides changed three things. A rejected token request is cached and disables a long-lived client, so the token is now a plain value with a new SDK client per call. The generated timeout of 0 means no timeout, so every call sets 30 seconds. And a stub axios adapter is the test seam, so the tests pin what each call sends over the wire, with no network.

Bryntum. The board is Bryntum Scheduler at the Enterprise tier, version 8.0, and each feature carries a rule of the product:

  • a calendar per member, drawn with resourceNonWorkingTime, so each row is shaded outside that member's own hours;
  • eventBuffer for the travel to the member's next home;
  • calendarHighlight fed by the solver, so a dragged bar lights up only the members who can take it;
  • eventDrag's validator for the reason in the tooltip, and an asynchronous beforeEventDropFinalize for the server's final check;
  • resourceTimeRanges for "Out today" across the absent member's row, and a time range for the demo clock's now line;
  • the week in CrudManager format, with stores on syncDataOnLoad, so each update animates only the bars that moved;
  • a non-continuous time axis: six working days from 07:00 to 19:00, with the nights removed.

Cloudflare. The money steps are Cloudflare Workflows: one instance per money task, with each step persisted and retried (place the hold; capture and pay; check the payout, with a durable sleep between checks; record the outcome). The ledger is a Durable Object with SQLite, the API is a Worker running Hono, a cron trigger starts the sweep every 5 minutes, and Pages serves the site. It all runs on the free plan.

Gemini. Gemini reads members' messages, chooses among the solver's plans through function calling, writes each message in the recipient's language, drafts agreements from text and voice, translates read-backs, and writes the statement's cover letter. Code decides every amount, every fee, who is paid, which covers are valid and whether an agreement can be signed.

The checks between them:

  • The agent can only submit a plan the solver returned, and it has no tool that touches PayPal.
  • A message with a number the tools did not give is replaced by a template.
  • A read-back that changes a number is not shown.
  • The rate, notice and fee must appear in the member's own words.

The demo path's answers are recorded in the repository, so the deployed demo responds instantly and the repo runs with no key.

Stack. TypeScript throughout: Hono, React, SQLite, Vitest with fast-check, Playwright with axe-core, oxlint, Prettier, GitHub Actions, a Dockerfile, and a devcontainer for Codespaces.

Challenges I ran into

Idempotency across retries and across demo resets. A task can fail between the capture and the payout. On the live site I made the settlement step fail at exactly that point. Cloudflare Workflows retried the step, which captured nothing new and paid once. PayPal itself refused a second capture (AUTHORIZATION_ALREADY_CAPTURED) and a second payout batch. Because the demo resets the same week many times, every PayPal id also carries a run tag drawn at each reset.

The PayPal SDK on Workers. The SDK sends requests through axios, whose fetch adapter always passes cache: "default", and Workers refuse that option. A small shim that loads before the SDK drops it. Durable Object stubs also belong to the request that made them, so the ledger client asks for a new one on every call.

Numbers in other languages. Translating an agreement is where a model is most likely to change an amount. Every read-back is checked number by number against the English text before a household sees it, and a test keeps a real refused translation as a fixture: a Portuguese read-back that turned the $133.00 hold into $114.00.

A household's yes arrives later. Marek could be booked elsewhere while the Okafors were being asked, and their yes would then double-book him. The test suite caught it, along with four other bugs, and each now has its own regression test. A yes runs the same check again.

Accomplishments that I'm proud of

The money path is real, on the live site, in US dollars on the PayPal sandbox:

  • 15 buyer-absent holds placed by Workflows in 10 seconds;
  • a $140.00 capture with $17.50 released, and a $35.00 late-cancel fee with $52.50 released;
  • payouts final in 23.7 and 25.5 seconds, each with a PayPal transaction id;
  • 18 webhook deliveries in that run confirmed by PayPal's signature check, and none refused.

The cover solver breaks no rule:

  • development set (60 scenarios): every placeable visit placed, 55 of 55, and 0 rules broken;
  • held-out set (20 scenarios, labelled before the solver ever ran on them): 20 of 20, 0 rules broken;
  • a "first free member" baseline breaks a rule in 68 of 86 and 26 of 29 placements.

The pay rules were written before the engine:

  • 40 cases worked out by hand, and the engine matches all 40;
  • property tests on 9,000 random cases check that money is conserved and the capture never exceeds the hold;
  • mutation testing of the engine kills 143 of 154 mutants (92.86%).

Self-attack: 13 hostile inputs against the live model, all handled:

  • prompt injection in a household's job text;
  • a member's message ordering a payment, or trying to change their rate;
  • a rate below Seattle's minimum, and an agreement with no schedule;
  • a forged webhook, a stranger's check-out, a cancellation after the visit started;
  • a dispute, and the crash between capture and payout.

Engineering: 377 unit and integration tests in random order, with no network and no keys, and 11 browser tests. The decision core has 97.7% line coverage and 92% branch coverage. axe-core finds 0 WCAG 2.1 AA violations on every screen of the story, the Bryntum board included.

What I learned

A payment hold is a scheduling primitive. Once the hold belongs to the visit, a sick call becomes a scheduling problem with the money already in place, and the coordinator never touches a payment.

A scheduler's drag can carry a real rule. The board's refusal is not a separate validation layer: it is the agent's solver, asked one question at a time.

The model is most useful where the people are: reading a hurried message, writing to Teresa in Portuguese, turning a voice note into contract terms. It is least trusted where the money is, and the code says so in one sentence on the page.

What's next

  • A pilot with a cleaning cooperative in Seattle before the ordinance takes effect on 1 July 2027.
  • Recurring agreements that renew the vaulted consent each season.
  • The same rule for other visit-based work under similar ordinances: home care, dog walking, tutoring.

Built With

  • apimatic
  • fastify
  • gemini
  • node.js
  • paypal-orders
  • paypal-payments
  • paypal-payouts
  • paypal-server-sdk
  • paypal-transaction-search
  • paypal-vault
  • paypal-webhooks
  • postgresql
  • react
  • render
  • render-workflows
  • typescript
  • vitest
Share this project:

Updates

Submission history