@cms.ai/brand_brain 0.0.1 → 0.1.0

package/src/types.ts

@@ -1,9 +1,11 @@
 // This package is deliberately self-contained: it imports NO types from
 // @navless/types. That package is a barrel (`export *` over dozens of modules),
 // so importing any symbol drags the whole surface into the bundled .d.ts and the
-// dts bundler chokes on it. The wire-protocol enums below are stable contracts,
-// hand-mirrored here so the published package has zero @navless/* runtime deps
-// and a self-contained declaration file.
+// dts bundler chokes on it. The wire-protocol enums and payload interfaces below
+// are stable contracts, hand-mirrored here so the published package has zero
+// @navless/* runtime deps and a self-contained declaration file. Authoritative
+// server sources: `guide-runtime/sse-adapter.ts` (wire frames) and
+// `@navless/types/guide.types.ts` (payload shapes).
 
 /** AG-UI protocol frame types written by the guide SSE stream. */
 export const SSEMessageType = {
@@ -17,7 +19,11 @@ export const SSEMessageType = {
 } as const;
 export type SSEMessageTypeName = (typeof SSEMessageType)[keyof typeof SSEMessageType];
 
-/** The `name` on `CUSTOM` guide events (skill payloads). */
+/**
+ * The `name` on `CUSTOM` guide events (skill payloads). `SkillGate` and
+ * `SkillError` never surface as `skill` stream events — the SDK re-maps them to
+ * the dedicated `gate` / `error` {@link GuideStreamEvent} variants.
+ */
 export const GuideEvent = {
   SkillStart: "skill_start",
   SkillContent: "skill_content",
@@ -38,7 +44,6 @@ export const GuideEvent = {
   SkillEnd: "skill_end",
   SkillError: "skill_error",
   SkillGate: "skill_gate",
-  InputSuggestions: "input_suggestions",
 } as const;
 export type GuideEventName = (typeof GuideEvent)[keyof typeof GuideEvent];
 
@@ -111,10 +116,77 @@ export interface GuideGraphSnapshot {
   edges: Array<{ from: string; to: string; relationship: string; strength: number }>;
 }
 
+// ============================================================================
+// Brand theme
+// ============================================================================
+
+/**
+ * The guide's brand theme — shadcn-style design tokens as CSS color strings
+ * (hex or `oklch(...)`). Every property is optional: absent tokens mean "keep
+ * your default". Map them onto your CSS variables / Tailwind theme so the
+ * guide UI matches the brand:
+ *
+ * ```css
+ * :root {
+ *   --primary: <theme.primary>;
+ *   --background: <theme.background>;
+ * }
+ * ```
+ */
+export interface BrandKitTheme {
+  /** Main brand color (buttons, focus rings) */
+  primary?: string;
+  /** Text on primary backgrounds */
+  primaryForeground?: string;
+  /** Secondary surface color */
+  secondary?: string;
+  /** Text on secondary surfaces */
+  secondaryForeground?: string;
+  /** Main page background */
+  background?: string;
+  /** Default body text */
+  foreground?: string;
+  /** Muted areas, borders, inputs */
+  muted?: string;
+  /** Muted/secondary text */
+  mutedForeground?: string;
+  /** Border color */
+  border?: string;
+  /** Input border color */
+  input?: string;
+  /** Focus ring color */
+  ring?: string;
+}
+
+/** How a brand kit colors the guide's skill icons. */
+export const SkillIconColorMode = {
+  /** Keep the built-in per-skill colors. */
+  Default: "default",
+  /** Apply a single brand color to every skill icon. */
+  Mono: "mono",
+  /** Pick a color per skill; skills left unset fall back to the default. */
+  PerSkill: "per_skill",
+} as const;
+export type SkillIconColorModeType = (typeof SkillIconColorMode)[keyof typeof SkillIconColorMode];
+
 /**
- * Resolved guide metadata returned by `guides.resolve`. `theme` / `skillIconStyle`
- * are left as `unknown` in v1 — read them defensively or narrow as needed.
+ * Per-brand-kit skill icon color customization, discriminated on `mode`.
+ * Colors are CSS color strings (same format as {@link BrandKitTheme}).
  */
+export type SkillIconStyle =
+  | { mode: typeof SkillIconColorMode.Default }
+  | {
+      mode: typeof SkillIconColorMode.Mono;
+      /** Single color applied to every skill icon. */
+      monoColor: string;
+    }
+  | {
+      mode: typeof SkillIconColorMode.PerSkill;
+      /** Color per skill; missing keys fall back to the default. */
+      colors: Partial<Record<SkillResponseTypeType, string>>;
+    };
+
+/** Resolved guide metadata returned by `guides.resolve`. */
 export interface ResolvedGuide {
   id: string;
   name: string;
@@ -125,8 +197,9 @@ export interface ResolvedGuide {
   companyName: string;
   gdprEnabled: boolean;
   advancedSettings: { gatePdfDownload: boolean };
-  theme: unknown;
-  skillIconStyle: unknown;
+  /** Brand design tokens — apply to your UI so the guide matches the brand. */
+  theme: BrandKitTheme | null;
+  skillIconStyle: SkillIconStyle | null;
   faviconUrl: string | null;
   logoUrl: string | null;
   heroImageUrl: string | null;
@@ -164,7 +237,12 @@ export interface ConversationWithMessages {
   messages: ConversationMessage[];
 }
 
-/** A persisted skill deliverable. `data` shape varies by `type`. */
+/**
+ * A persisted skill deliverable. `data` shape varies by `type` — it is the
+ * skill's completed output (e.g. for `howto` a `{ title, steps: HowToStep[] }`
+ * record); the streamed payload interfaces in this file describe the same
+ * building blocks.
+ */
 export interface SkillInstance {
   id: string;
   skillOutputId: string;
@@ -265,8 +343,10 @@ export interface InitGuideConfig {
   /** Guide slug to resolve (e.g. "default"). */
   slug: string;
   /**
-   * Host domain used for account resolution + attribution. Defaults to
-   * `window.location.hostname`. Required when running without a browser window.
+   * Optional override for the host used in account resolution + attribution.
+   * Defaults to the `baseUrl` hostname (lowercased, `www.`/port stripped), which
+   * is the registered account domain. Only set this if resolution must key off a
+   * different registered domain than the one requests are sent to.
    */
   domain?: string;
   /**
@@ -300,17 +380,424 @@ export interface AskOptions {
   signal?: AbortSignal;
 }
 
+// ============================================================================
+// Skill payload building blocks (mirrored from @navless/types/guide.types.ts)
+// ============================================================================
+
+/** Kind of content a document/playlist item points at. */
+export const ContentType = {
+  PDF: "pdf",
+  DOCX: "docx",
+  PPTX: "pptx",
+  Image: "image",
+  VideoNative: "video_native",
+  VideoYouTube: "video_youtube",
+  VideoWistia: "video_wistia",
+  Document: "document",
+  URL: "url",
+  Text: "text",
+  Markdown: "markdown",
+} as const;
+export type ContentTypeName = (typeof ContentType)[keyof typeof ContentType];
+
+/**
+ * Document reference streamed with a reply — the sources behind the answer.
+ * Render as source cards/citations: title, optional link, optional thumbnail.
+ */
+export interface GuideDocument {
+  id: string;
+  title: string;
+  tag?: string;
+  /** Lucide icon name. */
+  icon?: string;
+  url?: string;
+  contentType?: ContentTypeName;
+  body?: string;
+  thumbnailUrl?: string;
+  /** 1-based citation number matching the [N] references in the reply text. Undefined if the document was not part of the reply context. */
+  citationIndex?: number;
+}
+
+/** Confidence level attached to a content recommendation. */
+export const Confidence = {
+  High: "high",
+  Medium: "medium",
+  Low: "low",
+} as const;
+export type ConfidenceName = (typeof Confidence)[keyof typeof Confidence];
+
+/**
+ * Follow-up recommendation to invoke a skill — render as a pill button that
+ * calls `ask(prompt, { forcedSkill: skill })`.
+ */
+export interface SkillRecommendation {
+  id: string;
+  skill: SkillResponseTypeType;
+  label: string;
+  prompt: string;
+}
+
+/**
+ * A content recommendation generated by the recommend skill — render as a card
+ * whose click calls `ask(prompt, { forcedSkill: targetSkill })`.
+ */
+export interface ContentRecommendation {
+  id: string;
+  targetSkill: Exclude<SkillResponseTypeType, "recommend">;
+  title: string;
+  rationale: string;
+  prompt: string;
+  confidence: ConfidenceName;
+}
+
+/** The render kind of a surfaced call-to-action. */
+export const SkillCtaKind = {
+  Url: "url",
+  Form: "form",
+  Product: "product",
+  Scheduler: "scheduler",
+} as const;
+export type SkillCtaKindName = (typeof SkillCtaKind)[keyof typeof SkillCtaKind];
+
+/** Where a surfaced CTA renders. One slot today: below the skill response. */
+export const CtaPlacement = {
+  ResponseFooter: "response_footer",
+} as const;
+export type CtaPlacementName = (typeof CtaPlacement)[keyof typeof CtaPlacement];
+
+/** Which scheduler embed a scheduler CTA loads. */
+export const SchedulerProvider = {
+  HubSpot: "hubspot",
+  Calendly: "calendly",
+} as const;
+export type SchedulerProviderName = (typeof SchedulerProvider)[keyof typeof SchedulerProvider];
+
+/**
+ * A call-to-action surfaced for a turn, discriminated on `kind`:
+ * - `url`:       external link — render a button that opens `href`.
+ * - `form`:      in-guide form — render a button/banner for the form `formId`.
+ * - `product`:   product recommendation — render a link/card to `href`.
+ * - `scheduler`: meeting embed — render a button that opens `url` in the
+ *                provider's scheduling widget (or a new tab).
+ *
+ * Only render the first CTA in the list; the wire carries a list for forward
+ * compatibility. `ctaInstanceId` (when present) should be echoed on CTA
+ * analytics events so impressions and clicks join up.
+ */
+export type SkillCTA =
+  | {
+      kind: typeof SkillCtaKind.Url;
+      placement: CtaPlacementName;
+      ctaId: string | null;
+      label: string;
+      href: string;
+      /** Custom banner heading; absent → use a default like "Recommended next step". */
+      bannerText?: string;
+      /** Lucide icon name; absent → a default lightbulb. */
+      bannerIcon?: string;
+      ctaInstanceId?: string;
+    }
+  | {
+      kind: typeof SkillCtaKind.Form;
+      placement: CtaPlacementName;
+      ctaId: string;
+      label: string;
+      formId: string;
+      bannerText?: string;
+      bannerIcon?: string;
+      ctaInstanceId?: string;
+    }
+  | {
+      kind: typeof SkillCtaKind.Product;
+      placement: CtaPlacementName;
+      productId: string;
+      label: string;
+      href: string;
+      ctaInstanceId?: string;
+    }
+  | {
+      kind: typeof SkillCtaKind.Scheduler;
+      placement: CtaPlacementName;
+      ctaId: string;
+      label: string;
+      provider: SchedulerProviderName;
+      /** The meeting/scheduling link the embed loads. */
+      url: string;
+      bannerText?: string;
+      bannerIcon?: string;
+      ctaInstanceId?: string;
+    };
+
+/** Diagnose skill mode. */
+export const DiagnoseSubtype = {
+  /** A scored self-assessment rendered with results at the end. */
+  Standalone: "standalone",
+  /** Questions gather context for a follow-up skill (see `followUpSkill`). */
+  ContextGathering: "context_gathering",
+} as const;
+export type DiagnoseSubtypeName = (typeof DiagnoseSubtype)[keyof typeof DiagnoseSubtype];
+
+/** Answer option labels for diagnose questions. */
+export const DiagnoseOptionLabel = {
+  A: "A",
+  B: "B",
+  C: "C",
+  D: "D",
+} as const;
+export type DiagnoseOptionLabelName = (typeof DiagnoseOptionLabel)[keyof typeof DiagnoseOptionLabel];
+
+/** Header for a diagnostic assessment — render as the assessment intro. */
+export interface DiagnosticHeader {
+  targetTopic: string;
+  subtitle: string;
+  /** Total number of questions the assessment will stream. */
+  questionCount: number;
+  subtype?: DiagnoseSubtypeName;
+  /** For context_gathering mode — the skill to invoke after the user submits answers. */
+  followUpSkill?: string;
+  /** For context_gathering mode — the prompt to send to `followUpSkill` afterwards. */
+  followUpPrompt?: string;
+}
+
+/**
+ * A self-assessment question (no correct answer). Render the options as a
+ * single-choice list; `score` supports a results chart in standalone mode.
+ */
+export interface DiagnosticQuestion {
+  id: string;
+  /** Short category name, usable as a results-chart axis label. */
+  category: string;
+  questionText: string;
+  options: Array<{ label: DiagnoseOptionLabelName; text: string; score?: number }>;
+  prerequisiteConceptId: string | null;
+  prerequisiteConceptName: string | null;
+}
+
+/** A step title in a how-to outline (details stream later as {@link HowToStep}). */
+export interface HowToStepOutline {
+  id: string;
+  title: string;
+}
+
+/** How-to outline — render immediately as a skeleton; steps fill in after. */
+export interface HowToOutline {
+  title: string;
+  steps: HowToStepOutline[];
+}
+
+/** Content reference attached to a how-to step — render as a source card. */
+export interface HowToStepContent {
+  contentId: string;
+  title: string;
+  url: string | null;
+  contentType: ContentTypeName | null;
+  /** The matching excerpt that demonstrates relevance. */
+  excerpt: string;
+  thumbnailUrl?: string;
+}
+
+/** A fully detailed how-to step — replaces the outline entry with the same `id`. */
+export interface HowToStep {
+  id: string;
+  title: string;
+  description: string;
+  content: HowToStepContent | null;
+  /** Lucide icon name. */
+  icon?: string;
+}
+
+/** Header for a playlist — render as the playlist title/description. */
+export interface PlaylistHeader {
+  title: string;
+  description: string;
+}
+
+/** A single item in a curated playlist — render as a content card. */
+export interface PlaylistItem {
+  id: string;
+  title: string;
+  description: string | null;
+  body?: string | null;
+  contentType: ContentTypeName;
+  url: string | null;
+  thumbnailUrl?: string;
+  /** Why this item is included — streams in later via `skill_playlist_rationale`. */
+  rationale?: string;
+}
+
+/** Business case format sub-types. */
+export const BusinessCaseSubType = {
+  RoiAnalysis: "roi-analysis",
+  StakeholderBrief: "stakeholder-brief",
+  VendorComparison: "vendor-comparison",
+} as const;
+export type BusinessCaseSubTypeName = (typeof BusinessCaseSubType)[keyof typeof BusinessCaseSubType];
+
+/** Format option in the business case chooser — render as a selectable card. */
+export interface BusinessCaseFormatOption {
+  subType: BusinessCaseSubTypeName;
+  label: string;
+  description: string;
+  /** Lucide icon name. */
+  icon: string;
+}
+
+/** Reference to a pre-generated business case draft, keyed by sub-type. */
+export interface BusinessCaseDraftRef {
+  draftId: string;
+  skillInstanceId: string;
+}
+
+/** Node types in a solution design diagram. */
+export const SolutionDesignNodeType = {
+  Process: "process",
+  Decision: "decision",
+  Datastore: "datastore",
+  External: "external",
+  Trigger: "trigger",
+  Start: "start",
+  End: "end",
+} as const;
+export type SolutionDesignNodeTypeName = (typeof SolutionDesignNodeType)[keyof typeof SolutionDesignNodeType];
+
+/** A node in a solution design diagram — render as a flowchart node. */
+export interface SolutionDesignNode {
+  id: string;
+  label: string;
+  description: string;
+  nodeType: SolutionDesignNodeTypeName;
+  /** Lucide icon name. */
+  icon: string;
+}
+
+/** A directed edge between two solution design nodes (by node `id`). */
+export interface SolutionDesignEdge {
+  id: string;
+  source: string;
+  target: string;
+  label?: string;
+}
+
+/** Header for a solution design — render as the diagram title/summary. */
+export interface SolutionDesignHeader {
+  title: string;
+  summary: string;
+}
+
+/** Suggested retry attached to a recoverable skill error. */
+export interface SkillErrorRetryHint {
+  /** Re-ask with this prompt… */
+  prompt: string;
+  /** …optionally forcing this skill. */
+  forcedSkill?: SkillResponseTypeType;
+}
+
+// ============================================================================
+// The `ask()` event stream
+// ============================================================================
+
+/**
+ * A structured skill event, discriminated on `name`. Every turn runs one skill
+ * (plain answers are the `answer` skill): `skill_start` announces which,
+ * payload events stream the deliverable, and `skill_end` closes it. Use
+ * {@link reduceSkillEvent} to fold these into renderable state instead of
+ * handling each variant by hand.
+ */
+export type GuideSkillEvent =
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillStart;
+      /** Which skill this turn runs, and the assistant message it belongs to. */
+      value: { skill: SkillResponseTypeType; messageId: string; diagnoseSubtype?: DiagnoseSubtypeName; followUpSkill?: string };
+    }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillContent;
+      /** Markdown token chunk of the skill's long-form body (business case drafts, etc.). */
+      value: { delta: string };
+    }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillDocuments;
+      /** Source documents behind the reply — render as citation/source cards. */
+      value: { documents: GuideDocument[] };
+    }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillRecommendations;
+      /**
+       * Either the recommend skill's content cards ({@link ContentRecommendation},
+       * has `targetSkill`) or post-answer follow-up pills ({@link SkillRecommendation},
+       * has `skill`). Discriminate by which of those keys is present.
+       */
+      value: { recommendations: ContentRecommendation[] | SkillRecommendation[] };
+    }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillCTAs;
+      /** Calls-to-action for this turn — render the first below the response. */
+      value: { ctas: SkillCTA[] };
+    }
+  | { type: "skill"; name: typeof GuideEvent.SkillDiagnoseHeader; value: { header: DiagnosticHeader } }
+  | { type: "skill"; name: typeof GuideEvent.SkillDiagnoseQuestion; value: { question: DiagnosticQuestion } }
+  | { type: "skill"; name: typeof GuideEvent.SkillPlaylistItems; value: { items: PlaylistItem[] } }
+  | { type: "skill"; name: typeof GuideEvent.SkillPlaylistHeader; value: { header: PlaylistHeader } }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillPlaylistRationale;
+      /** Late-streamed rationale for the playlist item with this `itemId`. */
+      value: { itemId: string; rationale: string };
+    }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillHowToOutline;
+      /** Render the outline immediately; detailed steps stream in `skill_howto_steps`. */
+      value: { outline: HowToOutline; skillInstanceId?: string };
+    }
+  | { type: "skill"; name: typeof GuideEvent.SkillHowToSteps; value: { steps: HowToStep[] } }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillBusinessCaseChooser;
+      /** Format options to choose from; `drafts` maps subType → pre-generated draft. */
+      value: { formats: BusinessCaseFormatOption[]; drafts: Record<string, BusinessCaseDraftRef> };
+    }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillBusinessCaseDelta;
+      /** Markdown chunk of the draft for one business case format. */
+      value: { subType: BusinessCaseSubTypeName; delta: string };
+    }
+  | { type: "skill"; name: typeof GuideEvent.SkillSolutionDesignHeader; value: { header: SolutionDesignHeader } }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillSolutionDesignDiagram;
+      /** Flowchart nodes + edges — render with any diagram/graph component. */
+      value: { nodes: SolutionDesignNode[]; edges: SolutionDesignEdge[] };
+    }
+  | {
+      type: "skill";
+      name: typeof GuideEvent.SkillEnd;
+      /** `skillInstanceId` is the persisted deliverable's id (for `skills.get`/`update`). */
+      value: { skillInstanceId?: string; skillResponseId?: string };
+    };
+
 /**
- * A single event yielded by {@link GuideClient.ask}. The common case is `text`
- * (the streamed chat reply); `skill` carries every structured skill payload,
- * discriminated by its {@link GuideEventName} `name`.
+ * A single event yielded by {@link GuideClient.ask}.
+ *
+ * - `text` streams the chat reply; `skill` carries the structured deliverable
+ *   (see {@link GuideSkillEvent}).
+ * - `gate` means the guide wants an email before continuing — collect one,
+ *   call `submitGate(email)`, then re-send the message.
+ * - `skill-unknown` is a forward-compatibility escape hatch: a structured
+ *   event this SDK version doesn't know. Safe to ignore.
  */
 export type GuideStreamEvent =
   | { type: "run-started"; runId: string }
   | { type: "message-start"; messageId: string; role: string }
   | { type: "text"; messageId: string; delta: string }
   | { type: "message-end"; messageId: string }
-  | { type: "skill"; name: GuideEventName; value: Record<string, unknown> }
+  | GuideSkillEvent
+  | { type: "skill-unknown"; name: string; value: Record<string, unknown> }
   | { type: "gate"; skill: SkillResponseTypeType; prompt?: string; skillInstanceId?: string }
-  | { type: "error"; message: string; code?: string }
+  | { type: "error"; message: string; code?: string; retryable?: boolean; retryHint?: SkillErrorRetryHint }
   | { type: "run-finished"; finishReason?: string };