Skip to content
ketutezraugmPublic

About

Leonid: the EO’s best friend.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Leonid

Leonid is an AI operations agent for community tech events that runs all of an event's money on PayPal. Sponsor money comes in through PayPal Invoicing, purchases and people payouts go out through the organizer's own PayPal wallet, and every outflow passes spending rules that no agent can break. The organizer sets a max spend once. The agent plans the event and scouts venues, and every payment (a venue plan the organizer agrees to, a volunteer's receipt claim, a prize) is checked against the rules and sent only if they allow it. Every decision is written to an audit log, and a PayPal-enforced kill switch (deleting the vault payment token) stops the agent's spending instantly.

This is a working build on the PayPal sandbox: no live keys, no real money. Built for the PayPal AI Hackathon. Full spec: docs/PRD.pdf.

Live demo

App (hosted demo) https://quartermaster-staging.onrender.com (seeded event: OpenHack 2027). No PayPal sandbox account is needed: press Enter the demo with the judge access code from the submission notes, or open the one-click link given there
Demo video https://youtu.be/fiTMPqjL3JA (2:55)
Health check https://quartermaster-staging.onrender.com/api/health

The hosted demo runs on a paid Render web service, so it does not sleep.

Trying it (about 3 minutes).

  1. Open the app link from the submission notes (it carries the access code), or paste the code into the box and press Enter the demo.
  2. You land on your events, with the seeded OpenHack 2027 event. Your session is private: events you create are visible only to you, and each event keeps its own budget and caps.
  3. Agent: ask Leo to plan the event and scout a venue, review the plan, and pay it with PayPal (sandbox). The payment goes through the rules check and is written to the audit log. A venue payment is above the agent wallet's $1,000 daily auto-pay limit, so the rules send it to approval and PayPal's own approval window opens: sign in there with the sandbox account in the submission notes and approve.
  4. Plan: the Bryntum Calendar, coloured by workstream, with each purchase labelled by the sponsor that funds it.
  5. Money: the AG Studio command center and the dashboard agent.
  6. Settings: the agent's wallet and the kill switch. Revoking the wallet deletes its token at PayPal, and PayPal refuses the next charge. The demo wallet is shared by every judge, so try this last; Restore demo wallet switches on one of the spare wallets again.

Hackathon qualification

Requirement How this repo meets it
Uses PayPal APIs end to end in the sandbox Log in with PayPal, Invoicing, Orders, Vault, Payouts, Transaction Search and webhooks. See PayPal capabilities used
An AI agent that acts on money, not just talks about it The agent plans the event and scouts venues in a tool loop. A model also reads a volunteer's receipt, and the payout is sent with no human step when the rules allow it. Every payment goes through the executor, which pays only after the rules engine says allow. See Agent loop and Receipt claims and payouts
Public GitHub repo with setup, architecture and payment flow Setup · Architecture · Payment flow
Demo video under 3 minutes 2:55 on YouTube; script in docs/demo-script.md
Sponsor integrations AG Studio · Bryntum · Render · APIMatic

What it does

Area What the organizer gets Features
Rules are code A max spend plus daily and category caps and approved vendors, enforced by a deterministic check(); never by a prompt F9
Agent wallet Connect PayPal once; the agent pays from the vaulted wallet, supervised payments use PayPal's approve button F13, F14
Kill switch One click deletes the vault token at PayPal; there is no fallback payment path F15
Money in Sponsor invoices (Invoicing v2), public ticket and donation checkout, live status from webhooks F4, F6
Money out Volunteer receipt claims and prize or speaker payouts (Payouts v1) through the same rules F16, F17
One plan Bryntum Calendar coloured by workstream; each purchase names the sponsor that funds it F11
Command center AG Studio dashboard with custom widgets and a dashboard agent F20, F21
Sponsor report A report built by a Render Workflow from reconciled data F22

Architecture

  Organizer ── Log in with PayPal ──▶ session (allowlist)
      │
      ▼
┌───────────────────────────────────────────────────────┐
│  Web (apps/web: React + Vite)                          │
│  Agent chat · Plan · Money · Claims · Sponsor report   │
│  Only the PayPal JS SDK runs here; no PayPal secrets   │
└────────────────────┬──────────────────────────────────┘
                     │ /api (zod contracts: packages/shared)
                     ▼
┌───────────────────────────────────────────────────────┐
│  API (apps/api: Express 5)                             │
│  agents ─▶ executor ─▶ rules check() ─▶ PayPal client  │
│               │            allow | needs_approval |    │
│               │            block   (pure, no I/O)      │
│               └──▶ audit_log (input, reason, rule      │
│                    result, PayPal id)                  │
└───────┬─────────────────────────────┬─────────────────┘
        │ Treasury app                │ Procurement app
        │ Identity, Invoicing,        │ Vault, spend Orders
        │ income Orders, Payouts,     │
        │ Transaction Search          │
        ▼                             ▼
┌───────────────────────────────────────────────────────┐
│  PayPal sandbox ──▶ webhooks ──▶ /api/webhooks/paypal  │
│  (signature verified, then the ledger is updated)      │
└───────────────────────────────────────────────────────┘
  Postgres (Supabase) · Render web service + Render Workflows

Webhooks are the source of truth. "Paid" comes from PayPal's events, never from our own guess. Transaction Search lags, so it is used for reconciliation and reports only.

Payment flow

  1. Set the limit — the organizer connects a PayPal wallet (Vault v3 setup token → payment token) and sets a max spend with the "Add rule" button in the agent chat.
  2. Plan and source — the agent writes a checklist, finds venues, and drafts a spend. Product pages, receipts and invoice notes are treated as data, never as instructions.
  3. Check the rules — every spend goes through check(spend, rules, budget) and returns allow, needs_approval or block. The result and the reason go to the audit log.
  4. Pay or stop — allow charges the vaulted wallet; block pays nothing; needs_approval creates an order the treasurer approves with PayPal's button, captured only after PayPal reports it APPROVED for the exact amount. The demo rules have no approval threshold (removed Nov 9), but a spend that would take the day's automatic payments past the agent wallet's $1,000 daily cap still needs approval: that is how a venue payment is approved.
  5. Confirm from PayPal — the capture, payout or invoice webhook updates the ledger. Payout items are matched by sender_item_id, so an unclaimed or returned item is never shown as paid.
  6. Kill switch — deleting the vault payment token at PayPal makes every later automatic spend fail.

Only the executor can reach the PayPal spend call (apps/api/src/paypal/spend.ts); an ESLint rule enforces that import boundary.

Setup

Prerequisites: Node 22 and pnpm (corepack enable). A hosted demo already exists (see Live demo), so local setup is only needed for development.

pnpm install
cp .env.example .env   # PayPal sandbox credentials, DATABASE_URL, OPENROUTER_API_KEY, ...
pnpm --filter @leonid/api db:migrate && pnpm --filter @leonid/api db:seed
pnpm dev               # web on http://localhost:5173, API on http://localhost:3001

Other commands: pnpm build, pnpm start (serves the built web app from the API), pnpm typecheck, pnpm lint, pnpm test. Env var names and what each one does are in .env.example.

You need two PayPal sandbox apps (Treasury and Procurement, each with a webhook), a sandbox business account for the organizer and a sandbox personal account for a sponsor. Day-1 checks are in docs/p2/DAY1-RUNBOOK.md. Locally, PayPal's dashboard refuses an http://localhost return URL, so use the demo login on a local run and real login on staging.

What's real vs. simulated

Status
PayPal login, invoices, orders, vault, payouts, webhooks Real: PayPal sandbox, no live keys anywhere
Rules engine, audit log, kill switch Real: deterministic code, token deleted at PayPal
Payouts on the sandbox Real: on Nov 11 a $1.00 prize was paid through the app and PayPal's payout webhook marked it Paid. A receipt claim shares that payout path; it is covered by tests with PayPal faked and has not been run end to end on the hosted demo
Seeded event (OpenHack 2027: 200 people, Mar 14, 2027, $8,000, three sponsors) Sample data: generic products and names, no brand assets
Plan tasks Sample data on some screens, labelled in the UI; sponsor status is live
Late-delivery recovery (F18, F19) Not built yet

Repo layout

Path What
apps/web React + Vite front end; src/pages/ maps to the PRD screens
apps/api Express API: agents, rules engine, executor, PayPal clients, webhooks
apps/workflows Render Workflow jobs (budget recompute, invoice reminders, sponsor report)
packages/shared API contract: zod schemas and types shared by web and API
render.yaml Render Blueprint (web service; Postgres is Supabase)
docs/ PRD, demo script, per-owner notes and sandbox results

PayPal capabilities used

Capability Code
OAuth client credentials (per app, cached token) apps/api/src/paypal/client.ts
Orders v2: create order, show order apps/api/src/paypal/orders.ts
Log in with PayPal (OpenID Connect: authorize, code exchange, userinfo) for the treasurer; only members of an allowlist get a session (F1) apps/api/src/auth/, apps/api/src/routes/auth.ts
Vault v3: setup token, payment token for the agent wallet, and deleting the token as the kill switch (F13, F15) apps/api/src/paypal/vault.ts, apps/api/src/routes/wallet.ts, revokeWallet in apps/api/src/payments/executor.ts, the demo wallet pool in apps/api/src/payments/pool.ts and apps/api/src/routes/walletPool.ts
Orders v2, automatic payment: charge the saved wallet with vault_id, only after the rules engine says allow (F13) apps/api/src/paypal/spend.ts (imported only by the executor; ESLint enforces it), apps/api/src/payments/executor.ts
Orders v2, supervised payment: an order the treasurer approves with PayPal's button, captured only after PayPal reports it APPROVED for the exact amount (F14) apps/api/src/payments/executor.ts, apps/api/src/routes/approvals.ts, apps/api/src/webhooks/orderApproved.ts (CHECKOUT.ORDER.APPROVED backup), apps/web/src/approvals/
Reporting: Treasury account balances for the wallet card (F2) apps/api/src/paypal/balances.ts, apps/api/src/routes/treasury.ts
Sandbox negative testing (PayPal-Mock-Response) apps/api/src/paypal/client.ts, apps/api/scripts/paypal-smoke.ts (pnpm --filter @leonid/api paypal:smoke)
Invoicing v2: create, send, show, search by reference (sponsor invoices, F4) apps/api/src/paypal/invoicing.ts, apps/api/src/invoices/send.ts, apps/api/src/routes/invoices.ts
Orders v2, public checkout for tickets and donations with no login (F6): the server creates and prices the order (custom_id carries leonid:<eventId>:ticket or leonid:<eventId>:donation), PayPal's JS button only approves it, the server captures it, and the PAYMENT.CAPTURE.COMPLETED webhook records the amount net of PayPal fees in the ledger. Proven on staging: a $25 ticket and a $10 donation both reached the ledger apps/api/src/routes/checkout.ts, apps/api/src/paypal/income.ts, apps/api/src/webhooks/handlers/capture-completed.ts, apps/web/src/checkout/PayButtons.tsx
Webhook events into the ledger: INVOICING.INVOICE.PAID, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED apps/api/src/webhooks/handlers/, apps/api/src/db/ledger.ts
Payouts v1 (F16, F17): receipt claims, prizes and speaker fees, one payout per spend with our reference id as sender_batch_id, sender_item_id and PayPal-Request-Id, sent only by the executor after the rules engine (Treasury app) apps/api/src/paypal/payouts.ts, apps/api/src/payments/executor.ts, apps/api/src/claims/service.ts, apps/api/src/payouts/service.ts, apps/api/scripts/day1/payouts.ts
Payout item webhooks: PAYMENT.PAYOUTS-ITEM.* (succeeded, failed, unclaimed, returned and the rest) mark each claim, prize or speaker fee paid or not, matched by sender_item_id (F17) apps/api/src/webhooks/handlers/payout-item.ts, apps/api/src/paypal/payout-status.ts
Transaction Search: one sandbox query (day-1 check only; reconciliation comes with F20 and F22) apps/api/scripts/day1/search.ts

Sponsor integrations

AG Studio

The Money screen is an AG Studio command center, themed from apps/web/src/styles/tokens.css. Its data sources are built from the shared widget shapes (packages/shared/src/widgets.ts); they are filled from the treasurer-only endpoints GET /api/widgets/*. The funding thermometer, budget burn and rules health are live, from the ledger, the budget figures and the audit log. The payouts ledger is live too: every receipt claim, prize and speaker fee, with the status PayPal's payout item webhooks last reported. Delivery risk is labelled sample until orders and tracking exist. A line above the widgets says which is which. If the endpoints cannot be reached (not signed in, no server), the page shows its own sample as a whole and says why, because live sponsor ids would not match sample rows and the cross-filtering would break.

What Code
Studio wiring, lazy-loaded apps/web/src/money/CommandCenter.tsx
Theme from design tokens apps/web/src/money/studio-theme.ts
Data sources from the shared shapes apps/web/src/money/studio-data.ts
Default report (KPIs, funding, budget burn, payouts ledger) apps/web/src/money/initial-report.ts
Widget endpoints, in the shared shapes apps/api/src/routes/widgets.ts
Data hook: fetch, label the source, fall back apps/web/src/money/use-command-center-data.ts
Custom widgets: funding thermometer, budget burn, rules health, delivery risk apps/web/src/money/widgets/

Money command center, with sample data

Budget burn is a custom widget: for each budget category it shows what was spent (captured) and committed (authorised, not yet captured) against the category's cap. A category over its cap says so in words and gets a line at the cap. Clicking a category cross-filters the widgets that share its table. Its numbers are live: committed spend is counted exactly as the rules check counts it, and the caps are the rules in force, so the widget and the rules agree on what is left.

Budget burn widget

Rules health is a third custom widget: how many recent spends the rules allowed, sent to the treasurer or blocked, with each check's amount, category and reasons. A check that has no reasons is labelled, and one with a decision it does not recognise is reported instead of counted.

Rules health widget

Delivery risk is the fourth custom widget: the ordered items against their deadlines, most urgent first, with how many are late, at risk, on track or without a delivery date yet. An item with no date says so; it is never shown as arriving on its deadline.

Delivery risk widget

Cross-filtering. A click on a sponsor or a budget category filters the widgets that list individual rows: the payouts ledger, rules health and delivery risk. The funding, budget and KPI widgets ignore other widgets' selections on purpose, because a category total is not a sponsor's and a query that joins one through the other can inflate a sum. Studio's fan-out check is set to refuse such a query (options.fanout.execute: 'prevent'). Studio does not tell a custom widget that the filters changed, so CommandCenter passes onStateUpdated to apps/web/src/money/widgets/filters-changed.ts, which makes the row-listing widgets fetch again.

The Stage 2 write-up, with how the cross-filtering works and what is still sample: docs/p3/stage-2.md. Setup notes and the day-1 PayPal checks: docs/p3/stage-0.md. The licence key is read from VITE_AG_STUDIO_LICENSE and is not committed.

Dashboard agent (F21). "Ask the dashboard agent" above the widgets opens Studio's AI Assistant, run by our own agent harness built on AG Studio's agent framework (apps/web/src/money/dashboardAgent.ts). Our agent, the Leonid analyst, answers the treasurer. It reads the dashboard (schema, report, page) and queries its data, then hands building to AG's own five agents with delegate_to: the lead agent adds and configures a new chart, and the widget and page agents do the details. Every agent's model turn goes to our API (apps/api/src/routes/dashboardAgent.ts), which holds the model key, is treasurer-only and rate-limited, and audits each turn. The API runs no tool itself; Studio runs its dashboard tools in the browser, and there are no money tools to call. Asked "Where are we overspending?" on the seeded event (checked on Nov 9 against the real model, about 80 seconds), it added a "Spend vs Cap by Category" chart, left the existing widgets as they were, and answered from the data: swag $140 of its $1,000 cap; prizes $1,680 with no cap set. A widget the agent adds lasts until the page is reloaded.

The dashboard agent answering "Where are we overspending?"

Receipt claims and payouts

Volunteers, speakers and winners are paid from the Treasury app with PayPal Payouts, and every payment passes the same rules engine as a purchase.

  • Receipt claims (F16). The treasurer registers a volunteer with their PayPal email and gets a personal claim link (/claim/:token; only a SHA-256 hash of the token is stored). On a phone, the volunteer snaps a receipt. A model reads it into a fixed schema (merchant, date, total, currency, line items, a confidence for each), with the photo passed as data, so text on a receipt cannot change who is paid or how much. A clear reading goes to the executor as a claim: the rules check it (the $50 per person per day cap and the event's maximum spend), the check is audited, a claim that breaks a rule is blocked, and the money goes only to the registered email. A field under 0.8 confidence, a foreign currency or no total waits for the treasurer, whose confirmed amount still goes through the rules. Code: apps/api/src/claims/, apps/api/src/routes/claims.ts, apps/web/src/pages/VolunteerClaim.tsx, apps/web/src/pages/Claims.tsx.
  • Prizes and speaker fees (F17). The Money screen's Payouts tab pays a winner or a speaker through the rules engine. The rules engine checks each payment (max spend, daily and category caps) and audits it, and an allowed one is sent at once. A payout that would take the day past the $1,000 daily cap waits for approval, and the screen that approved payouts was removed on Nov 9, so keep each prize under $1,000. A prize funded by a sponsor is not held for that sponsor's invoice (the sponsor gate is gone; the rules are the limit). Code: apps/api/src/payouts/service.ts, apps/api/src/routes/payouts.ts, apps/web/src/money/Payouts.tsx.
  • What PayPal says is the truth. "Paid" comes only from PayPal's payout item webhooks, never from our own guess. We use the item events rather than the batch event, because a successful batch can still hold an unclaimed or returned item. An unknown status or an unknown item is written to the audit log and changes nothing.
  • Proven on the sandbox (Nov 11). A $1.00 prize sent through the app was accepted by PayPal and moved to Paid by PayPal's PAYMENT.PAYOUTS-ITEM webhook. Not yet shown: a receipt claim end to end on the hosted demo. It uses the same payout path and is covered by automated tests against the real executor and rules engine, with PayPal faked.

Bryntum

The Plan screen and Home both show the event's plan in a Bryntum Calendar (trial 7.3.7, React wrapper, thin packages) in apps/web/src/home/: Day and Week on an hour grid, Month as days, read-only, tasks coloured by workstream or by status, event day highlighted. Sponsors show up as they did in the Gantt: a sponsor's invoice task follows that sponsor's status, and each purchase says which sponsor funds it and whether they have paid. The Bryntum Gantt is no longer on any screen (its code stays in apps/web/src/plan/).

  • Each sponsor invoice is a task, live from PayPal. Its bar follows the sponsor's status from GET /api/sponsors: invoiced is in progress, and when PayPal reports the invoice paid (INVOICING.INVOICE.PAID) it turns done, without a reload (the screen re-reads sponsor status every 10 seconds while one is unpaid).
  • Every purchase says which sponsor funds it, and whether that sponsor has paid yet ("Harbor Cloud · not paid yet"). It is a label, not a lock: since Nov 6 the organizer's own PayPal account pays, so a purchase never waits on a sponsor.
  • Red means a delivery problem. At risk is two days or fewer to spare before a deadline; late is past it. Late-delivery recovery (F18/F19) is not built: it is where the agent would move the dependent tasks.
  • Event day is a fixed milestone (a must-start-on constraint), and each purchase with a deadline gets a deadline flag.
  • A real event plan, not a list of payments. Every task has a kind (task, payment or milestone) and a workstream (venue, catering, swag, AV and wifi, printing and signage, photo and video, prizes, speakers and volunteers, sponsors). The planning agent always adds the event-week spine: final confirmations with vendors at T-7, load-in and AV/wifi test and the final rehearsal at T-1, event day, and load-out at T+1, each linked to what it waits on. The Plan screen opens coloured by workstream, with milestones marked ◆ and payments marked $; one click switches to status colours, and late stays red in both.

Plan coloured by workstream, with the event-week milestones

  • One design system. The Calendar's colours use the same status colors as every badge in the app, and its theme (like the earlier Gantt's) is driven from apps/web/src/styles/tokens.css.
What Code
Gantt setup (the earlier plan view; no screen shows it now): columns, bar colors apps/web/src/plan/PlanGantt.tsx
Sponsor labels: which sponsor funds each purchase, invoice tasks from sponsor status apps/web/src/plan/gating.ts
Each event's own tasks from GET /api/events/:id/plan, turned into plan tasks apps/web/src/plan/fromApi.ts
Task model with our status and its funding sponsor apps/web/src/plan/PlanTask.ts
Seeded OpenHack 2027 plan: 22 linked tasks in nine workstreams, with the event-week milestones, three sponsors (pnpm db:seed; tops up an older seeded plan) apps/api/src/db/seed.ts
Task kinds and workstreams: shared contract, workstream labels and colours packages/shared/src/plan.ts, apps/web/src/plan/workstreams.ts
Theme overrides from design tokens apps/web/src/plan/gantt-theme.css
Plan page: the Calendar, coloured by workstream or by status apps/web/src/pages/Plan.tsx

In this screenshot Lumen Labs has paid, so its invoice task is done and "Buy prizes" shows it as paid for. Harbor Cloud and Pixel Foundry are invoiced and not paid yet:

Plan: each purchase names the sponsor that funds it

Status: each event's tasks come from its plan endpoint (the planning agent writes them, and the demo event is seeded), and sponsor status is live. Not built: tracking dates (F18) and late-delivery recovery (F19), where the agent would move dependent tasks when a delivery runs late.

Agent loop

The agent chat is a tool loop, not a single completion. An orchestrator agent writes a checklist for the organizer's goal, works through it with tools, and stops when every item is done or blocked. The checklist is saved as a mandate in Postgres (Supabase), so it survives reloads.

Piece Code
Orchestrator (read, checklist, delegate) apps/api/src/agents/orchestrator.ts
Planning subagent (its PRD §7 tools only) apps/api/src/agents/planning.ts, tools/
Streaming chat route + rate limit apps/api/src/routes/chat.ts
Schema, migrations, seed apps/api/src/db/schema.ts, apps/api/drizzle/, seed.ts
Web chat with live checklist apps/web/src/chat/AgentChat.tsx

Setup: set DATABASE_URL (Supabase session pooler, port 5432), then pnpm --filter @leonid/api db:migrate && pnpm --filter @leonid/api db:seed.

Safety: no agent tool moves money. A payment starts from an organizer action (agreeing to a venue plan, sending a prize, reviewing a claim) or from the receipt reader, and always passes check() in the executor. Every tool call writes an audit_log row with its input and a one-sentence reason.

Differs from the PRD: the database is Supabase Postgres instead of Render Postgres, and the orchestrator is a sixth agent (it holds no money tools). Update the PRD to match.

Render

The app is one Render web service: the Express API also serves the built web app, so there is a single URL. Postgres is Supabase, not Render Postgres.

  • Blueprint: render.yaml declares the service (Node 22, health check /api/health, build with pnpm, pnpm start). Every secret is sync: false: its name is in the file and the value is entered in the Render dashboard, never committed. The same names are in .env.example.
  • Migrations: render.yaml declares pnpm --filter @leonid/api db:migrate as the pre-deploy command. The hosted demo service was created by hand and its database predates that bookkeeping, so its migrations are applied by hand, in one transaction after a dry run.
  • Hosting: the leonid service deploys automatically from the main branch on a paid Render web service, so it does not sleep. Its address is still quartermaster-staging.onrender.com: Render does not change an address after a service is created, and PayPal has it registered. Every PayPal beat described below was rehearsed on it against the PayPal sandbox.
  • Webhooks: each PayPal app has its own webhook, delivered to /api/webhooks/paypal/:app on the service URL. Every event is verified with PayPal's verify-webhook-signature before any handler runs (PAYPAL_WEBHOOK_VERIFY=true). Handlers act on INVOICING.INVOICE.PAID and PAYMENT.CAPTURE.COMPLETED (ledger income), PAYMENT.CAPTURE.REFUNDED and PAYMENT.CAPTURE.REVERSED (income reversals), CHECKOUT.ORDER.APPROVED (backup capture of a treasurer-approved order), and the payout events PAYMENT.PAYOUTS-ITEM.* and PAYMENT.PAYOUTSBATCH.DENIED (claim and prize status); the ledger writes are idempotent on the PayPal capture or invoice id because PayPal retries deliveries.
  • One instance only: the funds check and the spend it writes are serialized in-process, so the service must not be scaled past one instance.
  • Render Workflows (beta): a separate Workflow service runs the background jobs in apps/workflows. budget-recompute lists the events and runs recompute-event for each one in parallel, each retried up to three times. The work itself happens in the API's /api/jobs/* endpoints, behind a secret of their own, so the audit log and the ledger stay in one place and a task holds no PayPal credentials. A treasurer starts it by hand with POST /api/workflows/budget-recompute/run (apps/api/src/routes/workflows.ts). Proven on staging on Nov 5: one run recomputed five events in parallel and wrote five workflow.budget_recompute audit rows plus one workflow.trigger row; for the demo event it found $3,023.85 cleared, $1,400.00 committed and $1,623.85 unlocked. The recompute is a snapshot, since the unlocked budget is derived from the ledger on every read. invoice-reminders works the same way: it lists the sponsors whose invoice is out and unpaid, then runs remind-sponsor for each in parallel. For each one the API asks PayPal for the live invoice status and only then asks PayPal to email a reminder (POST /v2/invoicing/invoices/{id}/remind), so a sponsor who has just paid is never nagged, and a sponsor is reminded at most once per 24 hours (apps/api/src/invoices/remind.ts). Start it with POST /api/workflows/invoice-reminders/run. Proven on staging on Nov 5: a sandbox invoice for the bronze sponsor ($2,500) was sent, one run reminded that sponsor, and the audit log shows invoice.create, invoice.sent, workflow.trigger and invoice.reminder for the same PayPal invoice. sponsor-reports builds each paying sponsor's spend report (F22): it lists the sponsors that have paid and runs report-sponsor for each in parallel (apps/api/src/reports/). The numbers are computed by code from the ledger and the executor's records, never by a model: a spend funded by one sponsor counts in full for that sponsor, and every other spend is paid from the pooled cleared income, each source paying its proportional share (cents split by the largest-remainder method), so a sponsor is never attributed more than it paid in. A model may only phrase a short summary from those figures: its output is held to plain text with no links or addresses and no number that was not supplied, otherwise a template is used, and the page says when an AI wrote it. Payments to people appear only inside category totals, never by name. The report is published at a stable, unguessable link read by the public /report/:shareToken page, and the treasurer gets the link from GET /api/reports/link/:sponsorId. Start it with POST /api/workflows/sponsor-reports/run. Proven on staging on Nov 5: one run published Harbor Cloud's report ($3,000.00 received; $1,384.67 attributed across four purchases, checked by hand against the ledger: its $3,000.00 is 98.9% of the event's $3,033.21 cleared income, and 98.9% of the $1,400.00 spent is $1,384.67), the public page rendered it with each purchase's PayPal ID, and the AI summary passed the output checks. The figures come from the ledger and the executor's records, and each purchase is then checked against PayPal's own transaction records with Transaction Search (apps/api/src/paypal/search.ts, apps/api/src/reports/crosscheck.ts): it is "confirmed" only when PayPal lists a successful payment of exactly that amount and nothing tied to it took money back (a refund or reversal makes it "differs"), and "not in PayPal's records yet" is not an accusation, because Transaction Search can take about three hours to list a payment. The check found a real mismatch on its first live run: three approved purchases were stored under their order id while PayPal lists the capture id, so the report now shows and checks the capture id the executor recorded when the approval was captured. After that fix a rerun on staging confirmed all four of Harbor Cloud's purchases against PayPal (paypalCheck 4 confirmed, 0 differ, 0 not found). The other jobs in the PRD (delivery check, payout batch) are not built yet: the delivery check has no tracking data to read, and the payout batch waits on the claims code.
  • Demo wallet pool: the hosted demo is shared, and a reset must not need a person to log in to PayPal each time. So a few wallet tokens are approved ahead of time (POST /api/wallet/pool/fill makes the approval links, with permit_multiple_payment_tokens: true) and kept on standby in the demo_token_pool table. A standby token is never charged: the only way one becomes the agent's wallet is POST /api/wallet/pool/reset, a treasurer action, which first runs the normal kill switch (deletes the current token at PayPal) and then activates the oldest standby token in one transaction. With an empty pool, reset refuses and changes nothing. POST /api/wallet/pool/end deletes every standby token at PayPal when the demo is over. The normal connect flow is unchanged (one token per payer), and the standby tokens are the one place a token exists that the kill switch of the active wallet does not delete, which is why end exists. Proven on staging on Nov 5: three links were approved as the sandbox Personal account and became three standby tokens; reset activated the first; a second reset deleted that token at PayPal (404 on a direct read afterwards), activated the next, and the last standby token still existed at PayPal; the audit log shows wallet.revoke and wallet.pool_reset. PayPal gave each approved link its own token with its own customer id.
  • Demo switches: DEMO_LOGIN gives judges without a PayPal account a treasurer session. In production it also needs DEMO_LOGIN_ALLOW_PRODUCTION and a judge access code (DEMO_LOGIN_CODE, at least 8 characters, kept out of the repo), and the server logs a loud warning while it is on. A demo session cannot fill or end the shared wallet pool, and it can reset the pool only when the wallet is not active: Restore demo wallet in Settings switches on a spare wallet after a judge has revoked the shared one. Demo login is on for the judging window. DEMO_SPEND (a sandbox spend button for rehearsals) is off.

What was proven on the hosted demo with the real sandbox (Nov 2, when the demo rules still had a $200 approval threshold, which was removed on Nov 9): a $140 swag spend paid automatically from the saved wallet; a $420 spend stopped for approval and was captured after the treasurer approved it in PayPal's popup; after the kill switch deleted the vault token, a further spend was refused and PayPal itself answered 404 TOKEN_NOT_FOUND for the deleted token. The rules in that run are a hard-coded list (apps/api/src/rules/demoRules.ts); the rules compiler (F8) is not built yet.

APIMatic

We use the APIMatic Context Plugin (context-matic@apimatic, MCP server context-matic) in Claude Code to check PayPal request shapes. Only calls the plugin actually answered are listed. The PayPal client code in apps/api/src/paypal/ was written before the plugin was running on this machine, so the entries below are a cross-check of that code, not its origin.

Date Tool Prompt or query What it returned Files checked
2026-10-29 fetch_api (typescript, paypal) paypal One API, "PayPal Server SDK": Orders, Payments, US-only Vault, Transaction Search, Subscriptions n/a
2026-10-29 ask Log in with PayPal: authorization URL, code-for-token exchange, /v1/identity/oauth2/userinfo Not covered. The SDK documents only the client-credentials grant; no Identity or userinfo endpoint F1 (apps/api/src/auth/), see note below
2026-10-29 ask How do I create a Vault setup token for a PayPal wallet? VaultController.createSetupToken with paymentSource.paypal; SDK @paypal/paypal-server-sdk@2.0.0 apps/api/src/paypal/vault.ts
2026-10-29 model_search VaultPaypalWalletRequest, PaypalWalletExperienceContext Confirms every field we send exists: usageType, customerType, permitMultiplePaymentTokens, experienceContext.returnUrl/cancelUrl, shippingPreference, userAction, vaultId. Optional usagePattern is one we do not send vault.ts, orders.ts
2026-10-29 endpoint_search userinfo, RequestToken No Identity endpoint. Returned unrelated Orders, Payments, Subscriptions, Transaction Search and Vault methods n/a
2026-11-01 model_search PurchaseUnitRequest Which order field can carry our event id. customId is the "API caller-provided external ID… used to reconcile transactions… appears in transaction and settlement reports"; referenceId is the purchase unit's id (ours already); invoiceId must be unique per merchant account. Decision: the event id goes in custom_id. The related Order.links text also says an order opened without the PayPal button needs a return_url, or the payer sees an error page after approving; this matches the loop we saw on a manually opened approval link (not yet proven to be the cause); the Approvals page uses PayPal's button instead apps/api/src/paypal/orders.ts, spend.ts
2026-11-02 ask How do I create an order with intent CAPTURE for a buyer who approves with the PayPal JS SDK button, with purchase_units custom_id and a fixed amount, and then capture it from the server? OrdersController.createOrder with intent: CheckoutPaymentIntent.Capture and purchaseUnits[].customId + amount; return the order id to the PayPal JS SDK button; after the buyer approves, call OrdersController.captureOrder with the same order id. Confirms the F6 flow: the server creates (and prices) the order, the button only approves it, the server captures apps/api/src/routes/checkout.ts, apps/api/src/paypal/income.ts, apps/web/src/checkout/PayButtons.tsx
2026-11-02 model_search PurchaseUnitRequest (again, for F6) Same finding as 2026-11-01: customId carries our qm:<eventId>:ticket or qm:<eventId>:donation tag and is returned on the order and its capture, so the webhook can credit the right event. amount must be positive apps/api/src/paypal/orders.ts, apps/api/src/routes/checkout.ts
2026-11-05 ask What does permit_multiple_payment_tokens do when creating a vault setup token? When true, PayPal can create multiple payment tokens for the same payer and merchant or platform combination, including separate tokens for different customers who share one PayPal account. It lives on the PayPal wallet request of CreateSetupToken (VaultPaypalWalletRequest). Matches what we saw at PayPal: two approvals by one payer gave two live tokens with different customer ids, and deleting one left the other alive apps/api/src/paypal/vault.ts (permitMultipleTokens), apps/api/src/routes/walletPool.ts
2026-11-05 endpoint_search getPaymentToken VaultController.getPaymentToken(id): reads one payment token; 404 when it does not exist, 403 without permission. This is the read we use to confirm that a deleted token is gone and a standby token still exists (GET /v3/vault/payment-tokens/{id}) the pool checks in the Nov 5 staging run (a throwaway script, not committed)
2026-11-05 endpoint_search SearchTransactions TransactionSearchController.searchTransactions: GET /v1/reporting/transactions with start_date and end_date (RFC 3339 with seconds; at most 31 days apart), optional transaction_id, fields (transaction_info returns only the transaction details), balance_affecting_records_only, page_size and page. It also says a transaction takes up to three hours to appear, which is why the report words a missing record as "not in PayPal's records yet" apps/api/src/paypal/search.ts, apps/api/src/reports/crosscheck.ts
2026-11-05 model_search TransactionInformation The fields of one listed transaction: transactionId, paypalReferenceId (the related base id), transactionStatus (S success, P pending, D denied, V reversed or refunded in full), transactionAmount and feeAmount as money. We read the id, the reference id, the status and the gross amount apps/api/src/paypal/search.ts

Not answered (the tool returned "An error occurred invoking 'ask'"): a long multi-part Vault question, a long Orders-with-vault_id question, and the short How do I create an order paid with a vaulted PayPal token (vault_id)?. Short single-topic questions worked best.

Gap worth telling APIMatic: the plugin has no coverage of PayPal Identity (Log in with PayPal), which our F1 needs. F1 request shapes therefore come from PayPal's own developer documentation, and the code is not attributed to the plugin.

License

MIT

About

Leonid: the EO’s best friend.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages