@mercuryo-ai/magicpay-cli 0.1.0

package/dist/commands/poll-secret.js

@@ -0,0 +1,87 @@
+import { describeSecretRequestStatus } from '@mercuryo-ai/magicpay-sdk/core';
+import { exportRunStepToOtlpHttpJsonBestEffort } from '../otel-exporter.js';
+import { serializeSecretRequest } from '../request-output.js';
+import { finishRunStep, startRunStep } from '../run-store.js';
+import { getMagicPayClient } from '../secret-backend.js';
+import { saveSecretRequestSnapshot } from '../secret-state.js';
+import { saveMagicPaySession } from '../workflow-state.js';
+export async function pollSecret(session, requestId) {
+    const step = session.activeRunId
+        ? startRunStep({
+            runId: session.activeRunId,
+            command: 'poll-secret',
+            input: {
+                requestId,
+            },
+            refs: {
+                requestId,
+            },
+        })
+        : null;
+    const finalizeStep = async (result) => {
+        if (step) {
+            finishRunStep({
+                runId: step.runId,
+                stepId: step.stepId,
+                success: result.success,
+                ...('outcomeType' in result && typeof result.outcomeType === 'string'
+                    ? { outcomeType: result.outcomeType }
+                    : {}),
+                ...('message' in result && typeof result.message === 'string'
+                    ? { message: result.message }
+                    : {}),
+                ...('reason' in result && typeof result.reason === 'string'
+                    ? { reason: result.reason }
+                    : {}),
+            });
+            await exportRunStepToOtlpHttpJsonBestEffort(step.runId, step.stepId);
+        }
+        return result;
+    };
+    if (!session.intentSessionId) {
+        return finalizeStep({
+            success: false,
+            error: 'workflow_session_required',
+            outcomeType: 'blocked',
+            message: 'Protected secret request polling failed because no active workflow session is bound to this browser.',
+            reason: 'Run `magicpay start-session` first so MagicPay has a workflow session for protected requests.',
+            requestId,
+        });
+    }
+    const client = getMagicPayClient();
+    const result = await client.secrets.poll(session.intentSessionId, requestId);
+    if (!result.success) {
+        if (result.kind === 'other') {
+            return finalizeStep({
+                success: false,
+                error: 'secret_request_lookup_failed',
+                outcomeType: 'blocked',
+                message: 'Protected secret request polling failed because MagicPay did not return a usable request state.',
+                reason: result.reason,
+                requestId,
+            });
+        }
+        return finalizeStep({
+            success: false,
+            error: 'secret_request_not_found',
+            outcomeType: 'blocked',
+            message: 'Protected secret request lookup failed because the requested request does not exist.',
+            reason: result.reason,
+            requestId,
+        });
+    }
+    const snapshot = saveSecretRequestSnapshot(session, result.result.snapshot);
+    session.currentRequestId = result.result.session.currentRequestId ?? undefined;
+    session.lastKnownStatus = result.result.session.status;
+    session.lastEventSeq = result.result.session.lastEventSeq;
+    saveMagicPaySession(session);
+    const statusContract = describeSecretRequestStatus(snapshot.status, snapshot.requestType);
+    return finalizeStep({
+        success: true,
+        ...serializeSecretRequest(snapshot),
+        ...(statusContract.outcomeType ? { outcomeType: statusContract.outcomeType } : {}),
+        message: statusContract.message,
+        reason: statusContract.reason,
+        ...(statusContract.nextAction ? { nextAction: statusContract.nextAction } : {}),
+    });
+}

package/dist/commands/request-secret.d.ts

@@ -0,0 +1,15 @@
+import { type MagicPaySession } from '../workflow-state.js';
+export type RequestSecretResult = ({
+    success: true;
+} & Record<string, unknown>) | {
+    success: false;
+    error: 'workflow_session_required' | 'unknown_fill_ref' | 'fillable_form_absent' | 'secret_request_host_resolution_failed' | 'stored_secret_not_available_for_fill_ref';
+    outcomeType: 'blocked';
+    message: string;
+    reason: string;
+    fillRef?: string;
+    storedSecretRef?: string;
+    fillableFormPresence?: 'present' | 'unknown' | 'absent';
+};
+export declare function requestSecret(session: MagicPaySession, fillRef: string, storedSecretRef: string, merchantName: string): Promise<RequestSecretResult>;
+//# sourceMappingURL=request-secret.d.ts.map

