@perrylink/dsh-ticktick 0.1.2

package/src/domain.ts

@@ -0,0 +1,224 @@
+/**
+ * Tool discovery and task normalization over the TickTick MCP tool list:
+ * names are resolved by pattern (pinnable per deployment) and results are
+ * normalized into a stable `{ id, title, done, projectId, dueDate,
+ * sortOrder }` view. Ported from the measured 0.1.0-era bridge; the wire
+ * facts (list order = descending sortOrder, inbox ids carry 'inbox') were
+ * verified against the live endpoint.
+ *
+ * @module dsh-ticktick/domain
+ */
+
+import type { McpCallResult, McpTool } from './mcp.ts'
+import type { ToolPins } from './config.ts'
+
+/** The resolved raw MCP tool names for the bridge operations. */
+export interface ToolResolver {
+  readonly projects: string
+  readonly tasks: string
+  readonly create: string
+  readonly complete: string
+  readonly remove: string
+  readonly update: string
+  readonly move: string
+  /** `list_completed_tasks_by_date` (P2 completed view). */
+  readonly completed: string
+  /** `search` or `search_task` (P2 full-text search). */
+  readonly search: string
+  /** `get_task_by_id` (P2 read-after-write verification). */
+  readonly getTask: string
+  /** `batch_add_tasks` (P2 batch create). */
+  readonly batchAdd: string
+}
+
+/** Stable task view the widget and tools render. */
+export interface TicktickTask {
+  readonly id: string
+  readonly title: string
+  readonly done: boolean
+  /** Owning project, required by TickTick's complete_task call. */
+  readonly projectId?: string
+  /** ISO due date (TickTick date-time), absent when the task has none. */
+  readonly dueDate?: string
+  /** TickTick sort order (list order is descending). */
+  readonly sortOrder?: number
+}
+
+/** One project entry from `list_projects` (the virtual inbox included). */
+export interface TicktickProject {
+  readonly id: string
+  readonly name: string
+}
+
+const PROJECTS_PATTERN = /(list|get)[^a-z0-9]*(project|projects)|(project|projects)[^a-z0-9]*(list|get)/i
+const TASKS_PATTERN = /(undone|open)[^a-z0-9]*(task|tasks)|project[^a-z0-9]*(with|undone)[^a-z0-9]*(task|tasks)/i
+const CREATE_PATTERN = /^(create|add|insert|new)[^a-z0-9]*(task|todo)|^(task|todo)[^a-z0-9]*(create|add|insert|new)/i
+const COMPLETE_PATTERN = /^(complete|finish|done|close|check)[^a-z0-9]*(task|todo)|^(task|todo)[^a-z0-9]*(complete|finish|done|close|check)/i
+const REMOVE_PATTERN = /^(delete|remove)[^a-z0-9]*(task|todo)|^(task|todo)[^a-z0-9]*(delete|remove)/i
+const UPDATE_PATTERN = /^update[^a-z0-9]*(task|todo)|^(task|todo)[^a-z0-9]*update/i
+const MOVE_PATTERN = /^move[^a-z0-9]*(task|todo)|^(task|todo)[^a-z0-9]*move/i
+const COMPLETED_PATTERN = /completed[^a-z0-9]*(task|tasks)|completed_by/i
+const SEARCH_PATTERN = /^search(_task)?$/i
+const GET_TASK_PATTERN = /get[^a-z0-9]*task[^a-z0-9]*by[^a-z0-9]*id|^fetch$/i
+const BATCH_ADD_PATTERN = /batch[^a-z0-9]*add[^a-z0-9]*(task|tasks)/i
+
+/**
+ * Pick the raw tool names for the eleven operations, honoring pins.
+ * A pin that is not advertised falls back to pattern discovery, then to
+ * the first advertised tool, then to the pin itself (an empty resolver
+ * surfaces as a failed call, never a silent no-op).
+ * @param tools - the advertised tool list.
+ * @param pins - config-level name pins.
+ * @returns the resolved names.
+ */
+export function resolveTools(tools: readonly McpTool[], pins: ToolPins): ToolResolver {
+  const pick = (pattern: RegExp, pin: string): string => {
+    if (pin !== '' && tools.some(tool => tool.name === pin)) return pin
+    return tools.find(tool => pattern.test(tool.name))?.name
+      ?? (pin !== '' ? pin : tools[0]?.name)
+      ?? ''
+  }
+  // Prefer the exact `search` tool over `search_task` (both match the pattern).
+  const searchPin = pins.search
+  const exactSearch = tools.find(tool => tool.name === 'search')
+  const search = (searchPin !== '' && tools.some(tool => tool.name === searchPin)) ? searchPin
+    : (exactSearch?.name ?? pick(SEARCH_PATTERN, searchPin))
+  return {
+    projects: pick(PROJECTS_PATTERN, pins.projects),
+    tasks: pick(TASKS_PATTERN, pins.tasks),
+    create: pick(CREATE_PATTERN, pins.create),
+    complete: pick(COMPLETE_PATTERN, pins.complete),
+    remove: pick(REMOVE_PATTERN, pins.remove),
+    update: pick(UPDATE_PATTERN, pins.update),
+    move: pick(MOVE_PATTERN, pins.move),
+    completed: pick(COMPLETED_PATTERN, pins.completed),
+    search,
+    getTask: pick(GET_TASK_PATTERN, pins.getTask),
+    batchAdd: pick(BATCH_ADD_PATTERN, pins.batchAdd),
+  }
+}
+
+const VALUE_KEY = /title|content|text|subject|name|desc/i
+const ID_KEY = /(^|_)(id|uuid)$|taskId|task_id/i
+const PROJECT_KEY = /projectId|project_id/i
+
+/** Parse the project entries out of a `list_projects` result (object or array payloads). */
+export function normalizeProjects(result: McpCallResult): readonly TicktickProject[] {
+  const projects: TicktickProject[] = []
+  const seen = new Set<string>()
+  const accept = (record: Record<string, unknown>): void => {
+    const id = record.id
+    const name = record.name
+    if (typeof id === 'string' && typeof name === 'string' && !seen.has(id)) {
+      seen.add(id)
+      projects.push({ id, name })
+    }
+  }
+  for (const block of result.content ?? []) {
+    if (block.type !== 'text' || block.text === undefined) continue
+    try {
+      const parsed = JSON.parse(block.text) as unknown
+      if (Array.isArray(parsed)) {
+        for (const entry of parsed) {
+          if (entry !== null && typeof entry === 'object') accept(entry as Record<string, unknown>)
+        }
+      } else if (parsed !== null && typeof parsed === 'object') {
+        accept(parsed as Record<string, unknown>)
+      }
+    } catch {
+      // Non-JSON text blocks are not project entries.
+    }
+  }
+  return projects
+}
+
+/** Walk a value for arrays whose elements look like task objects. */
+function findTaskArrays(value: unknown, depth: number): unknown[][] {
+  if (depth > 8 || value === null || typeof value !== 'object') return []
+  if (Array.isArray(value)) {
+    const elements = value.filter(item => item !== null && typeof item === 'object' && !Array.isArray(item))
+    if (elements.length > 0 && elements.every(item => {
+      const record = item as Record<string, unknown>
+      return Object.keys(record).some(key => VALUE_KEY.test(key))
+    })) return [value as unknown[]]
+    return value.flatMap(item => findTaskArrays(item, depth + 1))
+  }
+  return Object.values(value as Record<string, unknown>).flatMap(item => findTaskArrays(item, depth + 1))
+}
+
+/** Read the task id, title, done flag, project, due date, and sort order from one task-like record. */
+function readTask(record: Record<string, unknown>): TicktickTask | null {
+  const keys = Object.keys(record)
+  const titleKey = keys.find(key => VALUE_KEY.test(key) && typeof record[key] === 'string')
+  const idKey = keys.find(key => ID_KEY.test(key))
+  if (titleKey === undefined || idKey === undefined) return null
+  const idValue = record[idKey]
+  if (typeof idValue !== 'string' && typeof idValue !== 'number') return null
+  const projectKey = keys.find(key => PROJECT_KEY.test(key))
+  const projectValue = projectKey === undefined ? undefined : record[projectKey]
+  const dueKey = keys.find(key => /dueDate|due_date|deadline/i.test(key))
+  const dueValue = dueKey === undefined ? undefined : record[dueKey]
+  const sortKey = keys.find(key => /sortOrder|sort_order/i.test(key))
+  const sortValue = sortKey === undefined ? undefined : record[sortKey]
+  const status = record.status
+  const done = status === 2 || status === '2' || status === 'completed'
+    || record.completed === true || record.done === true || record.finished === true
+  return {
+    id: String(idValue),
+    title: record[titleKey] as string,
+    done,
+    ...(typeof projectValue === 'string' ? { projectId: projectValue } : {}),
+    ...(typeof dueValue === 'string' && dueValue !== '' ? { dueDate: dueValue } : {}),
+    ...(typeof sortValue === 'number' ? { sortOrder: sortValue } : {}),
+  }
+}
+
+/** Normalize a tools/call result into the stable task view. */
+export function normalizeTasks(result: McpCallResult): readonly TicktickTask[] {
+  const sources: unknown[] = [result.structuredContent]
+  for (const block of result.content ?? []) {
+    if (block.type === 'text' && block.text !== undefined) {
+      try { sources.push(JSON.parse(block.text) as unknown) } catch { sources.push(block.text) }
+    }
+  }
+  const seen = new Set<string>()
+  const tasks: TicktickTask[] = []
+  for (const source of sources) {
+    // A single task echo (create_task answers one object) is accepted
+    // directly — guarded by a task field so project/list wrappers and
+    // plain objects never masquerade as tasks; arrays of task-like rows
+    // come through findTaskArrays.
+    if (source !== null && typeof source === 'object' && !Array.isArray(source)) {
+      const record = source as Record<string, unknown>
+      const taskish = Object.keys(record).some(key => /status|projectId|project_id|dueDate|due_date|sortOrder|sort_order/i.test(key))
+      if (taskish) {
+        const direct = readTask(record)
+        if (direct !== null && !seen.has(direct.id)) {
+          seen.add(direct.id)
+          tasks.push(direct)
+        }
+      }
+    }
+    for (const array of findTaskArrays(source, 0)) {
+      for (const item of array) {
+        const task = readTask(item as Record<string, unknown>)
+        if (task !== null && !seen.has(task.id)) {
+          seen.add(task.id)
+          tasks.push(task)
+        }
+      }
+    }
+  }
+  return tasks
+}
+
+/**
+ * Whether a project id names the virtual inbox. Measured wire fact: inbox
+ * ids carry the literal 'inbox' (either exactly or inside an internal id),
+ * while regular projects are hex ids.
+ * @param projectId - the project id.
+ * @returns true for inbox ids.
+ */
+export function isInboxProject(projectId: string): boolean {
+  return projectId === 'inbox' || projectId.includes('inbox')
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+/**
+ * `dsh-ticktick` — the TickTick (Dida365) task bridge for DeepSeek Harness.
+ *
+ * Host half: mounts the `ticktick` Remote service (status plus the seven
+ * task operations over the official TickTick MCP endpoint), registers the
+ * eight curated `ticktick_*` tools on the shared service, installs the
+ * `ticktick` settings namespace (token / token file / endpoint / protected
+ * ids) that the browser settings card edits, and announces the tool set in
+ * one system-prompt section.
+ *
+ * The token is re-read per request: the settings card's secret field wins,
+ * then the token file (`$DSH_HOME/.ticktick-token` by default). Writing the
+ * file activates the bridge without a config change.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`).
+ *
+ * @module dsh-ticktick
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+// Type-only: activates the `ctx.settings` Context merge.
+import type {} from '@deepseek-ai/dsh-settings'
+import z from '@deepseek-ai/schemastery'
+import { DEFAULT_MCP_URL, resolveConfig, type Config, type ResolvedConfig } from './config.ts'
+import { TicktickService, type TicktickServiceConfig } from './service.ts'
+import { buildTicktickTools } from './tools.ts'
+import { TICKTICK_SETTINGS_NS, type TicktickSettings } from './wire.ts'
+
+export const name = 'ticktick'
+
+/** Hard services: the tool registry and the prompt assembly. `settings` is an optional child. */
+export const inject = ['tools', 'systemPrompt']
+
+export { Config, resolveConfig, DEFAULT_MCP_URL, DEFAULT_TOOL_CALL_TIMEOUT_MS } from './config.ts'
+export { TicktickService } from './service.ts'
+export type { TicktickServiceConfig } from './service.ts'
+export { buildTicktickTools } from './tools.ts'
+export { McpStreamableClient, parseMcpMessage } from './mcp.ts'
+export type { McpCallResult, McpClientFace, McpTool } from './mcp.ts'
+export { isInboxProject, normalizeProjects, normalizeTasks, resolveTools } from './domain.ts'
+export type { TicktickProject, TicktickTask, ToolResolver } from './domain.ts'
+export type * from './wire.ts'
+
+/** Settings namespace the browser card edits (paired by this exact key). */
+export const SETTINGS_NS = TICKTICK_SETTINGS_NS
+
+/** Schemastery schema for the settings namespace (the card renders this). */
+export const TicktickSettingsSchema: z<TicktickSettings> = z.object({
+  token: z.string().role('secret').default(''),
+  tokenFile: z.string().default(''),
+  mcpUrl: z.string().default(DEFAULT_MCP_URL),
+  protectedTaskIds: z.array(z.string()).default([]),
+})
+
+/** Default token file: `<DSH_HOME>/.ticktick-token` (or `~/.dsh/.ticktick-token`). */
+function defaultTokenFile(): string {
+  return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), '.ticktick-token')
+}
+
+/**
+ * Resolve the current Bearer token: the settings card's secret wins, then
+ * the DIDA365_TOKEN environment variable, then the configured token file.
+ * @param settings - current settings layer.
+ * @param resolved - loader config.
+ * @returns the token, or `null` when unconfigured.
+ */
+export function resolveToken(settings: TicktickSettings, resolved: ResolvedConfig): string | null {
+  if (settings.token !== '') return settings.token
+  const env = process.env.DIDA365_TOKEN
+  if (env !== undefined && env.trim() !== '') return env.trim()
+  const file = settings.tokenFile !== ''
+    ? settings.tokenFile
+    : (resolved.tokenFile !== '' ? resolved.tokenFile : defaultTokenFile())
+  if (!existsSync(file)) return null
+  const token = readFileSync(file, 'utf8').trim()
+  return token === '' ? null : token
+}
+
+/**
+ * Mount the bridge: the settings namespace, the Remote service, the eight
+ * tools, and the usage announcement.
+ *
+ * @param ctx - context carrying tools + systemPrompt.
+ * @param config - raw loader config; defaults applied through {@link resolveConfig}.
+ */
+export async function apply(ctx: Context, config: Config | undefined): Promise<void> {
+  const resolved = resolveConfig(config)
+  let settingsSource: () => TicktickSettings = () => ({
+    token: '',
+    tokenFile: resolved.tokenFile,
+    mcpUrl: resolved.mcpUrl,
+    protectedTaskIds: [...resolved.protectedTaskIds],
+  })
+  let service: TicktickService | undefined
+
+  ctx.inject(['settings'], (scope) => {
+    scope.settings.installSection(ctx, SETTINGS_NS, TicktickSettingsSchema, {
+      token: '',
+      tokenFile: resolved.tokenFile,
+      mcpUrl: resolved.mcpUrl,
+      protectedTaskIds: [...resolved.protectedTaskIds],
+    }, {
+      validate: (value) => {
+        if (value.mcpUrl.trim() === '') throw new Error('dsh-ticktick: mcpUrl must not be empty')
+      },
+      setSource: (source) => { settingsSource = source },
+      onChange: () => { service?.reset() },
+    })
+  })
+
+  const serviceConfig: TicktickServiceConfig = {
+    getToken: () => resolveToken(settingsSource(), resolved),
+    mcpUrl: resolved.mcpUrl,
+    toolCallTimeoutMs: resolved.toolCallTimeoutMs,
+    protectedTaskIds: resolved.protectedTaskIds,
+    pins: resolved.tools,
+  }
+
+  // The service has no injects beyond its own registration; capture the
+  // mounted instance for the tools and the settings change hook.
+  await ctx.plugin(TicktickService, serviceConfig)
+  service = ctx.get('ticktick') as TicktickService
+
+  for (const tool of buildTicktickTools(service)) {
+    ctx.effect(() => ctx.tools.register(tool), `dsh-ticktick: ${tool.name} tool`)
+  }
+
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'ticktick:usage',
+    order: 350,
+    text: 'TickTick (Dida365) tasks are available through the ticktick_* tools: ticktick_status, ticktick_lists, ticktick_tasks, ticktick_add, ticktick_complete, ticktick_delete, ticktick_due, ticktick_reorder, ticktick_completed, ticktick_search, ticktick_batch_add. The Session header also shows a TickTick panel for browsing lists (undone/completed views, full-text search), adding, completing, deleting, setting due dates, and drag reordering.',
+  }), 'dsh-ticktick: system prompt section')
+}

