@pingroom/sdk 0.8.0 → 0.9.0

package/src/internal/guards.ts

@@ -0,0 +1,129 @@
+import { PingRoomError } from '../errors.js';
+
+/** Mirrors the server's structured-`data` limits so oversized payloads fail fast, locally. */
+export const MAX_DATA_BYTES = 8 * 1024;
+export const MAX_DATA_KEYS = 25;
+export const MAX_PRIVATE_PING_MESSAGE_LENGTH = 120;
+export const MAX_PUBLIC_PING_MESSAGE_LENGTH = 160;
+export const MAX_PING_TITLE_LENGTH = 40;
+
+/** Count Unicode code points, matching Laravel's multibyte string validation. */
+function characterLength(value: string): number {
+  return Array.from(value).length;
+}
+
+export function assertMaxLength(value: unknown, max: number, field: string): void {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (typeof value !== 'string') {
+    throw new PingRoomError(`\`${field}\` must be a string.`, { code: 'invalid_request' });
+  }
+  const length = characterLength(value);
+  if (length > max) {
+    throw new PingRoomError(
+      `\`${field}\` may have at most ${max} characters (got ${length}).`,
+      { code: 'invalid_request' },
+    );
+  }
+}
+
+/**
+ * Bytes a JSON string takes as PHP's default json_encode() writes it, which is
+ * what the server's 8 KB cap measures: every non-ASCII UTF-16 unit becomes a
+ * six-byte `\uXXXX` escape and `/` becomes `\/`. Non-Latin text is several
+ * times larger there than its UTF-8 size.
+ */
+export function serverJsonByteLength(json: string): number {
+  let bytes = 0;
+  for (let index = 0; index < json.length; index += 1) {
+    const code = json.charCodeAt(index);
+    if (code > 0x7f) bytes += 6;
+    else if (code === 0x2f) bytes += 2;
+    else bytes += 1;
+  }
+  return bytes;
+}
+
+export function assertStructuredData(data: unknown): void {
+  if (data === undefined || data === null) {
+    return;
+  }
+  if (typeof data !== 'object' || Array.isArray(data)) {
+    throw new PingRoomError('`data` must be a JSON object (not an array or scalar).', { code: 'invalid_data' });
+  }
+  const keys = Object.keys(data as object);
+  if (keys.length > MAX_DATA_KEYS) {
+    throw new PingRoomError(`\`data\` may have at most ${MAX_DATA_KEYS} keys (got ${keys.length}).`, { code: 'invalid_data' });
+  }
+  let encoded: string;
+  try {
+    encoded = JSON.stringify(data);
+  } catch {
+    throw new PingRoomError('`data` must be JSON-serializable.', { code: 'invalid_data' });
+  }
+  const bytes = serverJsonByteLength(encoded);
+  if (bytes > MAX_DATA_BYTES) {
+    throw new PingRoomError(`\`data\` is too large (${bytes} bytes, max ${MAX_DATA_BYTES}).`, { code: 'invalid_data' });
+  }
+}
+
+export function assertActionNumber(n: unknown): void {
+  if (n === undefined || n === null) {
+    return;
+  }
+  if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > 16) {
+    throw new PingRoomError('action_number must be an integer 1–16.', { code: 'invalid_request' });
+  }
+}
+
+const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/** PHP trim()'s default set: what the server strips from both ends of a key. */
+const SERVER_TRIM = /^[ \t\n\r\0\x0B]+|[ \t\n\r\0\x0B]+$/g;
+
+/**
+ * Normalize an idempotency key the way the server reads it
+ * (`RequestIdempotency::keyFrom`): trimmed, then 1–255 characters. It travels
+ * as the `Idempotency-Key` header, so it must also be printable ASCII (space
+ * included): fetch throws on a character outside Latin-1, which surfaced as a
+ * retryable `network_error` that every retry repeated, and a Latin-1 byte above
+ * 0x7E reaches the server as invalid UTF-8.
+ */
+export function normalizeIdempotencyKey(value: unknown, field = 'idempotencyKey'): string {
+  if (typeof value !== 'string') {
+    throw new PingRoomError(`\`${field}\` must be a string.`, { code: 'invalid_request' });
+  }
+  const key = value.replace(SERVER_TRIM, '');
+  if (key.length < 1 || key.length > MAX_IDEMPOTENCY_KEY_LENGTH || !/^[\x20-\x7E]+$/.test(key)) {
+    throw new PingRoomError(
+      `\`${field}\` must be 1–${MAX_IDEMPOTENCY_KEY_LENGTH} printable ASCII characters (letters, digits, punctuation or spaces).`,
+      { code: 'invalid_request' },
+    );
+  }
+  return key;
+}
+
+export function requireNonEmpty(value: unknown, field: string): void {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new PingRoomError(`\`${field}\` is required.`, { code: 'invalid_request' });
+  }
+}
+
+/** Validate before uppercasing so Unicode case expansion cannot become a code. */
+export function normalizeRedeemCode(value: unknown): string {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9]{12}$/.test(value.trim())) {
+    throw new PingRoomError('The code must contain exactly 12 letters or digits.', { code: 'invalid_request' });
+  }
+  return value.trim().toUpperCase();
+}
+
+/**
+ * The field must be sent, but may be empty — the server rule is `present`,
+ * not `required`. A quick action's `label` is the case: a Ping can be named by
+ * its emoji alone, so `''` is a deliberate value rather than a missing one.
+ */
+export function requirePresentString(value: unknown, field: string): void {
+  if (typeof value !== 'string') {
+    throw new PingRoomError(`\`${field}\` must be a string.`, { code: 'invalid_request' });
+  }
+}

