@itpay/cli 0.2.17 → 2.0.0-rc.1

package/dist/src/commands/order.js

@@ -0,0 +1,78 @@
+// Read a single V3 order by id. Supports terminal text and agent markdown output.
+import { formatMoney, renderOrder } from "../render/output.js";
+import { hintFor } from "../render/status.js";
+import { resolveOutput } from "../render/sink.js";
+import { ensureIdeImageAttach, ideImageAttachBlock } from "../render/ide.js";
+export async function runOrder(backend, orderID, options = {}) {
+    const out = resolveOutput(options.output);
+    const order = await backend.getOrder(orderID);
+    // Prepare an IDE image attach slot. Order responses usually do not
+    // carry a brand QR — the previous buy already produced one. We still
+    // call ensureIdeImageAttach so the disabled / failed / no-source
+    // states get surfaced consistently across commands.
+    const plan = {
+        kind: "checkout_qr",
+        host: (options.host ?? "terminal"),
+        summary: "order presentation",
+        url: "",
+        preferredQRSources: [],
+        platform: {
+            text: "order presentation",
+            links: [],
+            buttons: [],
+            blocks: [],
+        },
+    };
+    await ensureIdeImageAttach(plan, {
+        ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+    });
+    if (options.host === "codex" || options.host === "claude-code" || options.host === "trae") {
+        out(renderOrderMarkdown(order, plan) + "\n");
+    }
+    else {
+        out(renderOrder(order) + "\n");
+        if (plan.ideImageAttach) {
+            out(ideImageAttachBlock(plan.ideImageAttach).filter((l) => l.length > 0).join("\n") + "\n");
+        }
+        out(`hint: ${hintFor("order", order.status)}\n`);
+    }
+}
+function renderOrderMarkdown(order, plan) {
+    const lines = [];
+    lines.push(`## :package: 订单 ${order.order_id}`);
+    lines.push("");
+    const statusEmoji = order.status === "delivered" ? ":white_check_mark:" : order.status === "refunded" ? ":arrows_counterclockwise:" : ":hourglass:";
+    lines.push(`| 字段 | 值 |`);
+    lines.push(`|------|-----|`);
+    lines.push(`| 状态 | ${statusEmoji} ${order.status} |`);
+    lines.push(`| 金额 | ${formatMoney(order.amount_minor, order.currency)} |`);
+    lines.push(`| Checkout | \`${order.checkout_id}\``);
+    if (order.paid_at)
+        lines.push(`| 支付时间 | ${order.paid_at} |`);
+    lines.push("");
+    if (order.items.length > 0) {
+        lines.push(`| 项目 | 数量 | 单价 |`);
+        lines.push(`|------|:----:|------|`);
+        for (const item of order.items) {
+            lines.push(`| ${item.title} | ${item.quantity} | ${formatMoney(item.amount_minor, item.currency)} |`);
+        }
+        lines.push("");
+    }
+    if (order.delivery_artifacts.length > 0) {
+        lines.push(`### :lock: 交付物`);
+        lines.push("");
+        for (const artifact of order.delivery_artifacts) {
+            const notification = artifact.notification_status ? ` — notification:${artifact.notification_status}` : "";
+            const vault = artifact.vault_artifact_id ? ` — vault:\`${artifact.vault_artifact_id}\`` : "";
+            lines.push(`- \`${artifact.delivery_artifact_id}\` — ${artifact.artifact_type} — ${artifact.status}${notification}${vault}`);
+            if (artifact.public_preview)
+                lines.push(`  > ${artifact.public_preview}`);
+        }
+        lines.push("");
+    }
+    if (plan.ideImageAttach) {
+        lines.push(...ideImageAttachBlock(plan.ideImageAttach));
+    }
+    lines.push(`> :bulb: ${hintFor("order", order.status)}`);
+    return lines.join("\n");
+}

package/dist/src/commands/orders.js

