Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

63.8 KB
Raw Blame
// API Service Layer for OpenWA Dashboard
// Centralized API client with TypeScript types

import { warnIfInsecureHttpUrl } from '../utils/urlSecurity';
import { isKeyUnusable } from '../utils/authLifecycle';
import { fetchAllPages } from '../utils/fetchAllPages';

// Resolve the API base URL. By default this is the same-origin relative path '/api',
// correct when the dashboard and API are served from the same origin (the default
// single-container setup). For a split-origin deployment (dashboard hosted separately
// from the API), set VITE_API_URL at build time to the API ORIGIN — e.g.
// `VITE_API_URL=https://gateway.example.com` — and the '/api' prefix is appended here.
// Previously VITE_API_URL was documented but never read, so the dashboard always called
// same-origin '/api' and a split deployment failed with "Invalid API Key" (#91).
// Exported so direct fetches (e.g. auth/validate in Login.tsx / App.tsx) honor VITE_API_URL
// too — otherwise split-origin deployments break. Empty VITE_API_URL → '/api'.
export const API_ORIGIN = (import.meta.env.VITE_API_URL ?? '').replace(/\/+$/, '');
export const API_BASE_URL = `${API_ORIGIN}/api`;
// Warn (not refuse — would break dev + TLS-terminating-proxy) when the API origin is an
// insecure http:// URL pointing at a non-localhost host (API keys sent in cleartext).
if (API_ORIGIN) warnIfInsecureHttpUrl(API_ORIGIN, 'VITE_API_URL');

// =============================================================================
// Types
// =============================================================================

/**
 * The three tunable keys, as the gateway resolves them — not the raw stored column, which the API
 * never returns. `maxReconnectAttempts` is null when reconnects are unlimited, which is the default
 * and which no number in the accepted 0-20 range can express.
 */
export interface SessionConfig {
  autoRejectCalls: boolean;
  maxReconnectAttempts: number | null;
  reconnectBaseDelay: number;
}

export type SessionProxyType = 'http' | 'https' | 'socks4' | 'socks5';

export interface SessionProxy {
  enabled: boolean;
  proxyType: SessionProxyType | null;
  proxyHost: string | null;
  hasCredentials: boolean;
}

export interface CreateSessionOptions {
  proxyUrl?: string;
  proxyType?: SessionProxyType;
}

export interface Session {
  id: string;
  name: string;
  status:
    | 'created'
    | 'initializing'
    | 'authenticating'
    | 'qr_ready'
    | 'ready'
    | 'disconnected'
    | 'action_required'
    | 'failed';
  /**
   * Whether the gateway holds a live engine for this session right now. The precondition the
   * lifecycle routes enforce, and not derivable from `status`: `disconnected` covers both a session
   * mid automatic-reconnect (engine present, start 400s) and one stopped through stop() (no engine).
   * Optional BY DESIGN, not drift: the wire always carries it, but this client's state model
   * clears it to "unknown" after a websocket status event until the row refreshes, so the action
   * helpers fall back to the historical status set instead of trusting a stale value.
   */
  engineLoaded?: boolean;
  phone?: string | null;
  pushName?: string | null;
  connectedAt?: string | null;
  lastActive?: string | null;
  createdAt: string;
  updatedAt: string;
  /** Human-readable reason carried while the status is 'failed' (terminal failure),
   * 'action_required' (operator must intervene, e.g. acknowledge an onboarding modal), or
   * 'initializing' during an engine-internal reconnect (from the fifth consecutive attempt, or while a
   * retry waits after a failed relaunch). */
  lastError?: string | null;
  /**
   * A limit WhatsApp itself has placed on the account, or null when there is none. Distinct from
   * `lastError`, which describes a fault on the gateway's side of the link. Optional only because a
   * dashboard can be served by a gateway that predates the field.
   */
  restriction?: AccountRestriction | null;
}

/** One participant's presence within a chat. */
export interface ParticipantPresence {
  id: string;
  /** `composing`/`recording` mean actively typing or recording; `paused` means they stopped. */
  state: 'available' | 'unavailable' | 'composing' | 'recording' | 'paused';
  /** Unix SECONDS. Absent whenever the contact's privacy settings hide last-seen. */
  lastSeen?: number;
}

/** The last presence reported for a chat since it was subscribed. */
export interface ChatPresence {
  chatId: string;
  participants: ParticipantPresence[];
  groupOnlineCount?: number;
  /** When the gateway received the report — NOT a WhatsApp timestamp. */
  observedAt: string;
}

/**
 * A restriction WhatsApp has in force on a session's account.
 *
 * `reachout_timelock` leaves the session connected and existing chats working — only starting new
 * conversations is blocked — which is why it can appear on a perfectly `ready` session. `tos_block`
 * and `proxy_block` refuse the connection itself and so cannot.
 */
export interface AccountRestriction {
  kind: 'reachout_timelock' | 'tos_block' | 'proxy_block';
  /** The engine's own token for the cause, verbatim (`TOS_BLOCK`, `BIZ_QUALITY`, …). */
  code: string;
  /** ISO timestamp when enforcement ends, when WhatsApp states one. */
  expiresAt?: string | null;
}

export interface SessionStats {
  total: number;
  active: number;
  ready: number;
  disconnected: number;
  byStatus: Record<string, number>;
  memoryUsage: { heapUsed: number; heapTotal: number; rss: number };
}

export type WebhookFilterOperator = 'is' | 'isNot' | 'contains' | 'equals';

export interface WebhookFilterCondition {
  field: string;
  operator: WebhookFilterOperator;
  value: string | string[] | boolean;
  caseSensitive?: boolean;
}

export interface WebhookFilters {
  conditions: WebhookFilterCondition[];
}

export interface Webhook {
  id: string;
  sessionId: string;
  url: string;
  events: string[];
  filters?: WebhookFilters | null;
  active: boolean;
  retryCount: number;
  /** Null until the first delivery attempt. */
  lastTriggeredAt?: string | null;
  createdAt: string;
  updatedAt: string;
}

// Request bodies for webhook writes. `secret` and `headers` are write-only: no webhook read returns them.
export interface CreateWebhookRequest {
  url: string;
  events: string[];
  filters?: WebhookFilters | null;
  secret?: string;
  headers?: Record<string, string>;
}

export interface UpdateWebhookRequest {
  url?: string;
  events?: string[];
  active?: boolean;
  filters?: WebhookFilters | null;
  /** An empty string removes the stored secret. */
  secret?: string;
  /** Replaces the stored map wholesale; `{}` removes every custom header. */
  headers?: Record<string, string>;
}

export interface MessageTemplate {
  id: string;
  sessionId: string;
  name: string;
  body: string;
  header?: string | null;
  footer?: string | null;
  createdAt: string;
  updatedAt: string;
}

export interface TemplatePayload {
  name: string;
  body: string;
  header?: string | null;
  footer?: string | null;
}

export interface ApiKey {
  id: string;
  name: string;
  keyPrefix: string;
  role: 'admin' | 'operator' | 'viewer';
  allowedIps?: string[];
  allowedSessions?: string[];
  allowedChats?: string[];
  isActive: boolean;
  expiresAt?: string;
  lastUsedAt?: string;
  usageCount: number;
  createdAt: string;
}

/** The creation response: every list/detail field plus the plaintext key, shown exactly once. */
export interface CreatedApiKey extends ApiKey {
  apiKey: string;
}

export interface AuditLog {
  id: string;
  action: string;
  severity: 'info' | 'warn' | 'error';
  apiKeyId: string | null;
  apiKeyName: string | null;
  sessionId: string | null;
  sessionName: string | null;
  ipAddress: string | null;
  userAgent: string | null;
  method: string | null;
  path: string | null;
  statusCode: number | null;
  /** Null when the action succeeded. */
  errorMessage: string | null;
  /** Free-form context whose shape varies per action. */
  metadata: Record<string, unknown> | null;
  createdAt: string;
}

