@huui/cdx-switcher 1.8.7 → 1.9.0

package/api.d.mts

@@ -0,0 +1,129 @@
+//#region api.d.ts
+/** API 调用失败时使用的稳定错误代码，调用方应优先根据此字段处理。 */
+type CdxApiErrorCode = "CONFIGURATION_ERROR" | "CURRENT_ACCOUNT_UNAVAILABLE" | "ACCOUNT_LABEL_REQUIRED" | "ACCOUNT_LABEL_NOT_FOUND" | "ACCOUNT_LABEL_DUPLICATED" | "SECRET_STORE_UNAVAILABLE" | "CREDENTIAL_UNAVAILABLE" | "AUTH_FAILED" | "USAGE_UNAVAILABLE" | "NETWORK_ERROR";
+/** API 失败时的错误信息；不会包含访问令牌、刷新令牌或账号邮箱。 */
+interface CdxApiError {
+  /** 供程序稳定判断的错误代码。 */
+  code: CdxApiErrorCode;
+  /** 供日志或人工排查使用的可读错误说明。 */
+  message: string;
+  /** 为 true 时，调用方可以在退避后重试当前请求。 */
+  retryable: boolean;
+}
+/** 所有公开 API 统一使用的成功或失败返回结构。 */
+type CdxApiResult<T> = {
+  /** 调用是否成功。 */ok: true; /** 成功时返回的业务数据。 */
+  data: T;
+} | {
+  /** 调用是否成功。 */ok: false; /** 失败时返回的结构化错误信息。 */
+  error: CdxApiError;
+};
+/** 不暴露内部账号 ID 与邮箱的账号安全摘要。 */
+interface AccountSummary {
+  /** 用户通过 `cdx label` 设置的账号标签；未设置时为 null。 */
+  label: string | null;
+  /** 用于界面或日志展示的安全名称；未设置标签时显示“未命名账号 N”。 */
+  displayName: string;
+  /** 此账号是否为当前已写入开发工具认证文件的账号。 */
+  isCurrent: boolean;
+}
+/** `listAccounts` 成功时返回的数据。 */
+interface AccountListData {
+  /** 已配置账号的安全摘要列表，按 cdx 配置中的顺序排列。 */
+  accounts: AccountSummary[];
+}
+/** `getCurrentAccount` 成功时返回的数据。 */
+interface CurrentAccountData {
+  /** 当前启用账号的安全摘要。 */
+  account: AccountSummary;
+}
+/** 单个限额周期的规范化数据。 */
+interface UsageWindowData {
+  /** 限额周期类别；primary 为主周期，secondary 为辅助周期。 */
+  kind: "primary" | "secondary";
+  /** 当前周期已经使用的百分比，范围通常为 0 到 100。 */
+  usedPercent: number;
+  /** 当前周期剩余的百分比，按 100 - usedPercent 计算。 */
+  remainingPercent: number;
+  /** 此限额周期的总时长，单位为秒。 */
+  limitWindowSeconds: number;
+  /** 限额下次重置的 ISO 8601 时间字符串。 */
+  resetsAt: string;
+  /** 限额下次重置的 Unix 时间戳，单位为毫秒。 */
+  resetsAtUnixMs: number;
+  /** 相对于 checkedAt 的剩余时间，单位为毫秒；过期时为 0。 */
+  resetsInMs: number;
+}
+/** 账号额度附加信息。 */
+interface CreditsData {
+  /** 账号是否拥有可用额度。 */
+  hasCredits: boolean;
+  /** 额度是否不受余额限制。 */
+  unlimited: boolean;
+  /** 可用余额；上游未提供时为 null。 */
+  balance: number | null;
+}
+/** `getCurrentAccountUsage` 成功时返回的数据。 */
+interface CurrentAccountUsageData {
+  /** 被查询的当前启用账号。 */
+  account: AccountSummary;
+  /** 本次用量数据查询完成时的 ISO 8601 时间。 */
+  checkedAt: string;
+  /** 账号套餐类型；上游未提供时为 null。 */
+  planType: string | null;
+  /** 主周期和辅助周期的规范化限额数据。 */
+  windows: UsageWindowData[];
+  /** 账号额度信息；上游未提供时为 null。 */
+  credits: CreditsData | null;
+}
+/** 指定账号切换时的输入参数。 */
+interface SwitchToAccountInput {
+  /** 目标账号的唯一标签；标签重复或不存在时会返回结构化错误。 */
+  label: string;
+}
+/** 认证文件更新后的写入状态。 */
+interface AuthTargetWriteData {
+  /** OpenCode 认证文件的写入状态。 */
+  openCode: "written";
+  /** Codex CLI 认证文件的写入、清理或跳过状态。 */
+  codex: "written" | "cleared" | "skipped";
+  /** Pi Agent 认证文件的写入状态。 */
+  pi: "written";
+}
+/** `switchNextAccount` 与 `switchToAccount` 成功时返回的数据。 */
+interface AccountSwitchData {
+  /** 切换前当前启用账号的安全摘要。 */
+  previousAccount: AccountSummary;
+  /** 切换后当前启用账号的安全摘要。 */
+  currentAccount: AccountSummary;
+  /** 是否实际切换到了另一个账号；只有一个账号或指定当前账号时为 false。 */
+  changed: boolean;
+  /** 切换完成时的 ISO 8601 时间。 */
+  switchedAt: string;
+  /** 本次切换写入各开发工具认证文件的结果。 */
+  targets: AuthTargetWriteData;
+}
+/**
+ * 返回所有已配置账号的安全摘要。
+ *
+ * 不会返回账号邮箱、内部账号 ID 或任何认证凭据。
+ */
+declare const listAccounts: () => Promise<CdxApiResult<AccountListData>>;
+/** 返回当前已经写入开发工具认证文件的账号信息。 */
+declare const getCurrentAccount: () => Promise<CdxApiResult<CurrentAccountData>>;
+/**
+ * 查询当前启用账号的周期用量和下一次重置时间。
+ *
+ * 此方法不会输出 CLI 文本，也不会返回令牌或原始上游响应。
+ */
+declare const getCurrentAccountUsage: () => Promise<CdxApiResult<CurrentAccountUsageData>>;
+/** 按配置顺序切换到下一个账号。 */
+declare const switchNextAccount: () => Promise<CdxApiResult<AccountSwitchData>>;
+/**
+ * 按用户设置的唯一标签切换账号。
+ *
+ * 不接受账号邮箱或内部账号 ID；请先通过 CLI 的 `cdx label` 为账号设置标签。
+ */
+declare const switchToAccount: (input: SwitchToAccountInput) => Promise<CdxApiResult<AccountSwitchData>>;
+//#endregion
+export { AccountListData, AccountSummary, AccountSwitchData, AuthTargetWriteData, CdxApiError, CdxApiErrorCode, CdxApiResult, CreditsData, CurrentAccountData, CurrentAccountUsageData, SwitchToAccountInput, UsageWindowData, getCurrentAccount, getCurrentAccountUsage, listAccounts, switchNextAccount, switchToAccount };

