@mercuryo-ai/magicpay-cli 0.1.1 → 0.1.4

package/README.md

@@ -1,56 +1,76 @@
 # @mercuryo-ai/magicpay-cli
 
-Payment-only MagicPay CLI for session, secrets, and protected-form completion.
+Protected-form CLI for MagicPay sessions, approvals, and one-time secret fills.
 
-`magicpay` is the payment-only MagicPay CLI surface for:
+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`.
 
-- gateway setup and health checks;
-- workflow session lifecycle;
-- secret catalog, request, poll, protected fill, and guarded submit/observe flow;
-- narrow browser attachment and protected-form completion on an already prepared page.
+## Before You Start
 
-## Install
+- 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
+
+## Install And Initialize
+
+```bash
+npm i -g @mercuryo-ai/magicpay-cli@latest
+magicpay init <magicpay-api-key>
+magicpay --version
+magicpay status
+```
+
+## Typical 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.
+
+Example:
+
+```bash
+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:
 
 ```bash
-npm i -g @mercuryo-ai/magicpay-cli
-magicpay --help
+magicpay --version
+magicpay status
 ```
 
-## Current surface
-
-- `init`
-- `status`
-- `attach`
-- `start-session`
-- `end-session`
-- `find-form`
-- `get-secrets-catalog`
-- `request-secret`
-- `mock-approve-secret`
-- `mock-deny-secret`
-- `poll-secret`
-- `fill-secret`
-- `submit-form`
-
-Browser attach happens over CDP:
-
-- `magicpay attach <cdp-url>`
-
-`magicpay fill-secret` now performs a post-fill refresh, auto-submits when it
-can resolve one live form-bound submit control, and returns a follow-up observe
-result when submission happens. `submit-form` remains available as a manual
-recovery surface.
-
-`magicpay status` stays quiet about CLI updates by default. When a newer npm
-release is available, it includes a short English notice and the suggested
-update command.
-
-## Architecture boundary
-
-- `magicpay` is the operator CLI for workflow sessions, approvals, protected
-  secret handling, and narrow form completion on the current page.
-- `@mercuryo-ai/agentbrowse` owns browser primitives and the reusable browser
-  session store API.
-- `@mercuryo-ai/magicpay-sdk` owns reusable MagicPay API and flow helpers.
-- `@mercuryo-ai/magicpay-cli` owns branded payment CLI orchestration and the
-  payment-safe command UX on top of the shared `~/.magicpay` home.
+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.
+
+## 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`
+- Development-only helpers: `mock-approve-secret`, `mock-deny-secret`
+- Manual recovery: `submit-form`
+
+## Choose Another Package When
+
+- You only need browser navigation, observation, or extraction:
+  use `@mercuryo-ai/agentbrowse-cli`
+- You want one CLI for both browser work and protected fills:
+  use `@mercuryo-ai/magicpay-agent-cli`

package/dist/commands/attach.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/commands/attach.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAQlC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;AAE5C,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAO3F"}
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/commands/attach.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAQlC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;AAwB5C,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA6B3F"}

package/dist/commands/attach.js

@@ -1,7 +1,39 @@
 import { attach as attachBrowser, close as closeBrowser, } from '@mercuryo-ai/agentbrowse';
 import { loadMagicPayBrowserSession, loadMagicPaySession, saveMagicPaySession, } from '../workflow-state.js';
