Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

42.4 KB
Raw Blame
import { BadRequestException, HttpException, HttpStatus, Injectable, Optional } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { InjectRepository } from '@nestjs/typeorm';
import { MoreThanOrEqual, Repository } from 'typeorm';
import { Message, MessageDirection } from './entities/message.entity';
import { Session } from '../session/entities/session.entity';
import { resolveSendPacingConfig, type SendPacingConfig } from './send-pacing.config';
import { incrementSendPacingRefusals, type SendPacingRefusalReason } from '../../common/metrics/send-pacing-metrics';
import { createLogger } from '../../common/services/logger.service';
import { EngineRefusedError } from '../../common/errors/engine-refused.error';
import { EngineNotSupportedError } from '../../common/errors/engine-not-supported.error';
import { EngineThrottledError } from '../../common/errors/engine-throttled.error';
import { EngineNotSentError } from '../../common/errors/engine-not-sent.error';
import { SsrfBlockedError } from '../../common/security/ssrf-guard';
import { toParticipantWid } from '../../engine/identity/wa-id';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';

/** Body code on a pacing refusal. The throttler's own 429 carries no `code`, which is what tells the two apart. */
export const SEND_PACING_LIMITED = 'SEND_PACING_LIMITED';

/**
 * True for the 429 `assertSendAllowed` throws — a policy refusal, distinguished from any other 429
 * by the `code` on its body. Callers use it to treat a paced-out send as a refusal-to-send rather
 * than a delivery failure (no `message:failed`, no breaker increment — the engine was never asked).
 */
export function isPacingLimitedError(error: unknown): boolean {
  if (!(error instanceof HttpException)) return false;
  const body = error.getResponse();
  return typeof body === 'object' && body !== null && (body as { code?: string }).code === SEND_PACING_LIMITED;
}

/**
 * Whether a failed send says anything about the ACCOUNT's standing with WhatsApp — the only thing
 * the breaker is meant to measure.
 *
 * Adapters raise plenty of failures before (or instead of) asking WhatsApp: a blocked media URL, a
 * capability the engine does not implement, a socket that is not connected, a message id that is
 * not in the local store, a malformed request. Counting those lets a client sending bad requests
 * open the breaker on a perfectly healthy session and 429 every send for the cooldown. The rule is
 * therefore: a client-fault or engine-state HTTP status (4xx/501/503) does NOT count; a refusal
 * WhatsApp itself returned — EngineRefusedError (403) — and anything unclassified (a raw engine
 * error, a timeout, a 5xx) does. A rate limit WhatsApp answered (EngineThrottledError, a 503 on the wire)
 * counts as well: it is WhatsApp refusing this account's traffic, the signal the breaker exists to act on,
 * even though the send provably went nowhere (see sentNothing).
 */
export function countsTowardSendBreaker(error: unknown): boolean {
  if (error instanceof EngineRefusedError || error instanceof EngineThrottledError) return true;
  if (error instanceof SsrfBlockedError) return false;
  if (error instanceof HttpException) {
    const status = error.getStatus();
    // 4xx = the caller's request was wrong; 501 = this engine cannot do it; 503 = the engine is not
    // connected (a transport fault the reconnect machinery owns, not an account signal).
    const NOT_IMPLEMENTED: number = HttpStatus.NOT_IMPLEMENTED;
    const SERVICE_UNAVAILABLE: number = HttpStatus.SERVICE_UNAVAILABLE;
    return !((status >= 400 && status < 500) || status === NOT_IMPLEMENTED || status === SERVICE_UNAVAILABLE);
  }
  return true;
}

/**
 * Whether a send that threw provably never went out, so its admission can be handed back: a client or
 * refusal status (4xx), a 501 for something the engine cannot do, a media URL the SSRF guard blocked
 * before any fetch, a WhatsApp rate limit (EngineThrottledError), turned away before it ran, or a transport
 * failure before the message was handed to WhatsApp (EngineNotSentError). Anything else (a deadline, a
 * dropped socket, a dead page) leaves the outcome unknown; WhatsApp may have taken the message, so its
 * admission stays held.
 */
export function sentNothing(error: unknown): boolean {
  return (
    error instanceof SsrfBlockedError ||
    (error instanceof HttpException &&
      (error.getStatus() < 500 ||
        error instanceof EngineNotSupportedError ||
        error instanceof EngineThrottledError ||
        error instanceof EngineNotSentError))
  );
}

/**
 * Cold reachouts `assertReachoutAllowed` set aside on the group tally for one request, and the UTC
 * day they were taken from. Hand it back to `refundGroupReachouts` if the engine call fails.
 */
export interface GroupReachoutReservation {
  coldCount: number;
  dayStartMs: number;
}

/** Nothing reserved: the feature is off, no cold schedule, or no stranger in the batch. */
const NO_RESERVATION: GroupReachoutReservation = { coldCount: 0, dayStartMs: 0 };

/** Per-session breaker state. Deliberately in memory — see the class doc. */
interface BreakerState {
  consecutiveFailures: number;
  /** Epoch ms the breaker opened, or null while it is closed. */
  openedAt: number | null;
}

