@fluid-app/fluid-cli-channels 0.0.0-stage → 0.1.1

package/dist/index.mjs

@@ -0,0 +1,1125 @@
+import prompts from "prompts";
+import { NAV_HELP, assertInteractive, createDomainCommand, terminalPrompter } from "@fluid-app/fluid-cli";
+import { z } from "zod";
+import { spawn } from "node:child_process";
+//#region src/channels.ts
+var ChannelsError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ChannelsError";
+	}
+};
+const CHANNELS = {
+	tiktok: {
+		id: "tiktok",
+		label: "TikTok Shop",
+		base: "/api/v202506/tiktok",
+		listings: "product_listings",
+		listing: "product_listing",
+		accountIdField: "shop_id",
+		accountNameField: "shop_name",
+		channelProductIdField: "tiktok_product_id",
+		reviewFields: [],
+		detailFields: [
+			"region",
+			"seller_type",
+			"tiktok_warehouse_id"
+		]
+	},
+	meta: {
+		id: "meta",
+		label: "Meta (Facebook and Instagram)",
+		base: "/api/v202506/meta",
+		listings: "catalog_listings",
+		listing: "catalog_listing",
+		accountIdField: "catalog_id",
+		accountNameField: "catalog_name",
+		channelProductIdField: "product_retailer_id",
+		reviewFields: [
+			"marketplace_review_status",
+			"shops_review_status",
+			"whatsapp_review_status",
+			"instagram_review_status"
+		],
+		detailFields: [
+			"meta_business_id",
+			"meta_page_id",
+			"meta_instagram_business_account_id",
+			"waba_id",
+			"phone_number_id"
+		]
+	},
+	google: {
+		id: "google",
+		label: "Google Merchant Center",
+		base: "/api/v202506/google",
+		listings: "product_listings",
+		listing: "product_listing",
+		accountIdField: "merchant_center_id",
+		accountNameField: "merchant_center_name",
+		channelProductIdField: "item_group_id",
+		reviewFields: [
+			"google_review_status",
+			"content_language",
+			"feed_label"
+		],
+		detailFields: ["google_mca_id"]
+	}
+};
+const CHANNEL_IDS = Object.keys(CHANNELS);
+function channelOf(id) {
+	const channel = CHANNELS[id.trim().toLowerCase()];
+	if (!channel) throw new ChannelsError(`"${id}" isn't a channel this plugin connects. Use one of: ${CHANNEL_IDS.join(", ")}.`);
+	return channel;
+}
+const str = (value) => value === void 0 || value === null ? null : String(value);
+function summarizeConnection(channel, wire) {
+	const details = {};
+	for (const field of channel.detailFields) details[field] = wire[field] ?? null;
+	return {
+		channel: channel.id,
+		connected: wire["status"] === "connected",
+		id: Number(wire["id"]),
+		status: String(wire["status"] ?? "unknown"),
+		account: {
+			id: str(wire[channel.accountIdField]),
+			name: str(wire[channel.accountNameField])
+		},
+		connectedAt: str(wire["connected_at"]),
+		disconnectedAt: str(wire["disconnected_at"]),
+		accessTokenExpiresAt: str(wire["access_token_expires_at"]),
+		lastError: wire["last_error"] ?? null,
+		details
+	};
+}
+function summarizeListing(channel, wire) {
+	const review = {};
+	for (const field of channel.reviewFields) review[field] = wire[field] ?? null;
+	return {
+		id: Number(wire["id"]),
+		productId: Number(wire["product_id"]),
+		status: String(wire["status"] ?? "unknown"),
+		auditStatus: str(wire["audit_status"]),
+		channelProductId: str(wire[channel.channelProductIdField]),
+		review,
+		lastPublishedAt: str(wire["last_published_at"]),
+		lastSyncedAt: str(wire["last_synced_at"]),
+		lastError: wire["last_error"] ?? null
+	};
+}
+/** A listing that's no longer on the channel: removed by you (`deleted`),
+*  or, on TikTok, deactivated by you. Adding its product again re-lists it. */
+function isRemoved(listing) {
+	return listing.status === "deleted" || listing.status === "seller_deactivated";
+}
+/** A listing whose product is on the channel now, or has been sent to it. */
+function isListed(listing) {
+	return !isRemoved(listing);
+}
+//#endregion
+//#region src/schemas.ts
+/** A connection as the API returns it. Channel-specific fields pass through. */
+const connectionWire = z.looseObject({
+	id: z.number(),
+	status: z.string()
+});
+const connectionResponse = z.object({ connection: connectionWire });
+const authorizeUrlResponse = z.object({ url: z.string().min(1) });
+/** A listing as the API returns it. Channel-specific fields pass through. */
+const listingWire = z.looseObject({
+	id: z.number(),
+	product_id: z.number(),
+	status: z.string(),
+	audit_status: z.string().nullish()
+});
+/** The cursor block of a listings page; the rows are read with listingsResponse. */
+const listingsPageMeta = z.object({ meta: z.object({ pagination: z.object({ next_cursor: z.string().nullish() }).optional() }).optional() });
+const listingResponse = (key) => z.object({ [key]: listingWire });
+const listingsResponse = (key) => z.object({ [key]: z.array(listingWire) });
+const productsPage = z.object({
+	products: z.array(z.looseObject({
+		id: z.number(),
+		title: z.string().nullish()
+	})),
+	meta: z.object({ pagination: z.object({ total_pages: z.number().nullish() }).optional() }).optional()
+});
+const collectionsPage = z.object({
+	collections: z.array(z.looseObject({
+		id: z.number(),
+		title: z.string().nullish()
+	})),
+	meta: z.object({ pagination: z.object({ next_cursor: z.string().nullish() }).optional() }).optional()
+});
+const productIdsInput = z.object({ product_ids: z.array(z.number().int().positive()).min(1) });
+const warehouseInput = z.object({ tiktok_warehouse_id: z.string().trim().min(1) });
+const regionInput = z.object({ region: z.enum(["US", "GLOBAL"]) });
+/** Validate a request body before it's sent, naming the bad input. */
+function validateInput(schema, data, what) {
+	const result = schema.safeParse(data);
+	if (result.success) return result.data;
+	throw new ChannelsError(`Invalid ${what}: ${result.error.issues[0]?.message ?? "invalid value"}.`);
+}
+/** Validate a response against a schema, naming what was being read on failure. */
+function parse(schema, data, what) {
+	const result = schema.safeParse(data);
+	if (result.success) return result.data;
+	const issue = result.error.issues[0];
+	throw new ChannelsError(`Fluid returned an unexpected ${what}${issue && issue.path.length > 0 ? ` at ${issue.path.join(".")}` : ""}: ${issue?.message ?? "invalid shape"}.`);
+}
+//#endregion
+//#region src/api.ts
+const LISTING_PAGE_SIZE = 100;
+const MAX_LISTING_PAGES = 100;
+const PRODUCT_PAGE_SIZE = 100;
+const MAX_PRODUCT_PAGES = 100;
+function statusOf(err) {
+	const status = err?.status;
+	return typeof status === "number" ? status : void 0;
+}
+/** The channel's connection, or a not-connected marker when the company has
+*  none (the API answers 404). */
+async function getConnection(client, channel) {
+	try {
+		return summarizeConnection(channel, parse(connectionResponse, await client.get(`${channel.base}/connection`), `${channel.label} connection`).connection);
+	} catch (err) {
+		if (statusOf(err) === 404) return {
+			channel: channel.id,
+			connected: false,
+			status: "not_connected"
+		};
+		throw err;
+	}
+}
+/** Requires a connection; listings and disconnect have nothing to act on
+*  without one. */
+async function requireConnection(client, channel) {
+	const connection = await getConnection(client, channel);
+	if (!("id" in connection)) throw new ChannelsError(`This company has no ${channel.label} connection. Run fluid channels connect ${channel.id} first.`);
+	return connection;
+}
+/** Ask Fluid for the channel's sign-in URL. A person opens it, approves
+*  Fluid's access on the channel, and the channel sends them back to Fluid,
+*  which saves the connection. */
+async function authorizeUrl(client, channel, options = {}) {
+	const body = channel.id === "tiktok" ? validateInput(regionInput, { region: options.region ?? "US" }, "--region") : {};
+	return parse(authorizeUrlResponse, await client.post(`${channel.base}/connection/authorize_url`, body), "sign-in URL response").url;
+}
+async function disconnect(client, channel) {
+	return summarizeConnection(channel, parse(connectionResponse, await client.delete(`${channel.base}/connection`), "disconnect response").connection);
+}
+async function setTiktokWarehouse(client, channel, tiktokWarehouseId) {
+	const body = validateInput(warehouseInput, { tiktok_warehouse_id: tiktokWarehouseId }, "TikTok warehouse ID");
+	return summarizeConnection(channel, parse(connectionResponse, await client.patch(`${channel.base}/connection`, body), "warehouse update response").connection);
+}
+/** Every listing on the connection, newest first. */
+async function listListings(client, channel) {
+	const all = [];
+	let cursor;
+	for (let page = 0; page < MAX_LISTING_PAGES; page += 1) {
+		const raw = await client.get(`${channel.base}/${channel.listings}`, { page: {
+			limit: LISTING_PAGE_SIZE,
+			...cursor ? { cursor } : {}
+		} });
+		const what = `${channel.label} listings page`;
+		const rows = parse(listingsResponse(channel.listings), raw, what)[channel.listings];
+		all.push(...rows.map((row) => summarizeListing(channel, row)));
+		const next = parse(listingsPageMeta, raw, what).meta?.pagination?.next_cursor;
+		if (!next || rows.length === 0) return all;
+		cursor = next;
+	}
+	throw new ChannelsError(`This connection has more than ${MAX_LISTING_PAGES * LISTING_PAGE_SIZE} listings; refusing to act on a partial list.`);
+}
+/** The company's active products, optionally only those in the given
+*  collections. Draft and archived products are never sent to a channel. */
+async function listActiveProducts(client, collectionIds = []) {
+	const byId = /* @__PURE__ */ new Map();
+	for (let page = 1; page <= MAX_PRODUCT_PAGES; page += 1) {
+		const data = parse(productsPage, await client.get("/api/v2025-06/products", {
+			page,
+			per_page: PRODUCT_PAGE_SIZE,
+			status: ["active"],
+			...collectionIds.length > 0 ? { collection_ids: collectionIds } : {}
+		}), "product list page");
+		const products = data.products;
+		for (const p of products) byId.set(p.id, {
+			id: p.id,
+			title: p.title ?? `Product ${p.id}`
+		});
+		const totalPages = data.meta?.pagination?.total_pages;
+		if (totalPages != null ? page >= totalPages : products.length < PRODUCT_PAGE_SIZE) return [...byId.values()];
+	}
+	throw new ChannelsError(`This company has more than ${MAX_PRODUCT_PAGES * PRODUCT_PAGE_SIZE} active products; refusing to add a partial catalog.`);
+}
+/** IDs of the company's active products; see listActiveProducts. */
+async function listActiveProductIds(client, collectionIds = []) {
+	return (await listActiveProducts(client, collectionIds)).map((p) => p.id);
+}
+/** Every collection on the company, for picking which to send. */
+async function listCollections(client) {
+	const all = [];
+	let cursor;
+	for (let page = 0; page < MAX_LISTING_PAGES; page += 1) {
+		const data = parse(collectionsPage, await client.get("/api/v202604/company/collections", { page: {
+			limit: 100,
+			...cursor ? { cursor } : {}
+		} }), "collection list page");
+		all.push(...data.collections.map((c) => ({
+			id: c.id,
+			title: c.title ?? `Collection ${c.id}`
+		})));
+		const next = data.meta?.pagination?.next_cursor;
+		if (!next || data.collections.length === 0) return all;
+		cursor = next;
+	}
+	throw new ChannelsError("This company has too many collections to list.");
+}
+/**
+* Decide which products to send. A product already on the channel is
+* skipped. One you removed earlier is skipped too, unless you ask to bring
+* removed products back, so adding the whole catalog never undoes a
+* deliberate removal.
+*/
+function planAdd(productIds, listings, includeRemoved) {
+	const byProduct = new Map(listings.map((l) => [l.productId, l]));
+	const plan = {
+		toAdd: [],
+		alreadyListed: [],
+		previouslyRemoved: []
+	};
+	for (const id of new Set(productIds)) {
+		const listing = byProduct.get(id);
+		if (!listing) plan.toAdd.push(id);
+		else if (isListed(listing)) plan.alreadyListed.push(id);
+		else if (includeRemoved) plan.toAdd.push(id);
+		else plan.previouslyRemoved.push(id);
+	}
+	return plan;
+}
+/** Send products to the channel in batches. Each new listing starts as a
+*  draft and publishes in the background. */
+async function addProducts(client, channel, productIds) {
+	const added = [];
+	for (let start = 0; start < productIds.length; start += 50) {
+		const batch = productIds.slice(start, start + 50);
+		try {
+			const body = validateInput(productIdsInput, { product_ids: batch }, "product IDs");
+			const rows = parse(listingsResponse(channel.listings), await client.post(`${channel.base}/${channel.listings}`, body), "publish response")[channel.listings];
+			added.push(...rows.map((row) => summarizeListing(channel, row)));
+		} catch (err) {
+			if (added.length === 0) throw err;
+			throw new ChannelsError(`Added ${added.length} product(s), then a batch failed: ${err instanceof Error ? err.message : String(err)}. Run the same command again to continue; products already added are skipped.`);
+		}
+	}
+	return added;
+}
+/** Find the listing for each product ID, refusing names that have none. */
+function listingsForProducts(productIds, listings) {
+	const byProduct = new Map(listings.map((l) => [l.productId, l]));
+	const found = [];
+	const notListed = [];
+	for (const id of new Set(productIds)) {
+		const listing = byProduct.get(id);
+		if (listing && isListed(listing)) found.push(listing);
+		else notListed.push(id);
+	}
+	return {
+		found,
+		notListed
+	};
+}
+/** Take a listing off the channel. A published listing is withdrawn from
+*  the channel; one that never published is just marked removed. */
+async function removeListing(client, channel, listingId) {
+	return summarizeListing(channel, parse(listingResponse(channel.listing), await client.delete(`${channel.base}/${channel.listings}/${encodeURIComponent(String(listingId))}`), "remove response")[channel.listing]);
+}
+/** Re-run a failed publish. Only listings whose status is publish_failed
+*  can be retried. */
+async function retryListing(client, channel, listingId) {
+	return summarizeListing(channel, parse(listingResponse(channel.listing), await client.post(`${channel.base}/${channel.listings}/${encodeURIComponent(String(listingId))}/retry`), "retry response")[channel.listing]);
+}
+//#endregion
+//#region src/browser.ts
+/** Open a URL in the default browser. Returns false when there's no way to. */
+function openInBrowser(url) {
+	const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+	try {
+		const child = spawn(command, args, {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.on("error", () => void 0);
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/issues.ts
+/** Fixes for the failure types Fluid records when it can't send a product. */
+const HINTS = {
+	missing_description: "Give the product a description in Fluid, then retry.",
+	missing_package_dimensions: "Give at least one variant a positive package length, width, height, and weight in Fluid, then retry.",
+	missing_mandatory_attribute: "TikTok's category for this product requires the attributes named in the error. Check the product's category in TikTok Seller Center.",
+	warehouse_not_configured: "Choose the TikTok warehouse first: fluid channels warehouse tiktok <tiktok-warehouse-id> --yes. Then retry.",
+	warehouse_not_mapped: "No Fluid warehouse is linked to this TikTok warehouse ID yet. The CLI can't link one; ask Fluid support to, then run fluid channels warehouse tiktok <tiktok-warehouse-id> --yes again.",
+	missing_sku: "Give every active variant a SKU in Fluid, then retry.",
+	duplicate_sku: "Another listing on this channel already uses the SKU. Make each variant's SKU unique, then retry.",
+	no_variants: "The product has no active variants. Activate at least one variant, then retry.",
+	connection_inactive: "The connection isn't active. Reconnect with fluid channels connect, then retry."
+};
+function errorOf(listing) {
+	const error = listing.lastError;
+	if (!error || typeof error !== "object") return {
+		type: null,
+		message: typeof error === "string" ? error : null
+	};
+	const record = error;
+	return {
+		type: typeof record["type"] === "string" ? record["type"] : null,
+		message: typeof record["description"] === "string" ? record["description"] : typeof record["message"] === "string" ? record["message"] : null
+	};
+}
+function actionFor(listing) {
+	if (isRemoved(listing)) return null;
+	if (listing.status === "publish_failed") return "retry";
+	if (listing.status === "platform_deactivated" || listing.status === "frozen") return "resolve_on_channel";
+	if (listing.auditStatus === "audit_failed") return "fix_and_relist";
+	return null;
+}
+const ACTION_HINTS = {
+	retry: "Fix what the error names, then retry.",
+	fix_and_relist: "The channel's review rejected the product. Fix it in Fluid, then remove it and add it again so the corrected product is sent.",
+	resolve_on_channel: "The channel deactivated or froze the listing. Check the reason in the channel's seller tools."
+};
+function findIssues(listings) {
+	const issues = [];
+	for (const listing of listings) {
+		const action = actionFor(listing);
+		if (!action) continue;
+		const { type, message } = errorOf(listing);
+		issues.push({
+			listingId: listing.id,
+			productId: listing.productId,
+			status: listing.status,
+			auditStatus: listing.auditStatus,
+			action,
+			errorType: type,
+			error: message,
+			hint: action === "retry" && type && HINTS[type] || ACTION_HINTS[action]
+		});
+	}
+	return issues;
+}
+function countListings(listings) {
+	const byStatus = {};
+	const byAuditStatus = {};
+	let listed = 0;
+	for (const listing of listings) {
+		byStatus[listing.status] = (byStatus[listing.status] ?? 0) + 1;
+		const audit = listing.auditStatus ?? "none";
+		byAuditStatus[audit] = (byAuditStatus[audit] ?? 0) + 1;
+		if (isListed(listing)) listed += 1;
+	}
+	return {
+		total: listings.length,
+		listed,
+		issues: findIssues(listings).length,
+		byStatus,
+		byAuditStatus
+	};
+}
+//#endregion
+//#region src/walk.ts
+const STAGE_NAMES = {
+	channel: "Pick the channel",
+	connect: "Connect",
+	warehouse: "TikTok warehouse",
+	catalog: "Choose the products",
+	issues: "Fix issues"
+};
+const isConnected = (c) => c.connected === true;
+/** A reply's navigation as a stage outcome; null when it's an answer. */
+function navOutcome(reply) {
+	if (!("nav" in reply)) return null;
+	return {
+		back: "back",
+		skip: "skip",
+		menu: "menu",
+		quit: "quit"
+	}[reply.nav];
+}
+async function walkChannels(deps) {
+	const { api, prompter } = deps;
+	let channel = deps.channel ? channelOf(deps.channel) : null;
+	let connected = false;
+	let warehouseSet = false;
+	let added = 0;
+	let retried = 0;
+	const skipped = /* @__PURE__ */ new Set();
+	const history = [];
+	const stages = () => [
+		...deps.channel ? [] : ["channel"],
+		"connect",
+		...channel?.id === "tiktok" ? ["warehouse"] : [],
+		"catalog",
+		"issues"
+	];
+	const ask = (q) => prompter.ask({
+		...q,
+		canGoBack: history.length > 0
+	});
+	/** Every live change asks first. Navigating away counts as no. */
+	const confirm = async (message) => {
+		const reply = await ask({
+			section: "Confirm",
+			message,
+			kind: "select",
+			choices: [{
+				title: "Yes, do it",
+				value: "yes"
+			}, {
+				title: "No",
+				value: "no"
+			}]
+		});
+		return "value" in reply && reply.value === "yes";
+	};
+	const failed = (error) => prompter.note(`Not done: ${error instanceof Error ? error.message : String(error)}`);
+	/** The connection, or a note and a jump to Connect when there isn't one. */
+	const requireConnected = async (current) => {
+		const connection = await getConnection(api, current);
+		if (isConnected(connection)) return connection;
+		prompter.note(`${current.label} isn't connected yet. Connect it first.`);
+		return { jump: "connect" };
+	};
+	const pickChannel = async () => {
+		const choices = [];
+		for (const id of CHANNEL_IDS) {
+			const c = CHANNELS[id];
+			const connection = await getConnection(api, c);
+			choices.push({
+				title: c.label,
+				value: id,
+				description: isConnected(connection) ? `connected${connection.account.name ? ` to ${connection.account.name}` : ""}` : "not connected"
+			});
+		}
+		const reply = await ask({
+			section: STAGE_NAMES.channel,
+			message: "Which channel?",
+			kind: "select",
+			choices,
+			...channel ? { current: channel.label } : {}
+		});
+		const nav = navOutcome(reply);
+		if (nav) return nav;
+		channel = channelOf(reply.value);
+		return "next";
+	};
+	const connect = async (current) => {
+		const existing = await getConnection(api, current);
+		if (isConnected(existing)) {
+			connected = true;
+			const reply = await ask({
+				section: STAGE_NAMES.connect,
+				message: `${current.label} is connected${existing.account.name ? ` to ${existing.account.name}` : ""}.`,
+				kind: "select",
+				choices: [{
+					title: "Continue",
+					value: "continue"
+				}, {
+					title: "Approve again",
+					value: "reconnect",
+					description: "for a new account, or after access expired"
+				}]
+			});
+			const nav = navOutcome(reply);
+			if (nav) return nav;
+			if (reply.value === "continue") return "next";
+		}
+		let url = await authorizeUrl(api, current);
+		const show = (link) => {
+			prompter.note(`Open this link in a browser signed in to the ${current.label} account and approve Fluid's access. It works once, for 10 minutes:\n${link}`);
+			if (deps.open?.(link)) prompter.note("Opened it in your browser.");
+		};
+		show(url);
+		for (;;) {
+			const reply = await ask({
+				section: STAGE_NAMES.connect,
+				message: "Done approving?",
+				kind: "select",
+				choices: [{
+					title: "Yes, check the connection",
+					value: "check"
+				}, {
+					title: "Get a new link",
+					value: "link"
+				}]
+			});
+			const nav = navOutcome(reply);
+			if (nav) return nav;
+			if (reply.value === "link") {
+				url = await authorizeUrl(api, current);
+				show(url);
+				continue;
+			}
+			const after = await getConnection(api, current);
+			if (isConnected(after)) {
+				connected = true;
+				prompter.note(`Connected${after.account.name ? ` to ${after.account.name}` : ""}.`);
+				return "next";
+			}
+			prompter.note(`Not connected yet (status: ${after.status}). Finish approving in the browser, or get a new link if it expired.`);
+		}
+	};
+	const warehouse = async (current) => {
+		const connection = await requireConnected(current);
+		if ("jump" in connection) return connection;
+		const saved = connection.details["tiktok_warehouse_id"];
+		const reply = await ask({
+			section: STAGE_NAMES.warehouse,
+			message: "TikTok warehouse ID to publish inventory from",
+			kind: "text",
+			hint: "from TikTok Seller Center",
+			...typeof saved === "string" && saved ? { current: saved } : {}
+		});
+		const nav = navOutcome(reply);
+		if (nav) return nav;
+		const value = reply.value.trim();
+		if (value === "") {
+			if (typeof saved === "string" && saved) return "next";
+			prompter.note("Type the warehouse ID, or > to skip.");
+			return "stay";
+		}
+		if (value === saved) return "next";
+		if (!await confirm(`Publish inventory from TikTok warehouse ${value}?`)) return "stay";
+		try {
+			await setTiktokWarehouse(api, current, value);
+		} catch (error) {
+			failed(error);
+			prompter.note("Fluid only accepts a TikTok warehouse ID that a Fluid warehouse is linked to. If it isn't linked, ask Fluid support.");
+			return "stay";
+		}
+		warehouseSet = true;
+		prompter.note(`Inventory publishes from TikTok warehouse ${value}.`);
+		return "next";
+	};
+	/** Pick several items from a searchable list. Returns the picked IDs, or
+	*  a navigation outcome. `<` with picks undoes the last one. */
+	const pickMany = async (message, items) => {
+		const picked = [];
+		for (;;) {
+			const remaining = items.filter((item) => !picked.includes(item.id));
+			const reply = await ask({
+				section: STAGE_NAMES.catalog,
+				message: `${message} (${picked.length} picked)`,
+				kind: "search",
+				hint: "type to search; < undoes the last pick",
+				choices: [{
+					title: `Done picking (${picked.length})`,
+					value: "done"
+				}, ...remaining.map((item) => ({
+					title: item.title,
+					value: String(item.id)
+				}))]
+			});
+			if ("nav" in reply && reply.nav === "back" && picked.length > 0) {
+				picked.pop();
+				continue;
+			}
+			const nav = navOutcome(reply);
+			if (nav) return nav;
+			const value = reply.value;
+			if (value === "done") return picked;
+			picked.push(Number(value));
+		}
+	};
+	const sendProducts = async (current, productIds, { explicit = false } = {}) => {
+		const plan = planAdd(productIds, await listListings(api, current), explicit);
+		if (plan.previouslyRemoved.length > 0) prompter.note(`${plan.previouslyRemoved.length} product(s) you removed earlier stay off. Re-add them with fluid channels catalog ${current.id} --add <ids> --include-removed --yes.`);
+		if (plan.toAdd.length === 0) {
+			prompter.note(`Nothing new to send; ${plan.alreadyListed.length} already listed.`);
+			return "next";
+		}
+		if (!await confirm(`Send ${plan.toAdd.length} product(s) to ${current.label}?`)) return "stay";
+		try {
+			const listings = await addProducts(api, current, plan.toAdd);
+			added += listings.length;
+		} catch (error) {
+			failed(error);
+			return "stay";
+		}
+		prompter.note(`Sent ${plan.toAdd.length}. Each publishes in the background, and ${current.label} reviews it; check later with fluid channels status ${current.id}.`);
+		return "next";
+	};
+	const catalog = async (current) => {
+		const connection = await requireConnected(current);
+		if ("jump" in connection) return connection;
+		const counts = countListings(await listListings(api, current));
+		const reply = await ask({
+			section: STAGE_NAMES.catalog,
+			message: `Which products go to ${current.label}? (${counts.listed} listed now)`,
+			kind: "select",
+			choices: [
+				{
+					title: "Whole catalog",
+					value: "all",
+					description: "every active product not listed yet; products you create later need another run"
+				},
+				{
+					title: "Whole collections",
+					value: "collections",
+					description: "the active products in the collections you pick"
+				},
+				{
+					title: "Selected products",
+					value: "selected",
+					description: "only the products you pick; best for trying a few first"
+				},
+				{
+					title: "Leave them as they are",
+					value: "none"
+				}
+			]
+		});
+		const nav = navOutcome(reply);
+		if (nav) return nav;
+		const choice = reply.value;
+		if (choice === "none") return "next";
+		if (choice === "all") return sendProducts(current, await listActiveProductIds(api));
+		if (choice === "collections") {
+			const collections = await listCollections(api);
+			if (collections.length === 0) {
+				prompter.note("This company has no collections.");
+				return "stay";
+			}
+			const ids = await pickMany("Pick collections", collections);
+			if (!Array.isArray(ids)) return ids === "back" ? "stay" : ids;
+			if (ids.length === 0) return "stay";
+			return sendProducts(current, await listActiveProductIds(api, ids));
+		}
+		const products = await listActiveProducts(api);
+		if (products.length === 0) {
+			prompter.note("This company has no active products.");
+			return "stay";
+		}
+		const ids = await pickMany("Pick products", products);
+		if (!Array.isArray(ids)) return ids === "back" ? "stay" : ids;
+		if (ids.length === 0) return "stay";
+		return sendProducts(current, ids, { explicit: true });
+	};
+	const issues = async (current) => {
+		const connection = await requireConnected(current);
+		if ("jump" in connection) return connection;
+		const found = findIssues(await listListings(api, current));
+		if (found.length === 0) {
+			prompter.note(`No issues. Products still publishing or in review show in fluid channels status ${current.id}.`);
+			return "next";
+		}
+		for (const issue of found.slice(0, 10)) prompter.note(`Product ${issue.productId} (${issue.status}${issue.auditStatus ? `, ${issue.auditStatus}` : ""}): ${issue.error ? `${issue.error}. ` : ""}${issue.hint}`);
+		if (found.length > 10) prompter.note(`…and ${found.length - 10} more: fluid channels issues ${current.id}`);
+		const retryable = found.filter((issue) => issue.action === "retry");
+		const reply = await ask({
+			section: STAGE_NAMES.issues,
+			message: `${found.length} issue(s). Fix the products in Fluid, then:`,
+			kind: "select",
+			choices: [
+				...retryable.length > 0 ? [{
+					title: `Retry ${retryable.length} failed publish(es)`,
+					value: "retry"
+				}] : [],
+				{
+					title: "Check again",
+					value: "check"
+				},
+				{
+					title: "Done for now",
+					value: "done"
+				}
+			]
+		});
+		const nav = navOutcome(reply);
+		if (nav) return nav;
+		const choice = reply.value;
+		if (choice === "done") return "next";
+		if (choice === "check") return "stay";
+		if (!await confirm(`Retry ${retryable.length} failed publish(es) on ${current.label}?`)) return "stay";
+		for (const issue of retryable) try {
+			await retryListing(api, current, issue.listingId);
+			retried += 1;
+		} catch (error) {
+			failed(error);
+		}
+		prompter.note(`Retried ${retried}. They publish in the background.`);
+		return "stay";
+	};
+	const runStage = async (stage) => {
+		if (stage === "channel") return pickChannel();
+		if (!channel) return { jump: "channel" };
+		if (stage === "connect") return connect(channel);
+		if (stage === "warehouse") return warehouse(channel);
+		if (stage === "catalog") return catalog(channel);
+		return issues(channel);
+	};
+	/** The menu: jump to any stage, or stop. */
+	const openMenu = async () => {
+		return await prompter.menu("Where to?", [...stages().map((stage) => ({
+			title: `${skipped.has(stage) ? "skipped  " : ""}${STAGE_NAMES[stage]}`,
+			value: stage,
+			disabled: stage !== "channel" && !channel
+		})), {
+			title: "Stop for now",
+			value: "quit"
+		}]);
+	};
+	prompter.note(NAV_HELP);
+	let stage = stages()[0];
+	let finished = false;
+	for (;;) {
+		const outcome = await runStage(stage);
+		if (outcome === "quit") break;
+		if (outcome === "stay") continue;
+		if (typeof outcome === "object") {
+			history.push(stage);
+			stage = outcome.jump;
+			continue;
+		}
+		if (outcome === "back") {
+			const previous = history.pop();
+			if (previous) stage = previous;
+			else prompter.note("This is the first step.");
+			continue;
+		}
+		if (outcome === "menu") {
+			const choice = await openMenu();
+			if (choice === "quit") break;
+			if (choice) {
+				history.push(stage);
+				stage = choice;
+			}
+			continue;
+		}
+		if (outcome === "skip") skipped.add(stage);
+		else skipped.delete(stage);
+		const order = stages();
+		const next = order[order.indexOf(stage) + 1];
+		history.push(stage);
+		if (!next) {
+			finished = true;
+			break;
+		}
+		stage = next;
+	}
+	if (finished && channel) prompter.note(`Done. Check how the products sync with fluid channels status ${channel.id}, and fix rejections with fluid channels issues ${channel.id}.`);
+	return {
+		channel: channel?.id ?? null,
+		connected,
+		warehouseSet,
+		added,
+		retried,
+		skipped: [...skipped],
+		finished
+	};
+}
+//#endregion
+//#region src/index.ts
+async function client(ctx) {
+	return await ctx.getClient();
+}
+/**
+* Changes to a live channel need an explicit yes. Scripts and agents pass
+* `--yes`; an interactive terminal is asked. With neither, nothing runs.
+*/
+async function confirmChange(question, yes, interactive = Boolean(process.stdin.isTTY)) {
+	if (yes) return;
+	if (!interactive) throw new ChannelsError(`${question} Pass --yes to confirm.`);
+	if (!(await prompts({
+		type: "confirm",
+		name: "ok",
+		message: question,
+		initial: false
+	})).ok) throw new ChannelsError("Cancelled.");
+}
+/** The error the API sent back, as `{ message, details }`, when there is one. */
+function apiError(err) {
+	const body = err?.body;
+	if (!body || typeof body !== "object") return {};
+	const error = body["error"];
+	if (error && typeof error === "object") {
+		const record = error;
+		const details = record["details"];
+		return {
+			...typeof record["message"] === "string" ? { message: record["message"] } : {},
+			...details && typeof details === "object" && Object.keys(details).length > 0 ? { details } : {}
+		};
+	}
+	if (typeof error === "string") return { message: error };
+	if (typeof body["error_message"] === "string") return { message: body["error_message"] };
+	return {};
+}
+/** Print a failure as JSON on stderr and exit non-zero, so scripts and
+*  agents can read it the same way as a success. */
+function fail(err) {
+	const rawStatus = err?.status;
+	const status = typeof rawStatus === "number" ? rawStatus : void 0;
+	const fromApi = apiError(err);
+	const message = fromApi.message ?? (err instanceof Error ? err.message : String(err));
+	process.stderr.write(JSON.stringify({
+		error: message,
+		...status ? { status } : {},
+		...fromApi.details ? { details: fromApi.details } : {}
+	}) + "\n");
+	process.exitCode = 1;
+}
+function run(action) {
+	return action().catch(fail);
+}
+const collect = (value, previous = []) => [...previous, value];
+/** Product, listing, or collection IDs from repeatable, comma-separated flags. */
+function parseIds(values, flag) {
+	const ids = [];
+	for (const value of values) for (const part of value.split(",")) {
+		const trimmed = part.trim();
+		if (trimmed === "") continue;
+		if (!/^\d+$/.test(trimmed) || Number(trimmed) <= 0) throw new ChannelsError(`${flag} takes numeric IDs; "${trimmed}" isn't one.`);
+		ids.push(Number(trimmed));
+	}
+	return [...new Set(ids)];
+}
+/** Exactly one catalog change per run, or none to list the listings. */
+function catalogMode(opts) {
+	const chosen = [
+		opts.all && "all",
+		opts.add.length > 0 && "add",
+		opts.remove.length > 0 && "remove",
+		opts.removeAll && "remove-all"
+	].filter(Boolean);
+	if (chosen.length > 1) throw new ChannelsError("Use one of --all, --add, --remove, or --remove-all per run.");
+	if (opts.collection.length > 0 && !opts.all) throw new ChannelsError("--collection goes with --all.");
+	if (opts.includeRemoved && !opts.all && opts.add.length === 0) throw new ChannelsError("--include-removed goes with --all or --add.");
+	return chosen[0] ?? "list";
+}
+async function removeEach(api, channel, listings) {
+	const removed = [];
+	const failed = [];
+	for (const listing of listings) try {
+		removed.push(await removeListing(api, channel, listing.id));
+	} catch (err) {
+		failed.push({
+			productId: listing.productId,
+			error: apiError(err).message ?? (err instanceof Error ? err.message : String(err))
+		});
+	}
+	return {
+		removed,
+		failed
+	};
+}
+/** Print a result that has per-item failures, and exit non-zero when any did. */
+function outputWithFailures(ctx, result) {
+	ctx.output(result);
+	if (result.failed.length > 0) {
+		process.stderr.write(JSON.stringify({ error: `${result.failed.length} item(s) failed; see failed in the output.` }) + "\n");
+		process.exitCode = 1;
+	}
+}
+function registerChannelCommands(parent, ctx) {
+	parent.command("list").description(`Show ${CHANNEL_IDS.join(", ")} and whether each is connected`).action(() => run(async () => {
+		const api = await client(ctx);
+		const rows = [];
+		for (const id of CHANNEL_IDS) {
+			const channel = CHANNELS[id];
+			const connection = await getConnection(api, channel);
+			rows.push({
+				label: channel.label,
+				...connection
+			});
+		}
+		ctx.output(rows);
+	}));
+	parent.command("connect <channel>").description("Print the URL a person opens to approve Fluid's access on the channel; --open opens it in a browser").option("--region <region>", "TikTok Shop only: US or GLOBAL", "US").option("--open", "Open the URL in the default browser", false).action((channelId, opts) => run(async () => {
+		const channel = channelOf(channelId);
+		const region = opts.region.trim().toUpperCase();
+		if (channel.id === "tiktok" && region !== "US" && region !== "GLOBAL") throw new ChannelsError(`--region is US or GLOBAL, not "${opts.region}".`);
+		const api = await client(ctx);
+		const current = await getConnection(api, channel);
+		const url = await authorizeUrl(api, channel, { region });
+		const opened = opts.open ? openInBrowser(url) : false;
+		ctx.output({
+			channel: channel.id,
+			alreadyConnected: current.connected,
+			url,
+			opened,
+			next: `Open the URL in a browser signed in to the ${channel.label} account, approve the access, then run: fluid channels status ${channel.id}. The link works once and expires; run connect again for a new one.`
+		});
+	}));
+	parent.command("status <channel>").description("Show the connection and a count of its listings by status").action((channelId) => run(async () => {
+		const channel = channelOf(channelId);
+		const api = await client(ctx);
+		const connection = await getConnection(api, channel);
+		if (!("id" in connection)) {
+			ctx.output({
+				connection,
+				listings: null
+			});
+			return;
+		}
+		ctx.output({
+			connection,
+			listings: countListings(await listListings(api, channel))
+		});
+	}));
+	parent.command("catalog <channel>").description("List the products on the channel, or change them: --all, --add, --remove, or --remove-all (changes live config)").option("--all", "Add every active product (or every active product in --collection) not already listed", false).option("--collection <ids>", "With --all, only products in these collections (repeatable, comma-separated)", collect, []).option("--include-removed", "With --all or --add, also re-add products you removed earlier", false).option("--add <ids>", "Add these product IDs (repeatable, comma-separated)", collect, []).option("--remove <ids>", "Remove these product IDs from the channel (repeatable, comma-separated)", collect, []).option("--remove-all", "Remove every listed product from the channel", false).option("--yes", "Confirm without a prompt", false).action((channelId, opts) => run(async () => {
+		const channel = channelOf(channelId);
+		const mode = catalogMode(opts);
+		const api = await client(ctx);
+		await requireConnection(api, channel);
+		const listings = await listListings(api, channel);
+		if (mode === "list") {
+			ctx.output({
+				channel: channel.id,
+				counts: countListings(listings),
+				listings
+			});
+			return;
+		}
+		if (mode === "all" || mode === "add") {
+			const collections = parseIds(opts.collection, "--collection");
+			const requested = mode === "all" ? await listActiveProductIds(api, collections) : parseIds(opts.add, "--add");
+			const plan = planAdd(requested, listings, opts.includeRemoved);
+			const summary = {
+				channel: channel.id,
+				mode,
+				...mode === "all" ? {
+					collections,
+					activeProducts: requested.length
+				} : {},
+				alreadyListed: plan.alreadyListed.length,
+				previouslyRemoved: plan.previouslyRemoved
+			};
+			if (plan.toAdd.length === 0) {
+				ctx.output({
+					...summary,
+					added: 0,
+					listings: []
+				});
+				return;
+			}
+			await confirmChange(`Send ${plan.toAdd.length} product(s) to ${channel.label}?`, opts.yes);
+			const added = await addProducts(api, channel, plan.toAdd);
+			ctx.output({
+				...summary,
+				added: added.length,
+				listings: added,
+				next: `Each product publishes in the background. Check progress with: fluid channels status ${channel.id}`
+			});
+			return;
+		}
+		const targets = mode === "remove-all" ? {
+			found: listings.filter(isListed),
+			notListed: []
+		} : listingsForProducts(parseIds(opts.remove, "--remove"), listings);
+		if (targets.found.length === 0) {
+			ctx.output({
+				channel: channel.id,
+				mode,
+				removed: [],
+				notListed: targets.notListed,
+				failed: []
+			});
+			return;
+		}
+		await confirmChange(`Remove ${targets.found.length} product(s) from ${channel.label}?`, opts.yes);
+		const result = await removeEach(api, channel, targets.found);
+		outputWithFailures(ctx, {
+			channel: channel.id,
+			mode,
+			removed: result.removed,
+			notListed: targets.notListed,
+			failed: result.failed
+		});
+	}));
+	parent.command("issues <channel>").description("List listings that failed to publish or were rejected, with what to do; --retry retries failed publishes (changes live config)").option("--retry", "Retry every listing whose publish failed", false).option("--yes", "Confirm --retry without a prompt", false).action((channelId, opts) => run(async () => {
+		const channel = channelOf(channelId);
+		const api = await client(ctx);
+		await requireConnection(api, channel);
+		const issues = findIssues(await listListings(api, channel));
+		if (!opts.retry) {
+			ctx.output({
+				channel: channel.id,
+				count: issues.length,
+				issues
+			});
+			return;
+		}
+		const retryable = issues.filter((issue) => issue.action === "retry");
+		if (retryable.length === 0) {
+			ctx.output({
+				channel: channel.id,
+				retried: [],
+				failed: [],
+				issues
+			});
+			return;
+		}
+		await confirmChange(`Retry ${retryable.length} failed publish(es) on ${channel.label}?`, opts.yes);
+		const retried = [];
+		const failed = [];
+		for (const issue of retryable) try {
+			retried.push(await retryListing(api, channel, issue.listingId));
+		} catch (err) {
+			failed.push({
+				productId: issue.productId,
+				error: apiError(err).message ?? (err instanceof Error ? err.message : String(err))
+			});
+		}
+		outputWithFailures(ctx, {
+			channel: channel.id,
+			retried,
+			failed
+		});
+	}));
+	parent.command("warehouse <channel> <tiktokWarehouseId>").description("TikTok Shop only: choose the TikTok warehouse whose inventory Fluid publishes (changes live config)").option("--yes", "Confirm without a prompt", false).action((channelId, tiktokWarehouseId, opts) => run(async () => {
+		const channel = channelOf(channelId);
+		if (channel.id !== "tiktok") throw new ChannelsError("Only TikTok Shop uses a warehouse setting.");
+		const id = tiktokWarehouseId.trim();
+		if (id === "") throw new ChannelsError("Pass the TikTok warehouse ID.");
+		const api = await client(ctx);
+		await requireConnection(api, channel);
+		await confirmChange(`Publish inventory from TikTok warehouse ${id}?`, opts.yes);
+		ctx.output(await setTiktokWarehouse(api, channel, id));
+	}));
+	parent.command("walk [channel]").description("Set a channel up question by question in the terminal: connect it, choose the products, fix issues; asks before each change (changes live config)").action((channelId) => run(async () => {
+		assertInteractive("`connect`, `status`, `catalog`, and `issues` with --yes");
+		if (channelId) channelOf(channelId);
+		ctx.output(await walkChannels({
+			api: await client(ctx),
+			prompter: terminalPrompter(),
+			...channelId ? { channel: channelId } : {},
+			open: openInBrowser
+		}));
+	}));
+	parent.command("disconnect <channel>").description("Disconnect the channel; products already on it stay there (changes live config)").option("--yes", "Confirm without a prompt", false).action((channelId, opts) => run(async () => {
+		const channel = channelOf(channelId);
+		const api = await client(ctx);
+		await requireConnection(api, channel);
+		const stillListed = (await listListings(api, channel)).filter(isListed).length;
+		const warning = stillListed > 0 ? ` ${stillListed} product(s) stay on ${channel.label} and stop syncing; remove them first with fluid channels catalog ${channel.id} --remove-all.` : "";
+		await confirmChange(`Disconnect ${channel.label}?${warning}`, opts.yes);
+		ctx.output({
+			connection: await disconnect(api, channel),
+			stillListed
+		});
+	}));
+}
+const plugin = {
+	name: "@fluid-app/fluid-cli-channels",
+	version: "0.1.0",
+	register(ctx) {
+		ctx.program.addCommand(createDomainCommand("channels", "Sales channels: connect TikTok Shop, Meta, or Google Merchant Center, choose the products, check sync, disconnect", registerChannelCommands));
+	}
+};
+//#endregion
+export { catalogMode, confirmChange, plugin as default, fail, parseIds, registerChannelCommands };
+
+//# sourceMappingURL=index.mjs.map