export interface MessageResponse {
  messageId: string;
  timestamp: number;
}

// Mirrors the backend engine ChatKind (dashboard cannot import wa-id.ts).
export type ChatKind = 'individual' | 'group' | 'channel' | 'status' | 'broadcast' | 'unknown';
// Mirrors CHAT_KINDS in the backend webhook filter registry (src/modules/webhook/filters/filter-types.ts).
export const CHAT_KINDS: readonly ChatKind[] = ['individual', 'group', 'channel', 'status', 'broadcast', 'unknown'];

// Chat summary returned by GET /sessions/:id/chats (mirrors the backend ChatSummary).
export interface Chat {
  id: string;
  name: string;
  isGroup: boolean;
  kind: ChatKind;
  unreadCount: number;
  timestamp: number;
  lastMessage?: string;
  lastMessageType?: MessageType;
  archived: boolean;
  pinned: boolean;
  muted: boolean;
  muteExpiration?: number;
}

// Engine-neutral message types (mirrors the backend's IWhatsAppEngine MessageType). The backend
// normalizes raw engine tokens at the adapter boundary (#265/#270), so persisted rows, the
// message.received/sent payloads, and the websocket all use these values.
export const MESSAGE_TYPES = [
  'text',
  'image',
  'video',
  'audio',
  'voice',
  'document',
  'sticker',
  'location',
  'contact',
  'poll',
  'call',
  'revoked',
  'order',
  'product',
  'masked',
  'unknown',
] as const;
export type MessageType = (typeof MESSAGE_TYPES)[number];

/** Coerce an arbitrary string (e.g. a raw websocket payload field) to a known MessageType. */
export function asMessageType(value: string | undefined): MessageType {
  return (MESSAGE_TYPES as readonly string[]).includes(value ?? '') ? (value as MessageType) : 'unknown';
}

export interface ChatMessage {
  id: string;
  waMessageId?: string;
  chatId: string;
  /** Chat kind of the source conversation (present on live engine/WS payloads). */
  kind?: ChatKind;
  /**
   * Human-readable name of the message's sender. For a group this is the participant who posted
   * (their pushName/contact name); the chat view uses it to label who said what, like WhatsApp. Null
   * on legacy rows or when the engine could not resolve a name.
   */
  chatName?: string;
  /**
   * Stable sender identity for a group message: the participant JID who actually posted (`from` is
   * the group JID). Present on live/engine payloads and on rows persisted after the column was
   * added; absent on 1:1 messages, outgoing echoes, and legacy rows.
   */
  author?: string;
  from: string;
  to: string;
  body: string;
  type: MessageType;
  direction: 'incoming' | 'outgoing';
  status: 'pending' | 'sent' | 'delivered' | 'read' | 'failed';
  timestamp?: number;
  createdAt: string;
  metadata?: {
    poll?: { name: string; options: string[]; allowMultipleAnswers: boolean };
    media?: {
      mimetype: string;
      filename?: string;
      data?: string;
      omitted?: boolean;
      sizeBytes?: number;
      /** With `omitted`: the inline copy was dropped because the chat-media archive holds the bytes. */
      archived?: boolean;
    };
    quotedMessage?: { id: string; body: string };
    reactions?: Record<string, string>;
    /** The gateway observed an edit of this message. */
    edited?: boolean;
    call?: { video: boolean; missed: boolean };
    /** Business prompt choices (Baileys). Present on inbound prompts that offer buttons. */
    buttons?: Array<{ id: string; text: string }>;
  };
}

// Live WhatsApp message from the engine history endpoint (not a persisted DB row): it carries `fromMe`
// instead of `direction`/`status`. Used to backfill a chat thread the gateway never captured live.
export interface EngineHistoryMessage {
  id: string;
  chatId: string;
  from: string;
  to: string;
  body: string;
  type: MessageType;
  /** Unix timestamp in seconds. */
  timestamp: number;
  fromMe: boolean;
  isGroup: boolean;
  isStatusBroadcast?: boolean;
  kind: ChatKind;
  /** Disappearing-messages timer on the chat, in seconds. Absent when the chat has none set. */
  ephemeralDuration?: number;
  /** Sender in a group: `from` is the group JID, so this participant WID is the real poster. */
  author?: string;
  mentionedIds?: string[];
  /** Present on `call` messages only. */
  call?: { video: boolean; missed: boolean };
  isLidSender?: boolean;
  senderPhone?: string | null;
  /**
   * Sender contact info, best-effort from the engine's cache. History carries `name` and `pushName`;
   * the richer fields are added when `WEBHOOK_CONTACT_DETAILS=true`, as on `message.received`.
   */
  contact?: {
    id?: string;
    number?: string;
    name?: string;
    pushName?: string;
    shortName?: string;
    type?: string;
    isMyContact?: boolean;
    isWAContact?: boolean;
    isBusiness?: boolean;
    isEnterprise?: boolean;
    verifiedName?: string;
    verifiedLevel?: number;
    isBlocked?: boolean;
    labels?: string[];
  };
  /** Status/story styling. Declared by the engine payload; this route never sets either. */
  backgroundColor?: string;
  font?: number;
  media?: {
    mimetype: string;
    filename?: string;
    data?: string;
    omitted?: boolean;
    sizeBytes?: number;
    archived?: boolean;
  };
  poll?: { name: string; options: string[]; allowMultipleAnswers: boolean };
  quotedMessage?: { id: string; body: string };
  location?: { latitude: number; longitude: number; description?: string; address?: string; url?: string };
  /** Present on `order` messages only: the placed cart, plus the single-order token for its items. */
  order?: { orderId: string; token?: string };
  /** Present on `product` messages only: the catalog product shared into the chat. */
  product?: { productId: string; title?: string; description?: string; businessOwnerJid?: string };
}

// Mirrors the backend engine Channel / ChannelMessage (GET /sessions/:id/channels[/:id/messages]).
export interface Channel {
  id: string;
  name: string;
  description?: string;
  inviteCode?: string;
  subscriberCount?: number;
  picture?: string;
  verified?: boolean;
  createdAt?: number;
}

export interface ChannelMessage {
  id: string;
  body: string;
  timestamp: number;
  hasMedia: boolean;
  mediaUrl?: string;
}

// Mirrors the backend engine Status / IWhatsAppEngine status methods (GET /sessions/:id/status).
export interface StatusUpdate {
  id: string;
  contact: { id: string; name?: string; pushName?: string };
  type: 'text' | 'image' | 'video' | 'voice';
  caption?: string;
  mediaUrl?: string;
  backgroundColor?: string;
  font?: number;
  timestamp: string;
  expiresAt: string;
}

export interface ContactStatusGroup {
  contact: { id: string; name?: string; pushName?: string };
  items: StatusUpdate[];
  latest: string;
}

/** GET /sessions/:id/groups/:groupId (GroupInfoDto). */
export interface GroupInfo {
  id: string;
  name: string;
  description?: string;
  owner?: string;
  createdAt?: number;
  participants: Array<{ id: string; number: string; name?: string; isAdmin: boolean; isSuperAdmin: boolean }>;
  /** Only admins may edit the group's info. */
  locked?: boolean;
  announce?: boolean;
}

export interface GroupAck {
  success: boolean;
  message: string;
}

/** One participant's outcome of a membership write; the gateway answers 200 even when some are refused. */
export interface GroupParticipantResult {
  id: string;
  success: boolean;
  status?: number;
  message?: string;
}

export interface GroupParticipantsAck extends GroupAck {
  results: GroupParticipantResult[];
}

