@cms.ai/brand_brain 0.0.1

package/src/types.ts

@@ -0,0 +1,316 @@
+// 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.
+
+/** AG-UI protocol frame types written by the guide SSE stream. */
+export const SSEMessageType = {
+  RunStarted: "RUN_STARTED",
+  RunFinished: "RUN_FINISHED",
+  RunError: "RUN_ERROR",
+  TextMessageStart: "TEXT_MESSAGE_START",
+  TextMessageContent: "TEXT_MESSAGE_CONTENT",
+  TextMessageEnd: "TEXT_MESSAGE_END",
+  Custom: "CUSTOM",
+} as const;
+export type SSEMessageTypeName = (typeof SSEMessageType)[keyof typeof SSEMessageType];
+
+/** The `name` on `CUSTOM` guide events (skill payloads). */
+export const GuideEvent = {
+  SkillStart: "skill_start",
+  SkillContent: "skill_content",
+  SkillDocuments: "skill_documents",
+  SkillRecommendations: "skill_recommendations",
+  SkillCTAs: "skill_ctas",
+  SkillDiagnoseHeader: "skill_diagnose_header",
+  SkillDiagnoseQuestion: "skill_diagnose_question",
+  SkillPlaylistItems: "skill_playlist_items",
+  SkillPlaylistHeader: "skill_playlist_header",
+  SkillPlaylistRationale: "skill_playlist_rationale",
+  SkillHowToOutline: "skill_howto_outline",
+  SkillHowToSteps: "skill_howto_steps",
+  SkillBusinessCaseChooser: "skill_businesscase_chooser",
+  SkillBusinessCaseDelta: "skill_businesscase_delta",
+  SkillSolutionDesignHeader: "skill_solutiondesign_header",
+  SkillSolutionDesignDiagram: "skill_solutiondesign_diagram",
+  SkillEnd: "skill_end",
+  SkillError: "skill_error",
+  SkillGate: "skill_gate",
+  InputSuggestions: "input_suggestions",
+} as const;
+export type GuideEventName = (typeof GuideEvent)[keyof typeof GuideEvent];
+
+/** The guide skill types. `answer` is always on; the rest are enabled per-guide. */
+export const SkillResponseType = {
+  Answer: "answer",
+  HowTo: "howto",
+  Diagnose: "diagnose",
+  Recommend: "recommend",
+  Playlist: "playlist",
+  BusinessCase: "businesscase",
+  SolutionDesign: "solutiondesign",
+} as const;
+export type SkillResponseTypeType = (typeof SkillResponseType)[keyof typeof SkillResponseType];
+
+/** Consent tiers. `essential` is always granted server-side. */
+export const ConsentTier = {
+  Essential: "essential",
+  Functional: "functional",
+  Analytical: "analytical",
+} as const;
+export type ConsentTierName = (typeof ConsentTier)[keyof typeof ConsentTier];
+
+/** Analytics events fired by the SDK bootstrap. */
+export const EmbedTrackingEvent = {
+  EmbedLoaded: "embed_loaded",
+  EmbedPageView: "embed_page_view",
+  EmbedTriggerClicked: "embed_trigger_clicked",
+  EmbedSideTabClicked: "embed_side_tab_clicked",
+  EmbedSideTabDismissed: "embed_side_tab_dismissed",
+} as const;
+export type EmbedTrackingEventName = (typeof EmbedTrackingEvent)[keyof typeof EmbedTrackingEvent];
+
+/**
+ * The `eventType` passed to {@link GuideClient.track}. Any server-recognized
+ * event string is accepted — use an {@link EmbedTrackingEvent} member for the
+ * common cases.
+ */
+export type TrackEventType = string;
+
+/** Consent tiers a visitor can grant. `essential` is always granted server-side. */
+export interface ConsentLevels {
+  functional?: boolean;
+  analytical?: boolean;
+}
+
+export interface ConsentFlags {
+  essential: boolean;
+  functional: boolean;
+  analytical: boolean;
+}
+
+/** Per-guide UI copy overrides. */
+export interface GuideCustomization {
+  welcomeMessage?: string;
+  chatInputPlaceholders?: string[];
+  suggestionsTitle?: string;
+  helpTitle?: string;
+  pickUpWhereYouLeftOff?: string;
+  showGuideName?: boolean;
+  sideTabButtonText?: string;
+  pdfDisclaimerLine1?: string;
+  pdfDisclaimerLine2?: string;
+  pdfDownloadDescription?: string;
+}
+
+/** Lightweight knowledge-graph snapshot for page-load visualization. */
+export interface GuideGraphSnapshot {
+  nodes: Array<{ id: string; name: string; type: string; tier: number }>;
+  edges: Array<{ from: string; to: string; relationship: string; strength: number }>;
+}
+
+/**
+ * Resolved guide metadata returned by `guides.resolve`. `theme` / `skillIconStyle`
+ * are left as `unknown` in v1 — read them defensively or narrow as needed.
+ */
+export interface ResolvedGuide {
+  id: string;
+  name: string;
+  slug: string;
+  brandKitId: string | null;
+  magicLinkFormId: string | null;
+  accountId: string;
+  companyName: string;
+  gdprEnabled: boolean;
+  advancedSettings: { gatePdfDownload: boolean };
+  theme: unknown;
+  skillIconStyle: unknown;
+  faviconUrl: string | null;
+  logoUrl: string | null;
+  heroImageUrl: string | null;
+  customization: GuideCustomization | null;
+  graphSnapshot: GuideGraphSnapshot | null;
+}
+
+/** A conversation record. */
+export interface Conversation {
+  id: string;
+  accountId: string;
+  guideId: string;
+  visitorId: string;
+  sessionId: string;
+  title: string | null;
+  createdAt: Date;
+  deletedAt: Date | null;
+}
+
+/** A persisted conversation message. */
+export interface ConversationMessage {
+  id: string;
+  accountId: string;
+  conversationId: string;
+  role: "human" | "assistant";
+  content: string | null;
+  isSynthetic: boolean;
+  createdAt: Date;
+  deletedAt: Date | null;
+}
+
+/** A conversation plus a page of its messages. */
+export interface ConversationWithMessages {
+  conversation: Conversation;
+  messages: ConversationMessage[];
+}
+
+/** A persisted skill deliverable. `data` shape varies by `type`. */
+export interface SkillInstance {
+  id: string;
+  skillOutputId: string;
+  accountId: string;
+  conversationId: string;
+  type: SkillResponseTypeType;
+  visitorId: string;
+  sessionId: string;
+  title: string | null;
+  data: Record<string, unknown>;
+  surfacedCta: unknown;
+  sharedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt: Date | null;
+}
+
+/** A skill instance as returned in history lists (no `data`/`surfacedCta`). */
+export interface SkillHistoryInstance {
+  id: string;
+  skillOutputId: string;
+  accountId: string;
+  conversationId: string;
+  type: SkillResponseTypeType;
+  visitorId: string;
+  sessionId: string;
+  title: string | null;
+  sharedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt: Date | null;
+  stepsCompleted: number | null;
+  totalSteps: number | null;
+}
+
+/** Skill history grouped by conversation. */
+export interface SkillHistoryGroup {
+  conversationId: string;
+  conversationTitle: string | null;
+  latestActivityAt: Date;
+  instances: SkillHistoryInstance[];
+}
+
+export interface UpdateSkillInstanceResult {
+  id: string;
+  data: Record<string, unknown>;
+  updatedAt: Date;
+}
+
+export interface SelectDraftResult {
+  skillInstanceId: string | null;
+}
+
+export interface MarkSharedResult {
+  sharedAt: Date;
+}
+
+export interface ImportSharedResult {
+  skillInstanceId: string;
+  type: SkillResponseTypeType;
+  conversationId: string;
+}
+
+/** The current visitor's tracking + consent + email status. */
+export interface VisitorStatus {
+  visitorId: string;
+  isTracked: boolean;
+  consent: { functional: boolean; analytical: boolean };
+  email: string | null;
+  verified: boolean;
+}
+
+/** Result of an email-gate submission. */
+export interface SubmitGateResult {
+  success: boolean;
+  needsVerification: boolean;
+}
+
+/** Optional lead-capture fields beyond the ones the SDK fills automatically. */
+export interface SubmitGateOptions {
+  redirectUrl?: string;
+  skill?: string;
+  prompt?: string;
+  skillInstanceId?: string;
+  hostUrl?: string;
+  requireVerification?: boolean;
+  downloadIntent?: boolean;
+  shareIntent?: boolean;
+}
+
+export interface InitGuideConfig {
+  /**
+   * Branded host origin the SDK talks to, e.g. "https://guide.acme.com". Must be
+   * on the customer's own root domain so the visitor cookies stay same-site.
+   * `/api/v3` is appended automatically.
+   */
+  baseUrl: string;
+  /** 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.
+   */
+  domain?: string;
+  /**
+   * Consent handling on init:
+   * - `"auto"` (default): grant all tiers when the guide has GDPR disabled; wait
+   *   for an explicit `setConsent()` when it is enabled.
+   * - explicit levels: submit these immediately.
+   * - `false`: submit nothing; call `setConsent()` yourself.
+   */
+  consent?: "auto" | ConsentLevels | false;
+  /** Fire an initial `embed_loaded` + page-view event on init. Default `true`. */
+  trackLoad?: boolean;
+  /**
+   * Custom fetch implementation (SSR/testing). Defaults to `globalThis.fetch`.
+   * `credentials: "include"` is always applied so visitor cookies ride along.
+   */
+  fetch?: typeof globalThis.fetch;
+}
+
+/** A message in the SDK's in-memory conversation history. */
+export interface ChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface AskOptions {
+  /** Force a specific skill, bypassing server-side LLM routing. */
+  forcedSkill?: SkillResponseTypeType;
+  /** Abort the in-flight stream. */
+  signal?: AbortSignal;
+}
+
+/**
+ * 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`.
+ */
+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> }
+  | { type: "gate"; skill: SkillResponseTypeType; prompt?: string; skillInstanceId?: string }
+  | { type: "error"; message: string; code?: string }
+  | { type: "run-finished"; finishReason?: string };