@soimy/dingtalk 3.5.2 → 3.6.0

package/src/config-schema.ts

@@ -7,65 +7,78 @@ const AckReactionSchema = z.union([
   z.string().min(1),
 ]);
 
+const CardStreamingModeSchema = z.enum(["off", "answer", "all"]);
+const ContextVisibilitySchema = z.enum(["all", "allowlist", "allowlist_quote"]);
+
+/**
+ * Runtime-parsed DingTalk account config.
+ *
+ * Compatibility note:
+ * - `agentId`, `corpId`, `showThinkingStream`, and `asyncMode` are intentionally
+ *   not parsed here. They remain only in manifest metadata for legacy host/UI
+ *   compatibility and are ignored by the current runtime.
+ */
 const DingTalkAccountConfigShape = {
   /** Account name (optional display name) */
   name: z.string().optional(),
 
-  /** Whether this channel is enabled */
+  /** Enable or disable this DingTalk channel/account without deleting saved credentials. */
   enabled: z.boolean().optional().default(true),
 
-  /** DingTalk App Key (Client ID) - required for authentication */
+  /** DingTalk App Key (Client ID) used to authenticate API and Stream connections. */
   clientId: z.string().optional(),
 
-  /** DingTalk App Secret (Client Secret) - required for authentication */
+  /** DingTalk App Secret (Client Secret) used to obtain DingTalk access tokens. */
   clientSecret: z.string().optional(),
 
-  /** Direct message policy: open, pairing, or allowlist */
+  /** Direct-message access policy: open, pairing, or allowlist. */
   dmPolicy: z.enum(["open", "pairing", "allowlist"]).optional().default("open"),
 
-  /** Group message policy: open, allowlist, or disabled */
+  /** Group-message access policy: open, allowlist, or disabled. */
   groupPolicy: z.enum(["open", "allowlist", "disabled"]).optional().default("open"),
 
-  /** List of allowed user IDs for allowlist policy */
+  /** User IDs allowed when `dmPolicy` is `allowlist`. */
   allowFrom: z.array(z.string()).optional(),
 
-  /** List of allowed user IDs for group allowlist policy */
+  /** Sender IDs allowed when `groupPolicy` is `allowlist`. */
   groupAllowFrom: z.array(z.string()).optional(),
 
-  /** Default disabled. Enabling "all" allows learned displayName lookup but may misroute on stale/duplicate names and is available to all callers until upstream exposes requester authz context. */
+  /** Default disabled. Enabling `all` allows learned displayName lookup but may misroute on stale or duplicate names and is available to all callers until upstream exposes requester authz context. */
   displayNameResolution: z.enum(["disabled", "all"]).optional().default("disabled"),
 
+  /** Controls how much supplemental host context remains visible to the reply runtime. `allowlist_quote` is the safest advanced mode when only explicit quotes or replies should remain visible. */
+  contextVisibility: ContextVisibilitySchema.optional(),
+
+  /** Allowed remote media download hosts, IPs, or CIDRs for media fetches. */
   mediaUrlAllowlist: z.array(z.string()).optional(),
 
-  /** Native ack reaction mode: off, emoji, or kaomoji */
+  /** Native acknowledgement reaction mode: off, emoji, kaomoji, or a custom compatibility string. */
   ackReaction: AckReactionSchema.optional(),
 
+  /** Retention window in days for short-lived message context used by quoting and media recovery. */
   journalTTLDays: z.number().int().min(1).optional().default(DEFAULT_MESSAGE_CONTEXT_TTL_DAYS),
-  /** Enable debug logging */
+  /** Enable verbose DingTalk channel debug logging. */
   debug: z.boolean().optional().default(false),
 
-  /** Message type for replies: markdown or card */
+  /** Default reply delivery mode: markdown or card. */
   messageType: z.enum(["markdown", "card"]).optional().default("markdown"),
 
-  /** Card template ID for AI interactive cards
-   * obtain the template ID from DingTalk Developer Console.
-   * ref: https://github.com/soimy/openclaw-channel-dingtalk/blob/main/README.md#3-%E5%BB%BA%E7%AB%8B%E5%8D%A1%E7%89%87%E6%A8%A1%E6%9D%BF%E5%8F%AF%E9%80%89
-   */
+  /** Deprecated and ignored. AI card replies now always use the built-in DingTalk template contract. Keep only for backward-compatible config parsing. */
   cardTemplateId: z.string().optional(),
 
-  /** Card template key for streaming updates
-   * Default: 'content' - maps to the content field in the card template
-   * This key is used in the streaming API to update specific fields in the card.
-   */
+  /** Deprecated and ignored. The built-in AI card contract owns the streaming field mapping. Keep only for backward-compatible config parsing. */
   cardTemplateKey: z.string().optional().default("content"),
 
-  /** Per-group configuration, keyed by conversationId (supports "*" wildcard) */
+  /** Per-group overrides keyed by conversationId. Supports `*` as a wildcard fallback. */
   groups: z
     .record(
       z.string(),
       z.object({
+        /** Additional system prompt appended for this group. */
         systemPrompt: z.string().optional(),
+        /** Require an explicit @mention before the bot answers in this group. */
         requireMention: z.boolean().optional(),
+        /** Optional per-group sender allowlist for tighter access control than the channel default. */
         groupAllowFrom: z.array(z.string()).optional(),
       }),
     )
@@ -73,65 +86,95 @@ const DingTalkAccountConfigShape = {
 
   /** Connection robustness configuration */
 
-  /** Maximum number of connection attempts before giving up (default: 10) */
+  /** Maximum connection attempts in a single reconnect cycle before backing off or giving up. */
   maxConnectionAttempts: z.number().int().min(1).optional().default(10),
 
-  /** Initial reconnection delay in milliseconds (default: 1000ms) */
+  /** Initial reconnect backoff delay in milliseconds. */
   initialReconnectDelay: z.number().int().min(100).optional().default(1000),
 
-  /** Maximum reconnection delay in milliseconds for exponential backoff (default: 60000ms = 1 minute) */
+  /** Upper bound for reconnect backoff delay in milliseconds. */
   maxReconnectDelay: z.number().int().min(1000).optional().default(60000),
 
-  /** Jitter factor for reconnection delay randomization (0-1, default: 0.3) */
+  /** Randomization factor added to reconnect backoff to avoid synchronized reconnect storms. */
   reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
 
-  /** Maximum number of runtime reconnect cycles before giving up (default: 10) */
+  /** Maximum reconnect cycles before the channel stops retrying and waits for the next lifecycle restart. */
   maxReconnectCycles: z.number().int().min(1).optional().default(10),
 
-  /** Maximum time (ms) for a single reconnect cycle before starting a new cycle (default: 50000) */
+  /** Time limit in milliseconds for one reconnect cycle before starting a fresh cycle. */
   reconnectDeadlineMs: z.number().int().min(5000).optional().default(50000),
 
-  /** Whether to use ConnectionManager (default: true). When false, rely on DWClient native keepAlive+autoReconnect. */
+  /** Enable the plugin connection manager. Disable only when you intentionally rely on DWClient native keepAlive plus autoReconnect behavior. */
   useConnectionManager: z.boolean().optional().default(true),
 
-  /** Maximum inbound media file size in MB (overrides runtime default when set) */
+  /** Maximum inbound media size in MB accepted by the plugin. When omitted, the runtime default is used. */
   mediaMaxMb: z.number().int().min(1).optional(),
 
-  /** Whether to enable underlying stream keepAlive heartbeat; defaults to !useConnectionManager when omitted */
+  /** Enable the underlying Stream client heartbeat. When omitted, runtime derives a default from `useConnectionManager`. */
   keepAlive: z.boolean().optional(),
-  /** Bypass system/global HTTP(S) proxy for DingTalk outbound send/card/upload APIs */
+  /** Bypass global or system HTTP(S) proxy settings for DingTalk send, upload, and card APIs. */
   bypassProxyForSend: z.boolean().optional().default(false),
+  /** Controls the proactive-send permission reminder shown when a conversation has not granted send rights yet. */
   proactivePermissionHint: z
     .object({
+      /** Show the proactive-send permission hint when the runtime detects missing DingTalk proactive permission. */
       enabled: z.boolean().optional().default(true),
+      /** Minimum cooldown in hours before the same proactive permission hint can be shown again. */
       cooldownHours: z.number().int().min(1).max(24 * 30).optional().default(24),
     })
     .optional()
     .default({ enabled: true, cooldownHours: 24 }),
 
-  /** Enable real-time card streaming (default: false).
-   *  When true, card updates are streamed per-token with 300ms throttle for a smoother experience, at the cost of more API calls. */
-  cardRealTimeStream: z.boolean().optional().default(false),
+  /** Deprecated compatibility flag. When true and `cardStreamingMode` is unset, runtime resolves to `cardStreamingMode: "all"`. Do not use in new configs. */
+  cardRealTimeStream: z.boolean().optional(),
+
+  /** Card streaming mode:
+   *  - off: disable incremental streaming
+   *  - answer: stream answer text
+   *  - all: stream answer + reasoning or thinking text */
+  cardStreamingMode: CardStreamingModeSchema.optional(),
 
-  /** AICard degrade duration in milliseconds after trigger errors (default: 30 minutes) */
+  /** Throttle interval in milliseconds between AI card streaming updates. */
+  cardStreamInterval: z.number().int().min(200).optional().default(1000),
+
+  /** Cooldown window in milliseconds after AI card trigger errors. Replies fall back to non-card delivery during this period. */
   aicardDegradeMs: z.number().int().min(60_000).optional().default(30 * 60 * 1000),
 
-  /** Enable local learning loop (default: false) */
+  /** Enable the local feedback-learning loop for notes, reflections, and command-assisted learning. */
   learningEnabled: z.boolean().optional(),
 
-  /** Auto-apply generated reflections into session notes/global rules (default: false) */
+  /** Automatically apply generated learning output into session notes or global rules when available. */
   learningAutoApply: z.boolean().optional(),
 
-  /** Session learning note TTL in milliseconds (default: 6 hours) */
+  /** Retention window in milliseconds for temporary learning notes. */
   learningNoteTtlMs: z.number().int().min(60_000).optional(),
 
-  /** Whether to convert markdown tables to plain text for better rendering on some clients (default: true) */
+  /** Convert markdown tables to plain text before sending when you want more consistent DingTalk rendering. */
   convertMarkdownTables: z.boolean().optional().default(true),
 
   /** @mention the sender after card finalization in group chats.
    *  Set to a non-empty string (e.g. "✅ 回复完成") to enable — the value is used as the message text.
    *  Leave empty or omit to disable. */
   cardAtSender: z.string().optional(),
+
+  /** Status line visibility toggles for the AI card footer. */
+  cardStatusLine: z
+    .object({
+      /** Show model name. */
+      model: z.boolean().optional().default(true),
+      /** Show thinking effort level. */
+      effort: z.boolean().optional().default(true),
+      /** Show agent display name. */
+      agent: z.boolean().optional().default(true),
+      /** Show task elapsed time. */
+      taskTime: z.boolean().optional().default(false),
+      /** Show token usage summary (input/output/cache). */
+      tokens: z.boolean().optional().default(false),
+      /** Show DingTalk API call count. */
+      dapiUsage: z.boolean().optional().default(false),
+    })
+    .optional()
+    .default({ model: true, effort: true, agent: true, taskTime: false, tokens: false, dapiUsage: false }),
 } as const;
 
 const DingTalkAccountConfigSchema = z.object(DingTalkAccountConfigShape);

package/src/config.ts

@@ -1,7 +1,7 @@
 import * as os from "node:os";
 import * as path from "node:path";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
-import type { DingTalkConfig } from "./types";
+import type { DingTalkChannelConfig, DingTalkConfig } from "./types";
 
 const WINDOWS_ROOT_DIRECTORIES = new Set([
   "Users",
@@ -26,12 +26,34 @@ function normalizeLearningConfig(
     learningNoteTtlMs: options.applyDefaults
       ? config.learningNoteTtlMs ?? DEFAULT_LEARNING_NOTE_TTL_MS
       : config.learningNoteTtlMs,
+    cardStreamingMode: options.applyDefaults
+      ? (config.cardStreamingMode ?? (config.cardRealTimeStream === true ? "all" : "off"))
+      : config.cardStreamingMode,
   };
 }
 
 function stripRemovedLegacyFields(config: DingTalkConfig): DingTalkConfig {
-  const { verboseRealtimeStream: _verboseRealtimeStream, ...rest } =
-    config as DingTalkConfig & { verboseRealtimeStream?: unknown };
+  const {
+    verboseRealtimeStream: _verboseRealtimeStream,
+    cardStreamReasoning: _cardStreamReasoning,
+    accounts,
+    ...rest
+  } = config as DingTalkConfig & {
+    verboseRealtimeStream?: unknown;
+    cardStreamReasoning?: unknown;
+    accounts?: Record<string, DingTalkConfig | undefined>;
+  };
+  const sanitizedAccounts = accounts
+    ? Object.fromEntries(
+        Object.entries(accounts).map(([accountId, accountConfig]) => [
+          accountId,
+          accountConfig ? stripRemovedLegacyFields(accountConfig) : accountConfig,
+        ]),
+      )
+    : undefined;
+  if (sanitizedAccounts) {
+    return { ...rest, accounts: sanitizedAccounts } as DingTalkConfig;
+  }
   return rest as DingTalkConfig;
 }
 
@@ -84,7 +106,7 @@ export function getConfig(cfg: OpenClawConfig, accountId?: string): DingTalkConf
   }
 
   if (dingtalkCfg.accounts && Object.keys(dingtalkCfg.accounts).length > 0) {
-    return dingtalkCfg;
+    return stripRemovedLegacyFields(dingtalkCfg);
   }
 
   return stripRemovedLegacyFields(normalizeLearningConfig(dingtalkCfg, { applyDefaults: true }));
@@ -250,3 +272,119 @@ export function stripTargetPrefix(target: string): { targetId: string; isExplici
   }
   return { targetId: target, isExplicitUser: false };
 }
