@cms.ai/brand_brain 0.0.1

package/dist/react/index.d.mts

@@ -0,0 +1,387 @@
+//#region src/types.d.ts
+/** The `name` on `CUSTOM` guide events (skill payloads). */
+declare const GuideEvent: {
+  readonly SkillStart: "skill_start";
+  readonly SkillContent: "skill_content";
+  readonly SkillDocuments: "skill_documents";
+  readonly SkillRecommendations: "skill_recommendations";
+  readonly SkillCTAs: "skill_ctas";
+  readonly SkillDiagnoseHeader: "skill_diagnose_header";
+  readonly SkillDiagnoseQuestion: "skill_diagnose_question";
+  readonly SkillPlaylistItems: "skill_playlist_items";
+  readonly SkillPlaylistHeader: "skill_playlist_header";
+  readonly SkillPlaylistRationale: "skill_playlist_rationale";
+  readonly SkillHowToOutline: "skill_howto_outline";
+  readonly SkillHowToSteps: "skill_howto_steps";
+  readonly SkillBusinessCaseChooser: "skill_businesscase_chooser";
+  readonly SkillBusinessCaseDelta: "skill_businesscase_delta";
+  readonly SkillSolutionDesignHeader: "skill_solutiondesign_header";
+  readonly SkillSolutionDesignDiagram: "skill_solutiondesign_diagram";
+  readonly SkillEnd: "skill_end";
+  readonly SkillError: "skill_error";
+  readonly SkillGate: "skill_gate";
+  readonly InputSuggestions: "input_suggestions";
+};
+type GuideEventName = (typeof GuideEvent)[keyof typeof GuideEvent];
+/** The guide skill types. `answer` is always on; the rest are enabled per-guide. */
+declare const SkillResponseType: {
+  readonly Answer: "answer";
+  readonly HowTo: "howto";
+  readonly Diagnose: "diagnose";
+  readonly Recommend: "recommend";
+  readonly Playlist: "playlist";
+  readonly BusinessCase: "businesscase";
+  readonly SolutionDesign: "solutiondesign";
+};
+type SkillResponseTypeType = (typeof SkillResponseType)[keyof typeof SkillResponseType];
+/**
+ * The `eventType` passed to {@link GuideClient.track}. Any server-recognized
+ * event string is accepted — use an {@link EmbedTrackingEvent} member for the
+ * common cases.
+ */
+type TrackEventType = string;
+/** Consent tiers a visitor can grant. `essential` is always granted server-side. */
+interface ConsentLevels {
+  functional?: boolean;
+  analytical?: boolean;
+}
+/** Per-guide UI copy overrides. */
+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. */
+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.
+ */
+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. */
+interface Conversation {
+  id: string;
+  accountId: string;
+  guideId: string;
+  visitorId: string;
+  sessionId: string;
+  title: string | null;
+  createdAt: Date;
+  deletedAt: Date | null;
+}
+/** A persisted conversation message. */
+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. */
+interface ConversationWithMessages {
+  conversation: Conversation;
+  messages: ConversationMessage[];
+}
+/** A persisted skill deliverable. `data` shape varies by `type`. */
+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`). */
+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. */
+interface SkillHistoryGroup {
+  conversationId: string;
+  conversationTitle: string | null;
+  latestActivityAt: Date;
+  instances: SkillHistoryInstance[];
+}
+interface UpdateSkillInstanceResult {
+  id: string;
+  data: Record<string, unknown>;
+  updatedAt: Date;
+}
+interface SelectDraftResult {
+  skillInstanceId: string | null;
+}
+interface MarkSharedResult {
+  sharedAt: Date;
+}
+interface ImportSharedResult {
+  skillInstanceId: string;
+  type: SkillResponseTypeType;
+  conversationId: string;
+}
+/** The current visitor's tracking + consent + email status. */
+interface VisitorStatus {
+  visitorId: string;
+  isTracked: boolean;
+  consent: {
+    functional: boolean;
+    analytical: boolean;
+  };
+  email: string | null;
+  verified: boolean;
+}
+/** Result of an email-gate submission. */
+interface SubmitGateResult {
+  success: boolean;
+  needsVerification: boolean;
+}
+/** Optional lead-capture fields beyond the ones the SDK fills automatically. */
+interface SubmitGateOptions {
+  redirectUrl?: string;
+  skill?: string;
+  prompt?: string;
+  skillInstanceId?: string;
+  hostUrl?: string;
+  requireVerification?: boolean;
+  downloadIntent?: boolean;
+  shareIntent?: boolean;
+}
+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. */
+interface ChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+}
+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`.
+ */
+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;
+};
+//#endregion
+//#region src/GuideClient.d.ts
+interface ConversationsApi {
+  getOrCreate(): Promise<Conversation>;
+  list(): Promise<Conversation[]>;
+  get(conversationId: string, options?: {
+    cursor?: string;
+    limit?: number;
+  }): Promise<ConversationWithMessages>;
+  delete(conversationId: string): Promise<Conversation>;
+}
+interface SkillsApi {
+  listHistory(): Promise<SkillHistoryGroup[]>;
+  get(skillInstanceId: string): Promise<SkillInstance>;
+  update(skillInstanceId: string, data: Record<string, unknown>): Promise<UpdateSkillInstanceResult>;
+  selectDraft(draftId: string): Promise<SelectDraftResult>;
+  markShared(skillInstanceId: string): Promise<MarkSharedResult>;
+  importShared(sourceSkillInstanceId: string): Promise<ImportSharedResult>;
+}
+/**
+ * The client returned by {@link initGuide}. Holds the resolved guide, the
+ * credentialed live API client, and the in-memory conversation history. Every
+ * method reuses an existing public endpoint — the SDK adds no server surface.
+ */
+declare class GuideClient {
+  #private;
+  /** Resolved guide metadata (ids, theme, customization). */
+  readonly guide: ResolvedGuide;
+  private readonly apiBaseUrl;
+  private readonly domain;
+  private readonly fetchImpl;
+  private readonly history;
+  private constructor();
+  static init(config: InitGuideConfig): Promise<GuideClient>;
+  /** The account this guide belongs to (used implicitly by history calls). */
+  get accountId(): string;
+  /** The in-memory conversation history accumulated by {@link ask}. */
+  get messages(): readonly ChatMessage[];
+  /**
+   * Send a message and stream the reply. Yields text deltas for the chat bubble
+   * plus every structured skill event; the full 7-skill surface flows through
+   * one stream. The user + assistant turns are appended to {@link messages}.
+   */
+  ask(message: string, options?: AskOptions): AsyncGenerator<GuideStreamEvent>;
+  /** Clear the in-memory conversation history (server-side history is unaffected). */
+  reset(): void;
+  /** Grant consent tiers. `essential` is always forced true server-side. */
+  setConsent(levels: ConsentLevels): Promise<void>;
+  /** Read the current visitor's tracking + consent + email status. */
+  getStatus(): Promise<VisitorStatus>;
+  /** Capture a lead email (sends a magic link when verification is required). */
+  submitGate(email: string, options?: SubmitGateOptions): Promise<SubmitGateResult>;
+  /**
+   * Fire an analytics event. Fire-and-forget — never throws into the host page.
+   * Uses a raw request (the same shape the embed script posts) so it stays
+   * decoupled from the typed client's event enum.
+   */
+  track(eventType: TrackEventType, properties?: Record<string, unknown>): void;
+  /** Fire the initial `embed_loaded` (with attribution) + first page view. */
+  trackLoad(): void;
+  /** Record a page view (call on client-side route changes in an SPA). */
+  trackPageView(url?: string): void;
+  /** End the current visit (best to call on `pagehide`). */
+  endSession(): Promise<void>;
+  /** Conversation history CRUD, scoped to this guide + account. */
+  readonly conversations: ConversationsApi;
+  /** Persisted skill deliverables (how-to progress, diagnose answers, etc.). */
+  readonly skills: SkillsApi;
+  private applyInitialConsent;
+}
+//#endregion
+//#region src/react/useGuide.d.ts
+interface UseGuideResult {
+  /** The client once bootstrapped, else `null`. */
+  client: GuideClient | null;
+  /** Resolved guide metadata once ready, else `null`. */
+  guide: ResolvedGuide | null;
+  /** Conversation history, kept in sync with the client. */
+  messages: ChatMessage[];
+  /** `true` once the client has finished initializing. */
+  isReady: boolean;
+  /** `true` while a reply is streaming. */
+  isStreaming: boolean;
+  /** Init or stream error, else `null`. */
+  error: Error | null;
+  /** Send a message and stream the reply into `messages`. */
+  ask: (message: string, options?: AskOptions) => Promise<void>;
+  /** Clear the in-memory conversation. */
+  reset: () => void;
+}
+/**
+ * React binding over {@link initGuide}. Bootstraps once per `baseUrl`+`slug`,
+ * mirrors the streamed reply into state, and ends the session on unmount —
+ * encapsulating the streaming/cleanup patterns so generated UIs stay correct.
+ */
+declare function useGuide(config: InitGuideConfig): UseGuideResult;
+//#endregion
+export { type UseGuideResult, useGuide };
+//# sourceMappingURL=index.d.mts.map

package/dist/react/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/GuideClient.ts","../../src/react/useGuide.ts"],"mappings":"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"}