@hubfluencer/mcp 0.4.0 → 0.6.0

package/src/output-schemas.ts

@@ -0,0 +1,360 @@
+/**
+ * `outputSchema`s for the STABLE tool envelopes — paired with the
+ * `structuredContent` each of those tools already returns.
+ *
+ * WHY THESE LIVE HERE (not inline in index.ts):
+ *   1. index.ts boots a live stdio MCP server at module load, so it can't be
+ *      imported from a unit test (see core.ts header). Declaring the schemas here
+ *      lets test/output-schemas.test.ts validate each one against a representative
+ *      `ok()` payload — a mismatch between a schema and the structuredContent it
+ *      guards throws an McpError at call time (the SDK runs
+ *      `safeParseAsync(outputSchema, structuredContent)` on every result), which
+ *      breaks strict clients, so it must be caught in CI, not in production.
+ *   2. One place to keep the schema and its payload in lock-step.
+ *
+ * WHAT THE SDK DOES WITH THEM: `McpServer.registerTool` accepts a Zod schema (or
+ * raw shape) as `outputSchema`; it converts it to draft-07 JSON Schema for the
+ * `tools/list` wire (so clients see typed output) and validates every non-error
+ * result's `structuredContent` against it. There is NO raw-JSON-Schema path — a
+ * plain object would be rejected at registration — so these are Zod objects,
+ * exactly like every `inputSchema` in index.ts.
+ *
+ * DESIGN — permissive by construction (the schema must NEVER reject a real
+ * payload):
+ *   - Every top-level object is `.passthrough()`. On the wire that emits
+ *     `additionalProperties: {}` (JSON Schema draft-07 "any extra key allowed"),
+ *     and at runtime it keeps unknown keys instead of failing — so a server that
+ *     adds a field, or a handler that threads an extra `note`/`kind_detail`, never
+ *     trips validation.
+ *   - Fields the MCP layer itself constructs with a guaranteed type (the
+ *     normalizeStatus booleans, a handler-set `slug`/`charged`/`saved_to`) are
+ *     typed precisely — that's the useful signal for a client.
+ *   - Fields passed THROUGH from server data whose type can legitimately vary
+ *     (credit counts, captions, hashtags, nested items, whole server aggregates)
+ *     are `z.unknown()` / permissive arrays. A too-strict type here would be the
+ *     one thing that throws.
+ *   - No field is `.required()` unless the handler ALWAYS sets it, and even then
+ *     we keep the set minimal so an unusual response can't fail the required check.
+ *
+ * These mirror the exact `ok(...)` shapes in index.ts; a drift on either side is a
+ * bug the paired test is meant to catch.
+ */
+
+import { z } from "zod";
+
+/** A presigned URL or a local-null field that may be absent/variable. */
+const urlish = z.unknown().optional();
+
+// ── Status envelopes (normalizeStatus output) ────────────────────────────────
+//
+// get_status returns NormalizedStatus verbatim; wait_for_completion adds
+// {saved_to, timed_out}. Every field except video_url/error is set by
+// normalizeStatus with a guaranteed type (stage falls back to "unknown"), so
+// those are typed precisely; video_url/error are string|null.
+
+/** get_status → the normalized {kind, slug, stage, terminal, ready, …} shape. */
+export const getStatusOutput = z
+	.object({
+		kind: z.string().optional(),
+		slug: z.string().optional(),
+		stage: z.string().optional(),
+		terminal: z.boolean().optional(),
+		ready: z.boolean().optional(),
+		video_url: z.union([z.string(), z.null()]).optional(),
+		error: z.union([z.string(), z.null()]).optional(),
+	})
+	.passthrough();
+
+/** wait_for_completion → get_status plus the download/timeout bookkeeping. */
+export const waitForCompletionOutput = z
+	.object({
+		kind: z.string().optional(),
+		slug: z.string().optional(),
+		stage: z.string().optional(),
+		terminal: z.boolean().optional(),
+		ready: z.boolean().optional(),
+		video_url: z.union([z.string(), z.null()]).optional(),
+		error: z.union([z.string(), z.null()]).optional(),
+		saved_to: z.union([z.string(), z.null()]).optional(),
+		timed_out: z.boolean().optional(),
+	})
+	.passthrough();
+
+// ── Credits ──────────────────────────────────────────────────────────────────
+
+/** get_credits → the whitelisted balance fields (server values, kept permissive). */
+export const getCreditsOutput = z
+	.object({
+		credits: z.unknown().optional(),
+		spendable_credits: z.unknown().optional(),
+		reserved_credits: z.unknown().optional(),
+		remaining_reserved_credits: z.unknown().optional(),
+		message: z.unknown().optional(),
+	})
+	.passthrough();
+
+// ── Download ───────────────────────────────────────────────────────────────────
+
+/** download_result → the presigned URL and, when saved, the path + byte count. */
+export const downloadResultOutput = z
+	.object({
+		video_url: z.union([z.string(), z.null()]).optional(),
+		saved_to: z.union([z.string(), z.null()]).optional(),
+		bytes: z.number().optional(),
+		note: z.string().optional(),
+	})
+	.passthrough();
+
+// ── Sliders (carousels) ────────────────────────────────────────────────────────
+
+/** One slide inside the get_slider deliverable (server-sourced fields → permissive). */
+const sliderSlide = z
+	.object({
+		position: z.unknown().optional(),
+		image_url: urlish,
+		headline: z.unknown().optional(),
+		body: z.unknown().optional(),
+		kicker: z.unknown().optional(),
+		status: z.unknown().optional(),
+	})
+	.passthrough();
+
+/** get_slider → carousel status + the per-slide deliverable. */
+export const getSliderOutput = z
+	.object({
+		slug: z.string().optional(),
+		kind: z.string().optional(),
+		status: z.string().optional(),
+		stage: z.string().optional(),
+		terminal: z.boolean().optional(),
+		completed: z.boolean().optional(),
+		error: z.union([z.string(), z.null()]).optional(),
+		caption: z.union([z.string(), z.null()]).optional(),
+		hashtags: z.array(z.unknown()).optional(),
+		slides: z.array(sliderSlide).optional(),
+	})
+	.passthrough();
+
+// ── Projects listing ────────────────────────────────────────────────────────────
+
+/** A normalized status row inside list_projects (permissive — server-derived). */
+const projectRow = z
+	.object({
+		kind: z.string().optional(),
+		slug: z.string().optional(),
+		stage: z.string().optional(),
+		terminal: z.boolean().optional(),
+		ready: z.boolean().optional(),
+		video_url: z.union([z.string(), z.null()]).optional(),
+		error: z.union([z.string(), z.null()]).optional(),
+	})
+	.passthrough();
+
+/** list_projects → the two normalized lanes plus an optional truncation note. */
+export const listProjectsOutput = z
+	.object({
+		shorts: z.array(projectRow).optional(),
+		projects: z.array(projectRow).optional(),
+		note: z.string().optional(),
+	})
+	.passthrough();
+
+// ── Create-tool results ────────────────────────────────────────────────────────
+//
+// The draft-create tools all return a small {slug, kind, next?} envelope; the
+// autopilot creators (create_editor_ad, create_editor_draft) also nest a
+// normalizeStatus `status`. make_video returns the richest shape (a full status
+// spread plus pricing/charge bookkeeping, OR — on dry_run / over-cap / short
+// balance — a not-charged pricing envelope); one permissive schema covers both
+// of its branches.
+
+/** create_short / create_slider → the draft slug + a next-step hint. */
+export const createDraftOutput = z
+	.object({
+		slug: z.union([z.string(), z.null()]).optional(),
+		kind: z.string().optional(),
+		next: z.string().optional(),
+	})
+	.passthrough();
+
+/** create_editor_ad / create_editor_draft → the draft slug + nested status. */
+export const createEditorOutput = z
+	.object({
+		slug: z.union([z.string(), z.null()]).optional(),
+		kind: z.string().optional(),
+		status: projectRow.optional(),
+		next: z.string().optional(),
+	})
+	.passthrough();
+
+/** make_video → the finished/timed-out status + pricing, or a not-charged draft. */
+export const makeVideoOutput = z
+	.object({
+		slug: z.union([z.string(), z.null()]).optional(),
+		kind: z.string().optional(),
+		kind_inferred: z.boolean().optional(),
+		stage: z.string().optional(),
+		terminal: z.boolean().optional(),
+		ready: z.boolean().optional(),
+		video_url: z.union([z.string(), z.null()]).optional(),
+		error: z.union([z.string(), z.null()]).optional(),
+		estimated_credits: z.unknown().optional(),
+		available_credits: z.unknown().optional(),
+		affordable: z.boolean().optional(),
+		charged: z.boolean().optional(),
+		saved_to: z.union([z.string(), z.null()]).optional(),
+		timed_out: z.boolean().optional(),
+		note: z.string().optional(),
+	})
+	.passthrough();
+
+// ── Campaign engine (high-value new tools) ─────────────────────────────────────
+
+/** A summarized campaign-pack item (summarizePackItem) — server fields permissive. */
+const packItem = z
+	.object({
+		id: z.unknown().optional(),
+		kind: z.unknown().optional(),
+		status: z.unknown().optional(),
+		hook: z.unknown().optional(),
+		video_factory_slug: z.union([z.string(), z.null()]).optional(),
+		slider_slug: z.union([z.string(), z.null()]).optional(),
+		draft_slug: z.union([z.string(), z.null()]).optional(),
+		draft_route: z.union([z.string(), z.null()]).optional(),
+		credit_estimate: z.unknown().optional(),
+		preview_url: z.unknown().optional(),
+		video_result_id: z.unknown().optional(),
+	})
+	.passthrough();
+
+/** get_campaign_pack → the summarized pack (summarizePack) with its items. */
+export const getCampaignPackOutput = z
+	.object({
+		id: z.unknown().optional(),
+		title: z.unknown().optional(),
+		status: z.unknown().optional(),
+		source_type: z.unknown().optional(),
+		source_url: z.unknown().optional(),
+		brief: z.unknown().optional(),
+		product_profile_id: z.unknown().optional(),
+		brand_profile_id: z.unknown().optional(),
+		item_count: z.number().optional(),
+		items: z.array(packItem).optional(),
+	})
+	.passthrough();
+
+/** create_campaign → the orchestrator result (runCreateCampaign / CreateCampaignResult). */
+export const createCampaignOutput = z
+	.object({
+		product_profile_id: z.union([z.number(), z.null()]).optional(),
+		campaign_pack_id: z.union([z.number(), z.null()]).optional(),
+		brand_profile_id: z.union([z.number(), z.null()]).optional(),
+		extracted: z
+			.union([
+				z
+					.object({
+						source_url: z.union([z.string(), z.null()]).optional(),
+						confidence: z.unknown().optional(),
+						name: z.unknown().optional(),
+					})
+					.passthrough(),
+				z.null(),
+			])
+			.optional(),
+		imported: z
+			.object({
+				primary_image: z.boolean().optional(),
+				logo: z.boolean().optional(),
+			})
+			.passthrough()
+			.optional(),
+		items: z.array(packItem).optional(),
+		summary: z
+			.object({
+				created: z.number().optional(),
+				materialized: z.number().optional(),
+				planned: z.number().optional(),
+			})
+			.passthrough()
+			.optional(),
+		steps: z
+			.array(
+				z
+					.object({
+						step: z.string().optional(),
+						ok: z.boolean().optional(),
+						detail: z.string().optional(),
+					})
+					.passthrough(),
+			)
+			.optional(),
+		next: z.string().optional(),
+		note: z.string().optional(),
+	})
+	.passthrough();
+
+// ── Series + calendar ──────────────────────────────────────────────────────────
+
+/** A summarized episode row inside the dashboard lanes (server fields permissive). */
+const episodeRow = z
+	.object({
+		id: z.unknown().optional(),
+		status: z.unknown().optional(),
+		draft_slug: z.union([z.string(), z.null()]).optional(),
+		draft_route: z.union([z.string(), z.null()]).optional(),
+	})
+	.passthrough();
+
+/** get_series_dashboard → the series + its lanes + per-item performance notes. */
+export const getSeriesDashboardOutput = z
+	.object({
+		series: z.record(z.string(), z.unknown()).optional(),
+		upcoming: z.array(episodeRow).optional(),
+		drafted: z.array(episodeRow).optional(),
+		published: z.array(episodeRow).optional(),
+		performance_notes: z.array(z.unknown()).optional(),
+	})
+	.passthrough();
+
+/** One summarized scheduled post (summarizeScheduledPost) — server fields permissive. */
+const scheduledPost = z
+	.object({
+		id: z.unknown().optional(),
+		platform: z.unknown().optional(),
+		status: z.unknown().optional(),
+		video_result_id: z.unknown().optional(),
+		video_url: z.unknown().optional(),
+		video_factory_kind: z.unknown().optional(),
+		campaign_pack_item_id: z.unknown().optional(),
+		caption: z.unknown().optional(),
+		hashtags: z.unknown().optional(),
+		scheduled_at: z.unknown().optional(),
+		timezone: z.unknown().optional(),
+		posted_at: z.unknown().optional(),
+		published_at: z.unknown().optional(),
+		error_message: z.unknown().optional(),
+	})
+	.passthrough();
+
+/** list_scheduled_posts → the calendar list. */
+export const listScheduledPostsOutput = z
+	.object({
+		posts: z.array(scheduledPost).optional(),
+	})
+	.passthrough();
+
+// ── Performance ────────────────────────────────────────────────────────────────
+
+/**
+ * get_recommendations → the server aggregate passed through UNCHANGED. Its exact
+ * fields (top hook/format/language, best items, confidence, note) are the
+ * server's to state and can evolve, so this stays a permissive open object —
+ * enough to signal "structured object" to a client without ever rejecting the
+ * aggregate.
+ */
+export const getRecommendationsOutput = z
+	.object({
+		confidence: z.unknown().optional(),
+		note: z.unknown().optional(),
+	})
+	.passthrough();