interface TenantConfig {
  botToken?: string; // optional Telegram bot token (BotFather)
  chatId?: string; // optional target supergroup id WITH topics, e.g. -1001234567890
  systemPrompt?: string; // optional system-prompt override
  model?: string; // optional model override
  onboardingStep?: number; // onboarding progress (optional; mirrors cloud)
  onboardingComplete?: boolean;
  visitorIdentity?: {
    enabled?: boolean; // default false; a name prompt never blocks chat
    prompt?: string; // English, up to 120 characters
    promptHe?: string; // Hebrew, up to 120 characters
    afterMessages?: number; // 1–5 visitor messages; default 1
  };
  forms?: FormSpec[]; // lead forms
  connectors?: Connector[]; // delivery / CTA connectors
  theme?: WidgetTheme; // widget appearance
  persona?: PersonaSpec; // bot voice + style rules — SERVER-ONLY, folded into the prompt, NEVER public
  script?: ConversationScript; // scripted opening sequence + starter chips (projected to the widget)
  popups?: PopupSpec[]; // proactive popup engine (theme.popupText is sugar for one timer popup)
  kbSources?: KbSource[]; // per-doc knowledge registry, assembled into the prompt at chat time
  kbVersion?: number; // bumped on any kbSources write (retrieval cache key)
  operators?: Operator[]; // humans to @mention on handoff (auto-learned; NEVER public)
  callSettings?: {
    enabled?: boolean; // default false; enables operator-initiated audio calls
    visitorRequestsEnabled?: boolean; // default false; visitor may request a call
    visitorRequestTrigger?: "after_handoff" | "always"; // default after_handoff
    notifyOnVisitorRequest?: boolean; // default true; push to registered operator devices
  };
}

interface FormSpec {
  id: string; // referenced by [!FORM:<id>]
  title: string; // card heading, e.g. "book a call"
  fields: FormField[];
  connectorIds?: string[]; // which connectors receive this lead; default = ALL configured
  successText?: string; // shown in the collapsed card after submit; widget has a default
}

interface FormField {
  name: string; // machine key, e.g. "budget"
  label: string; // visitor-facing
  type: "text" | "email" | "tel" | "textarea" | "select";
  required?: boolean;
  options?: string[]; // select only
}

type ConnectorType =
  "email" | "telegram" | "whatsapp" | "phone" | "instagram" | "facebook" | "tiktok" | "link";

// CTA fields — a connector doubles as a visitor-facing CTA card. Inert on the
// delivery-only types (email/telegram); the public projection fills per-type defaults.
interface CtaFields {
  cta?: boolean; // default true for CTA-capable types — false keeps it delivery-only
  label?: string; // button label; projection fills a per-type default when unset
  caption?: string; // small text above the button ("or keep chatting here")
  showAfterMs?: number; // per-CTA stagger after the FIRST visitor message. Default 0
}

interface Connector extends CtaFields {
  id: string;
  type: ConnectorType;
  toAddress?: string; // email
  phone?: string; // whatsapp/phone — digits, no "+" (server builds wa.me/tel hrefs)
  profileUrl?: string; // instagram (https)
  url?: string; // facebook/tiktok/link (https)
  // telegram uses the top-level botToken/chatId — no per-connector creds
}

interface Operator {
  id: number; // Telegram user id — enough for a text_mention (no public @username needed)
  name?: string; // display name (first_name), used as the mention label when no username
  username?: string; // public @username (preferred — a plain @mention, no entity)
}

interface WidgetTheme {
  launcherStyle?: "circle" | "pill"; // default circle; pill shows a label while closed
  launcherLabel?: string; // pill text, displayed up to 24 chars; defaults to the widget title
  primaryColor?: string; // visitor bubble + actions + header halo. Default gold #e39a2b
  launcherColor?: string; // optional badge fill; unset/"transparent" keeps Buttr floating
  glowColor?: string; // hex → launcher glow/sparkle/pulse tint. Unset = no glow layer at all
  position?: "br" | "bl"; // bottom-right | bottom-left. Default "br"
  avatar?: string; // "buttr" (inline default) | "none" | https URL | data:image/… URI (≤48KB)
  greeting?: string; // first bot bubble on open
  headerTitle?: string; // header text (supersedes data-title)
  tagline?: string; // header sub-line ("usually replies in minutes")
  radius?: number; // panel corner radius px, clamped 0–20. Default 20
  font?: string; // CSS font-family stack
  sound?: boolean; // notification ding. Default true
  sparkle?: boolean; // idle sparkle loop on the launcher. Default false
  direction?: "ltr" | "rtl"; // flips bubble corners + input dir. Default "ltr"
  popupText?: string; // proactive teaser-popup copy. Unset = popup off
  timing?: WidgetTiming;
}

interface WidgetTiming {
  // all ms; the widget clamps 0–300000. Each takes effect only when its feature is on.
  launcherDelayMs?: number; // default 0 = no entrance delay
  sparkleAfterMs?: number; // default 10000; inert unless sparkle
  popupDelayMs?: number; // default 8000; inert unless popupText
  popupCooldownHrs?: number; // default 24; inert unless popupText
  autoOpenMs?: number; // default 0 = never — auto-open after inbound msg while closed
}

interface PersonaSpec {
  toneOfVoice?: string; // free text: "warm, playful boulangerie owner; short sentences"
  styleRules?: string[]; // discrete do/don't rules: "never discuss competitors"
}

interface ConversationScript {
  opening?: string[]; // scripted bot-bubble sequence on panel open (projection caps at 5)
  // opening[0] supersedes theme.greeting; greeting alone == opening of length 1
  starters?: string[]; // suggested-question chips on a FRESH conversation (projection caps at 4)
  // click sends the text as the visitor's message
}

interface PopupSpec {
  trigger:
    | { kind: "timer"; delayMs?: number } // shown delayMs after load (default 8000)
    | { kind: "near"; selector: string; dwellMs?: number; threshold?: number }; // 8000 / 0.3
  text: string; // teaser card copy
  persist?: boolean; // default true → cooldownHours applies; false = resets every load
  cooldownHours?: number; // default 24; per-popup localStorage key (source ?? index)
  cancelOnClick?: string; // selector — visitor clicked the thing itself → dismiss
  source?: string; // origin label ("popup_pricing") → session context / handoff / lead meta
}

interface KbSource {
  id: string;
  name: string; // human label / doc title, e.g. "Refund policy"
  text: string; // the knowledge body
  updatedAt: number;
}
interface KbSuggestion {
  id: string;
  question: string; // what the bot couldn't answer
  answer: string; // what the human did
  createdAt: number;
}