/**
 * A send admitted recently, with the counts it read before it was admitted. A send's row is written by
 * the caller after the check returns (after the plugin gate), so a burst of parallel requests would
 * otherwise all read the same persisted count and all pass. Each cap is judged by the larger of the
 * persisted count and, for every held admission, the count it read plus the admissions held from it
 * on: none of those rows can be in the count it read, so nothing is counted twice. An admission stays held
 * for as long as any admission taken after it is held, since those may have read before its row landed
 * and would otherwise miss it once it stops being held. The cold cap holds its own chain the same way, over
 * the cold admissions alone: only a cold admission reads a cold count.
 */
interface Admission {
  /** Epoch ms its own term ends: a window from its admission, or from its settle. */
  until: number;
  /** An untilSettled caller still has no engine outcome to count in the persisted day. */
  unsettled: boolean;
  /** Epoch ms it stops being held, so only its row counts from then on; refreshed by heldAdmissions. */
  heldUntil: number;
  /** Reset at UTC rollover, then filled from the first current-day count. */
  sentToday: number | null;
  /**
   * Set for a cold send; the key is folded the way the cold count folds dialects. Cleared by heldAdmissions
   * once no cold admission's own term is running, so from then on only its row counts against the cold cap.
   */
  cold: { key: string; coldToday: number | null } | null;
}

/** The admissions a session holds, in the order they were admitted, for one UTC day. */
interface AdmissionHold {
  dayStartMs: number;
  admissions: Admission[];
}

/**
 * How long each admitted send is held against the caps before only its row counts: from its own
 * admission, or for one taken `untilSettled`, from the moment its caller settles it. It only has to
 * outlast the gap between that moment and the row insert. A send that fails before writing a row hands
 * its admission back (see assertSendAllowed), so only one that may still have gone out is over-counted,
 * for this long after it settles, or as long as a send admitted after it is held, if that is longer.
 */
const ADMISSION_WINDOW_MS = 10_000;

/**
 * Safety bound on an admission taken `untilSettled` that its caller never settles. Far longer than an
 * engine send normally runs (a media URL fetch is bounded by MEDIA_DOWNLOAD_TIMEOUT_MS, 30 s by default),
 * so it only matters if a caller loses track of one, which then holds the caps for this long instead of
 * for the rest of the day. A send still running past it stops being held.
 */
const UNSETTLED_ADMISSION_MAX_MS = 5 * 60_000;

/**
 * Settles the admission assertSendAllowed held. Called with nothing, for a send that provably never went
 * out, it hands the admission back at once. Called with `true`, once PENDING is written or the engine returned
 * or failed with an unknown outcome, it holds the admission for ADMISSION_WINDOW_MS while the row or own-send
 * echo lands, or for as long as a send admitted after it is held, if that is longer.
 */
export type SettleAdmission = (mayHaveSent?: boolean) => void;

/** Refusals suppressed since the last audited one, per session. */
interface RefusalSample {
  count: number;
  since: number;
}

/**
 * At most one `SEND_PACING_BLOCKED` row per session per window. A session that hits its daily cap
 * goes on being refused for the rest of the day, so one row per refused send would turn enforcing
 * the limit into an audit flood of its own — the same problem, and the same answer, as the
 * websocket rate limiter's `RATE_LIMIT_EXCEEDED` sampling.
 */
const REFUSAL_AUDIT_WINDOW_MS = 60_000;
/** Bound on the sampling map, so a churn of session ids cannot grow it without limit. */
const MAX_REFUSAL_KEYS = 1000;

/**
 * Refuses outbound sends that a young or misbehaving session should not be making.
 *
 * Two rules, both aimed at the way WhatsApp actually bans automated accounts:
 *
 *  - a **warm-up daily cap**, because a new account that immediately sends at volume is the pattern
 *    that gets numbers banned. The allowance grows with the session's age.
 *  - a **failure-streak breaker**, because a run of consecutive send failures usually means WhatsApp
 *    has already started refusing this account, and continuing to push makes its standing worse.
 *
 * It is plain code called from the send paths, NOT a `message:sending` hook subscriber. That is
 * load-bearing: `runGuarded` (plugin-capability-context.ts) suppresses `message:sending` when a
 * plugin sends from inside its own handler, so a hook-based governor would be silently bypassed on
 * exactly the automated traffic it exists to pace.
 *
 * The daily count is read from the `messages` table rather than a counter of its own. That table is
 * already the durable record of every chat send — bulk included, which persists through the same
 * `saveOutgoingMessage` — and it already carries the `(sessionId, createdAt)` index the count needs.
 * So the cap survives restarts with no table and no migration. The trade is that it counts only what
 * writes a row. Two kinds of path clear this check without ever adding to it: a status post
 * (status.service.ts) and a message edit, which is gated here via applySendingGate but only UPDATEs
 * the existing row, never inserts. A bulk item the engine refuses is a third: bulk persists its row only
 * after the send succeeds, so a failed item is checked against the cap but never counted into it,
 * unlike a failed single send whose PENDING row is kept as FAILED. A session using
 * them can exceed its stated allowance. A Baileys product send (catalog.service.ts `sendProduct`)
 * writes no row itself but is counted through the OUTGOING row its own-send echo persists
 * (MessageProjector.handleOwnSendEcho) shortly after the send returns. Deliberate, and documented in
 * .env.example and docs/06 so the number an operator reads is the number they get.
 * Because the row lands only after the check returns, sends admitted in the last few seconds are
 * also held in memory (see Admission), or a parallel burst would pass against one stale count. A bulk
 * item and a product send write their row only after the engine call, which can outlast that window
 * (a media URL fetch, an upload), so they are held until they settle (see `untilSettled`).
 * The breaker, by contrast, is in memory on purpose: it describes live conditions, and a restart
 * clearing it is the correct behaviour.
 */
