@accurix/centrinfo-widget 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+import "preact";
+
+//#region src/i18n.d.ts
+
+/**
+ * Every user-visible chrome string in one place. The widget ships English
+ * defaults; a host localises by passing `labels` to `Centrinfo.init()` —
+ * any subset is merged over the defaults (see `mergeStrings`). The chat
+ * *answers* are already multilingual server-side (the RAG mirrors the
+ * visitor's language); this covers the surrounding UI that the backend
+ * never produces.
+ */
+interface WidgetStrings {
+  openChat: string;
+  closeChat: string;
+  muteSounds: string;
+  unmuteSounds: string;
+  /** Header presence line when the org is reachable. */
+  statusOnline: string;
+  /** Header presence line when bootstrap was loaded with `offline`. */
+  statusOffline: string;
+  composerPlaceholder: string;
+  send: string;
+  emoji: string;
+  gifs: string;
+  attachFile: string;
+  recordVoice: string;
+  stopRecording: string;
+  stop: string;
+  copy: string;
+  copied: string;
+  retry: string;
+  clearChat: string;
+  clearChatConfirm: string;
+  clearChatConfirmBody: string;
+  clearConfirmCta: string;
+  /** Header "End conversation" button + its confirm dialog + ended-state copy. */
+  endChat: string;
+  endChatConfirm: string;
+  endChatConfirmBody: string;
+  endConfirmCta: string;
+  conversationEnded: string;
+  startNewChat: string;
+  /** Past-conversations history. */
+  pastConversations: string;
+  viewingPast: string;
+  backToChat: string;
+  historyEnded: string;
+  /** Per-message 👍/👎 feedback. */
+  feedbackHelpful: string;
+  feedbackNotHelpful: string;
+  feedbackThanks: string;
+  /** End-of-chat CSAT prompt. */
+  csatPrompt: string;
+  feedbackCommentPlaceholder: string;
+  feedbackSend: string;
+  cancel: string;
+  newMessages: string;
+  poweredBy: string;
+  searchGifs: string;
+  searchingGifs: string;
+  noGifs: string;
+  assistantTyping: string;
+  emptyReply: string;
+  errorGeneric: string;
+  errorRateLimit: string;
+  attaching: string;
+  attachTooLarge: string;
+  attachFailed: string;
+  /** Handoff card (manual follow-up request). */
+  handoffTitle: string;
+  handoffName: string;
+  handoffEmail: string;
+  handoffNotify: string;
+  sending: string;
+  /** Confirmation after a manual submit. `{email}` is replaced with the address (or removed). */
+  handoffShared: string;
+  /** Generic action-form success fallback + error. */
+  formThanks: string;
+  formError: string;
+  /** Demo-booking picker. */
+  bookingPickTime: string;
+  bookingDuration: string;
+  /** Confirmation after requesting a demo. `{when}` = the chosen slot. */
+  bookingRequested: string;
+  /** Confirmation when a real calendar event was created. `{when}` = slot. */
+  bookingConfirmed: string;
+  /** Shown when the chosen slot was just taken by someone else. */
+  bookingSlotTaken: string;
+  /** Link-mode (Calendly): prompt + CTA + done note + the meeting link label.
+   * `{provider}` = the scheduler label (e.g. "Calendly"). */
+  bookingViaProvider: string;
+  bookingOpenScheduler: string;
+  bookingLinkOpened: string;
+  bookingMeetingLink: string;
+  /** Preview mode (data-preview): canned reply, action note, top banner. */
+  previewReply: string;
+  previewActionNote: string;
+  previewBanner: string;
+}
+//#endregion
+//#region src/types.d.ts
+/** Public configuration surface passed to `Centrinfo.init()` / <CentrinfoWidget>. */
+interface WidgetConfig {
+  /** The org's public chat token (`pub_*`). Required. It IS the org identity. */
+  token: string;
+  /** API origin. Defaults to the production Centrinfo API. */
+  apiBaseUrl?: string;
+  /** Brand accent (any CSS color). Overrides the persona/default green. */
+  accentColor?: string;
+  /** Custom launcher icon — an image URL (e.g. the org's logo). Defaults to a chat glyph. */
+  launcherIcon?: string;
+  /** Tenor API key — enables the GIF picker. Omit to hide the GIF button. */
+  gifApiKey?: string;
+  /** Force a theme; otherwise follows the host's `prefers-color-scheme`. */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Open the panel automatically on first load. */
+  openByDefault?: boolean;
+  /** Play subtle sound effects (open / send / receive). Default true. Visitors can still mute. */
+  sound?: boolean;
+  /**
+   * Tappable example questions shown under the greeting until the visitor
+   * sends their first message. When omitted, the widget falls back to the
+   * `starterQuestions` configured on the token (served by bootstrap).
+   */
+  starters?: string[];
+  /**
+   * Localise the UI chrome. Any subset of `WidgetStrings` is merged over the
+   * English defaults — pass e.g. `{ composerPlaceholder: 'Écrivez…' }`. The
+   * chat answers themselves are already multilingual server-side.
+   */
+  labels?: Partial<WidgetStrings>;
+  /**
+   * Where the visible transcript is stored across reloads:
+   * - `local` (default) — `localStorage`, survives browser restarts (30d TTL).
+   * - `session` — `sessionStorage`, cleared when the tab closes (better on
+   *   shared / kiosk machines so the next visitor can't read prior chats).
+   * - `none` — never persisted; the transcript lives only in memory.
+   * The backend session id + memory are unaffected — this is purely the
+   * locally-rendered history.
+   */
+  persistence?: 'local' | 'session' | 'none';
+  /**
+   * Let visitors attach an image / PDF for the assistant to read (extracted
+   * server-side via the multimodal endpoint). Default true; set false to hide
+   * the attach button entirely.
+   */
+  attachments?: boolean;
+  /** Stacking context against the host page. */
+  zIndex?: number;
+  /** Use the built-in mock transport (local preview, no backend/token needed). */
+  demo?: boolean;
+  /**
+   * Preview mode. Loads the widget's REAL branding (via the bootstrap read)
+   * but answers every chat with a canned sample reply instead of calling the
+   * AI — so a developer can test the integration anywhere with just the token,
+   * at zero AI cost. Remove this flag (or use the normal embed) to go live.
+   */
+  preview?: boolean;
+  /**
+   * Host-app SSO passthrough. When the embedding site has a logged-in
+   * user, pass their identity here so the chat session is correlated
+   * with them in the org's widget inbox (instead of showing as
+   * "Anonymous"). Fully optional — omit for unauthenticated visitors.
+   *
+   * The widget posts this to `POST /public-chat/identify` once after
+   * bootstrap completes. To identify a visitor who logs in MID-SESSION
+   * (anonymous chat → sign-in), call `handle.identify(user)` instead.
+   * The same `sessionId` survives the identify call, so prior
+   * anonymous messages stay attached to the now-known session row.
+   *
+   * See .claude/PUBLIC_WIDGET_LIBRARY.md "Identified visitors" for
+   * what fields to pass + the privacy guidance.
+   */
+  user?: WidgetUser;
+  /** Which side the launcher + panel dock to. Default 'right'. */
+  alignment?: 'left' | 'right';
+  /** Horizontal distance (px) from the aligned edge. Default 20. */
+  horizontalPadding?: number;
+  /** Vertical distance (px) from the bottom. Default 20. */
+  verticalPadding?: number;
+  /** Hide the built-in launcher button — open the widget via `show()` or a
+   * `customLauncherSelector`. Default false. */
+  hideDefaultLauncher?: boolean;
+  /** CSS selector for host-page element(s) that open the widget on click
+   * (your own launcher). Listeners are (re)bound automatically. */
+  customLauncherSelector?: string;
+  /** Auto-logout (wipe local data) after this many minutes of inactivity.
+   * 0 / omitted = never. Use on shared / kiosk devices. */
+  sessionDurationMinutes?: number;
+  /** A message to proactively show (auto-opens the widget) — e.g.
+   * "Questions about pricing? I'm here 👋". Omit to disable. */
+  proactiveMessage?: string;
+  /** Seconds to wait on the page before showing it. Default 5. */
+  proactiveDelaySeconds?: number;
+  /** Only fire on pages whose path contains one of these substrings.
+   * Omitted/empty = every page. e.g. ['/pricing', '/checkout']. */
+  proactiveOnPaths?: string[];
+  /** Show a "How was this chat?" CSAT rating when the conversation ends.
+   * Default true. */
+  csat?: boolean;
+  /** Event hooks. */
+  onOpen?: () => void;
+  onClose?: () => void;
+  /** Aliases of onOpen/onClose (Intercom naming). Both fire. */
+  onShow?: () => void;
+  onHide?: () => void;
+  /** Fires whenever the unread-message count changes (drive your own badge). */
+  onUnreadChange?: (count: number) => void;
+  onMessage?: (msg: {
+    role: 'user' | 'assistant';
+    content: string;
+  }) => void;
+  onAction?: (action: string) => void;
+  onHandoff?: () => void;
+}
+/** A B2B company / account the visitor belongs to (Intercom "Company object").
+ * Folded into the session metadata for the staff inbox. */
+interface WidgetCompany {
+  id?: string;
+  name?: string;
+  plan?: string;
+  /** Account creation date — epoch seconds/ms or ISO string. */
+  createdAt?: number | string;
+  monthlySpend?: number;
+  /** Any extra company attributes. */
+  [key: string]: string | number | boolean | undefined;
+}
+/** Host-app SSO passthrough payload + data attributes. All fields optional. */
+interface WidgetUser {
+  /** Host-app's stable user id (UUID, account number, etc.). Strongly recommended. */
+  externalId?: string;
+  /** Intercom-style alias for `externalId` (whichever you set is used). */
+  userId?: string;
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  /** Single-field name when first/last aren't split host-side. */
+  name?: string;
+  phone?: string;
+  /** Account creation date — epoch seconds/ms or ISO string (a data attribute). */
+  createdAt?: number | string;
+  /** Avatar image URL (the "Avatar object") — surfaced to staff in the inbox. */
+  avatarUrl?: string;
+  /** The visitor's company / account (B2B "Company object"). */
+  company?: WidgetCompany;
+  /**
+   * Custom data attributes (plan tier, signup date, segment, …). Merged into
+   * the session metadata, same privacy caveat as `metadata` below.
+   */
+  customAttributes?: Record<string, string | number | boolean>;
+  /**
+   * Arbitrary host-app key/values (plan tier, signup date, custom
+   * segments). Surfaced as-is in the org's staff inbox. DO NOT pass
+   * sensitive data — the widget script runs on the public web and a
+   * determined visitor with devtools could inspect it. Safe: plan
+   * tier, signup date, segment. Unsafe: card numbers, SSNs, auth
+   * tokens, internal admin flags.
+   */
+  metadata?: Record<string, string | number | boolean>;
+}
+/** Imperative handle returned by `init()` / `createWidget()`. */
+interface WidgetHandle {
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  /** Open the panel (alias of `open`, Intercom naming). */
+  show: () => void;
+  /** Close the panel (alias of `close`, Intercom naming). */
+  hide: () => void;
+  /** Update the visitor's attributes mid-session (merge). Alias of `identify`. */
+  update: (user: WidgetUser) => void;
+  /**
+   * Identify the visitor mid-session (e.g. after they log in on the
+   * host site). The session's prior anonymous messages stay attached
+   * — the widget's sessionId is stable across identify. Same merge
+   * semantics as boot-time `user`: first-value-wins per field, shallow
+   * metadata merge.
+   */
+  identify: (user: WidgetUser) => void;
+  /** Wipe the locally-rendered transcript + start a fresh backend session. */
+  clear: () => void;
+  /**
+   * Logout: erase ALL of this visitor's locally-stored data (identity,
+   * transcripts, conversation history) and reset to a fresh anonymous
+   * session. Call on host-app logout / shared devices — à la Intercom
+   * `shutdown`. `logout` is an alias.
+   */
+  shutdown: () => void;
+  logout: () => void;
+  destroy: () => void;
+}
+//#endregion
+//#region src/mount.d.ts
+/** Create + mount a widget. Returns an imperative handle. */
+declare const createWidget: (config: WidgetConfig) => WidgetHandle;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Boot the widget. Idempotent — a second `init()` tears down the previous
+ * instance first, so calling it twice (e.g. SPA re-render) won't stack widgets.
+ */
+declare const init: (config: WidgetConfig) => WidgetHandle;
+declare const Centrinfo: {
+  init: (config: WidgetConfig) => WidgetHandle;
+  createWidget: (config: WidgetConfig) => WidgetHandle;
+};
+//#endregion
+export { Centrinfo, type WidgetConfig, type WidgetHandle, type WidgetStrings, type WidgetUser, createWidget, init };