package/dist/commands/request-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-secret.d.ts","sourceRoot":"","sources":["../../src/commands/request-secret.ts"],"names":[],"mappings":"AAcA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEjF,MAAM,MAAM,mBAAmB,GAC3B,CAAC;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC7C;IACE,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EACD,2BAA2B,GAC3B,kBAAkB,GAClB,sBAAsB,GACtB,uCAAuC,GACvC,0CAA0C,CAAC;IAC/C,WAAW,EAAE,SAAS,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CACzD,CAAC;AAmEN,wBAAsB,aAAa,CACjC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAkM9B"}

package/dist/commands/request-secret.js

@@ -0,0 +1,235 @@
+import { buildRequestInputForObservedForm } from '@mercuryo-ai/magicpay-sdk/agentbrowse';
+import { describeSecretRequestStatus, resolveSecretCatalogContext, } from '@mercuryo-ai/magicpay-sdk/core';
+import { exportRunStepToOtlpHttpJsonBestEffort } from '../otel-exporter.js';
+import { getFillableForm } from '../fillable-form-state.js';
+import { serializeSecretRequest } from '../request-output.js';
+import { finishRunStep, startRunStep } from '../run-store.js';
+import { getMagicPayClient } from '../secret-backend.js';
+import { saveSecretCatalog, saveSecretRequestSnapshot } from '../secret-state.js';
+import { saveMagicPaySession } from '../workflow-state.js';
+function fillableFormPresencePayload(fillableForm) {
+    return {
+        fillableFormPresence: fillableForm.presence ?? 'present',
+    };
+}
+function formatUnknownError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object') {
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return Object.prototype.toString.call(error);
+        }
+    }
+    return String(error);
+}
+async function ensureCatalogForForm(session, fillableForm) {
+    const pageState = session.runtime?.pages?.[fillableForm.pageRef];
+    const pageUrl = pageState?.url;
+    if (!pageUrl) {
+        return {
+            catalog: null,
+            host: null,
+        };
+    }
+    const { host, catalog: cached } = resolveSecretCatalogContext(session.secretCatalogByHost, pageUrl);
+    if (cached) {
+        return {
+            catalog: cached,
+            host,
+        };
+    }
+    if (!session.intentSessionId) {
+        return {
+            catalog: null,
+            host,
+        };
+    }
+    const snapshot = await getMagicPayClient().secrets.fetchCatalog(session.intentSessionId, pageUrl);
+    saveSecretCatalog(session, snapshot);
+    saveMagicPaySession(session);
+    return {
+        catalog: snapshot,
+        host,
+    };
+}
+export async function requestSecret(session, fillRef, storedSecretRef, merchantName) {
+    const step = session.activeRunId
+        ? startRunStep({
+            runId: session.activeRunId,
+            command: 'request-secret',
+            input: {
+                fillRef,
+                storedSecretRef,
+                merchantName,
+            },
+            refs: {
+                pageRef: session.runtime?.currentPageRef,
+                fillRef,
+            },
+        })
+        : null;
+    const finalizeStep = async (result) => {
+        if (step) {
+            finishRunStep({
+                runId: step.runId,
+                stepId: step.stepId,
+                success: result.success,
+                ...('outcomeType' in result && typeof result.outcomeType === 'string'
+                    ? { outcomeType: result.outcomeType }
+                    : {}),
+                ...('message' in result && typeof result.message === 'string'
+                    ? { message: result.message }
+                    : {}),
+                ...('reason' in result && typeof result.reason === 'string'
+                    ? { reason: result.reason }
+                    : {}),
+            });
+            await exportRunStepToOtlpHttpJsonBestEffort(step.runId, step.stepId);
+        }
+        return result;
+    };
+    try {
+        if (!session.intentSessionId) {
+            return finalizeStep({
+                success: false,
+                error: 'workflow_session_required',
+                outcomeType: 'blocked',
+                message: 'Protected secret request was not created because no active workflow session is bound to this browser.',
+                reason: 'Run `magicpay start-session` first so MagicPay has a workflow session for protected requests.',
+                fillRef,
+                storedSecretRef,
+            });
+        }
+        const fillableForm = getFillableForm(session, fillRef);
+        if (!fillableForm) {
+            return finalizeStep({
+                success: false,
+                error: 'unknown_fill_ref',
+                outcomeType: 'blocked',
+                message: 'Protected secret request was not created because the requested fill reference is unknown.',
+                reason: 'The provided fillRef does not match any currently observed protected fill target.',
+                fillRef,
+                storedSecretRef,
+            });
+        }
+        if (fillableForm.presence === 'absent') {
+            return finalizeStep({
+                success: false,
+                error: 'fillable_form_absent',
+                outcomeType: 'blocked',
+                message: 'Protected secret request was not created because the requested fill target is no longer present on the page.',
+                reason: 'MagicPay CLI already observed this protected fill target as absent, so a new observe pass is required before requesting a secret.',
+                fillRef,
+                storedSecretRef,
+                ...fillableFormPresencePayload(fillableForm),
+            });
+        }
+        let catalogHost = null;
+        let catalog = null;
+        try {
+            const resolved = await ensureCatalogForForm(session, fillableForm);
+            catalog = resolved.catalog;
+            catalogHost = resolved.host;
+        }
+        catch {
+            catalog = null;
+            catalogHost = null;
+        }
+        if (!catalogHost) {
+            return finalizeStep({
+                success: false,
+                error: 'secret_request_host_resolution_failed',
+                outcomeType: 'blocked',
+                message: 'Protected secret request was not created because MagicPay CLI could not determine the current site host.',
+                reason: 'The current page URL did not resolve to a usable host for secret request creation.',
+                fillRef,
+                storedSecretRef,
+                ...fillableFormPresencePayload(fillableForm),
+            });
+        }
+        const pageState = session.runtime?.pages?.[fillableForm.pageRef];
+        const client = getMagicPayClient();
+        const requestInput = buildRequestInputForObservedForm({
+            sessionId: session.intentSessionId,
+            merchantName,
+            fillableForm,
+            storedSecretRef,
+            catalog,
+            urlOrHost: pageState?.url ?? catalogHost,
+            page: {
+                ref: fillableForm.pageRef,
+                ...(pageState?.url ? { url: pageState.url } : {}),
+                ...(pageState?.title ? { title: pageState.title } : {}),
+            },
+        });
+        if (!requestInput.success) {
+            if (requestInput.kind === 'host_resolution_failed') {
+                return finalizeStep({
+                    success: false,
+                    error: 'secret_request_host_resolution_failed',
+                    outcomeType: 'blocked',
+                    message: 'Protected secret request was not created because MagicPay CLI could not determine the current site host.',
+                    reason: requestInput.reason,
+                    fillRef,
+                    storedSecretRef,
+                    ...fillableFormPresencePayload(fillableForm),
+                });
+            }
+            return finalizeStep({
+                success: false,
+                error: 'stored_secret_not_available_for_fill_ref',
+                outcomeType: 'blocked',
+                message: 'Protected secret request was not created because this stored secret is not available for the requested fill target.',
+                reason: 'The provided storedSecretRef is not a candidate for the requested protected fill target.',
+                fillRef,
+                storedSecretRef,
+                ...fillableFormPresencePayload(fillableForm),
+            });
+        }
+        const created = await client.secrets.createRequest(requestInput.input);
+        if (requestInput.catalog && requestInput.catalog !== catalog) {
+            saveSecretCatalog(session, requestInput.catalog);
+        }
+        const snapshot = saveSecretRequestSnapshot(session, created.snapshot);
+        session.currentRequestId = created.session.currentRequestId ?? undefined;
+        session.lastKnownStatus = created.session.status;
+        session.lastEventSeq = created.session.lastEventSeq;
+        saveMagicPaySession(session);
+        const statusContract = describeSecretRequestStatus(snapshot.status, snapshot.requestType);
+        const reasonPrefix = created.reused
+            ? 'MagicPay CLI reused an existing secret request for this fill target.'
+            : 'MagicPay CLI created a new secret request for this fill target.';
+        return finalizeStep({
+            success: true,
+            ...fillableFormPresencePayload(fillableForm),
+            ...serializeSecretRequest(snapshot),
+            reused: created.reused,
+            ...(created.duplicate ? { duplicate: true } : {}),
+            ...(statusContract.outcomeType ? { outcomeType: statusContract.outcomeType } : {}),
+            message: statusContract.message,
+            reason: `${reasonPrefix} ${statusContract.reason}`,
+            ...(statusContract.nextAction ? { nextAction: statusContract.nextAction } : {}),
+        });
+    }
+    catch (error) {
+        if (step) {
+            finishRunStep({
+                runId: step.runId,
+                stepId: step.stepId,
+                success: false,
+                outcomeType: 'secret_request_failed',
+                message: 'Protected secret request failed.',
+                reason: formatUnknownError(error),
+            });
+            await exportRunStepToOtlpHttpJsonBestEffort(step.runId, step.stepId);
+        }
+        throw error;
+    }
+}