@Injectable()
export class SendPacingService {
  private readonly logger = createLogger('SendPacingService');
  private readonly breakers = new Map<string, BreakerState>();
  /**
   * Per-session count of cold GROUP-ADD reachouts used today. Group adds (createGroup/
   * addParticipants) persist no message row, so `countColdReachoutsToday` — which reads the messages
   * table — cannot see them; without this tally each add request would get the full daily allowance
   * afresh, making the cap per-request instead of per-day. In memory like the breaker (the service
   * doc explains why); it resets by UTC day, and also on restart — which for this half of the budget
   * means a restart FORGETS what was already spent and hands out the allowance again. That errs
   * toward more reachouts, not fewer, and is the one place this feature is not restart-proof: the
   * chat half is counted from the messages table and is.
   */
  private readonly groupReachoutTally = new Map<string, { dayStartMs: number; count: number }>();
  private readonly holds = new Map<string, AdmissionHold>();
  private readonly refusalSamples = new Map<string, RefusalSample>();

  constructor(
    @InjectRepository(Message, 'data')
    private readonly messageRepository: Repository<Message>,
    @InjectRepository(Session, 'data')
    private readonly sessionRepository: Repository<Session>,
    @Optional()
    private readonly configService?: ConfigService,
    // @Optional so the standalone constructions in specs keep working. AuditModule is @Global, so in
    // a running gateway it is always present; absent means the console log is the only record.
    @Optional()
    private readonly auditService?: AuditService,
  ) {}

  /**
   * Throw unless this session may send right now. Called at the top of every outbound send path.
   *
   * When the feature is off this returns before doing anything at all — no query, no map lookup — so
   * a deployment that has not opted in behaves exactly as it did before the governor existed.
   *
   * `hold: false` judges the send without holding it in the admission window, for a gated send that
   * never writes a row (an edit): holding it would charge the caps for a message that is never sent.
   *
   * `untilSettled` holds the admission for as long as the send runs, for a caller whose row lands only
   * after the engine call (a bulk item, a product send): the window starts when the caller settles it
   * with `true`, bounded by UNSETTLED_ADMISSION_MAX_MS if it never does. Without it the window starts
   * now, for a caller that writes its PENDING row before asking the engine.
   * `whilePreparing` has no safety expiry: its caller must settle in a finally block once the
   * PENDING write finishes or preparation fails, even when hooks take arbitrarily long.
   *
   * Returns the settle for the admission it held, or undefined when it held none. A caller whose send
   * fails before writing a row, and before WhatsApp may have taken it, calls it with nothing so that
   * send stops counting against the caps at once instead of refusing the next one.
   */
  async assertSendAllowed(
    sessionId: string,
    chatId?: string,
    opts: { hold?: boolean; untilSettled?: boolean; whilePreparing?: boolean } = {},
  ): Promise<SettleAdmission | undefined> {
    const config = resolveSendPacingConfig(this.configService);
    if (!config.enabled) return;

    this.assertBreakerClosed(sessionId, config);
    const session = await this.sessionRepository.findOne({ where: { id: sessionId } });
    // No row means the send is about to fail on its own for a better reason than pacing; let it.
    if (!session) return;

    const dayStart = startOfUtcDay(new Date());
    // Age from createdAt, NOT connectedAt: connectedAt is overwritten on every connect, so a session
    // that reconnects would look one day old forever and never leave the first rung of the ramp.
    const ageDays = Math.floor((dayStart.getTime() - startOfUtcDay(session.createdAt).getTime()) / DAY_MS);
    const allowance = this.allowanceForAge(config.warmupSchedule, ageDays);
    const sentToday = await this.messageRepository.count({
      where: { sessionId, direction: MessageDirection.OUTGOING, createdAt: MoreThanOrEqual(dayStart) },
    });
    // A stale count must not reset the new day's held admissions.
    if (startOfUtcDay(new Date()).getTime() !== dayStart.getTime()) {
      return this.assertSendAllowed(sessionId, chatId, opts);
    }
    // The overall cap is the cheaper check and bounds everything, so it settles before the cold probe.
    this.assertUnderDailyCap(sessionId, dayStart, ageDays, allowance, sentToday);
    const cold = await this.readColdReachouts(sessionId, chatId, dayStart, ageDays, config);
    if (startOfUtcDay(new Date()).getTime() !== dayStart.getTime()) {
      return this.assertSendAllowed(sessionId, chatId, opts);
    }

    // Judged again, and admitted, with no await from here on: a concurrent request admitted while this
    // one was reading must count, and this one must count for the next.
    this.assertUnderDailyCap(sessionId, dayStart, ageDays, allowance, sentToday);
    // A status post (no chatId) never writes a row and never has, so it is not held either.
    if (!chatId) return;
    // A chat already held as a cold admission is the same reachout again, not a new one.
    const key = coldChatKey(chatId);
    if (cold && !this.heldAdmissions(sessionId, dayStart).some(a => a.cold?.key === key)) {
      this.assertUnderColdCap(sessionId, dayStart, ageDays, cold);
    }
    if (opts.hold !== false) {
      const until = opts.whilePreparing
        ? Infinity
        : Date.now() + (opts.untilSettled ? UNSETTLED_ADMISSION_MAX_MS : ADMISSION_WINDOW_MS);
      const admission: Admission = {
        until,
        unsettled: opts.untilSettled === true,
        heldUntil: until,
        sentToday,
        cold: cold ? { key, coldToday: cold.coldToday } : null,
      };
      const hold = this.holds.get(sessionId);
      if (hold?.dayStartMs === dayStart.getTime()) hold.admissions.push(admission);
      else this.holds.set(sessionId, { dayStartMs: dayStart.getTime(), admissions: [admission] });
      let settled = false;
      return (mayHaveSent = false) => {
        if (settled) return;
        settled = true;
        admission.unsettled = false;
        if (mayHaveSent) {
          admission.until = Date.now() + ADMISSION_WINDOW_MS;
          return;
        }
        // Handed back, it holds nothing.
        admission.until = admission.heldUntil = 0;
        const admissions = this.holds.get(sessionId)?.admissions;
        const index = admissions?.indexOf(admission) ?? -1;
        if (admissions && index !== -1) {
          admissions.splice(index, 1);
          if (admissions.length === 0) this.holds.delete(sessionId);
        }
      };
    }
  }