@@ -0,0 +1,22 @@
+// List V3 orders visible to the account-scoped session. Requires
+// ITPAY_BEARER_TOKEN to be set to an account-scoped buyer session token.
+// Order-scoped sessions are rejected by the backend with 403 and the
+// CLI surfaces the typed `HttpError` so `main.ts` can render it.
+import { renderOrder } from "../render/output.js";
+import { hintFor } from "../render/status.js";
+import { resolveOutput } from "../render/sink.js";
+export async function runListOrders(backend, config, options) {
+    const out = resolveOutput(options.output);
+    if (!config.bearerToken) {
+        throw new Error("ITPAY_BEARER_TOKEN is required to list account orders");
+    }
+    const response = await backend.listAccountOrders(options.limit, options.status, config.bearerToken);
+    if (response.orders.length === 0) {
+        out("no orders found\n");
+        return;
+    }
+    for (const order of response.orders) {
+        out(renderOrder(order) + "\n");
+        out(`hint: ${hintFor("order", order.status)}\n\n`);
+    }
+}

package/dist/src/commands/pay.js

@@ -0,0 +1,26 @@
+// Optional CLI helper: only intended for the V3 `payment-intent` flow when
+// the human checkout page is unavailable. The V3 architecture prefers
+// that the human checkout page creates the payment intent, but the CLI
+// still needs an escape hatch for sandbox/manual testing.
+import { operationID } from "../state/config.js";
+import { resolveOutput } from "../render/sink.js";
+export async function runPay(backend, config, options) {
+    const out = resolveOutput(options.output);
+    const request = {
+        payment_method_type: options.method,
+        ...(options.preferredProvider ? { preferred_provider: options.preferredProvider } : {}),
+        ...(options.buyerID ? { buyer_id: options.buyerID } : {}),
+        ...(options.refreshAction ? { refresh_action: true } : {}),
+    };
+    const intent = await backend.createPaymentIntent(options.checkoutID, request, await operationID(config, `payment.intent:${options.checkoutID}:${options.method}`));
+    out(`payment_intent_id: ${intent.payment_intent_id}\n`);
+    out(`status:            ${intent.status}\n`);
+    out(`method:            ${intent.payment_method_type}\n`);
+    out(`amount:            ${(intent.amount_minor / 100).toFixed(2)} ${intent.currency}\n`);
+    if (intent.action?.qr_image_url) {
+        out(`qr_image_url:      ${intent.action.qr_image_url}\n`);
+    }
+    if (intent.action?.mobile_wallet_url) {
+        out(`mobile_wallet_url: ${intent.action.mobile_wallet_url}\n`);
+    }
+}

package/dist/src/commands/readyz.js

@@ -0,0 +1,8 @@
+// Liveness probe. Useful for smoke testing CLI wiring before running `buy`.
+import { renderReady } from "../render/output.js";
+import { resolveOutput } from "../render/sink.js";
+export async function runReadyz(backend, options = {}) {
+    const out = resolveOutput(options.output);
+    const response = await backend.readyz();
+    out(renderReady(response) + "\n");
+}

package/dist/src/commands/refund.js

@@ -0,0 +1,20 @@
+// Create a V3 refund request. The backend decides policy state and
+// returns the canonical refund status. The CLI never assumes a refund
+// succeeded locally — it always re-reads canonical state.
+import { operationID } from "../state/config.js";
+import { renderRefund } from "../render/output.js";
+import { hintFor } from "../render/status.js";
+import { resolveOutput } from "../render/sink.js";
+export async function runRefund(backend, config, options) {
+    const out = resolveOutput(options.output);
+    const request = {
+        payment_intent_id: options.paymentIntentID,
+        amount_minor: options.amountMinor,
+        currency: options.currency,
+        ...(options.reason ? { reason: options.reason } : {}),
+        ...(options.createdBy ? { created_by: options.createdBy } : {}),
+    };
+    const refund = await backend.createRefund(options.orderID, request, await operationID(config, `refund.create:${options.orderID}:${options.paymentIntentID}:${options.amountMinor}:${options.currency}`));
+    out(renderRefund(refund) + "\n");
+    out(`hint: ${hintFor("refund", refund.status)}\n`);
+}

package/dist/src/commands/services.js

