/**
 * Types for the Rendel web SDK, for a TypeScript project that loads it
 * with a <script> tag. Save next to your sources (or reference it from
 * tsconfig "include") and `window.Rendel` is typed.
 *
 * https://rendel.ai/docs/web
 */

export type Risk = "read" | "write" | "destructive";

export interface Invocation {
  id: string;
  name: string;
  params: Record<string, any>;
  risk: Risk;
}

export interface Action {
  /** snake_case, starting with a letter. */
  name: string;
  /** How the copilot decides when to use it. */
  description: string;
  /** JSON Schema for the parameters. Leave out for none. */
  params?: Record<string, any>;
  risk: Risk;
  /** Return what the copilot should know about the outcome; throw to say it failed. */
  handler: (params: Record<string, any>, invocation: Invocation) => unknown;
  /** The sentence on the confirmation card, with {param} placeholders. */
  confirmTemplate?: string;
  /** The same sentence per language: { tr: "…" }. */
  confirmTemplates?: Record<string, string>;
  /** 15000 unless you say otherwise. */
  timeoutMs?: number;
  /** Returned instead of running the handler while a test key is in use. */
  sandboxResult?: Record<string, any>;
}

export interface Theme {
  surface?: string;
  onSurface?: string;
  accent?: string;
  onAccent?: string;
  bubble?: string;
  onBubble?: string;
  surfaceRaised?: string;
  surfaceSunk?: string;
  surfaceHigh?: string;
  composer?: string;
  onComposer?: string;
  onComposerFaint?: string;
  radius?: Partial<Record<"xs" | "sm" | "card" | "hero" | "control", number>>;
  type?: Partial<Record<"display" | "title" | "heading" | "body" | "label" | "caption" | "overline", number>>;
  fontFamily?: string;
  displayFontFamily?: string;
  /** How the parts are built; the console's `theme.style`. Absent is the first of each. */
  style?: {
    card?: "flat" | "raised" | "outlined";
    button?: "filled" | "outlined";
    product?: "tile" | "row" | "photo";
    tracker?: "vertical" | "horizontal" | "bar";
  };
  /** One kind of card set apart from the rest; the console's `theme.cards`. */
  cards?: Partial<Record<CardKind, CardLook>>;
}

export type CardKind = "product_cards" | "info_card" | "item_list" | "order_tracker" | "confirm_card";

/** One part of a card: its colour and its size in px, and a button's fill and corner. */
export interface PartLook {
  color?: string;
  size?: number;
  fill?: string;
  radius?: number;
}

/** One kind of card's plate, picture well, corner, build and parts. Absent is the theme's. */
export interface CardLook {
  surfaceRaised?: string;
  surfaceSunk?: string;
  radius?: number;
  style?: "raised" | "outlined" | "flat";
  /** Keyed by the part's `data-part` name: "title", "price", "confirm"… */
  parts?: Record<string, PartLook>;
}

/** The signed-in person's current token from your own sign-in, or null when nobody is. */
export type UserToken = string | null | undefined;

export interface InitOptions {
  appKey: string;
  /** The languages the copilot answers in: ["tr"] is Turkish only. Leave out for any. */
  languages?: string[];
  /** The page's language when it has a picker; the browser's otherwise. */
  locale?: string;
  actions?: Action[];
  theme?: Theme;
  assistantName?: string;
  launcherLabel?: string;
  suggestions?: string[];
  emptyStateTitle?: string;
  emptyStateBody?: string;
  composerHint?: string;
  attachIcon?: "paperclip" | "image" | "plus" | "off";
  voiceIcon?: "microphone" | "waveform" | "off";
  sendIcon?: "arrow-up" | "paper-plane" | "arrow-right";
  enabled?: boolean;
  /** False hides the floating button; open the panel from your own with Rendel.open(). */
  launcher?: boolean;
  /** False ignores what is published in the console. */
  remoteConfig?: boolean;
  strings?: Record<string, string | string[]>;
  onOpenUrl?: (url: string) => void;
  onLog?: (record: LogRecord) => void;
  apiBaseUrl?: string;
  streamIdleTimeoutMs?: number;
  /** The signed-in person's token; the same as calling `setUserToken`. */
  userToken?: () => UserToken | Promise<UserToken>;
}

export interface LogRecord {
  level: "debug" | "warn" | "error";
  code: string;
  message: string;
  error?: unknown;
}

export interface IdentifyOptions {
  userId: string | number;
  traits?: Record<string, unknown>;
  /** HMAC-SHA256(userId, identity secret) from your server, when verification is on. */
  userHmac?: string;
}

/**
 * What `pair` answers. `endsAt` is when the console stops watching (ISO
 * 8601). A failure's `message` is a sentence to show as it is:
 * `test_only` is a live key, `not_found` a code that is wrong, used or older
 * than ten minutes, `rate_limited` too many tries in a minute, and `failed`
 * anything else, an unreachable network included.
 */
export type PairResult =
  | { ok: true; endsAt: string }
  | { ok: false; reason: "test_only" | "not_found" | "rate_limited" | "failed"; message: string };

export interface RendelApi {
  readonly version: string;
  init(options: InitOptions): Promise<void>;
  /** After sign-in. Survives reloads; call reset() on sign-out. */
  identify(user: IdentifyOptions): Promise<void>;
  reset(): void;
  /**
   * How the copilot reaches your API as the person asking, with no API key:
   * their current token from your own sign-in, or null when nobody is signed
   * in. Asked for before every question, so return a fresh one. Never stored.
   * Safe to call before `init`; null removes it.
   */
  setUserToken(fn: (() => UserToken | Promise<UserToken>) | null): void;
  /**
   * Pairs this browser with the console: pass the code the console shows
   * (`K7Q2-M9XD`, dash and case optional). From then on the console watches
   * this browser's conversation for two hours, read only; the copilot behaves
   * exactly as before. Test keys only; a code works once, for ten minutes.
   * Never rejects. Safe to call before `init`: it waits for it, briefly.
   */
  pair(code: string): Promise<PairResult>;
  registerAction(action: Action): void;
  addContextProvider(key: string, provider: () => unknown): void;
  open(): void;
  close(): void;
  toggle(): void;
  refreshConfig(): Promise<void>;
  /** Returns a function that removes the listener. */
  on(event: "opened" | "closed" | "messageSent" | "actionExecuted", listener: () => void): () => void;
  readonly isInitialized: boolean;
  readonly isOpen: boolean;
  readonly deviceId: string | null;
}

/** @deprecated The name before 0.9.0. Use `RendelApi`. */
export type NeonCopilotApi = RendelApi;

declare global {
  interface Window {
    Rendel: RendelApi;
    /** @deprecated The name before 0.9.0, the same object. Use `Rendel`. */
    NeonCopilot: RendelApi;
  }
  const Rendel: RendelApi;
  /** @deprecated The name before 0.9.0, the same object. Use `Rendel`. */
  const NeonCopilot: RendelApi;
}