Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

11.8 KB
Raw Blame
/**
 * Injectable HTTP transport for the OpenWA SDK.
 *
 * The client never calls `globalThis.fetch` directly. Instead it accepts a
 * `FetchLike` implementation (defaulting to the global `fetch`). This makes the
 * SDK trivially testable — a test passes a recorder as `fetch` instead of
 * monkey-patching globals — and lets consumers intercept/observability-wrap
 * outbound calls.
 *
 * @packageDocumentation
 */

import { classifyApiError, OpenWAApiError, OpenWATimeoutError } from './errors.js';

/** Subset of the WHATWG `fetch` signature the SDK relies on. */
export type FetchLike = typeof globalThis.fetch;

export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

export interface RequestOptions {
  method: HttpMethod;
  /** Full path beginning with `/`, e.g. `/api/sessions`; any other path is refused and nothing is sent. */
  path: string;
  /** Query parameters, serialized into the URL. */
  query?: object;
  /** JSON-serializable request body. */
  body?: unknown;
  /** Override the per-client timeout (ms) for this single request; `0` or `Infinity` turns it off. */
  timeoutMs?: number;
  /** Extra headers merged on top of the client defaults (auth/JSON win). */
  headers?: Record<string, string>;
}

export interface ClientConfig {
  /** Base URL of the OpenWA API, e.g. `http://localhost:2785`. */
  baseUrl: string;
  /** API key sent as `X-API-Key`. */
  apiKey: string;
  /** Per-request timeout in milliseconds (default 30000); `0` or `Infinity` turns it off. */
  timeoutMs?: number;
  /** Default headers applied to every request. */
  defaultHeaders?: Record<string, string>;
  /** Injectable transport; defaults to the global `fetch`. */
  fetch?: FetchLike;
}

/** Stands in for an empty or dot id; encodeURIComponent output never contains it. */
const BLANK_SEGMENT = '\u0000';

/**
 * Percent-encode a single path segment (e.g. a chat/message id) so a value
 * containing `/`, `#`, `?` or whitespace can't break out of its path position.
 * WhatsApp-id characters that are already path-safe (`@`, `:`, `+`) are kept
 * readable.
 *
 * An empty, `.` or `..` segment becomes {@link BLANK_SEGMENT}, which `send()`
 * rejects: fetch resolves dot segments before sending, and an empty one means
 * a required id was blank, so either would reach the parent resource instead
 * of the intended one. Marking it here rather than throwing keeps the refusal
 * a rejection of the returned promise, since resource methods are not async.
 */
export function encodeSegment(segment: string | number): string {
  const text = String(segment);
  if (text === '' || text === '.' || text === '..') return BLANK_SEGMENT;
  return encodeURIComponent(text).replace(/%40/g, '@').replace(/%3A/g, ':').replace(/%2B/g, '+');
}

/** Build a URL with serialized query params, omitting `undefined`/`null` values. */
export function buildUrl(baseUrl: string, path: string, query?: object): string {
  const base = baseUrl.replace(/\/$/, '');
  if (!query) return `${base}${path}`;
  const params = new URLSearchParams();
  for (const [key, value] of Object.entries(query)) {
    if (value === undefined || value === null) continue;
    params.append(key, String(value));
  }
  const qs = params.toString();
  if (!qs) return `${base}${path}`;
  // A raw path may already carry a query string; extend it rather than start a second one. The values go
  // ahead of any fragment, since fetch drops everything after a '#' and the server would never see them.
  const hash = path.indexOf('#');
  const head = hash === -1 ? path : path.slice(0, hash);
  return `${base}${head}${head.includes('?') ? '&' : '?'}${qs}${hash === -1 ? '' : path.slice(hash)}`;
}

/**
 * Perform a single request against the OpenWA API and return the parsed JSON
 * body (or `null` for 204). Throws a typed {@link OpenWAApiError} subclass on
 * non-2xx, or {@link OpenWATimeoutError} on timeout.
 */
