@mercuryo-ai/magicpay-cli 0.1.4 → 0.1.6

package/README.md

@@ -1,38 +1,55 @@
 # @mercuryo-ai/magicpay-cli
 
-Protected-form CLI for MagicPay sessions, approvals, and one-time secret fills.
+Protected-form CLI for prepared browser pages.
 
-Choose this package when the browser is already at the correct login, identity,
-or payment form and you want MagicPay to handle the protected part of the flow.
-If you still need browser navigation and page interaction, pair it with
-`@mercuryo-ai/agentbrowse-cli` or use `@mercuryo-ai/magicpay-agent-cli`.
+MagicPay CLI is for the part of a workflow that handles approved stored values
+on a login, identity, or payment form that is already open in the browser.
 
-## Before You Start
+Use it when you need to:
 
-- Node.js 18 or newer
-- A MagicPay account. Create it at `https://agents.mercuryo.io/signup`, then
-  create an API key in the dashboard.
-- A browser page that is already at the protected step you want to complete
+- attach to an already prepared browser page;
+- bind the page to a workflow session;
+- discover the supported protected form;
+- request approval for stored values;
+- fill the approved values through the guarded protected-form flow.
 
-## Install And Initialize
+MagicPay is focused on the protected step itself. Reach the target page first
+with another browsing tool or an existing browser session, then hand the form
+over to MagicPay.
+
+## Install
 
 ```bash
 npm i -g @mercuryo-ai/magicpay-cli@latest
+```
+
+## API Setup
+
+Configure the API key once:
+
+Get an account and API key at `https://agents.mercuryo.io/signup`.
+
+```bash
 magicpay init <magicpay-api-key>
-magicpay --version
 magicpay status
 ```
 
-## Typical Flow
+`magicpay status` is the normal readiness check before a protected-form task.
+Use `magicpay doctor` only when `init` or `status` still fail and you need to
+inspect the local config.
+
+## Core Flow
 
-1. Attach to the already running browser page.
-2. Start a workflow session.
-3. Find the protected form.
-4. Refresh the secrets catalog only if candidates are missing or stale.
-5. Request approval for one secret.
-6. Poll until the request is fulfilled or terminal.
-7. Run `fill-secret`.
-8. Use `submit-form` only as manual recovery if the normal flow still needs it.
+1. `magicpay attach <cdp-url>`
+2. `magicpay start-session [name]`
+3. `magicpay find-form`
+4. `magicpay get-secrets-catalog` only if candidates are missing or stale
+5. `magicpay request-secret <fillRef> <storedSecretRef> --merchant-name <name>`
+6. `magicpay poll-secret <requestId>`
+7. `magicpay fill-secret <fillRef> <requestId>`
+8. `magicpay submit-form <fillRef>` only if the guarded fill flow explicitly
+   leaves submission unfinished
+9. `magicpay end-session` when the protected step is complete
 
 Example:
 
@@ -40,35 +57,38 @@ Example:
 magicpay attach <cdp-url>
 magicpay start-session "Checkout"
 magicpay find-form
-magicpay get-secrets-catalog
 magicpay request-secret <fillRef> <storedSecretRef> --merchant-name "Example Store"
 magicpay poll-secret <requestId>
 magicpay fill-secret <fillRef> <requestId>
 ```
 
-## Verify And Troubleshoot
-
-Use these checks first:
+If `find-form` does not return the right candidates, refresh the catalog and
+retry:
 
 ```bash
-magicpay --version
-magicpay status
+magicpay get-secrets-catalog
+magicpay find-form
 ```
 
-Use `magicpay doctor` only when `init` or `status` still fail and you need to
-inspect the local MagicPay config. `mock-approve-secret` and
-`mock-deny-secret` are development-only helpers, not production approval flows.
+## Operating Rules
+
+- Start from a prepared page, not from generic browser navigation.
+- Use `magicpay status` before a new protected-form task.
+- Re-run `magicpay find-form` after meaningful page changes.
+- Treat `magicpay submit-form` as manual recovery, not as the default happy
+  path.
+- `mock-approve-secret` and `mock-deny-secret` are development-only helpers,
+  not production approval flows.
 
 ## Command Groups
 
 - Setup and diagnostics: `init`, `status`, `doctor`
 - Session control: `attach`, `start-session`, `end-session`
 - Protected form flow: `find-form`, `get-secrets-catalog`, `request-secret`,
-  `poll-secret`, `fill-secret`
+  `poll-secret`, `fill-secret`, `submit-form`
 - Development-only helpers: `mock-approve-secret`, `mock-deny-secret`
-- Manual recovery: `submit-form`
 
-## Choose Another Package When
+## Companion Tools
 
 - You only need browser navigation, observation, or extraction:
   use `@mercuryo-ai/agentbrowse-cli`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mercuryo-ai/magicpay-cli",
-  "version": "0.1.4",
-  "description": "MagicPay CLI — payment/session/secrets shell with narrow protected-form completion",
+  "version": "0.1.6",
+  "description": "Protected-form CLI for prepared browser pages",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -37,10 +37,10 @@
   "dependencies": {
     "@browserbasehq/stagehand": "^3.0.0",
     "dotenv": "^16.4.0",
-    "@mercuryo-ai/magicpay-sdk": "0.1.0-test.5",
-    "@mercuryo-ai/magicpay-home": "0.1.6",
-    "@mercuryo-ai/agentbrowse": "0.2.53",
-    "@mercuryo-ai/captcha-solver": "0.1.1"
+    "@mercuryo-ai/magicpay-sdk": "0.1.0-test.7",
+    "@mercuryo-ai/magicpay-home": "0.1.7",
+    "@mercuryo-ai/agentbrowse": "0.2.54",
+    "@mercuryo-ai/captcha-solver": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",