Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

79.6 KB
Raw Blame
// WhatsApp Engine Interface - Abstract layer for WA engines
//
// Identity contract (the engine boundary is an anti-corruption layer for WhatsApp's id dialects):
// every JID an engine EMITS in a neutral field (`from` / `to` / `chatId` / `author` / contact + chat
// `id`, etc.) is in the NEUTRAL dialect, so application code never has to know which engine produced
// it. The neutral dialect is small:
//   - `<phone>@c.us`  a user known by phone (the raw `@s.whatsapp.net` form folds into this)
//   - `<id>@g.us`     a group
//   - `<lid>@lid`     a user known ONLY by privacy id - phone genuinely unknown (a first-class state)
//   - `status@broadcast` / `<id>@newsletter` / `<id>@broadcast`  special channels
//   - never `@s.whatsapp.net`, never a `:device` suffix
// Resolution rule: prefer `@c.us` (resolve a lid to its phone when the mapping is known), fall back to
// `@lid` only when it can't be resolved. See `engine/identity/wa-id.ts` for the shared implementation.
// (Ids the engine ACCEPTS - e.g. `sendTextMessage(chatId)` - may be neutral; the adapter de-normalizes
// to its own dialect. Full inbound + outbound conformance is being rolled out per-engine.)

import type { ChatKind } from '../identity/wa-id';

export enum EngineStatus {
  DISCONNECTED = 'disconnected',
  INITIALIZING = 'initializing',
  QR_READY = 'qr_ready',
  AUTHENTICATING = 'authenticating',
  READY = 'ready',
  ACTION_REQUIRED = 'action_required',
  FAILED = 'failed',
}

export interface MessageResult {
  id: string;
  timestamp: number;
  /**
   * Display text actually sent, when it differs from the caller's input. Button clicks resolve
   * the visible label from the stored prompt when the caller omitted `text`, so the persisted
   * row can store that label instead of the raw `buttonId`.
   */
  body?: string;
}

/**
 * A send payload that can quote an earlier message, turning the send into a reply.
 *
 * Deliberately a PROPERTY on the payload rather than a parameter on the engine methods: the parity
 * gate reads call-shaped members out of this file, so a new method would demand a capability-matrix
 * row while a property demands nothing (see engine-parity.spec.ts MEMBER_RE).
 *
 * The id is engine-specific and the adapters do NOT harmonize it: whatsapp-web.js matches the
 * serialized message id, Baileys looks the raw key id up in its local store and can only quote a
 * message it has already persisted.
 */
export interface Quotable {
  /** Quote this message id in the send. Omit for a plain, unquoted send. */
  quotedMessageId?: string;
}

export interface MediaInput extends Quotable {
  mimetype: string;
  data: Buffer | string; // Buffer or base64 or URL
  /** Caller-supplied filename wins. Document sends fall back to 'file' when omitted (wwebjs first derives the URL basename); image/video/audio sends carry no filename. */
  filename?: string;
  caption?: string;
  /** Neutral WIDs (`<phone>@c.us`) to @mention in the caption. The adapter de-normalizes per engine. */
  mentions?: string[];
  /** When true, send as a WhatsApp voice note (PTT). audio-only; ignored by other media types. */
  ptt?: boolean;
}

/**
 * Engine-neutral message type. Each adapter maps its library's native message-type tokens
 * (e.g. whatsapp-web.js `chat`/`ptt`/`vcard`) to this vocabulary at the adapter boundary,
 * so no consumer outside the adapter sees engine-specific type strings. `unknown` covers any
 * type the active engine reports that doesn't map to a first-class kind.
 */
export type MessageType =
  | 'text'
  | 'image'
  | 'video'
  | 'audio'
  | 'voice'
  | 'document'
  | 'sticker'
  | 'location'
  | 'contact'
  | 'poll'
  | 'call'
  | 'revoked'
  // WhatsApp Business commerce: a customer's cart placed from the catalog, and a single product
  // card shared into a chat. Both carry the ids the commerce APIs need — see `IncomingMessage`.
  | 'order'
  | 'product'
  // A message WhatsApp deliberately withheld from linked/companion devices (e.g. high-security
  // business OTPs): the payload is absent by design, not unparseable. See `mapBaileysMessageType`.
  | 'masked'
  | 'unknown';

export interface IncomingMessage {
  id: string;
  from: string;
  to: string;
  chatId: string;
  body: string;
  type: MessageType;
  timestamp: number;
  fromMe: boolean;
  isGroup: boolean;
  /**
   * Set by an engine that applied an edit to `body` before it handed the message over: the text the message
   * arrived with. The edits that reached the message meanwhile reach the session too, and are compared with
   * this text. It equals `body` when a later edit restored that text, as the message was edited all the same,
   * and is unset when every edit repeated the text. The session removes the field before the message is
   * hooked, stored or announced.
   */
  originalBody?: string;
  /** User-facing chat kind of the conversation this message belongs to (derived from `chatId`). */
  kind: ChatKind;
  /**
   * True for a status/story broadcast (not a real conversation). Set by the adapter so engine-neutral
   * code can skip these without matching an engine-specific pseudo-JID (e.g. `status@broadcast`).
   */
  isStatusBroadcast?: boolean;
  /** WhatsApp ephemeral/disappearing-messages timer in seconds. Set per-chat on each message
   *  in the raw payload. 0 or undefined = no disappearing timer.
   *  Known values: 86400 (24h), 604800 (7d), 7776000 (90d). */
  ephemeralDuration?: number;
  /**
   * For group, status and broadcast-list messages, the WID of the sender, where `from` is the group or
   * `status@broadcast`. A broadcast-list message the account received is filed under the sender's own
   * chat on Baileys, as WhatsApp lists it, so there `chatId` and `from` name the sender and `author`
   * repeats it.
   */
  author?: string;
  /** WIDs @mentioned in the message (empty/absent when none). Surfaced for command targeting. */
  mentionedIds?: string[];
  /** Set for `call` (call_log) messages: video vs voice, and whether an incoming call went unanswered. */
  call?: { video: boolean; missed: boolean };
  /**
   * Set for `order` messages: a cart the customer placed from the business catalog. The message
   * carries no line items — `orderId` plus the single-order `token` are the correlation handle a
   * caller redeems against WhatsApp's own order lookup, which this project does not expose, so both
   * must survive to that caller. Both engines populate them.
   */
  order?: {
    orderId: string;
    /** Opaque, single-order credential. Pass through unchanged; do not log it. */
    token?: string;
  };
  /**
   * Set for `product` messages: the catalog product shared into the chat. `productId` identifies it
   * within `businessOwnerJid`'s catalog, so it resolves through the catalog routes only when that
   * catalog is the session's own. Both engines populate `productId`; the rest are best-effort.
   */
  product?: {
    productId: string;
    title?: string;
    description?: string;
    businessOwnerJid?: string;
  };
  /**
   * Set when the sender tapped a WhatsApp Business button, template quick-reply, list row, or
   * native-flow control. `id` is the stable handle the business defined on the button/row; `text`
   * is the visible label when WhatsApp still carries it (also mirrored into `body`). **Baileys
   * only**: whatsapp-web.js does not surface interactive replies as structured fields.
   */
  button?: {
    id: string;
    text?: string;
  };
  /**
   * Set on an inbound WhatsApp Business prompt that offers buttons (or list rows flattened as
   * buttons): the choices shown to the recipient. URL/call CTAs are omitted, since they are not
   * clickable via {@link IWhatsAppEngine.clickButton} and must not masquerade as button ids.
   * Distinct from {@link IncomingMessage.button}, which is set only when someone *taps* a choice.
   * **Baileys only.** Capped (count and label length) so a malformed prompt cannot bloat
   * persisted rows / webhook payloads.
   */
  buttons?: Array<{
    id: string;
    text: string;
  }>;
  /**
   * Set by the adapter when the sender is identified by a privacy id (e.g. a WhatsApp `@lid`) rather
   * than a phone number, so engine-neutral code can decide whether to attempt phone resolution without
   * matching an engine-specific JID scheme.
   */
  isLidSender?: boolean;
  /**
   * Best-effort phone number (MSISDN digits) of the sender, resolved from a privacy id when inline
   * resolution is enabled (`RESOLVE_LID_TO_PHONE`). `null` when the engine cannot map it. Only
   * populated for `isLidSender` messages.
   */
  senderPhone?: string | null;
  /** Sender contact info, best-effort from the WhatsApp Web cache. Sync fields only (no network). */
  contact?: MessageContact;
  /** Styling of a text status/story: background as `#RRGGBB`. Only set by engines that expose it. */
  backgroundColor?: string;
  /** Styling of a text status/story: the WhatsApp font index. Only set by engines that expose it. */
  font?: number;
  poll?: PollDetails;
  media?: {
    mimetype: string;
    filename?: string;
    data?: string; // base64; absent when the payload was omitted (see `omitted`)
    /** True when the media blob was dropped: a size cap, a timeout, a disabled download, or a failed one. */
    omitted?: boolean;
    /** Decoded byte size of the media; always set when `omitted` is true. */
    sizeBytes?: number;
  };
  quotedMessage?: {
    id: string;
    body: string;
  };
  location?: {
    latitude: number;
    longitude: number;
    description?: string;
    address?: string;
    url?: string;
  };
}

/**
 * Synchronous (already-resolved, no network call) fields of a sender contact, surfaced on
 * {@link IncomingMessage}. Async getters (profile pic / about / formatted number) are intentionally
 * NOT included — they hit WhatsApp servers per message and risk rate-limit/ban. All optional; a key
 * is present only when the engine populated it.
 */