+function currentPageMetadata(session) {
+    const runtime = session.runtime;
+    if (!runtime) {
+        return { url: '', title: '' };
+    }
+    const currentPageRef = runtime.currentPageRef;
+    const currentPage = (currentPageRef ? runtime.pages?.[currentPageRef] : undefined) ??
+        Object.values(runtime.pages ?? {})[0];
+    return {
+        url: currentPage?.url ?? '',
+        title: currentPage?.title ?? '',
+    };
+}
 export async function attach(cdpUrl, options) {
-    await closeBrowser(loadMagicPaySession() ?? loadMagicPayBrowserSession());
+    const existingSession = loadMagicPaySession() ?? loadMagicPayBrowserSession();
+    const normalizedCdpUrl = cdpUrl.trim();
+    if (existingSession?.cdpUrl?.trim() === normalizedCdpUrl) {
+        const session = existingSession;
+        const { url, title } = currentPageMetadata(session);
+        saveMagicPaySession(session);
+        return {
+            success: true,
+            runtime: 'attached',
+            session,
+            cdpUrl: session.cdpUrl,
+            url,
+            title,
+            ...(options?.provider ? { provider: options.provider } : {}),
+            captchaSolveCapable: options?.capabilities?.captchaSolve === true ||
+                (session.capabilities?.captchaSolve ===
+                    true),
+        };
+    }
+    await closeBrowser(existingSession);
     const result = await attachBrowser(cdpUrl, options);
     if (result.success) {
         saveMagicPaySession(result.session);

package/dist/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+import { type MagicPayConfigDoctorResult } from '@mercuryo-ai/magicpay-home';
+export declare function doctor(): MagicPayConfigDoctorResult;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAEnG,wBAAgB,MAAM,IAAI,0BAA0B,CAEnD"}

package/dist/commands/doctor.js

@@ -0,0 +1,4 @@
+import { doctorMagicPayConfig } from '@mercuryo-ai/magicpay-home';
+export function doctor() {
+    return doctorMagicPayConfig('magicpay');
+}

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE;QACP,gBAAgB,EAAE,IAAI,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAMD,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAwBhE"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE;QACP,gBAAgB,EAAE,IAAI,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAwBhE"}

package/dist/commands/init.js

@@ -1,14 +1,9 @@
-import { getConfigPath, readConfig, writeConfig } from '../config.js';
+import { getConfigPath, normalizeMagicPayApiUrl, readConfig, writeConfig } from '../config.js';
 import { DEFAULT_MAGICPAY_API_URL } from '../generated/build-config.js';
-function normalizeApiUrl(value) {
-    return value.replace(/\/$/, '');
-}
 export function init(apiKey, apiUrl) {
     const config = readConfig();
     const normalizedApiKey = apiKey.trim();
-    const normalizedApiUrl = apiUrl?.trim()
-        ? normalizeApiUrl(apiUrl.trim())
-        : DEFAULT_MAGICPAY_API_URL;
+    const normalizedApiUrl = normalizeMagicPayApiUrl(apiUrl?.trim() ? apiUrl.trim() : DEFAULT_MAGICPAY_API_URL);
     writeConfig({
         ...config,
         gateway: {

package/dist/config.d.ts

@@ -1,2 +1,2 @@
-export { getMagicPayConfigPath as getConfigPath, getMagicPayHomeDir as getStateDir, readMagicPayConfig as readConfig, writeMagicPayConfig as writeConfig, type MagicPaySharedConfig as MagicPayCliConfig, } from '@mercuryo-ai/magicpay-home';
+export { getMagicPayConfigPath as getConfigPath, getMagicPayHomeDir as getStateDir, normalizeMagicPayApiUrl, readMagicPayConfig as readConfig, writeMagicPayConfig as writeConfig, type MagicPaySharedConfig as MagicPayCliConfig, } from '@mercuryo-ai/magicpay-home';
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,IAAI,aAAa,EACtC,kBAAkB,IAAI,WAAW,EACjC,kBAAkB,IAAI,UAAU,EAChC,mBAAmB,IAAI,WAAW,EAClC,KAAK,oBAAoB,IAAI,iBAAiB,GAC/C,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,IAAI,aAAa,EACtC,kBAAkB,IAAI,WAAW,EACjC,uBAAuB,EACvB,kBAAkB,IAAI,UAAU,EAChC,mBAAmB,IAAI,WAAW,EAClC,KAAK,oBAAoB,IAAI,iBAAiB,GAC/C,MAAM,4BAA4B,CAAC"}

package/dist/config.js

@@ -1 +1 @@
-export { getMagicPayConfigPath as getConfigPath, getMagicPayHomeDir as getStateDir, readMagicPayConfig as readConfig, writeMagicPayConfig as writeConfig, } from '@mercuryo-ai/magicpay-home';
+export { getMagicPayConfigPath as getConfigPath, getMagicPayHomeDir as getStateDir, normalizeMagicPayApiUrl, readMagicPayConfig as readConfig, writeMagicPayConfig as writeConfig, } from '@mercuryo-ai/magicpay-home';

package/dist/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAE3B,MAAM,mCAAmC,CAAC;AA6B3C,wBAAgB,+BAA+B,IAAI,qBAAqB,GAAG,IAAI,CAiB9E;AAED,wBAAgB,4BAA4B,IAAI,qBAAqB,CAMpE;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,CAAC;AAE3D,wBAAsB,qBAAqB,CACzC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GACzC,OAAO,CAAC,mBAAmB,CAAC,CAE9B"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAE3B,MAAM,mCAAmC,CAAC;AAyB3C,wBAAgB,+BAA+B,IAAI,qBAAqB,GAAG,IAAI,CAiB9E;AAED,wBAAgB,4BAA4B,IAAI,qBAAqB,CAMpE;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,CAAC;AAE3D,wBAAsB,qBAAqB,CACzC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GACzC,OAAO,CAAC,mBAAmB,CAAC,CAE9B"}

package/dist/gateway.js

@@ -13,11 +13,8 @@ function trimOrUndefined(value) {
     }
     return trimmed;
 }
-function normalizeApiUrl(value) {
-    return value.replace(/\/$/, '');
-}
 function appendApiPath(apiUrl, suffix) {
-    return `${normalizeApiUrl(apiUrl)}${suffix.startsWith('/') ? suffix : `/${suffix}`}`;
+    return `${apiUrl}${suffix.startsWith('/') ? suffix : `/${suffix}`}`;
 }
 export function tryResolveMagicPayGatewayConfig() {
     const config = readConfig();
@@ -30,7 +27,7 @@ export function tryResolveMagicPayGatewayConfig() {
     }
     return {
         apiKey,
-        apiUrl: normalizeApiUrl(apiUrl),
+        apiUrl,
     };
 }
 export function resolveMagicPayGatewayConfig() {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA0VA,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4HvE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA6VA,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiIvE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}

package/dist/index.js

@@ -3,6 +3,7 @@ import { config as loadEnv } from 'dotenv';
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { attach } from './commands/attach.js';
+import { doctor } from './commands/doctor.js';
 import { endSession } from './commands/end-session.js';
 import { fillSecret } from './commands/fill-secret.js';
 import { findForm } from './commands/find-form.js';
@@ -21,6 +22,7 @@ import { loadMagicPayBrowserSession, loadMagicPaySession, } from './workflow-sta
 loadEnv();
 const KNOWN_COMMANDS = new Set([
     'init',
+    'doctor',
     'status',
     'attach',
     'start-session',
@@ -39,6 +41,7 @@ function usageText() {
 
 Commands:
   init <apiKey> [--api-url <url>] Configure MagicPay gateway access for the payment CLI
+  doctor                         Check persisted MagicPay config and gateway URL
   status                          Check gateway health and authenticated agent identity
   attach <cdp-url> [options]      Attach the payment CLI to an already prepared browser over CDP
   start-session [name] [--merchant-name <name>]
@@ -294,6 +297,10 @@ export async function main(argv = process.argv) {
             outputJSON(init(initArgs.apiKey, initArgs.apiUrl));
             return;
         }
+        case 'doctor': {
+            outputJSON(doctor());
+            return;
+        }
         case 'status': {
             outputJSON(await status());
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercuryo-ai/magicpay-cli",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "MagicPay CLI — payment/session/secrets shell with narrow protected-form completion",
   "type": "module",
   "license": "MIT",
@@ -23,9 +23,31 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MercuryoAI/skills.git"
+  },
+  "homepage": "https://agents.mercuryo.io/docs/agents",
+  "bugs": {
+    "url": "https://github.com/MercuryoAI/skills/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
+  "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"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.18"
+  },
   "scripts": {
     "build:config:dev": "node scripts/write-build-config.mjs https://durcottggsiesxxqzvbb.supabase.co/functions/v1/api",
     "build:config:prod": "node scripts/write-build-config.mjs https://agents-api.mercuryo.io/functions/v1/api",
@@ -40,19 +62,5 @@
     "test:unit:bare": "MAGICPAY_DISABLE_TELEMETRY=1 vitest run --exclude \"src/__tests__/*.e2e.test.ts\" --exclude \"dist/**\"",
     "test:e2e": "npm run test:deps && npm run test:e2e:bare",
     "test:e2e:bare": "MAGICPAY_DISABLE_TELEMETRY=1 vitest run --no-file-parallelism --maxWorkers=1 src/__tests__/protected-fill.e2e.test.ts"
-  },
-  "dependencies": {
-    "@browserbasehq/stagehand": "^3.0.0",
-    "@mercuryo-ai/captcha-solver": "workspace:*",
-    "@mercuryo-ai/magicpay-sdk": "workspace:*",
-    "@mercuryo-ai/magicpay-home": "workspace:*",
-    "@mercuryo-ai/agentbrowse": "workspace:*",
-    "dotenv": "^16.4.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "5.9.2",
-    "vitest": "^4.0.18"
   }
-}
+}