package/dist/commands/screenshot.d.ts

@@ -0,0 +1,4 @@
+import { type BrowserSessionState, type ScreenshotResult } from '@mercuryo-ai/agentbrowse';
+export type { ScreenshotResult };
+export declare function screenshot(session: BrowserSessionState, filePath?: string): Promise<ScreenshotResult>;
+//# sourceMappingURL=screenshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/commands/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC,wBAAsB,UAAU,CAC9B,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAQ3B"}

package/dist/commands/screenshot.js

@@ -0,0 +1,11 @@
+import { screenshot as screenshotPrimitive, } from '@mercuryo-ai/agentbrowse';
+import { saveMagicPaySession } from '../workflow-state.js';
+export async function screenshot(session, filePath) {
+    const initialPageRef = session.runtime?.currentPageRef;
+    const result = await screenshotPrimitive(session, filePath);
+    const currentPageRef = session.runtime?.currentPageRef;
+    if (result.success || currentPageRef !== initialPageRef) {
+        saveMagicPaySession(session);
+    }
+    return result;
+}

package/dist/commands/solve-captcha.d.ts

@@ -0,0 +1,19 @@
+export type SolveCaptchaSuccess = {
+    success: true;
+    solved: number;
+    verified: number;
+    unresolved: number;
+    unresolvedCaptchas: string[];
+    detected: number;
+    timedOut: boolean;
+};
+export type SolveCaptchaFailure = {
+    success: false;
+    error: 'captcha_session_required' | 'captcha_not_supported' | 'captcha_solve_failed';
+    outcomeType: 'blocked' | 'unsupported' | 'failed';
+    message: string;
+    reason: string;
+};
+export type SolveCaptchaResult = SolveCaptchaSuccess | SolveCaptchaFailure;
+export declare function solveCaptcha(timeoutSeconds?: number): Promise<SolveCaptchaResult>;
+//# sourceMappingURL=solve-captcha.d.ts.map