export interface MessageContact {
  /** Sender JID (`…@c.us` or a `…@lid` privacy id). */
  id?: string;
  /** Phone digits, best-effort. For `@lid` senders the authoritative number is `IncomingMessage.senderPhone`. */
  number?: string;
  name?: string;
  pushName?: string;
  shortName?: string;
  /** whatsapp-web.js contact type token. */
  type?: string;
  /** Saved in the account's address book. */
  isMyContact?: boolean;
  /** Is a WhatsApp user. */
  isWAContact?: boolean;
  isBusiness?: boolean;
  isEnterprise?: boolean;
  /** Business verified name. */
  verifiedName?: string;
  /** Business verification level. */
  verifiedLevel?: number;
  isBlocked?: boolean;
  /** Label IDs (CRM). Names are not resolved — that would need a network call. */
  labels?: string[];
}

export interface Contact {
  id: string;
  name?: string;
  pushName?: string;
  number: string;
  isMyContact: boolean;
  isBlocked: boolean;
  profilePicUrl?: string;
}

export interface Group {
  id: string;
  name: string;
  participantsCount?: number;
  isAdmin?: boolean;
  /** JID of the parent community this group is linked to, or null if standalone. */
  linkedParentJID?: string | null;
}

export interface GroupParticipant {
  id: string;
  number: string;
  name?: string;
  isAdmin: boolean;
  isSuperAdmin: boolean;
}

/**
 * Outcome of a group membership write (add/remove/promote/demote) for ONE participant. Engines
 * that report per-participant results map them verbatim (whatsapp-web.js `addParticipants` resolves
 * a `{[participantId]: {code, message}}` object; Baileys `groupParticipantsUpdate` resolves a
 * `[{status, jid}]` array).
 *
 * whatsapp-web.js remove/promote/demote confirm only the batch, but an install-time patch
 * (`scripts/patch-wwebjs-participant-arity.js`) makes the page report which requested ids resolved
 * to actual members, so those entries are per-participant too: an id the page dropped is reported
 * `404` rather than confirmed. On a tree where that patch was not applied the marker is absent and
 * the adapter falls back to one batch-confirmed entry per requested participant, which is all the
 * library reports there.
 *
 * `status` is the engine's own code when it reported one (e.g. 200 ok, 403 invite-only/not-admin,
 * 404 not registered or not a member, 409 already a member).
 */
export interface ParticipantOperationResult {
  /** Neutral participant id the outcome belongs to. */
  id: string;
  /** True only when the engine confirmed the change for THIS participant. */
  success: boolean;
  /** Engine-reported status code, when it gave one. */
  status?: number;
  /** Engine-reported human-readable reason, when it gave one. */
  message?: string;
}

/**
 * Who may add participants to a group. Neutral vocabulary: the engines disagree on how they encode
 * this — Baileys uses a boolean where `true` means everyone, whatsapp-web.js carries WhatsApp's own
 * `'all_member_add'`/`'admin_add'` strings (despite typing the field as a boolean with the opposite
 * sense) — so adapters normalise to this on the way out and de-normalise on the way in.
 */
export type GroupMemberAddMode = 'all' | 'admins';

export interface GroupInfo {
  id: string;
  name: string;
  description?: string;
  owner?: string;
  createdAt?: number;
  participants: GroupParticipant[];
  isReadOnly?: boolean;
  isAnnounce?: boolean;
  /** Only admins can send messages (the WhatsApp "announce" group setting). */
  announce?: boolean;
  /** Only admins can edit group info — subject, description, picture (the WhatsApp "locked"/restrict setting). */
  locked?: boolean;
  /** Disappearing-messages timer in seconds; 0 or undefined = off. */
  ephemeralSeconds?: number;
  /** Who may add participants. Undefined when the engine did not report it. */
  memberAddMode?: GroupMemberAddMode;
  /** JID of the parent community this group is linked to, or null if standalone. */
  linkedParentJID?: string | null;
}

/**
 * What an invite code discloses about a group BEFORE joining it.
 *
 * Deliberately not `GroupInfo`: that carries a participant list, and a non-member has no such list —
 * WhatsApp discloses at most a count. Reusing it would force an empty array that reads as "this
 * group has no members", which is a different and wrong claim.
 */
export interface GroupJoinInfo {
  id: string;
  name: string;
  description?: string;
  owner?: string;
  /** Unix seconds the group was created, when the engine reports it. */
  createdAt?: number;
  /** How many members, when disclosed. There is no list to give — you are not in the group yet. */
  participantCount?: number;
}

/** How a join request was made. Neutral vocabulary; both engines' tokens map onto it. */
export type GroupMembershipRequestMethod = 'invite_link' | 'non_admin_add' | 'linked_group_join';

/**
 * One pending request to join a group that has join-approval turned on. Mapped at the adapter
 * boundary from engine shapes that disagree on everything: whatsapp-web.js resolves raw
 * page-context store objects (wid objects, PascalCase method tokens), Baileys bare wire attrs
 * (engine-dialect jids, snake_case tokens, stringly timestamps). Fields the engine did not report
 * are omitted rather than defaulted.
 */
export interface GroupMembershipRequest {
  /** Neutral id of the user asking to join. */
  participantId: string;
  /** Who created the request when the engine reports it (differs from the requester on a non-admin add). */
  addedById?: string;
  /** How the request was made, when the engine reports a token this shape models. */
  method?: GroupMembershipRequestMethod;
  /** Unix seconds the request was created, when the engine reports it. */
  requestedAt?: number;
}

/**
 * A caller-supplied link preview, used instead of fetching one.
 *
 * Nothing is fetched for these: the caller states the metadata, so the gateway makes no outbound
 * request at all — which also means a preview can be attached for a URL this server could not reach.
 */
export interface CustomLinkPreview {
  /** The URL as it appears in the message text; WhatsApp anchors the preview to it. */
  url: string;
  /** Required — WhatsApp will not render a preview without one. */
  title: string;
  description?: string;
}

export interface ContactCard extends Quotable {
  name: string;
  number: string;
}

export interface LocationInput extends Quotable {
  latitude: number;
  longitude: number;
  description?: string;
  address?: string;
}

/** Poll choices as received from the engine, without vote counts. */
export interface PollDetails {
  name: string;
  options: string[];
  allowMultipleAnswers: boolean;
}

export interface PollInput extends Quotable {
  /** Poll question / title. */
  name: string;
  /** Options to vote on (WhatsApp accepts between 2 and 12). */
  options: string[];
  /** When true a voter can pick several options; default is single choice. */
  allowMultipleAnswers?: boolean;
}

export interface ReactionSender {
  senderId: string;
  emoji: string;
  timestamp: number;
}

export interface MessageReaction {
  emoji: string;
  senders: ReactionSender[];
}

// Phase 3: Labels (WhatsApp Business)
export interface Label {
  id: string;
  name: string;
  hexColor: string;
}

/**
 * A label to create or update. Keyed on a CALLER-SUPPLIED id, because that is exactly what the
 * underlying operation is: WhatsApp's app-state carries one `label_edit` write indexed by label id,
 * and whether it creates or updates depends only on whether that id already exists. There is no
 * server-assigned id to hand back, so inventing one here would be inventing a contract the protocol
 * does not have — and could silently overwrite an existing label.
 */
export interface LabelInput {
  id: string;
  name?: string;
  /**
   * WhatsApp's colour INDEX (0-19), not a hex value. Deliberately not the `hexColor` the read path
   * returns: neither library exposes the index-to-hex mapping — whatsapp-web.js passes hex straight
   * through from the WA Web store and Baileys only ever speaks in indices — so a translation table
   * here would be guesswork that silently sets the wrong colour.
   */
  color?: number;
}

// Phase 3: Status/Stories
export interface Status {
  id: string;
  contact: {
    id: string;
    name?: string;
    pushName?: string;
  };
  /**
   * `voice` covers an audio status posted as a voice note (PTT). It was added alongside voice status
   * posting; before that a voice status read back as `text`, since anything that was not an image or
   * a video collapsed to it.
   */
  type: 'text' | 'image' | 'video' | 'voice';
  caption?: string;
  mediaUrl?: string;
  /** Downloaded media bytes for an image/video status, when the engine fetched them (see `capInboundMediaFor`). */
  media?: IncomingMessage['media'];
  backgroundColor?: string;
  font?: number;
  timestamp: Date;
  expiresAt: Date;
}

export interface StatusPostOptions {
  /**
   * Neutral JIDs (@c.us / @lid) permitted to see the status. Maps to Baileys statusJidList.
   * REQUIRED on the Baileys engine (it rejects an absent/empty list with a 400); ignored by
   * whatsapp-web.js, which broadcasts to the account's status-privacy audience.
   */
  recipients?: string[];
  /** Hex background colour (#RRGGBB). Honoured on text and voice statuses (Baileys engine). */
  backgroundColor?: string;
  /** Font index. Honoured on text and voice statuses (Baileys engine). */
  font?: number;
  /** Caption. Image/video status only. */
  caption?: string;
}

export interface StatusResult {
  statusId: string;
  timestamp: Date;
  expiresAt: Date;
}

// Phase 3: Channels/Newsletter
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;
}

// Phase 3: Catalog (WhatsApp Business)
export interface Catalog {
  id: string;
  name: string;
  description?: string;
  productCount: number;
  url: string;
}