package/src/internal/request.ts

@@ -0,0 +1,97 @@
+// Request building shared by the PingRoom namespaces: path segments, bodies,
+// the Idempotency-Key header, ping input checks and long-poll timing.
+
+import { PingRoomError } from '../errors.js';
+import {
+  assertActionNumber,
+  assertMaxLength,
+  assertStructuredData,
+  MAX_PING_TITLE_LENGTH,
+  MAX_PUBLIC_PING_MESSAGE_LENGTH,
+  normalizeIdempotencyKey,
+  requireNonEmpty,
+} from './guards.js';
+import type { PingInput } from '../types.js';
+
+/** Extra wall-clock allowance over the server's hold window for long-poll calls. */
+const LONG_POLL_BUFFER_MS = 10_000;
+const DEFAULT_WAIT_SECONDS = 20;
+
+/**
+ * Minimum spacing between the starts of two handoff-wait polls. The route is
+ * throttled at 30 requests a minute per human; a short or zero `timeout`
+ * would otherwise let one loop exhaust it.
+ */
+export const MIN_HANDOFF_POLL_INTERVAL_MS = 2100;
+/**
+ * Minimum spacing between the starts of two `listen()` polls after an empty
+ * answer. `notifications/wait` is throttled at 30 requests a minute per human,
+ * shared with every other listener on the account (the CLI, other agents); a
+ * zero hold or a proxy that answers early would otherwise spin the loop and
+ * keep that bucket exhausted. Same floor as the handoff wait.
+ */
+export const MIN_LISTEN_POLL_INTERVAL_MS = MIN_HANDOFF_POLL_INTERVAL_MS;
+/**
+ * Minimum spacing between the starts of two approval or question wait polls.
+ * The server normally holds each one, but a proxy or a zero hold that answers
+ * `pending` at once would otherwise spin the loop and keep that route's
+ * 30-per-minute bucket for the human exhausted. Same floor as the handoff wait and the
+ * CLI (2100 ms keeps one loop under 30 a minute).
+ */
+export const MIN_WAIT_POLL_INTERVAL_MS = MIN_HANDOFF_POLL_INTERVAL_MS;
+
+export function enc(segment: string): string {
+  // encodeURIComponent leaves `.` and `..` alone, and URL parsing then
+  // resolves them as dot segments: `live.get('AB12', '..')` would request the
+  // room itself. No id is empty or a dot segment, so refuse them.
+  if (segment === '' || segment === '.' || segment === '..') {
+    throw new PingRoomError('A path parameter may not be empty, `.` or `..`.', { code: 'invalid_request' });
+  }
+  return encodeURIComponent(segment);
+}
+
+/**
+ * Lift the SDK-only `idempotencyKey` out of an input and into the
+ * `Idempotency-Key` header the server reads. The server trims the key and
+ * accepts 1–255 characters; as a header it must also be printable ASCII.
+ */
+export function splitIdempotencyKey<T extends { idempotencyKey?: string }>(
+  input: T,
+): { body: Omit<T, 'idempotencyKey'>; headers?: Record<string, string> } {
+  const { idempotencyKey, ...body } = input;
+  if (idempotencyKey === undefined) {
+    return { body };
+  }
+  return { body, headers: { 'Idempotency-Key': normalizeIdempotencyKey(idempotencyKey) } };
+}
+
+/** `onRetry`, when given, must be callable: a TypeError mid-outage would hide the real failure. */
+export function assertOnRetry(onRetry: unknown): void {
+  if (onRetry !== undefined && typeof onRetry !== 'function') {
+    throw new PingRoomError('`onRetry` must be a function.', { code: 'invalid_request' });
+  }
+}
+
+export function dropUndefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) {
+      out[k] = v;
+    }
+  }
+  return out as Partial<T>;
+}
+
+export function assertPing(ping: PingInput): void {
+  requireNonEmpty(ping.message, 'message');
+  // The invite code does not expose room visibility. Permit the public-room
+  // ceiling locally; Laravel applies 120 for private and 160 for public rooms.
+  assertMaxLength(ping.message, MAX_PUBLIC_PING_MESSAGE_LENGTH, 'message');
+  assertMaxLength(ping.title, MAX_PING_TITLE_LENGTH, 'title');
+  assertActionNumber(ping.action_number);
+  assertStructuredData(ping.data);
+}
+
+export function waitTimeoutMs(seconds: number | undefined): number {
+  return (seconds ?? DEFAULT_WAIT_SECONDS) * 1000 + LONG_POLL_BUFFER_MS;
+}