package/api.mjs

@@ -0,0 +1,164 @@
+import { D as loadConfig, O as loadConfiguredSecretStoreSelection, m as createSecretStoreAdapterFromSelection, n as fetchUsage, t as switchAccountAtIndex } from "./account-switch-BDEmlyn5.mjs";
+//#region api.ts
+const success = (data) => ({
+	ok: true,
+	data
+});
+const failure = (code, message, retryable) => ({
+	ok: false,
+	error: {
+		code,
+		message,
+		retryable
+	}
+});
+const formatAccount = (account, index, currentIndex) => {
+	const label = account.label?.trim() || null;
+	return {
+		label,
+		displayName: label ?? `未命名账号 ${index + 1}`,
+		isCurrent: index === currentIndex
+	};
+};
+const loadApiConfig = async () => {
+	try {
+		return success(await loadConfig());
+	} catch {
+		return failure("CONFIGURATION_ERROR", "无法读取 cdx 账号配置。", false);
+	}
+};
+const resolveCurrentAccount = (config) => {
+	const account = config.accounts[config.current];
+	if (!account?.accountId) return failure("CURRENT_ACCOUNT_UNAVAILABLE", "当前启用账号不存在或账号配置无效。", false);
+	return success({
+		account,
+		index: config.current
+	});
+};
+const createConfiguredSecretStore = async () => {
+	try {
+		return success(createSecretStoreAdapterFromSelection(await loadConfiguredSecretStoreSelection() ?? "auto"));
+	} catch {
+		return failure("SECRET_STORE_UNAVAILABLE", "无法初始化系统凭据库。", false);
+	}
+};
+const mapUsageFailure = (result) => {
+	if (result.error.type === "auth_failed") return failure("AUTH_FAILED", "当前账号凭据不可用，请使用 CLI 完成登录或重新登录。", false);
+	if (result.error.type === "network_error") return failure("NETWORK_ERROR", "查询账号用量时网络请求失败。", true);
+	return failure("USAGE_UNAVAILABLE", "当前无法获取账号用量。", true);
+};
+const mapUsageWindow = (kind, snapshot, checkedAtMs) => {
+	const resetsAtUnixMs = snapshot.reset_at * 1e3;
+	return {
+		kind,
+		usedPercent: snapshot.used_percent,
+		remainingPercent: Math.max(0, 100 - snapshot.used_percent),
+		limitWindowSeconds: snapshot.limit_window_seconds,
+		resetsAt: new Date(resetsAtUnixMs).toISOString(),
+		resetsAtUnixMs,
+		resetsInMs: Math.max(0, resetsAtUnixMs - checkedAtMs)
+	};
+};
+const mapAuthTargets = (authResult) => ({
+	openCode: "written",
+	pi: "written",
+	codex: authResult.codexWritten ? "written" : authResult.codexCleared ? "cleared" : "skipped"
+});
+/**
+* 返回所有已配置账号的安全摘要。
+*
+* 不会返回账号邮箱、内部账号 ID 或任何认证凭据。
+*/
+const listAccounts = async () => {
+	const configResult = await loadApiConfig();
+	if (!configResult.ok) return configResult;
+	return success({ accounts: configResult.data.accounts.map((account, index) => formatAccount(account, index, configResult.data.current)) });
+};
+/** 返回当前已经写入开发工具认证文件的账号信息。 */
+const getCurrentAccount = async () => {
+	const configResult = await loadApiConfig();
+	if (!configResult.ok) return configResult;
+	const currentResult = resolveCurrentAccount(configResult.data);
+	if (!currentResult.ok) return currentResult;
+	return success({ account: formatAccount(currentResult.data.account, currentResult.data.index, configResult.data.current) });
+};
+/**
+* 查询当前启用账号的周期用量和下一次重置时间。
+*
+* 此方法不会输出 CLI 文本，也不会返回令牌或原始上游响应。
+*/
+const getCurrentAccountUsage = async () => {
+	const configResult = await loadApiConfig();
+	if (!configResult.ok) return configResult;
+	const currentResult = resolveCurrentAccount(configResult.data);
+	if (!currentResult.ok) return currentResult;
+	const secretStoreResult = await createConfiguredSecretStore();
+	if (!secretStoreResult.ok) return secretStoreResult;
+	const usageResult = await fetchUsage(currentResult.data.account.accountId, secretStoreResult.data);
+	if (!usageResult.ok) return mapUsageFailure(usageResult);
+	try {
+		const checkedAtMs = Date.now();
+		const windows = [];
+		if (usageResult.data.rate_limit?.primary_window) windows.push(mapUsageWindow("primary", usageResult.data.rate_limit.primary_window, checkedAtMs));
+		if (usageResult.data.rate_limit?.secondary_window) windows.push(mapUsageWindow("secondary", usageResult.data.rate_limit.secondary_window, checkedAtMs));
+		const credits = usageResult.data.credits ? {
+			hasCredits: usageResult.data.credits.has_credits,
+			unlimited: usageResult.data.credits.unlimited,
+			balance: usageResult.data.credits.balance ?? null
+		} : null;
+		return success({
+			account: formatAccount(currentResult.data.account, currentResult.data.index, configResult.data.current),
+			checkedAt: new Date(checkedAtMs).toISOString(),
+			planType: usageResult.data.plan_type ?? null,
+			windows,
+			credits
+		});
+	} catch {
+		return failure("USAGE_UNAVAILABLE", "上游用量数据格式异常，暂时无法解析。", true);
+	}
+};
+const switchToIndex = async (config, targetIndex) => {
+	const currentResult = resolveCurrentAccount(config);
+	if (!currentResult.ok) return currentResult;
+	const secretStoreResult = await createConfiguredSecretStore();
+	if (!secretStoreResult.ok) return secretStoreResult;
+	try {
+		const result = await switchAccountAtIndex(config, targetIndex, secretStoreResult.data);
+		return success({
+			previousAccount: formatAccount(currentResult.data.account, currentResult.data.index, currentResult.data.index),
+			currentAccount: formatAccount(result.account, result.currentIndex, result.currentIndex),
+			changed: result.previousIndex !== result.currentIndex,
+			switchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			targets: mapAuthTargets(result.authResult)
+		});
+	} catch {
+		return failure("CREDENTIAL_UNAVAILABLE", "无法读取目标账号凭据或更新认证文件。", true);
+	}
+};
+/** 按配置顺序切换到下一个账号。 */
+const switchNextAccount = async () => {
+	const configResult = await loadApiConfig();
+	if (!configResult.ok) return configResult;
+	const nextIndex = (configResult.data.current + 1) % configResult.data.accounts.length;
+	return switchToIndex(configResult.data, nextIndex);
+};
+/**
+* 按用户设置的唯一标签切换账号。
+*
+* 不接受账号邮箱或内部账号 ID；请先通过 CLI 的 `cdx label` 为账号设置标签。
+*/
+const switchToAccount = async (input) => {
+	const label = typeof input?.label === "string" ? input.label.trim() : "";
+	if (!label) return failure("ACCOUNT_LABEL_REQUIRED", "切换账号时必须提供非空标签。", false);
+	const configResult = await loadApiConfig();
+	if (!configResult.ok) return configResult;
+	const matchingIndices = configResult.data.accounts.map((account, index) => ({
+		account,
+		index
+	})).filter(({ account }) => account.label === label).map(({ index }) => index);
+	if (matchingIndices.length === 0) return failure("ACCOUNT_LABEL_NOT_FOUND", `未找到标签为“${label}”的账号。`, false);
+	if (matchingIndices.length > 1) return failure("ACCOUNT_LABEL_DUPLICATED", `账号标签“${label}”重复，无法确定切换目标。`, false);
+	return switchToIndex(configResult.data, matchingIndices[0]);
+};
+//#endregion
+export { getCurrentAccount, getCurrentAccountUsage, listAccounts, switchNextAccount, switchToAccount };

