@keyou007/agent-bot 0.1.0

package/src/cli/FeishuAppConfiguration.ts

@@ -0,0 +1,473 @@
+import { gzipSync } from "node:zlib";
+import type { FeishuAppCredentials } from "./FeishuAppRegistration.js";
+
+const FEISHU_OPEN_BASE_URL = "https://open.feishu.cn";
+const TENANT_TOKEN_PATH = "/open-apis/auth/v3/tenant_access_token/internal";
+const APPLICATION_PATH_PREFIX = "/open-apis/application/v6/applications";
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_COMPLETION_TIMEOUT_MS = 10 * 60_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+
+interface ScopeRequirement {
+  requested: string;
+  accepted: string[];
+}
+
+const REQUIRED_SCOPE_REQUIREMENTS: ScopeRequirement[] = [
+  {
+    requested: "application:application:self_manage",
+    accepted: ["application:application:self_manage"],
+  },
+  {
+    requested: "im:chat:create",
+    accepted: ["im:chat:create", "im:chat"],
+  },
+  {
+    requested: "im:chat:read",
+    accepted: ["im:chat:read", "im:chat:readonly", "im:chat"],
+  },
+  {
+    requested: "im:message.group_at_msg:readonly",
+    accepted: [
+      "im:message.group_at_msg:readonly",
+      "im:message.group_at_msg.include_bot:readonly",
+      "im:message.group_at_msg",
+      "im:message.group_msg:readonly",
+      "im:message.group_msg",
+    ],
+  },
+  {
+    requested: "im:message.p2p_msg:readonly",
+    accepted: ["im:message.p2p_msg:readonly", "im:message.p2p_msg"],
+  },
+  {
+    requested: "im:message.reactions:write_only",
+    accepted: ["im:message.reactions:write_only", "im:message"],
+  },
+  {
+    requested: "im:message:readonly",
+    accepted: ["im:message:readonly", "im:message.history:readonly", "im:message"],
+  },
+  {
+    requested: "im:message:send_as_bot",
+    accepted: ["im:message:send_as_bot", "im:message:send", "im:message"],
+  },
+  {
+    requested: "im:message:update",
+    accepted: ["im:message:update", "im:message:send_as_bot", "im:message"],
+  },
+  {
+    requested: "im:resource",
+    accepted: ["im:resource", "im:resource:upload"],
+  },
+];
+
+export const REQUIRED_FEISHU_SCOPES = REQUIRED_SCOPE_REQUIREMENTS.map((requirement) => requirement.requested);
+export const REQUIRED_FEISHU_EVENTS = ["im.message.receive_v1", "im.chat.updated_v1"] as const;
+export const REQUIRED_FEISHU_CALLBACKS = ["card.action.trigger"] as const;
+
+const CORE_FEISHU_SCOPES = new Set([
+  "application:application:self_manage",
+  "im:message.group_at_msg:readonly",
+  "im:message.p2p_msg:readonly",
+  "im:message:send_as_bot",
+]);
+const CORE_FEISHU_EVENTS = new Set<string>(["im.message.receive_v1"]);
+
+export interface FeishuAppConfiguration {
+  scopes: string[];
+  events: string[];
+  callbacks: string[];
+}
+
+export interface MissingFeishuAppConfiguration {
+  scopes: string[];
+  events: string[];
+  callbacks: string[];
+}
+
+export interface FeishuConfigurationChallenge {
+  verificationUrl: string;
+  missing: MissingFeishuAppConfiguration;
+  blocking: boolean;
+}
+
+export interface EnsureFeishuAppConfigurationOptions {
+  fetch?: typeof globalThis.fetch;
+  sleep?: (milliseconds: number) => Promise<void>;
+  signal?: AbortSignal;
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+  onVerification?: (challenge: FeishuConfigurationChallenge) => void | Promise<void>;
+}
+
+export interface EnsureFeishuAppConfigurationResult {
+  status: "ready" | "updated" | "partial";
+  configuration: FeishuAppConfiguration;
+  added: MissingFeishuAppConfiguration;
+  remaining: MissingFeishuAppConfiguration;
+}
+
+type JsonObject = Record<string, unknown>;
+
+export async function ensureFeishuAppConfiguration(
+  credentials: FeishuAppCredentials,
+  options: EnsureFeishuAppConfigurationOptions = {},
+): Promise<EnsureFeishuAppConfigurationResult> {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const sleep = options.sleep ?? delay;
+  const pollIntervalMs = positiveInteger(options.pollIntervalMs) ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = positiveInteger(options.timeoutMs) ?? DEFAULT_COMPLETION_TIMEOUT_MS;
+
+  let configuration: FeishuAppConfiguration;
+  try {
+    configuration = await readFeishuAppConfiguration(credentials, fetchImpl, options.signal);
+  } catch (error) {
+    if (!isPermissionError(error)) throw error;
+    configuration = emptyConfiguration();
+  }
+
+  const missing = missingFeishuAppConfiguration(configuration);
+  if (!hasMissingConfiguration(missing)) {
+    return {
+      status: "ready",
+      configuration,
+      added: emptyConfiguration(),
+      remaining: emptyConfiguration(),
+    };
+  }
+
+  const coreMissing = coreMissingFeishuAppConfiguration(missing);
+  if (!hasMissingConfiguration(coreMissing)) {
+    await requestMissingFeishuConfiguration(credentials.appId, missing, false, options.onVerification);
+    return {
+      status: "partial",
+      configuration,
+      added: emptyConfiguration(),
+      remaining: missing,
+    };
+  }
+
+  await requestMissingFeishuConfiguration(credentials.appId, coreMissing, true, options.onVerification);
+
+  let remainingMs = timeoutMs;
+  let lastError: unknown;
+  while (remainingMs > 0) {
+    const waitMs = Math.min(pollIntervalMs, remainingMs);
+    await sleepWithAbort(sleep, waitMs, options.signal);
+    remainingMs -= waitMs;
+
+    try {
+      configuration = await readFeishuAppConfiguration(credentials, fetchImpl, options.signal);
+      const remaining = missingFeishuAppConfiguration(configuration);
+      if (!hasMissingConfiguration(coreMissingFeishuAppConfiguration(remaining))) {
+        if (hasMissingConfiguration(remaining)) {
+          await requestMissingFeishuConfiguration(credentials.appId, remaining, false, options.onVerification);
+        }
+        return {
+          status: hasMissingConfiguration(remaining) ? "partial" : "updated",
+          configuration,
+          added: resolvedMissingConfiguration(missing, remaining),
+          remaining,
+        };
+      }
+      lastError = undefined;
+    } catch (error) {
+      if (options.signal?.aborted) throw abortError(options.signal);
+      lastError = error;
+    }
+  }
+
+  const detail = lastError instanceof Error ? ` 最后一次检查失败：${lastError.message}` : "";
+  throw new Error(`等待飞书核心权限和消息事件配置生效超时，请重新运行 agent-bot init。${detail}`);
+}
+
+async function requestMissingFeishuConfiguration(
+  appId: string,
+  missing: MissingFeishuAppConfiguration,
+  blocking: boolean,
+  onVerification: EnsureFeishuAppConfigurationOptions["onVerification"],
+): Promise<void> {
+  const verificationUrl = buildFeishuConfigurationUrl(appId, missing);
+  await onVerification?.({ verificationUrl, missing, blocking });
+}
+
+export function missingFeishuAppConfiguration(configuration: FeishuAppConfiguration): MissingFeishuAppConfiguration {
+  const scopes = new Set(configuration.scopes);
+  const events = new Set(configuration.events);
+  const callbacks = new Set(configuration.callbacks);
+  return {
+    scopes: REQUIRED_SCOPE_REQUIREMENTS.filter(
+      (requirement) => !requirement.accepted.some((scope) => scopes.has(scope)),
+    ).map((requirement) => requirement.requested),
+    events: REQUIRED_FEISHU_EVENTS.filter((event) => !events.has(event)),
+    callbacks: REQUIRED_FEISHU_CALLBACKS.filter((callback) => !callbacks.has(callback)),
+  };
+}
+
+export function buildFeishuConfigurationUrl(appId: string, missing: MissingFeishuAppConfiguration): string {
+  const manifest: JsonObject = {};
+  if (missing.scopes.length > 0) {
+    manifest.scopes = {
+      tenant: missing.scopes,
+      user: [],
+    };
+  }
+  if (missing.events.length > 0) {
+    manifest.events = {
+      items: {
+        tenant: missing.events,
+        user: [],
+      },
+    };
+  }
+  if (missing.callbacks.length > 0) {
+    manifest.callbacks = {
+      items: missing.callbacks,
+    };
+  }
+
+  const encoded = gzipSync(Buffer.from(JSON.stringify(manifest), "utf8")).toString("base64url");
+  const url = new URL("/page/launcher", FEISHU_OPEN_BASE_URL);
+  url.searchParams.set("clientID", appId);
+  url.searchParams.set("addons", encoded);
+  return url.toString();
+}
+
+async function readFeishuAppConfiguration(
+  credentials: FeishuAppCredentials,
+  fetchImpl: typeof globalThis.fetch,
+  signal?: AbortSignal,
+): Promise<FeishuAppConfiguration> {
+  const token = await getTenantAccessToken(credentials, fetchImpl, signal);
+  const appId = encodeURIComponent(credentials.appId);
+  const headers = { Authorization: `Bearer ${token}` };
+  const [application, versions] = await Promise.all([
+    fetchJson(
+      fetchImpl,
+      `${FEISHU_OPEN_BASE_URL}${APPLICATION_PATH_PREFIX}/${appId}?lang=zh_cn`,
+      { headers },
+      signal,
+      "查询飞书应用配置",
+    ),
+    fetchJson(
+      fetchImpl,
+      `${FEISHU_OPEN_BASE_URL}${APPLICATION_PATH_PREFIX}/${appId}/app_versions?lang=zh_cn&page_size=2`,
+      { headers },
+      signal,
+      "查询飞书应用版本",
+    ),
+  ]);
+
+  const app = readObject(readObject(application, "data"), "app");
+  const callbackInfo = readObject(app, "callback_info");
+  const callbacks = readStringArray(callbackInfo, "subscribed_callbacks");
+  const publishedVersion = readArray(readObject(versions, "data"), "items")
+    .filter(isJsonObject)
+    .find((item) => readNumber(item, "status") === 1 && hasPublishTime(item.publish_time));
+  const scopes = publishedVersion
+    ? readArray(publishedVersion, "scopes")
+        .filter(isJsonObject)
+        .filter((item) => readStringArray(item, "token_types").includes("tenant"))
+        .map((item) => readString(item, "scope"))
+        .filter(Boolean)
+    : [];
+  const events = publishedVersion
+    ? readArray(publishedVersion, "event_infos")
+        .filter(isJsonObject)
+        .map((item) => readString(item, "event_type"))
+        .filter(Boolean)
+    : [];
+
+  return {
+    scopes: uniqueSorted(scopes),
+    events: uniqueSorted(events),
+    callbacks: uniqueSorted(callbacks),
+  };
+}
+
+async function getTenantAccessToken(
+  credentials: FeishuAppCredentials,
+  fetchImpl: typeof globalThis.fetch,
+  signal?: AbortSignal,
+): Promise<string> {
+  const payload = await fetchJson(
+    fetchImpl,
+    `${FEISHU_OPEN_BASE_URL}${TENANT_TOKEN_PATH}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json; charset=utf-8" },
+      body: JSON.stringify({
+        app_id: credentials.appId,
+        app_secret: credentials.appSecret,
+      }),
+    },
+    signal,
+    "获取飞书 tenant_access_token",
+  );
+  const token = readString(payload, "tenant_access_token");
+  if (!token) throw new Error("飞书 tenant_access_token 响应缺少访问凭证。");
+  return token;
+}
+
+async function fetchJson(
+  fetchImpl: typeof globalThis.fetch,
+  url: string,
+  init: RequestInit,
+  parentSignal: AbortSignal | undefined,
+  operation: string,
+): Promise<JsonObject> {
+  if (parentSignal?.aborted) throw abortError(parentSignal);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(new Error("request timeout")), REQUEST_TIMEOUT_MS);
+  const onAbort = (): void => controller.abort(parentSignal?.reason);
+  parentSignal?.addEventListener("abort", onAbort, { once: true });
+
+  try {
+    const response = await fetchImpl(url, { ...init, signal: controller.signal });
+    const payload = (await response.json().catch(() => undefined)) as unknown;
+    if (!isJsonObject(payload)) {
+      throw new Error(`${operation}返回了无法解析的响应（HTTP ${response.status}）。`);
+    }
+    const code = readNumber(payload, "code");
+    if (!response.ok || code !== 0) {
+      throw new FeishuConfigurationApiError(
+        `${operation}失败：${readString(payload, "msg") || response.statusText || `HTTP ${response.status}`}`,
+        code,
+        response.status,
+      );
+    }
+    return payload;
+  } catch (error) {
+    if (parentSignal?.aborted) throw abortError(parentSignal);
+    if (controller.signal.aborted) throw new Error(`${operation}请求超时。`);
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    parentSignal?.removeEventListener("abort", onAbort);
+  }
+}
+
+class FeishuConfigurationApiError extends Error {
+  constructor(
+    message: string,
+    readonly code: number,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+function isPermissionError(error: unknown): boolean {
+  return (
+    error instanceof FeishuConfigurationApiError &&
+    (error.status === 403 ||
+      error.code === 99991672 ||
+      error.code === 99991676 ||
+      /permission|scope|权限/i.test(error.message))
+  );
+}
+
+function hasMissingConfiguration(missing: MissingFeishuAppConfiguration): boolean {
+  return missing.scopes.length > 0 || missing.events.length > 0 || missing.callbacks.length > 0;
+}
+
+function coreMissingFeishuAppConfiguration(missing: MissingFeishuAppConfiguration): MissingFeishuAppConfiguration {
+  return {
+    scopes: missing.scopes.filter((scope) => CORE_FEISHU_SCOPES.has(scope)),
+    events: missing.events.filter((event) => CORE_FEISHU_EVENTS.has(event)),
+    callbacks: [],
+  };
+}
+
+function resolvedMissingConfiguration(
+  initial: MissingFeishuAppConfiguration,
+  remaining: MissingFeishuAppConfiguration,
+): MissingFeishuAppConfiguration {
+  const remainingScopes = new Set(remaining.scopes);
+  const remainingEvents = new Set(remaining.events);
+  const remainingCallbacks = new Set(remaining.callbacks);
+  return {
+    scopes: initial.scopes.filter((scope) => !remainingScopes.has(scope)),
+    events: initial.events.filter((event) => !remainingEvents.has(event)),
+    callbacks: initial.callbacks.filter((callback) => !remainingCallbacks.has(callback)),
+  };
+}
+
+function emptyConfiguration(): FeishuAppConfiguration {
+  return { scopes: [], events: [], callbacks: [] };
+}
+
+function uniqueSorted(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+function hasPublishTime(value: unknown): boolean {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function readObject(value: JsonObject, key: string): JsonObject {
+  const field = value[key];
+  return isJsonObject(field) ? field : {};
+}
+
+function readArray(value: JsonObject, key: string): unknown[] {
+  const field = value[key];
+  return Array.isArray(field) ? field : [];
+}
+
+function readStringArray(value: JsonObject, key: string): string[] {
+  return readArray(value, key)
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function readString(value: JsonObject, key: string): string {
+  const field = value[key];
+  return typeof field === "string" ? field.trim() : "";
+}
+
+function readNumber(value: JsonObject, key: string): number {
+  const field = value[key];
+  return typeof field === "number" ? field : Number(field);
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function positiveInteger(value: number | undefined): number | undefined {
+  return Number.isInteger(value) && value !== undefined && value > 0 ? value : undefined;
+}
+
+function abortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error("飞书应用配置已取消。");
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function sleepWithAbort(
+  sleep: (milliseconds: number) => Promise<void>,
+  milliseconds: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!signal) {
+    await sleep(milliseconds);
+    return;
+  }
+  if (signal.aborted) throw abortError(signal);
+
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    await Promise.race([sleep(milliseconds), aborted]);
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}

package/src/cli/FeishuAppRegistration.ts

@@ -0,0 +1,207 @@
+const FEISHU_ACCOUNTS_BASE_URL = "https://accounts.feishu.cn";
+const FEISHU_OPEN_BASE_URL = "https://open.feishu.cn";
+const APP_REGISTRATION_PATH = "/oauth/v1/app/registration";
+const DEFAULT_EXPIRES_IN_SECONDS = 600;
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const MAX_POLL_INTERVAL_SECONDS = 60;
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export interface FeishuAppRegistrationChallenge {
+  verificationUrl: string;
+  userCode: string;
+  expiresIn: number;
+  interval: number;
+}
+
+export interface FeishuAppCredentials {
+  appId: string;
+  appSecret: string;
+}
+
+export interface FeishuAppRegistrationOptions {
+  fetch?: typeof globalThis.fetch;
+  sleep?: (milliseconds: number) => Promise<void>;
+  signal?: AbortSignal;
+  onVerification?: (challenge: FeishuAppRegistrationChallenge) => void | Promise<void>;
+}
+
+type RegistrationPayload = Record<string, unknown>;
+
+export async function registerFeishuApp(options: FeishuAppRegistrationOptions = {}): Promise<FeishuAppCredentials> {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const sleep = options.sleep ?? delay;
+  const begin = await postRegistration(
+    fetchImpl,
+    {
+      action: "begin",
+      archetype: "PersonalAgent",
+      auth_method: "client_secret",
+      request_user_info: "open_id tenant_brand",
+    },
+    options.signal,
+  );
+  throwRegistrationError(begin, "无法发起飞书应用创建");
+
+  const deviceCode = readString(begin, "device_code");
+  const userCode = readString(begin, "user_code");
+  if (!deviceCode || !userCode) {
+    throw new Error("飞书应用创建响应缺少 device_code 或 user_code。");
+  }
+
+  const expiresIn =
+    readPositiveInteger(begin, "expire_in") ?? readPositiveInteger(begin, "expires_in") ?? DEFAULT_EXPIRES_IN_SECONDS;
+  const initialInterval = readPositiveInteger(begin, "interval") ?? DEFAULT_POLL_INTERVAL_SECONDS;
+  const verificationUrl = readString(begin, "verification_uri_complete") || buildVerificationUrl(userCode);
+
+  await options.onVerification?.({
+    verificationUrl,
+    userCode,
+    expiresIn,
+    interval: initialInterval,
+  });
+
+  let remainingMs = expiresIn * 1_000;
+  let intervalSeconds = initialInterval;
+  let waitBeforePoll = false;
+
+  while (remainingMs > 0) {
+    if (options.signal?.aborted) throw abortError(options.signal);
+    if (waitBeforePoll) {
+      const waitMs = Math.min(intervalSeconds * 1_000, remainingMs);
+      await sleepWithAbort(sleep, waitMs, options.signal);
+      remainingMs -= waitMs;
+      if (remainingMs <= 0) break;
+    }
+    waitBeforePoll = true;
+
+    let payload: RegistrationPayload;
+    try {
+      payload = await postRegistration(
+        fetchImpl,
+        {
+          action: "poll",
+          device_code: deviceCode,
+        },
+        options.signal,
+      );
+    } catch (error) {
+      if (options.signal?.aborted) throw abortError(options.signal);
+      intervalSeconds = Math.min(intervalSeconds + 1, MAX_POLL_INTERVAL_SECONDS);
+      continue;
+    }
+
+    const errorCode = readString(payload, "error");
+    if (!errorCode) {
+      const appId = readString(payload, "client_id");
+      const appSecret = readString(payload, "client_secret");
+      if (appId && appSecret) return { appId, appSecret };
+      continue;
+    }
+
+    switch (errorCode) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        intervalSeconds = Math.min(intervalSeconds + 5, MAX_POLL_INTERVAL_SECONDS);
+        continue;
+      case "access_denied":
+        throw new Error("你已取消飞书应用创建。");
+      case "expired_token":
+      case "invalid_grant":
+        throw new Error("飞书应用创建链接已过期，请重新运行 agent-bot init。");
+      default:
+        throwRegistrationError(payload, "飞书应用创建失败");
+    }
+  }
+
+  throw new Error("等待飞书应用创建超时，请重新运行 agent-bot init。");
+}
+
+function buildVerificationUrl(userCode: string): string {
+  const url = new URL("/page/cli", FEISHU_OPEN_BASE_URL);
+  url.searchParams.set("user_code", userCode);
+  url.searchParams.set("from", "cli");
+  return url.toString();
+}
+
+async function postRegistration(
+  fetchImpl: typeof globalThis.fetch,
+  values: Record<string, string>,
+  parentSignal?: AbortSignal,
+): Promise<RegistrationPayload> {
+  if (parentSignal?.aborted) throw abortError(parentSignal);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(new Error("request timeout")), REQUEST_TIMEOUT_MS);
+  const onAbort = (): void => controller.abort(parentSignal?.reason);
+  parentSignal?.addEventListener("abort", onAbort, { once: true });
+
+  try {
+    const response = await fetchImpl(`${FEISHU_ACCOUNTS_BASE_URL}${APP_REGISTRATION_PATH}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(values),
+      signal: controller.signal,
+    });
+    const payload = (await response.json().catch(() => undefined)) as unknown;
+    if (!isRecord(payload)) {
+      throw new Error(`飞书应用注册接口返回了无法解析的响应（HTTP ${response.status}）。`);
+    }
+    return payload;
+  } finally {
+    clearTimeout(timeout);
+    parentSignal?.removeEventListener("abort", onAbort);
+  }
+}
+
+function throwRegistrationError(payload: RegistrationPayload, prefix: string): void {
+  const code = readString(payload, "error");
+  if (!code) return;
+  const description = readString(payload, "error_description") || code;
+  throw new Error(`${prefix}：${description}`);
+}
+
+function readString(value: RegistrationPayload, key: string): string {
+  const field = value[key];
+  return typeof field === "string" ? field.trim() : "";
+}
+
+function readPositiveInteger(value: RegistrationPayload, key: string): number | undefined {
+  const field = value[key];
+  const parsed = typeof field === "number" ? field : Number(field);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function isRecord(value: unknown): value is RegistrationPayload {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function abortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error("飞书应用创建已取消。");
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function sleepWithAbort(
+  sleep: (milliseconds: number) => Promise<void>,
+  milliseconds: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!signal) {
+    await sleep(milliseconds);
+    return;
+  }
+  if (signal.aborted) throw abortError(signal);
+
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    await Promise.race([sleep(milliseconds), aborted]);
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}