package/src/internal/retry.ts

@@ -0,0 +1,157 @@
+import { PingRoomError } from '../errors.js';
+import { sleep, throwIfAborted } from './async.js';
+
+/** First retry delay after a transient failure, in ms. */
+export const TRANSIENT_BACKOFF_BASE_MS = 1000;
+/**
+ * The smallest backoff base, whatever a caller asks for. A persistent failure
+ * would otherwise retry in a tight loop (a base of 0 never grows at all)
+ * against wait routes limited to 30 requests a minute each.
+ */
+export const MIN_TRANSIENT_BACKOFF_MS = 250;
+/** Ceiling on the exponential backoff (a server Retry-After may ask for longer). */
+export const TRANSIENT_BACKOFF_CAP_MS = 30_000;
+/** setTimeout fires immediately above this, so no delay may exceed it. */
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * How long past the last-seen `expires_at` a wait keeps retrying an
+ * unreachable API. The server reports `expired` once expires_at passes, so
+ * after this the only outcome left is one that cannot be read. Covers clock
+ * skew. Same bound as the CLI.
+ */
+export const WAIT_EXPIRY_GRACE_MS = 5 * 60_000;
+/** The bound on an unbroken outage while no response has carried `expires_at`. */
+export const WAIT_UNKNOWN_EXPIRY_OUTAGE_MS = 15 * 60_000;
+
+/**
+ * A failure a read loop may retry: a dropped connection, a request deadline,
+ * a 429 (each wait route has its own 30/min bucket per human), or a 5xx.
+ * Everything else — 401/403/404/422, a refused redirect, a malformed response —
+ * is permanent and must surface to the caller.
+ */
+export function isTransientError(error: unknown): error is PingRoomError {
+  return (
+    error instanceof PingRoomError
+    && (error.code === 'network_error'
+      || error.code === 'timeout'
+      || error.status === 429
+      || error.status >= 500)
+  );
+}
+
+/**
+ * Delay before retrying after the `failures`-th consecutive transient failure:
+ * exponential from `baseMs`, capped at 30 s. A server `retryAfter` replaces the
+ * exponential step, but is never waited for less than `baseMs`. A `baseMs`
+ * below {@link MIN_TRANSIENT_BACKOFF_MS} is raised to it.
+ */
+export function transientDelayMs(
+  error: PingRoomError,
+  failures: number,
+  baseMs: number = TRANSIENT_BACKOFF_BASE_MS,
+): number {
+  const requested = Number.isFinite(baseMs) && baseMs >= 0 ? baseMs : TRANSIENT_BACKOFF_BASE_MS;
+  const base = Math.max(MIN_TRANSIENT_BACKOFF_MS, requested);
+  const retryAfter = error.retryAfter;
+  if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter >= 0) {
+    return Math.min(MAX_TIMER_MS, Math.max(retryAfter * 1000, base));
+  }
+  // Enough doublings to pass the cap from any base; also keeps 2 ** step finite.
+  const step = Math.min(Math.max(0, failures - 1), 30);
+  return Math.min(MAX_TIMER_MS, Math.max(base, TRANSIENT_BACKOFF_CAP_MS), base * 2 ** step);
+}
+
+export interface PollUntilSettledOptions<T> {
+  /** One bounded long-poll. Its errors are retried only when transient. */
+  poll: () => Promise<unknown>;
+  /** Check the response's minimal shape; throw `invalid_response` otherwise. */
+  validate: (value: unknown) => T;
+  /** True once the validated value is terminal. */
+  settled: (value: T) => boolean;
+  signal?: AbortSignal;
+  /** Minimum time between the starts of two polls, in ms. Default 0. */
+  minIntervalMs?: number;
+  /** Read `expires_at` (an ISO time) from a validated response; it bounds an outage. */
+  expiresAt?: (value: T) => unknown;
+  /** Names what is waited on in the give-up message, e.g. `approval a1`. */
+  what: string;
+  /** Called before each retry of a transient failure; `attempt` counts consecutive failures from 1. */
+  onRetry?: (error: PingRoomError, attempt: number) => void;
+}
+
+function timeOf(value: unknown): number | null {
+  const at = typeof value === 'string' ? Date.parse(value) : NaN;
+  return Number.isFinite(at) ? at : null;
+}
+
+function unavailable(last: PingRoomError, since: number, what: string): PingRoomError {
+  const reason = last.status > 0 ? `HTTP ${last.status}` : (last.code ?? 'network error');
+  return new PingRoomError(
+    `PingRoom unavailable since ${new Date(since).toISOString()} (${reason}); stopped waiting for ${what}.`,
+    { code: 'unavailable', cause: last },
+  );
+}
+
+/**
+ * The shared human-in-the-loop wait loop. Polls until a validated response is
+ * terminal; retries transient failures with backoff; rejects with the
+ * signal's reason once it aborts. A response that fails validation is never
+ * returned as an outcome.
+ *
+ * The retries are bounded even without a signal. Once only failures have come
+ * back since the last valid response, and the last-seen `expires_at` plus
+ * {@link WAIT_EXPIRY_GRACE_MS} has passed (or, before any `expires_at` was
+ * seen, after {@link WAIT_UNKNOWN_EXPIRY_OUTAGE_MS} of unbroken failures), the
+ * wait rejects with `unavailable`, the last failure as its `cause`.
+ */
+export async function pollUntilSettled<T>(options: PollUntilSettledOptions<T>): Promise<T> {
+  const { poll, validate, settled, signal, minIntervalMs = 0, expiresAt, what, onRetry } = options;
+  let failures = 0;
+  let failingSince: number | null = null;
+  // expires_at plus grace, from the last valid response that carried one.
+  let deadline: number | null = null;
+  for (;;) {
+    throwIfAborted(signal);
+    const startedAt = Date.now();
+    let value: T;
+    try {
+      value = validate(await poll());
+    } catch (error) {
+      throwIfAborted(signal);
+      if (!isTransientError(error)) {
+        throw error;
+      }
+      failures += 1;
+      failingSince ??= Date.now();
+      const remaining = (deadline ?? failingSince + WAIT_UNKNOWN_EXPIRY_OUTAGE_MS) - Date.now();
+      if (remaining <= 0) {
+        throw unavailable(error, failingSince, what);
+      }
+      onRetry?.(error, failures);
+      // A fast failure still consumes a poll. Keep retries spaced even when a
+      // pending response between failures resets the exponential backoff.
+      const delay = Math.max(transientDelayMs(error, failures), minIntervalMs - (Date.now() - startedAt));
+      // Do not retry earlier than the interval or Retry-After just to fit the
+      // outage bound. Wait out the budget, then stop without another request.
+      if (delay > remaining) {
+        await sleep(remaining, signal);
+        throwIfAborted(signal);
+        throw unavailable(error, failingSince, what);
+      }
+      await sleep(delay, signal);
+      continue;
+    }
+    failures = 0;
+    failingSince = null;
+    const expiry = expiresAt ? timeOf(expiresAt(value)) : null;
+    if (expiry !== null) {
+      deadline = expiry + WAIT_EXPIRY_GRACE_MS;
+    }
+    if (settled(value)) {
+      return value;
+    }
+    // An injected transport can resolve pending polls immediately. Yield
+    // between them so timer-driven cancellation and deadlines can run.
+    await sleep(Math.max(0, minIntervalMs - (Date.now() - startedAt)), signal);
+  }
+}

