Skip to content
edycutjongPublic

About

πŸ›΅ Replace the passport deposit with a PayPal hold. The shop points, the shared baseline answers, PayPal moves only what the renter accepted.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

161 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Jaminan icon β€” a red stamp on the one accepted line, a green stamp releasing the rest of the hold

Jaminan πŸ›΅

A PayPal hold that replaces the passport at the scooter-rental counter. The shop points, the shared baseline answers, and PayPal moves only the money the renter accepted.

Jaminan β€” a PayPal hold instead of your passport. One red stamp for the cracked mirror; one green stamp releases the rest of the hold.

Live Demo Judge Path Landing Page Pitch Deck Demo Video Devpost Write-up X thread Built for PayPal AI Hackathon


Next.js TypeScript FastAPI PayPal Upstash License CI/CD Release

The live judge route on the PayPal sandbox: one tap opens a real $115.00 authorization, Release the hold voids it, and the green RELEASED stamp lands only after PayPal reads back VOIDED.


πŸ’‘ The Problem & Solution

The Problem

In Bali and Jakarta the deposit on a rented scooter is often your passport (or a local's KTP). At return the shop points at a dent, the renter says it was already there, and whoever holds the document wins the argument. Neither side has evidence they both saw, and the "deposit" is a document, not money either side can trust.

The Solution

Jaminan replaces the passport with a PayPal authorization and replaces the argument with a shared walkaround.

What runs today, on the PayPal sandbox: at /app/judge one tap authorizes $115.00 on a saved sandbox wallet, captures the $15.00 fee, writes the handover tracking, and releases the hold on a second tap, each stamp waiting for PayPal's read-back. No vision model is pinned as benchmarked yet, so a live rental cannot price a damage line. The priced path is a recorded sandbox run with scripted claim answers (evidence/paypal-sandbox-run.json: one $18.00 capture with final_capture=true, the other $82.00 released, a second capture refused with 422) and is exercised in the unit and sandbox tests.

  1. The renter scans the shop QR and gives one PayPal approval that authorizes the fee plus the deposit and saves the wallet for later fines. The fee is captured when both sides confirm the baseline at pickup; the deposit stays held.
  2. A guided 8-angle walkaround records the scooter at pickup. Renter and shop confirm the baseline together.
  3. At return the owner points, the shared baseline answers. The shop taps a mark and picks its (part, damage_class) from the published tariff. The model only answers what the pickup photos show; it never sets a price.
  4. Code decides: no mark at return, visible at pickup, or not comparable at pickup all mean cannot be charged, and a mark that doesn't look like the kind the shop named can't be paid from the hold. Only clearly new damage becomes a priced line.
  5. The hold only pays lines the renter accepted. Accepted lines become one capture with final_capture=true. A clean return voids the hold. A contested line goes out as an itemized PayPal invoice at its tariff price.

On AI-generated test images (not photographs): the same crop, model-call and decision steps as the app's claim path, run from a script (one angle, no rental, no close-ups), asked qwen3-vl-plus about two pointed claims on a generated pickup/return pair, three times each, and recorded every answer. It read both wrong. It called the old scuff new: the tariff has no scuff line on the fairing, so the shop named a dent, an over-claim. At the mirror mounts it found no missing mirror, only a smudge elsewhere. No rental or payment was involved, and no line could be priced because no model is benchmarked. The first claim's error, a false "new" on an old mark, is the one the benchmark has to rule out before any model is pinned. Not a benchmark: evidence/generated-pair/.

What the shared baseline can't show, nobody can charge.

πŸ—οΈ Architecture & Tech Stack

Jaminan architecture

Mermaid source
flowchart LR
  R[Renter phone PWA] --> API
  S[Shop phone PWA] --> API
  subgraph API[FastAPI on Vercel Python functions /api/*]
    G[Frame gate: blur + glare] --> V[Vision: pointed claims]
    V --> F[Deterministic filter + tariff]
    F --> L[State machine + ledger]
    L --> PC[paypal.py REST client]
  end
  V --> Q[Qwen on DashScope]
  PC --> PP[(PayPal sandbox)]
  PP -- webhooks --> API
  L --> DB[(Upstash Redis jaminan:*)]
Loading
Layer Technology
UI Next.js 16 PWA (App Router), React 19, TypeScript. Bahasa on shop screens, English on renter screens
API Python 3, FastAPI, httpx, Pydantic, deployed as Vercel Python functions
Frame gate numpy + Pillow: Laplacian-variance blur and clipped-highlight glare checks, no model call to reject a bad frame
Vision Qwen via DashScope (OpenAI-compatible, image input, JSON-schema answer)
Storage Upstash Redis, one JSON document per rental, keys prefixed jaminan:
Jobs One Vercel Cron entry /api/cron/daily (reauth sweep, expiry guard, daily close)

πŸ† PayPal Integration

PayPal is the engine, not a decoration: the deposit is an authorization, and its whole lifecycle is the product. The REST client is hand-written in jaminan/paypal.py.

approve (Orders v2 AUTHORIZE + vault consent)
   β†’ capture fee (final_capture=false)  β†’ tracking on the fee capture
   β†’ claims β†’ renter accepts lines
   β†’ { capture accepted lines (final_capture=true) | void }
   β†’ [reauthorize on day 4 for rentals over 3 days]
   β†’ [invoice: contested lines / damage above the hold]
   β†’ [later fine: merchant-initiated capture on the vaulted wallet]
PayPal surface Used for
Orders v2 AUTHORIZE with store_in_vault one approval: fee + deposit hold + saved wallet
Payments v2 capture (final_capture false/true) fee now, accepted damage lines at settle
Payments v2 void clean return releases the hold
Payments v2 reauthorize re-secures long rentals (Day 4 to Day 29 window)
Vault v3 + merchant-initiated charges later fines on the saved wallet
Shipment tracking handover record on the fee capture; the tracking number carries the first 8 hex characters of the baseline SHA-256
Invoicing v2 contested lines and damage above the hold, with an evidence-pack link
Webhooks v1 and GET /api/integrations/verify events checked with PayPal's verify-webhook-signature call when a webhook id is configured and stored with their verified/failed flag; live read-back of PayPal state

The APIMatic Context Plugin was used once, to write a Transaction Search call through PayPal's generated SDK (docs/APIMATIC.md): the request authenticated and PayPal answered 403 NOT_AUTHORIZED, because the sandbox app lacks permission for Transaction Search (we believe the feature is not enabled). The client itself is hand-written. The settle screen shows the status read back from PayPal after the call. Real-sandbox tests in tests/ cover authorize, vault, capture, void and invoice; tracking, webhooks and fine capture are covered by offline tests. Outside the tests, tracking runs in the recorded sandbox runs and on every /app/judge rental, and incoming webhooks are checked with PayPal's signature call and listed with the result on /app/integrations/verify; the fine capture has no sandbox run.

How this differs

Existing approach What it does What it does not do
AI fleet-inspection products (e.g. Monk, Ravin, ProovStation) Detect damage on vehicle photos Their sites do not describe a payment hold, capture or release, as far as we found
Turo-style photo check-in Both sides photograph the car on a marketplace Tie the photos to an authorization that only accepted lines can capture, as far as we found
A phone video before you ride The renter's own record Carry a co-signature, or get the passport back

πŸ€– For booking agents (MCP)

jaminan/mcp_server.py is a stdio MCP server that lets an agent book a scooter for a person. The agent can look up vehicles, get a price and ask for a booking. Only the renter can pay. The server calls the same service as the app through the live API (/api/shops/{id} and /api/agent/*). It needs mcp and httpx, and no secrets. It runs on the PayPal sandbox.

Tool What it does
list_vehicles(shop_id) Lists the shop's scooters, each with its daily fee and refundable deposit
quote_rental(vehicle_id, days) Returns the fee and deposit, which together make the PayPal hold, plus the tariff version and its SHA-256. The counter uses the same Service.quote()
start_rental(vehicle_id, days, renter_email) Creates the rental and returns a PayPal approve_url for the renter. The rental stays DRAFT, with no hold, until the renter approves
get_rental(rental_id) Read-only. Returns the rental's state and PayPal's own record of it: the order before approval, the authorization after

What an agent cannot do: approve the hold, accept or contest a damage line, capture, void or refund. None of these is a tool. The agent routes also never return the shop or renter key that those actions need. The renter's key reaches the renter only through PayPal's return redirect, after they log in and approve. PayPal's cancel link, which its login page shows to anyone holding the approval link, carries no key. renter_email only pre-fills the PayPal login, and it approves nothing. Bookings are limited to 12 per IP address per hour and 300 per day in all. The judge route has the same limits, counted separately. Bad input gets a one-line error, never a stack trace. All of this holds for any renter's PayPal account. The one deliberate exception is the sandbox /judge route, which holds the project's own pool wallet with no approval so that a judge can try the flow in one tap.

# from the repo root, after the install below
claude mcp add jaminan -e PYTHONPATH="$PWD" -- "$PWD/.venv/bin/python" -m jaminan.mcp_server          # Claude Code
codex mcp add jaminan --env PYTHONPATH="$PWD" -- "$PWD/.venv/bin/python" -m jaminan.mcp_server       # Codex
npx @modelcontextprotocol/inspector --cli -e PYTHONPATH="$PWD" "$PWD/.venv/bin/python" -m jaminan.mcp_server --method tools/list   # MCP Inspector

Recorded on 2026-10-24: Claude Code and Codex each booked through quote_rental β†’ start_rental β†’ get_rental. The sandbox renter approved in PayPal (a script logged in as the sandbox buyer: scripts/mcp_renter_approves.py), and each agent then read back the authorization in a new session: CREATED, for USD 130.00 and USD 145.00. Codex's approval policy blocked start_rental until the operator approved that one tool. list_vehicles and quote_rental, which are annotated read-only, ran without approval. Offline, all 18 write routes under /api/rentals/{id} refuse the agent's token. Live, it gets 403 on the 8 money and answer routes. Transcripts and PayPal ids: evidence/mcp/.

πŸ“Š Engineering Rigor

Metric Value
Tests collected 243 (pytest): 234 offline unit, contract and invariant tests, 8 against the real PayPal sandbox (including CAPTURED and second-capture 422 read-backs), 1 live Qwen schema check; plus 31 Vitest unit tests for the web lib/
Claim-decision sweep decide_claim run over 23,040 combinations of the five yes/no answers, serving model (pinned, other, none), confidence, a confirmed baseline mark, a low-comparability tile, three parts and five damage classes: every chargeable result satisfies every "new since pickup" condition and carries a tariff price (tests/test_invariants.py)
Settle property test up to 3,000 generated settlements (Hypothesis): the hold pays exactly the accepted chargeable lines at their tariff price, blocks exactly when a line is mispriced, or unanswered and the settle is not forced; invoices only contested lines plus any accepted amount above the deposit; and never captures more than the authorization
Offline coverage 100% of jaminan/, line and branch (pytest --cov --cov-branch, 1,692 statements, 500 branches), enforced in CI with --cov-fail-under=100; 100% of the web lib/ under Vitest (npm run test:unit). Two # pragma: no cover: a defensive re-check in rules.settle_plan (rules.py:186) that the line list makes unreachable, and the abstract Store._cmd stub (store.py:18)
CI A six-stage GitHub Actions pipeline (ci.yml): 1 Quality (ruff, mypy, offline tests with a 100% coverage gate; eslint, tsc, Vitest lib/ tests with a 100% gate) and 2 Security (gitleaks over full history, pip-audit, npm audit, licence check) run in parallel, then 3 Build (next build, API boot smoke), 4 E2E (Playwright, no secrets), 5 Performance (Lighthouse CI on / and /pitch, every category β‰₯ 0.9, a11y β‰₯ 0.95) and 6 Deploy gate (every stage green; Vercel deploys only after it). Also gitleaks as its own workflow; CodeQL (Python and TypeScript); GitHub secret scanning with push protection; Dependabot monthly, grouped, no major bumps
Live acceptance script scripts/e2e_live.py (375 px viewport)
Evidence pack evidence/: three recorded PayPal sandbox settlements call by call (scripts/record_paypal_evidence.py), the full test run, offline coverage and the live e2e log
Vision accuracy No benchmark yet. The benchmark on a staged scooter set is pending. So far the model has been shown on AI-generated test images (not photographs) (recorded answers) and in the partial check on public photos below, which it failed
Vision (partial, public single photos) FAIL. 48 Wikimedia Commons photos, the same photo as pickup and return: qwen3-vl-plus called an old mark "new" in 71 of 105 answers and a clean spot "new" in 66 of 66 (bar: 0 for both). One photo with 2 marks failed the blur gate and was not scored, so 35 marks Γ— 3 = 105. The damage class matched the label in 36 of 105 readings. p50 2,703 ms, p95 8,601 ms. Labels drawn by the builder's agent (Claude), not an independent annotator. Not the staged-set benchmark, and it does not test new damage between two photos of one vehicle or real shop conditions (report)

Honest limits (9)

  1. Sandbox only. Nothing here has moved live money; live vault and merchant-initiated eligibility are unverified.
  2. One merchant. The demo uses a single sandbox merchant; a production path needs one onboarded merchant per shop.
  3. Wallet path only. The card-path authorize answered 422 on 2026-10-14 without a stated reason (PayPal's response gave none; we believe advanced card processing is not enabled for this Indonesia-region sandbox merchant), so cards are out of scope.
  4. Non-return is out of scope. Jaminan covers damage and fines, not a scooter that never comes back.
  5. No vision accuracy claim yet. Until the benchmark runs, no finding from a non-benchmarked model is chargeable.
  6. Reauthorize is proven on the sandbox, not yet through the rental flow. On 2026-10-23 (day 9) PayPal accepted reauthorize on a plain hold and on a hold that already had its fee captured (201 both), and refused a second one on the same hold (422 REAUTHORIZATION_TOO_SOON, "only allowed once"): evidence/paypal-reauthorize.jsonl. The sweep's day-4 trigger rule and its refusal fallback (re-authorize on the vaulted wallet, then void the old hold) are unit-tested, including through cron_daily(); the /api/cron/daily route and Vercel's schedule have not run on a rental, and no rental has yet reached day 4 through the app.
  7. The model has not been benchmarked on the staged scooter set. Its recorded answers on the AI-generated test pair (not photographs, evidence/generated-pair/) are not a benchmark, and the one check on real photos is partial and failed (limit 9).
  8. An agent booking ends at the hold. The shop phone opens only the rentals it created, because it holds their key, and no shop login exists yet, so nobody can hand over or release a hold an agent booked. PayPal lets that hold lapse after 29 days (sandbox only).
  9. The vision model fails a partial check on public photos. Given the same real photo as pickup and return, qwen3-vl-plus called old marks and clean spots "new" in 71 of 105 and 66 of 66 answers (evidence/public-photo-bench/). No model is pinned, so those answers charge nothing. Pinning one needs a fix and a passing staged-set benchmark first.

πŸš€ Getting Started

Prerequisites

Node 22 (the version CI uses), Python 3.12, a PayPal sandbox app, an Upstash Redis REST database and a Qwen (DashScope) key. Copy the variable names from jaminan/config.py into .env.local.

Installation

git clone https://github.com/edycutjong/jaminan && cd jaminan
npm install && python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
npm run dev:api & npm run dev

Or skip setup: open the live /judge route, which mints a fresh sandbox rental on one tap and lets you release the hold. Priced lines are in the recorded settlements in DEMO.md.

πŸ§ͺ Testing & CI

make ci                                                                       # ruff, mypy, offline tests + coverage, pip-audit, eslint, tsc, build, npm audit
.venv/bin/python -m pytest -m "not sandbox and not live_model and not slow"   # offline suite only
.venv/bin/python -m pytest                                                    # + real sandbox, live Qwen, headless browser (needs credentials)
python scripts/e2e_live.py https://jaminan.edycu.dev/app --shots /tmp/jaminan-e2e   # live acceptance as two phones at 375 px

Commits use Angular prefixes (feat:, fix:, …); the release workflow derives the next semantic version from them β€” see CONTRIBUTING.

The sandbox, live-model and browser tests need credentials, so CI runs the offline suite only (plus 8 Playwright checks on the built app with no credentials); run them yourself with the third command. Tests that pin a fixed defect are named for it. .env.example lists every variable.

πŸ“ Project Structure

app/        Next.js screens: renter (r/), shop (shop/), judge, integrations/verify
api/        FastAPI entry (Vercel Python function)
jaminan/    paypal.py Β· rules.py Β· gate.py Β· vision.py Β· service.py Β· tariff.py Β· store.py Β· mcp_server.py
fixtures/   published tariff, fine ceilings, shop and vehicle seed
tools/label labelling tool for the staged photo set
tests/      unit, contract, invariant and real-sandbox tests
.github/    CI, CodeQL, gitleaks, Dependabot, community files

πŸ—ΊοΈ Roadmap

  • PayPal lifecycle: authorize, capture, void, vault, invoice, tracking
  • Pointed-claim rules in code, tariff-priced
  • Judge route with a fresh sandbox rental
  • Vision benchmark on a staged scooter set
    • Partial check on public single photos (Wikimedia Commons): run once, fails both 0-false-"new" bars (report)
  • Reauthorize sandbox run (2026-10-23: 201 on two holds, second attempt 422)
  • MCP rental tool for booking agents (evidence/mcp/)

πŸ“½οΈ Demo Materials

πŸ“„ License

MIT

About

πŸ›΅ Replace the passport deposit with a PayPal hold. The shop points, the shared baseline answers, PayPal moves only what the renter accepted.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages