@hubfluencer/mcp 0.5.0 → 0.6.0

package/src/series-calendar.ts

@@ -0,0 +1,351 @@
+/**
+ * Pure, side-effect-light helpers for the series + content-calendar tools
+ * (index.ts).
+ *
+ * Like core.ts / campaign.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, response summarizers, the
+ * batch/bounds validators, and the calendar's 403-scope 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):
+ *   - series_controller.ex, series_episode_controller.ex,
+ *     scheduled_post_controller.ex + the Series / Posts contexts.
+ *   - NONE of those three controllers mount `Plugs.Idempotency`, so the series +
+ *     calendar tools send NO Idempotency-Key (mirroring campaign.ts). A plain
+ *     transport retry of a create is therefore NOT server-deduplicated; the tool
+ *     descriptions + `idempotentHint` reflect that honestly. The two exceptions
+ *     that ARE safe to replay are semantic, not plug-backed: mark-episode-posted
+ *     and mark-scheduled-posted are CAS transitions whose replay the server
+ *     defines as a no-op / 422 (see the mark helpers below).
+ *   - plan_series_episodes meters the FREE daily AiAssistQuota (429
+ *     `ai_assist_quota_exceeded`, identical shape to the campaign-pack planner)
+ *     and spends no video credits. materialize_episode creates a 0-credit DRAFT.
+ *   - The calendar is REMINDER-ONLY by design here: these tools never accept or
+ *     send a social-account id, so every scheduled_post they create is a manual-
+ *     posting reminder that the pipeline `WriteScope` floor authorizes with
+ *     `video:generate`. Attaching a social account (auto-publish) additionally
+ *     requires `account:admin`, which agent tokens never hold — so a 403
+ *     `insufficient_scope` here means the TARGETED post already carries an
+ *     account, or the token predates the reminder-calendar scope split.
+ */
+
+import { asRecord } from "./core.js";
+
+/** The narrow client surface these tools' helpers need — a subset of HubfluencerClient. */
+export interface SeriesCalendarClient {
+	get<T = unknown>(
+		path: string,
+		query?: Record<string, string | number | undefined>,
+	): Promise<T>;
+	post<T = unknown>(
+		path: string,
+		body?: unknown,
+		idempotencyKey?: string,
+	): Promise<T>;
+}
+
+// ── Series field mapping ──────────────────────────────────────────────────────
+
+// The series create/update body accepts exactly these fields
+// (series_controller.ex @series_fields). `campaign_pack_id` is intentionally
+// EXCLUDED — the server sets the series' rolling pack from context on the first
+// materialize, never from user input — so it is not offered here either.
+export const SERIES_FIELDS = [
+	"brand_profile_id",
+	"product_profile_id",
+	"name",
+	"template",
+	"cadence",
+	"tone",
+	"default_format",
+	"status",
+	"metadata",
+] as const;
+
+/** Picks only the accepted series fields from a raw args object, dropping the rest. */
+export function pickSeriesFields(
+	args: Record<string, unknown>,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const k of SERIES_FIELDS) {
+		if (args[k] !== undefined) out[k] = args[k];
+	}
+	return out;
+}
+
+// ── Series / episode summarization ────────────────────────────────────────────
+
+// A materialized episode deep-links by the format of its draft: editor_ad →
+// /editor/:slug, short → /short/:slug, carousel → /slider/:slug. The serializer
+// already resolves the slug off the (preloaded) campaign_pack_item; surfacing the
+// route saves the agent from re-deriving it and mirrors the pack-item summarizer.
+function episodeDraftRoute(
+	format: unknown,
+	factorySlug: string | null,
+	sliderSlug: string | null,
+): string | null {
+	if (format === "carousel") return sliderSlug ? `/slider/${sliderSlug}` : null;
+	if (format === "short") return factorySlug ? `/short/${factorySlug}` : null;
+	if (format === "editor_ad")
+		return factorySlug ? `/editor/${factorySlug}` : null;
+	return null;
+}
+
+/** One episode, trimmed to the fields an agent needs to decide the next step. */
+export interface EpisodeSummary {
+	id: unknown;
+	series_id: unknown;
+	position: unknown;
+	status: unknown;
+	hook: unknown;
+	brief: unknown;
+	caption: unknown;
+	suggested_format: unknown;
+	hashtags: unknown;
+	posted_at: unknown;
+	campaign_pack_item_id: unknown;
+	video_factory_slug: string | null;
+	slider_slug: string | null;
+	draft_slug: string | null;
+	draft_route: string | null;
+}
+
+/**
+ * Summarizes one raw episode (as the SeriesEpisode serializer emits it) into the
+ * compact shape the episode tools return. Surfaces the materialized draft slug +
+ * its deep-link route (editor_ad/short → the video factory, carousel → the
+ * slider) so an agent can see which ideas are still plannable, which are drafted,
+ * and where each draft lives.
+ */
+export function summarizeEpisode(episode: unknown): EpisodeSummary {
+	const e = asRecord(episode);
+	const factorySlug =
+		typeof e.video_factory_slug === "string" ? e.video_factory_slug : null;
+	const sliderSlug = typeof e.slider_slug === "string" ? e.slider_slug : null;
+	const draftSlug = factorySlug ?? sliderSlug;
+	return {
+		id: e.id,
+		series_id: e.series_id,
+		position: e.position,
+		status: e.status,
+		hook: e.hook ?? null,
+		brief: e.brief ?? null,
+		caption: e.caption ?? null,
+		suggested_format: e.suggested_format ?? null,
+		hashtags: e.hashtags ?? [],
+		posted_at: e.posted_at ?? null,
+		campaign_pack_item_id: e.campaign_pack_item_id ?? null,
+		video_factory_slug: factorySlug,
+		slider_slug: sliderSlug,
+		draft_slug: draftSlug,
+		draft_route: episodeDraftRoute(e.suggested_format, factorySlug, sliderSlug),
+	};
+}
+
+/** Summarizes a raw series (SeriesController serializer). */
+export function summarizeSeries(series: unknown): Record<string, unknown> {
+	const s = asRecord(series);
+	return {
+		id: s.id,
+		name: s.name ?? null,
+		template: s.template ?? null,
+		cadence: s.cadence ?? null,
+		tone: s.tone ?? null,
+		default_format: s.default_format ?? null,
+		status: s.status ?? null,
+		brand_profile_id: s.brand_profile_id ?? null,
+		product_profile_id: s.product_profile_id ?? null,
+		campaign_pack_id: s.campaign_pack_id ?? null,
+	};
+}
+
+/**
+ * Summarizes the read-only series dashboard (SeriesEpisodeController.dashboard):
+ * the series plus its episodes grouped by lane (upcoming = ideas, drafted,
+ * published) and the per-item performance notes, each episode compacted through
+ * summarizeEpisode so the drafted/published lanes carry deep-link routes.
+ */
+export function summarizeDashboard(
+	dashboard: unknown,
+): Record<string, unknown> {
+	const d = asRecord(dashboard);
+	const lane = (v: unknown): EpisodeSummary[] =>
+		Array.isArray(v) ? v.map(summarizeEpisode) : [];
+	return {
+		series: summarizeSeries(d.series),
+		upcoming: lane(d.upcoming),
+		drafted: lane(d.drafted),
+		published: lane(d.published),
+		performance_notes: Array.isArray(d.performance_notes)
+			? d.performance_notes
+			: [],
+	};
+}
+
+// ── Scheduled-post (calendar) summarization + bounds ──────────────────────────
+
+// The scheduled-post statuses the calendar list can filter on
+// (ScheduledPost.statuses/0). Kept in sync with the controller's ?status= enum.
+export const SCHEDULED_POST_STATUSES = [
+	"scheduled",
+	"reminded",
+	"posted",
+	"publishing",
+	"published",
+	"failed",
+	"canceled",
+] as const;
+
+// The platforms a reminder can target (ScheduledPost @platforms). "other" is the
+// pure-reminder platform (no account may ever attach); these tools never attach
+// an account anyway, so all three are reminder-only from the agent's side.
+export const SCHEDULED_POST_PLATFORMS = [
+	"tiktok",
+	"instagram",
+	"other",
+] as const;
+
+// Server bounds mirrored so the tool fails fast with a precise message instead of
+// round-tripping to a 422 (ScheduledPost @max_hashtags / @max_hashtag_length +
+// the caption validate_length). @max_pending_scheduled_posts is surfaced in the
+// description, not enforced client-side (the count is server state).
+export const MAX_CAPTION_LENGTH = 5000;
+export const MAX_HASHTAGS = 30;
+export const MAX_HASHTAG_LENGTH = 100;
+export const MAX_PENDING_SCHEDULED_POSTS = 500;
+
+/**
+ * Validates the schedule_post caption + hashtags against the ScheduledPost
+ * changeset bounds (caption ≤5000, ≤30 hashtags, each ≤100 chars). Returns an
+ * error string naming the exact bound, or null when valid. Kept in code (not
+ * Zod) so the flat tool schema stays TS2589-safe and the message is actionable.
+ */
+export function validateScheduledPostCopy(args: {
+	caption?: string;
+	hashtags?: string[];
+}): string | null {
+	if (
+		typeof args.caption === "string" &&
+		args.caption.length > MAX_CAPTION_LENGTH
+	) {
+		return `caption must be at most ${MAX_CAPTION_LENGTH} characters.`;
+	}
+	if (args.hashtags !== undefined) {
+		if (args.hashtags.length > MAX_HASHTAGS) {
+			return `Provide at most ${MAX_HASHTAGS} hashtags (got ${args.hashtags.length}).`;
+		}
+		const tooLong = args.hashtags.find((h) => h.length > MAX_HASHTAG_LENGTH);
+		if (tooLong !== undefined) {
+			return `each hashtag must be at most ${MAX_HASHTAG_LENGTH} characters.`;
+		}
+	}
+	return null;
+}
+
+/**
+ * Builds the schedule_post create body from the tool args. REMINDER-ONLY: this
+ * NEVER threads a social-account id, so the resulting post is always a manual-
+ * posting reminder the WriteScope floor authorizes with video:generate. Drops
+ * undefined so the server sees a clean shape; blank strings are omitted.
+ */
+export function buildScheduledPostBody(args: {
+	video_result_id: number;
+	platform: string;
+	scheduled_at: string;
+	caption?: string;
+	hashtags?: string[];
+	timezone?: string;
+	campaign_pack_item_id?: number;
+}): Record<string, unknown> {
+	const body: Record<string, unknown> = {
+		video_result_id: args.video_result_id,
+		platform: args.platform,
+		scheduled_at: args.scheduled_at,
+	};
+	const str = (v: string | undefined) =>
+		typeof v === "string" && v.trim() !== "" ? v : undefined;
+	const caption = str(args.caption);
+	if (caption !== undefined) body.caption = caption;
+	if (args.hashtags !== undefined) body.hashtags = args.hashtags;
+	const timezone = str(args.timezone);
+	if (timezone !== undefined) body.timezone = timezone;
+	if (args.campaign_pack_item_id !== undefined)
+		body.campaign_pack_item_id = args.campaign_pack_item_id;
+	return body;
+}
+
+/** One scheduled post, trimmed to what an agent managing a calendar needs. */
+export interface ScheduledPostSummary {
+	id: unknown;
+	platform: unknown;
+	status: unknown;
+	video_result_id: unknown;
+	video_url: unknown;
+	video_factory_kind: unknown;
+	campaign_pack_item_id: unknown;
+	caption: unknown;
+	hashtags: unknown;
+	scheduled_at: unknown;
+	timezone: unknown;
+	posted_at: unknown;
+	published_at: unknown;
+	error_message: unknown;
+}
+
+/**
+ * Summarizes one raw scheduled post (ScheduledPostController serializer) into the
+ * compact calendar shape. Deliberately DROPS `tiktok_account_id` /
+ * `instagram_account_id` / `video_post_id` / `platform_params`: these tools are
+ * reminder-only and must not surface (or invite acting on) the auto-publish
+ * account binding. `video_url` is the presigned export the user posts manually.
+ */
+export function summarizeScheduledPost(post: unknown): ScheduledPostSummary {
+	const p = asRecord(post);
+	return {
+		id: p.id,
+		platform: p.platform,
+		status: p.status,
+		video_result_id: p.video_result_id ?? null,
+		video_url: p.video_url ?? null,
+		video_factory_kind: p.video_factory_kind ?? null,
+		campaign_pack_item_id: p.campaign_pack_item_id ?? null,
+		caption: p.caption ?? null,
+		hashtags: p.hashtags ?? [],
+		scheduled_at: p.scheduled_at ?? null,
+		timezone: p.timezone ?? null,
+		posted_at: p.posted_at ?? null,
+		published_at: p.published_at ?? null,
+		error_message: p.error_message ?? null,
+	};
+}
+
+// ── Calendar 403 (scope) message augmentation ─────────────────────────────────
+
+/**
+ * Augments a generic `insufficient_scope` (403) message for the reminder-only
+ * calendar writes. These tools never send a social-account id, so a scope
+ * refusal can only mean one of two things — spell BOTH out so the agent knows it
+ * isn't a tool bug and can't fix it by retrying:
+ *
+ *   1. the TARGETED post already carries a social account (an auto-publish set up
+ *      in the app), so touching it needs `account:admin`; or
+ *   2. the token predates the reminder-calendar scope split (it lacks the write
+ *      scope the pipeline floor now accepts for reminder-only calendar writes).
+ *
+ * Publishing stays human/app-only either way. Returns the original message
+ * unchanged for any non-403 / non-scope error so other failures read normally.
+ */
+export function calendarScopeErrorText(
+	status: number | undefined,
+	code: string | undefined,
+	message: string,
+): string {
+	if (status !== 403 || code !== "insufficient_scope") return message;
+	return (
+		`${message} This calendar tool only creates manual-posting REMINDERS and never attaches a social ` +
+		"account, so this scope refusal means either the targeted post already references a social account " +
+		"(an app-only auto-publish that needs account:admin) or the token predates the reminder-calendar " +
+		"permission. Publishing stays in the app; reschedule/cancel/mark a reminder-only post instead."
+	);
+}