package/src/internal/url.ts

@@ -0,0 +1,78 @@
+import { PingRoomError } from '../errors.js';
+
+export function isLoopbackHost(hostname: string): boolean {
+  const h = hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '');
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.endsWith('.localhost');
+}
+
+/**
+ * Refuse to carry a bearer credential over plain http to a non-loopback host —
+ * a token on the wire over http is a token leaked. https always passes; http is
+ * allowed only to loopback dev hosts, or anywhere when `allowInsecure` is set.
+ */
+export function assertSecureUrl(rawUrl: string, allowInsecure: boolean): URL {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    // Never echo the input: an incoming-webhook URL carries its secret in the
+    // path, and error messages end up in logs.
+    throw new PingRoomError('Invalid URL (value withheld because it may contain a secret).', {
+      code: 'invalid_url',
+    });
+  }
+  if (url.protocol === 'https:') {
+    return url;
+  }
+  if (url.protocol === 'http:' && (allowInsecure || isLoopbackHost(url.hostname))) {
+    return url;
+  }
+  throw new PingRoomError(
+    `Refusing to send credentials over an insecure URL (${url.protocol}//${url.host}). ` +
+      'Use https, or set allowInsecure: true for trusted local development.',
+    { code: 'insecure_url' },
+  );
+}
+
+/**
+ * Strip a URL out of an error message, keeping only its origin. An
+ * incoming-webhook URL carries its secret in the path, and fetch
+ * implementations (node-fetch, for one) quote the requested URL in their
+ * errors, so a message copied from one must not reach a caller's logs as-is.
+ */
+export function redactUrlInMessage(message: string, url: URL, rawUrl: string): string {
+  const withheld = `${url.origin}/[redacted]`;
+  let out = message;
+  for (const full of [rawUrl, url.href]) {
+    if (full) out = out.split(full).join(withheld);
+  }
+  for (const tail of [`${url.pathname}${url.search}${url.hash}`, url.pathname]) {
+    if (tail.length > 1) out = out.split(tail).join('/[redacted]');
+  }
+  return out;
+}
+
+/**
+ * Every request goes out with `redirect: 'manual'` (Cloudflare Workers throw
+ * on `'error'`), so a redirect comes back as a response instead of being
+ * followed. Refuse it: a 307/308 would replay pairing secrets, uploaded bytes
+ * or a webhook body to whatever origin `Location` names. Browsers report a
+ * manual redirect as an `opaqueredirect` with status 0; other runtimes return
+ * the 3xx itself.
+ */
+export function refuseRedirect(res: Response): void {
+  if (res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400)) {
+    // Release the body, best effort. A custom `fetch` such as node-fetch hands
+    // back a Node Readable with no cancel(); calling it threw a TypeError that
+    // surfaced as a retryable network_error instead of this refusal.
+    try {
+      (res.body?.cancel?.() as Promise<void> | undefined)?.catch?.(() => {});
+    } catch {
+      // Ignored: the refusal below is what matters.
+    }
+    throw new PingRoomError('Refusing to follow a redirect; credentials and request bodies are never forwarded.', {
+      code: 'redirect_refused',
+      status: res.status,
+    });
+  }
+}