  /** Cold chat reachouts today: the persisted count, or more when the held admissions account for more. */
  private chatReachoutsToday(sessionId: string, dayStart: Date, persisted: number): number {
    const held = this.heldAdmissions(sessionId, dayStart);
    // Newest first, so `chats` is always the distinct cold chats held from this admission on.
    const chats = new Set<string>();
    let count = persisted;
    for (let i = held.length - 1; i >= 0; i--) {
      const cold = held[i].cold;
      if (!cold) continue;
      cold.coldToday ??= persisted;
      chats.add(cold.key);
      count = Math.max(count, cold.coldToday + chats.size);
    }
    return count;
  }

  /** This session's held admissions today, oldest first, including preparations carried across midnight. */
  private heldAdmissions(sessionId: string, dayStart: Date): Admission[] {
    const hold = this.holds.get(sessionId);
    if (!hold) return [];
    const now = Date.now();
    if (hold.dayStartMs !== dayStart.getTime()) {
      // Preparations and engine calls still running may write today; completed yesterday's sends do not.
      hold.admissions = hold.admissions.filter(a => a.until === Infinity || (a.unsettled && a.until > now));
      hold.dayStartMs = dayStart.getTime();
      for (const admission of hold.admissions) {
        admission.sentToday = null;
        if (admission.cold) admission.cold.coldToday = null;
      }
    }
    // The cold terms lapse as a whole, once no cold admission's own term is running: a warm admission read no
    // cold count, so it cannot have missed a cold row, and letting it hold them would keep a cold send that
    // wrote no row counted for as long as warm sends keep arriving. Cleared rather than skipped, so a cold
    // admission taken later cannot bring them back.
    if (!hold.admissions.some(a => a.cold && a.until > now)) for (const a of hold.admissions) a.cold = null;
    // Newest first: an admission stays held while the next one is. Each one taken after it may have read
    // its count before this one's row landed, and its own term counts this one and each later one once, on
    // a count read before any of their rows.
    for (let i = hold.admissions.length - 1; i >= 0; i--) {
      const a = hold.admissions[i];
      a.heldUntil = Math.max(a.until, hold.admissions[i + 1]?.heldUntil ?? 0);
    }
    // heldUntil never rises from the oldest admission to the newest, so the hold lapses as a whole, once
    // its oldest admission is no longer held.
    if (hold.dayStartMs === dayStart.getTime() && (hold.admissions[0]?.heldUntil ?? 0) > now) return hold.admissions;
    this.holds.delete(sessionId);
    return [];
  }

