@fluid-app/fluid-cli-payments 0.1.147 → 0.1.149

package/README.md

@@ -2,7 +2,8 @@
 
 Fluid CLI plugin for payments onboarding: the KYC form at
 **Settings → Onboarding** in the admin. See what's missing, fill in fields and
-documents, and submit the form for review.
+documents, and submit the form for review. Once payments are set up,
+[`test-order`](#test-order) places one order on the company's test gateway.
 
 ```bash
 npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-payments
@@ -67,3 +68,54 @@ non-zero. Commands that change data ask for confirmation unless you pass
 
 The walkthrough is the payments onboarding guided setup at
 https://docs.fluid.app/setup.
+
+## Test order
+
+`test-order` proves checkout works for a new company by placing one order on
+its test gateway, with you as the buyer:
+
+```bash
+fluid payments test-order --product 501 --accept-agreements --yes
+fluid payments test-order --variant 9001 --country CA --accept-agreements --yes \
+  --address '{"address1":"100 King St W","city":"Toronto","state":"ON","postal_code":"M5X 1A9"}'
+```
+
+The buyer is the signed-in person: the order uses your email, and `--email`
+can only repeat it. Checkout records the store's required agreements as
+accepted by the buyer, so a test order needs a person's sign-in (`fluid login`
+with email) and refuses a company API token with `PERSON_SIGN_IN_REQUIRED`.
+When the store has required agreements, it stops with
+`AGREEMENTS_NOT_ACCEPTED` and their titles until you read them and pass
+`--accept-agreements`.
+
+It builds a cart for one unit (`--product` buys the product's master
+variant, so a draft product works too), sets the email, address and the
+first shipping method, then pays with the test card `4242 4242 4242 4242`
+and prints the order's id and number as JSON. The built-in address is in the US. Outside
+the US, pass a real `--address`, since tax is quoted for it.
+
+Before anything is paid for, it checks that every payment method the cart
+offers is a test card on the Bogus gateway, all on one payment account, and
+charges only that account. Otherwise it stops with a `code`, such as
+`NO_PAYMENT_ACCOUNT` (a company that signed up recently may need to confirm
+its signup first) or `NOT_TEST_GATEWAY`. A bad email or address also fails before
+anything is paid for. It names the agreements you accept in the question and
+the output, and sends back the version of their text it was shown, so
+checkout refuses if the wording changes before the order completes. Agents pass `--yes`, and people at a
+terminal are asked; without either it stops with `CONFIRMATION_REQUIRED`,
+and a "no" stops with `CANCELLED`. Just before the order completes it reads
+the cart again and repeats the payment checks, stopping with
+`PAYMENT_ACCOUNT_CHANGED` if the account it checked is no longer the one
+the cart would charge. Use the same environment as your login
+(`--base-url`).
+
+The order is real, though no money moves. The confirmation email goes to
+you, order webhooks fire, and inventory is adjusted as for any order.
+Checkout finds or creates a customer (and member) for your email in the
+store and records the agreement acceptances against it. Nothing marks the
+order as a test, so it shows in sales reports until it's refunded. Refund
+and cancel it in the admin if you don't want it in the order list. Each run
+tries once and places a new order. A failure after the cart exists gives
+the cart's `cartId` and the time in `details` (never the cart token, which
+opens the cart). If it fails with `ORDER_OUTCOME_UNKNOWN`, look in the
+admin for an order from your email at that time before running it again.

package/dist/index.d.mts

@@ -2,19 +2,8 @@ import { CommandContext, FluidPlugin } from "@fluid-app/fluid-cli";
 import { Command } from "commander";
 
 //#region src/index.d.ts
-/**
- * Changes to the onboarding form need an explicit yes. Scripts and agents
- * pass `--yes`; an interactive terminal is asked. With neither, nothing runs.
- */
-declare function confirmChange(question: string, yes: boolean, interactive?: boolean): Promise<void>;
-/**
- * Print a failure as JSON on stderr and exit non-zero. The API's error body
- * names fields and reasons, never the submitted values, so its `errors` are
- * passed through as `details`.
- */
-declare function fail(err: unknown, write?: (text: string) => void): void;
 declare function registerOnboardingCommands(parent: Command, ctx: CommandContext): void;
 declare const plugin: FluidPlugin;
 //#endregion
-export { confirmChange, plugin as default, fail, registerOnboardingCommands };
+export { plugin as default, registerOnboardingCommands };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;AA8CA;;iBAAsB,aAAA,CACpB,QAAA,UACA,GAAA,WACA,WAAA,aACC,OAAA;;;;;;iBAkBa,IAAA,CACd,GAAA,WACA,KAAA,IAAQ,IAAA;AAAA,iBAmDM,0BAAA,CACd,MAAA,EAAQ,OAAA,EACR,GAAA,EAAK,cAAA;AAAA,cA4TD,MAAA,EAAQ,WAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;iBAyDgB,0BAAA,CACd,MAAA,EAAQ,OAAA,EACR,GAAA,EAAK,cAAA;AAAA,cAiUD,MAAA,EAAQ,WAAA"}

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import prompts from "prompts";
 import { NAV_HELP, assertInteractive, createDomainCommand, terminalPrompter } from "@fluid-app/fluid-cli";
 import { readFile } from "node:fs/promises";
 import { basename, extname } from "node:path";
+import prompts from "prompts";
 //#region src/fields.ts
 const STEPS = [
 	{
@@ -588,9 +588,12 @@ function stepReports(snapshot, missing) {
 //#endregion
 //#region src/types.ts
 var OnboardingError = class extends Error {
-	constructor(message, details) {
+	/** `code` is a stable, machine-readable name for the failure, printed
+	*  beside the message so a script can branch on it. */
+	constructor(message, details, code) {
 		super(message);
 		this.details = details;
+		this.code = code;
 		this.name = "OnboardingError";
 	}
 };
@@ -1728,28 +1731,27 @@ async function walkOnboarding(deps, opts = {}) {
 	};
 }
 //#endregion
-//#region src/index.ts
-async function client(ctx) {
-	return await ctx.getClient();
-}
+//#region src/cli.ts
 /**
 * Changes to the onboarding form need an explicit yes. Scripts and agents
-* pass `--yes`; an interactive terminal is asked. With neither, nothing runs.
+* pass `--yes`; an interactive terminal is asked. With neither, nothing runs,
+* and the refusal's code (CONFIRMATION_REQUIRED, or CANCELLED for a "no")
+* lets a script tell it from a failure.
 */
 async function confirmChange(question, yes, interactive = Boolean(process.stdin.isTTY)) {
 	if (yes) return;
-	if (!interactive) throw new OnboardingError(`${question} Pass --yes to confirm.`);
+	if (!interactive) throw new OnboardingError(`${question} Pass --yes to confirm.`, void 0, "CONFIRMATION_REQUIRED");
 	if (!(await prompts({
 		type: "confirm",
 		name: "ok",
 		message: question,
 		initial: false
-	})).ok) throw new OnboardingError("Cancelled.");
+	})).ok) throw new OnboardingError("Cancelled.", void 0, "CANCELLED");
 }
 /**
 * Print a failure as JSON on stderr and exit non-zero. The API's error body
 * names fields and reasons, never the submitted values, so its `errors` are
-* passed through as `details`.
+* passed through as `details`. An `OnboardingError`'s `code` is printed too.
 */
 function fail(err, write = (t) => process.stderr.write(t)) {
 	const status = typeof err.status === "number" ? err.status : void 0;
@@ -1757,8 +1759,10 @@ function fail(err, write = (t) => process.stderr.write(t)) {
 	const apiDetail = body && (body["errors"] ?? body["error"] ?? body["error_message"]);
 	const message = typeof body?.["error_message"] === "string" ? body["error_message"] : typeof apiDetail === "string" ? apiDetail : err instanceof Error ? err.message : String(err);
 	const details = err instanceof OnboardingError && err.details !== void 0 ? err.details : apiDetail && typeof apiDetail === "object" ? apiDetail : void 0;
+	const code = err instanceof OnboardingError ? err.code : void 0;
 	write(JSON.stringify({
 		error: message,
+		...code ? { code } : {},
 		...status ? { status } : {},
 		...details !== void 0 ? { details } : {}
 	}) + "\n");
@@ -1767,6 +1771,378 @@ function fail(err, write = (t) => process.stderr.write(t)) {
 function run(action) {
 	return action().catch((err) => fail(err));
 }
+//#endregion
+//#region src/test-order.ts
+const CART_TIMEOUT_MS = 15e3;
+const COMPLETE_TIMEOUT_MS = 6e4;
+const CHECKOUT = "/api/checkout/v2026-04/carts";
+const PAYMENTS = "/api/payments/v2026-04/carts";
+const TOKENIZE_CARD = "/api/v202506/payments/tokenize_card";
+const TEST_CARD = "4242424242424242";
+/** A real address, so a tax quote for it succeeds. */
+const US_ADDRESS = {
+	address1: "1200 Market St",
+	city: "San Francisco",
+	state: "CA",
+	postal_code: "94103"
+};
+const DEFAULT_NAME = "Test Order";
+function refusal(code, message, details) {
+	return new OnboardingError(message, details, code);
+}
+function positiveId(raw, flag) {
+	const value = /^\d+$/.test(raw) ? Number(raw) : 0;
+	if (!Number.isSafeInteger(value) || value <= 0) throw refusal("FLAGS_INVALID", `${flag} takes a numeric id, not "${raw}".`);
+	return value;
+}
+/**
+* The ship-to and bill-to address. Checkout permits `name`, not
+* `first_name`/`last_name`, so only `name` is sent.
+*/
+function buildAddress(raw, country) {
+	if (raw === void 0) {
+		if (country !== "US") throw refusal("ADDRESS_REQUIRED", `The built-in address is in the US. Pass --address '{"address1":…,"city":…,"postal_code":…}' with a real address in ${country}.`);
+		return {
+			name: DEFAULT_NAME,
+			...US_ADDRESS,
+			country_code: country
+		};
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw refusal("FLAGS_INVALID", "--address must be a JSON object.");
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw refusal("FLAGS_INVALID", "--address must be a JSON object.");
+	const given = parsed;
+	const text = (key) => typeof given[key] === "string" && given[key].trim() ? given[key].trim() : void 0;
+	const missing = [
+		"address1",
+		"city",
+		"postal_code"
+	].filter((k) => !text(k));
+	if (missing.length) throw refusal("FLAGS_INVALID", `--address needs ${missing.join(", ")}.`);
+	const address = { name: text("name") ?? DEFAULT_NAME };
+	for (const key of [
+		"address1",
+		"address2",
+		"city",
+		"state",
+		"postal_code"
+	]) {
+		const value = text(key);
+		if (value) address[key] = value;
+	}
+	return {
+		...address,
+		country_code: country
+	};
+}
+/**
+* Why the cart must not be paid for, or null when every payment method it
+* offers is a test card on the Bogus gateway and all name one account. A
+* sandbox account on a real processor also says `test`, so `bogus_gateway`
+* is checked too. The same rule as the checkout load test's.
+*/
+function gatewayRefusal(cart) {
+	if ((cart.available_payment_methods ?? []).length === 0) return refusal("NO_PAYMENT_ACCOUNT", "The cart offers nothing to pay with: the company has no payment account that takes this order. A company that signed up recently may need to confirm its signup first. Nothing was placed.");
+	const live = liveMethodRefusal(cart);
+	if (live) return live;
+	if (testAccount(cart) === null) return refusal("NO_SINGLE_TEST_ACCOUNT", "The cart's test payment methods don't name one payment account to charge. Nothing was placed.");
+	return null;
+}
+/** A refusal naming the first payment method that isn't a Bogus test card. */
+function liveMethodRefusal(cart) {
+	const live = (cart.available_payment_methods ?? []).find((m) => m.type !== "credit_card" || m.test !== true || m.bogus_gateway !== true);
+	if (!live) return null;
+	return refusal("NOT_TEST_GATEWAY", `The cart offers a payment method that isn't a test card on the Bogus gateway (${live.name || live.type || "unnamed"}), so this company could be charged for real. Nothing was placed.`, { paymentMethod: {
+		type: live.type,
+		name: live.name
+	} });
+}
+/** The one account every test payment method names, or null. */
+function testAccount(cart) {
+	const accounts = new Set((cart.available_payment_methods ?? []).map((m) => m.uuid));
+	const [account] = accounts;
+	return accounts.size === 1 && typeof account === "string" && account ? account : null;
+}
+/** The code for a refused request, by the step that sent it. */
+function codeFor(step, status, body) {
+	if (step === "create_cart" && status === 422 && body?.errors?.["items"]) return "VARIANT_UNAVAILABLE";
+	if (step === "tokenize_card") return "TOKENIZE_FAILED";
+	if (step === "complete") {
+		const details = Array.isArray(body?.meta?.error_details) ? body.meta.error_details : [];
+		if (status >= 500 || details.some((d) => d?.payment === "unknown")) return "ORDER_OUTCOME_UNKNOWN";
+		if (body?.meta?.code === "cart_total_changed") return "CART_TOTAL_CHANGED";
+		return "CHECKOUT_REFUSED";
+	}
+	return "REQUEST_FAILED";
+}
+/**
+* One cart or payment call, sent without the login token. These endpoints
+* need none: the cart calls act on the cart token, and tokenize_card is
+* public. A token would do harm on one of them: for a company with isolated
+* payment tokens, attaching a card reads the bearer, attaches the card to
+* that person's customer record and rewrites the cart's email to theirs. So
+* these calls use a plain fetch, not the CLI's client, which always adds
+* Authorization.
+*/
+async function publicRequest(deps, step, method, path, body, headers = {}) {
+	const timeout = step === "complete" ? COMPLETE_TIMEOUT_MS : CART_TIMEOUT_MS;
+	let response;
+	let text;
+	try {
+		response = await deps.fetch(`${deps.baseUrl}${path}`, {
+			method,
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json",
+				...headers
+			},
+			body: body === void 0 ? void 0 : JSON.stringify(body),
+			signal: AbortSignal.timeout(timeout)
+		});
+		text = await response.text();
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		if (step === "complete") throw refusal("ORDER_OUTCOME_UNKNOWN", `Checkout got no answer (${reason}), so the order may or may not have been placed. Check the orders in the admin before running this again.`);
+		throw refusal("REQUEST_FAILED", `The ${step} request got no answer (${reason}). Nothing was charged.`);
+	}
+	let parsed = null;
+	try {
+		parsed = text ? JSON.parse(text) : null;
+	} catch {
+		parsed = null;
+	}
+	if (response.ok) return parsed ?? {};
+	const errorBody = parsed && typeof parsed === "object" ? parsed : null;
+	const apiMessage = typeof errorBody?.error_message === "string" ? errorBody.error_message : typeof errorBody?.error === "string" ? errorBody.error : `HTTP ${response.status}`;
+	const code = codeFor(step, response.status, errorBody);
+	const message = code === "ORDER_OUTCOME_UNKNOWN" ? `Checkout couldn't confirm the outcome (${apiMessage}), so the order may or may not have been placed. Check the orders in the admin before running this again.` : `${step}: ${apiMessage}`;
+	const details = Object.fromEntries(Object.entries({
+		step,
+		errors: errorBody?.errors,
+		errorDetails: errorBody?.meta?.error_details,
+		cart: errorBody?.meta?.cart
+	}).filter(([, v]) => v !== void 0));
+	throw Object.assign(refusal(code, message, details), { status: response.status });
+}
+/**
+* The buyer's email: the signed-in person's own. The order accepts the
+* store's required agreements in the buyer's name, so the buyer has to be
+* the person running the command. A company API token has no person behind
+* it, and `/api/me` refuses it, so a token can't place a test order.
+*/
+async function buyerEmail(reads, given) {
+	let me;
+	try {
+		me = await reads.get("/api/me");
+	} catch (error) {
+		const status = error.status;
+		if (status === 401 || status === 403) throw refusal("PERSON_SIGN_IN_REQUIRED", "A test order accepts the store's checkout agreements as its buyer, so it needs a person's sign-in (`fluid login` with email). A company API token has no person behind it.");
+		throw error;
+	}
+	const own = me.email?.trim();
+	if (!own) throw refusal("REQUEST_FAILED", "Couldn't read the signed-in person's email.");
+	if (given !== void 0 && given.trim().toLowerCase() !== own.toLowerCase()) throw refusal("EMAIL_NOT_SIGNED_IN_PERSON", "--email must be your own address, the one you signed in with: the order accepts the store's agreements in its buyer's name. Leave --email out to use it.");
+	return own;
+}
+/**
+* Place one order on the company's test gateway and return it. Every check
+* on the flags and the cart runs before the question, the payment checks run
+* again just before complete, and nothing is charged before complete: a
+* refused run leaves at most an unused cart. A failure after the cart exists
+* gives the cart's id and the time in its details.
+*/
+async function placeTestOrder(deps, opts) {
+	if (Boolean(opts.variant) === Boolean(opts.product)) throw refusal("FLAGS_INVALID", "Pass exactly one of --variant or --product.");
+	if (opts.email !== void 0 && !opts.email.trim()) throw refusal("FLAGS_INVALID", "--email can't be blank.");
+	const productId = opts.product ? positiveId(opts.product, "--product") : void 0;
+	let variantId = opts.variant ? positiveId(opts.variant, "--variant") : void 0;
+	const email = await buyerEmail(deps.reads, opts.email);
+	const me = await deps.reads.get("/api/company/v1/companies/me");
+	const company = me.data?.company ?? me.company;
+	const shop = company?.subdomain;
+	if (!shop) throw refusal("REQUEST_FAILED", "Couldn't tell which company this token belongs to.");
+	const country = (opts.country ?? company?.default_country?.iso ?? "").trim().toUpperCase();
+	if (!country) throw refusal("FLAGS_INVALID", "The company has no default country. Pass --country <iso>.");
+	const address = buildAddress(opts.address, country);
+	let product;
+	if (productId !== void 0) {
+		const read = await deps.reads.get(`/api/v202604/company/products/${productId}`).catch((error) => {
+			if (error.status === 404) throw refusal("PRODUCT_NOT_FOUND", `This company has no product ${productId}. Nothing was placed.`);
+			throw error;
+		});
+		variantId = read.product?.default_variant?.id;
+		if (!variantId) throw refusal("VARIANT_UNAVAILABLE", `Product ${productId} has no master variant to buy. Pass --variant <id> instead.`);
+		product = {
+			id: productId,
+			title: read.product?.title,
+			status: read.product?.status
+		};
+	}
+	const created = await publicRequest(deps, "create_cart", "POST", CHECKOUT, {
+		fluid_shop: shop,
+		country_code: country,
+		items: [{
+			variant_id: variantId,
+			quantity: 1
+		}]
+	});
+	const cartToken = created.cart?.cart_token;
+	if (!cartToken) throw refusal("REQUEST_FAILED", "Checkout created no cart token.");
+	try {
+		return await payForCart(deps, opts, {
+			created: created.cart ?? {},
+			cartToken,
+			email,
+			shop,
+			country,
+			address,
+			variantId,
+			product
+		});
+	} catch (err) {
+		throw withCartContext(err, {
+			...created.cart?.id ? { cartId: created.cart.id } : {},
+			at: (deps.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+		});
+	}
+}
+/**
+* The same failure with the cart's id and the time added to its details, so
+* the order can be looked up in the admin before a rerun places a second
+* one. The id, not the cart token: the token opens the cart (its email and
+* address) on the public cart routes, and stderr is often kept.
+*/
+function withCartContext(err, context) {
+	if (!(err instanceof OnboardingError)) return err;
+	const own = err.details;
+	const details = own === void 0 ? context : own && typeof own === "object" && !Array.isArray(own) ? {
+		...own,
+		...context
+	} : {
+		...context,
+		details: own
+	};
+	const tagged = new OnboardingError(err.message, details, err.code);
+	const status = err.status;
+	return status === void 0 ? tagged : Object.assign(tagged, { status });
+}
+/** Everything after the cart exists, through complete. */
+async function payForCart(deps, opts, run) {
+	const { cartToken, email, shop, country, address, variantId, product } = run;
+	const live = liveMethodRefusal(run.created);
+	if (live) throw live;
+	const cartPath = `${CHECKOUT}/${encodeURIComponent(cartToken)}`;
+	await publicRequest(deps, "set_email", "PATCH", cartPath, { email });
+	const shipping = (await publicRequest(deps, "set_address", "POST", `${cartPath}/address`, {
+		type: "both",
+		address
+	})).cart?.available_shipping_methods?.[0];
+	if (!shipping) throw refusal("NO_SHIPPING_METHOD", `The company offers no shipping method to ${country}. Nothing was placed.`);
+	const cart = (await publicRequest(deps, "set_shipping", "PUT", `${cartPath}/shipping`, { shipping_method_id: shipping.id })).cart ?? {};
+	if (String(cart.shipping_method?.id ?? "") !== String(shipping.id)) throw refusal("SHIPPING_NOT_SET", `Checkout didn't keep shipping method ${shipping.id}. Nothing was placed.`);
+	const refused = gatewayRefusal(cart);
+	if (refused) throw refused;
+	const account = testAccount(cart);
+	const total = cart.amount_total;
+	const currency = cart.currency_code;
+	if (total === null || total === void 0 || !currency) throw refusal("VARIANT_UNAVAILABLE", `Checkout shows no total or currency for this cart (an item in it may have no price in ${country}). Nothing was placed.`);
+	const agreements = [...new Map((cart.agreements ?? []).filter((a) => a.required).map((a) => [a.id, a])).values()];
+	const agreementIds = agreements.map((a) => a.id);
+	const agreementVersions = agreements.filter((a) => typeof a.content_digest === "string" && a.content_digest).map((a) => ({
+		id: a.id,
+		content_digest: a.content_digest
+	}));
+	const agreementTitles = agreements.map((a) => a.title || `#${a.id}`);
+	if (agreements.length && !opts.acceptAgreements) throw refusal("AGREEMENTS_NOT_ACCEPTED", `Checkout needs the buyer to accept the store's required agreements: ${agreementTitles.join(", ")}. The order accepts them in your name, as the signed-in person. Read them, then pass --accept-agreements. Nothing was placed.`, { agreements: agreements.map((a) => ({
+		id: a.id,
+		title: a.title
+	})) });
+	await confirmChange(`Place a test order of ${product?.title ? `"${product.title}"` : `variant ${variantId}`} for ${total} ${currency} on ${shop}? It sends a confirmation email to your sign-in address and fires order webhooks.${agreementTitles.length ? ` You accept the store's required agreements as its buyer: ${agreementTitles.join(", ")}.` : ""}`, opts.yes, deps.interactive);
+	const now = (deps.now ?? (() => /* @__PURE__ */ new Date()))();
+	const expYear = String(now.getUTCFullYear() + 3);
+	const issued = await publicRequest(deps, "tokenize_card", "POST", TOKENIZE_CARD, { credit_card: {
+		first_name: "Test",
+		last_name: "Order",
+		number: TEST_CARD,
+		verification_value: "123",
+		month: "12",
+		year: expYear
+	} });
+	const card = issued.transaction?.payment_method;
+	if (issued.transaction?.succeeded !== true || card?.test !== true || !card.token) throw refusal("TOKENIZE_FAILED", "The test gateway issued no test card token. Nothing was charged.");
+	await publicRequest(deps, "attach_card", "PUT", `${PAYMENTS}/${encodeURIComponent(cartToken)}/payment_method`, {
+		type: "credit_card",
+		payment_method: {
+			token_provider: "vgs",
+			token: card.token,
+			card_holder: DEFAULT_NAME,
+			last_four: card.last_four_digits || TEST_CARD.slice(-4),
+			bin: card.first_six_digits || TEST_CARD.slice(0, 6),
+			card_network: card.card_network || "visa",
+			exp_month: "12",
+			exp_year: expYear
+		},
+		payment_account: account
+	});
+	const current = (await publicRequest(deps, "reread_cart", "GET", cartPath)).cart ?? {};
+	const moved = gatewayRefusal(current);
+	if (moved) throw moved;
+	if (testAccount(current) !== account || current.payment_account && current.payment_account !== account) throw refusal("PAYMENT_ACCOUNT_CHANGED", `The cart's test payment account is no longer ${account}, the one that was checked. Nothing was charged.`);
+	const idempotencyKey = (deps.randomUUID ?? (() => crypto.randomUUID()))();
+	const placed = await publicRequest(deps, "complete", "POST", `${cartPath}/complete`, {
+		expected_total: String(total),
+		expected_currency: currency,
+		...agreementIds.length ? { accepted_agreement_ids: agreementIds } : {},
+		...agreementVersions.length ? { accepted_agreement_versions: agreementVersions } : {}
+	}, { "Idempotency-Key": idempotencyKey });
+	const order = placed.order;
+	if (!order?.id) throw refusal("UNEXPECTED_CHECKOUT_RESPONSE", "Checkout answered without an order (it may want a redirect, a 3DS challenge or an enrollment step). Check the orders in the admin before running this again.", { keys: Object.keys(placed) });
+	return {
+		placed: true,
+		order: {
+			id: order.id,
+			orderNumber: order.order_number
+		},
+		total,
+		currency,
+		shop,
+		country,
+		variant: {
+			id: variantId,
+			...product ? {
+				productId: product.id,
+				productStatus: product.status
+			} : {}
+		},
+		paymentAccount: account,
+		acceptedAgreements: agreements.map((a) => ({
+			id: a.id,
+			title: a.title
+		})),
+		note: `A real order on the test gateway: nothing was charged, but a confirmation email went to your sign-in address and order webhooks fired. Refund and cancel it in the admin if you don't want it in the order list.`
+	};
+}
+const commandBaseUrl = (parent) => (parent.opts().baseUrl ?? process.env["FLUID_API_BASE"] ?? "https://api.fluid.app").replace(/\/$/, "");
+function registerTestOrderCommand(parent, ctx, overrides = {}) {
+	parent.command("test-order").description("Place one order on the company's test gateway to prove checkout works, as the signed-in person; refused unless every payment method is a test card (places a real order: sends an email, fires webhooks)").option("--email <email>", "The buyer's email; must be your own (the signed-in person's), which is the default").option("--accept-agreements", "Accept the store's required checkout agreements as the buyer (required when it has any)", false).option("--variant <id>", "The variant to buy").option("--product <id>", "A product to buy, by its master variant").option("--country <iso>", "Country to buy in (ISO code); defaults to the company's default country").option("--address <json>", "Ship-to address as JSON, e.g. {\"address1\":\"…\",\"city\":\"…\",\"state\":\"…\",\"postal_code\":\"…\"}; required outside the US").option("--yes", "Confirm without a prompt", false).action((opts) => run(async () => {
+		const reads = await ctx.getClient();
+		ctx.output(await placeTestOrder({
+			reads,
+			fetch: overrides.fetch ?? ((input, init) => fetch(input, init)),
+			baseUrl: commandBaseUrl(parent),
+			interactive: overrides.interactive
+		}, opts));
+	}));
+}
+//#endregion
+//#region src/index.ts
+async function client(ctx) {
+	return await ctx.getClient();
+}
 const collect = (value, previous = []) => [...previous, value];
 const GROUPS = [
 	"info",
@@ -1913,10 +2289,13 @@ const plugin = {
 	name: "@fluid-app/fluid-cli-payments",
 	version: "0.1.0",
 	register(ctx) {
-		ctx.program.addCommand(createDomainCommand("payments", "Payments onboarding: what's missing, fill it in, and submit", registerOnboardingCommands));
+		ctx.program.addCommand(createDomainCommand("payments", "Payments onboarding: what's missing, fill it in, and submit; or place a test order", (parent, commandCtx) => {
+			registerOnboardingCommands(parent, commandCtx);
+			registerTestOrderCommand(parent, commandCtx);
+		}));
 	}
 };
 //#endregion
-export { confirmChange, plugin as default, fail, registerOnboardingCommands };
+export { plugin as default, registerOnboardingCommands };
 
 //# sourceMappingURL=index.mjs.map