@hubfluencer/mcp 0.4.0 → 0.6.0

package/src/campaign.ts

@@ -0,0 +1,797 @@
+/**
+ * Pure, side-effect-light helpers for the campaign-engine tools (index.ts).
+ *
+ * Like core.ts / uploads.ts, this lives outside index.ts on purpose: index.ts
+ * registers every tool and connects an stdio transport at module load, so a unit
+ * test can't import it. The campaign tools' request-shape builders, response
+ * shaping, and — most importantly — the `create_campaign` orchestrator's
+ * step sequencing + partial-failure handling are extracted here so they are
+ * testable against a fake client.
+ *
+ * GROUND TRUTH (verified against the API controllers, 2026-07-02):
+ *   - product_source_controller.ex, product_profile_controller.ex,
+ *     brand_profile_controller.ex, campaign_pack_controller.ex.
+ *   - NONE of those four controllers mount `Plugs.Idempotency`, so the campaign
+ *     tools send NO Idempotency-Key (unlike the editor/tracking/slider tools).
+ *     A plain transport retry of a create is therefore NOT server-deduplicated;
+ *     the tool descriptions + `idempotentHint` reflect that honestly.
+ *   - plan + hook_variations meter the FREE daily AiAssistQuota (429
+ *     `ai_assist_quota_exceeded`, identical shape to the editor assists) and
+ *     spend no video credits. materialize / add-variations create 0-credit
+ *     DRAFTS. Nothing here ever starts paid generation.
+ */
+
+import { asRecord } from "./core.js";
+
+/** The narrow client surface the orchestrator needs — a subset of HubfluencerClient. */
+export interface CampaignClient {
+	get<T = unknown>(
+		path: string,
+		query?: Record<string, string | number | undefined>,
+	): Promise<T>;
+	post<T = unknown>(
+		path: string,
+		body?: unknown,
+		idempotencyKey?: string,
+	): Promise<T>;
+}
+
+/** A thrown API error carries an HTTP status (mirrors client.ts HubfluencerError). */
+function statusOf(e: unknown): number | undefined {
+	const s = (e as { status?: unknown })?.status;
+	return typeof s === "number" ? s : undefined;
+}
+
+// ── Product-profile field mapping ────────────────────────────────────────────
+
+// The product-profile create/update body accepts exactly these textual fields
+// (product_profile_controller.ex @product_fields). primary_image_s3_key /
+// logo_s3_key are set through the import-image flow, never passed here.
+export const PRODUCT_PROFILE_FIELDS = [
+	"name",
+	"source_url",
+	"description",
+	"benefits",
+	"offer",
+	"proof_points",
+	"audience",
+	"cta",
+	"banned_claims",
+	"brand_tone",
+	"metadata",
+] as const;
+
+/** The shape of the `product` block extract returns (ExtractedProduct schema). */
+export interface ExtractedProduct {
+	name?: string | null;
+	description?: string | null;
+	images?: string[];
+	logo?: string | null;
+	price?: string | null;
+	currency?: string | null;
+	brand?: string | null;
+	availability?: string | null;
+	benefits?: string[];
+	offer?: string | null;
+	proof_points?: string[];
+	audience?: string | null;
+	cta?: string | null;
+	banned_claims?: string[];
+	brand_tone?: string | null;
+}
+
+/**
+ * Maps the facts `extract` returns into a product-profile create/update body,
+ * keeping only the textual fields the profile controller accepts and dropping
+ * empties (so a partial extraction doesn't overwrite good saved data with null).
+ * `sourceUrl` is threaded in from the extraction envelope (the product block
+ * itself carries no URL). Image/logo URLs are handled by the import-image flow,
+ * not here, so they are intentionally excluded.
+ */
+export function extractedProductToProfileAttrs(
+	product: ExtractedProduct | undefined,
+	sourceUrl?: string,
+): Record<string, unknown> {
+	const p = product ?? {};
+	const attrs: Record<string, unknown> = {};
+	const str = (v: unknown): string | undefined => {
+		if (typeof v !== "string") return undefined;
+		const t = v.trim();
+		return t === "" ? undefined : t;
+	};
+	const list = (v: unknown): string[] | undefined => {
+		if (!Array.isArray(v)) return undefined;
+		const arr = v.filter(
+			(x): x is string => typeof x === "string" && x.trim() !== "",
+		);
+		return arr.length > 0 ? arr : undefined;
+	};
+
+	const name = str(p.name);
+	if (name !== undefined) attrs.name = name;
+	const description = str(p.description);
+	if (description !== undefined) attrs.description = description;
+	const benefits = list(p.benefits);
+	if (benefits !== undefined) attrs.benefits = benefits;
+	const offer = str(p.offer);
+	if (offer !== undefined) attrs.offer = offer;
+	const proof = list(p.proof_points);
+	if (proof !== undefined) attrs.proof_points = proof;
+	const audience = str(p.audience);
+	if (audience !== undefined) attrs.audience = audience;
+	const cta = str(p.cta);
+	if (cta !== undefined) attrs.cta = cta;
+	const banned = list(p.banned_claims);
+	if (banned !== undefined) attrs.banned_claims = banned;
+	const tone = str(p.brand_tone);
+	if (tone !== undefined) attrs.brand_tone = tone;
+	const src = str(sourceUrl);
+	if (src !== undefined) attrs.source_url = src;
+
+	return attrs;
+}
+
+/** Picks only the accepted product-profile fields from a raw args object. */
+export function pickProductProfileFields(
+	args: Record<string, unknown>,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const k of PRODUCT_PROFILE_FIELDS) {
+		if (args[k] !== undefined) out[k] = args[k];
+	}
+	return out;
+}
+
+// The brand-profile create/update body accepts exactly these fields
+// (brand_profile_controller.ex @brand_fields). Asset links are managed through
+// the separate attach/detach endpoints, not this body.
+export const BRAND_PROFILE_FIELDS = [
+	"name",
+	"logo_s3_key",
+	"primary_color",
+	"secondary_color",
+	"font_family",
+	"tone_words",
+	"default_cta",
+	"default_audience",
+	"banned_claims",
+	"preferred_visual_language",
+	"preferred_creative_format",
+	"metadata",
+] as const;
+
+/** Picks only the accepted brand-profile fields from a raw args object. */
+export function pickBrandProfileFields(
+	args: Record<string, unknown>,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const k of BRAND_PROFILE_FIELDS) {
+		if (args[k] !== undefined) out[k] = args[k];
+	}
+	return out;
+}
+
+// ── Plan / hook source validation ────────────────────────────────────────────
+
+/**
+ * plan + hook_variations require EITHER a product_profile_id OR an inline
+ * `product` object with a non-blank name (campaign_pack_controller
+ * parse_plan_params / parse_hook_params). Returns an error string, or null when
+ * the pair is valid. Kept in code (not Zod) so the flat schemas stay TS2589-safe
+ * and the message names the exact remedy.
+ */
+export function validatePlanSource(
+	productProfileId: number | undefined,
+	product: { name?: unknown } | undefined,
+): string | null {
+	const hasProfile =
+		typeof productProfileId === "number" &&
+		Number.isInteger(productProfileId) &&
+		productProfileId > 0;
+	const hasProduct =
+		product != null &&
+		typeof product === "object" &&
+		typeof product.name === "string" &&
+		product.name.trim() !== "";
+	if (hasProfile || hasProduct) return null;
+	return "Provide either product_profile_id (a saved profile) or a product object with a non-empty name.";
+}
+
+/**
+ * Builds the plan / hook_variations request body from the tool args, dropping
+ * undefined so the server sees a clean shape. `extras` carries the hook-only
+ * fields (brand_profile_id, count). Blank strings are dropped (the controller
+ * treats them as absent anyway).
+ */
+export function buildPlanBody(args: {
+	product_profile_id?: number;
+	product?: Record<string, unknown>;
+	goal?: string;
+	platform?: string;
+	language?: string;
+	brand_profile_id?: number;
+	count?: number;
+}): Record<string, unknown> {
+	const body: Record<string, unknown> = {};
+	if (args.product_profile_id !== undefined)
+		body.product_profile_id = args.product_profile_id;
+	if (args.product !== undefined) body.product = args.product;
+	const str = (v: string | undefined) =>
+		typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+	const goal = str(args.goal);
+	if (goal !== undefined) body.goal = goal;
+	const platform = str(args.platform);
+	if (platform !== undefined) body.platform = platform;
+	const language = str(args.language);
+	if (language !== undefined) body.language = language;
+	if (args.brand_profile_id !== undefined)
+		body.brand_profile_id = args.brand_profile_id;
+	if (args.count !== undefined) body.count = args.count;
+	return body;
+}
+
+// ── Variations validation ────────────────────────────────────────────────────
+
+/** The server cap on one add-variations batch (@max_variations_batch). */
+export const MAX_VARIATIONS_BATCH = 12;
+
+/**
+ * Validates the add_pack_variations / create_campaign variations list against
+ * the server's 1..12 batch cap (campaign_pack_controller parse_variations).
+ * Returns an error string, or null when valid.
+ */
+export function validateVariationsBatch(variations: unknown): string | null {
+	if (!Array.isArray(variations) || variations.length === 0) {
+		return "Provide at least one variation.";
+	}
+	if (variations.length > MAX_VARIATIONS_BATCH) {
+		return `Provide at most ${MAX_VARIATIONS_BATCH} variations per request (got ${variations.length}).`;
+	}
+	return null;
+}
+
+// ── Pack / item summarization for get_campaign_pack + list ────────────────────
+
+/** One item, trimmed to the fields an agent needs to decide the next step. */
+export interface PackItemSummary {
+	id: unknown;
+	kind: unknown;
+	status: unknown;
+	hook: unknown;
+	video_factory_slug: string | null;
+	slider_slug: string | null;
+	draft_slug: string | null;
+	draft_route: string | null;
+	credit_estimate: unknown;
+	preview_url: unknown;
+	video_result_id: unknown;
+}
+
+// A materialized item deep-links by kind: editor_ad/short → the video factory
+// slug, carousel → the slider slug. Surfacing the route saves the agent from
+// re-deriving it and mirrors the serializer's own deep-link note.
+function draftRouteFor(kind: unknown, slug: string | null): string | null {
+	if (slug === null) return null;
+	if (kind === "carousel") return `/slider/${slug}`;
+	if (kind === "short") return `/short/${slug}`;
+	if (kind === "editor_ad") return `/editor/${slug}`;
+	return null;
+}
+
+/**
+ * Summarizes one raw campaign-pack item (as the CampaignPackItem serializer
+ * emits it) into the compact shape get_campaign_pack / list_campaign_packs
+ * return. Surfaces the materialized draft slug + its deep-link route and the
+ * per-item credit estimate (stored on metadata by the variations flow), so an
+ * agent can see exactly which items are draftable, which are drafted, and what
+ * generating each would cost.
+ */
+export function summarizePackItem(item: unknown): PackItemSummary {
+	const it = asRecord(item);
+	const meta = asRecord(it.metadata);
+	const factorySlug =
+		typeof it.video_factory_slug === "string" ? it.video_factory_slug : null;
+	const sliderSlug = typeof it.slider_slug === "string" ? it.slider_slug : null;
+	const draftSlug = factorySlug ?? sliderSlug;
+	return {
+		id: it.id,
+		kind: it.kind,
+		status: it.status,
+		hook: it.hook ?? null,
+		video_factory_slug: factorySlug,
+		slider_slug: sliderSlug,
+		draft_slug: draftSlug,
+		draft_route: draftRouteFor(it.kind, draftSlug),
+		// The per-item credit ESTIMATE (from the hook board), surfaced so the
+		// agent can price the still-separate paid generation step.
+		credit_estimate: meta.credit_estimate ?? null,
+		preview_url: it.preview_url ?? null,
+		video_result_id: it.video_result_id ?? null,
+	};
+}
+
+/** Summarizes a raw campaign pack (CampaignPack serializer) with its items. */
+export function summarizePack(pack: unknown): Record<string, unknown> {
+	const p = asRecord(pack);
+	const items = Array.isArray(p.items) ? p.items.map(summarizePackItem) : [];
+	return {
+		id: p.id,
+		title: p.title ?? null,
+		status: p.status,
+		source_type: p.source_type ?? null,
+		source_url: p.source_url ?? null,
+		brief: p.brief ?? null,
+		product_profile_id: p.product_profile_id ?? null,
+		brand_profile_id: p.brand_profile_id ?? null,
+		item_count: items.length,
+		items,
+	};
+}
+
+/**
+ * Summarizes a raw campaign pack for the LIST endpoint, which — unlike the show
+ * endpoint — does NOT preload `:items` (commerce.ex list_campaign_packs; the
+ * controller's serialize_items maps the NotLoaded association to []). Emitting
+ * `items: []` / `item_count: 0` here would read as "this pack is empty" and make
+ * agents mis-plan, so this variant OMITS both fields entirely: per-item detail is
+ * only honest via get_campaign_pack. Keeps the same pack-level fields as
+ * summarizePack minus items/item_count.
+ */
+export function summarizePackListEntry(pack: unknown): Record<string, unknown> {
+	const p = asRecord(pack);
+	return {
+		id: p.id,
+		title: p.title ?? null,
+		status: p.status,
+		source_type: p.source_type ?? null,
+		source_url: p.source_url ?? null,
+		brief: p.brief ?? null,
+		product_profile_id: p.product_profile_id ?? null,
+		brand_profile_id: p.brand_profile_id ?? null,
+	};
+}
+
+// ── create_campaign orchestrator ─────────────────────────────────────────────
+//
+// The high-level intent tool mirrors make_video's altitude: one call takes a
+// product URL (or a saved product_profile_id) all the way to a persisted pack
+// full of editable DRAFTS. It is $0 end-to-end — it only ever touches the free
+// AI-assist quota (plan + hook_variations) and creates 0-credit drafts; it NEVER
+// triggers autopilot/generate/render (that stays a separate, explicit, paid
+// step). Every stage is best-effort past the point a pack exists: a partial
+// failure returns everything achieved so far plus precise resume guidance naming
+// the granular tool to continue with.
+
+export interface CreateCampaignArgs {
+	url?: string;
+	product_profile_id?: number;
+	brand_profile_id?: number;
+	item_count?: number;
+	formats?: string[];
+	language?: string;
+	goal?: string;
+	platform?: string;
+}
+
+/** A structured step outcome recorded on the orchestrator result's `steps` log. */
+export interface CampaignStep {
+	step: string;
+	ok: boolean;
+	detail?: string;
+}
+
+export interface CreateCampaignResult {
+	product_profile_id: number | null;
+	campaign_pack_id: number | null;
+	brand_profile_id: number | null;
+	extracted: {
+		source_url: string | null;
+		confidence: unknown;
+		name: unknown;
+	} | null;
+	imported: { primary_image: boolean; logo: boolean };
+	items: PackItemSummary[];
+	summary: { created: number; materialized: number; planned: number };
+	steps: CampaignStep[];
+	next: string;
+	note: string;
+}
+
+const HOOK_MIN = 3;
+const HOOK_MAX = 6;
+
+/**
+ * Runs the create_campaign pipeline against a client. Pure of MCP concerns
+ * (returns a plain result object; index.ts wraps it with ok()). Throws only on a
+ * FATAL error that leaves nothing worth returning (no product source at all, or
+ * the pack create itself failing) — every later stage is caught and folded into
+ * the result with resume guidance, so one flaky sub-step never discards the pack.
+ *
+ * `log` receives one line per stage (stderr-only in index.ts). The clamp on the
+ * hook count mirrors the server's 3..6 board size.
+ */
+export async function runCreateCampaign(
+	client: CampaignClient,
+	args: CreateCampaignArgs,
+	log: (msg: string) => void = () => {},
+): Promise<CreateCampaignResult> {
+	const steps: CampaignStep[] = [];
+	const record = (step: string, ok: boolean, detail?: string) => {
+		steps.push({ step, ok, ...(detail ? { detail } : {}) });
+		log(`${ok ? "ok" : "skip"}: ${step}${detail ? ` — ${detail}` : ""}`);
+	};
+
+	let productProfileId: number | null = args.product_profile_id ?? null;
+	let extracted: CreateCampaignResult["extracted"] = null;
+	const imported = { primary_image: false, logo: false };
+	let extractedProduct: ExtractedProduct | undefined;
+
+	// 1) INGEST — extract from the URL (0 credits, stateless) when no profile id
+	//    was supplied. A URL is required when there's no product_profile_id.
+	if (productProfileId === null) {
+		if (!args.url) {
+			throw new Error("Provide either url or product_profile_id.");
+		}
+		const res = await client.post<{ data: unknown }>(
+			"/product-sources/extract",
+			{
+				url: args.url,
+			},
+		);
+		const data = asRecord(asRecord(res).data);
+		extractedProduct = asRecord(data.product) as ExtractedProduct;
+		extracted = {
+			source_url: (data.source_url as string) ?? args.url,
+			confidence: data.confidence ?? null,
+			name: extractedProduct.name ?? null,
+		};
+		record(
+			"extract_product_page",
+			true,
+			`confidence=${data.confidence ?? "?"}`,
+		);
+
+		// 2) PERSIST identity — create a product profile from the extracted facts so
+		//    the pack (and its drafts) inherit a durable source of truth. A profile
+		//    needs a name; if extraction found none, fall back to the URL host.
+		const attrs = extractedProductToProfileAttrs(
+			extractedProduct,
+			extracted.source_url ?? args.url,
+		);
+		if (
+			typeof attrs.name !== "string" ||
+			(attrs.name as string).trim() === ""
+		) {
+			attrs.name = fallbackNameFromUrl(args.url);
+		}
+		const created = await client.post<{ data: { id: number } }>(
+			"/product-profiles",
+			attrs,
+		);
+		productProfileId = asRecord(asRecord(created).data).id as number;
+		record("create_product_profile", true, `id=${productProfileId}`);
+
+		// 3) IMPORT imagery — best-effort. A failed image import must NOT sink the
+		//    campaign, so each is caught and recorded. primary image first, then logo.
+		const primaryUrl = firstString(extractedProduct.images);
+		if (primaryUrl) {
+			try {
+				await client.post("/product-sources/import-image", {
+					image_url: primaryUrl,
+					product_profile_id: productProfileId,
+					link_as: "primary_image",
+				});
+				imported.primary_image = true;
+				record("import_primary_image", true);
+			} catch (e) {
+				record("import_primary_image", false, describeErr(e));
+			}
+		}
+		const logoUrl =
+			typeof extractedProduct.logo === "string"
+				? extractedProduct.logo
+				: undefined;
+		if (logoUrl && logoUrl.trim() !== "") {
+			try {
+				await client.post("/product-sources/import-image", {
+					image_url: logoUrl,
+					product_profile_id: productProfileId,
+					link_as: "logo",
+				});
+				imported.logo = true;
+				record("import_logo", true);
+			} catch (e) {
+				record("import_logo", false, describeErr(e));
+			}
+		}
+	} else {
+		record("use_product_profile", true, `id=${productProfileId}`);
+	}
+
+	// 4) PLAN — meters the free AI-assist quota (429 on exhaustion). Best-effort:
+	//    the plan's positioning/estimate is nice-to-have context; the pack can
+	//    still be built from hook variations if planning is quota-blocked. A 429
+	//    here is surfaced (with the unlock hint) but does not abort.
+	let positioning: string | null = null;
+	try {
+		const planRes = await client.post<{ data: unknown }>(
+			"/campaign-packs/plan",
+			buildPlanBody({
+				product_profile_id: productProfileId,
+				goal: args.goal,
+				platform: args.platform,
+				language: args.language,
+			}),
+		);
+		const planData = asRecord(asRecord(planRes).data);
+		positioning =
+			typeof planData.positioning === "string" ? planData.positioning : null;
+		record("plan_campaign", true);
+	} catch (e) {
+		if (statusOf(e) === 429) {
+			record(
+				"plan_campaign",
+				false,
+				"ai_assist_quota_exceeded (unlock_ai_assists to add +10, or continue)",
+			);
+		} else {
+			record("plan_campaign", false, describeErr(e));
+		}
+	}
+
+	// 5) HOOK VARIATIONS — also meters the free quota. This IS load-bearing: the
+	//    variations become the pack's items. If it's quota-blocked or errors, we
+	//    can't build a populated pack, so return early with resume guidance (the
+	//    profile is already saved, so the agent resumes cheaply once unblocked).
+	const count = clampCount(args.item_count);
+	let variations: unknown[] = [];
+	try {
+		const hookRes = await client.post<{ data: unknown }>(
+			"/campaign-packs/hook-variations",
+			buildPlanBody({
+				product_profile_id: productProfileId,
+				brand_profile_id: args.brand_profile_id,
+				count,
+				goal: args.goal,
+				platform: args.platform,
+				language: args.language,
+			}),
+		);
+		const hookData = asRecord(asRecord(hookRes).data);
+		variations = Array.isArray(hookData.variations) ? hookData.variations : [];
+		record("generate_hook_variations", true, `${variations.length} variations`);
+	} catch (e) {
+		const quota = statusOf(e) === 429;
+		record(
+			"generate_hook_variations",
+			false,
+			quota ? "ai_assist_quota_exceeded" : describeErr(e),
+		);
+		return partialResult({
+			productProfileId,
+			campaignPackId: null,
+			brandProfileId: args.brand_profile_id ?? null,
+			extracted,
+			imported,
+			items: [],
+			positioning,
+			steps,
+			next: quota
+				? `generate_hook_variations({ product_profile_id: ${productProfileId} }) once the daily AI-assist quota resets, or unlock_ai_assists first, then create_campaign_pack + add_pack_variations.`
+				: `generate_hook_variations({ product_profile_id: ${productProfileId} }), then create_campaign_pack + add_pack_variations.`,
+			note: quota
+				? "Stopped at hook variations: the free daily AI-assist quota is exhausted. The product profile is saved — resume once it resets (or unlock more)."
+				: "Stopped at hook variations. The product profile is saved — resume with the granular tools.",
+		});
+	}
+
+	// If the board came back empty (LLM returned nothing usable), there's nothing
+	// to populate a pack with — save the caller a committed-but-empty pack.
+	if (variations.length === 0) {
+		return partialResult({
+			productProfileId,
+			campaignPackId: null,
+			brandProfileId: args.brand_profile_id ?? null,
+			extracted,
+			imported,
+			items: [],
+			positioning,
+			steps,
+			next: `generate_hook_variations({ product_profile_id: ${productProfileId} }) to retry, then create_campaign_pack + add_pack_variations.`,
+			note: "Hook variations came back empty — retry generate_hook_variations, then build the pack.",
+		});
+	}
+
+	// Respect the requested format filter: keep only variations whose
+	// suggested_format is in `formats` (when given). If the filter removes
+	// everything, fall back to the full board rather than a pack with no items.
+	const filtered = filterVariationsByFormat(variations, args.formats);
+	const chosen = (filtered.length > 0 ? filtered : variations).slice(
+		0,
+		MAX_VARIATIONS_BATCH,
+	);
+
+	// 6) CREATE the pack (0 credits, no persisted generation). This is the point
+	//    of no return for "return the pack even if later steps wobble". A failure
+	//    HERE is fatal (nothing durable to hand back), so it propagates.
+	const packBody: Record<string, unknown> = {
+		product_profile_id: productProfileId,
+	};
+	if (args.brand_profile_id !== undefined)
+		packBody.brand_profile_id = args.brand_profile_id;
+	if (args.language !== undefined && args.language.trim() !== "")
+		packBody.language = args.language;
+	if (extracted?.source_url) {
+		packBody.source_type = "url";
+		packBody.source_url = extracted.source_url;
+	}
+	if (typeof extractedProduct?.name === "string")
+		packBody.title = extractedProduct.name;
+	const packRes = await client.post<{ data: { id: number } }>(
+		"/campaign-packs",
+		packBody,
+	);
+	const campaignPackId = asRecord(asRecord(packRes).data).id as number;
+	record("create_campaign_pack", true, `id=${campaignPackId}`);
+
+	// 7) ADD + MATERIALIZE the chosen variations as DRAFTS (0 credits, best-effort
+	//    per item server-side). One call handles the whole batch; the server
+	//    keeps any variation it can't materialize as a "planned" item with a
+	//    reason, so the response is authoritative for what became a draft.
+	let items: PackItemSummary[] = [];
+	let summary = { created: 0, materialized: 0, planned: 0 };
+	try {
+		const varRes = await client.post<{ data: unknown }>(
+			`/campaign-packs/${campaignPackId}/variations`,
+			{ variations: chosen, materialize: true },
+		);
+		const varData = asRecord(asRecord(varRes).data);
+		items = Array.isArray(varData.items)
+			? varData.items.map(summarizePackItem)
+			: [];
+		const s = asRecord(varData.summary);
+		summary = {
+			created: numberOr(s.created, items.length),
+			materialized: numberOr(s.materialized, 0),
+			planned: numberOr(s.planned, 0),
+		};
+		record(
+			"add_pack_variations",
+			true,
+			`${summary.materialized}/${summary.created} materialized`,
+		);
+	} catch (e) {
+		record("add_pack_variations", false, describeErr(e));
+		return partialResult({
+			productProfileId,
+			campaignPackId,
+			brandProfileId: args.brand_profile_id ?? null,
+			extracted,
+			imported,
+			items: [],
+			positioning,
+			steps,
+			next: `add_pack_variations({ pack_id: ${campaignPackId}, variations: [...], materialize: true }) to populate the pack (up to ${MAX_VARIATIONS_BATCH} per call), or get_campaign_pack({ id: ${campaignPackId} }) to inspect it.`,
+			note: "The pack was created but adding its variations failed — resume with add_pack_variations.",
+		});
+	}
+
+	const draftable = summary.materialized;
+	return {
+		product_profile_id: productProfileId,
+		campaign_pack_id: campaignPackId,
+		brand_profile_id: args.brand_profile_id ?? null,
+		extracted,
+		imported,
+		items,
+		summary,
+		steps,
+		next: `get_campaign_pack({ id: ${campaignPackId} }) to review the drafts; then, for EACH draft you want to publish, generate it EXPLICITLY (a SEPARATE, PAID step): editor_ad/short → start_autopilot({ slug }) or the granular generate/render tools; carousel → generate_slider({ slug }).`,
+		note:
+			`Campaign pack ${campaignPackId} created with ${summary.created} item(s), ${draftable} materialized into editable DRAFTS. ` +
+			(positioning ? `Positioning: ${positioning}. ` : "") +
+			"$0 so far (free AI-assist quota + 0-credit drafts). Generation/render is a separate, explicit, PAID step per draft — nothing was generated.",
+	};
+}
+
+// ── orchestrator helpers ─────────────────────────────────────────────────────
+
+function partialResult(p: {
+	productProfileId: number | null;
+	campaignPackId: number | null;
+	brandProfileId: number | null;
+	extracted: CreateCampaignResult["extracted"];
+	imported: { primary_image: boolean; logo: boolean };
+	items: PackItemSummary[];
+	positioning: string | null;
+	steps: CampaignStep[];
+	next: string;
+	note: string;
+}): CreateCampaignResult {
+	const materialized = p.items.filter((i) => i.draft_slug !== null).length;
+	return {
+		product_profile_id: p.productProfileId,
+		campaign_pack_id: p.campaignPackId,
+		brand_profile_id: p.brandProfileId,
+		extracted: p.extracted,
+		imported: p.imported,
+		items: p.items,
+		summary: {
+			created: p.items.length,
+			materialized,
+			planned: p.items.length - materialized,
+		},
+		steps: p.steps,
+		next: p.next,
+		note: p.note,
+	};
+}
+
+function clampCount(n: number | undefined): number {
+	if (typeof n !== "number" || !Number.isFinite(n)) return HOOK_MAX;
+	return Math.min(HOOK_MAX, Math.max(HOOK_MIN, Math.round(n)));
+}
+
+/**
+ * Keeps only variations whose suggested_format is in `formats` (normalized to
+ * the server's editor_ad/short/carousel spelling). An empty/absent filter keeps
+ * everything. Returned so create_campaign can honor a `formats` request without
+ * a second server round-trip.
+ */
+export function filterVariationsByFormat(
+	variations: unknown[],
+	formats: string[] | undefined,
+): unknown[] {
+	if (!Array.isArray(formats) || formats.length === 0) return variations;
+	const wanted = new Set(formats.map(normalizeFormat));
+	return variations.filter((v) =>
+		wanted.has(normalizeFormat(asRecord(v).suggested_format)),
+	);
+}
+
+function normalizeFormat(v: unknown): string {
+	if (typeof v !== "string") return "";
+	return v
+		.trim()
+		.toLowerCase()
+		.replace(/[\s-]+/g, "_");
+}
+
+function firstString(arr: unknown): string | undefined {
+	if (!Array.isArray(arr)) return undefined;
+	for (const v of arr) {
+		if (typeof v === "string" && v.trim() !== "") return v;
+	}
+	return undefined;
+}
+
+function numberOr(v: unknown, fallback: number): number {
+	return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+// A concise, human error line for the steps log — the API code when present
+// (machine-stable), else the message, never a raw stack.
+function describeErr(e: unknown): string {
+	const code = (e as { code?: unknown })?.code;
+	if (typeof code === "string" && code !== "") return code;
+	const status = statusOf(e);
+	if (e instanceof Error && e.message)
+		return status ? `HTTP ${status}: ${e.message}` : e.message;
+	return status ? `HTTP ${status}` : "failed";
+}
+
+/**
+ * Derives a product-profile name from a URL when extraction found none — the
+ * host with a leading www. dropped (e.g. "https://shop.acme.com/x" → "shop.acme.com").
+ * Falls back to a generic label for an unparseable URL so create never fails the
+ * profile's required-name changeset.
+ */
+export function fallbackNameFromUrl(url: string | undefined): string {
+	if (typeof url !== "string" || url.trim() === "") return "Imported product";
+	try {
+		const host = new URL(url).hostname.replace(/^www\./, "");
+		return host || "Imported product";
+	} catch {
+		return "Imported product";
+	}
+}