// An entry of the session's address book, from GET /sessions/:id/contacts: what the recipient pickers and the
// chat list's saved-contact check read. Only the name, push name and picture are optional.
export interface Contact {
  id: string;
  name?: string;
  pushName?: string;
  /** MSISDN digits without separators — always present in the response. */
  number: string;
  isMyContact: boolean;
  isBlocked: boolean;
  /** Absent when the contact has none or privacy hides it. */
  profilePicUrl?: string;
}

export interface SendMediaPayload {
  base64?: string;
  url?: string;
  mimetype?: string;
  filename?: string;
  caption?: string;
  /** Quote an earlier message, making the media send a reply. Omit for an ordinary send. */
  quotedMessageId?: string;
}

// Payloads below mirror the backend DTOs in src/modules/message/dto (raw bodies, no envelope).
export interface SendLocationPayload {
  chatId: string;
  latitude: number;
  longitude: number;
  description?: string;
  address?: string;
}

export interface SendContactPayload {
  chatId: string;
  contactName: string;
  contactNumber: string;
}

export interface SendPollPayload {
  chatId: string;
  name: string;
  options: string[];
  allowMultipleAnswers?: boolean;
}

export interface ForwardMessagePayload {
  fromChatId: string;
  toChatId: string;
  messageId: string;
}

// Media block of a single bulk message (BulkMediaDto — no caption; caption sits next to it).
export interface BulkMediaPayload {
  url?: string;
  base64?: string;
  mimetype?: string;
  filename?: string;
  ptt?: boolean;
}

export interface BulkMessageItem {
  chatId: string;
  type: 'text' | 'image' | 'video' | 'audio' | 'document';
  content: {
    text?: string;
    image?: BulkMediaPayload;
    video?: BulkMediaPayload;
    audio?: BulkMediaPayload;
    document?: BulkMediaPayload;
    caption?: string;
  };
  variables?: Record<string, string>;
}

export interface SendBulkPayload {
  batchId?: string;
  messages: BulkMessageItem[];
  options?: {
    delayBetweenMessages?: number;
    randomizeDelay?: boolean;
    stopOnError?: boolean;
  };
}

/** 202 response of POST send-bulk — the batch is processing asynchronously; poll getBatchStatus. */
export interface BulkBatchResponse {
  batchId: string;
  status: string;
  totalMessages: number;
  estimatedCompletionTime?: string;
  statusUrl: string;
}

export type BatchStatus = 'pending' | 'processing' | 'completed' | 'cancelled' | 'failed';

export interface BatchProgress {
  total: number;
  sent: number;
  failed: number;
  pending: number;
  cancelled: number;
}

export interface BatchMessageResult {
  chatId: string;
  status: 'pending' | 'sent' | 'failed' | 'cancelled';
  messageId?: string;
  error?: { code: string; message: string };
  sentAt?: string;
}

/** GET batch/:batchId shape. */
export interface BatchStatusResponse {
  batchId: string;
  status: BatchStatus;
  progress: BatchProgress;
  /** One entry per recipient already attempted — empty until the first send resolves. */
  results: BatchMessageResult[];
  startedAt?: string | null;
  completedAt?: string | null;
}

/** POST batch/:batchId/cancel shape: the batch state without per-recipient results or timestamps. */
export interface BatchCancelResponse {
  batchId: string;
  status: BatchStatus;
  progress: BatchProgress;
}

export interface HealthStatus {
  status: 'ok' | 'error';
  timestamp?: string;
  /** Running backend version (from package.json) — read live so the sidebar never shows a stale build. */
  version?: string;
  details?: {
    database?: { status: string };
    redis?: { status: string };
    queue?: { status: string };
  };
}

/** GET /infra/update-check: the running version against the latest published release. */
export interface UpdateCheck {
  current: string;
  latest: string | null;
  updateAvailable: boolean;
  releaseUrl: string | null;
}

export interface InfraStatus {
  // `builtIn` = OpenWA's own bundled container is actually running and backing this service (live),
  // not just the saved intent; falls back to the saved flag (the environment's first) beside a host that reaches the
  // bundled container when Docker is unavailable. (#488) `running` = a bundled container OpenWA created is up,
  // whether or not the service uses it, beside this instance's own built-in flag (the environment's first, else the
  // saved one); false for one Docker Compose created and with that flag not true, absent while Docker is unreachable,
  // and from an older gateway.
  database: { connected: boolean; type: string; host: string; builtIn: boolean; running?: boolean };
  redis: { enabled: boolean; connected: boolean; host: string; port: number; builtIn: boolean; running?: boolean };
  queue: {
    enabled: boolean;
    webhooks: { pending: number; completed: number; failed: number };
  };
  storage: {
    type: 'local' | 's3';
    path?: string;
    bucket?: string;
    // S3 only, when an endpoint is set: the one the server dials, which a stopped bundled MinIO still names.
    endpoint?: string;
    builtIn: boolean;
    running?: boolean;
    s3Available?: boolean;
  };
  engine: {
    type: string;
    headless: boolean;
    // whatsapp-web.js only: the WhatsApp Web build sessions request as their pin (distinct from the
    // library version, and not necessarily the build a page runs) and how it was chosen. (#488)
    webVersion?: string | null;
    webVersionSource?: 'pinned' | 'auto' | 'native';
  };
  /**
   * Editable settings supplied by a layer above `data/.env.generated` (the container environment or a
   * project `.env`), which therefore cannot be changed from this page until that layer is. Reported by
   * the gateway rather than inferred from a running-vs-saved mismatch, because that mismatch is also
   * what an unrestarted save looks like and the two need opposite advice (#1082).
   *
   * Optional only because a dashboard can be served by a gateway that predates the field.
   */
  envPinned?: string[];
}

// Saved infrastructure config (from data/.env.generated) used to hydrate the form.
// Secrets are never returned — `*Set` flags indicate whether a value is stored.
export interface SavedConfig {
  database: {
    type: 'sqlite' | 'postgres';
    builtIn: boolean;
    // Whether the saved config states the built-in mode of this service. False when a host the environment
    // pins decides it, when the file does not select the service (the first boot writes every flag as false),
    // when the file holds the bundled host with the flag not true (the next boot dials the container) and when
    // nothing is saved: the form then follows what /infra/status reports as running.
    builtInSet: boolean;
    host: string;
    port: string;
    username: string;
    database: string;
    schema: string;
    poolSize: number;
    sslEnabled: boolean;
    sslRejectUnauthorized: boolean;
    passwordSet: boolean;
  };
  redis: { enabled: boolean; builtIn: boolean; builtInSet: boolean; host: string; port: string; passwordSet: boolean };
  queue: { enabled: boolean };
  storage: {
    type: 'local' | 's3';
    builtIn: boolean;
    builtInSet: boolean;
    localPath: string;
    s3Bucket: string;
    s3Region: string;
    s3Endpoint: string;
    s3CredentialsSet: boolean;
  };
  engine: { type: string; headless: boolean; sessionDataPath: string; browserArgs: string };
}

export interface SaveConfigPayload {
  database?: {
    // Absent keeps the stored selection; the form leaves out a type the environment pins.
    type?: 'sqlite' | 'postgres';
    builtIn?: boolean;
    host?: string;
    port?: string;
    username?: string;
    password?: string;
    database?: string;
    schema?: string;
    poolSize?: number;
    sslEnabled?: boolean;
    sslRejectUnauthorized?: boolean;
  };
  redis?: {
    enabled?: boolean;
    builtIn?: boolean;
    host?: string;
    port?: string;
    password?: string;
  };
  queue?: {
    enabled?: boolean;
  };
  storage?: {
    type?: 'local' | 's3';
    builtIn?: boolean;
    localPath?: string;
    s3Bucket?: string;
    s3Region?: string;
    s3AccessKey?: string;
    s3SecretKey?: string;
    s3Endpoint?: string;
  };
  engine?: {
    type?: string;
    headless?: boolean;
    sessionDataPath?: string;
    browserArgs?: string;
  };
}