  /**
   * Throw unless this session may reach out to these contacts at once.
   *
   * Adding someone to a group is a reachout in every sense that matters: it puts the account in
   * front of a stranger who did not ask for it, and doing it in bulk is the single most
   * ban-associated action this product can perform. So it draws on the same cold budget a first
   * message does — a batch of twenty strangers costs twenty, not one.
   *
   * It does NOT consume the overall daily message allowance: no message is sent, and spending a
   * send budget on something that sends nothing would misreport both.
   *
   * The whole batch is refused rather than trimmed. Adding some of the requested participants and
   * reporting success would leave the caller unable to tell who actually got added, and the engines
   * report per-participant outcomes for real failures already — a pacing refusal must not be
   * mistaken for one of those.
   *
   * An allowed batch is reserved on the group tally before this returns, in the same synchronous
   * step as the comparison, so concurrent requests cannot all pass against the same unspent budget.
   * The caller refunds the reservation if the engine call then throws.
   */
  async assertReachoutAllowed(sessionId: string, contactIds: string[]): Promise<GroupReachoutReservation> {
    const config = resolveSendPacingConfig(this.configService);
    if (!config.enabled) return NO_RESERVATION;

    this.assertBreakerClosed(sessionId, config);
    if (config.coldSchedule.length === 0 || contactIds.length === 0) return NO_RESERVATION;

    // The same id twice in one request is one contact, and must cost one. Each contact is probed
    // under both user-id dialects (see dialectVariants) — a contact known under the other spelling
    // is not a stranger.
    const unique = [...new Set(contactIds.map(toParticipantWid))];
    const variantsByContact = new Map(unique.map(id => [id, dialectVariants(id)]));
    const knownRows = await this.messageRepository
      .createQueryBuilder('m')
      .select('DISTINCT m.chatId', 'chatId')
      .where('m.sessionId = :sessionId', { sessionId })
      .andWhere('m.chatId IN (:...ids)', { ids: [...new Set([...variantsByContact.values()].flat())] })
      .getRawMany<{ chatId: string }>();
    const knownIds = new Set(knownRows.map(row => row.chatId));
    const coldCount = unique.filter(id => !variantsByContact.get(id)!.some(v => knownIds.has(v))).length;
    if (coldCount === 0) return NO_RESERVATION;

    const session = await this.sessionRepository.findOne({ where: { id: sessionId } });
    if (!session) return NO_RESERVATION;

    const dayStart = startOfUtcDay(new Date());
    const ageDays = Math.floor((dayStart.getTime() - startOfUtcDay(session.createdAt).getTime()) / DAY_MS);
    const allowance = this.allowanceForAge(config.coldSchedule, ageDays);
    // A batch larger than a whole day's allowance cannot pass on any day of this rung, so a 429 with a
    // retry hint would send a client that honours it round the same refusal every day. Nothing is
    // reserved; the caller has to split the request.
    if (coldCount > allowance) {
      throw new BadRequestException(
        `Reaching ${coldCount} new contact(s) exceeds the daily allowance of ${allowance} new ` +
          `conversation(s) for a session ${ageDays} day(s) old; split the request into batches of at most ${allowance}`,
      );
    }
    // Both sources of the day's reachouts: cold chat messages (persisted rows, or the sends just
    // admitted when those are more) and prior group adds
    // (the in-memory tally). Group adds persist nothing, so without the tally they would not count
    // against themselves and the cap would reset every request.
    const coldChats = await this.countColdReachoutsToday(sessionId, dayStart);
    // The UTC day rolled over while counting: check again against the new day, so the batch is
    // reserved on (and judged by) the day it actually runs in.
    if (startOfUtcDay(new Date()).getTime() !== dayStart.getTime()) {
      return this.assertReachoutAllowed(sessionId, contactIds);
    }
    const groupToday = this.groupReachoutsToday(sessionId, dayStart);
    const usedToday = this.chatReachoutsToday(sessionId, dayStart, coldChats) + groupToday;
    if (usedToday + coldCount <= allowance) {
      // Reserved now, with no await between the check and the charge: a concurrent request must
      // see this batch as spent. The caller refunds it (refundGroupReachouts) if the engine call
      // throws, so a createGroup that 501s on whatsapp-web.js or an add the engine refuses does not
      // burn the day's cold allowance for participants never contacted.
      this.addGroupReachouts(sessionId, dayStart, coldCount);
      return { coldCount, dayStartMs: dayStart.getTime() };
    }

    // Refused only because of cold sends still held: the batch fits once they lapse, not at the next UTC day.
    const retryAfter =
      coldChats + groupToday + coldCount <= allowance
        ? secondsUntilLapsed(
            this.heldAdmissions(sessionId, dayStart)
              .filter(a => a.cold)
              .map(a => a.until),
          )
        : secondsUntilNextUtcDay();
    this.refuse('cold_daily_cap', sessionId, retryAfter, {
      reason:
        `Reaching ${coldCount} new contact(s) would exceed the daily allowance of ${allowance} ` +
        `new conversation(s) for a session ${ageDays} day(s) old (${usedToday} already used)`,
      allowance,
      coldToday: usedToday,
      coldCount,
    });
  }

  /**
   * Give back a reservation from assertReachoutAllowed after the engine call failed. Only the day it
   * was taken from is credited: once the tally has rolled over to a new UTC day, the old day's
   * reservation no longer counts against anything and the new day's tally is left alone.
   */
  refundGroupReachouts(sessionId: string, reservation: GroupReachoutReservation): void {
    if (reservation.coldCount <= 0) return;
    const tally = this.groupReachoutTally.get(sessionId);
    if (!tally || tally.dayStartMs !== reservation.dayStartMs) return;
    tally.count = Math.max(0, tally.count - reservation.coldCount);
  }