package/dist/commands/solve-captcha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-captcha.d.ts","sourceRoot":"","sources":["../../src/commands/solve-captcha.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,0BAA0B,GAAG,uBAAuB,GAAG,sBAAsB,CAAC;IACrF,WAAW,EAAE,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAmC3E,wBAAsB,YAAY,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0DvF"}

package/dist/commands/solve-captcha.js

@@ -0,0 +1,63 @@
+import { supportsCaptchaSolve, } from '@mercuryo-ai/agentbrowse';
+import { solveCaptchasByCdp } from '@mercuryo-ai/captcha-solver';
+import { resolveMagicPayGatewayConfig } from '../gateway.js';
+import { writeInfo } from '../output.js';
+import { loadMagicPayBrowserSession } from '../workflow-state.js';
+const DEFAULT_TIMEOUT_SECONDS = 90;
+const MAX_SOLVE_TIMEOUT_MS = 120_000;
+function buildFailure(error, outcomeType, message, reason) {
+    return {
+        success: false,
+        error,
+        outcomeType,
+        message,
+        reason,
+    };
+}
+function resolveSharedProxy(transport) {
+    return transport?.proxyMode === 'proxy' ? transport.proxy : undefined;
+}
+function buildSuccess(result) {
+    return {
+        success: true,
+        solved: result.solved,
+        verified: result.verified,
+        unresolved: result.unresolved,
+        unresolvedCaptchas: result.unresolvedCaptchas,
+        detected: result.detected,
+        timedOut: result.timedOut,
+    };
+}
+export async function solveCaptcha(timeoutSeconds) {
+    const session = loadMagicPayBrowserSession();
+    if (!session) {
+        return buildFailure('captcha_session_required', 'blocked', 'Captcha solving requires an active browser session.', 'Start a browser session with `magicpay launch` or `magicpay attach <cdp-url>` before running `magicpay solve-captcha`.');
+    }
+    if (!supportsCaptchaSolve(session)) {
+        return buildFailure('captcha_not_supported', 'unsupported', 'The current browser session does not support captcha solving.', 'This session was started without captcha-solving capability.');
+    }
+    const timeoutMs = Math.max(1, timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000;
+    const sharedProxy = resolveSharedProxy(session.transport);
+    let gateway;
+    try {
+        gateway = resolveMagicPayGatewayConfig();
+    }
+    catch (error) {
+        return buildFailure('captcha_solve_failed', 'failed', 'Captcha solving failed.', error instanceof Error ? error.message : String(error));
+    }
+    writeInfo(`[captcha] solve-captcha started (timeout ${Math.ceil(timeoutMs / 1000)}s, endpoint ${session.cdpUrl})`);
+    try {
+        const result = await solveCaptchasByCdp(session.cdpUrl, gateway.apiKey, {
+            timeoutMs,
+            solveTimeoutMs: Math.min(timeoutMs, MAX_SOLVE_TIMEOUT_MS),
+            apiUrl: gateway.apiUrl,
+            proxy: sharedProxy,
+            sharedTransport: Boolean(sharedProxy),
+            onProgress: (message) => writeInfo(message),
+        });
+        return buildSuccess(result);
+    }
+    catch (error) {
+        return buildFailure('captcha_solve_failed', 'failed', 'Captcha solving failed.', error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/commands/start-session.d.ts

@@ -0,0 +1,28 @@
+export type StartSessionSuccessResult = {
+    success: true;
+    runId: string;
+    startedAt: string;
+    browserSessionId: string;
+    intentSessionId: string;
+    lastEventSeq: number;
+    status: string;
+    currentRequestId: string | null;
+    replacedPreviousRun: boolean;
+    profile?: string;
+    pageRef?: string;
+    url?: string;
+    title?: string;
+};
+export type StartSessionFailureResult = {
+    success: false;
+    error: 'browser_session_unavailable' | 'backend_session_start_failed' | 'workflow_session_complete_failed';
+    outcomeType: 'blocked' | 'failed';
+    message: 'Session start failed.';
+    reason: string;
+};
+export type StartSessionResult = StartSessionSuccessResult | StartSessionFailureResult;
+export interface StartSessionOptions {
+    merchantName?: string;
+}
+export declare function startSession(requestedName?: string, options?: StartSessionOptions): Promise<StartSessionResult>;
+//# sourceMappingURL=start-session.d.ts.map

package/dist/commands/start-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-session.d.ts","sourceRoot":"","sources":["../../src/commands/start-session.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EACD,6BAA6B,GAC7B,8BAA8B,GAC9B,kCAAkC,CAAC;IACvC,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG,yBAAyB,CAAC;AAIvF,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA6LD,wBAAsB,YAAY,CAChC,aAAa,CAAC,EAAE,MAAM,EACtB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CA0K7B"}