package/src/mcp.ts

@@ -0,0 +1,213 @@
+/**
+ * Minimal Model Context Protocol streamable-HTTP client for the TickTick
+ * endpoint: initialize, tools/list, and tools/call, accepting SSE or JSON
+ * responses, propagating the session id and the negotiated protocol version,
+ * honoring Retry-After on 429, and surfacing tool-level `isError` failures
+ * as thrown errors.
+ *
+ * @module dsh-ticktick/mcp
+ */
+
+/** One tool as advertised by `tools/list`. */
+export interface McpTool {
+  readonly name: string
+  readonly description?: string
+  readonly inputSchema?: {
+    readonly properties?: Readonly<Record<string, { readonly type?: string }>>
+    readonly required?: readonly string[]
+  }
+}
+
+/** Settled `tools/call` result (text blocks or structured content). */
+export interface McpCallResult {
+  readonly content?: readonly { readonly type: string; readonly text?: string }[]
+  readonly structuredContent?: unknown
+}
+
+/** Structural face of the MCP client the service drives (test seam). */
+export interface McpClientFace {
+  initialize(): Promise<void>
+  listTools(): Promise<readonly McpTool[]>
+  callTool(name: string, args: Record<string, unknown>): Promise<McpCallResult>
+}
+
+/** One JSON-RPC request payload. */
+interface McpRequest {
+  readonly jsonrpc: '2.0'
+  readonly id?: number
+  readonly method: string
+  readonly params?: unknown
+}
+
+/**
+ * Parse one MCP response body: the last SSE `data:` payload, or plain JSON.
+ * @param body - raw response text.
+ * @returns the parsed message, or `undefined` for an empty body.
+ */
+export function parseMcpMessage(body: string): unknown | undefined {
+  if (body.trim() === '') return undefined
+  const dataLines = body.split(/\r?\n/).filter(line => line.startsWith('data:'))
+  if (dataLines.length > 0) {
+    const last = dataLines[dataLines.length - 1]!.slice(5).trim()
+    return JSON.parse(last) as unknown
+  }
+  return JSON.parse(body) as unknown
+}
+
+/** Fetch face, injectable for tests. */
+export type FetchFace = (url: string, init?: RequestInit) => Promise<Response>
+
+/**
+ * Streamable-HTTP MCP client with Bearer auth. Requests are simple POSTs;
+ * notifications tolerate empty responses. A 429 response is retried once
+ * after the server's Retry-After delay (bounded to one minute).
+ */
+export class McpStreamableClient implements McpClientFace {
+  private sessionId: string | undefined
+  private protocolVersion: string | undefined
+  private nextId = 1
+
+  /**
+   * @param url - MCP server URL (e.g. https://mcp.dida365.com).
+   * @param token - Bearer token (the TickTick API 口令).
+   * @param timeoutMs - per-request deadline in milliseconds.
+   * @param fetchFn - fetch implementation (defaults to global fetch).
+   */
+  constructor(
+    private readonly url: string,
+    private readonly token: string,
+    private readonly timeoutMs: number,
+    private readonly fetchFn: FetchFace = fetch,
+  ) {}
+
+  /** Perform the initialize handshake and send the initialized notification. */
+  async initialize(): Promise<void> {
+    const response = await this.send({
+      jsonrpc: '2.0',
+      id: this.nextId++,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-03-26',
+        capabilities: {},
+        clientInfo: { name: 'dsh-ticktick', version: '0.1.0' },
+      },
+    }, false)
+    const body = await response.text()
+    if (response.status !== 200) throw new Error(`ticktick MCP initialize: HTTP ${response.status}: ${body.slice(0, 200)}`)
+    this.sessionId = response.headers.get('mcp-session-id') ?? undefined
+    const message = parseMcpMessage(body) as { readonly result?: { readonly protocolVersion?: string } } | undefined
+    this.protocolVersion = message?.result?.protocolVersion
+    if (this.protocolVersion === undefined) {
+      throw new Error(`ticktick MCP initialize: unexpected response: ${body.slice(0, 200)}`)
+    }
+    await this.post({ jsonrpc: '2.0', method: 'notifications/initialized' })
+  }
+
+  /** Fetch the server's tool list. */
+  async listTools(): Promise<readonly McpTool[]> {
+    const message = await this.post({ jsonrpc: '2.0', id: this.nextId++, method: 'tools/list', params: {} }) as
+      | { readonly result?: { readonly tools?: readonly McpTool[] } }
+      | undefined
+    return message?.result?.tools ?? []
+  }
+
+  /**
+   * Invoke one tool. A tool-level failure (the MCP result flag `isError`)
+   * throws with the server's message — TickTick reports validation failures
+   * that way, not as JSON-RPC errors.
+   * @param name - the raw MCP tool name.
+   * @param args - the tool arguments object.
+   * @returns the settled result (text blocks or structured content).
+   */
+  async callTool(name: string, args: Record<string, unknown>): Promise<McpCallResult> {
+    const message = await this.post({
+      jsonrpc: '2.0',
+      id: this.nextId++,
+      method: 'tools/call',
+      params: { name, arguments: args },
+    }) as { readonly result?: McpCallResult & { readonly isError?: boolean }; readonly error?: unknown } | undefined
+    if (message?.error !== undefined) {
+      throw new Error(`ticktick MCP tools/call ${name}: ${JSON.stringify(message.error)}`)
+    }
+    if (message?.result?.isError === true) {
+      const text = message.result.content
+        ?.filter(block => block.type === 'text' && block.text !== undefined)
+        .map(block => block.text)
+        .join('\n')
+      throw new Error(`ticktick MCP tools/call ${name}: ${text ?? 'unknown tool error'}`)
+    }
+    return message?.result ?? {}
+  }
+
+  /**
+   * Send one request and parse the response message: a 429 is retried once
+   * after Retry-After, any other non-2xx status throws, and an empty body
+   * (notification success) parses to `undefined`.
+   * @param request - JSON-RPC payload.
+   * @param carryHeaders - include session/protocol headers (false for initialize).
+   * @returns the parsed message, or `undefined` for an empty body.
+   */
+  private async post(request: McpRequest, carryHeaders = true): Promise<unknown | undefined> {
+    const response = await this.send(request, carryHeaders)
+    const body = await response.text()
+    if (response.status !== 200 && response.status !== 202) {
+      throw new Error(`ticktick MCP request failed: HTTP ${response.status}: ${body.slice(0, 200)}`)
+    }
+    return parseMcpMessage(body)
+  }
+
+  /**
+   * Send one request, retrying once after Retry-After when the server
+   * answers 429.
+   * @param request - JSON-RPC payload.
+   * @param carryHeaders - include session/protocol headers (false for initialize).
+   * @returns the raw response (body not yet read).
+   */
+  private async send(request: McpRequest, carryHeaders = true): Promise<Response> {
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      authorization: `Bearer ${this.token}`,
+    }
+    if (carryHeaders) {
+      if (this.sessionId !== undefined) headers['mcp-session-id'] = this.sessionId
+      if (this.protocolVersion !== undefined) headers['mcp-protocol-version'] = this.protocolVersion
+    }
+    const signal = AbortSignal.timeout(this.timeoutMs)
+    const send = async (): Promise<Response> =>
+      await this.fetchFn(this.url, { method: 'POST', headers, body: JSON.stringify(request), signal })
+    let response = await send()
+    if (response.status === 429) {
+      const retryAfter = parseRetryAfter(response.headers.get('retry-after'))
+      await delay(retryAfter, signal)
+      response = await send()
+    }
+    return response
+  }
+}
+
+/** Parse a Retry-After header (seconds or HTTP date), bounded to 60s. */
+function parseRetryAfter(value: string | null): number {
+  if (value === null) return 1_000
+  const seconds = Number(value)
+  if (Number.isFinite(seconds)) return Math.min(Math.max(seconds * 1_000, 0), 60_000)
+  const epoch = Date.parse(value)
+  if (Number.isFinite(epoch)) return Math.min(Math.max(epoch - Date.now(), 0), 60_000)
+  return 1_000
+}
+
+/** Abortable delay (bounded by the request timeout signal). */
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      reject(signal.reason)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}