+
+// ============ Onboarding Helper Functions ============
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+
+/**
+ * List all DingTalk account IDs from config
+ */
+export function listDingTalkAccountIds(cfg: OpenClawConfig): string[] {
+  const dingtalk = cfg.channels?.dingtalk as DingTalkChannelConfig | undefined;
+  if (!dingtalk) {
+    return [];
+  }
+
+  const accountIds: string[] = [];
+
+  if (dingtalk.clientId || dingtalk.clientSecret) {
+    accountIds.push(DEFAULT_ACCOUNT_ID);
+  }
+
+  if (dingtalk.accounts) {
+    accountIds.push(...Object.keys(dingtalk.accounts));
+  }
+
+  return accountIds;
+}
+
+/**
+ * Resolved DingTalk account with configuration status
+ */
+export interface ResolvedDingTalkAccount extends DingTalkConfig {
+  accountId: string;
+  configured: boolean;
+}
+
+/**
+ * Resolve a specific DingTalk account configuration
+ */
+export function resolveDingTalkAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): ResolvedDingTalkAccount {
+  const id = accountId || DEFAULT_ACCOUNT_ID;
+  const dingtalk = cfg.channels?.dingtalk as DingTalkChannelConfig | undefined;
+
+  if (id === DEFAULT_ACCOUNT_ID) {
+    const rawConfig: DingTalkConfig = {
+      clientId: dingtalk?.clientId ?? "",
+      clientSecret: dingtalk?.clientSecret ?? "",
+      name: dingtalk?.name,
+      enabled: dingtalk?.enabled,
+      dmPolicy: dingtalk?.dmPolicy,
+      groupPolicy: dingtalk?.groupPolicy,
+      allowFrom: dingtalk?.allowFrom,
+      groupAllowFrom: dingtalk?.groupAllowFrom,
+      displayNameResolution: dingtalk?.displayNameResolution,
+      contextVisibility: dingtalk?.contextVisibility,
+      journalTTLDays: dingtalk?.journalTTLDays,
+      ackReaction: dingtalk?.ackReaction,
+      debug: dingtalk?.debug,
+      messageType: dingtalk?.messageType,
+      cardTemplateId: dingtalk?.cardTemplateId,
+      cardTemplateKey: dingtalk?.cardTemplateKey,
+      groups: dingtalk?.groups,
+      accounts: dingtalk?.accounts,
+      maxConnectionAttempts: dingtalk?.maxConnectionAttempts,
+      initialReconnectDelay: dingtalk?.initialReconnectDelay,
+      maxReconnectDelay: dingtalk?.maxReconnectDelay,
+      reconnectJitter: dingtalk?.reconnectJitter,
+      maxReconnectCycles: dingtalk?.maxReconnectCycles,
+      reconnectDeadlineMs: dingtalk?.reconnectDeadlineMs,
+      useConnectionManager: dingtalk?.useConnectionManager,
+      mediaMaxMb: dingtalk?.mediaMaxMb,
+      keepAlive: dingtalk?.keepAlive,
+      bypassProxyForSend: dingtalk?.bypassProxyForSend,
+      proactivePermissionHint: dingtalk?.proactivePermissionHint,
+      cardStreamingMode: dingtalk?.cardStreamingMode,
+      cardRealTimeStream: dingtalk?.cardRealTimeStream,
+      cardStreamInterval: dingtalk?.cardStreamInterval,
+      aicardDegradeMs: dingtalk?.aicardDegradeMs,
+      learningEnabled: dingtalk?.learningEnabled,
+      learningAutoApply: dingtalk?.learningAutoApply,
+      learningNoteTtlMs: dingtalk?.learningNoteTtlMs,
+      convertMarkdownTables: dingtalk?.convertMarkdownTables,
+      cardAtSender: dingtalk?.cardAtSender,
+    };
+    const config = stripRemovedLegacyFields(rawConfig);
+    return {
+      ...config,
+      accountId: id,
+      configured: Boolean(config.clientId && config.clientSecret),
+    };
+  }
+
+  const accountConfig = dingtalk?.accounts?.[id];
+  if (accountConfig) {
+    const merged = mergeAccountWithDefaults(
+      dingtalk as DingTalkConfig,
+      accountConfig,
+    );
+    const publicMerged = stripRemovedLegacyFields(merged);
+    return {
+      ...publicMerged,
+      accountId: id,
+      configured: Boolean(merged.clientId && merged.clientSecret),
+    };
+  }
+
+  return {
+    clientId: "",
+    clientSecret: "",
+    accountId: id,
+    configured: false,
+  };
+}