export interface Product {
  id: string;
  name: string;
  description?: string;
  /** Absent when the catalog item carries no price. */
  price?: number;
  /** Absent when the catalog item carries no currency. */
  currency?: string;
  /** Present only when price is. */
  priceFormatted?: string;
  imageUrl?: string;
  url: string;
  isAvailable: boolean;
  retailerId?: string;
}

export interface ProductQueryOptions {
  page?: number;
  limit?: number;
}

export interface PaginatedProducts {
  products: Product[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
}

/**
 * Lightweight summary of a chat, exposed to the dashboard's real-time chats view.
 * Only library-agnostic primitives are leaked here; raw whatsapp-web.js objects are
 * mapped to this shape inside the adapter.
 */
export interface ChatSummary {
  id: string;
  name: string;
  isGroup: boolean;
  /** User-facing chat kind. `isGroup` is retained for back-compat; `kind` is the full discriminator. */
  kind: ChatKind;
  unreadCount: number;
  timestamp: number;
  lastMessage?: string;
  /** Engine-neutral type of the last message, when available. */
  lastMessageType?: MessageType;
  /** Archived state, as set via `POST /sessions/{sessionId}/chats/archive`. */
  archived: boolean;
  /** Pinned state, as set via `POST /sessions/{sessionId}/chats/pin`. */
  pinned: boolean;
  /**
   * Muted state, as set via `POST /sessions/{sessionId}/chats/mute`. The verdict a caller needs to
   * label a mute/unmute control: whatsapp-web.js derives `Chat.isMuted` itself, and Baileys compares
   * a persisted `muteEndTime` (epoch milliseconds) against now. `muteExpiration` carries the instant.
   */
  muted: boolean;
  /**
   * Epoch MILLISECONDS at which the mute ends, present only when `muted` is true; `0` means muted
   * indefinitely. Milliseconds is the same unit as `POST /sessions/{sessionId}/chats/mute`
   * `muteUntil`, so a FINITE value can be written straight back (`mute-chat.dto.ts` documents that
   * unit and why a seconds value is a trap). The `0` an indefinite mute reports is the exception:
   * `muteUntil` requires a real future instant, so re-apply an indefinite mute with a far-future
   * timestamp rather than `0`.
   */
  muteExpiration?: number;
}

/**
 * Engine-neutral chat presence state. `typing`/`recording` show the indicator to the chat;
 * `paused` clears it. Best-effort: engines without a presence concept may no-op.
 */
export type ChatState = 'typing' | 'recording' | 'paused';

/**
 * Which kind of call a generated link opens. `audio` is the neutral spelling; Baileys uses the same
 * word, whatsapp-web.js calls it `voice`, and WhatsApp's own URL path is `/voice/`.
 */
export type CallLinkType = 'audio' | 'video';

/**
 * Engine-neutral message delivery status. Each adapter maps its native delivery signal
 * (e.g. whatsapp-web.js MessageAck integers, Baileys WAMessageStatus) to this vocabulary,
 * so no consumer outside the adapter sees engine-specific ack codes.
 */
export type DeliveryStatus = 'pending' | 'sent' | 'delivered' | 'read' | 'failed';

/**
 * Structured payload for a remotely-revoked ("deleted for everyone") message.
 * The engine layer never emits a localized display string; `body` is intentionally
 * empty and the dashboard renders the localized "message deleted" text.
 */
export interface RevokedMessage {
  id: string;
  /**
   * Serialized id of the ORIGINAL message that was deleted (when available).
   *
   * This is the reliable cross-engine field for reconciling the deleted message in
   * your own storage — both adapters populate it with the original message id:
   *  - whatsapp-web.js: `id` is the revocation NOTIFICATION (a distinct message), so
   *    `id !== revokedId`. `revokedId` may be undefined when the original is not in
   *    the local store.
   *  - Baileys: the revoke arrives as a protocolMessage whose key already points at
   *    the original, so `id === revokedId`.
   *
   * Consumers should match on `revokedId` (falling back to `id`) rather than `id`.
   */
  revokedId?: string;
  chatId: string;
  from: string;
  to: string;
  type: 'revoked';
  body: '';
  timestamp: number;
}

export interface EditedMessage {
  messageId: string;
  chatId: string;
  body: string;
  senderId: string;
  from: string;
  to: string;
  fromMe: boolean;
  isGroup: boolean;
  type: MessageType;
  hasMedia: boolean;
  /** For group messages, the participant that authored the edited message. */
  author?: string;
  /** WIDs mentioned by the edited message's latest content. */
  mentionedIds?: string[];
  /** Unix seconds when the edit occurred (not the original message creation time). */
  timestamp: number;
}

/** A guest's answer to a WhatsApp event invitation (the "Going" / "Not going" / "Maybe" buttons). */
export type EventResponseKind = 'going' | 'not_going' | 'maybe' | 'unknown';

/**
 * One RSVP to a WhatsApp event (the calendar-style event created from the attach menu). WhatsApp
 * encrypts each RSVP with a key derived from the event creation message's `messageSecret`, so an
 * engine can only report the answers to events whose creation message it holds. A guest who changes
 * their answer produces a new RSVP; the one with the latest `timestamp` per `responderId` is the
 * current state.
 */
export interface EventResponseEvent {
  /** Id of the event creation message the RSVP answers. */
  eventMessageId: string;
  /** Neutral id of the chat the event was posted in. */
  chatId: string;
  /** Neutral id of the guest who answered (the account itself when it answered from its phone). */
  responderId: string;
  /** The responder's saved name and profile name, when the session knows either. */
  contact?: { name?: string; pushName?: string };
  /** True when the account itself answered (from its phone). */
  fromMe: boolean;
  response: EventResponseKind;
  /** Extra guests the responder said they are bringing; absent when WhatsApp sent none. */
  extraGuestCount?: number;
  /** The event's name, when the creation message is available to read it from. */
  eventName?: string;
  /** Id of the RSVP message itself; unique per answer, so a changed answer has a new one. */
  responseMessageId: string;
  /** Unix seconds the guest answered (sender clock). */
  timestamp: number;
}

export interface ReactionEvent {
  messageId: string;
  chatId: string;
  reaction: string;
  senderId: string;
}

/**
 * A voter's current selection on a poll (the native poll sent with `send-poll` or from the phone).
 * WhatsApp sends the whole selection each time a voter changes it, so the latest `timestamp` per
 * `voterId` is the current state, and an empty `selectedOptions` means the voter cleared their vote.
 */
export interface PollVoteEvent {
  /** Id of the poll creation message the vote belongs to. */
  pollMessageId: string;
  /** Neutral id of the chat the poll was posted in. */
  chatId: string;
  /** Neutral id of the voter (the account itself when it voted from its phone). */
  voterId: string;
  /**
   * The option texts now selected, exactly as they appear on the poll (the same strings `vote-poll`
   * takes). An option the engine could not name is left out.
   */
  selectedOptions: string[];
  /** The poll's question, when the creation message is available to read it from. */
  pollName?: string;
  /** Unix seconds the voter changed the selection (sender clock). */
  timestamp: number;
  /**
   * The same instant in Unix milliseconds. Two changes of one voter within a second share `timestamp`, so
   * this is what orders them and tells them apart.
   */
  timestampMs: number;
}

/**
 * A group membership or metadata change, mapped at the adapter boundary to this neutral
 * shape so consumers never see engine-specific payloads:
 *  - whatsapp-web.js: `group_join` / `group_leave` / `group_update` /
 *    `group_membership_request` (GroupNotification).
 *  - Baileys: `group-participants.update` (add/remove only — promote/demote are not
 *    surfaced), `groups.update` (subject/desc/announce/restrict), `groups.upsert` (this
 *    session added to or joining a group; participantIds is the session's own id) and `group.join-request`
 *    (action 'created' only — the wwebjs event has no revoke/reject counterpart, so only
 *    the shared signal is surfaced; rc14 itself emits the event only for non-admin-add
 *    requests — the direct self-request stub 144 is unhandled upstream, marked TODO at
 *    Utils/process-message.js:569 — so an invite-link self-request may not fire on Baileys).
 * All ids are in the neutral dialect (`@g.us` / `@c.us`; a lid stays `<id>@lid` when the
 * lid->phone mapping is unknown).
 */
export interface GroupEvent {
  kind: 'join' | 'leave' | 'update' | 'join_request';
  /** Neutral group id (`@g.us`). */
  groupId: string;
  /** Who performed the action, neutral user id when the engine reports one. */
  actorId?: string;
  /** Affected users (join/leave), or the users asking to join (join_request), neutral ids. Empty for metadata updates. */
  participantIds: string[];
  /** Metadata delta for kind 'update'; absent or partially populated for join/leave. */
  changes?: { subject?: string; description?: string; announce?: boolean; locked?: boolean };
  /** Unix seconds when the change occurred (engine timestamp when available, else receipt time). */
  timestamp: number;
}

/**
 * An incoming (ringing) call, mapped at the adapter boundary to this neutral shape:
 *  - whatsapp-web.js: the client `call` event (the adapter caches the ringing call id so a repeated
 *    signal for the same call is not announced twice).
 *  - Baileys: the `call` event's `offer` status entries (other statuses are lifecycle updates and
 *    are not surfaced).
 * All ids are in the neutral dialect (`@c.us`; a lid caller stays `<id>@lid` when the lid->phone
 * mapping is unknown, resolved via the inline phone twin when the engine provides one).
 */
export interface IncomingCallEvent {
  /** Engine call id; the id `rejectCall` accepts while the call is still ringing (Baileys). */
  callId: string;
  /** Neutral caller id. */
  from: string;
  isVideo: boolean;
  isGroup: boolean;
  /** Unix seconds when the call was created (engine timestamp). */
  timestamp: number;
}

/**
 * A restriction WhatsApp itself has placed on the account behind a session — as opposed to a
 * connection fault, a stale credential, or an operator action.
 *
 * The two engines report genuinely different things, so `kind` is the discriminator consumers act
 * on rather than a lowest common denominator:
 *
 *  - `reachout_timelock` (Baileys) — the account stays connected and existing chats keep working;
 *    WhatsApp only blocks *starting new conversations*. Reported first-class by the library
 *    (`connection.update.reachoutTimeLock`), including when it is lifted.
 *  - `tos_block` / `proxy_block` (whatsapp-web.js) — a connection-level refusal: WhatsApp Web drops
 *    the socket and the engine cannot stay linked at all. Derived from the `WAState` the library
 *    reports on its `disconnected` event, which is the only channel that carries it.
 *
 * That difference is load-bearing for clearing: a `reachout_timelock` can only be resolved by an
 * explicit lift signal, whereas a connection-scoped kind is disproved the moment the session reaches
 * READY again — the block would have prevented that.
 */
export interface AccountRestriction {
  kind: 'reachout_timelock' | 'tos_block' | 'proxy_block';
  /**
   * The engine's own token for the cause, kept verbatim so an operator can search for it and so a
   * new upstream value is surfaced rather than flattened: the `WAState` string on whatsapp-web.js
   * (`TOS_BLOCK`, `SMB_TOS_BLOCK`, `PROXYBLOCK`) or the enforcement type on Baileys (`BIZ_QUALITY`,
   * `WEB_COMPANION_ONLY`, one of the BIZ_COMMERCE_VIOLATION_* values, …).
   */
  code: string;
  /** Unix ms when enforcement ends, when the engine states it (Baileys timelocks only). */
  expiresAt?: number;
}

/**
 * Neutral presence states, matching what WhatsApp itself distinguishes: whether the contact is
 * reachable, and whether they are actively typing or recording in the chat being watched.
 */
export type PresenceState = 'available' | 'unavailable' | 'composing' | 'recording' | 'paused';

/** One participant's presence within a chat. */
export interface ParticipantPresence {
  /** Neutral participant id. In a 1:1 chat this is the chat's own id. */
  id: string;
  state: PresenceState;
  /**
   * Unix SECONDS the contact was last seen, when WhatsApp discloses it. Absent for contacts whose
   * privacy settings hide last-seen — which is the common case, not an error.
   */
  lastSeen?: number;
}

/**
 * Presence in one chat. A group reports every participant WhatsApp chose to tell us about, so this
 * is a list rather than a single state even for a 1:1 chat, where it holds exactly one entry.
 */
export interface PresenceUpdateEvent {
  chatId: string;
  participants: ParticipantPresence[];
  /** How many group members are online, when the engine reports it (groups only). */
  groupOnlineCount?: number;
}

/**
 * How a ringing call ended.
 *
 * `terminate` is deliberately NOT mapped to an outcome. WhatsApp uses it both for a caller hanging
 * up before the call was answered and for either side ending an answered one, and the event carries
 * nothing that separates the two — reporting it as either would be wrong half the time. Telling
 * those apart needs call-duration tracking, which is its own piece of work.
 */
export type CallOutcome = 'accepted' | 'rejected' | 'missed';

/**
 * A call that was ringing has ended.
 *
 * The engines report the outcome but not WHO caused it: an accept can come from any of the account's
 * linked devices, and a reject can equally be the account declining or WhatsApp giving up. So this
 * says what happened to the call, never who did it.
 */
export interface CallOutcomeEvent {
  /** The same id the matching `onCall` offer carried. */
  callId: string;
  /** Neutral caller id. */
  from: string;
  outcome: CallOutcome;
  isVideo: boolean;
  isGroup: boolean;
  /** Unix seconds the outcome was reported (engine timestamp). */
  timestamp: number;
}

/** What one recipient did with an outgoing message. `played` applies to voice notes and view-once media. */
export type MessageReceiptStatus = 'delivered' | 'read' | 'played';

/**
 * One recipient's receipt for a message the account sent (group and status messages, where WhatsApp
 * reports each participant separately). Receipts from the account's own linked devices are dropped
 * by the adapter, so `participant` is always someone else.
 */
export interface MessageReceiptEvent {
  messageId: string;
  /** Neutral id of the chat the message was sent to (the group, or `status@broadcast`). */
  chatId: string;
  /** Neutral id of the recipient the receipt came from. */
  participant: string;
  status: MessageReceiptStatus;
  /** Unix seconds the recipient reached this status (engine timestamp). */
  timestamp: number;
}

/**
 * A message's place in its session from the moment it arrives until its row is written (see
 * `EngineEventCallbacks.admitInbound`). The engine hands it back with the message it emits.
 */
export interface InboundTicket {
  /**
   * Room for one downloaded payload: true once granted, false when the message asked for none, or
   * when no room came free in time (the media then goes out with the omitted marker, undownloaded).
   * Call it right before the download, never earlier: the grant is held until the row is written.
   */
  reserve: () => boolean | Promise<boolean>;
  /** Keep the room until `p` settles too: work on the payload that may outlive the emit. */
  holdUntil: (p: Promise<unknown>) => void;
  /** The message will not be emitted: release its turn and its room. A no-op after the emit. */
  drop: () => void;
  /**
   * Whether the session recorded a delete for everyone of this message while holding it, so emitting
   * it stores the row cleared and announces nothing. False for a revoke the session never saw.
   */
  readonly revoked: boolean;
}

/**
 * What the session made of a message handed to `EngineEventCallbacks.onMessage`, for an engine that
 * keeps its own copy of messages keyed by id. An engine that keeps none ignores it.
 */
export interface InboundOutcome {
  /**
   * The session already holds a different message under this id (another chat, another side of the
   * conversation, or another author), so the delivery was dropped as a duplicate. The engine's copy
   * under that id is this delivery's, not the message the session holds, and must not stand in for it.
   * Left out for a delivery that landed and for one the session cannot prove is another message.
   */
  conflict?: boolean;
}

/**
 * The session's answer to `onMessage`, for an engine that wants to know what became of the message.
 * Wrapped rather than a bare promise: most engines ignore it, and a promise nobody awaits reads as a
 * mistake wherever a callback is called.
 */
export interface InboundReceipt {
  /** Settles once the message's row is settled, with what became of it; never rejects. */
  settled: Promise<InboundOutcome | undefined>;
}

export interface EngineEventCallbacks {
  onQRCode?: (qr: string) => void;
  onReady?: (phone: string, pushName: string) => void;
  /**
   * Set only where a downloaded payload outlives the emit (PostgreSQL writes asynchronously). The
   * engine calls it synchronously as each live message arrives, in arrival order, and passes the
   * ticket to the emit, or drops it when the message is not emitted. `needsRoom` says whether the
   * message will download media; `status` marks a status post. Undefined when the engine is stale.
   */
  admitInbound?: (arrival: {
    id: string;
    chatId: string;
    needsRoom: boolean;
    status: boolean;
    /** Whether the account itself sent it. Left out where the engine cannot say before it maps the message. */
    fromMe?: boolean;
    /** The neutral id of the sender behind a group, status or list message, as `IncomingMessage.author`. */
    author?: string;
  }) => InboundTicket | undefined;
  /**
   * Fired for each received message. The session may answer with a receipt for what it makes of the
   * message once its row is settled (see {@link InboundReceipt}); the engine never holds the message back
   * for it. A change aimed at that message waits for the receipt only when it reads as foreign to the
   * copy the engine holds under its id; one from that copy's own chat and author is not delayed. A receipt
   * that fails, or is still unsettled after minutes, is let go of. No receipt comes for a message the
   * session skips as ephemeral, nor for one the engine does not emit because its sender deleted it while
   * it was processed and nothing holds it from its arrival (SQLite): the engine's copy of such a message
   * that reuses another message's id is not reported as a conflict, and stays.
   */
  onMessage?: (message: IncomingMessage, ticket?: InboundTicket) => void | InboundReceipt;
  /**
   * Fired for messages the account itself created (outgoing) — including sends composed on a
   * linked phone, which the `message`/`onMessage` event never delivers. Used to emit `message.sent`.
   */
  onMessageCreate?: (message: IncomingMessage, ticket?: InboundTicket) => void;
  /**
   * Fired when the delivery status of an outgoing message advances. The adapter maps its native
   * delivery signal to the neutral `DeliveryStatus`, so consumers never see engine-specific codes.
   * `chatId` is the conversation the acked message belongs to, canonicalized the same way the
   * inbound mappers canonicalize `IncomingMessage.chatId`; undefined when the engine's update
   * carries no chat, and the emitted payload then omits the field rather than guess.
   */
  onMessageAck?: (messageId: string, status: DeliveryStatus, chatId?: string) => void;
  /**
   * Fired once per recipient as each one receives, reads or plays a message the account sent to a
   * group or status. Baileys only: whatsapp-web.js has no per-participant receipt event.
   */
  onMessageReceipt?: (event: MessageReceiptEvent) => void;
  /**
   * `actor.fromMe` says whether the account itself made the revoke (from its phone). Only an engine that
   * receives the raw protocol message can say; whatsapp-web.js leaves it out.
   */
  onMessageRevoked?: (message: RevokedMessage, actor?: { fromMe: boolean }) => void;
  onMessageReaction?: (event: ReactionEvent) => void;
  onMessageEdited?: (message: EditedMessage) => void;
  /**
   * Fired for each RSVP to a WhatsApp event (consumers emit `event.response`). Baileys only: it
   * decrypts the RSVP itself from the stored event creation message. whatsapp-web.js never fires it.
   */
  onEventResponse?: (event: EventResponseEvent) => void;
  /**
   * Fired each time a voter changes their selection on a poll (consumers emit `poll.vote`).
   * whatsapp-web.js only: Baileys never fires it.
   */
  onPollVote?: (event: PollVoteEvent) => void;
  /**
   * Fired on group membership changes (join/leave), group metadata updates
   * (subject/description/announce/locked), and pending join requests. The `kind` selects the
   * consumer event name (`group.join` / `group.leave` / `group.update` / `group.join_request`).
   */
  onGroupEvent?: (event: GroupEvent) => void;
  /**
   * Fired when an incoming call starts ringing (consumers emit `call.received`). On Baileys the call
   * can be rejected via `rejectCall(callId)` only while it is still ringing: the adapter keeps what
   * the rejection needs cached for that window. whatsapp-web.js refuses `rejectCall`.
   */
  onCall?: (event: IncomingCallEvent) => void;
  /**
   * Bulk historical messages from an engine's initial sync (e.g. Baileys `messaging-history.set`).
   * They predate the live session, so consumers persist them for the chat view but must not dispatch.
   * An async consumer may return stored revocations to keep previews cleared across resyncs.
   */
  onHistoryMessages?: (messages: IncomingMessage[]) => void | Promise<IncomingMessage[] | void>;
  onDisconnected?: (reason: string) => void;
  /**
   * Fired each time the engine schedules an INTERNAL reconnect attempt: a drop it retries on its own
   * and deliberately does NOT report through `onDisconnected`, because the session is still linked and
   * the credentials are still good. Purely informational, so a consumer must not tear anything down on
   * it; the engine keeps owning the retry.
   *
   * `attempt` is the 1-based number of the attempt being scheduled. An engine may carry it across a
   * short-lived connection, so a link that drops right after opening keeps climbing the backoff; it
   * resets on a scan, when a QR window runs out, or once no drop has occurred for the engine's
   * stability window. An episode can therefore start at attempt > 1 after a brief READY, so a
   * consumer should treat the first attempt after a READY, not only attempt 1, as a new episode.
   * The close that ends an unscanned QR window is not a reconnect and is never reported; any other
   * close while a QR waits is.
   * `nextDelayMs` is how long the engine waits before making it. Together they are what a consumer
   * needs to tell a one-second blip from a session that has been down for an hour, which the status
   * alone cannot: the engine reports INITIALIZING for the whole episode, exactly as it does for a
   * session that has never been paired.
   *
   * Optional: an engine that hands every drop to its consumer instead of retrying internally
   * (whatsapp-web.js does) simply never invokes this, because that consumer already has the drop.
   */
  onReconnecting?: (attempt: number, nextDelayMs: number) => void;
  onStateChanged?: (state: EngineStatus) => void;
  /**
   * Fired when the engine needs an operator action to keep the session healthy — currently only the
   * whatsapp-web.js onboarding-modal fallback (#982): a new account shows a "What's new" modal after
   * linking that must be acknowledged, and the adapter dismisses it automatically; this fires only if
   * that dismissal fails, so a headless deployment is told (rather than left to be logged out ~5m
   * later). The engine has already moved to ACTION_REQUIRED; `reason` carries a human-readable cause.
   * Distinct from `onError` (terminal) and `onDisconnected` (recoverable): it does NOT clear on its
   * own — once the operator has acted, the session must be restarted (stop, then start) to return
   * to READY.
   */
  onActionRequired?: (reason: string) => void;
  /**
   * Fired when the engine learns that WhatsApp has restricted (or un-restricted) the account behind
   * this session. `null` means the engine positively reports no restriction in force — it is a
   * *lift*, not "unknown", so consumers may clear state on it; an engine that simply never learns
   * anything stays silent instead.
   *
   * Purely informational: the adapter does NOT change its own status or reconnect behavior because
   * of a restriction, so this cannot turn a recoverable session into a dead one on a misread.
   * Consumers decide what a restriction is worth.
   */
  onAccountRestriction?: (restriction: AccountRestriction | null) => void;
  /**
   * Fired when WhatsApp reports presence for a chat this session subscribed to. Push-only and
   * unsolicited after the subscription: there is no way to ask for a contact's presence on demand,
   * which is why consumers keep the last reported state rather than querying for it.
   */
  onPresenceUpdate?: (event: PresenceUpdateEvent) => void;
  /**
   * Fired when a call that was ringing ends — answered, declined, or never picked up. Distinct from
   * `onCall`, which announces the ring itself: an outcome must never re-enter that path, or a call
   * being declined would look like a fresh incoming call and (with auto-reject on) be answered.
   */
  onCallOutcome?: (event: CallOutcomeEvent) => void;
  /**
   * Fired on a terminal initialization/authentication failure (e.g. Chromium
   * could not launch, or WhatsApp rejected the stored credentials). The engine
   * has already moved to FAILED; `reason` carries a human-readable cause that
   * callers may surface to operators. Distinct from `onDisconnected`, which is
   * recoverable and triggers reconnection.
   */
  onError?: (reason: string) => void;
  /**
   * Fired SYNCHRONOUSLY the instant a credential-teardown operation begins — i.e. the moment the
   * adapter kicks off the call that ends in an `fs.rm` of this session's on-disk WhatsApp auth
   * directory. The argument is the SAME promise the adapter is about to await (or, for a
   * WhatsApp-originated unlink, a promise the adapter controls that represents the same rm).
   *
   * Unlike the other callbacks, this one is NOT guarded on the engine still being live: a logout
   * that captured the engine registers its destructive promise even as a concurrent stop()/delete()
   * evicts that engine, because the rm it ends in targets this session's auth dir and would
   * otherwise race a (re)created session under that same name. The directory is keyed by the session
   * id; the lifecycle tracks the promise under the immutable captured session NAME, which is unique
   * per live row and so covers that directory, so start()/delete()/executeReconnect can wait
   * (bounded, fail-closed) for it to settle before touching that path.
   *
   * Adapters that never remove credentials on their own simply never invoke this. Baileys invokes it for a
   * WhatsApp-originated unlink (a remote logout): the promise is the cleanup that wipes the stored account
   * state and the auth directory.
   */
  onCredentialTeardownStarted?: (operation: Promise<void>) => void;
  /**
   * Synchronous atomic claim for ONE automatic credential-reset attempt within a single reconnect
   * episode. The adapter calls this BEFORE it begins the destructive credential reset that ends in
   * an `fs.rm` of this session's on-disk auth dir (the stuck-auth recovery path: a session that
   * authenticated but never reached readiness). Returns `true` exactly once per episode — the claim
   * is owned by the session lifecycle, so it survives an automatic reconnect that builds a FRESH
   * adapter (which would otherwise reset an instance-local budget and wipe LocalAuth every
   * generation, looping forever). Returns `false` once the budget is spent, and the adapter MUST
   * then fail terminally (FAILED + `onError`) WITHOUT touching the auth dir.
   *
   * SYNCHRONOUS by contract: the race between the stuck-auth timeout and any concurrent
   * start()/reconnect is resolved within a single event-loop turn. The adapter does NOT await it.
   *
   * Optional: when absent (standalone adapter use/test, no session lifecycle) the adapter falls back
   * to its own instance-local one-shot boolean so standalone behavior is unchanged.
   */
  claimStuckAuthRecovery?: () => boolean;
}

// ---------------------------------------------------------------------------
// Capability slices
//
// The engine surface is one contract per consumer domain rather than one flat list: each
// interface below is the slice one domain uses, and IWhatsAppEngine at the end of this section
// composes them all. Adapters keep implementing the union; a consumer that only touches one
// domain can narrow to the slice it needs. The slices deliberately live in this same file: the
// parity gate (engine-parity.spec.ts) reads the method inventory straight out of this file's
// text, so every method declaration stays here, indented as a member, doc comment attached.
// ---------------------------------------------------------------------------

/**
 * Session lifecycle, connection health, and identity: start/stop the engine, observe its status,
 * and read the identity it authenticated as. The QR and pairing-code members are the
 * link-a-new-session surface.
 *
 * Status and liveness stay with lifecycle rather than forming their own slice because the
 * session-lifecycle consumer uses them for exactly that: deciding whether a session is alive.
 */
export interface SessionLifecycleCapability {
  initialize(callbacks: EngineEventCallbacks): Promise<void>;