export async function request<T>(
  config: Required<Omit<ClientConfig, 'fetch'>> & { fetch: FetchLike },
  options: RequestOptions,
): Promise<T> {
  return send(config, options, async res => {
    if (res.status === 204) {
      return null as T;
    }
    const text = await res.text();
    if (!text) return null as T;
    try {
      return JSON.parse(text) as T;
    } catch {
      return text as unknown as T;
    }
  });
}

/** A binary (non-JSON) 2xx body, e.g. the stored status media bytes. */
export interface BinaryResponse {
  data: Uint8Array;
  contentType: string | null;
}

/**
 * Like {@link request}, but for endpoints that stream raw bytes instead of
 * JSON (e.g. status media). Returns the body verbatim plus the served
 * Content-Type; a 204/empty body resolves to zero-length data.
 */
export async function requestBytes(
  config: Required<Omit<ClientConfig, 'fetch'>> & { fetch: FetchLike },
  options: RequestOptions,
): Promise<BinaryResponse> {
  return send(config, options, async res => {
    if (res.status === 204) {
      return { data: new Uint8Array(0), contentType: null };
    }
    return { data: new Uint8Array(await res.arrayBuffer()), contentType: res.headers.get('content-type') };
  });
}

/**
 * Whether a header value holds a character fetch cannot send: a control character other than a tab, or one
 * above U+00FF. Checked at construction so that the refusal names the header and never repeats the value,
 * which the transport's own TypeError does, and a credential would reach the application's log with it.
 */
export function hasUnsendableChar(value: string): boolean {
  return /[\u0000-\u0008\u000a-\u001f\u007f\u0100-\uffff]/.test(value);
}

/**
 * A timeout in milliseconds, coerced once: untyped JS config can pass a numeric string (process.env).
 * `0` or `Infinity` turns the timeout off, so any other value that is not a non-negative number (an
 * empty variable, `30s`) is refused rather than read as "off", which would let a request hang forever.
 */
export function toTimeoutMs(value: unknown): number {
  const ms = typeof value === 'string' && value.trim() === '' ? NaN : Number(value);
  if (Number.isNaN(ms) || ms < 0) {
    throw new TypeError(
      `OpenWA: timeoutMs must be a non-negative number of milliseconds, got ${JSON.stringify(value)}`,
    );
  }
  return ms;
}

/**
 * Shared transport for {@link request} and {@link requestBytes}: builds the
 * URL/headers, performs the fetch under the per-request timeout, translates a
 * non-2xx into a typed error, then hands the response to `consume` — still
 * inside the timeout window, so a stalled body read aborts too.
 */