package/src/device-registration.ts

@@ -0,0 +1,245 @@
+import { execFile } from "node:child_process";
+import httpClient from "./http-client.js";
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const REGISTRATION_BASE_URL = "https://oapi.dingtalk.com";
+const REGISTRATION_SOURCE = "openClaw";
+const RETRY_WINDOW_MS = 120_000; // 2 minutes for transient errors
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export class RegistrationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistrationError";
+  }
+}
+
+export interface RegistrationResult {
+  clientId: string;
+  clientSecret: string;
+}
+
+interface BeginResult {
+  deviceCode: string;
+  verificationUrl: string;
+  expiresIn: number;
+  interval: number;
+}
+
+type PollStatus = "WAITING" | "SUCCESS" | "FAIL" | "EXPIRED";
+
+interface PollResult {
+  status: PollStatus;
+  clientId?: string;
+  clientSecret?: string;
+  failReason?: string;
+}
+
+// ── Internal helpers ───────────────────────────────────────────────────────
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+async function apiPost(
+  path: string,
+  payload: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const url = `${REGISTRATION_BASE_URL}${path}`;
+  const resp = await httpClient.post(url, payload, { timeout: 15_000 });
+  const data = resp.data as Record<string, unknown>;
+  const errcode = data.errcode;
+  if (errcode !== undefined && errcode !== 0) {
+    const errmsg = asString(data.errmsg) || "unknown error";
+    throw new RegistrationError(`API error [${path}]: ${errmsg} (errcode=${typeof errcode === "number" ? errcode : asString(errcode)})`);
+  }
+  return data;
+}
+
+// ── Step 1: init → nonce ───────────────────────────────────────────────────
+
+async function initRegistration(): Promise<string> {
+  const data = await apiPost("/app/registration/init", { source: REGISTRATION_SOURCE });
+  const nonce = asString(data.nonce).trim();
+  if (!nonce) {
+    throw new RegistrationError("init response missing nonce");
+  }
+  return nonce;
+}
+
+// ── Step 2: begin → deviceCode + verificationUrl ───────────────────────────
+
+async function beginRegistration(nonce: string): Promise<BeginResult> {
+  const data = await apiPost("/app/registration/begin", { nonce });
+  const deviceCode = asString(data.device_code).trim();
+  const verificationUrl = asString(data.verification_uri_complete).trim();
+  if (!deviceCode) {
+    throw new RegistrationError("begin response missing device_code");
+  }
+  if (!verificationUrl) {
+    throw new RegistrationError("begin response missing verification_uri_complete");
+  }
+  return {
+    deviceCode,
+    verificationUrl,
+    expiresIn: Number(data.expires_in ?? 7200) || 7200,
+    interval: Math.max(Number(data.interval ?? 3) || 3, 2),
+  };
+}
+
+// ── Step 3: poll ───────────────────────────────────────────────────────────
+
+async function pollRegistration(deviceCode: string): Promise<PollResult> {
+  const data = await apiPost("/app/registration/poll", { device_code: deviceCode });
+  const raw = asString(data.status).trim().toUpperCase();
+  const status: PollStatus = ["WAITING", "SUCCESS", "FAIL", "EXPIRED"].includes(raw)
+    ? (raw as PollStatus)
+    : "FAIL";
+  return {
+    status,
+    clientId: asString(data.client_id).trim() || undefined,
+    clientSecret: asString(data.client_secret).trim() || undefined,
+    failReason: asString(data.fail_reason).trim() || undefined,
+  };
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+export interface DeviceRegistrationSession {
+  verificationUrl: string;
+  waitForResult: (options?: {
+    onWaiting?: () => void;
+    signal?: AbortSignal;
+  }) => Promise<RegistrationResult>;
+}
+
+export async function beginDeviceRegistration(): Promise<DeviceRegistrationSession> {
+  const nonce = await initRegistration();
+  const { deviceCode, verificationUrl, expiresIn, interval } = await beginRegistration(nonce);
+
+  const waitForResult = async (options?: {
+    onWaiting?: () => void;
+    signal?: AbortSignal;
+  }): Promise<RegistrationResult> => {
+    const deadline = Date.now() + expiresIn * 1000;
+    let networkRetryStart = 0;
+    let statusRetryStart = 0;
+
+    const signal = options?.signal;
+    let abortHandler: (() => void) | null = null;
+    const abortPromise = signal
+      ? new Promise<never>((_resolve, reject) => {
+          abortHandler = () => reject(new RegistrationError("registration cancelled"));
+          signal.addEventListener("abort", abortHandler, { once: true });
+        })
+      : null;
+    // Suppress unhandled rejection when abort fires outside Promise.race
+    abortPromise?.catch(() => {});
+
+    const sleep = () =>
+      new Promise((resolve) => setTimeout(resolve, interval * 1000));
+
+    try {
+      while (Date.now() < deadline) {
+        if (signal?.aborted) {
+          throw new RegistrationError("registration cancelled");
+        }
+
+        // AbortSignal-aware sleep
+        await (abortPromise ? Promise.race([sleep(), abortPromise]) : sleep());
+
+        // Check again after sleep — abort may have fired during sleep
+        if (signal?.aborted) {
+          throw new RegistrationError("registration cancelled");
+        }
+
+        let result: PollResult;
+        try {
+          result = await pollRegistration(deviceCode);
+        } catch {
+          if (!networkRetryStart) {
+            networkRetryStart = Date.now();
+          }
+          if (Date.now() - networkRetryStart < RETRY_WINDOW_MS) {
+            continue;
+          }
+          throw new RegistrationError("registration polling failed after retry window");
+        }
+
+        // Successful poll resets network retry window
+        networkRetryStart = 0;
+
+        const { status } = result;
+
+        if (status === "WAITING") {
+          statusRetryStart = 0;
+          options?.onWaiting?.();
+          continue;
+        }
+
+        if (status === "SUCCESS") {
+          const clientId = result.clientId;
+          const clientSecret = result.clientSecret;
+          if (!clientId || !clientSecret) {
+            throw new RegistrationError("authorization succeeded but credentials are missing");
+          }
+          return { clientId, clientSecret };
+        }
+
+        if (status === "EXPIRED") {
+          throw new RegistrationError("authorization expired, please restart registration");
+        }
+
+        // FAIL — retry within window
+        if (!statusRetryStart) {
+          statusRetryStart = Date.now();
+        }
+        if (Date.now() - statusRetryStart < RETRY_WINDOW_MS) {
+          continue;
+        }
+        throw new RegistrationError(`authorization failed: ${result.failReason ?? status}`);
+      }
+
+      throw new RegistrationError("authorization timed out, please retry");
+    } finally {
+      if (abortHandler && signal) {
+        signal.removeEventListener("abort", abortHandler);
+      }
+    }
+  };
+
+  return { verificationUrl, waitForResult };
+}
+
+// ── Browser helper ─────────────────────────────────────────────────────────
+
+export function openUrlInBrowser(url: string): void {
+  // Validate URL before handing to OS launcher
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" || !parsed.hostname.endsWith(".dingtalk.com")) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  const platform = process.platform;
+  let bin: string;
+  let args: string[];
+  if (platform === "darwin") {
+    bin = "open";
+    args = [url];
+  } else if (platform === "win32") {
+    bin = "cmd";
+    args = ["/c", "start", "", url];
+  } else {
+    bin = "xdg-open";
+    args = [url];
+  }
+  execFile(bin, args, (err) => {
+    void err;
+  });
+}