  disconnect(): Promise<void>; // Closes browser but keeps session (can reconnect without QR)

  logout(): Promise<void>; // Logs out and clears session data (requires QR scan again)

  destroy(): Promise<void>;

  // Force-kill THIS engine's own resources immediately (e.g. SIGKILL a wedged Chromium for a stuck
  // session), then best-effort graceful teardown — used to recover a session that destroy() can't.
  // Each adapter kills only its own resources (never a process-wide pkill).
  forceDestroy(): Promise<void>;

  getStatus(): EngineStatus;

  /**
   * Active liveness probe: performs a real round-trip against the engine's connection and
   * resolves true only when the session is genuinely alive. Implementations must treat probe
   * failure/timeout as "dead" — a wedged connection can keep reporting READY (cached status),
   * so getStatus() alone is not proof of life. Optional: engines whose transport already
   * self-detects death (e.g. Baileys keepalive emits a close event within ~35s) may return a
   * cheap local check. Polled periodically by the session watchdog.
   */
  probeLiveness?(): Promise<boolean>;

  getQRCode(): string | null;

  /**
   * Request an 8-char pairing code to link via phone number instead of scanning the QR. Only valid while
   * the engine is QR_READY; both adapters throw EngineNotReadyError (409) in any other status.
   */
  requestPairingCode(phoneNumber: string): Promise<string>;

