@zhin.js/plugin-calendar 0.1.5 → 0.1.7

package/src/chat-auth.ts

@@ -1,3 +1,6 @@
+import { CalendarError } from './errors.js';
+import { resolveLocale, type Locale } from 'zhin.js/i18n';
+import { messages as t } from './i18n.js';
 /**
  * Chat-driven OAuth authorization: `calendar auth <provider>` creates a PKCE
  * link, the HTTP callback exchanges the code, stores the refresh token in the
@@ -31,11 +34,13 @@ export const OAUTH_PROVIDERS: readonly OAuthProviderKind[] = [
 
 export type CalendarNotifier<Target> = (
   target: Target,
-  text: string
+  text: string,
+  locale: Locale
 ) => Promise<void>;
 
 export interface CalendarAuthServiceOptions<Target> {
   readonly config: CalendarConfig;
+  readonly locale?: Locale;
   readonly managers: Partial<Record<OAuthProviderKind, OAuthTokenManager>>;
   readonly credentials: CalendarCredentialStore | undefined;
   readonly notify: CalendarNotifier<Target> | undefined;
@@ -56,10 +61,6 @@ interface ClientCredentials {
   readonly tenant: string;
 }
 
-const PROVIDER_DISPLAY_NAME: Record<OAuthProviderKind, string> = {
-  google: "Google 日历",
-  microsoft: "Outlook 日历",
-};
 
 export function parseOAuthProvider(
   value: unknown
@@ -117,6 +118,7 @@ export function localOriginFromAddress(address: {
 
 export class CalendarAuthService<Target> {
   readonly #config: CalendarConfig;
+  readonly #locale: Locale;
   readonly #managers: Partial<Record<OAuthProviderKind, OAuthTokenManager>>;
   readonly #credentials: CalendarCredentialStore | undefined;
   readonly #notify: CalendarNotifier<Target> | undefined;
@@ -126,6 +128,7 @@ export class CalendarAuthService<Target> {
 
   constructor(options: CalendarAuthServiceOptions<Target>) {
     this.#config = options.config;
+    this.#locale = resolveLocale(options.locale);
     this.#managers = options.managers;
     this.#credentials = options.credentials;
     this.#notify = options.notify;
@@ -137,19 +140,20 @@ export class CalendarAuthService<Target> {
   /** Handles `calendar auth <provider>` and returns the chat reply. */
   async startAuthorization(
     provider: OAuthProviderKind,
-    requester: CredentialOwner<Target>
+    requester: CredentialOwner<Target>,
+    locale: Locale = resolveLocale(requester.locale)
   ): Promise<string> {
-    const displayName = PROVIDER_DISPLAY_NAME[provider];
+    const displayName = t(locale, provider);
     if (!this.#credentials) {
-      return "日历授权需要数据库（databaseHostToken）来保存 refresh_token，当前不可用。";
+      return t(locale, 'needsDatabase');
     }
     const client = this.#clientCredentials(provider);
     if (!client) {
-      return this.#missingClientMessage(provider);
+      return this.#missingClientMessage(provider, locale);
     }
     const redirectUri = this.#resolveRedirectUri();
     if (!redirectUri) {
-      return "未找到 HTTP 服务地址：请启用 zhin 的 HTTP Host，或在 plugins.calendar.oauth_redirect_base_url 配置外部可访问地址。";
+      return t(locale, 'needsHttp');
     }
 
     const pkce = createPkcePair();
@@ -159,7 +163,7 @@ export class CalendarAuthService<Target> {
       state,
       codeVerifier: pkce.verifier,
       redirectUri,
-      requester,
+      requester: { ...requester, locale },
     });
     const authorizeUrl = buildAuthorizeUrl({
       provider,
@@ -172,11 +176,11 @@ export class CalendarAuthService<Target> {
 
     const validMinutes = Math.round(OAUTH_SESSION_TTL_MS / 60_000);
     return [
-      `请在浏览器打开下面的链接完成${displayName}授权（${validMinutes} 分钟内有效，只能使用一次）：`,
+      t(locale, 'openLink', { provider: displayName, minutes: validMinutes }),
       authorizeUrl,
       "",
-      `回调地址：${redirectUri}`,
-      "该地址必须能从打开链接的浏览器访问，并已登记在 OAuth 客户端的重定向 URI 中。",
+      t(locale, 'callback', { url: redirectUri }),
+      t(locale, 'callbackHelp'),
     ].join("\n");
   }
 
@@ -188,21 +192,23 @@ export class CalendarAuthService<Target> {
       return {
         statusCode: 400,
         message:
-          "授权链接无效、已使用或已过期，请在聊天中重新发送 calendar auth 命令。",
+          t(this.#locale, 'invalidLink'),
       };
     }
 
+    const locale = resolveLocale(session.requester.locale);
     const provider = session.provider;
-    const displayName = PROVIDER_DISPLAY_NAME[provider];
+    const displayName = t(locale, provider);
     const oauthError = searchParams.get("error");
     if (oauthError) {
       const description = searchParams.get("error_description") ?? "";
       const detail = `${oauthError} ${description}`.trim();
       await this.#notifySafely(
         session.requester.target,
-        `${displayName}授权失败：${detail}`
+        t(locale, 'failed', { provider: displayName, detail }),
+        locale
       );
-      return { statusCode: 400, message: `授权失败：${detail}` };
+      return { statusCode: 400, message: t(locale, 'callbackFailed', { detail }) };
     }
 
     const code = searchParams.get("code") ?? "";
@@ -210,7 +216,7 @@ export class CalendarAuthService<Target> {
     if (!code || !client || !this.#credentials) {
       return {
         statusCode: 400,
-        message: "缺少授权码或客户端配置，请重新授权。",
+        message: t(locale, 'codeMissing'),
       };
     }
 
@@ -232,79 +238,78 @@ export class CalendarAuthService<Target> {
       );
       this.#managers[provider]?.setRefreshToken(tokens.refreshToken);
     } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
+      const reason = error instanceof CalendarError ? error.format(locale) : error instanceof Error ? error.message : String(error);
       await this.#notifySafely(
         session.requester.target,
-        `${displayName}授权失败：${reason}`
+        t(locale, 'failed', { provider: displayName, detail: reason }),
+        locale
       );
-      return { statusCode: 502, message: `授权失败：${reason}` };
+      return { statusCode: 502, message: t(locale, 'callbackFailed', { detail: reason }) };
     }
 
     const providerHint =
       this.#config.provider === provider
         ? ""
