@tomako/tools-runtime 0.1.0

package/src/lib/tools/product-poster-generator-schema.ts

@@ -0,0 +1,215 @@
+import { z } from "zod";
+
+export const PRODUCT_POSTER_GENERATOR_SCENE = "product_poster_generator";
+export const PRODUCT_POSTER_GENERATOR_RESULT_TYPE = "product_poster_generation";
+export const PRODUCT_POSTER_GENERATOR_PROMPT_VERSION = "product-poster-generator.v1";
+
+export const PRODUCT_POSTER_CHANNELS = [
+  "websiteHero",
+  "socialLaunch",
+  "paidAd",
+  "productHunt",
+  "ogImage",
+] as const;
+
+export const PRODUCT_POSTER_SCENES = [
+  "landingPage",
+  "featureLaunch",
+  "paidCampaign",
+  "communityLaunch",
+  "contentCover",
+] as const;
+
+export const PRODUCT_POSTER_FORMATS = [
+  "multiSize",
+  "ultrawide",
+  "landscape",
+  "landscape32",
+  "landscape43",
+  "square",
+  "portrait34",
+  "portrait",
+  "story",
+] as const;
+
+export const PRODUCT_POSTER_STYLES = [
+  "cleanSaas",
+  "boldLaunch",
+  "premiumEditorial",
+  "playfulApp",
+  "enterpriseTrust",
+] as const;
+
+export type ProductPosterChannel = (typeof PRODUCT_POSTER_CHANNELS)[number];
+export type ProductPosterScene = (typeof PRODUCT_POSTER_SCENES)[number];
+export type ProductPosterFormat = (typeof PRODUCT_POSTER_FORMATS)[number];
+export type ProductPosterStyle = (typeof PRODUCT_POSTER_STYLES)[number];
+
+const nonEmptyString = z.string().trim().min(1);
+const optionalReferenceUrlSchema = z
+  .string()
+  .trim()
+  .url()
+  .optional()
+  .or(z.literal(""))
+  .default("");
+
+export const productPosterGeneratorInputSchema = z
+  .object({
+    productName: z.string().trim().min(2).max(80),
+    productUrl: z
+      .string()
+      .trim()
+      .max(180)
+      .optional()
+      .or(z.literal("")),
+    productContext: z.string().trim().min(8).max(900),
+    audience: z.string().trim().min(3).max(140),
+    targetScene: z.enum(PRODUCT_POSTER_SCENES),
+    primaryCta: z.string().trim().min(2).max(60),
+    channel: z.enum(PRODUCT_POSTER_CHANNELS),
+    format: z.enum(PRODUCT_POSTER_FORMATS),
+    style: z.enum(PRODUCT_POSTER_STYLES),
+    brandColors: z.string().trim().max(120).optional().or(z.literal("")),
+    screenshotNames: z.array(z.string()).max(4).default([]),
+    logoName: z.string().optional(),
+    logoReferenceImageUrl: optionalReferenceUrlSchema,
+    screenshotReferenceImageUrls: z.array(z.string().trim().url()).max(4).optional().default([]),
+    referenceImageUrls: z.array(z.string().trim().url()).max(4).optional().default([]),
+  })
+  .superRefine((value, ctx) => {
+    const url = value.productUrl?.trim();
+    if (url) {
+      try {
+        const parsed = new URL(url);
+        if (!["http:", "https:"].includes(parsed.protocol)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["productUrl"],
+            message: "invalid_url",
+          });
+        }
+      } catch {
+        ctx.addIssue({
+          code: "custom",
+          path: ["productUrl"],
+          message: "invalid_url",
+        });
+      }
+    }
+
+    const compactContext = value.productContext
+      .trim()
+      .replace(/\s+/g, "")
+      .toLowerCase();
+    if (
+      /^[\d._-]+$/.test(compactContext) ||
+      /^(test|demo|example|测试|占位|随便)+$/i.test(compactContext)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["productContext"],
+        message: "weak_context",
+      });
+    }
+  });
+
+export type ProductPosterGeneratorInput = z.infer<
+  typeof productPosterGeneratorInputSchema
+>;
+
+export const productPosterGenerationResultSchema = z.object({
+  promptId: z.string().trim().optional(),
+  promptVersion: z
+    .literal(PRODUCT_POSTER_GENERATOR_PROMPT_VERSION)
+    .or(z.string().trim().min(1))
+    .optional(),
+  summary: nonEmptyString,
+  product: z.object({
+    name: nonEmptyString,
+    url: z.string().trim().url().optional().nullable(),
+    audience: nonEmptyString,
+    context: nonEmptyString,
+  }),
+  creativeDirection: z.object({
+    targetScene: z.enum(PRODUCT_POSTER_SCENES),
+    channel: z.enum(PRODUCT_POSTER_CHANNELS),
+    format: z.enum(PRODUCT_POSTER_FORMATS),
+    style: z.enum(PRODUCT_POSTER_STYLES),
+    primaryCta: nonEmptyString,
+    brandColors: z.string().trim().optional(),
+    size: z.string().trim().optional(),
+  }),
+  image: z.object({
+    imageTaskId: nonEmptyString,
+    imageUrl: z.string().trim().url(),
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    model: z.string().trim().optional(),
+    size: z.string().trim().optional(),
+  }),
+  generationPrompt: z.string().trim().optional(),
+  assets: z
+    .object({
+      logoName: z.string().trim().optional(),
+      screenshotNames: z.array(z.string().trim()).default([]),
+      referenceImageCount: z.number().int().nonnegative().default(0),
+      imageModelReferenceCount: z.number().int().nonnegative().optional(),
+      logoReferenceImageUrl: z.string().trim().url().optional(),
+      exactLogoApplied: z.boolean().optional(),
+      originalGeneratedImageUrl: z.string().trim().url().optional(),
+      logoPlacement: z
+        .object({
+          left: z.number().nonnegative(),
+          top: z.number().nonnegative(),
+          width: z.number().positive(),
+          height: z.number().positive(),
+        })
+        .optional(),
+      note: z.string().trim().optional(),
+    })
+    .optional(),
+  reviewChecklist: z.array(nonEmptyString).default([]),
+  limitations: z.array(nonEmptyString).default([]),
+  generatedAt: z.string().trim().optional(),
+});
+
+export type ProductPosterGenerationResult = z.infer<
+  typeof productPosterGenerationResultSchema
+>;
+
+export function createProductPosterImage(input: ProductPosterGeneratorInput) {
+  const colorNote = input.brandColors?.trim()
+    ? input.brandColors.trim()
+    : "Extract a restrained palette from the logo, screenshot, and product URL.";
+  const assetNote = [
+    input.logoName ? `Logo: ${input.logoName}` : "Logo: not uploaded",
+    input.screenshotNames.length
+      ? `Screenshots: ${input.screenshotNames.join(", ")}`
+      : "Screenshots: not uploaded",
+  ];
+
+  return {
+    product: {
+      name: input.productName.trim(),
+      url: input.productUrl?.trim() || null,
+      audience: input.audience.trim(),
+      context: input.productContext.trim(),
+    },
+    creativeDirection: {
+      targetScene: input.targetScene,
+      channel: input.channel,
+      format: input.format,
+      style: input.style,
+      primaryCta: input.primaryCta.trim(),
+      brandColors: colorNote,
+    },
+    posterChecklist: [
+      "Show the real product interface or a faithful screenshot crop.",
+      "Keep headline, subheadline, and CTA readable at the selected format.",
+      "Match color, logo, and screenshot treatment to the product brand.",
+      "Avoid unsupported claims, fake customer logos, private data, and cluttered UI.",
+    ],
+    expectedAssets: assetNote,
+  };
+}