@@ -0,0 +1,317 @@
+import { operationID } from "../state/config.js";
+import { resolveOutput } from "../render/sink.js";
+import { dispatchRender } from "../render/index.js";
+import { ensureIdeImageAttach } from "../render/ide.js";
+import { buildAgentChatHandoff } from "../render/markdown.js";
+import { buildCheckoutQRPlan } from "./buy.js";
+import { attachAgentGuidance, buildServiceActionGuidance, buildServiceInvokedGuidance, buildServiceReadModelGuidance, buildServiceStartedGuidance, printAgentGuidance, } from "./guidance.js";
+const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
+export async function runServicesStart(backend, config, serviceID, options = {}) {
+    const host = options.host ?? "terminal";
+    const response = await backend.startServiceExecution({
+        service_id: serviceID,
+        agent_device_id: config.agentDeviceID,
+        ...(options.buyerID ? { buyer_id: options.buyerID } : {}),
+        client_context: {
+            agent_device_id: config.agentDeviceID,
+            host,
+            ...(options.target ? { target: options.target } : {}),
+            ...(options.clientContext ?? {}),
+        },
+    });
+    writeJSON(options.output, attachAgentGuidance(response, buildServiceStartedGuidance(response)));
+}
+export async function runServicesInvoke(backend, config, serviceExecutionID, capabilityID, input, options = {}) {
+    const idempotencyKey = await operationID(config, `service.invoke:${serviceExecutionID}:${capabilityID}:${stableInput(input)}`);
+    const response = await backend.invokeServiceCapability(serviceExecutionID, capabilityID, {
+        idempotency_key: idempotencyKey,
+        redacted_summary: input,
+    });
+    const guidance = buildServiceInvokedGuidance(response);
+    if (options.jsonOutput) {
+        writeJSON(options.output, attachAgentGuidance(response, guidance));
+        return;
+    }
+    printAgentGuidance(guidance, options.output);
+}
+function stableInput(input) {
+    return JSON.stringify(Object.fromEntries(Object.entries(input).sort(([left], [right]) => left.localeCompare(right))));
+}
+export async function runServicesAction(backend, serviceExecutionID, actionType, input, options = {}) {
+    const selection = await resolveCandidateSelection(backend, serviceExecutionID, actionType, options);
+    const request = {
+        action_type: actionType,
+        input_snapshot: input,
+    };
+    if (options.actorType)
+        request.actor_type = options.actorType;
+    if (options.actorID)
+        request.actor_id = options.actorID;
+    if (options.status)
+        request.status = normalizeServiceActionStatus(options.status);
+    const resultItemID = selection?.resultItemID ?? options.resultItemID;
+    const selectedCandidateHash = selection?.stableHash ?? options.selectedCandidateHash;
+    if (resultItemID)
+        request.result_item_id = resultItemID;
+    if (selectedCandidateHash)
+        request.selected_candidate_hash = selectedCandidateHash;
+    if (options.requiredBefore)
+        request.required_before = options.requiredBefore;
+    const response = await backend.recordServiceExecutionAction(serviceExecutionID, request);
+    writeJSON(options.output, attachAgentGuidance(response, buildServiceActionGuidance(response)));
+}
+async function resolveCandidateSelection(backend, serviceExecutionID, actionType, options) {
+    if (options.candidateRank === undefined)
+        return undefined;
+    if (actionType !== "select_candidate") {
+        throw new Error("--candidate is only valid with --action select_candidate");
+    }
+    if (options.resultItemID || options.selectedCandidateHash) {
+        throw new Error("--candidate cannot be combined with --result-item or --selected-candidate-hash");
+    }
+    if (!Number.isInteger(options.candidateRank) || options.candidateRank < 1) {
+        throw new Error("--candidate must be a positive integer result rank");
+    }
+    const execution = await backend.getServiceExecution(serviceExecutionID);
+    const result = execution.result_items.find((item) => item.rank === options.candidateRank);
+    if (!result) {
+        throw new Error(`candidate ${options.candidateRank} is not available on service execution ${serviceExecutionID}`);
+    }
+    return {
+        resultItemID: result.service_capability_result_item_id,
+        stableHash: result.stable_hash,
+    };
+}
+export async function runServicesCheckout(backend, config, serviceExecutionID, capabilityID, options = {}) {
+    const deliveryContact = {
+        ...(options.deliveryContact ?? {}),
+        ...(options.email ? { email: options.email } : {}),
+    };
+    if (!options.resume && !capabilityID) {
+        throw new Error("--capability is required when creating a service checkout; use --resume to recover an existing handoff");
+    }
+    if (!options.resume && String(deliveryContact.email ?? "").trim() === "") {
+        const execution = await backend.getServiceExecution(serviceExecutionID);
+        const capability = execution.capabilities.find((item) => item.capability_id === capabilityID);
+        if (!capability) {
+            throw new Error(`capability ${capabilityID} is not available on service execution ${serviceExecutionID}`);
+        }
+        if (capability.delivery_email_required) {
+            throw new Error("delivery email is required before creating this service checkout; ask the buyer for --email");
+        }
+    }
+    const response = await backend.createServiceExecutionCheckout(serviceExecutionID, {
+        ...(capabilityID ? { capability_id: capabilityID } : {}),
+        ...(Object.keys(deliveryContact).length > 0 ? { delivery_contact: deliveryContact } : {}),
+        ...(options.resume ? { resume: true } : {}),
+    });
+    const checkout = response.checkout;
+    const checkoutID = checkout.checkout.checkout_id;
+    const displayToken = checkout.display_token;
+    const checkoutURL = tokenizedCheckoutURL(checkout.checkout_url, displayToken, checkout.qr_payload);
+    const plan = buildCheckoutQRPlan({
+        host: options.host ?? "terminal",
+        checkoutID,
+        checkoutURL,
+        displayToken,
+        qrPayload: checkout.qr_payload,
+        ...(checkout.qr_png_url ? { qrPNGURL: checkout.qr_png_url } : {}),
+        nextAction: checkout.checkout.next_action,
+        orderItems: response.cart.items.map((item) => ({
+            title: item.title,
+            quantity: item.quantity,
+            amountMinor: item.amount_minor,
+            currency: item.currency,
+        })),
+        orderCurrency: checkout.checkout.currency,
+    });
+    options.persistHandoff?.({
+        serviceExecutionID,
+        cartID: response.cart.cart_id,
+        checkoutID,
+        displayToken,
+        checkoutURL,
+    });
+    if (options.jsonOutput) {
+        await ensureIdeImageAttach(plan, {
+            enabled: config.ideImageAttach,
+            ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        });
+        writeJSON(options.output, buildServicesCheckoutJSON(response, checkoutURL, plan));
+        return;
+    }
+    await dispatchRender(plan, {
+        host: options.host ?? "terminal",
+        isTTY: options.isTTY ?? Boolean(process.stdout.isTTY),
+        ...(options.target ? { target: options.target } : {}),
+        ...(options.qrFormat ? { qrFormat: options.qrFormat } : {}),
+        ...(options.qrFilePath ? { qrFilePath: options.qrFilePath } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        baseURL: config.baseURL,
+    });
+}
+export async function runServicesGet(backend, serviceExecutionID, options = {}) {
+    const response = await backend.getServiceExecution(serviceExecutionID);
+    const guidance = buildServiceReadModelGuidance(response);
+    if (options.jsonOutput) {
+        writeJSON(options.output, attachAgentGuidance(response, guidance));
+        return;
+    }
+    printAgentGuidance(guidance, options.output);
+}
+export async function runServicesNext(backend, serviceExecutionID, options = {}) {
+    const response = await backend.getServiceExecution(serviceExecutionID);
+    const guidance = buildServiceReadModelGuidance(response);
+    if (options.jsonOutput) {
+        writeJSON(options.output, guidance);
+        return;
+    }
+    printAgentGuidance(guidance, options.output);
+}
+export async function runServicesList(backend, options = {}) {
+    const response = await backend.listServiceExecutions(options.limit ?? 50);
+    if (options.jsonOutput) {
+        writeJSON(options.output, response.executions.map((model) => ({
+            execution: model.execution,
+            agent_guidance: buildServiceReadModelGuidance(model),
+        })));
+        return;
+    }
+    const out = resolveOutput(options.output);
+    for (const model of response.executions) {
+        const guidance = buildServiceReadModelGuidance(model);
+        out(`${guidance.summary}\n`);
+        const next = guidance.next_actions[0];
+        if (next)
+            out(`next: ${next.command}\n`);
+    }
+}
+export async function runServicesReadResult(backend, serviceExecutionID, options = {}) {
+    writeJSON(options.output, await backend.getGrantedServiceResult(serviceExecutionID));
+}
+export async function runServicesEvents(backend, serviceExecutionID, options = {}) {
+    writeJSON(options.output, await backend.listServiceExecutionEvents(serviceExecutionID));
+}
+export function parseKeyValueList(values) {
+    const result = {};
+    for (const value of values ?? []) {
+        const index = value.indexOf("=");
+        if (index <= 0) {
+            throw new Error(`invalid --input "${value}", expected key=value`);
+        }
+        result[value.slice(0, index)] = parseValue(value.slice(index + 1));
+    }
+    return result;
+}
+export function collectOption(value, previous = []) {
+    previous.push(value);
+    return previous;
+}
+function parseValue(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    return value;
+}
+function writeJSON(output, value) {
+    resolveOutput(output)(JSON.stringify(value, null, 2) + "\n");
+}
+function buildServicesCheckoutJSON(response, checkoutURL, plan) {
+    const checkout = response.checkout;
+    const output = {
+        kind: "checkout_handoff_required",
+        next_action: "open_human_checkout",
+        service_execution_id: response.binding.service_execution_id,
+        service_quote_lock_id: response.service_quote_lock_id,
+        checkout_id: checkout.checkout.checkout_id,
+        checkout_status: checkout.checkout.status,
+        handoff_reissued: response.handoff_reissued,
+        checkout_url: checkoutURL,
+        display_token: checkout.display_token,
+        qr_payload: checkout.qr_payload,
+        amount_minor: checkout.checkout.amount_minor,
+        currency: checkout.checkout.currency,
+        next: `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token}`,
+        warning: "Do not call `itpay pay` for the normal buyer flow; show this ItPay checkout URL/QR to the human.",
+    };
+    const nextActions = [{
+            id: "open_human_checkout",
+            label: "Show the ItPay checkout URL or branded QR to the human",
+            command: `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token}`,
+            requires_human: true,
+            reason: "The human must review and pay on the ItPay checkout page.",
+        }];
+    output.next_actions = nextActions;
+    output.agent_guidance = {
+        kind: "checkout_handoff",
+        summary: `checkout ${checkout.checkout.checkout_id}: show the ItPay checkout handoff to the human`,
+        state: {
+            service_execution_id: response.binding.service_execution_id,
+            checkout_id: checkout.checkout.checkout_id,
+            checkout_status: checkout.checkout.status,
+        },
+        next_actions: nextActions,
+        recovery: [{
+                id: "inspect_checkout",
+                label: "Read checkout presentation",
+                command: `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token}`,
+            }],
+    };
+    if (checkout.qr_png_url) {
+        output.qr_png_url = checkout.qr_png_url;
+    }
+    if (plan.ideImageAttach) {
+        output.brand_qr_status = plan.ideImageAttach.status;
+        output.brand_qr_mime_type = plan.ideImageAttach.mimeType;
+        output.brand_qr_must_render_reason = plan.ideImageAttach.mustRenderReason;
+        output.brand_qr_render_action = "agent_must_read_local_path_into_ide_chat";
+        if (plan.ideImageAttach.localPath) {
+            output.brand_qr_local_path = plan.ideImageAttach.localPath;
+            const stableName = plan.ideImageAttach.localPath.split("/").pop();
+            if (stableName)
+                output.brand_qr_stable_name = stableName;
+        }
+        if (plan.ideImageAttach.mirrors.length > 0) {
+            output.brand_qr_mirrors = [...plan.ideImageAttach.mirrors];
+        }
+        if (plan.ideImageAttach.caption) {
+            output.brand_qr_caption = plan.ideImageAttach.caption;
+        }
+        if (plan.ideImageAttach.error) {
+            output.brand_qr_error = plan.ideImageAttach.error;
+        }
+    }
+    output.agent_action = buildAgentChatHandoff(plan);
+    return output;
+}
+function normalizeServiceActionStatus(status) {
+    const normalized = status.trim().toLowerCase();
+    if (!serviceActionStatuses.has(normalized)) {
+        throw new Error(`invalid --status "${status}". Supported: pending, approved, rejected, expired, cancelled`);
+    }
+    return normalized;
+}
+function tokenizedCheckoutURL(checkoutURL, displayToken, qrPayload) {
+    if (qrPayload.trim().length > 0) {
+        return qrPayload;
+    }
+    if (checkoutURL.trim().length === 0 || displayToken.trim().length === 0) {
+        return checkoutURL;
+    }
+    try {
+        const parsed = new URL(checkoutURL);
+        if (!parsed.searchParams.has("display_token")) {
+            parsed.searchParams.set("display_token", displayToken);
+        }
+        return parsed.toString();
+    }
+    catch {
+        const separator = checkoutURL.includes("?") ? "&" : "?";
+        return `${checkoutURL}${separator}display_token=${encodeURIComponent(displayToken)}`;
+    }
+}