// Global message search (mirrors the backend GET /search contract from #664).
// `timestamp` is epoch-seconds (the messages column is seconds, not ms); `dateFrom`/`dateTo`
// are epoch-ms on the wire — see `dateFrom`/`dateTo` JSDoc below.
export interface SearchParams {
  q: string;
  sessionId?: string;
  chatId?: string;
  direction?: string;
  type?: string;
  from?: string;
  /** Epoch-ms lower bound (inclusive) — the backend binds against messages.timestamp (/1000). */
  dateFrom?: number;
  /** Epoch-ms upper bound (inclusive). */
  dateTo?: number;
  limit?: number;
  offset?: number;
}

export interface SearchHit {
  messageId: string;
  waMessageId: string;
  sessionId: string;
  chatId: string;
  body: string;
  /** Provider-generated excerpt with `<mark>` highlight markers — render as text, never as HTML. */
  snippet: string;
  /** Epoch-seconds (mirrors the persisted messages.timestamp column). */
  timestamp: number;
  type: string;
  direction: 'incoming' | 'outgoing';
  from: string;
  score?: number;
}

export interface SearchResults {
  hits: SearchHit[];
  total: number;
  tookMs: number;
  provider: string;
}

// =============================================================================
// API Client
// =============================================================================

// Shared failure handling for every response shape (json/text/blob). When the stored API key is
// unusable (a 401 for an invalid/expired/revoked key, or a 403 because its allowedIps refuse this
// client) clear it and return to login so the user isn't stuck on a dashboard where every request
// fails; the never-settling promise halts this request's chain so callers neither flash a generic
// error toast nor receive an undefined payload while the page navigates away. Otherwise throw an
// Error carrying the HTTP status and, when the gateway supplied one, its machine code.
// `sentKey` is the key the request carried (null when none). Logout aborts nothing in flight, so an
// answer can arrive after the stored key changed. With a key sent but none stored, a sign-out is
// already under way (an earlier failure of the same burst, or the user on the login form): stay
// silent and do not navigate again. A request sent without a key comes only from a chain that
// outlived a logout (the dashboard shows the login form whenever no key is stored), so with none
// stored it stays silent too rather than reloading the login form under the user. With another key
// stored, the answer speaks for a key no longer in use and must not sign out the current one, so it
// fails like any other error.
async function handleErrorResponse<T>(response: Response, sentKey: string | null): Promise<T> {
  // On a non-JSON body (e.g. a reverse-proxy 502/503/504 HTML page) fall through to `HTTP <status>`
  // rather than statusText: the toast folds an exact `HTTP 502`/`HTTP 503` into its connection-lost
  // toast (a 504 keeps its own), and statusText is empty over HTTP/2 anyway.
  const error = await response.json().catch(() => ({}));
  const storedKey = sessionStorage.getItem('openwa_api_key');
  if (isKeyUnusable(response.status, error.message) && (storedKey === sentKey || storedKey === null)) {
    sessionStorage.removeItem('openwa_api_key');
    if (typeof window !== 'undefined') {
      if (sentKey !== null && storedKey === sentKey) window.location.assign('/');
      return new Promise<T>(() => {});
    }
  }
  // Carry the HTTP status on the Error (message unchanged, so the toast de-dup still matches) so
  // callers can tell apart a permission 403 from a real server 5xx instead of guessing from text.
  // Carry the machine `code` too: the gateway's stable codes (SESSION_LOGOUT_INCOMPLETE,
  // SESSION_NAME_TEARDOWN_PENDING, …) drive specific recovery UI, and a reverse-proxy 502 that
  // never reached the gateway carries no code at all — that distinction is exactly what the unlink
  // classifier keys on instead of fragile message heuristics.
  const err = new Error(error.message || `HTTP ${response.status}`) as Error & {
    status?: number;
    code?: string;
  };
  err.status = response.status;
  if (typeof error.code === 'string') err.code = error.code;
  throw err;
}

async function request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
  const url = `${API_BASE_URL}${endpoint}`;

  // Get API key from sessionStorage for authentication
  const apiKey = sessionStorage.getItem('openwa_api_key');

  // For FormData (file uploads) let the browser set multipart/form-data + boundary itself.
  const isFormData = options.body instanceof FormData;
  const headers: HeadersInit = {
    ...(isFormData ? {} : { 'Content-Type': 'application/json' }),
    ...(apiKey ? { 'X-API-Key': apiKey } : {}),
    ...options.headers,
  };

  const response = await fetch(url, { ...options, headers });

  if (!response.ok) {
    return handleErrorResponse<T>(response, apiKey);
  }

  if (response.status === 204) {
    return undefined as T;
  }

  return response.json();
}

/** Like {@link request} but returns the raw response text — e.g. a plugin's HTML config-UI bundle. */
async function requestText(endpoint: string): Promise<string> {
  const apiKey = sessionStorage.getItem('openwa_api_key');
  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    headers: { ...(apiKey ? { 'X-API-Key': apiKey } : {}) },
  });

  if (!response.ok) {
    return handleErrorResponse<string>(response, apiKey);
  }

  return response.text();
}

/** Like {@link request} but returns a Blob — e.g. for status media downloads. */
async function requestBlob(endpoint: string, signal?: AbortSignal): Promise<Blob> {
  const url = `${API_BASE_URL}${endpoint}`;

  // Get API key from sessionStorage for authentication
  const apiKey = sessionStorage.getItem('openwa_api_key');

  const headers: HeadersInit = {
    ...(apiKey ? { 'X-API-Key': apiKey } : {}),
  };

  const response = await fetch(url, { headers, signal });

  if (!response.ok) {
    return handleErrorResponse<Blob>(response, apiKey);
  }

  return response.blob();
}

// =============================================================================
// Session API
// =============================================================================