package/src/lib/tools/product-ui-generator-schema.ts

@@ -0,0 +1,157 @@
+import { z } from "zod";
+
+export const PRODUCT_UI_GENERATOR_RESULT_TYPE = "product_ui_generation";
+export const PRODUCT_UI_GENERATOR_SCENE = "product_ui_generator";
+export const PRODUCT_UI_GENERATOR_PROMPT_VERSION = "product-ui-generator.v1";
+
+export const productUiPlatformSchema = z.enum(["web", "mobile", "desktop", "mixed"]);
+export const productUiToneSchema = z.enum([
+  "premium",
+  "minimal",
+  "playful",
+  "editorial",
+  "enterprise",
+]);
+export const productUiLanguageSchema = z.enum(["zh", "en"]);
+
+export const PRODUCT_UI_PLATFORMS = productUiPlatformSchema.options;
+export const PRODUCT_UI_TONES = productUiToneSchema.options;
+export const PRODUCT_UI_LANGUAGES = productUiLanguageSchema.options;
+
+const optionalText = (max = 1200) => z.string().trim().max(max).optional().default("");
+
+const placeholderPattern =
+  /^(test|demo|placeholder|asdf|qwer|123|1234|111|xxx|随便|测试|示例)$/i;
+
+export const productUiInputSchema = z
+  .object({
+    productName: optionalText(100),
+    idea: z.string().trim().min(24).max(2400),
+    targetUsers: optionalText(240),
+    coreScenario: optionalText(360),
+    platform: productUiPlatformSchema.default("mixed"),
+    tone: productUiToneSchema.default("premium"),
+    language: productUiLanguageSchema.default("zh"),
+    mustInclude: optionalText(1000),
+    mustAvoid: optionalText(800),
+  })
+  .superRefine((value, ctx) => {
+    if (placeholderPattern.test(value.idea) || /^\d+$/.test(value.idea)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["idea"],
+        message: "Please describe a real product idea, not a placeholder.",
+      });
+    }
+    if (value.targetUsers && placeholderPattern.test(value.targetUsers)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["targetUsers"],
+        message: "Please describe the real audience or leave this empty.",
+      });
+    }
+  });
+
+export const productUiScreenSchema = z.object({
+  id: z.string().trim().min(1).max(80),
+  title: z.string().trim().min(1).max(120),
+  platform: z.string().trim().min(1).max(80),
+  purpose: z.string().trim().min(1).max(260),
+  layout: z.string().trim().min(1).max(500),
+  visualDirection: z.string().trim().min(1).max(500),
+  keyInteractions: z.array(z.string().trim().min(1).max(260)).min(1).max(8),
+  implementationPrompt: z.string().trim().min(1).max(1200),
+});
+
+export const productUiVisualSystemSchema = z.object({
+  mood: z.string().trim().min(1).max(240),
+  palette: z.array(z.string().trim().min(1).max(80)).min(3).max(8),
+  typography: z.array(z.string().trim().min(1).max(160)).min(1).max(5),
+  components: z.array(z.string().trim().min(1).max(180)).min(3).max(12),
+  motion: z.array(z.string().trim().min(1).max(180)).default([]),
+});
+
+export const productUiOnePageSchema = z.object({
+  productDefinition: z.string().trim().min(1).max(1600),
+  featureDetails: z.array(z.string().trim().min(1).max(500)).min(3).max(12),
+  businessRequirements: z.array(z.string().trim().min(1).max(500)).min(3).max(12),
+  userScenarios: z.array(z.string().trim().min(1).max(400)).min(2).max(8),
+  codingPrompt: z.string().trim().min(1).max(5000),
+});
+
+export const productUiResultSchema = z.object({
+  resultStatus: z.enum(["final"]).default("final"),
+  productName: z.string().trim().min(1).max(120),
+  summary: z.string().trim().min(1).max(900),
+  designThesis: z.string().trim().min(1).max(900),
+  screens: z.array(productUiScreenSchema).min(3).max(8),
+  visualSystem: productUiVisualSystemSchema,
+  interactionFlow: z.array(z.string().trim().min(1).max(300)).min(3).max(10),
+  exportOnePage: productUiOnePageSchema,
+  missingInfo: z.array(z.string().trim().min(1).max(500)).default([]),
+  risks: z.array(z.string().trim().min(1).max(500)).default([]),
+  promptVersion: z.string().trim().min(1).max(120).default(PRODUCT_UI_GENERATOR_PROMPT_VERSION),
+  generatedAt: z.string().trim().max(80).optional(),
+});
+
+export type ProductUiPlatform = z.infer<typeof productUiPlatformSchema>;
+export type ProductUiTone = z.infer<typeof productUiToneSchema>;
+export type ProductUiLanguage = z.infer<typeof productUiLanguageSchema>;
+export type ProductUiInput = z.infer<typeof productUiInputSchema>;
+export type ProductUiScreen = z.infer<typeof productUiScreenSchema>;
+export type ProductUiResult = z.infer<typeof productUiResultSchema>;
+
+export function normalizeProductUiResult(value: unknown): ProductUiResult | null {
+  const parsed = productUiResultSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+export function stringifyProductUiOnePage(result: ProductUiResult): string {
+  const lines = [
+    `# ${result.productName} UI OnePage`,
+    "",
+    "## Product definition",
+    result.exportOnePage.productDefinition,
+    "",
+    "## Design thesis",
+    result.designThesis,
+    "",
+    "## Feature details",
+    ...result.exportOnePage.featureDetails.map((item) => `- ${item}`),
+    "",
+    "## Business and requirements",
+    ...result.exportOnePage.businessRequirements.map((item) => `- ${item}`),
+    "",
+    "## User scenarios",
+    ...result.exportOnePage.userScenarios.map((item) => `- ${item}`),
+    "",
+    "## Visual system",
+    `Mood: ${result.visualSystem.mood}`,
+    `Palette: ${result.visualSystem.palette.join(", ")}`,
+    `Typography: ${result.visualSystem.typography.join("; ")}`,
+    `Components: ${result.visualSystem.components.join("; ")}`,
+    "",
+    "## Screens",
+    ...result.screens.flatMap((screen, index) => [
+      `### ${index + 1}. ${screen.title}`,
+      `Platform: ${screen.platform}`,
+      `Purpose: ${screen.purpose}`,
+      `Layout: ${screen.layout}`,
+      `Visual direction: ${screen.visualDirection}`,
+      "Interactions:",
+      ...screen.keyInteractions.map((item) => `- ${item}`),
+      "Implementation prompt:",
+      screen.implementationPrompt,
+      "",
+    ]),
+    "## Coding prompt",
+    result.exportOnePage.codingPrompt,
+    "",
+    "## Risks and review notes",
+    ...(result.risks.length ? result.risks : ["Review generated UI copy, legal claims, and production data before launch."]).map(
+      (item) => `- ${item}`,
+    ),
+  ];
+
+  return lines.join("\n");
+}

package/src/lib/tools/reddit-pain-point-finder-schema.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+
+export const REDDIT_PAIN_POINT_FINDER_RESULT_TYPE = "reddit_pain_point_report";
+export const REDDIT_PAIN_POINT_FINDER_SCENE = "reddit_pain_point_finder";
+export const REDDIT_PAIN_POINT_FINDER_PROMPT_VERSION =
+  "reddit-pain-point-finder.v1";
+
+const invalidDirectionPattern =
+  /^(test|demo|placeholder|asdf|123|111|hello|hi|idea|startup idea|pain point)$/i;
+
+export const redditPainPointFinderInputSchema = z.object({
+  direction: z
+    .string()
+    .trim()
+    .min(12)
+    .max(900)
+    .refine((value) => !invalidDirectionPattern.test(value), "placeholder"),
+  audience: z.string().trim().max(240).optional(),
+  sourceMix: z
+    .enum(["all", "reddit", "x", "hacker_news", "reddit_hn"])
+    .default("all"),
+});
+
+export type RedditPainPointFinderInput = z.infer<
+  typeof redditPainPointFinderInputSchema
+>;
+
+const confidence = z.enum(["low", "medium", "high"]).catch("low");
+const signalStrength = z.enum(["weak", "mixed", "strong"]).catch("mixed");
+const paymentIntent = z.enum(["low", "medium", "high", "unknown"]).catch("unknown");
+
+const sourceSchema = z.object({
+  platform: z.string(),
+  label: z.string(),
+  url: z.string().optional(),
+  note: z.string().optional(),
+});
+
+const communitySchema = z.object({
+  platform: z.string(),
+  name: z.string(),
+  whyRelevant: z.string(),
+  searchQuery: z.string().optional(),
+});
+
+const complaintSchema = z.object({
+  theme: z.string(),
+  plainLanguageComplaint: z.string(),
+  userQuotes: z.array(z.string()).default([]),
+  frequency: signalStrength,
+  paidIntent: paymentIntent,
+  whyItHurts: z.string(),
+  smallFeature: z.string(),
+  landingPageAngle: z.string(),
+  confidence,
+  sources: z.array(sourceSchema).default([]),
+});
+
+const wedgeSchema = z.object({
+  title: z.string(),
+  targetUser: z.string(),
+  promise: z.string(),
+  featureScope: z.array(z.string()).default([]),
+  landingPageHero: z.string(),
+  validationTest: z.string(),
+});
+
+export const redditPainPointFinderResultSchema = z.object({
+  directionTitle: z.string(),
+  summary: z.string(),
+  searchQueries: z.array(z.string()).default([]),
+  relevantCommunities: z.array(communitySchema).default([]),
+  topComplaints: z.array(complaintSchema).min(1),
+  opportunityWedges: z.array(wedgeSchema).default([]),
+  avoidBuilding: z.array(z.string()).default([]),
+  nextResearchSteps: z.array(z.string()).default([]),
+  sources: z.array(sourceSchema).default([]),
+  confidence,
+  boundaryNote: z.string(),
+  promptVersion: z.string().default(REDDIT_PAIN_POINT_FINDER_PROMPT_VERSION),
+  generatedAt: z.string().optional(),
+});
+
+export type RedditPainPointFinderResult = z.infer<
+  typeof redditPainPointFinderResultSchema
+>;
+export type RedditPainPointSignalStrength = z.infer<typeof signalStrength>;
+export type RedditPainPointPaymentIntent = z.infer<typeof paymentIntent>;

package/src/lib/tools/resolve-tool-locale-copy.ts

@@ -0,0 +1,75 @@
+import {
+  pickLocaleCopy,
+  resolvePrimaryLocale,
+  type PartialLocaleRecord,
+} from "../../i18n/locale-fallback";
+import type { AppLocale } from "../../i18n/locale";
+import enToolsPages from "../../i18n/messages/en/tools";
+import zhToolsPages from "../../i18n/messages/zh/tools";
+import type { ToolLocaleCopy, ToolSpec } from "../../features/tools/types";
+
+import { resolveToolsPagesKey } from "./tool-message-keys";
+
+type ToolPageModule = { meta?: ToolLocaleCopy };
+
+function toolsPagesForPrimary(locale: AppLocale): Record<string, ToolPageModule> {
+  return (resolvePrimaryLocale(locale) === "zh"
+    ? zhToolsPages
+    : enToolsPages) as unknown as Record<string, ToolPageModule>;
+}
+
+/** 从 i18n toolsPages.{camelSlug}.meta 读取 SEO 列表文案（legacy 迁移后唯一来源） */
+export function getToolI18nMeta(
+  slug: string,
+  locale: AppLocale,
+): ToolLocaleCopy | undefined {
+  const key = resolveToolsPagesKey(slug);
+  const pages = toolsPagesForPrimary(locale);
+  const mod = pages[key as keyof typeof pages];
+  if (mod && typeof mod === "object" && "meta" in mod && mod.meta) {
+    return mod.meta;
+  }
+  return undefined;
+}
+
+export function isPackageToolSpec(spec: ToolSpec): boolean {
+  return spec.widget?.mode === "package";
+}
+
+/** 解析工具在指定 locale 下的 SEO/list 文案；package 走 spec.locales，legacy 优先 i18n meta */
+export function resolveToolLocaleCopy(spec: ToolSpec, locale: AppLocale): ToolLocaleCopy {
+  if (isPackageToolSpec(spec) && spec.locales) {
+    return pickLocaleCopy(spec.locales, locale);
+  }
+
+  const fromI18n = getToolI18nMeta(spec.slug, locale);
+  if (fromI18n) return fromI18n;
+
+  if (spec.locales) {
+    return pickLocaleCopy(spec.locales, locale);
+  }
+
+  throw new Error(
+    `No locale copy for tool "${spec.slug}" (${locale}). Add i18n meta or spec.locales.`,
+  );
+}
+
+/** 组装完整 locales 记录（MCP catalog、sitemap 等） */
+export function resolveToolSpecLocales(spec: ToolSpec): PartialLocaleRecord<ToolLocaleCopy> {
+  if (isPackageToolSpec(spec) && spec.locales) {
+    return spec.locales;
+  }
+
+  const zh = getToolI18nMeta(spec.slug, "zh") ?? spec.locales?.zh;
+  const en = getToolI18nMeta(spec.slug, "en") ?? spec.locales?.en;
+
+  if (!zh || !en) {
+    throw new Error(`Missing zh/en locale copy for tool "${spec.slug}"`);
+  }
+
+  return { zh, en };
+}
+
+export function withResolvedLocales(spec: ToolSpec): ToolSpec {
+  return { ...spec, locales: resolveToolSpecLocales(spec) };
+}

package/src/lib/tools/slug.ts

@@ -0,0 +1,60 @@
+import { listToolDrafts } from "./draft-store";
+
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function slugifyToolName(input: string): string {
+  const normalized = input
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+
+  return normalized || "new-tool";
+}
+
+export function isValidToolSlug(slug: string): boolean {
+  return SLUG_RE.test(slug);
+}
+
+export function slugConflictReason(
+  slug: string,
+  options: { publishedSlugs: string[]; excludeDraftId?: string },
+): string | null {
+  if (!isValidToolSlug(slug)) {
+    return "invalid";
+  }
+
+  if (options.publishedSlugs.includes(slug)) {
+    return "published";
+  }
+
+  const draftTaken = listToolDrafts().some(
+    (draft) => draft.slug === slug && draft.id !== options?.excludeDraftId,
+  );
+  if (draftTaken) {
+    return "draft";
+  }
+
+  return null;
+}
+
+export function suggestUniqueSlug(
+  base: string,
+  options: { publishedSlugs: string[]; excludeDraftId?: string },
+): string {
+  const candidate = slugifyToolName(base);
+  if (!slugConflictReason(candidate, options)) {
+    return candidate;
+  }
+
+  for (let i = 2; i <= 20; i += 1) {
+    const next = `${candidate}-v${i}`;
+    if (!slugConflictReason(next, options)) {
+      return next;
+    }
+  }
+
+  return `${candidate}-${Date.now().toString(36)}`;
+}

package/src/lib/tools/social-listening-research-report-schema.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+
+export const SOCIAL_LISTENING_RESEARCH_REPORT_RESULT_TYPE =
+  "social_listening_research_report";
+export const SOCIAL_LISTENING_RESEARCH_REPORT_SCENE =
+  "social_listening_research_report";
+export const SOCIAL_LISTENING_RESEARCH_REPORT_PROMPT_VERSION =
+  "social-listening-research-report.v1";
+
+const invalidQuestionPattern =
+  /^(test|demo|placeholder|asdf|123|111|hello|hi|research|market research|social listening)$/i;
+
+export const socialListeningResearchReportInputSchema = z.object({
+  researchQuestion: z
+    .string()
+    .trim()
+    .min(15)
+    .max(1200)
+    .refine((value) => !invalidQuestionPattern.test(value), "placeholder"),
+  platforms: z.enum(["reddit_x", "reddit", "x", "all"]).default("reddit_x"),
+  audience: z.string().trim().max(240).optional(),
+  market: z.string().trim().max(120).optional(),
+});
+
+export type SocialListeningResearchReportInput = z.infer<
+  typeof socialListeningResearchReportInputSchema
+>;
+
+const confidence = z.enum(["low", "medium", "high"]).catch("low");
+const signalStrength = z.enum(["weak", "mixed", "strong"]).catch("mixed");
+const sentiment = z.enum(["negative", "mixed", "positive", "polarized"]).catch("mixed");
+
+const sourceSchema = z.object({
+  platform: z.string(),
+  label: z.string(),
+  url: z.string().optional(),
+  note: z.string().optional(),
+  confidence,
+});
+
+const quoteSchema = z.object({
+  text: z.string(),
+  sourceLabel: z.string(),
+  sourceUrl: z.string().optional(),
+  platform: z.string().optional(),
+});
+
+const researchThemeSchema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  sentiment,
+  evidenceStrength: signalStrength,
+  representativeQuotes: z.array(quoteSchema).default([]),
+  audienceSegments: z.array(z.string()).default([]),
+  implications: z.array(z.string()).default([]),
+  sourceLabels: z.array(z.string()).default([]),
+});
+
+const opportunitySchema = z.object({
+  title: z.string(),
+  userNeed: z.string(),
+  whyItMatters: z.string(),
+  suggestedAction: z.string(),
+  evidenceStrength: signalStrength,
+});
+
+const riskSchema = z.object({
+  title: z.string(),
+  whyItMatters: z.string(),
+  mitigation: z.string(),
+});
+
+export const socialListeningResearchReportResultSchema = z.object({
+  reportStatus: z.enum(["partial", "final"]).default("final"),
+  completedSections: z.array(z.string()).default([]),
+  inProgressSection: z.string().optional(),
+  reportTitle: z.string().default("Social listening research report"),
+  executiveSummary: z.string().default(""),
+  researchScope: z
+    .object({
+      question: z.string().default(""),
+      platforms: z.array(z.string()).default([]),
+      market: z.string().optional(),
+      audience: z.string().optional(),
+      searchQueries: z.array(z.string()).default([]),
+    })
+    .default({ question: "", platforms: [], searchQueries: [] }),
+  themes: z.array(researchThemeSchema).default([]),
+  audienceSegments: z.array(z.string()).default([]),
+  opportunities: z.array(opportunitySchema).default([]),
+  risks: z.array(riskSchema).default([]),
+  questionsToValidate: z.array(z.string()).default([]),
+  missingEvidence: z.array(z.string()).default([]),
+  sources: z.array(sourceSchema).default([]),
+  confidence,
+  boundaryNote: z.string().default(""),
+  promptVersion: z.string().default(SOCIAL_LISTENING_RESEARCH_REPORT_PROMPT_VERSION),
+  generatedAt: z.string().optional(),
+});
+
+export type SocialListeningResearchReportResult = z.infer<
+  typeof socialListeningResearchReportResultSchema
+>;
+export type SocialListeningSignalStrength = z.infer<typeof signalStrength>;
+export type SocialListeningSentiment = z.infer<typeof sentiment>;