async function send<T>(
  config: Required<Omit<ClientConfig, 'fetch'>> & { fetch: FetchLike },
  options: RequestOptions,
  consume: (res: Response) => Promise<T>,
): Promise<T> {
  // The path is appended to the base URL, so one without a leading `/` could move the host
  // (`.example.net/x`, `@example.net/x`) and send the API key there.
  if (!options.path.startsWith('/')) {
    throw new TypeError(`OpenWA: path must begin with "/": ${JSON.stringify(options.path)}`);
  }
  if (options.path.includes(BLANK_SEGMENT)) {
    throw new TypeError(`OpenWA: empty or dot path segment in ${JSON.stringify(options.path)}`);
  }
  const url = buildUrl(config.baseUrl, options.path, options.query);
  // fetch resolves `.` and `..` segments before sending, so such a segment would reach the parent
  // resource instead of the intended one. Mirror the URL parser: it drops tab and newline, reads `\`
  // as `/`, treats %2e as a dot, and trims trailing C0 controls and spaces, which end the path only
  // when no query or fragment follows it. Empty segments, such as a trailing slash, are sent as
  // written; a blank id is refused above.
  const tail = url.slice(config.baseUrl.replace(/\/$/, '').length);
  const rawPath = tail.split(/[?#]/, 1)[0];
  let pathOnly = rawPath.replace(/[\t\n\r]/g, '');
  if (rawPath.length === tail.length) pathOnly = pathOnly.replace(/[\x00-\x20]+$/, '');
  for (const segment of pathOnly.split(/[/\\]/).slice(1)) {
    const dots = segment.replace(/%2e/gi, '.');
    if (dots === '.' || dots === '..') {
      throw new TypeError(`OpenWA: dot path segment in ${JSON.stringify(options.path)}`);
    }
  }
  // fetch upper-cases GET, POST, PUT and DELETE itself but sends PATCH and any other verb as written, and the
  // gateway answers 400 to a lowercase method; a caller without the HttpMethod type can pass one. A missing
  // method stays undefined, which fetch sends as GET. Read before the timer is armed: a value that is not a
  // string throws here, and nothing would clear the timer.
  const method = options.method?.toUpperCase();
  const timeoutMs = toTimeoutMs(options.timeoutMs ?? config.timeoutMs);

  const controller = new AbortController();
  // 0 or Infinity means no client timeout. setTimeout fires after 1 ms for a delay that is not
  // finite or exceeds 2^31-1, so cap it rather than abort every request.
  const timer =
    Number.isFinite(timeoutMs) && timeoutMs > 0
      ? setTimeout(() => controller.abort(), Math.min(timeoutMs, 2_147_483_647))
      : undefined;

  // Auth and JSON content-type WIN over caller-supplied defaults/per-request headers — the SDK only
  // ever sends a JSON body, and this matches the Python and PHP SDKs (which force JSON) and the
  // documented "JSON headers win" contract. Header names are case-insensitive and fetch joins duplicates,
  // so merge by lowercased name (a per-request header replaces a default in any case) and drop a
  // caller's copy of ours before adding them; putting ours last is not enough.
  const merged = new Map<string, [string, string]>();
  for (const [name, value] of [...Object.entries(config.defaultHeaders), ...Object.entries(options.headers ?? {})]) {
    const lower = name.toLowerCase();
    if (lower !== 'content-type' && lower !== 'x-api-key') merged.set(lower, [name, value]);
  }
  const headers: Record<string, string> = Object.fromEntries(merged.values());
  headers['Content-Type'] = 'application/json';
  headers['X-API-Key'] = config.apiKey;

  // Called without a receiver: a platform fetch passed in as `fetch: globalThis.fetch` throws
  // "Illegal invocation" in browsers and Workers when invoked as a method of `config`.
  const doFetch = config.fetch;
  try {
    const res = await doFetch(url, {
      method,
      headers,
      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
      signal: controller.signal,
      // Never auto-follow redirects: doing so would re-send the X-API-Key header
      // to the redirect target (potentially a different origin). A 3xx surfaces
      // as a non-2xx error instead.
      redirect: 'manual',
    });

    if (!res.ok) {
      const context = `${method} ${options.path}`;
      const apiError = await OpenWAApiError.fromResponse(res, context);
      throw classifyApiError(apiError.status, apiError.message, apiError.body, apiError.errorKind, apiError.headers);
    }

    return await consume(res);
  } catch (err) {
    if (err instanceof Error && err.name === 'AbortError') {
      throw new OpenWATimeoutError(timeoutMs);
    }
    throw err;
  } finally {
    clearTimeout(timer);
  }
}

const LOCALHOST_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);

/**
 * Warn (NOT throw) when a URL is `http://` and the host is not localhost. The API key is sent as
 * an `X-API-Key` header on every request — over plaintext http to a non-local host that's cleartext
 * on the wire. Warning (not refusing) keeps local dev and TLS-terminating-proxy topologies working.
 */
export function warnIfInsecureHttpUrl(url: string, label = 'baseUrl'): void {
  try {
    const parsed = new URL(url);
    if (parsed.protocol === 'http:' && !LOCALHOST_HOSTS.has(parsed.hostname.toLowerCase())) {
      console.warn(
        `[OpenWA SDK] ${label} uses an insecure http:// URL (host: ${parsed.hostname}). ` +
          'The API key will be sent in cleartext. Use https:// in production.',
      );
    }
  } catch {
    // Unparseable — the request will fail downstream with a clear error.
  }
}