export const sessionApi = {
  list: () => request<Session[]>('/sessions'),
  get: (id: string) => request<Session>(`/sessions/${id}`),
  create: (name: string, options?: CreateSessionOptions) =>
    request<Session>('/sessions', {
      method: 'POST',
      body: JSON.stringify({
        name,
        ...(options?.proxyUrl ? { proxyUrl: options.proxyUrl } : {}),
      }),
    }),
  delete: (id: string) => request<void>(`/sessions/${id}`, { method: 'DELETE' }),
  getConfig: (id: string) => request<SessionConfig>(`/sessions/${id}/config`),
  // PATCH merges: only the keys sent are touched. Send null to clear one back to its default.
  updateConfig: (id: string, patch: Partial<Record<keyof SessionConfig, boolean | number | null>>) =>
    request<SessionConfig>(`/sessions/${id}/config`, {
      method: 'PATCH',
      body: JSON.stringify(patch),
    }),
  getProxy: (id: string) => request<SessionProxy>(`/sessions/${id}/proxy`),
  updateProxy: (id: string, patch: { proxyUrl?: string | null }) =>
    request<SessionProxy>(`/sessions/${id}/proxy`, {
      method: 'PATCH',
      body: JSON.stringify(patch),
    }),
  start: (id: string) => request<Session>(`/sessions/${id}/start`, { method: 'POST' }),
  stop: (id: string) => request<Session>(`/sessions/${id}/stop`, { method: 'POST' }),
  logout: (id: string) => request<Session>(`/sessions/${id}/logout`, { method: 'POST' }),
  forceKill: (id: string) => request<Session>(`/sessions/${id}/force-kill`, { method: 'POST' }),
  getQR: (id: string) => request<{ qrCode: string; status: string }>(`/sessions/${id}/qr`),
  requestPairingCode: (id: string, phoneNumber: string) =>
    request<{ pairingCode: string; status: string }>(`/sessions/${id}/pairing-code`, {
      method: 'POST',
      body: JSON.stringify({ phoneNumber }),
    }),
  getStats: () => request<SessionStats>('/sessions/stats/overview'),
  getGroups: (id: string) =>
    request<{ id: string; name?: string; linkedParentJID?: string | null }[]>(`/sessions/${id}/groups`),
  // Operator route, Baileys only: whatsapp-web.js answers 501. Participants are WhatsApp ids (`…@c.us`).
  createGroup: (id: string, name: string, participants: string[]) =>
    request<{ id: string; name: string }>(`/sessions/${id}/groups`, {
      method: 'POST',
      body: JSON.stringify({ name, participants }),
    }),
  getGroup: (id: string, groupId: string) =>
    request<GroupInfo>(`/sessions/${id}/groups/${encodeURIComponent(groupId)}`),
  // The group writes below are operator routes. Whether WhatsApp lets this account make them (an admin,
  // or any member while the group's info is unlocked) is decided by WhatsApp; a refusal answers 403.
  setGroupSubject: (id: string, groupId: string, subject: string) =>
    request<GroupAck>(`/sessions/${id}/groups/${encodeURIComponent(groupId)}/subject`, {
      method: 'PUT',
      body: JSON.stringify({ subject }),
    }),
  setGroupDescription: (id: string, groupId: string, description: string) =>
    request<GroupAck>(`/sessions/${id}/groups/${encodeURIComponent(groupId)}/description`, {
      method: 'PUT',
      body: JSON.stringify({ description }),
    }),
  setGroupPicture: (id: string, groupId: string, base64: string, mimetype: string) =>
    request<GroupAck>(`/sessions/${id}/groups/${encodeURIComponent(groupId)}/picture`, {
      method: 'PUT',
      body: JSON.stringify({ base64, mimetype }),
    }),
  addGroupParticipants: (id: string, groupId: string, participants: string[]) =>
    request<GroupParticipantsAck>(`/sessions/${id}/groups/${encodeURIComponent(groupId)}/participants`, {
      method: 'POST',
      body: JSON.stringify({ participants }),
    }),
  removeGroupParticipants: (id: string, groupId: string, participants: string[]) =>
    request<GroupParticipantsAck>(`/sessions/${id}/groups/${encodeURIComponent(groupId)}/participants`, {
      method: 'DELETE',
      body: JSON.stringify({ participants }),
    }),
  setGroupAdmins: (id: string, groupId: string, participants: string[], admin: boolean) =>
    request<GroupParticipantsAck>(
      `/sessions/${id}/groups/${encodeURIComponent(groupId)}/participants/${admin ? 'promote' : 'demote'}`,
      { method: 'POST', body: JSON.stringify({ participants }) },
    ),
  leaveGroup: (id: string, groupId: string) =>
    request<GroupAck>(`/sessions/${id}/groups/${encodeURIComponent(groupId)}/leave`, { method: 'POST' }),
  getChats: async (id: string, signal?: AbortSignal) => {
    let lastError: unknown;
    const { items, throttled } = await fetchAllPages<Chat>(
      async (limit, offset) => {
        signal?.throwIfAborted();
        try {
          const data = await request<Chat[]>(`/sessions/${id}/chats?limit=${limit}&offset=${offset}`, { signal });
          return { data, total: data.length < limit ? offset + data.length : Infinity };
        } catch (err) {
          lastError = err;
          throw err;
        } finally {
          signal?.throwIfAborted();
        }
      },
      { pageSize: 1000, maxItems: Infinity },
    );
    // A later throttled page must fail the load rather than present an incomplete sidebar.
    if (throttled) throw lastError;
    const seen = new Set<string>();
    return items.filter(chat => {
      if (seen.has(chat.id)) return false;
      seen.add(chat.id);
      return true;
    });
  },
  // `messageIds` are the messages to acknowledge. Baileys acknowledges them one by one and, without any, only the
  // newest it holds; whatsapp-web.js reads the whole chat and ignores them.
  markChatRead: (id: string, chatId: string, messageIds?: string[]) =>
    request<{ success: boolean }>(`/sessions/${id}/chats/read`, {
      method: 'POST',
      body: JSON.stringify({ chatId, ...(messageIds?.length ? { messageIds } : {}) }),
    }),
  // Both also delete the gateway's stored copy of the chat's messages (rows, media, search entries).
  clearChatMessages: (id: string, chatId: string) =>
    request<{ success: boolean }>(`/sessions/${id}/chats/${encodeURIComponent(chatId)}/messages`, {
      method: 'DELETE',
    }),
  deleteChat: (id: string, chatId: string) =>
    request<{ success: boolean }>(`/sessions/${id}/chats/delete`, {
      method: 'POST',
      body: JSON.stringify({ chatId }),
    }),
  // Archive and pin answer `{ success: false }` when the engine declined to act (WhatsApp keeps at most three
  // chats pinned), which the callers treat as a failure. Mute has no declined outcome and always answers success.
  archiveChat: (id: string, chatId: string, archive: boolean) =>
    request<{ success: boolean }>(`/sessions/${id}/chats/archive`, {
      method: 'POST',
      body: JSON.stringify({ chatId, archive }),
    }),
  pinChat: (id: string, chatId: string, pin: boolean) =>
    request<{ success: boolean }>(`/sessions/${id}/chats/pin`, {
      method: 'POST',
      body: JSON.stringify({ chatId, pin }),
    }),
  /** `muteUntil` is epoch MILLISECONDS; null unmutes. */
  muteChat: (id: string, chatId: string, muteUntil: number | null) =>
    request<{ success: boolean }>(`/sessions/${id}/chats/mute`, {
      method: 'POST',
      body: JSON.stringify({ chatId, muteUntil }),
    }),
  markChatUnread: (id: string, chatId: string) =>
    request<{ success: boolean }>(`/sessions/${id}/chats/unread`, {
      method: 'POST',
      body: JSON.stringify({ chatId }),
    }),
  // `offset` counts DB rows already fetched for this chat, never rendered rows: the thread merges
  // these with engine history, so paging by the merged length would skip DB rows. `total` is not
  // read to decide whether an older page exists — a page short of `limit` is; a chat with live
  // traffic keeps growing `total` after the fact, so comparing rows-held against it stops early.
  getChatMessages: (id: string, chatId: string, limit = 100, offset = 0) =>
    request<{ messages: ChatMessage[]; total: number }>(
      `/sessions/${id}/messages?chatId=${encodeURIComponent(chatId)}&limit=${limit}&offset=${offset}`,
    ),
  // Live history straight from WhatsApp (bypasses the DB) — backfills a thread the gateway never
  // captured, e.g. a freshly paired session whose persisted store is still empty.
  // includeMedia downloads the media payload (base64) for history messages so stickers/images/
  // video/voice render instead of collapsing to an empty timestamp-only bubble.
  getChatHistory: (id: string, chatId: string, limit = 100, includeMedia = false) =>
    request<EngineHistoryMessage[]>(
      `/sessions/${id}/messages/${encodeURIComponent(chatId)}/history?limit=${limit}${
        includeMedia ? '&includeMedia=true' : ''
      }`,
    ),
  // A message's stored media, fetched on demand. The message list carries its media inline only up to
  // MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES; past that budget the payload arrives as the
  // `{ omitted: true, sizeBytes }` marker and the bytes are only reachable here. Served as an
  // attachment (Content-Disposition), so callers download it rather than rendering it inline.
  getMessageMediaBlob: (id: string, chatId: string, messageId: string, signal?: AbortSignal) =>
    requestBlob(
      `/sessions/${id}/messages/${encodeURIComponent(chatId)}/${encodeURIComponent(messageId)}/media`,
      signal,
    ),
  getSubscribedChannels: (id: string) => request<Channel[]>(`/sessions/${id}/channels`),
  getChannelMessages: (id: string, channelId: string, limit = 50) =>
    request<ChannelMessage[]>(`/sessions/${id}/channels/${encodeURIComponent(channelId)}/messages?limit=${limit}`),
  getContactStatuses: (id: string) => request<{ statuses: StatusUpdate[] }>(`/sessions/${id}/status`),
  getStatusMediaBlob: (id: string, statusId: string, signal?: AbortSignal) =>
    requestBlob(`/sessions/${id}/status/${encodeURIComponent(statusId)}/media`, signal),
  postTextStatus: (
    id: string,
    text: string,
    recipients?: string[],
    extra?: { backgroundColor?: string; font?: number },
  ) =>
    request(`/sessions/${id}/status/send-text`, {
      method: 'POST',
      body: JSON.stringify({ text, recipients, ...extra }),
    }),
  postImageStatus: (
    id: string,
    image: { url?: string; base64?: string; mimetype?: string },
    recipients?: string[],
    caption?: string,
  ) =>
    request(`/sessions/${id}/status/send-image`, {
      method: 'POST',
      body: JSON.stringify({ image, recipients, caption }),
    }),
};