package/cdx.d.mts

@@ -0,0 +1,105 @@
+import { Command } from "commander";
+
+//#region lib/oauth/login.d.ts
+type AuthFlowMode = "auto" | "device";
+type PerformLoginOptions = {
+  authFlow?: AuthFlowMode;
+};
+declare const performLogin: (options?: PerformLoginOptions) => Promise<{
+  accountId: string;
+} | null>;
+//#endregion
+//#region lib/commands/login.d.ts
+type LoginDeps = {
+  performLogin?: typeof performLogin;
+};
+//#endregion
+//#region lib/commands/switch.d.ts
+declare const switchNext: () => Promise<void>;
+declare const switchToAccount: (identifier: string) => Promise<void>;
+//#endregion
+//#region lib/types.d.ts
+type SecretStoreSelection = "auto" | "legacy-keychain";
+type AccountRecord = {
+  accountId: string;
+  keychainService: string;
+  label?: string;
+};
+type Config = {
+  current: number;
+  accounts: AccountRecord[];
+  secretStore?: SecretStoreSelection;
+};
+type OAuthPayload = {
+  refresh: string;
+  access: string;
+  expires: number;
+  accountId: string;
+  idToken?: string;
+};
+//#endregion
+//#region lib/secrets/macos-cross-keychain.d.ts
+type BackendId = "native-macos" | "macos";
+type MacOSCrossKeychainBackendId = BackendId;
+//#endregion
+//#region lib/secrets/store.d.ts
+type SecretStoreCapability = {
+  available: boolean;
+  reason?: string;
+};
+type SecretStoreAdapter = {
+  id: string;
+  label: string;
+  getServiceName(accountId: string): string;
+  save(accountId: string, payload: OAuthPayload): Promise<void>;
+  load(accountId: string): Promise<OAuthPayload>;
+  delete(accountId: string): Promise<void>;
+  exists(accountId: string): Promise<boolean>;
+  listAccountIds(): Promise<string[]>;
+  getCapability(): SecretStoreCapability;
+};
+declare const createRuntimeSecretStoreAdapter: (platform?: NodeJS.Platform) => SecretStoreAdapter;
+declare const createSecretStoreAdapterFromSelection: (selection?: SecretStoreSelection, platform?: NodeJS.Platform) => SecretStoreAdapter;
+declare const resolveMacOSCrossKeychainBackendId: (platform?: NodeJS.Platform) => Promise<MacOSCrossKeychainBackendId | null>;
+declare const getSecretStoreAdapter: () => SecretStoreAdapter;
+declare const setSecretStoreAdapter: (adapter: SecretStoreAdapter) => void;
+declare const resetSecretStoreAdapter: () => void;
+//#endregion
+//#region lib/config.d.ts
+declare const loadConfig: () => Promise<Config>;
+declare const saveConfig: (config: Config) => Promise<void>;
+//#endregion
+//#region lib/auth.d.ts
+declare const writeAuthFile: (payload: OAuthPayload) => Promise<void>;
+declare const writeCodexAuthFile: (payload: OAuthPayload) => Promise<void>;
+declare const writePiAuthFile: (payload: OAuthPayload) => Promise<void>;
+type WriteAuthResult = {
+  piWritten: boolean;
+  codexWritten: boolean;
+  codexMissingIdToken: boolean;
+  codexCleared: boolean;
+};
+declare const writeAllAuthFiles: (payload: OAuthPayload) => Promise<WriteAuthResult>;
+//#endregion
+//#region lib/paths.d.ts
+type PathConfig = {
+  configDir: string;
+  configPath: string;
+  authPath: string;
+  codexAuthPath: string;
+  piAuthPath: string;
+};
+declare const getPaths: () => PathConfig;
+declare const setPaths: (paths: Partial<PathConfig>) => void;
+declare const resetPaths: () => void;
+declare const createTestPaths: (testDir: string) => PathConfig;
+//#endregion
+//#region lib/interactive.d.ts
+declare const runInteractiveMode: () => Promise<void>;
+//#endregion
+//#region cdx.d.ts
+declare const interactiveMode: () => Promise<void>;
+declare const getMacOSKeychainPromptWarning: (selection: SecretStoreSelection, platform?: NodeJS.Platform, backendId?: MacOSCrossKeychainBackendId | null) => string | null;
+declare const createProgram: (deps?: LoginDeps) => Command;
+//#endregion
+export { type AccountRecord, type Config, type MacOSCrossKeychainBackendId, type OAuthPayload, type SecretStoreAdapter, type SecretStoreSelection, createProgram, createRuntimeSecretStoreAdapter, createSecretStoreAdapterFromSelection, createTestPaths, getMacOSKeychainPromptWarning, getPaths, getSecretStoreAdapter, interactiveMode, loadConfig, resetPaths, resetSecretStoreAdapter, resolveMacOSCrossKeychainBackendId, runInteractiveMode, saveConfig, setPaths, setSecretStoreAdapter, switchNext, switchToAccount, writeAllAuthFiles, writeAuthFile, writeCodexAuthFile, writePiAuthFile };