Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

10.9 KB
Raw Blame
import type { NewsletterMetadata, WASocket } from '@whiskeysockets/baileys';
import { Channel } from '../interfaces/whatsapp-engine.interface';
import { ChannelNotFoundError } from '../../common/errors/channel-not-found.error';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { mapServerRefusal } from './baileys-groups';
import { BAILEYS_QUERY_BUDGET_MS, withQueryDeadline } from './baileys-query-deadline';

/**
 * Channel-domain operations extracted from BaileysAdapter. The adapter keeps the public
 * methods as thin forwarders and injects this narrow host surface via closures, so the
 * delegate never touches lifecycle state directly.
 */
export interface BaileysChannelsHost {
  ensureReady(): void;
  /** Post-ensureReady socket handle — call host.ensureReady() first. */
  getSocket(): WASocket;
  /**
   * Neutral → engine jid dialect. Channel ids need no mapping (`@newsletter` in both), but the
   * admin writes take a USER jid, which does.
   */
  toEngineJid(jid: string): string;
}

/**
 * WA error code of a w:mex refusal, or undefined for anything else.
 *
 * executeWMexQuery (lib/Socket/mex.js) parses a GraphQL payload out of a SUCCESSFUL iq, so a
 * refusal never reaches assertNodeErrorFree and never carries the numeric `data` refusedStatusCode
 * reads. It throws `Boom(msg, { statusCode: errorCode, data: firstError })` instead — the code on
 * the Boom, the error node as `data`.
 *
 * The discriminator is a `data` that is a GraphQL error node, one carrying `message` or
 * `extensions`. Any object is not enough: promiseTimeout (Utils/generics.js) rejects a stalled send
 * or an unanswered query with `Boom('Timed Out', { statusCode: 408, data: { stack } })`, and
 * executeWMexQuery's OTHER throw carries the raw result node as `data`. Both are transport
 * failures, and reading their 4xx code as a refusal would turn a stalled socket into a 403 or 404.
 */
export function wmexRefusalCode(error: unknown): number | undefined {
  const err = error as { data?: unknown; output?: { statusCode?: unknown } } | null | undefined;
  if (typeof err?.data === 'number') {
    return err.data;
  }
  const node = err?.data as { message?: unknown; extensions?: unknown } | null | undefined;
  const isGraphQlError = typeof node === 'object' && node !== null && ('message' in node || 'extensions' in node);
  if (isGraphQlError && typeof err?.output?.statusCode === 'number') {
    return err.output.statusCode;
  }
  return undefined;
}

/**
 * `thread_metadata` as newsletterMetadata actually returns it (recorded live in
 * scripts/patch-baileys-newsletter-create.spec.js). The .d.ts types it as the flattened create shape.
 */
interface RawNewsletterThread {
  name?: { text?: string } | null;
  description?: { text?: string } | null;
  invite?: string;
  subscribers_count?: string;
  verification?: 'VERIFIED' | 'UNVERIFIED';
  creation_time?: string;
}

/** A wire number that may come as a string, or as NaN from the create parser; undefined unless finite. */
function finiteNumber(value: number | string | undefined): number | undefined {
  const n = typeof value === 'string' ? Number.parseInt(value, 10) : value;
  return n !== undefined && Number.isFinite(n) ? n : undefined;
}

export class BaileysChannels {
  constructor(
    private readonly host: BaileysChannelsHost,
    private readonly queryBudgetMs: number = BAILEYS_QUERY_BUDGET_MS,
  ) {}

  /**
   * Bound a channel call. executeWMexQuery throws Boom(..., { statusCode: 400, data: result }) when
   * nothing came back, and with result undefined Boom normalises data to null — so the refusal
   * classifier cannot place it and the raw Boom escapes as a bare 500.
   */
  private bounded<T>(work: Promise<T>, operation: string): Promise<T> {
    return withQueryDeadline(work, this.queryBudgetMs, `WhatsApp did not answer ${operation} in time`);
  }

  /** Post-ensureReady socket handle. */
  private sock(): WASocket {
    return this.host.getSocket();
  }

  async getChannelById(channelId: string): Promise<Channel | null> {
    this.host.ensureReady();
    // newsletterMetadata resolves ANY channel by jid (richer than the wwjs subscribed-list lookup).
    const meta = await this.lookup('jid', channelId, 'the channel lookup');
    return meta ? this.toChannel(meta) : null;
  }

  async subscribeToChannel(inviteCode: string): Promise<Channel> {
    this.host.ensureReady();
    const meta = await this.lookup('invite', inviteCode, 'the invite lookup');
    if (!meta) {
      throw new ChannelNotFoundError(inviteCode);
    }
    await mapServerRefusal(
      'Subscribing to the channel',
      () => this.bounded(this.sock().newsletterFollow(meta.id), 'the channel subscribe'),
      wmexRefusalCode,
    );
    return this.toChannel(meta);
  }

  /**
   * A channel lookup that WhatsApp refuses (an unknown id, a bad invite code) comes back as a w:mex
   * GraphQL error rather than an empty node, so a 4xx refusal is read as "no such channel", the same
   * way the group invite lookup reads one. A rate limit (429) or a timeout (408) says nothing about
   * the channel, so it answers 503, as the deadline does.
   */
  private async lookup(type: 'jid' | 'invite', key: string, operation: string) {
    try {
      return await this.bounded(this.sock().newsletterMetadata(type, key), operation);
    } catch (error) {
      const code = wmexRefusalCode(error);
      if (code === 408 || code === 429) {
        throw new EngineTransportError(`WhatsApp rate-limited or timed out ${operation} (code ${code})`);
      }
      if (code !== undefined && code >= 400 && code < 500) {
        return null;
      }
      throw error;
    }
  }