  getPhoneNumber(): string | null;

  getPushName(): string | null;
}

/**
 * Outbound messaging: every member that composes a NEW message into a chat — text, media,
 * location, contact card, sticker, poll — plus reply and forward, which are sends that quote or
 * re-route existing content.
 */
export interface MessagingCapability {
  /**
   * Send text.
   *
   * `linkPreview: false` suppresses the URL preview on BOTH engines. Otherwise the two differ:
   * whatsapp-web.js builds one in-page by default, while on Baileys a preview is OPT-IN — only
   * `linkPreview: true` produces one, because generating it is a blocking outbound fetch per URL.
   */
  sendTextMessage(
    chatId: string,
    text: string,
    mentions?: string[],
    options?: { linkPreview?: boolean; customPreview?: CustomLinkPreview } & Quotable,
  ): Promise<MessageResult>;

  sendImageMessage(chatId: string, media: MediaInput): Promise<MessageResult>;

  sendVideoMessage(chatId: string, media: MediaInput): Promise<MessageResult>;

  sendAudioMessage(chatId: string, media: MediaInput): Promise<MessageResult>;

  sendDocumentMessage(chatId: string, media: MediaInput): Promise<MessageResult>;

  sendLocationMessage(chatId: string, location: LocationInput): Promise<MessageResult>;