// =============================================================================
// Webhook API
// =============================================================================

export const webhookApi = {
  listBySession: (sessionId: string) => request<Webhook[]>(`/sessions/${sessionId}/webhooks`),
  listAll: () => request<Webhook[]>('/webhooks'),
  create: (sessionId: string, data: CreateWebhookRequest) =>
    request<Webhook>(`/sessions/${sessionId}/webhooks`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  update: (sessionId: string, id: string, data: UpdateWebhookRequest) =>
    request<Webhook>(`/sessions/${sessionId}/webhooks/${id}`, {
      method: 'PUT',
      body: JSON.stringify(data),
    }),
  delete: (sessionId: string, id: string) =>
    request<void>(`/sessions/${sessionId}/webhooks/${id}`, { method: 'DELETE' }),
  test: (sessionId: string, id: string) =>
    request<{ success: boolean; statusCode?: number; error?: string }>(`/sessions/${sessionId}/webhooks/${id}/test`, {
      method: 'POST',
    }),
};

// =============================================================================
// Template API
// =============================================================================

export const templateApi = {
  list: (sessionId: string) => request<MessageTemplate[]>(`/sessions/${sessionId}/templates`),
  create: (sessionId: string, data: TemplatePayload) =>
    request<MessageTemplate>(`/sessions/${sessionId}/templates`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  update: (sessionId: string, id: string, data: Partial<TemplatePayload>) =>
    request<MessageTemplate>(`/sessions/${sessionId}/templates/${id}`, {
      method: 'PUT',
      body: JSON.stringify(data),
    }),
  delete: (sessionId: string, id: string) =>
    request<void>(`/sessions/${sessionId}/templates/${id}`, { method: 'DELETE' }),
};

// =============================================================================
// Contact API
// =============================================================================

export interface CheckNumberResponse {
  number: string;
  exists: boolean;
  /** The number's WhatsApp id in the neutral `<phone>@c.us` form on both engines, or null if unregistered. */
  whatsappId: string | null;
}

export interface ProfilePictureResponse {
  /** Signed CDN URL for the contact/group picture, or null when hidden / unavailable. */
  url: string | null;
}

export const contactApi = {
  // The route caps a response at 1000 contacts; walk the pages so an address book past that is complete.
  // No item cap: the status recipient picker needs every contact, and the server's short page ends the walk.
  list: async (sessionId: string) => {
    let lastError: unknown;
    const { items, throttled } = await fetchAllPages(
      async (limit, offset) => {
        try {
          const data = await request<Contact[]>(`/sessions/${sessionId}/contacts?limit=${limit}&offset=${offset}`);
          // The route answers a bare array with no total: a short page is the last one.
          return { data, total: data.length < limit ? offset + data.length : Infinity };
        } catch (err) {
          lastError = err;
          throw err;
        }
      },
      { pageSize: 1000, maxItems: Infinity },
    );
    // A page still throttled after the retries would leave the picker silently short; fail the whole
    // load with that page's 429, as a throttled first page already does.
    if (throttled) throw lastError;
    return items;
  },
  /** The ids of the contacts this account has blocked. */
  listBlocked: (sessionId: string) => request<string[]>(`/sessions/${sessionId}/contacts/blocked`),
  block: (sessionId: string, contactId: string) =>
    request<{ success: boolean }>(`/sessions/${sessionId}/contacts/${encodeURIComponent(contactId)}/block`, {
      method: 'POST',
    }),
  unblock: (sessionId: string, contactId: string) =>
    request<{ success: boolean }>(`/sessions/${sessionId}/contacts/${encodeURIComponent(contactId)}/block`, {
      method: 'DELETE',
    }),
  /** Save the contact to the account's address book, or rename the entry it has. */
  upsert: (sessionId: string, contactId: string, firstName: string, lastName?: string) =>
    request<{ success: boolean }>(`/sessions/${sessionId}/contacts/${encodeURIComponent(contactId)}`, {
      method: 'PUT',
      body: JSON.stringify({ firstName, ...(lastName ? { lastName } : {}) }),
    }),
  checkNumber: (sessionId: string, number: string) =>
    request<CheckNumberResponse>(`/sessions/${sessionId}/contacts/check/${encodeURIComponent(number)}`),
  // Returns the contact/group profile picture URL. Both engines return null when the user hid their
  // picture or has none. The URL is a signed WhatsApp CDN link that expires in a few hours, so the
  // dashboard caches it for an hour (see useProfilePicture) and re-fetches on expiry.
  profilePicture: (sessionId: string, contactId: string) =>
    request<ProfilePictureResponse>(`/sessions/${sessionId}/contacts/${encodeURIComponent(contactId)}/profile-picture`),
  // Best-effort resolution of a contact id (e.g. an @lid privacy id) to its phone number (MSISDN
  // digits), or null when the engine can't map it. Cached a day by useResolvedPhone.
  resolvePhone: (sessionId: string, contactId: string) =>
    request<{ contactId: string; phone: string | null }>(
      `/sessions/${sessionId}/contacts/${encodeURIComponent(contactId)}/phone`,
    ),
  // Batch-resolve profile picture URLs for a whole sidebar in ONE request — the per-chat burst of
  // parallel single fetches exhausts the per-IP throttle (429s). Engine lookups run 5 at a time
  // server-side; ids beyond the backend's 50-id cap are dropped client-side too.
  profilePictures: (sessionId: string, contactIds: string[]) =>
    request<{ pictures: Record<string, string | null> }>(
      `/sessions/${sessionId}/contacts/profile-pictures?ids=${contactIds
        .slice(0, 50)
        .map(encodeURIComponent)
        .join(',')}`,
    ),
};

// =============================================================================
// API Key API
// =============================================================================

export const apiKeyApi = {
  list: () => request<ApiKey[]>('/auth/api-keys'),
  create: (data: {
    name: string;
    role: string;
    allowedIps?: string[];
    allowedSessions?: string[];
    expiresAt?: string;
    allowedChats?: string[];
  }) =>
    request<CreatedApiKey>('/auth/api-keys', {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  update: (
    id: string,
    data: {
      name?: string;
      role?: string;
      allowedIps?: string[];
      allowedSessions?: string[];
      /** null removes the expiry. */
      expiresAt?: string | null;
      allowedChats?: string[];
    },
  ) =>
    request<ApiKey>(`/auth/api-keys/${id}`, {
      method: 'PUT',
      body: JSON.stringify(data),
    }),
  delete: (id: string) => request<void>(`/auth/api-keys/${id}`, { method: 'DELETE' }),
  revoke: (id: string) => request<ApiKey>(`/auth/api-keys/${id}/revoke`, { method: 'POST' }),
};

// =============================================================================
// Audit/Logs API
// =============================================================================

export const auditApi = {
  list: (params?: { action?: string; severity?: string; limit?: number; offset?: number }) => {
    const query = new URLSearchParams();
    if (params?.action) query.set('action', params.action);
    if (params?.severity) query.set('severity', params.severity);
    if (params?.limit) query.set('limit', String(params.limit));
    if (params?.offset) query.set('offset', String(params.offset));
    const queryStr = query.toString();
    return request<{ data: AuditLog[]; total: number }>(`/audit${queryStr ? `?${queryStr}` : ''}`);
  },
};

// =============================================================================
// Message API
// =============================================================================

export const messageApi = {
  sendText: (sessionId: string, chatId: string, text: string) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/send-text`, {
      method: 'POST',
      body: JSON.stringify({ chatId, text }),
    }),
  sendMedia: (
    sessionId: string,
    chatId: string,
    mediaType: 'image' | 'video' | 'audio' | 'document',
    payload: SendMediaPayload,
  ) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/send-${mediaType}`, {
      method: 'POST',
      body: JSON.stringify({ chatId, ...payload }),
    }),
  sendLocation: (sessionId: string, data: SendLocationPayload) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/send-location`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  sendContact: (sessionId: string, data: SendContactPayload) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/send-contact`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  // Stickers take the same media body as the other send-* endpoints (base64 XOR url + mimetype).
  sendSticker: (sessionId: string, chatId: string, payload: SendMediaPayload) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/send-sticker`, {
      method: 'POST',
      body: JSON.stringify({ chatId, ...payload }),
    }),
  sendPoll: (sessionId: string, data: SendPollPayload) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/send-poll`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  forward: (sessionId: string, data: ForwardMessagePayload) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/forward`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  // Async batch: returns 202 immediately; poll getBatchStatus until a terminal status.
  sendBulk: (sessionId: string, data: SendBulkPayload) =>
    request<BulkBatchResponse>(`/sessions/${sessionId}/messages/send-bulk`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  getBatchStatus: (sessionId: string, batchId: string) =>
    request<BatchStatusResponse>(`/sessions/${sessionId}/messages/batch/${encodeURIComponent(batchId)}`),
  cancelBatch: (sessionId: string, batchId: string) =>
    request<BatchCancelResponse>(`/sessions/${sessionId}/messages/batch/${encodeURIComponent(batchId)}/cancel`, {
      method: 'POST',
    }),
  reply: (sessionId: string, data: { chatId: string; quotedMessageId: string; text: string }) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/reply`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  /**
   * Tap a choice on an inbound business button/list prompt (Baileys only).
   * `messageId` is the prompt's WhatsApp id; `buttonId` is `buttons[].id`.
   */
  clickButton: (sessionId: string, data: { chatId: string; messageId: string; buttonId: string; text?: string }) =>
    request<MessageResponse>(`/sessions/${sessionId}/messages/click-button`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  react: (sessionId: string, data: { chatId: string; messageId: string; emoji: string }) =>
    request<void>(`/sessions/${sessionId}/messages/react`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
  delete: (sessionId: string, data: { chatId: string; messageId: string; forEveryone?: boolean }) =>
    request<void>(`/sessions/${sessionId}/messages/delete`, {
      method: 'POST',
      body: JSON.stringify(data),
    }),
};

// =============================================================================
// Search API
// =============================================================================

export const searchApi = {
  search: (params: SearchParams) => {
    const query = new URLSearchParams();
    Object.entries(params).forEach(([key, value]) => {
      if (value !== undefined && value !== '') query.set(key, String(value));
    });
    return request<SearchResults>(`/search?${query.toString()}`);
  },
};

// =============================================================================
// Health & Infrastructure API
// =============================================================================

export const healthApi = {
  check: () => request<HealthStatus>('/health'),
};

export const infraApi = {
  getStatus: () => request<InfraStatus>('/infra/status'),
  getUpdateCheck: () => request<UpdateCheck>('/infra/update-check'),
  getConfig: () => request<SavedConfig>('/infra/config'),
  saveConfig: (config: SaveConfigPayload) =>
    request<{ message: string; saved: boolean; envPath: string; profiles: string[] }>('/infra/config', {
      method: 'PUT',
      body: JSON.stringify(config),
    }),
  restart: (profiles?: string[], profilesToRemove?: string[], signal?: AbortSignal) =>
    request<{
      message: string;
      restarting: boolean;
      profiles: string[];
      profilesToRemove: string[];
      estimatedTime: number;
      // Present only when Docker started or stopped built-in services; `errors` lists what failed.
      orchestration?: { errors?: string[] };
      removal?: { errors?: string[] };
    }>('/infra/restart', {
      method: 'POST',
      body: JSON.stringify({ profiles: profiles || [], profilesToRemove: profilesToRemove || [] }),
      signal,
    }),
  // Readiness, not the plain /infra/health ping. The restart poll must not be able to latch onto the
  // process it just asked to shut down: /infra/health answers 200 for the whole drain,
  // while /health/ready reports 503 as soon as draining starts and stays 503 until both databases
  // answer. Public (no API key), like /infra/health.
  healthCheck: (signal?: AbortSignal) =>
    request<{ status: 'ok' | 'error'; details: Record<string, { status: string }> }>('/health/ready', { signal }),
  // Data migration: export all Data-DB tables (call while still on the OLD database, before switching),
  // then import after the switch + restart. Used by the DB-switch migration guard so data isn't lost.
  exportData: () =>
    request<{
      exportedAt: string;
      dataDbType: string;
      tables: Record<string, unknown[]>;
      counts: Record<string, number>;
      // Optional tables absent from an older schema. Always present in the response; a non-empty
      // list means the backup is partial, not that those tables were empty.
      skippedTables: string[];
      // Inline media payloads the export budget refused. Always present; non-zero means the rows are
      // all there but some of their media is not — a state a restored archive cannot express, since
      // the omitted marker is the same one media skipped on the way in gets.
      omittedInlineMedia: { messages: number; messageBatches: number };
    }>('/infra/export-data'),
  // 200 contract includes the orphan-engine reconciliation result (restartRequired / notices /
  // stopped+failed ids). 409 has several causes and the error's `code` distinguishes them:
  // IMPORT_WOULD_ORPHAN_ENGINES (live engines exist for sessions the backup would remove; the
  // message lists them) is the only one the caller retries with stopOrphans=true to stop those
  // engines inside the request. IMPORT_ALREADY_RUNNING (another restore is in flight) and
  // IMPORT_NESTED_TRANSACTION (another transaction holds the connection) leave nothing to retry.
  // force is deliberately NOT exposed: it leaves the engines writing into the restored tables until
  // a restart — the window stopOrphans exists to close.
  importData: (tables: Record<string, unknown[]>, options?: { stopOrphans?: boolean }) =>
    request<{
      imported: boolean;
      counts?: Record<string, number>;
      message?: string;
      warnings?: string[];
      notices?: string[];
      restartRequired?: boolean;
      orphanedEngines?: string[];
      stoppedOrphanEngines?: string[];
      failedOrphanEngines?: string[];
    }>('/infra/import-data', {
      method: 'POST',
      body: JSON.stringify({ tables, ...options }),
    }),
};

// =============================================================================
// Plugin Types
// =============================================================================

/** Field definition within a plugin's config schema (mirrors the backend PluginConfigField). */
export interface PluginConfigField {
  // 'textarea' is a multi-line string; a field with `enum` renders as a <select>.
  type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'textarea';
  title?: string;
  description?: string;
  default?: unknown;
  enum?: unknown[];
  required?: boolean;
  secret?: boolean;
  min?: number;
  max?: number;
  pattern?: string;
  items?: PluginConfigField; // array element schema; array-of-rows when items.type === 'object'
  properties?: Record<string, PluginConfigField>; // nested-object fields
}

export interface PluginConfigSchema {
  type: 'object';
  properties: Record<string, PluginConfigField>;
}

export interface PluginI18nText {
  title?: string;
  description?: string;
}
export interface PluginI18nLocale {
  name?: string;
  description?: string;
  config?: Record<string, PluginI18nText>;
}
export type PluginI18n = Record<string, PluginI18nLocale>;

export interface Plugin {
  id: string;
  name: string;
  version: string;
  type: 'engine' | 'storage' | 'queue' | 'auth' | 'extension';
  description?: string;
  author?: string;
  status: 'installed' | 'enabled' | 'disabled' | 'error';
  config: Record<string, unknown>;
  builtIn: boolean;
  provides: string[];
  /** Whether this plugin can host provisioned ingress instances (drives the Instances tab). */
  ingressCapable: boolean;
  /** Declared config fields, when the plugin exposes a schema (drives the dashboard config form). */
  configSchema?: PluginConfigSchema;
  /** When set, the plugin ships a sandboxed-iframe config editor (preferred over configSchema). */
  configUi?: { entry: string; height?: number };
  /** Whether the plugin is scoped to specific sessions (false = global, always runs). */
  sessionScoped: boolean;
  /** Sessions the plugin is activated for; ['*'] = all numbers. */
  activeSessions: string[];
  /** Per-session config overrides, keyed by sessionId (secrets redacted per slice). */
  sessionConfig?: Record<string, Record<string, unknown>>;
  loadedAt?: string;
  enabledAt?: string;
  error?: string;
  i18n?: PluginI18n;
}

export interface Engine {
  id: string;
  name: string;
  enabled: boolean;
  features: string[];
  /** Underlying engine library (e.g. whatsapp-web.js 1.34.7), distinct from the adapter version. */
  library?: { name: string; version: string };
}

/** A remote catalog entry annotated with this instance's install state. */
export interface CatalogPlugin {
  id: string;
  name: string;
  version: string;
  type?: string;
  status?: string;
  description?: string;
  author?: string;
  license?: string;
  keywords?: string[];
  minOpenWAVersion?: string;
  testedOpenWAVersion?: string;
  homepage?: string;
  download?: string;
  installed: boolean;
  installedVersion: string | null;
  updateAvailable: boolean;
  i18n?: PluginI18n;
}

// =============================================================================
// Plugins API
// =============================================================================

export const pluginsApi = {
  list: () => request<Plugin[]>('/plugins'),
  get: (id: string) => request<Plugin>(`/plugins/${id}`),
  enable: (id: string) =>
    request<{ success: boolean; message: string }>(`/plugins/${id}/enable`, {
      method: 'POST',
    }),
  disable: (id: string) =>
    request<{ success: boolean; message: string }>(`/plugins/${id}/disable`, {
      method: 'POST',
    }),
  updateConfig: (id: string, config: Record<string, unknown>) =>
    request<{ success: boolean; message: string }>(`/plugins/${id}/config`, {
      method: 'PUT',
      body: JSON.stringify({ config }),
    }),
  /** Set which sessions a session-scoped plugin is activated for (['*'] = all). */
  setSessions: (id: string, sessions: string[]) =>
    request<Plugin>(`/plugins/${id}/sessions`, { method: 'PUT', body: JSON.stringify({ sessions }) }),
  /** Set (or clear, with an empty object) a plugin's config override for one session. */
  updateSessionConfig: (id: string, sessionId: string, config: Record<string, unknown>) =>
    request<{ success: boolean; message: string }>(`/plugins/${id}/config/${encodeURIComponent(sessionId)}`, {
      method: 'PUT',
      body: JSON.stringify({ config }),
    }),
  healthCheck: (id: string) => request<{ healthy: boolean; message?: string }>(`/plugins/${id}/health`),
  install: (file: File) => {
    const form = new FormData();
    form.append('file', file);
    return request<Plugin>('/plugins/install', { method: 'POST', body: form });
  },
  installFromUrl: (url: string) =>
    request<Plugin>('/plugins/install-url', { method: 'POST', body: JSON.stringify({ url }) }),
  updateFromUrl: (id: string, url: string) =>
    request<Plugin>(`/plugins/${id}/update`, { method: 'POST', body: JSON.stringify({ url }) }),
  catalog: () => request<CatalogPlugin[]>('/plugins/catalog'),
  /** Fetch a plugin's sandboxed config-UI entry HTML (the API key stays here, in the parent). */
  getConfigUi: (id: string) => requestText(`/plugins/${id}/config-ui`),
  uninstall: (id: string) => request<{ success: boolean; message: string }>(`/plugins/${id}`, { method: 'DELETE' }),
  getEngines: () => request<Engine[]>('/infra/engines'),
  getCurrentEngine: () => request<{ engineType: string }>('/infra/engines/current'),
};

// =============================================================================
// Plugin instances API (Integration Fabric provisioning; mirrors src/modules/integration)
// =============================================================================

export interface IngressUrl {
  route: string;
  url: string;
}

export interface InstanceView {
  id: string;
  pluginId: string;
  instanceId: string;
  sessionScope: string | null;
  secret: string; // '***' on reads; plaintext once on create/regenerate
  verifyToken: string | null;
  config: Record<string, unknown> | null;
  enabled: boolean;
  createdAt: string;
  updatedAt: string;
  ingressUrls: IngressUrl[];
}

export type MintedInstance = InstanceView; // same shape; `secret` carries the plaintext once

export interface CreateInstanceInput {
  instanceId: string;
  sessionScope?: string;
  verifyToken?: string;
  /** Provider-fixed webhook secret (e.g. Chatwoot's). Omit to auto-generate one (shown once). */
  secret?: string;
  config?: Record<string, unknown>;
}

export interface UpdateInstanceInput {
  enabled?: boolean;
  /** null resets a scoped instance to all sessions; omit to leave the scope unchanged. */
  sessionScope?: string | null;
  config?: Record<string, unknown>;
}

export const pluginInstancesApi = {
  list: (pluginId: string) => request<InstanceView[]>(`/integration/plugins/${pluginId}/instances`),
  create: (pluginId: string, body: CreateInstanceInput) =>
    request<MintedInstance>(`/integration/plugins/${pluginId}/instances`, {
      method: 'POST',
      body: JSON.stringify(body),
    }),
  regenerateSecret: (pluginId: string, instanceId: string) =>
    request<MintedInstance>(`/integration/plugins/${pluginId}/instances/${instanceId}/regenerate-secret`, {
      method: 'POST',
    }),
  update: (pluginId: string, instanceId: string, body: UpdateInstanceInput) =>
    request<InstanceView>(`/integration/plugins/${pluginId}/instances/${instanceId}`, {
      method: 'PATCH',
      body: JSON.stringify(body),
    }),
  remove: (pluginId: string, instanceId: string) =>
    request<void>(`/integration/plugins/${pluginId}/instances/${instanceId}`, { method: 'DELETE' }),
};

// =============================================================================
// Statistics API (mirrors src/modules/stats)
// =============================================================================

export type StatsPeriod = '24h' | '7d' | '30d';

export interface OverviewStats {
  sessions: { active: number; total: number; byStatus: Record<string, number> };
  messages: { sent: number; received: number; failed: number; today: { sent: number; received: number } };
}

export interface MessageTimeSeriesPoint {
  timestamp: string;
  sent: number;
  received: number;
}

export interface MessageStats {
  timeSeries: MessageTimeSeriesPoint[];
  byType: Record<string, number>;
  bySession: Array<{ sessionId: string; name: string; sent: number; received: number }>;
  topChats: Array<{ chatId: string; chatName?: string | null; messageCount: number }>;
}

export const statsApi = {
  getOverview: () => request<OverviewStats>('/stats/overview'),
  getMessages: (period: StatsPeriod) => request<MessageStats>(`/stats/messages?period=${period}`),
};