  /** Cold group-add reachouts charged to this session today (0 once the stored day rolls over). */
  private groupReachoutsToday(sessionId: string, dayStart: Date): number {
    const tally = this.groupReachoutTally.get(sessionId);
    return tally && tally.dayStartMs === dayStart.getTime() ? tally.count : 0;
  }

  /** Add to today's group-add tally, resetting it first when the stored entry is from an earlier day. */
  private addGroupReachouts(sessionId: string, dayStart: Date, n: number): void {
    const dayStartMs = dayStart.getTime();
    const tally = this.groupReachoutTally.get(sessionId);
    if (tally && tally.dayStartMs === dayStartMs) tally.count += n;
    else this.groupReachoutTally.set(sessionId, { dayStartMs, count: n });
  }

  /**
   * Record a send that failed. A run of these trips the breaker.
   *
   * Only called on failures that reached WhatsApp and came back refused — a validation error thrown
   * before the engine is asked says nothing about the account's standing and must not count, or a
   * client sending malformed requests could trip the breaker on a perfectly healthy session.
   */
  recordSendFailure(sessionId: string): void {
    const config = resolveSendPacingConfig(this.configService);
    if (!config.enabled) return;

    const breaker = this.breakerFor(sessionId);
    breaker.consecutiveFailures += 1;
    if (breaker.openedAt === null && breaker.consecutiveFailures >= config.breakerThreshold) {
      breaker.openedAt = Date.now();
      this.logger.warn(`Send breaker tripped after ${breaker.consecutiveFailures} consecutive failures`, {
        sessionId,
        consecutiveFailures: breaker.consecutiveFailures,
        cooldownMs: config.breakerCooldownMs,
        action: 'send_breaker_tripped',
      });
      // Never sampled: a trip is rare and is the event an operator most wants to find afterwards.
      void this.auditService?.logWarn(AuditAction.SEND_BREAKER_TRIPPED, {
        sessionId,
        metadata: { consecutiveFailures: breaker.consecutiveFailures, cooldownMs: config.breakerCooldownMs },
        errorMessage: `Send breaker tripped after ${breaker.consecutiveFailures} consecutive send failures`,
      });
    }
  }

  /** Record a send that succeeded, which ends any streak in progress. */
  recordSendSuccess(sessionId: string): void {
    const config = resolveSendPacingConfig(this.configService);
    if (!config.enabled) return;

    const breaker = this.breakers.get(sessionId);
    if (!breaker) return;
    // A success proves the account is being served, so the streak resets AND an open breaker closes.
    // Nothing else closes it early: the cooldown is what normally lets traffic back through.
    this.breakers.delete(sessionId);
  }

  /** The allowance for a session this many whole days old, saturating at the schedule's last entry. */
  private allowanceForAge(schedule: number[], ageDays: number): number {
    const index = Math.min(Math.max(ageDays, 0), schedule.length - 1);
    return schedule[index];
  }

  private breakerFor(sessionId: string): BreakerState {
    const existing = this.breakers.get(sessionId);
    if (existing) return existing;
    const created: BreakerState = { consecutiveFailures: 0, openedAt: null };
    this.breakers.set(sessionId, created);
    return created;
  }

  private assertBreakerClosed(sessionId: string, config: SendPacingConfig): void {
    const breaker = this.breakers.get(sessionId);
    if (!breaker?.openedAt) return;

    const elapsed = Date.now() - breaker.openedAt;
    if (elapsed >= config.breakerCooldownMs) {
      // Cooldown served. Dropping the entry rather than zeroing it is what keeps the map bounded by
      // the number of sessions currently in trouble instead of every session that ever failed — and
      // it is equivalent, since the next failure recreates it at a count of one either way.
      this.breakers.delete(sessionId);
      return;
    }
    this.refuse('breaker_open', sessionId, Math.ceil((config.breakerCooldownMs - elapsed) / 1000), {
      reason: 'Sends are paused after a run of consecutive send failures',
    });
  }

  private assertUnderDailyCap(
    sessionId: string,
    dayStart: Date,
    ageDays: number,
    allowance: number,
    persisted: number,
  ): void {
    const held = this.heldAdmissions(sessionId, dayStart);
    const sentToday = held.reduce((max, a, i) => {
      a.sentToday ??= persisted;
      return Math.max(max, a.sentToday + held.length - i);
    }, persisted);
    if (sentToday < allowance) return;

    const retryAfter =
      persisted < allowance ? secondsUntilLapsed(held.map(a => a.heldUntil)) : secondsUntilNextUtcDay();
    this.refuse('daily_cap', sessionId, retryAfter, {
      reason: `Daily send allowance of ${allowance} reached for a session ${ageDays} day(s) old`,
      allowance,
      sentToday,
    });
  }