  sendContactMessage(chatId: string, contact: ContactCard): Promise<MessageResult>;

  sendStickerMessage(chatId: string, media: MediaInput): Promise<MessageResult>;

  sendPollMessage(chatId: string, poll: PollInput): Promise<MessageResult>;

  /**
   * Reply to a message, quoting it. `mentions` tags participants exactly as on the send routes: the
   * text must also carry the matching `@<number>` token for WhatsApp to render the tag.
   */
  replyToMessage(chatId: string, quotedMsgId: string, text: string, mentions?: string[]): Promise<MessageResult>;

  forwardMessage(fromChatId: string, toChatId: string, messageId: string): Promise<MessageResult>;
}

/**
 * Operations on messages that already exist: delete, edit, star, pin, and the reaction surface.
 *
 * votePoll lives here rather than with the poll send in MessagingCapability: it mutates an
 * existing poll message (the same shape of act as reactToMessage), it does not compose one.
 */
export interface MessageOperationsCapability {
  reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void>;

  getMessageReactions(chatId: string, messageId: string): Promise<MessageReaction[]>;

  deleteMessage(chatId: string, messageId: string, forEveryone?: boolean): Promise<void>;

  /**
   * Edit the body of a text message. Only the account's OWN messages can be edited; engines reject
   * non-text or foreign messages at their own layer — the engine's error is surfaced as-is.
   *
   * `mentions` re-applies participant tags to the new body. An edit REPLACES the message content, so
   * omitting it drops whatever tags the original carried rather than preserving them.
   */
  editMessage(chatId: string, messageId: string, body: string, mentions?: string[]): Promise<MessageResult>;

  /**
   * Star (bookmark) a message, or remove its star. Starring is a private, account-local marker —
   * it is not visible to the other party and has no group-admin restriction.
   */
  starMessage(chatId: string, messageId: string, star: boolean): Promise<void>;

  /**
   * Cast a vote on a poll. `options` are the option TEXTS, not ids: whatsapp-web.js matches by name
   * (`Message.js:1027-1031`), and no engine surfaces a stable per-option id through this interface,
   * so a caller has nothing else to name an option by. Pass every option that should end up
   * selected — the list replaces the current selection rather than adding to it, and an empty array
   * clears the vote.
   *
   * A poll whose options include duplicate texts will select ALL matching options; WhatsApp permits
   * duplicates, and the name is the only handle available.
   */
  votePoll(chatId: string, pollMessageId: string, options: string[]): Promise<void>;

  /**
   * Reply to a WhatsApp Business button / list prompt as if the account tapped a choice.
   * `buttonId` is the stable id from the prompt (see inbound `buttons[].id`); `text` is the visible
   * label when known. **Baileys only**: whatsapp-web.js has no interactive-reply send path.
   *
   * The prompt must already be in the engine message store (received while the session was live).
   * Classic `buttonsMessage` / `templateMessage` / `listMessage` prompts go through Baileys'
   * `buttonReply` / `listReply` helpers. Native-flow `interactiveMessage` replies are unverified
   * against a live business prompt and must not be treated as fully supported. URL/call CTA
   * buttons are not clickable this way, only quick-reply style choices and list rows.
   */
  clickButton(chatId: string, messageId: string, buttonId: string, text?: string): Promise<MessageResult>;

  /**
   * Pin a message in its chat for a bounded window. WhatsApp only recognises three durations —
   * 86400 (24h), 604800 (7d), 2592000 (30d) — so `durationSeconds` must be one of those; it is
   * required rather than defaulted here so neither adapter has to invent a value. In a group only
   * admins may pin; the engines surface their own refusal.
   */
  pinMessage(chatId: string, messageId: string, durationSeconds: number): Promise<void>;

  /** Remove a message's pin. Unpinning takes no duration — an existing pin's window is irrelevant. */
  unpinMessage(chatId: string, messageId: string): Promise<void>;
}

/**
 * Reading a chat's stored messages. Kept apart from the chat-management slice because this is
 * the engine's only media-bearing read path — the media budget parameters are a download
 * concern no other member shares.
 */
export interface ChatHistoryCapability {
  /**
   * Read a chat's most recent `limit` messages, returned oldest first (ascending timestamp). When
   * `includeMedia` downloads blobs, an optional `mediaMaxBytes` tightens the declared-size pre-gate
   * below the global MEDIA_DOWNLOAD_MAX_BYTES —
   * the status seed uses it to skip downloads the store would discard as over-cap anyway.
   * Inlined media is additionally bounded in aggregate (CHAT_HISTORY_MEDIA_BUDGET_BYTES), spent in
   * that same order: once the running base64 total crosses the budget, the newer media messages
   * carry the `omitted` marker instead of a download. An optional `signal` (e.g. client disconnect)
   * stops the read loop early; the messages collected so far are returned.
   */
  getChatHistory(
    chatId: string,
    limit?: number,
    includeMedia?: boolean,
    mediaMaxBytes?: number,
    signal?: AbortSignal,
  ): Promise<IncomingMessage[]>;
}

/**
 * Contacts and the account's addressbook: reads, number/identity resolution, the blocklist, and
 * addressbook writes.
 *
 * getProfilePicture sits here rather than with profiles: it reads any party's picture (a group
 * JID included — see setGroupPicture), and its consumer domain is contact data.
 */
export interface ContactCapability {
  /**
   * Defaults to reporting lookup answers. `seed` keeps positive lookups as display data and revokes alias
   * trust on a conflicting phone; null still uses owner-aware clearing.
   */
  readonly contactPhoneLookupPersistence?: 'seed';

  getContacts(): Promise<Contact[]>;

  getContactById(contactId: string): Promise<Contact | null>;

  checkNumberExists(number: string): Promise<boolean>;

  /**
   * Resolve a phone number to its canonical chat id in the neutral dialect (`<phone>@c.us`), or null
   * if the number is not registered. The engine owns the JID scheme and returns it already neutralized,
   * so the value is engine-agnostic and round-trips back to a send on any engine.
   */
  getNumberId(number: string): Promise<string | null>;

  /**
   * Best-effort resolution of a contact id to a phone number (MSISDN digits). `null` is a definitive
   * "no phone for this id"; a lookup that could not decide (a failed page read, or a lid no cache,
   * table or key store maps) rejects instead, so a caller that stores the answer never overwrites a
   * known mapping with a null. The contact id is the engine's native scheme; the adapter decides how
   * to resolve it.
   */
  resolveContactPhone(contactId: string): Promise<string | null>;

  getProfilePicture(contactId: string): Promise<string | null>;

  blockContact(contactId: string): Promise<void>;

  unblockContact(contactId: string): Promise<void>;

  /**
   * Neutral ids of the contacts this account has blocked — the read half of block/unblockContact.
   * Ids only: whatsapp-web.js resolves full Contact models, but Baileys' blocklist query answers
   * bare jids, and inventing the other fields on one engine would make the two engines claim
   * different things about the same account.
   */
  getBlockedContacts(): Promise<string[]>;

  /**
   * Save a contact to the account's addressbook, or edit an existing entry. `contactId` is a
   * neutral JID; whatsapp-web.js addresses the entry by phone number and Baileys by JID, so the
   * adapters convert. An empty `lastName` is normal — WhatsApp stores single-name contacts.
   */
  upsertContact(contactId: string, firstName: string, lastName?: string): Promise<void>;

  /** Remove a contact from the account's addressbook. Does not block or delete the chat. */
  deleteContact(contactId: string): Promise<void>;
}

/** Groups: reads, membership writes, settings mutations, invites, and join approvals. */
export interface GroupCapability {
  getGroups(): Promise<Group[]>;

