@hubfluencer/mcp 0.4.0 → 0.6.0

package/src/perf-review-assets.ts

@@ -0,0 +1,470 @@
+/**
+ * Pure, side-effect-light helpers for the performance-loop, review-link, and
+ * asset-catalog tools (index.ts).
+ *
+ * Like core.ts / campaign.ts / series-calendar.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 request-shape builders, the
+ * metric/attribute bounds validators, the review-link create presentation (the
+ * plaintext token is shown ONCE), the response summarizers, and the
+ * subscription-gate (402) message augmentation are extracted here so they are
+ * testable against a fake client / plain inputs.
+ *
+ * GROUND TRUTH (verified against the API controllers + contexts, 2026-07-02):
+ *   - creative_performance_controller.ex + performance_controller.ex (+ the
+ *     Performance context / CreativePerformance schema),
+ *     review_link_controller.ex (+ the Reviews context / ReviewLink schema),
+ *     catalog_asset_controller.ex (+ the Assets context / CatalogAsset schema).
+ *   - Performance + review controllers scope by the caller: a foreign/unknown
+ *     campaign-pack item or review link is a generic 404 (no enumeration). Reads
+ *     require video:read; writes require video:generate (agent tokens never carry
+ *     account:admin). record_metrics / set_attributes / create-review-link spend
+ *     NO video credits. make_more consumes the FREE daily AiAssistQuota (429
+ *     ai_assist_quota_exceeded), like the campaign-pack planner, and spends no
+ *     video credits.
+ *   - NONE of these controllers mount `Plugs.Idempotency`, so these tools send NO
+ *     Idempotency-Key. record_metrics is append-only (many snapshots per item),
+ *     create-review-link mints a fresh token every call — so a transport retry of
+ *     either FORKS a row; the tool `idempotentHint`s reflect that honestly. The
+ *     one exception is set_attributes: it upserts the SINGLE attributes row (a
+ *     second identical call converges to the same row), so it IS idempotent.
+ *   - The CATALOG asset routes additionally mount `RequireSubscription`, which
+ *     returns 402 `subscription_required` (NOT 403) when the user has no active
+ *     subscription — surfaced verbatim so the agent knows it's a billing gate, not
+ *     a tool bug it can retry.
+ *   - CAUTION SEMANTICS: get_recommendations returns the server's aggregate
+ *     UNCHANGED (confidence none/low/moderate, an honest note, never a causal/ROAS
+ *     claim). This module NEVER re-derives, softens, or overstates it.
+ */
+
+import { asRecord } from "./core.js";
+
+/** The narrow client surface these tools' helpers need — a subset of HubfluencerClient. */
+export interface PerfReviewAssetsClient {
+	get<T = unknown>(
+		path: string,
+		query?: Record<string, string | number | undefined>,
+	): Promise<T>;
+	post<T = unknown>(
+		path: string,
+		body?: unknown,
+		idempotencyKey?: string,
+	): Promise<T>;
+}
+
+// ── Performance: metric snapshot ──────────────────────────────────────────────
+
+// The platforms + sources a performance snapshot accepts
+// (CreativePerformance.platforms/0 + sources/0). Mirrored so the flat tool schema
+// can enum them without a server round-trip.
+export const PERFORMANCE_PLATFORMS = ["tiktok", "instagram", "other"] as const;
+export const PERFORMANCE_SOURCES = [
+	"manual",
+	"tiktok_api",
+	"instagram_api",
+] as const;
+
+// The non-negative integer engagement/conversion counts (CreativePerformance
+// @count_fields + watch_time). Validated client-side so a bad value fails fast
+// with a precise message instead of round-tripping to a 422.
+const PERFORMANCE_COUNT_FIELDS = [
+	"views",
+	"likes",
+	"comments",
+	"shares",
+	"clicks",
+	"conversions",
+	"watch_time_seconds",
+] as const;
+
+// revenue is numeric(14,2): a value at/above 10^12 overflows the column (the
+// changeset caps it at 999999999999.99). Mirror the ceiling so the tool rejects
+// an over-magnitude value cleanly rather than eliciting the server 422.
+const MAX_PERFORMANCE_REVENUE = 999_999_999_999.99;
+
+export interface RecordPerformanceArgs {
+	views?: number;
+	likes?: number;
+	comments?: number;
+	shares?: number;
+	clicks?: number;
+	conversions?: number;
+	revenue?: number;
+	watch_time_seconds?: number;
+	platform: string;
+	source?: string;
+	captured_at?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Validates a performance snapshot against the CreativePerformance changeset
+ * bounds (counts + watch_time ≥0, revenue ≥0 and ≤~1 trillion). Platform/source
+ * membership is enforced by the tool's Zod enum, so it isn't re-checked here.
+ * Returns an error string naming the exact bound, or null when valid.
+ */
+export function validatePerformanceMetrics(
+	args: RecordPerformanceArgs,
+): string | null {
+	for (const field of PERFORMANCE_COUNT_FIELDS) {
+		const v = args[field];
+		if (v === undefined) continue;
+		if (!Number.isFinite(v) || !Number.isInteger(v) || v < 0) {
+			return `${field} must be a non-negative integer.`;
+		}
+	}
+	if (args.revenue !== undefined) {
+		if (!Number.isFinite(args.revenue) || args.revenue < 0) {
+			return "revenue must be a non-negative number.";
+		}
+		if (args.revenue > MAX_PERFORMANCE_REVENUE) {
+			return `revenue must be at most ${MAX_PERFORMANCE_REVENUE}.`;
+		}
+	}
+	return null;
+}
+
+/**
+ * Builds the record-performance request body from the tool args, dropping
+ * undefined so the server sees a clean shape. `captured_at` is REQUIRED by the
+ * changeset (it orders snapshots); when the caller omits it we default to the
+ * current instant so a bare `record_performance` still succeeds. The owner +
+ * campaign_pack_item_id are set server-side from the verified item, never here.
+ */
+export function buildPerformanceBody(
+	args: RecordPerformanceArgs,
+	now: () => Date = () => new Date(),
+): Record<string, unknown> {
+	const body: Record<string, unknown> = { platform: args.platform };
+	for (const field of PERFORMANCE_COUNT_FIELDS) {
+		if (args[field] !== undefined) body[field] = args[field];
+	}
+	if (args.revenue !== undefined) body.revenue = args.revenue;
+	if (typeof args.source === "string" && args.source.trim() !== "")
+		body.source = args.source;
+	body.captured_at =
+		typeof args.captured_at === "string" && args.captured_at.trim() !== ""
+			? args.captured_at
+			: now().toISOString();
+	if (args.metadata !== undefined) body.metadata = args.metadata;
+	return body;
+}
+
+/** One performance snapshot, trimmed to the fields an agent reads back. */
+export interface PerformanceSnapshotSummary {
+	id: unknown;
+	campaign_pack_item_id: unknown;
+	platform: unknown;
+	views: unknown;
+	likes: unknown;
+	comments: unknown;
+	shares: unknown;
+	clicks: unknown;
+	conversions: unknown;
+	revenue: unknown;
+	watch_time_seconds: unknown;
+	source: unknown;
+	captured_at: unknown;
+}
+
+/** Summarizes one raw performance snapshot (CreativePerformanceController serializer). */
+export function summarizePerformance(
+	snapshot: unknown,
+): PerformanceSnapshotSummary {
+	const s = asRecord(snapshot);
+	return {
+		id: s.id,
+		campaign_pack_item_id: s.campaign_pack_item_id,
+		platform: s.platform,
+		views: s.views ?? null,
+		likes: s.likes ?? null,
+		comments: s.comments ?? null,
+		shares: s.shares ?? null,
+		clicks: s.clicks ?? null,
+		conversions: s.conversions ?? null,
+		revenue: s.revenue ?? null,
+		watch_time_seconds: s.watch_time_seconds ?? null,
+		source: s.source ?? null,
+		captured_at: s.captured_at ?? null,
+	};
+}
+
+// ── Performance: creative attributes (single upserted row) ────────────────────
+
+// The creative-attributes upsert accepts exactly these textual classifiers
+// (creative_performance_controller.ex attribute_attrs). All free-form; the server
+// stores one row per item and a repeat call updates it in place.
+export const CREATIVE_ATTRIBUTE_FIELDS = [
+	"hook_type",
+	"creative_format",
+	"visual_language",
+	"product_category",
+	"cta",
+	"length",
+	"caption_style",
+	"metadata",
+] as const;
+
+/** Picks only the accepted creative-attribute fields from a raw args object. */
+export function pickCreativeAttributeFields(
+	args: Record<string, unknown>,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const k of CREATIVE_ATTRIBUTE_FIELDS) {
+		if (args[k] !== undefined) out[k] = args[k];
+	}
+	return out;
+}
+
+// ── Review links ──────────────────────────────────────────────────────────────
+
+// The review-link expiry window (ReviewLink create; ReviewLinkCreateRequest
+// schema). Mirrored so the tool describes + fails fast on the bound; the server
+// clamps anyway (default 168h = 7 days).
+export const REVIEW_LINK_MIN_EXPIRES_IN_HOURS = 1;
+export const REVIEW_LINK_MAX_EXPIRES_IN_HOURS = 720;
+
+/**
+ * Validates the create-review-link output reference: EXACTLY ONE of
+ * video_result_id / slider_id (the changeset requires exactly one on create).
+ * Returns an error string, or null when the pair is valid.
+ */
+export function validateReviewOutput(
+	videoResultId: number | undefined,
+	sliderId: number | undefined,
+): string | null {
+	const hasVideo = typeof videoResultId === "number";
+	const hasSlider = typeof sliderId === "number";
+	if (hasVideo && hasSlider) {
+		return "Provide exactly one of video_result_id or slider_id, not both.";
+	}
+	if (!hasVideo && !hasSlider) {
+		return "Provide exactly one of video_result_id (a completed render) or slider_id (a completed carousel).";
+	}
+	return null;
+}
+
+/**
+ * Builds the create-review-link request body from the tool args, dropping
+ * undefined so the server sees a clean shape. `expires_in_hours` is passed
+ * through as-is (the server clamps 1..720); a blank version_label is omitted.
+ */
+export function buildReviewLinkBody(args: {
+	video_result_id?: number;
+	slider_id?: number;
+	campaign_pack_id?: number;
+	expires_in_hours?: number;
+	download_enabled?: boolean;
+	version_label?: string;
+}): Record<string, unknown> {
+	const body: Record<string, unknown> = {};
+	if (args.video_result_id !== undefined)
+		body.video_result_id = args.video_result_id;
+	if (args.slider_id !== undefined) body.slider_id = args.slider_id;
+	if (args.campaign_pack_id !== undefined)
+		body.campaign_pack_id = args.campaign_pack_id;
+	if (args.expires_in_hours !== undefined)
+		body.expires_in_hours = args.expires_in_hours;
+	if (args.download_enabled !== undefined)
+		body.download_enabled = args.download_enabled;
+	if (
+		typeof args.version_label === "string" &&
+		args.version_label.trim() !== ""
+	)
+		body.version_label = args.version_label;
+	return body;
+}
+
+/** One review link, trimmed to what an agent tracking a review needs. */
+export interface ReviewLinkSummary {
+	id: unknown;
+	status: unknown;
+	output_kind: unknown;
+	video_result_id: unknown;
+	slider_id: unknown;
+	campaign_pack_id: unknown;
+	expires_at: unknown;
+	download_enabled: unknown;
+	version_label: unknown;
+	view_count: unknown;
+	viewed_at: unknown;
+	comment_count: unknown;
+}
+
+/**
+ * Summarizes one raw review link (ReviewLinkController serializer). NEVER carries
+ * a token (the serializer omits token_hash and the plaintext only ever appears in
+ * the create payload). `comment_count` is the visible-comment count the context
+ * annotates on list/show (null on the create response — no activity yet).
+ */
+export function summarizeReviewLink(link: unknown): ReviewLinkSummary {
+	const l = asRecord(link);
+	return {
+		id: l.id,
+		status: l.status,
+		output_kind: l.output_kind ?? null,
+		video_result_id: l.video_result_id ?? null,
+		slider_id: l.slider_id ?? null,
+		campaign_pack_id: l.campaign_pack_id ?? null,
+		expires_at: l.expires_at ?? null,
+		download_enabled: l.download_enabled ?? null,
+		version_label: l.version_label ?? null,
+		view_count: l.view_count ?? null,
+		viewed_at: l.viewed_at ?? null,
+		comment_count: l.comment_count ?? null,
+	};
+}
+
+export interface CreateReviewLinkResult {
+	review_link: ReviewLinkSummary;
+	/** The plaintext review token — shown ONCE; NOT retrievable again. */
+	token: unknown;
+	/** Relative public review path, e.g. /review/<token>. */
+	review_path: unknown;
+	/** The absolute public review URL on the web-app origin (else the path). */
+	review_url: string | null;
+	important: string;
+	next: string;
+}
+
+// The no-login reviewer page (`/review/<token>`) is a FRONT web-app route (Expo
+// Router / Cloudflare Pages), NOT an API endpoint — the Phoenix API host serves a
+// 404 there. So the absolute review URL must be built on the web-app origin, which
+// is a DIFFERENT host from the API base (default API https://hubfluencer.com, web
+// app https://app.hubfluencer.com). This mirrors the front's own
+// REVIEW_WEB_ORIGIN_FALLBACK (types/review-link.ts) and the API's :web_app_origin
+// default (callback_page_safety.ex). `HUBFLUENCER_WEB_URL` overrides it (e.g. a
+// staging web origin) without touching HUBFLUENCER_BASE_URL, which stays the API.
+const DEFAULT_WEB_APP_ORIGIN = "https://app.hubfluencer.com";
+
+/**
+ * The web-app origin that serves the public no-login pages (the reviewer page at
+ * `/review/<token>`). Read from `HUBFLUENCER_WEB_URL`, falling back to the
+ * canonical https://app.hubfluencer.com — NOT the API base (a different host).
+ */
+export function reviewWebOrigin(env: NodeJS.ProcessEnv = process.env): string {
+	const configured = env.HUBFLUENCER_WEB_URL;
+	if (typeof configured === "string" && configured.trim() !== "") {
+		return configured.trim().replace(/\/+$/, "");
+	}
+	return DEFAULT_WEB_APP_ORIGIN;
+}
+
+/**
+ * Shapes the create-review-link result so the ONCE-only token + the public review
+ * URL are front-and-centre and the caller is told it can't be fetched again. The
+ * server returns { review_link, token, review_path }; `webOrigin` (the web-app
+ * host that actually serves `/review/<token>`, NOT the API base) is used to
+ * present an absolute review_url the owner can hand to a reviewer, falling back to
+ * the relative path.
+ */
+export function shapeCreateReviewLink(
+	data: unknown,
+	webOrigin: string | undefined,
+): CreateReviewLinkResult {
+	const d = asRecord(data);
+	const token = d.token ?? null;
+	const reviewPath = typeof d.review_path === "string" ? d.review_path : null;
+	const reviewUrl = absoluteReviewUrl(reviewPath, webOrigin);
+	return {
+		review_link: summarizeReviewLink(d.review_link),
+		token,
+		review_path: reviewPath,
+		review_url: reviewUrl,
+		important:
+			"SAVE THE TOKEN NOW — it is shown only ONCE and is NOT retrievable again. " +
+			"Only its hash is stored server-side; list_review_links and revoke_review_link never return it. " +
+			`Share the review URL${reviewUrl ? ` (${reviewUrl})` : ""} with your reviewer — they open it with no account.`,
+		next: "list_review_links to track approval/comment activity; revoke_review_link({ id }) to disable the URL.",
+	};
+}
+
+/**
+ * Joins a relative review path to the web-app origin, when known, so the owner
+ * gets a copy-pasteable absolute URL. The public review page is served by the
+ * FRONT web app (`/review/<token>`), not the API host. Returns the relative path
+ * unchanged if the origin is absent or unparseable — never throws.
+ */
+export function absoluteReviewUrl(
+	reviewPath: string | null,
+	webOrigin: string | undefined,
+): string | null {
+	if (!reviewPath) return null;
+	if (typeof webOrigin !== "string" || webOrigin.trim() === "")
+		return reviewPath;
+	try {
+		return new URL(reviewPath, webOrigin).toString();
+	} catch {
+		return reviewPath;
+	}
+}
+
+// ── Asset catalog ─────────────────────────────────────────────────────────────
+
+/** One catalog asset, trimmed to the fields an agent reuses across projects. */
+export interface CatalogAssetSummary {
+	id: unknown;
+	filename: unknown;
+	media_type: unknown;
+	mime_type: unknown;
+	size_bytes: unknown;
+	description: unknown;
+	status: unknown;
+	asset_url: unknown;
+	inserted_at: unknown;
+}
+
+/**
+ * Summarizes one raw catalog asset (CatalogAssetController render_asset) into the
+ * compact shape the asset tools return. `asset_url` is the presigned URL (image
+ * or video) the agent can reference; the image_meta/verified_* provenance fields
+ * are dropped as noise for the agent surface.
+ */
+export function summarizeCatalogAsset(asset: unknown): CatalogAssetSummary {
+	const a = asRecord(asset);
+	return {
+		id: a.id,
+		filename: a.filename ?? null,
+		media_type: a.media_type ?? null,
+		mime_type: a.mime_type ?? null,
+		size_bytes: a.size_bytes ?? null,
+		description: a.description ?? null,
+		status: a.status ?? null,
+		asset_url: a.asset_url ?? null,
+		inserted_at: a.inserted_at ?? null,
+	};
+}
+
+/** The storage quota block the catalog list/quota endpoints return. */
+export function summarizeAssetQuota(quota: unknown): Record<string, unknown> {
+	const q = asRecord(quota);
+	return {
+		limit_bytes: q.limit_bytes ?? null,
+		used_bytes: q.used_bytes ?? null,
+		pending_bytes: q.pending_bytes ?? null,
+		reserved_bytes: q.reserved_bytes ?? null,
+		remaining_bytes: q.remaining_bytes ?? null,
+	};
+}
+
+// ── Subscription-gate (402) message augmentation ──────────────────────────────
+
+/**
+ * Augments a `subscription_required` (402) message from the catalog asset routes
+ * (RequireSubscription plug). These routes gate the whole asset catalog behind an
+ * active subscription — a scope/credit retry can't fix it — so spell that out so
+ * the agent surfaces a clear "needs an active subscription" instead of a bare code
+ * and doesn't loop. Returns the original message unchanged for any other error.
+ */
+export function assetSubscriptionErrorText(
+	status: number | undefined,
+	code: string | undefined,
+	message: string,
+): string {
+	if (status !== 402 || code !== "subscription_required") return message;
+	return (
+		`${message} The reusable asset catalog requires an ACTIVE SUBSCRIPTION; ` +
+		"this is a billing gate, not a scope or credit issue, so retrying won't help — " +
+		"subscribe in the app first. (Generating videos/carousels does not require this.)"
+	);
+}