  /**
   * Deliberately NOT bounded, unlike every other call here: creating a channel is non-idempotent,
   * and 503 is a backpressure status the Go SDK retries three times for POST (sdk/go/retry.go).
   * A deadline abandons without cancelling, so a slow-but-succeeding create could leave duplicates.
   * An unanswered query therefore still surfaces opaquely rather than as something retryable, and so
   * does WA code 408: a server timeout does not say whether the channel was created.
   */
  async createChannel(name: string, description?: string): Promise<Channel> {
    this.host.ensureReady();
    const meta = await mapServerRefusal(
      'Creating the channel',
      () => this.sock().newsletterCreate(name, description),
      error => {
        const code = wmexRefusalCode(error);
        return code === 408 ? undefined : code;
      },
    );
    return this.toChannel(meta);
  }

  /**
   * Demote a channel admin back to a plain subscriber. `userId` arrives in the NEUTRAL dialect and
   * is mapped here, the way the contact and messaging delegates map theirs.
   *
   * There is no promote counterpart to pair this with, and that is upstream rather than ours:
   * Baileys exposes `newsletterDemote`, `newsletterChangeOwner` and `newsletterAdminCount` but no
   * promote, and whatsapp-web.js has no `promoteChannelAdmin` at all. An admin is promoted from the
   * WhatsApp app and can then be demoted through this API.
   */
  async demoteChannelAdmin(channelId: string, userId: string): Promise<void> {
    this.host.ensureReady();
    const userJid = this.host.toEngineJid(userId);
    await mapServerRefusal(
      'Demoting the channel admin',
      () => this.bounded(this.sock().newsletterDemote(channelId, userJid), 'the channel admin demotion'),
      wmexRefusalCode,
    );
  }

  /**
   * Hand the channel to a new owner. IRREVERSIBLE: the account stops being the owner and cannot
   * take it back through this API.
   *
   * Bounded, unlike `createChannel` above. That one stays unbounded because a retried create leaves
   * a duplicate channel behind; here a retry after a transfer that actually landed is refused, since
   * the account no longer owns the channel. So the deadline costs an ambiguous 503 ("may or may not
   * have applied") and buys a request that ends.
   */
  async transferChannelOwnership(channelId: string, newOwnerId: string): Promise<void> {
    this.host.ensureReady();
    const newOwnerJid = this.host.toEngineJid(newOwnerId);
    await mapServerRefusal(
      'Transferring the channel ownership',
      () => this.bounded(this.sock().newsletterChangeOwner(channelId, newOwnerJid), 'the channel ownership transfer'),
      wmexRefusalCode,
    );
  }

  async deleteChannel(channelId: string): Promise<void> {
    this.host.ensureReady();
    await mapServerRefusal(
      'Deleting the channel',
      () => this.bounded(this.sock().newsletterDelete(channelId), 'the channel delete'),
      wmexRefusalCode,
    );
  }

  async muteChannel(channelId: string, mute: boolean): Promise<void> {
    this.host.ensureReady();
    await mapServerRefusal(
      mute ? 'Muting the channel' : 'Unmuting the channel',
      () =>
        this.bounded(
          mute ? this.sock().newsletterMute(channelId) : this.sock().newsletterUnmute(channelId),
          mute ? 'the channel mute' : 'the channel unmute',
        ),
      wmexRefusalCode,
    );
  }

  async unsubscribeFromChannel(channelId: string): Promise<void> {
    this.host.ensureReady();
    // Unfollowing a channel the account no longer follows is refused like the other channel writes,
    // on either refusal channel, and answers the documented 403 as whatsapp-web.js does.
    await mapServerRefusal(
      'Unsubscribing from the channel',
      () => this.bounded(this.sock().newsletterUnfollow(channelId), 'the channel unsubscribe'),
      wmexRefusalCode,
    );
  }

  /**
   * Map a channel to the neutral Channel shape (optionals only when present).
   *
   * Two shapes arrive here. newsletterCreate flattens its response (parseNewsletterCreateResponse),
   * but newsletterMetadata returns the raw GraphQL node untouched: fields nested under
   * `thread_metadata`, name and description as `{ text }`, counts and timestamps as strings. The
   * flat fields are read first and the nested ones fill the gaps. The flat parse uses parseInt, so
   * a missing number arrives as NaN and is dropped rather than serialized as null.
   *
   * No `picture`: neither shape carries a URL, only a CDN direct path.
   */
  private toChannel(meta: NewsletterMetadata): Channel {
    const thread = meta.thread_metadata as RawNewsletterThread | undefined;
    const description = meta.description ?? thread?.description?.text;
    const invite = meta.invite ?? thread?.invite;
    const subscriberCount = finiteNumber(meta.subscribers) ?? finiteNumber(thread?.subscribers_count);
    const verification = meta.verification ?? thread?.verification;
    const createdAt = finiteNumber(meta.creation_time) ?? finiteNumber(thread?.creation_time);
    return {
      id: meta.id,
      name: meta.name ?? thread?.name?.text ?? '',
      ...(description ? { description } : {}),
      ...(invite ? { inviteCode: invite } : {}),
      ...(subscriberCount !== undefined ? { subscriberCount } : {}),
      ...(verification ? { verified: verification === 'VERIFIED' } : {}),
      ...(createdAt !== undefined ? { createdAt } : {}),
    };
  }
}