  getGroupInfo(groupId: string): Promise<GroupInfo | null>;

  createGroup(name: string, participants: string[]): Promise<Group>;

  /**
   * Membership writes resolve one {@link ParticipantOperationResult} per participant, so a partial
   * refusal (one invite-only number among several added) is visible instead of being flattened into
   * a blanket success. They THROW only when the operation failed for every requested participant —
   * e.g. the account lacks admin rights — or the batch itself was refused.
   */
  addParticipants(groupId: string, participants: string[]): Promise<ParticipantOperationResult[]>;

  removeParticipants(groupId: string, participants: string[]): Promise<ParticipantOperationResult[]>;

  promoteParticipants(groupId: string, participants: string[]): Promise<ParticipantOperationResult[]>;

  demoteParticipants(groupId: string, participants: string[]): Promise<ParticipantOperationResult[]>;

  leaveGroup(groupId: string): Promise<void>;

  setGroupSubject(groupId: string, subject: string): Promise<void>;

  setGroupDescription(groupId: string, description: string): Promise<void>;

  getGroupInviteCode(groupId: string): Promise<string>;

  revokeGroupInviteCode(groupId: string): Promise<string>;

  /**
   * Join a group via an invite code (the token from a `https://chat.whatsapp.com/<code>` link).
   * Resolves with the joined group's neutral id (`<id>@g.us`).
   */
  joinGroupViaInviteCode(inviteCode: string): Promise<string>;

  /**
   * What an invite code discloses about a group, without joining it. Read-only: nothing about the
   * account's membership changes, which is what makes it safe to call on an untrusted code.
   */
  getGroupJoinInfo(inviteCode: string): Promise<GroupJoinInfo>;

  /** Set the "only admins can send messages" group setting (WhatsApp announce). */
  setGroupMessagesAdminsOnly(groupId: string, adminsOnly: boolean): Promise<void>;

  /** Set the "only admins can edit group info" group setting (WhatsApp locked/restrict). */
  setGroupInfoAdminsOnly(groupId: string, adminsOnly: boolean): Promise<void>;

  /**
   * Set the group's picture. Requires admin rights on both engines; the engines report a refusal
   * differently, so the adapters normalise it. Reading the current picture needs no dedicated
   * method — `getProfilePicture` accepts a group JID.
   */
  setGroupPicture(groupId: string, media: MediaInput): Promise<void>;

  /** Remove the group's picture. */
  deleteGroupPicture(groupId: string): Promise<void>;

  /** Set who may add participants to the group. */
  setGroupMemberAddMode(groupId: string, mode: GroupMemberAddMode): Promise<void>;

  /**
   * Set the group's disappearing-messages timer in seconds; 0 disables it.
   * Known values: 86400 (24h), 604800 (7d), 7776000 (90d).
   */
  setGroupEphemeral(groupId: string, durationSec: number): Promise<void>;

  /**
   * Set this account's own member label in the group (the per-group tag shown beside its name); an empty
   * string clears it. Resolves once the label message is handed to WhatsApp: it travels as a group
   * protocol message with no per-request confirmation, and group metadata does not carry the label back.
   */
  setGroupMemberLabel(groupId: string, label: string): Promise<void>;

  /**
   * Pending join requests for a group with join-approval turned on. Admin-only on both engines;
   * a non-admin's read is refused by the engine and surfaced as-is.
   */
  getGroupMembershipRequests(groupId: string): Promise<GroupMembershipRequest[]>;

  /**
   * Approve pending join requests — the named participants, or EVERY pending request when
   * `participants` is omitted. Per-participant outcomes follow the membership-write contract
   * (see addParticipants); the all-failed/no-outcome guards apply only when participants were
   * NAMED — approving an empty queue is a no-op that resolves [].
   */
  approveGroupMembershipRequests(groupId: string, participants?: string[]): Promise<ParticipantOperationResult[]>;

  /** Reject pending join requests; same contract as approveGroupMembershipRequests. */
  rejectGroupMembershipRequests(groupId: string, participants?: string[]): Promise<ParticipantOperationResult[]>;
}

/**
 * Calls: rejecting a ringing call and generating call links. Call EVENTS arrive through
 * EngineEventCallbacks (onCall / onCallOutcome), not through this slice.
 */
export interface CallCapability {
  /**
   * Reject an incoming call. Only a currently-ringing call can be rejected: the Baileys adapter keeps
   * the caller JID it needs (keyed by the `callId` from {@link IncomingCallEvent}) for the ringing
   * window, and an unknown or expired callId fails with a not-found error (HTTP 404). whatsapp-web.js
   * throws EngineNotSupportedError (HTTP 501): a rejection it sent did not stop a live call ringing.
   */
  rejectCall(callId: string): Promise<void>;

  /**
   * Generate a shareable WhatsApp call link, returning the finished `https://call.whatsapp.com/…`
   * URL. `startTime` is an absolute epoch-MILLISECONDS timestamp; both engines take seconds on the
   * wire and each adapter converts.
   *
   * The engines return different things and the adapters reconcile them: whatsapp-web.js resolves
   * the finished link (or `''` on failure), Baileys resolves only the bare token and the adapter
   * assembles it behind the library's own prefix. A WhatsApp-side failure throws rather than
   * returning an empty or prefix-only link, which would look like a working link and is not one.
   */
  createCallLink(type: CallLinkType, startTime: number): Promise<string>;
}

/**
 * The account's OWN profile: display name, about text, and picture. Distinct from
 * ContactCapability, which reads and writes other parties.
 */
export interface ProfileCapability {
  /** Set the account's display name. */
  setProfileName(name: string): Promise<void>;

  /** Set the account's "about" / status text. */
  setProfileStatus(status: string): Promise<void>;

  /** Set the account's profile picture (a URL payload is fetched server-side). */
  setProfilePicture(media: MediaInput): Promise<void>;

  /**
   * Remove the account's own profile picture. Resolves when the removal is acknowledged; deleting a
   * picture that is not there is a no-op rather than an error, so the call is idempotent.
   *
   * Only whatsapp-web.js can report a refusal, and only as an explicit `false` — its page helper
   * also returns `undefined` when it did not attempt the delete at all, which is NOT a refusal.
   * Baileys resolves void and has no refusal signal, so it reports success for any acknowledged
   * write.
   */
  deleteProfilePicture(): Promise<void>;
}

/**
 * Labels (WhatsApp Business): label reads and writes, and the label-to-chat assignment surface.
 * A non-business account has no labels at all.
 */
export interface LabelCapability {
  getLabels(): Promise<Label[]>;

  getLabelById(labelId: string): Promise<Label | null>;

  getChatLabels(chatId: string): Promise<Label[]>;

  addLabelToChat(chatId: string, labelId: string): Promise<void>;

  /**
   * Create or update a label, keyed on `label.id`. One operation, not two: the engines express both
   * through a single app-state write, and which one happens depends on whether the id already
   * exists. Only fields that are set are changed.
   */
  upsertLabel(label: LabelInput): Promise<void>;

  /** Delete a label. It disappears from every chat it was on. */
  deleteLabel(labelId: string): Promise<void>;

  /** Every chat carrying a label. */
  getChatsByLabel(labelId: string): Promise<ChatSummary[]>;

  removeLabelFromChat(chatId: string, labelId: string): Promise<void>;
}

/** Channels/newsletters: subscription, reads, and the owner-only administration writes. */
export interface ChannelCapability {
  getSubscribedChannels(): Promise<Channel[]>;

  getChannelById(channelId: string): Promise<Channel | null>;

  subscribeToChannel(inviteCode: string): Promise<Channel>;

  unsubscribeFromChannel(channelId: string): Promise<void>;

  getChannelMessages(channelId: string, limit?: number): Promise<ChannelMessage[]>;

  /**
   * Create a channel and return it. The account becomes its owner, which is what makes deleting it
   * possible later — neither engine can delete a channel it does not own.
   */
  createChannel(name: string, description?: string): Promise<Channel>;

  /** Delete a channel this account owns. Irreversible, and its subscribers lose it. */
  deleteChannel(channelId: string): Promise<void>;

  /** Mute or unmute a channel's notifications for this account. Does not affect subscription. */
  muteChannel(channelId: string, mute: boolean): Promise<void>;

  /**
   * Demote a channel admin back to a plain subscriber. Requires this account to own the channel.
   *
   * There is deliberately no promote counterpart: neither library has one — Baileys exposes no
   * `newsletterPromote` and whatsapp-web.js no `promoteChannelAdmin` — so an admin is promoted from
   * the WhatsApp app and can then be demoted here.
   */
  demoteChannelAdmin(channelId: string, userId: string): Promise<void>;

  /**
   * Hand a channel this account owns to a new owner. **Irreversible** — the account stops being the
   * owner and cannot take it back through this API.
   *
   * The whatsapp-web.js option to also dismiss yourself as admin in the same call is not exposed:
   * the page function it relies on no longer exists, and it sits inside a branch that swallows its
   * own errors, so it would fail silently rather than refusing.
   */
  transferChannelOwnership(channelId: string, newOwnerId: string): Promise<void>;
}

/** Status/stories: reading contacts' statuses and posting or deleting the account's own. */
export interface StatusCapability {
  getContactStatuses(): Promise<Status[]>;

  getContactStatus(contactId: string): Promise<Status[]>;