-        : `\n注意：当前 plugins.calendar.provider 是 ${
-            this.#config.provider
-          }，日历工具不会使用 ${provider}。`;
+        : t(locale, 'otherProvider', { current: this.#config.provider, provider });
     await this.#notifySafely(
       session.requester.target,
-      `${displayName}授权成功，refresh_token 已保存到插件数据库。${providerHint}`
+      t(locale, 'authorized', { provider: displayName, hint: providerHint }),
+      locale
     );
-    return { statusCode: 200, message: "授权成功，可以关闭此页回到聊天。" };
+    return { statusCode: 200, message: t(locale, 'callbackSuccess') };
   }
 
   /** Handles `calendar status`. */
-  async describeStatus(): Promise<string> {
-    const lines = [`当前 provider：${this.#config.provider}`];
+  async describeStatus(locale?: Locale, authCommand?: string): Promise<string> {
+    const lines = [t(locale, 'currentProvider', { provider: this.#config.provider })];
     for (const provider of OAUTH_PROVIDERS) {
-      lines.push(await this.#describeProvider(provider));
+      lines.push(await this.#describeProvider(provider, locale, authCommand));
     }
     return lines.join("\n");
   }
 
   /** Handles `calendar logout <provider>`: removes the stored token. */
-  async logout(provider: OAuthProviderKind): Promise<string> {
-    const displayName = PROVIDER_DISPLAY_NAME[provider];
+  async logout(provider: OAuthProviderKind, locale?: Locale): Promise<string> {
+    const displayName = t(locale, provider);
     if (!this.#credentials) {
-      return "数据库不可用，没有可删除的授权。";
+      return t(locale, 'noDatabase');
     }
     await this.#credentials.delete(provider);
     this.#managers[provider]?.clearTokens();
-    return `已删除${displayName}在插件数据库中的授权。若 .env 里仍有 refresh_token，重载配置后会继续作为后备使用。`;
+    return t(locale, 'loggedOut', { provider: displayName });
   }
 
   /** Called by the token manager once when the refresh token is rejected. */
   async notifyAuthorizationLost(
     provider: OAuthProviderKind,
-    message: string
+    _message: string
   ): Promise<void> {
     const credential = await this.#credentials?.get(provider);
     const owner = credential?.authorized_by as CredentialOwner<Target> | null;
     if (!owner) {
       return;
     }
-    await this.#notifySafely(owner.target, message);
+    const locale = resolveLocale(owner.locale);
+    await this.#notifySafely(owner.target, t(locale, 'lost', { provider: t(locale, provider) }), locale);
   }
 
-  async #describeProvider(provider: OAuthProviderKind): Promise<string> {
-    const displayName = PROVIDER_DISPLAY_NAME[provider];
+  async #describeProvider(provider: OAuthProviderKind, locale?: Locale, authCommand?: string): Promise<string> {
+    const displayName = t(locale, provider);
     if (!this.#clientCredentials(provider)) {
-      return `${displayName}：未配置 client_id`;
+      return t(locale, 'clientMissing', { provider: displayName });
     }
     const credential = await this.#credentials?.get(provider);
     const manager = this.#managers[provider];
     if (manager?.authorizationLost) {
-      return `${displayName}：授权已失效，请发送「${authCommandFor(
-        provider
-      )}」`;
+      return [t(locale, 'lost', { provider: displayName }), authCommand ? t(locale, 'commandHint', { command: authCommandFor(provider, authCommand)! }) : ''].filter(Boolean).join(' ');
     }
     if (credential) {
-      return `${displayName}：已授权（数据库，${credential.authorized_at}）`;
+      return t(locale, 'databaseStatus', { provider: displayName, at: credential.authorized_at });
     }
     if (manager?.hasRefreshToken) {
-      return `${displayName}：使用配置/环境变量中的 refresh_token`;
+      return t(locale, 'envStatus', { provider: displayName });
     }
-    return `${displayName}：未授权，请发送「${authCommandFor(provider)}」`;
+    return [t(locale, 'notAuthorized', { provider: displayName }), authCommand ? t(locale, 'commandHint', { command: authCommandFor(provider, authCommand)! }) : ''].filter(Boolean).join(' ');
   }
 
   #clientCredentials(
@@ -331,19 +336,19 @@ export class CalendarAuthService<Target> {
     };
   }
 
-  #missingClientMessage(provider: OAuthProviderKind): string {
+  #missingClientMessage(provider: OAuthProviderKind, locale?: Locale): string {
     if (provider === "google") {
-      return "请先在 plugins.calendar.google 配置 client_id 和 client_secret（例如 ${GOOGLE_CALENDAR_CLIENT_ID} / ${GOOGLE_CALENDAR_CLIENT_SECRET}）。";
+      return t(locale, 'googleClient');
     }
-    return "请先在 plugins.calendar.microsoft 配置 client_id（例如 ${MS_GRAPH_CLIENT_ID}）。";
+    return t(locale, 'microsoftClient');
   }
 
-  async #notifySafely(target: Target, text: string): Promise<void> {
+  async #notifySafely(target: Target, text: string, locale: Locale): Promise<void> {
     if (!this.#notify) {
       return;
     }
     try {
-      await this.#notify(target, text);
+      await this.#notify(target, text, locale);
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error);
       console.warn(`[calendar] 发送授权通知失败：${reason}`);

package/src/config.ts

@@ -8,11 +8,11 @@ export const calendarConfig = Schema.object({
     Schema.const("microsoft"),
   ])
     .default("none")
-    .description("日历后端；none 时工具返回未启用提示")
+    .description("日历后端；none 时工具返回未启用提示").i18n({"en": {"description": "Calendar backend. Tools report that the calendar is disabled when set to none."}})
     .effect("reload"),
   timezone: Schema.string()
     .default("Asia/Manila")
-    .description("解释无偏移时间与展示用的 IANA 时区")
+    .description("解释无偏移时间与展示用的 IANA 时区").i18n({"en": {"description": "IANA timezone for interpreting times without offsets and for display."}})
     .effect("reload"),
   work_day_start: Schema.string().default("09:00").effect("reload"),
   work_day_end: Schema.string().default("18:00").effect("reload"),
@@ -32,7 +32,7 @@ export const calendarConfig = Schema.object({
     enabled: Schema.boolean().default(false),
     calendar_url: Schema.string()
       .default("")
-      .description("日历 collection URL")
+      .description("日历 collection URL").i18n({"en": {"description": "Calendar collection URL."}})
       .effect("reload"),
     username: Schema.string().default("").effect("reload"),
     password: Schema.string().default("").effect("reload"),
@@ -49,11 +49,11 @@ export const calendarConfig = Schema.object({
       .effect("reload"),
     refresh_token: Schema.string()
       .default("")
-      .description("${GOOGLE_CALENDAR_REFRESH_TOKEN}；用 auth google 获取")
+      .description("${GOOGLE_CALENDAR_REFRESH_TOKEN}；用 auth google 获取").i18n({"en": {"description": "${GOOGLE_CALENDAR_REFRESH_TOKEN}; obtain using the calendar authorization flow."}})
       .effect("reload"),
     calendar_id: Schema.string()
       .default("primary")
-      .description("日历 ID，默认 primary；可换成其它日历的 id")
+      .description("日历 ID，默认 primary；可换成其它日历的 id").i18n({"en": {"description": "Calendar ID, primary by default; can be set to another calendar ID."}})
       .effect("reload"),
     token_file: Schema.string()
       .default("")
@@ -70,19 +70,19 @@ export const calendarConfig = Schema.object({
       .effect("reload"),
     client_secret: Schema.string()
       .default("")
-      .description("可选；公共客户端可留空。${MS_GRAPH_CLIENT_SECRET}")
+      .description("可选；公共客户端可留空。${MS_GRAPH_CLIENT_SECRET}").i18n({"en": {"description": "Optional for public clients. ${MS_GRAPH_CLIENT_SECRET}"}})
       .effect("reload"),
     refresh_token: Schema.string()
       .default("")
-      .description("${MS_GRAPH_REFRESH_TOKEN}；用 auth microsoft 获取")
+      .description("${MS_GRAPH_REFRESH_TOKEN}；用 auth microsoft 获取").i18n({"en": {"description": "${MS_GRAPH_REFRESH_TOKEN}; obtain using the calendar authorization flow."}})
       .effect("reload"),
     tenant: Schema.string()
       .default("common")
-      .description("Azure tenant，默认 common")
+      .description("Azure tenant，默认 common").i18n({"en": {"description": "Azure tenant, common by default."}})
       .effect("reload"),
     calendar_id: Schema.string()
       .default("")
-      .description("留空或 primary/me = 默认日历；否则为 Graph calendar id")
+      .description("留空或 primary/me = 默认日历；否则为 Graph calendar id").i18n({"en": {"description": "Empty, primary or me selects the default calendar; otherwise a Graph calendar ID."}})
       .effect("reload"),
     token_file: Schema.string()
       .default("")

package/src/credential-store.ts

@@ -1,3 +1,4 @@
+import type { Locale } from 'zhin.js/i18n';
 /**
  * Persists OAuth refresh tokens in the plugin's database state (never in .env).
  */
@@ -13,6 +14,8 @@ export interface CalendarStateStore {
 /** Who completed the chat authorization and where to notify them later. */
 export interface CredentialOwner<Target = unknown> {
   readonly sender_id: string;
+  /** Fixed when authorization starts; token rotation preserves it. */
+  readonly locale?: Locale;
   readonly target: Target;
 }
 

package/src/errors.ts

@@ -0,0 +1,34 @@
+import { createMessages, type Locale } from 'zhin.js/i18n';
+
+const catalog = {
+  timezone: { 'zh-CN': '未知时区：{value}', en: 'Unknown timezone: {value}' },
+  datetime: { 'zh-CN': '无法解析时间：{value}', en: 'Could not parse datetime: {value}' },
+  datetimeFormat: { 'zh-CN': '无法解析时间：{value}（请用 YYYY-MM-DDTHH:mm 格式）', en: 'Could not parse datetime: {value} (use YYYY-MM-DDTHH:mm)' },
+  duration: { 'zh-CN': '无法解析时长：{value}（示例：10m、2h30m、1d）', en: 'Could not parse duration: {value} (examples: 10m, 2h30m, 1d)' },
+  workTime: { 'zh-CN': '工作时间格式无效：{value}（示例：09:00）', en: 'Invalid work time: {value} (example: 09:00)' },
+  positiveDuration: { 'zh-CN': '时长必须大于 0 分钟', en: 'Duration must be greater than 0 minutes' },
+  listHttp: { 'zh-CN': '{provider} 列表失败：HTTP {status} {detail}', en: '{provider} could not list events: HTTP {status} {detail}' },
+  createHttp: { 'zh-CN': '{provider} 创建失败：HTTP {status}', en: '{provider} could not create the event: HTTP {status}' },
+  caldavHttp: { 'zh-CN': 'CalDAV {method} 失败：HTTP {status}', en: 'CalDAV {method} failed: HTTP {status}' },
+  exchange: { 'zh-CN': '{provider}: 换取 token 失败：{detail}', en: '{provider}: token exchange failed: {detail}' },
+  refreshMissing: { 'zh-CN': '{provider}: 响应没有 refresh_token。Google 请确认 access_type=offline&prompt=consent；Microsoft 请确认已请求 offline_access。', en: '{provider}: the response has no refresh_token. For Google, check access_type=offline&prompt=consent; for Microsoft, request offline_access.' },
+  accessMissing: { 'zh-CN': '{provider}: 响应缺少 access_token', en: '{provider}: the response has no access_token' },
+  clientMissing: { 'zh-CN': '{provider}: 缺少 {field}', en: '{provider}: missing {field}' },
+  refreshHttp: { 'zh-CN': '{provider}: token 刷新失败 HTTP {status}：{detail}', en: '{provider}: token refresh failed, HTTP {status}: {detail}' },
+  refreshAccessMissing: { 'zh-CN': '{provider}: 刷新响应缺少 access_token', en: '{provider}: the refresh response has no access_token' },
+} as const;
+const messages = createMessages(catalog);
+
+/** Calendar-owned failures retain their code and raw parameters until presentation. */
+export class CalendarError extends Error {
+  readonly code: keyof typeof catalog;
+  readonly params: Readonly<Record<string, string | number>>;
+
+  constructor(code: keyof typeof catalog, params: Readonly<Record<string, string | number>> = {}, locale?: Locale) {
+    super(messages(locale, code, params));
+    this.name = 'CalendarError';
+    this.code = code;
+    this.params = params;
+  }
+  format(locale?: Locale): string { return messages(locale, this.code, this.params); }
+}

package/src/free-time.ts

@@ -1,3 +1,4 @@
+import { CalendarError } from './errors.js';
 /**
  * Finds free slots inside work hours between `from` and `to`, given busy events.
  */
@@ -21,7 +22,7 @@ export interface FreeTimeOptions {
 
 function parseHm(value: string): { hour: number; minute: number } {
   const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
-  if (!match) throw new Error(`工作时间格式无效：${value}（示例：09:00）`);
+  if (!match) throw new CalendarError('workTime', { value });
   return { hour: Number(match[1]), minute: Number(match[2]) };
 }
 
@@ -45,7 +46,7 @@ export function findFreeSlots(options: FreeTimeOptions): FreeSlot[] {
   const startHm = parseHm(options.workDayStart);
   const endHm = parseHm(options.workDayEnd);
   const durationMs = options.durationMinutes * 60000;
-  if (durationMs <= 0) throw new Error("时长必须大于 0 分钟");
+  if (durationMs <= 0) throw new CalendarError('positiveDuration');
 
   const busy = options.events
     .map((event) => ({

package/src/i18n.ts

@@ -0,0 +1,133 @@
+import { createMessages } from 'zhin.js/i18n';
+
+export const messages = createMessages({
+  untitled: { 'zh-CN': '(无标题)', en: '(Untitled)' },
+  "google": {
+    "zh-CN": "Google 日历",
+    "en": "Google Calendar"
+  },
+  "microsoft": {
+    "zh-CN": "Outlook 日历",
+    "en": "Outlook Calendar"
+  },
+  "providerInput": {
+    "zh-CN": "请选择 google 或 microsoft（outlook）",
+    "en": "Choose google or microsoft (outlook)."
+  },
+  "usage": {
+    "zh-CN": "用法：{command} google | {command} microsoft",
+    "en": "Usage: {command} google | {command} microsoft"
+  },
+  "chatRequired": {
+    "zh-CN": "请在私聊或群聊中发送该命令",
+    "en": "Send this command in a private or group conversation."
+  },
+  "needsDatabase": {
+    "zh-CN": "日历授权需要数据库（databaseHostToken）来保存 refresh_token，当前不可用。",
+    "en": "Calendar authorization needs a database (databaseHostToken) to store refresh_token; it is currently unavailable."
+  },
+  "needsHttp": {
+    "zh-CN": "未找到 HTTP 服务地址：请启用 zhin 的 HTTP Host，或在 plugins.calendar.oauth_redirect_base_url 配置外部可访问地址。",
+    "en": "No HTTP service address was found. Enable the Zhin HTTP Host or configure a publicly reachable oauth_redirect_base_url for this calendar instance."
+  },
+  "openLink": {
+    "zh-CN": "请在浏览器打开下面的链接完成{provider}授权（{minutes} 分钟内有效，只能使用一次）：",
+    "en": "Open the link below in your browser to authorize {provider}. It expires in {minutes} minutes and can be used once:"
+  },
+  "callback": {
+    "zh-CN": "回调地址：{url}",
+    "en": "Callback URL: {url}"
+  },
+  "callbackHelp": {
+    "zh-CN": "该地址必须能从打开链接的浏览器访问，并已登记在 OAuth 客户端的重定向 URI 中。",
+    "en": "This URL must be reachable from your browser and registered as a redirect URI in the OAuth client."
+  },
+  "invalidLink": {
+    "zh-CN": "授权链接无效、已使用或已过期，请回到聊天重新发起日历授权。",
+    "en": "This authorization link is invalid, already used or expired. Start calendar authorization again from chat."
+  },
+  "failed": {
+    "zh-CN": "{provider}授权失败：{detail}",
+    "en": "{provider} authorization failed: {detail}"
+  },
+  "callbackFailed": {
+    "zh-CN": "授权失败：{detail}",
+    "en": "Authorization failed: {detail}"
+  },
+  "codeMissing": {
+    "zh-CN": "缺少授权码或客户端配置，请重新授权。",
+    "en": "The authorization code or client configuration is missing. Start authorization again."
+  },
+  "otherProvider": {
+    "zh-CN": "\n注意：当前 plugins.calendar.provider 是 {current}，日历工具不会使用 {provider}。",
+    "en": "\nNote: the current calendar provider is {current}; calendar tools will not use {provider}."
+  },
+  "authorized": {
+    "zh-CN": "{provider}授权成功，refresh_token 已保存到插件数据库。{hint}",
+    "en": "{provider} authorization succeeded. The refresh token was saved in the plugin database.{hint}"
+  },
+  "callbackSuccess": {
+    "zh-CN": "授权成功，可以关闭此页回到聊天。",
+    "en": "Authorization succeeded. You can close this page and return to chat."
+  },
+  "currentProvider": {
+    "zh-CN": "当前 provider：{provider}",
+    "en": "Current provider: {provider}"
+  },
+  "noDatabase": {
+    "zh-CN": "数据库不可用，没有可删除的授权。",
+    "en": "The database is unavailable; there is no stored authorization to remove."
+  },
+  "loggedOut": {
+    "zh-CN": "已删除{provider}在插件数据库中的授权。若 .env 里仍有 refresh_token，重载配置后会继续作为后备使用。",
+    "en": "Removed the {provider} authorization from the plugin database. A refresh token still configured in .env remains a fallback after configuration reload."
+  },
+  "lost": {
+    "zh-CN": "{provider}：授权已失效，请通过日历授权入口重新授权。",
+    "en": "{provider}: authorization expired or was revoked. Use the calendar authorization entry to authorize again."
+  },
+  "notAuthorized": {
+    "zh-CN": "{provider}：尚未授权，请通过日历授权入口完成授权。",
+    "en": "{provider}: not authorized. Use the calendar authorization entry to authorize."
+  },
+  "commandHint": {
+    "zh-CN": "请发送「{command}」。",
+    "en": "Send \"{command}\"."
+  },
+  "clientMissing": {
+    "zh-CN": "{provider}：未配置 client_id",
+    "en": "{provider}: client_id is not configured"
+  },
+  "databaseStatus": {
+    "zh-CN": "{provider}：已授权（数据库，{at}）",
+    "en": "{provider}: authorized (database, {at})"
+  },
+  "envStatus": {
+    "zh-CN": "{provider}：使用配置/环境变量中的 refresh_token",
+    "en": "{provider}: using refresh_token from configuration or environment variables"
+  },
+  "googleClient": {
+    "zh-CN": "请先在 plugins.calendar.google 配置 client_id 和 client_secret（例如 GOOGLE_CALENDAR_CLIENT_ID / GOOGLE_CALENDAR_CLIENT_SECRET 环境变量）。",
+    "en": "Configure client_id and client_secret for the calendar Google client first, for example using the GOOGLE_CALENDAR_CLIENT_ID and GOOGLE_CALENDAR_CLIENT_SECRET environment variables."
+  },
+  "microsoftClient": {
+    "zh-CN": "请先在 plugins.calendar.microsoft 配置 client_id（例如 MS_GRAPH_CLIENT_ID 环境变量）。",
+    "en": "Configure client_id for the calendar Microsoft client first, for example using the MS_GRAPH_CLIENT_ID environment variable."
+  },
+  "disabled": {
+    "zh-CN": "日历未启用：请先配置 provider 与凭据",
+    "en": "Calendar is disabled. Configure a provider and credentials first."
+  },
+  "noEvents": {
+    "zh-CN": "（{provider}）{from} ~ {to} 没有事件",
+    "en": "({provider}) No events from {from} to {to}."
+  },
+  "noFreeTime": {
+    "zh-CN": "在工作时段（{start}-{end} {timezone}）没有足够的空闲",
+    "en": "No sufficiently long free slot during work hours ({start}–{end} {timezone})."
+  },
+  "eventCreated": {
+    "zh-CN": "已创建事件 [{id}]\n{title}\n{start} → {end}（{timezone}）",
+    "en": "Event created [{id}]\n{title}\n{start} → {end} ({timezone})"
+  }
+});

package/src/oauth-auth.ts

@@ -1,3 +1,4 @@
+import { CalendarError } from './errors.js';
 /**
  * OAuth authorization-code + PKCE helpers for the one-time auth CLI.
  */
@@ -126,17 +127,15 @@ export async function exchangeAuthorizationCode(
     const desc = String(
       data.error_description ?? data.error ?? response.statusText
     );
-    throw new Error(`${options.provider}: 换取 token 失败：${desc}`);
+    throw new CalendarError('exchange', { provider: options.provider, detail: desc });
   }
   const refreshToken = String(data.refresh_token ?? "");
   const accessToken = String(data.access_token ?? "");
   if (!refreshToken) {
-    throw new Error(
-      `${options.provider}: 响应没有 refresh_token。Google 请确认 access_type=offline&prompt=consent；Microsoft 请确认已请求 offline_access。`
-    );
+    throw new CalendarError('refreshMissing', { provider: options.provider });
   }
   if (!accessToken)
-    throw new Error(`${options.provider}: 响应缺少 access_token`);
+    throw new CalendarError('accessMissing', { provider: options.provider });
   return {
     accessToken,
     refreshToken,

package/src/oauth.ts

@@ -1,3 +1,4 @@
+import { CalendarError } from './errors.js';
 /**
  * Google Calendar and Microsoft Graph providers backed by OAuthTokenManager
  * (refresh_token flow; access tokens are never stored in config).
@@ -43,7 +44,7 @@ function mapGoogleEvent(
   const endDate = new Date(end.dateTime ?? end.date ?? "");
   return {
     id: String(item.id ?? ""),
-    title: String(item.summary ?? "(无标题)"),
+    title: String(item.summary ?? ""),
     start: formatInZone(startDate, timezone),
     end: formatInZone(endDate, timezone),
     location: item.location ? String(item.location) : undefined,
@@ -68,7 +69,7 @@ function mapMicrosoftEvent(
   );
   return {
     id: String(item.id ?? ""),
-    title: String(item.subject ?? "(无标题)"),
+    title: String(item.subject ?? ""),
     start: formatInZone(startDate, timezone),
     end: formatInZone(endDate, timezone),
     location: item.location
@@ -144,9 +145,7 @@ export function createGoogleCalendarProvider(
       });
       if (!response.ok) {
         const detail = (await response.text().catch(() => "")).slice(0, 300);
-        throw new Error(
-          `Google Calendar 列表失败：HTTP ${response.status} ${detail}`
-        );
+        throw new CalendarError('listHttp', { provider: 'Google Calendar', status: response.status, detail });
       }
       const data = (await response.json()) as {
         items?: Record<string, unknown>[];
@@ -180,7 +179,7 @@ export function createGoogleCalendarProvider(
         }
       );
       if (!response.ok)
-        throw new Error(`Google Calendar 创建失败：HTTP ${response.status}`);
+        throw new CalendarError('createHttp', { provider: 'Google Calendar', status: response.status });
       return mapGoogleEvent(
         (await response.json()) as Record<string, unknown>,
         options.timezone
@@ -246,9 +245,7 @@ export function createMicrosoftCalendarProvider(
       );
       if (!response.ok) {
         const detail = (await response.text().catch(() => "")).slice(0, 300);
-        throw new Error(
-          `Microsoft Graph 列表失败：HTTP ${response.status} ${detail}`
-        );
+        throw new CalendarError('listHttp', { provider: 'Microsoft Graph', status: response.status, detail });
       }
       const data = (await response.json()) as {
         value?: Record<string, unknown>[];
@@ -288,7 +285,7 @@ export function createMicrosoftCalendarProvider(
         { prefer: `outlook.timezone="${options.timezone}"` }
       );
       if (!response.ok)
-        throw new Error(`Microsoft Graph 创建失败：HTTP ${response.status}`);
+        throw new CalendarError('createHttp', { provider: 'Microsoft Graph', status: response.status });
       return mapMicrosoftEvent(
         (await response.json()) as Record<string, unknown>,
         options.timezone

package/src/time.ts

@@ -1,3 +1,4 @@
+import { CalendarError } from './errors.js';
 /**
  * Timezone helpers built on Intl (no dependencies).
  */
@@ -48,7 +49,7 @@ export function assertTimeZone(timeZone: string): void {
   try {
     formatterFor(timeZone);
   } catch {
-    throw new Error(`未知时区：${timeZone}`);
+    throw new CalendarError('timezone', { value: timeZone });
   }
 }
 
@@ -124,13 +125,13 @@ export function parseDateTimeInZone(value: string, timeZone: string): Date {
   const text = value.trim();
   if (/([zZ]|[+-]\d{2}:?\d{2})$/.test(text)) {
     const date = new Date(text);
-    if (Number.isNaN(date.getTime())) throw new Error(`无法解析时间：${value}`);
+    if (Number.isNaN(date.getTime())) throw new CalendarError('datetime', { value });
     return date;
   }
   const match =
     /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/.exec(text);
   if (!match)
-    throw new Error(`无法解析时间：${value}（请用 YYYY-MM-DDTHH:mm 格式）`);
+    throw new CalendarError('datetimeFormat', { value });
   return zonedTimeToUtc(
     {
       year: Number(match[1]),
@@ -161,7 +162,7 @@ export function parseDuration(value: string): number {
     consumed += match[0];
   }
   if (total <= 0 || consumed.replace(/\s/g, "") !== text.replace(/\s/g, "")) {
-    throw new Error(`无法解析时长：${value}（示例：10m、2h30m、1d）`);
+    throw new CalendarError('duration', { value });
   }
   return total;
 }