package/src/internal/validate.ts

@@ -0,0 +1,42 @@
+// Shape checks for server responses the wait loops and Agent Inbox trust.
+
+import { PingRoomError } from '../errors.js';
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+export function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === 'string';
+}
+
+/** UUIDs are case-insensitive; a caller may hold an id in either case. */
+export function sameId(received: unknown, expected: string): boolean {
+  return typeof received === 'string' && received.toLowerCase() === expected.toLowerCase();
+}
+
+export function invalidWaitResponse(subject: string, expectedId: string, value: unknown, stateField: string): never {
+  throw new PingRoomError(`PingRoom returned an invalid ${subject} wait response.`, {
+    code: 'invalid_response',
+    body: {
+      expected_id: expectedId,
+      received_id: isRecord(value) && typeof value['id'] === 'string' ? value['id'] : null,
+      [stateField]: isRecord(value) && typeof value[stateField] === 'string' ? value[stateField] : null,
+    },
+  });
+}
+
+/**
+ * A 2xx the PingRoom API never sends: a gateway's or captive portal's page, or
+ * a URL that is not PingRoom's. The body is kept short, for inspection only.
+ */
+export function invalidSuccessResponse(status: number, expected: string, body: unknown): PingRoomError {
+  return new PingRoomError(`PingRoom returned an invalid response (HTTP ${status}): expected ${expected}.`, {
+    code: 'invalid_response',
+    body: typeof body === 'string' ? body.slice(0, 512) : body,
+  });
+}