  postTextStatus(text: string, options: StatusPostOptions): Promise<StatusResult>;

  postImageStatus(media: MediaInput, options: StatusPostOptions): Promise<StatusResult>;

  postVideoStatus(media: MediaInput, options: StatusPostOptions): Promise<StatusResult>;

  /**
   * Post an audio status as a voice note. WhatsApp plays a status voice note only for Ogg/Opus, and
   * neither engine transcodes — the media conversion endpoints exist to produce it.
   */
  postVoiceStatus(media: MediaInput, options: StatusPostOptions): Promise<StatusResult>;

  deleteStatus(statusId: string): Promise<void>;
}

/**
 * Catalog (WhatsApp Business): catalog and product reads. sendProduct and sendCatalog stay here
 * rather than in MessagingCapability — they ship a catalog entity into a chat, and their consumer
 * is the commerce domain, so a messaging-only dependency need not carry them.
 */
export interface CatalogCapability {
  getCatalog(): Promise<Catalog | null>;

  getProducts(options?: ProductQueryOptions): Promise<PaginatedProducts>;

  getProduct(productId: string): Promise<Product | null>;

  sendProduct(chatId: string, productId: string, body?: string): Promise<MessageResult>;

  sendCatalog(chatId: string, body?: string): Promise<MessageResult>;
}

/**
 * The newest message the gateway stored for a chat (the `messages` table), in the shape an engine
 * that keys chat writes to a message needs to rebuild that message's key.
 */
export interface StoredChatMessage {
  /** The WhatsApp message id. */
  id: string;
  fromMe: boolean;
  /** The sender of a group message that is not from me, as stored (neutral dialect); absent otherwise. */
  author?: string;
  /** Epoch seconds. */
  timestamp: number;
  /**
   * The `<lid>@lid` of a 1:1 chat, and of `author`, as the persisted lid mapping holds them. Read from
   * the table rather than an in-memory cache, which can lack a mapping; absent when none is known.
   */
  lid?: string;
  authorLid?: string;
}

/**
 * Reads the newest stored message of the chat a write is for, across the chat's id forms. Engines
 * call it only when they know no message of the chat themselves, so a lookup costs nothing when it is
 * not needed; it resolves null when the gateway stored none.
 */
export type StoredChatMessageLookup = () => Promise<StoredChatMessage | null>;

/**
 * Chat-list management: enumeration and per-chat flags (seen, unread, archive, pin, mute,
 * clear). These operate on the chat itself; pinning a message INSIDE a chat is
 * MessageOperationsCapability.pinMessage.
 *
 * Baileys keys sendSeen, markUnread, archiveChat, clearChatMessages and deleteChat to a message of the
 * chat, and holds the chat's messages only in memory since its session started. `stored` is the
 * gateway's fallback for a chat with no message since then; whatsapp-web.js needs none and ignores it.
 */
export interface ChatCapability {
  getChats(): Promise<ChatSummary[]>;

  /**
   * `messageIds` names exactly which messages to acknowledge. Engines that acknowledge per
   * message (Baileys) need it to mark a burst; without it they acknowledge the newest received
   * message they know, else the newest received one `stored` finds. Engines with a chat-level
   * receipt (whatsapp-web.js) ignore both.
   *
   * `authors` maps a message id to who posted it, for a group: a receipt names its sender, and an id the
   * engine never kept (history backfill) has no key to read it from. An id with neither is not acknowledged.
   */
  sendSeen(
    chatId: string,
    messageIds?: string[],
    authors?: ReadonlyMap<string, string>,
    stored?: StoredChatMessageLookup,
  ): Promise<boolean>;

  /**
   * Resolves false when the engine cannot act. On Baileys an archived chat needs a known message to
   * key the mark to; a chat that is not archived is marked without one if the session knows it.
   */
  markUnread(chatId: string, stored?: StoredChatMessageLookup): Promise<boolean>;

  /**
   * Resolves false when the engine cannot act — on Baileys a chat with no known message at all, since
   * the delete removes the messages up to the one it is keyed to and guessing that is not safe.
   */
  deleteChat(chatId: string, stored?: StoredChatMessageLookup): Promise<boolean>;

  /**
   * Archive or unarchive a chat. Baileys keys the change to a known message of the chat and sends it
   * without one when none is known, which WhatsApp applies as well, but only for a chat the session
   * knows (a chat record, a persisted state row or a stored message); otherwise it resolves false.
   */
  archiveChat(chatId: string, archive: boolean, stored?: StoredChatMessageLookup): Promise<boolean>;

  /**
   * Pin or unpin a chat at the top of the chat list. Chat-level — distinct from `pinMessage`, which
   * pins a message inside a chat.
   *
   * Resolves false only when the engine DECLINED, and only one direction can: WhatsApp allows at
   * most three pinned chats, and whatsapp-web.js reports the refusal rather than silently dropping
   * it. Unpinning always resolves true, and Baileys always resolves true in both directions — it
   * writes an app-state patch and WhatsApp reports nothing back, so it cannot see the cap. Unlike
   * archiveChat the patch carries no `lastMessages`, so a chat with no known history pins fine.
   */
  pinChat(chatId: string, pin: boolean): Promise<boolean>;

  /**
   * Mute or unmute a chat's notifications. `muteUntil` is an absolute epoch-MILLISECONDS timestamp
   * the mute expires at; `null` unmutes now. To mute indefinitely, pass a far-future timestamp —
   * neither engine exposes a portable "forever" sentinel (whatsapp-web.js uses -1 internally,
   * Baileys has none), so the contract keeps a single well-defined shape instead.
   *
   * Milliseconds is measured, not inferred. WhatsApp's app-state `MuteAction.muteEndTimestamp` is
   * unsuffixed while the proto spells other millisecond fields `…Ms`, which reads as seconds and is
   * wrong: sending an epoch-seconds value live left the chat unmuted (the instant had already
   * passed in 1970), and the same instant sent in milliseconds muted it to the expected minute.
   * Getting this backwards is silent — the send still answers 200 and the mute simply never applies,
   * or lands tens of thousands of years out and reads as permanent.
   *
   * Unlike clearChatMessages/deleteChat this has no "engine declined" outcome: the Baileys `mute`
   * app-state modification carries no `lastMessages`, so a chat with no known history mutes like
   * any other. That is why it resolves void rather than boolean.
   */
  muteChat(chatId: string, muteUntil: number | null): Promise<void>;

  /**
   * Delete every message in a chat while keeping the chat itself in the list. Resolves false when
   * the engine cannot act — an unknown chat on whatsapp-web.js, or (as with deleteChat) a chat with
   * no known message at all on Baileys, whose clear is keyed to the last message.
   */
  clearChatMessages(chatId: string, stored?: StoredChatMessageLookup): Promise<boolean>;
}

/**
 * Presence: chat typing/recording indicators, the account's own online visibility, and presence
 * subscriptions (delivered through onPresenceUpdate).
 */
export interface PresenceCapability {
  /**
   * Send a typing/recording presence indicator to a chat, or clear it (`paused`).
   * Engine-agnostic and best-effort: engines without a presence concept should no-op.
   */
  sendChatState(chatId: string, state: ChatState): Promise<void>;

  /**
   * Publish the ACCOUNT's own global presence: `true` = appear online, `false` = appear offline.
   * A linked device that announces itself online routes notifications away from the phone, so a
   * headless bot that never goes offline suppresses the phone's own alerts — which is why this is
   * NOT best-effort, unlike sendChatState: the caller asked for a specific visibility, and a
   * swallowed failure would leave the account silently online. Chat-state updates are a separate
   * wire operation (`<chatstate>` / `sendStateTyping`) and do not publish this.
   *
   * The call itself is one-shot. The gateway remembers a successful one for the life of the running
   * engine and re-applies it once each time that connection opens: Baileys announces itself on
   * connect per `markOnlineOnConnect` (`available` by default), which would otherwise replace the
   * caller's choice on a transient reconnect. Replacing the engine drops the preference: stop,
   * restart, reconnect recovery, a watchdog recycle, or a takeover by another node.
   *
   * On Baileys this throws when the account push name is not set yet. `sendPresenceUpdate`
   * resolves without sending in that case (`no name present, ignoring presence update request`).
   */
  setOnlinePresence(available: boolean): Promise<void>;

  /**
   * Ask WhatsApp to start reporting a chat's presence, delivered through `onPresenceUpdate`.
   *
   * Deliberately per chat rather than a blanket subscribe-all: WhatsApp emits a presence update on
   * every transition — each time someone starts and stops typing — so subscribing to everything
   * turns an idle account into a firehose. The subscription lasts for the life of the connection and
   * has to be re-established after a reconnect.
   *
   * There is no matching read: presence cannot be queried, only received, which is why the gateway
   * serves the last reported state rather than fetching it.
   */
  subscribeToPresence(chatId: string): Promise<void>;
}

/**
 * The complete engine contract: every capability slice above, composed. Nothing is declared here
 * directly — a member belongs to the slice its consumer domain forms, so an engine-wide member
 * would mean a domain that has no other surface. Adapters implement this union unchanged.
 */
export interface IWhatsAppEngine
  extends
    SessionLifecycleCapability,
    MessagingCapability,
    MessageOperationsCapability,
    ChatHistoryCapability,
    ContactCapability,
    GroupCapability,
    CallCapability,
    ProfileCapability,
    LabelCapability,
    ChannelCapability,
    StatusCapability,
    CatalogCapability,
    ChatCapability,
    PresenceCapability {}