jackwener--opencli/docs/adapters/browser/mercury.md

Mercury

Mode: 🔐 Browser · Domain: app.mercury.com

Mercury reimbursements are authenticated browser UI flows. There is no public API and no stable JSON endpoint for creating an expense, so the adapter drives the visible Mercury reimbursements page through OpenCLI Browser Bridge. It creates a draft, uploads a local receipt file, waits for Mercury OCR, then re-applies the agent-provided fields because OCR can overwrite amount, currency, date, or merchant.

The write command is deliberately conservative: it stops at Mercury's Review step and never clicks the final Submit expense button. A human or responsible agent must inspect the Review page before any final submission.

Commands

Command	Description
opencli mercury reimbursement-plan	Validate a reimbursement payload locally without opening Mercury
opencli mercury check-login	Open Mercury reimbursements and report whether the selected browser profile is logged in
opencli mercury reimbursement-draft	Create a reimbursement draft, attach the receipt, correct OCR-overwritten fields, and stop at Review

reimbursement-plan and reimbursement-draft take the same business payload:

Flag	Meaning
--receipt	Absolute or relative path to a local receipt/proof file
--amount	Original-currency positive amount, e.g. 140.00
--currency	Original currency code, default CNY
--date	Expense date as YYYY-MM-DD
--merchant	Merchant name to show in Mercury
--category	Mercury expense category, default Marketing & Advertising
--notes	Business purpose / reimbursement notes
--ocr-wait-seconds	Seconds to wait after receipt upload before reapplying fields, default 8
--close-after-review	Close Review after verification; still never submits

Agent Workflow

# 1. Confirm the selected browser profile is logged into Mercury
opencli --profile <profile> mercury check-login -f json

# 2. Validate the payload locally first
opencli mercury reimbursement-plan \
  --receipt /absolute/path/to/receipt.png \
  --amount 140.00 \
  --currency CNY \
  --date 2026-06-26 \
  --merchant "Example Merchant" \
  --category "Marketing & Advertising" \
  --notes "Example business purpose." \
  -f json

# 3. Create the draft and stop at Review
opencli --profile <profile> mercury reimbursement-draft \
  --receipt /absolute/path/to/receipt.png \
  --amount 140.00 \
  --currency CNY \
  --date 2026-06-26 \
  --merchant "Example Merchant" \
  --category "Marketing & Advertising" \
  --notes "Example business purpose." \
  -f json

Expected Results

For check-login:

• status: "ready" means the profile reached Mercury reimbursements.
• status: "needs_login" means Mercury redirected to login; sign into Mercury in that Chrome/OpenCLI profile and rerun.

For reimbursement-plan:

• status: "ready" means the local receipt exists and amount/date formats are valid.
• Missing receipt files, non-positive amount strings, malformed currency codes, invalid calendar dates, or invalid wait/boolean flags fail before Mercury is opened.
• Output uses the receipt basename, not the absolute local path.

For reimbursement-draft:

• uploaded: true
• reviewReady: true
• submitBlocked: true
• warnings includes final Submit expense was intentionally not clicked
• Mercury shows the Review step with the expected receipt, amount, currency, date, merchant, category, and notes.

If upload confirmation, required field correction, or the Review postcondition fails, the command throws a typed error instead of returning a partial success row. Keep the browser open and inspect Mercury for validation errors.

Testing

Run repository-level checks:

npm run dev -- validate mercury
npm run typecheck
npm run docs:build

Run a local input smoke test:

npm run dev -- mercury reimbursement-plan \
  --receipt /tmp/example-receipt.png \
  --amount 1.00 \
  --currency USD \
  --date 2026-06-30 \
  --merchant "OpenCLI Test Merchant" \
  --category "Office Supplies & Equipment" \
  --notes "OpenCLI adapter smoke test; do not submit." \
  -f json

Run a real UI smoke test only in a test Mercury workspace/profile or with a harmless test receipt:

npm run dev -- --profile <profile> mercury reimbursement-draft \
  --receipt /absolute/path/to/test-receipt.png \
  --amount 1.00 \
  --currency USD \
  --date 2026-06-30 \
  --merchant "OpenCLI Test Merchant" \
  --category "Office Supplies & Equipment" \
  --notes "OpenCLI adapter smoke test; do not submit." \
  -f json

Pass condition: Mercury stops at Review and the returned row has submitBlocked: true. Do not click final Submit during smoke tests.

Notes

• Login is required. This adapter uses the selected OpenCLI browser profile; it does not store Mercury credentials or run an OAuth/login flow.
• Receipt upload targets Mercury's attachment input: [data-testid="expense-attachment-upload"]. If Mercury changes that selector, upload can fail while the rest of the form remains visible.
• OCR happens before correction. Mercury OCR can misread currency (for example CNY as JPY) or overwrite merchant/amount. The command uploads the receipt first, waits, then re-fills fields from the CLI arguments.
• Review is not submission. reimbursement-draft never presses the final Submit expense button. It prepares a draft for inspection.
• Use original currency. Enter the currency shown on the source receipt when Mercury supports it, then verify Mercury's converted reimbursement amount on the Review page.
• Output is intentionally compact. The returned row is a control-plane status summary; Mercury remains the source of truth for final visual review.

Troubleshooting

• needs_login: open Mercury in the same Chrome/OpenCLI profile, finish login, then rerun check-login.
• Upload failure: verify the file exists locally and that Mercury still uses the receipt input selector above. The command requires Browser Bridge uploadFiles support so it can verify the intended file input.
• Review failure: inspect Mercury for validation errors; the command may have uploaded the receipt and filled fields but failed to reach Review.
• Category did not commit: custom Mercury dropdowns can be sensitive to UI changes. Retry with the exact category label visible in Mercury.