  /**
   * Write one audit row per session per window, folding the refusals suppressed in between into the
   * next row's `suppressed` metadata — so the trail stays accurate without one write per refused
   * send. Modelled on the websocket limiter's own sampling, which exists for the same reason.
   */
  private auditRefusal(
    sessionId: string,
    rule: SendPacingRefusalReason,
    retryAfterSeconds: number,
    message: string,
  ): void {
    const now = Date.now();
    const prior = this.refusalSamples.get(sessionId);
    if (prior && now - prior.since < REFUSAL_AUDIT_WINDOW_MS) {
      prior.count += 1;
      return;
    }
    const suppressed = prior?.count ?? 0;
    // Re-insert rather than mutate, so the map stays in insertion order and the eviction below
    // really does drop the least recently audited session.
    this.refusalSamples.delete(sessionId);
    this.refusalSamples.set(sessionId, { count: 0, since: now });
    while (this.refusalSamples.size > MAX_REFUSAL_KEYS) {
      const oldest = this.refusalSamples.keys().next().value;
      if (oldest === undefined) break;
      this.refusalSamples.delete(oldest);
    }
    void this.auditService?.logWarn(AuditAction.SEND_PACING_BLOCKED, {
      sessionId,
      metadata: { rule, retryAfterSeconds, suppressed },
      errorMessage: message,
    });
  }

  /**
   * Read what the cold-reachout rule needs for this send, or null when the rule does not apply.
   *
   * "Cold" means this account has no history with the chat in EITHER direction: answering someone
   * who wrote to you first is not a reachout, and counting it as one would throttle exactly the
   * traffic WhatsApp wants to see. A chat with no `chatId` (a status post) is not addressed to
   * anyone, so the rule does not apply to it.
   *
   * The cheap probe runs first and settles most sends in one indexed lookup; the aggregate that
   * counts the day's cold reachouts only runs when this send is itself cold.
   */
  private async readColdReachouts(
    sessionId: string,
    chatId: string | undefined,
    dayStart: Date,
    ageDays: number,
    config: SendPacingConfig,
  ): Promise<{ allowance: number; coldToday: number } | null> {
    if (!chatId || config.coldSchedule.length === 0) return null;

    // Any row at all, either direction, any time: one message from them, or one from us last month,
    // and this is an existing relationship rather than a reachout. Probed under both user-id
    // dialects (see dialectVariants). The send being checked has not persisted its own row yet —
    // the gate runs before saveOutgoingMessage — so this cannot see it.
    const hasHistory = await this.messageRepository.exists({
      where: dialectVariants(chatId).map(id => ({ sessionId, chatId: id })),
    });
    if (hasHistory) return null;

    return {
      allowance: this.allowanceForAge(config.coldSchedule, ageDays),
      coldToday: await this.countColdReachoutsToday(sessionId, dayStart),
    };
  }

  /** Refuse a cold reachout once the day's allowance for them is spent. */
  private assertUnderColdCap(
    sessionId: string,
    dayStart: Date,
    ageDays: number,
    { allowance, coldToday: persisted }: { allowance: number; coldToday: number },
  ): void {
    // Group adds share this budget: a day spent adding strangers to groups must leave fewer cold
    // chat reachouts, so fold the in-memory group tally in alongside the chat count.
    const groupToday = this.groupReachoutsToday(sessionId, dayStart);
    const coldToday = this.chatReachoutsToday(sessionId, dayStart, persisted) + groupToday;
    if (coldToday < allowance) return;

    const retryAfter =
      persisted + groupToday < allowance
        ? secondsUntilLapsed(
            this.heldAdmissions(sessionId, dayStart)
              .filter(a => a.cold)
              .map(a => a.until),
          )
        : secondsUntilNextUtcDay();
    this.refuse('cold_daily_cap', sessionId, retryAfter, {
      reason: `Daily allowance of ${allowance} new conversation(s) reached for a session ${ageDays} day(s) old`,
      allowance,
      coldToday,
    });
  }

  /**
   * Distinct chats this session started today: it sent to them today, nothing in the chat predates
   * today, and nobody wrote to it first — a chat whose counterpart messaged earlier the same day is
   * an answered conversation, not a reachout (the "cold" rule above), however new the chat is.
   * Expressed as NOT EXISTS probes so the outer query stays on the `(sessionId, createdAt)` index
   * and each probe seeks `(sessionId, chatId, createdAt)`; the only aggregate is a per-chat MIN over
   * today's outgoing rows.
   */
  private countColdReachoutsToday(sessionId: string, dayStart: Date): Promise<number> {
    return (
      this.messageRepository
        .createQueryBuilder('m')
        // Counted per CONTACT, not per stored spelling: the same person reached under both user-id
        // dialects today is one reachout, and the correlated lookups below match either spelling
        // (see dialectVariants — a chat known as @s.whatsapp.net is not a stranger as @c.us).
        // REPLACE is the portable normalisation both SQLite and Postgres carry; the paired IN keeps
        // the inner side's `chatId` index usable.
        .select(`COUNT(DISTINCT REPLACE(m."chatId", '@s.whatsapp.net', '@c.us'))`, 'count')
        .where('m.sessionId = :sessionId', { sessionId })
        .andWhere('m.direction = :direction', { direction: MessageDirection.OUTGOING })
        .andWhere('m.createdAt >= :dayStart', { dayStart })
        // Identifiers are quoted because the columns really are camelCase (`"chatId"`, not `chat_id`)
        // — there is no snake_case naming strategy on this connection. Unquoted, Postgres would fold
        // them to lowercase and the query would fail at runtime on the very first cold send.
        .andWhere(
          `NOT EXISTS (SELECT 1 FROM "messages" p WHERE p."sessionId" = :sessionId AND p."chatId" IN (${DIALECT_PAIR('m')}) AND p."createdAt" < :dayStart)`,
        )
        // They wrote first: an incoming row strictly earlier than today's first outgoing one makes
        // the chat an answered conversation, not a cold start. A tie stays cold (conservative).
        .andWhere(
          `NOT EXISTS (SELECT 1 FROM "messages" i WHERE i."sessionId" = :sessionId AND i."chatId" IN (${DIALECT_PAIR('m')}) AND i."direction" = :incoming AND i."createdAt" < (SELECT MIN(o."createdAt") FROM "messages" o WHERE o."sessionId" = :sessionId AND o."chatId" IN (${DIALECT_PAIR('m')}) AND o."direction" = :direction AND o."createdAt" >= :dayStart))`,
          { incoming: MessageDirection.INCOMING },
        )
        .getRawOne<{ count: string | number }>()
        .then(row => Number(row?.count ?? 0))
    );
  }