package/src/linkPing.ts

@@ -0,0 +1,56 @@
+/**
+ * Link pings — make a ping a tappable button that opens a URL.
+ *
+ * The server convention is two reserved keys inside the structured `data`
+ * object: `url` (absolute http(s), <= 2048 chars) and `button_label`
+ * (<= 26 chars). This helper builds that fragment with client-side
+ * validation so a bad link fails fast instead of at the API boundary:
+ *
+ *   await pr.broadcast('ab12cd', {
+ *     message: 'Build 512 ready',
+ *     data: { commit: 'abc123', ...linkPing({ url: 'https://ci.example.com/b/512', buttonLabel: 'Open build' }) },
+ *   });
+ */
+
+export interface LinkPingInput {
+  /** Absolute http(s) URL opened when the recipient taps the link button. Max 2048 chars. */
+  url: string;
+  /** Text on the link button. Max 26 chars. Defaults to a generic label on-device. */
+  buttonLabel?: string;
+}
+
+export interface LinkPingData {
+  url: string;
+  button_label?: string;
+  [key: string]: unknown;
+}
+
+const URL_MAX = 2048;
+const LABEL_MAX = 26;
+
+/** Count code points, as the server's mb_strlen does — an emoji is one character, not two. */
+function characterLength(value: string): number {
+  return Array.from(value).length;
+}
+
+/** Build the `data` fragment for a link ping. Spread it into a ping's `data` object. */
+export function linkPing(input: LinkPingInput): LinkPingData {
+  let parsed: URL;
+  try {
+    parsed = new URL(input.url);
+  } catch {
+    throw new TypeError('linkPing: url is not a valid URL');
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new TypeError('linkPing: url must be an absolute http(s) URL');
+  }
+  if (characterLength(input.url) > URL_MAX) {
+    throw new TypeError(`linkPing: url must be at most ${URL_MAX} characters`);
+  }
+  if (input.buttonLabel !== undefined && characterLength(input.buttonLabel) > LABEL_MAX) {
+    throw new TypeError(`linkPing: buttonLabel must be at most ${LABEL_MAX} characters`);
+  }
+  const out: LinkPingData = { url: input.url };
+  if (input.buttonLabel !== undefined) out.button_label = input.buttonLabel;
+  return out;
+}