@mercuryo-ai/magicpay-home

Shared home directory and state contract for the MagicPay CLI family.

This package owns ~/.magicpay/: the on-disk home directory where MagicPay's CLIs keep their config, browser session, workflow state, and related files. It is not a CLI of its own — it is consumed as a dependency by:

• @mercuryo-ai/agentbrowse-cli — browser automation
• @mercuryo-ai/magicpay-cli — protected-form fills
• @mercuryo-ai/magicpay-agent-cli — combined browser + payment agent

Do I Need To Install This?

No. This package is pulled in automatically as a dependency of the CLIs above. You do not need to install or configure it directly.

Why This Package Exists

The underlying browser library @mercuryo-ai/agentbrowse stores its own state in ~/.agentbrowse/ by default. That default is the right behaviour for integrators who embed @mercuryo-ai/agentbrowse into their own product under their own brand.

MagicPay is one such integrator. To keep configuration, browser state, and workflow state together under a single directory, magicpay-home:

1. Defines the MagicPay home directory at ~/.magicpay/.
2. Overrides the @mercuryo-ai/agentbrowse storage hook so the browser library writes into ~/.magicpay/ instead of ~/.agentbrowse/ when any MagicPay CLI is running.
3. Provides typed helpers for the MagicPay-specific files in that same directory (config, workflow state, update-check state, etc.).

If you build your own product on top of @mercuryo-ai/agentbrowse, you can apply the same pattern with your own home directory name.

Directory Layout

All paths are relative to ~/.magicpay/ (or the OS equivalent of homedir() + "/.magicpay/").

| Path | Owner | Purpose | Written by | | --- | --- | --- | --- | | config.json | magicpay-home | Shared config: gateway (apiKey, apiUrl), browser defaults (profile, headless, proxy), updates policy. | init on any CLI. | | browser-session.json | @mercuryo-ai/agentbrowse (via override) | CDP endpoint and browser session state so launch / attach persist across processes. | Every CLI that touches the browser — agentbrowse-cli, magicpay-agent-cli. | | workflow-state.json | magicpay-home | In-flight protected-form workflow state (open-data snapshot, cached transient secrets, current step). | magicpay-cli and magicpay-agent-cli only. | | update-state.json | magicpay-home | Last CLI update-check timestamp and cached result. | Any CLI that runs the update check. | | mock-stored-secrets.json | magicpay-home | Development-only mock vault items. Not used in production. | Only when the CLI is run in mock mode. | | mock-secret-requests.json | magicpay-home | Development-only mock secret-request log. Not used in production. | Only when the CLI is run in mock mode. | | profiles/ | @mercuryo-ai/agentbrowse (via override) | Per-profile browser user-data directories (cookies, localStorage, cache). | launch when a named profile is used. | | runs/ | magicpay-home | Per-run telemetry and artefacts. | Any CLI run that records run telemetry. |

Rules of thumb when debugging:

• Safe to delete to reset auth: config.json. The next init re-creates it.
• Safe to delete to reset the browser session: browser-session.json. Next launch / attach starts fresh.
• Safe to delete to reset an in-flight workflow: workflow-state.json. Any active magicpay / magicpay-agent session is lost; the next start-session begins clean.
• Do not hand-edit any of these files — they are managed by the CLIs and may be rewritten at any moment.

What The Package Provides

• Typed helpers for reading and writing config.json (readMagicPayConfig, writeMagicPayConfig, doctorMagicPayConfig).
• Path helpers for every file and directory above (getMagicPayHomeDir, getMagicPayConfigPath, getMagicPayBrowserSessionPath, etc.).
• Workflow-state helpers for the in-flight protected-form session (loadWorkflowContext, saveWorkflowContext, clearWorkflowState).
• Browser-session helpers (loadMagicPayBrowserSession, saveMagicPayBrowserSession, deleteMagicPayBrowserSession) that also install the @mercuryo-ai/agentbrowse storage override so both packages read and write the same file.
• CLI update-check helper (checkForPackageUpdate) with state persisted in update-state.json.
• Safe concurrent writes so several MagicPay CLIs can run in the same process or side-by-side without corrupting shared files.

License

MIT