  private refuse(
    reason: SendPacingRefusalReason,
    sessionId: string,
    retryAfterSeconds: number,
    detail: { reason: string } & Record<string, unknown>,
  ): never {
    incrementSendPacingRefusals(reason);
    this.logger.warn(`Send refused by the pacing governor: ${detail.reason}`, {
      ...detail,
      sessionId,
      rule: reason,
      retryAfterSeconds,
      action: 'send_paced',
    });
    this.auditRefusal(sessionId, reason, retryAfterSeconds, detail.reason);
    // 429 with a body `code`, which is what distinguishes this from the global throttler's own 429 —
    // a client that retries blindly on 429 would otherwise treat a day-long cap like a one-second
    // rate limit. `retryAfterSeconds` says how long the refusal actually lasts.
    throw new HttpException(
      {
        statusCode: HttpStatus.TOO_MANY_REQUESTS,
        error: 'Too Many Requests',
        message: detail.reason,
        code: SEND_PACING_LIMITED,
        retryAfterSeconds,
      },
      HttpStatus.TOO_MANY_REQUESTS,
    );
  }
}

const DAY_MS = 86_400_000;

/**
 * Both spellings of a user id. Stored rows carry either dialect — inbound rows are neutralized to
 * `@c.us`, outbound rows keep the caller's raw form — so a byte-exact history probe misreads a
 * known contact addressed the other way as cold and over-draws the budget. Non-user ids (groups,
 * lids, …) pass through unchanged; a lid has no derivable phone twin to probe.
 */
/**
 * SQL for both user-id spellings of `<alias>."chatId"`, for use as an `IN (…)` list. The same idea
 * as {@link dialectVariants}, expressed portably: REPLACE exists on SQLite and Postgres alike, and
 * for a non-user id (a group, a lid) both branches collapse to the raw value.
 */
const DIALECT_PAIR = (alias: string): string =>
  `REPLACE(${alias}."chatId", '@s.whatsapp.net', '@c.us'), REPLACE(${alias}."chatId", '@c.us', '@s.whatsapp.net')`;

/** A chat id folded the way countColdReachoutsToday folds it, so the window counts contacts alike. */
function coldChatKey(chatId: string): string {
  return chatId.replace('@s.whatsapp.net', '@c.us');
}

function dialectVariants(chatId: string): string[] {
  const lower = chatId.toLowerCase();
  if (lower.endsWith('@c.us')) {
    return [chatId, chatId.slice(0, chatId.length - '@c.us'.length) + '@s.whatsapp.net'];
  }
  if (lower.endsWith('@s.whatsapp.net')) {
    return [chatId, chatId.slice(0, chatId.length - '@s.whatsapp.net'.length) + '@c.us'];
  }
  // A bare number is a user id with the suffix left off — the group-participant endpoints accept
  // one and the engines qualify it themselves, so the history probe has to look under both
  // spellings too or a contact the account already knows is charged as a stranger.
  if (/^\d{5,}$/.test(chatId.trim())) {
    const digits = chatId.trim();
    return [digits, `${digits}@c.us`, `${digits}@s.whatsapp.net`];
  }
  return [chatId];
}

/**
 * The cap's day boundary is UTC, not the server's local midnight: a deployment that moves timezone,
 * or replicas in different ones, must not disagree about when the allowance resets.
 */
function startOfUtcDay(at: Date): Date {
  return new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate()));
}

/**
 * Seconds until every one of these held admissions could have lapsed, given the epoch ms each one's hold
 * ends: when the persisted count alone is under the cap, the refusal lifts then, not at the next UTC day.
 * One still unsettled lapses a window after its settle at the earliest, so it is hinted as if it settled now.
 */
function secondsUntilLapsed(holdEnds: number[]): number {
  const now = Date.now();
  const last = holdEnds.reduce((max, end) => Math.max(max, Math.min(end, now + ADMISSION_WINDOW_MS)), now);
  return Math.max(1, Math.ceil((last - now) / 1000));
}

function secondsUntilNextUtcDay(): number {
  const now = Date.now();
  return Math.max(1, Math.ceil((startOfUtcDay(new Date(now)).getTime() + DAY_MS - now) / 1000));
}