@zhin.js/plugin-calendar 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# @zhin.js/plugin-calendar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+为 Zhin Agent 提供日历查询与创建：CalDAV（iCloud / Fastmail / Nextcloud），以及 **Google Calendar / Microsoft Outlook（Graph）**。
+
+Google / Outlook 的授权在**聊天里完成**：master 发送 `calendar auth google`，点开机器人回复的链接登录，refresh_token 会保存到插件数据库，不需要手动改 `.env`。授权失效时，日历工具会提示重新授权，并主动通知上次完成授权的会话（只通知一次）。
+
+## 安装
+
+```bash
+pnpm add @zhin.js/plugin-calendar
+```
+
+根 `package.json#zhin`：
+
+```json
+{
+  "features": [
+    { "package": "@zhin.js/command" },
+    { "package": "@zhin.js/tool" },
+    { "package": "@zhin.js/skill" }
+  ],
+  "plugins": [
+    { "package": "@zhin.js/plugin-calendar", "instanceKey": "calendar" }
+  ]
+}
+```
+
+聊天授权依赖 zhin 的数据库（保存 refresh_token）、HTTP Host（接收 OAuth 回调）和消息出站（通知授权结果）。缺少数据库或 HTTP Host 时，`calendar auth` 会直接说明原因；CalDAV 不受影响。
+
+## 使用流程（Google / Outlook）
+
+1. 在 Google Cloud 或 Azure 创建 OAuth 客户端（见下文），把 Client ID / Secret 写进运行项目的 `.env`。
+2. 在 `zhin.config.yml` 配置 `plugins.calendar`（见下文），重启或重载。
+3. master 在聊天中发送 `calendar auth google`（或 `calendar auth microsoft`）。
+4. 打开机器人回复的链接，登录并同意授权。链接 10 分钟内有效，只能用一次。
+5. 浏览器显示「授权成功」，机器人在原会话回复授权成功。完成。
+
+## 聊天命令（仅 master）
+
+| 命令                                  | 说明                                                      |
+| ------------------------------------- | --------------------------------------------------------- |
+| `calendar auth google`                | 生成 Google 授权链接（PKCE + state，10 分钟有效、一次性） |
+| `calendar auth microsoft` / `outlook` | 生成 Outlook（Microsoft Graph）授权链接                   |
+| `calendar status`                     | 查看当前 provider 与各平台授权状态（不会显示 token）      |
+| `calendar logout google\|microsoft`   | 删除数据库中保存的授权                                    |
+
+refresh_token 的读取顺序：**插件数据库（聊天授权写入）优先**，没有时才用配置里的 `refresh_token`（兼容旧的 `.env` 方式）。
+
+## 配置（`zhin.config.yml`）
+
+```yaml
+plugins:
+  calendar:
+    provider: google # none | caldav | google | microsoft
+    timezone: Asia/Manila
+    work_day_start: "09:00"
+    work_day_end: "18:00"
+    # OAuth 回调：默认使用 zhin HTTP Host 的本机地址，例如 http://127.0.0.1:8068/calendar/oauth/callback
+    oauth_redirect_base_url: "" # 浏览器和机器人不在同一台机器时，填外部可访问地址，如 https://bot.example.com
+    oauth_callback_path: /calendar/oauth/callback
+    google:
+      enabled: true
+      client_id: ${GOOGLE_CALENDAR_CLIENT_ID}
+      client_secret: ${GOOGLE_CALENDAR_CLIENT_SECRET}
+      refresh_token: "" # 可选后备；聊天授权后可以留空
+      calendar_id: primary
+      token_file: ""
+    microsoft:
+      enabled: false
+      client_id: ${MS_GRAPH_CLIENT_ID}
+      client_secret: ${MS_GRAPH_CLIENT_SECRET} # 公共客户端可留空
+      refresh_token: ""
+      tenant: common
+      calendar_id: "" # 空 / primary / me = 默认日历；否则 Graph calendar id
+      token_file: ""
+    caldav:
+      enabled: false
+      calendar_url: ${CALDAV_CALENDAR_URL}
+      username: ${CALDAV_USERNAME}
+      password: ${CALDAV_PASSWORD}
+```
+
+运行项目的 `.env`（放在启动 zhin 的项目根目录，不是插件目录）：
+
+```bash
+GOOGLE_CALENDAR_CLIENT_ID=xxxx.apps.googleusercontent.com
+GOOGLE_CALENDAR_CLIENT_SECRET=xxxx
+# Outlook
+MS_GRAPH_CLIENT_ID=xxxx
+MS_GRAPH_CLIENT_SECRET= # 可选
+```
+
+### 回调地址与反向代理 / 隧道
+
+回调地址 = `oauth_redirect_base_url`（为空时用 HTTP Host 本机地址）+ `oauth_callback_path`。这个地址必须同时满足：
+
+- 打开授权链接的浏览器能访问到它；
+- 已登记在 OAuth 客户端的「重定向 URI」里（必须**完全一致**）。
+
+如果反向代理或 Cloudflare Tunnel 只转发部分路径（例如只放行 `/grokbot/*`），要么在隧道里额外放行 `/calendar/oauth/callback`，要么把 `oauth_callback_path` 改到已放行的前缀下，例如：
+
+```yaml
+oauth_redirect_base_url: https://bot.example.com
+oauth_callback_path: /grokbot/calendar/oauth/callback
+```
+
+注意：Google「桌面应用」客户端只接受 `127.0.0.1` / `localhost` 回调。如果用公网域名回调，需要创建「Web 应用」类型的客户端，并把完整回调地址加入「已获授权的重定向 URI」。
+
+## Google Cloud 设置
+
+1. 打开 [Google Cloud Console](https://console.cloud.google.com/)，创建或选择一个项目。
+2. **API 和服务 → 库**，搜索并**启用 Google Calendar API**。  
+   漏掉这一步，授权会成功，但读日历时报 `403 accessNotConfigured`（Google Calendar API has not been used in project … or it is disabled）。
+3. **OAuth 同意屏幕**：用户类型选 External（Workspace 内部用可选 Internal）。  
+   应用处于 **Testing（测试）** 状态时，必须在「测试用户」里**添加要授权的 Google 账号**，否则浏览器会显示「尚未完成 Google 验证流程」和 `403 access_denied`。  
+   Testing 状态下 refresh_token 约 **7 天**过期，到期后再发一次 `calendar auth google` 即可；发布为 Production 后长期有效（仍受 Google 策略约束）。
+4. **凭据 → 创建凭据 → OAuth 客户端 ID**：
+   - 机器人和浏览器在同一台电脑：选「**桌面应用**」，回调用默认的 `http://127.0.0.1:<HTTP 端口>/calendar/oauth/callback`。
+   - 通过公网域名回调：选「**Web 应用**」，在「已获授权的重定向 URI」加入完整回调地址。
+5. 把 Client ID / Client Secret 写进 `.env` 的 `GOOGLE_CALENDAR_CLIENT_ID` / `GOOGLE_CALENDAR_CLIENT_SECRET`，重载后发送 `calendar auth google`。
+
+申请的 scope：`calendar.events` + `calendar.readonly`（`access_type=offline&prompt=consent`）。
+
+## Azure 应用注册（Outlook / Microsoft 365）
+
+1. [Azure Portal](https://portal.azure.com/) → **Microsoft Entra ID → 应用注册 → 新注册**。
+2. 支持的账户类型：个人 Outlook.com 账号选「任何组织目录中的帐户和个人 Microsoft 帐户」；仅公司账号可选单租户（此时 `tenant` 填租户 ID）。
+3. **身份验证 → 添加平台**：
+   - 本机回调：选「移动和桌面应用程序」，添加 `http://127.0.0.1:<HTTP 端口>/calendar/oauth/callback`（或 `http://localhost`，以门户允许为准），并打开「允许公共客户端流」，这样不需要 secret。
+   - 公网回调：选「Web」，添加完整回调地址，并在「证书和密码」创建客户端密码，填到 `MS_GRAPH_CLIENT_SECRET`。
+4. **API 权限 → Microsoft Graph → 委派的权限**：添加 `Calendars.ReadWrite`、`User.Read`、`offline_access`，组织账号按需「授予管理员同意」。
+5. **概述**里复制「应用程序(客户端) ID」到 `MS_GRAPH_CLIENT_ID`。
+6. `provider: microsoft`、`microsoft.enabled: true`，重载后发送 `calendar auth microsoft`。
+
+授权请求的 scope：`offline_access Calendars.ReadWrite User.Read`。
+
+## CalDAV
+
+```yaml
+plugins:
+  calendar:
+    provider: caldav
+    caldav:
+      enabled: true
+      calendar_url: ${CALDAV_CALENDAR_URL} # 日历 collection URL
+      username: ${CALDAV_USERNAME}
+      password: ${CALDAV_PASSWORD} # iCloud 请使用 App 专用密码
+```
+
+CalDAV 不需要聊天授权。
+
+## 故障排查
+
+| 现象                                                      | 原因与处理                                                                                                           |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| 读日历报 `403 accessNotConfigured` / API 未启用           | 该 Google Cloud 项目没有启用 Google Calendar API。到「API 和服务 → 库」启用，几分钟后重试。                          |
+| 浏览器显示「尚未完成 Google 验证流程」`403 access_denied` | 同意屏幕处于 Testing，账号不在测试用户里。添加测试用户后重新 `calendar auth google`。                                |
+| `redirect_uri_mismatch`                                   | 回调地址与客户端登记的不一致。核对 `calendar auth` 回复里的「回调地址」，原样登记到客户端。                          |
+| 点击链接后浏览器打不开回调页                              | 浏览器访问不到 zhin HTTP Host。配置 `oauth_redirect_base_url`，或让隧道放行 `oauth_callback_path`。                  |
+| 「授权链接无效、已使用或已过期」                          | 链接超过 10 分钟、已用过，或 zhin 重启过。重新发送 `calendar auth <provider>`。                                      |
+| 工具提示「日历授权已失效…（invalid_grant）」              | refresh_token 过期或被撤销（Google Testing 约 7 天、用户改密码、取消授权）。master 发送 `calendar auth <provider>`。 |
+| 工具提示「日历尚未授权」                                  | 数据库和配置里都没有 refresh_token。发送 `calendar auth <provider>`。                                                |
+| 日志提示「提供方返回了新的 refresh_token」                | Microsoft 会轮换 refresh_token。聊天授权时新值自动写回数据库；只用 `.env` 时请按日志更新，或配置 `token_file`。      |
+
+## 可选：命令行授权（后备方式）
+
+不方便走聊天回调时（例如没有 HTTP Host），可以用随包附带的命令行工具获取 refresh_token，再写入 `.env` 的 `GOOGLE_CALENDAR_REFRESH_TOKEN` / `MS_GRAPH_REFRESH_TOKEN`：
+
+```bash
+export GOOGLE_CALENDAR_CLIENT_ID=...
+export GOOGLE_CALENDAR_CLIENT_SECRET=...
+npx zhin-calendar-auth google
+
+export MS_GRAPH_CLIENT_ID=...
+npx zhin-calendar-auth microsoft
+```
+
+它在本机监听 `http://127.0.0.1:53682/callback`（`CALENDAR_OAUTH_PORT` 可改端口），需要把这个地址登记为客户端的重定向 URI。工具只读取已 export 的环境变量，只打印 refresh_token，不写任何文件。在 zhin 仓库内也可以用 `pnpm --filter @zhin.js/plugin-calendar auth google`。
+
+## Agent 技能
+
+技能 `calendar-scheduling`：
+
+| 工具             | 说明                                  |
+| ---------------- | ------------------------------------- |
+| `list_events`    | 列出时间范围内事件                    |
+| `find_free_time` | 工作时段内找空档                      |
+| `create_event`   | 创建事件（`role(master)` + 始终批准） |
+
+创建前应向用户确认标题、时间与时区。

package/commands/calendar/auth/index.js

@@ -0,0 +1,26 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from "zhin.js/command";
+import { createDeliveryTarget } from "zhin.js";
+import { parseOAuthProvider } from "../../../lib/chat-auth.js";
+import { calendarRuntimeToken } from "../../../lib/runtime.js";
+export default defineCommand({
+    description: "通过聊天完成 Google / Outlook 日历 OAuth 授权（master 专用）",
+    params: {
+        provider: { type: "string", description: "google 或 microsoft（outlook）" },
+    },
+    permit: ["role(master)"],
+    async execute({ input, params, use }) {
+        const provider = parseOAuthProvider(params.provider);
+        if (!provider) {
+            return "用法：calendar auth google | calendar auth microsoft";
+        }
+        if (!input?.sender?.id) {
+            return "请在私聊或群聊中发送该命令";
+        }
+        const requester = {
+            sender_id: input.sender.id,
+            target: createDeliveryTarget(input),
+        };
+        return use(calendarRuntimeToken).auth.startAuthorization(provider, requester);
+    },
+});

package/commands/calendar/auth/index.ts

@@ -0,0 +1,29 @@
+import { defineCommand } from "zhin.js/command";
+import { createDeliveryTarget } from "zhin.js";
+import { parseOAuthProvider } from "../../../src/chat-auth.js";
+import { calendarRuntimeToken } from "../../../src/runtime.js";
+
+export default defineCommand({
+  description: "通过聊天完成 Google / Outlook 日历 OAuth 授权（master 专用）",
+  params: {
+    provider: { type: "string", description: "google 或 microsoft（outlook）" },
+  },
+  permit: ["role(master)"],
+  async execute({ input, params, use }) {
+    const provider = parseOAuthProvider(params.provider);
+    if (!provider) {
+      return "用法：calendar auth google | calendar auth microsoft";
+    }
+    if (!input?.sender?.id) {
+      return "请在私聊或群聊中发送该命令";
+    }
+    const requester = {
+      sender_id: input.sender.id,
+      target: createDeliveryTarget(input),
+    };
+    return use(calendarRuntimeToken).auth.startAuthorization(
+      provider,
+      requester
+    );
+  },
+});

package/commands/calendar/logout/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from "zhin.js/command";
+import { parseOAuthProvider } from "../../../lib/chat-auth.js";
+import { calendarRuntimeToken } from "../../../lib/runtime.js";
+export default defineCommand({
+    description: "删除数据库中保存的日历授权（master 专用）",
+    params: {
+        provider: { type: "string", description: "google 或 microsoft（outlook）" },
+    },
+    permit: ["role(master)"],
+    async execute({ params, use }) {
+        const provider = parseOAuthProvider(params.provider);
+        if (!provider) {
+            return "用法：calendar logout google | calendar logout microsoft";
+        }
+        return use(calendarRuntimeToken).auth.logout(provider);
+    },
+});

package/commands/calendar/logout/index.ts

@@ -0,0 +1,18 @@
+import { defineCommand } from "zhin.js/command";
+import { parseOAuthProvider } from "../../../src/chat-auth.js";
+import { calendarRuntimeToken } from "../../../src/runtime.js";
+
+export default defineCommand({
+  description: "删除数据库中保存的日历授权（master 专用）",
+  params: {
+    provider: { type: "string", description: "google 或 microsoft（outlook）" },
+  },
+  permit: ["role(master)"],
+  async execute({ params, use }) {
+    const provider = parseOAuthProvider(params.provider);
+    if (!provider) {
+      return "用法：calendar logout google | calendar logout microsoft";
+    }
+    return use(calendarRuntimeToken).auth.logout(provider);
+  },
+});

package/commands/calendar/status/index.js

@@ -0,0 +1,10 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from "zhin.js/command";
+import { calendarRuntimeToken } from "../../../lib/runtime.js";
+export default defineCommand({
+    description: "查看日历授权状态（master 专用）",
+    permit: ["role(master)"],
+    async execute({ use }) {
+        return use(calendarRuntimeToken).auth.describeStatus();
+    },
+});

package/commands/calendar/status/index.ts

@@ -0,0 +1,10 @@
+import { defineCommand } from "zhin.js/command";
+import { calendarRuntimeToken } from "../../../src/runtime.js";
+
+export default defineCommand({
+  description: "查看日历授权状态（master 专用）",
+  permit: ["role(master)"],
+  async execute({ use }) {
+    return use(calendarRuntimeToken).auth.describeStatus();
+  },
+});

package/lib/caldav.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal CalDAV client (RFC 4791) for listing and creating VEVENTs.
+ * Works with iCloud, Fastmail and Nextcloud calendars.
+ */
+import type { CalendarEvent, CalendarProvider } from "./types.js";
+export interface CalDavOptions {
+    readonly calendarUrl: string;
+    readonly username: string;
+    readonly password: string;
+    readonly timezone: string;
+    readonly fetchImpl?: typeof fetch;
+}
+declare function escapeXml(value: string): string;
+/** Parses VEVENT components from a CalDAV multistatus response. */
+export declare function parseCalDavEvents(xml: string, timezone: string): CalendarEvent[];
+export declare function createCalDavProvider(options: CalDavOptions): CalendarProvider;
+export { escapeXml };
+//# sourceMappingURL=caldav.d.ts.map

package/lib/caldav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caldav.d.ts","sourceRoot":"","sources":["../src/caldav.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAMD,iBAAS,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxC;AAuCD,mEAAmE;AACnE,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,aAAa,EAAE,CA2BjB;AAgCD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,gBAAgB,CAgE7E;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/lib/caldav.js

@@ -0,0 +1,167 @@
+import { formatInZone } from "./time.js";
+function basicAuth(username, password) {
+    return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function toUtcStamp(date) {
+    return date
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d{3}/, "");
+}
+function parseIcsDate(value) {
+    const match = /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2})(Z)?)?/.exec(value.trim());
+    if (!match)
+        return new Date(NaN);
+    if (!match[4]) {
+        return new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+    }
+    const utc = match[7] === "Z";
+    const parts = [
+        Number(match[1]),
+        Number(match[2]) - 1,
+        Number(match[3]),
+        Number(match[4]),
+        Number(match[5]),
+        Number(match[6] ?? 0),
+    ];
+    return utc ? new Date(Date.UTC(...parts)) : new Date(...parts);
+}
+function extractField(block, name) {
+    const pattern = new RegExp(`^${name}(?:;[^:]*)?:(.*)$`, "im");
+    const match = pattern.exec(block);
+    return match
+        ? match[1].trim().replace(/\\n/g, "\n").replace(/\\,/g, ",")
+        : undefined;
+}
+/** Parses VEVENT components from a CalDAV multistatus response. */
+export function parseCalDavEvents(xml, timezone) {
+    const events = [];
+    const hrefs = [
+        ...xml.matchAll(/<[^:>]*:?href[^>]*>([^<]+)<\/[^:>]*:?href>/gi),
+    ].map((m) => m[1].trim());
+    const calendars = [...xml.matchAll(/BEGIN:VEVENT([\s\S]*?)END:VEVENT/g)];
+    calendars.forEach((match, index) => {
+        const block = match[1];
+        const uid = extractField(block, "UID") ?? hrefs[index] ?? `event-${index}`;
+        const summary = extractField(block, "SUMMARY") ?? "(无标题)";
+        const startRaw = extractField(block, "DTSTART");
+        const endRaw = extractField(block, "DTEND") ?? startRaw;
+        if (!startRaw || !endRaw)
+            return;
+        const start = parseIcsDate(startRaw);
+        const end = parseIcsDate(endRaw);
+        const allDay = !/T/.test(startRaw);
+        events.push({
+            id: uid,
+            title: summary,
+            start: formatInZone(start, timezone),
+            end: formatInZone(end, timezone),
+            location: extractField(block, "LOCATION"),
+            description: extractField(block, "DESCRIPTION"),
+            all_day: allDay,
+        });
+    });
+    return events;
+}
+function buildVevent(input, uid) {
+    const lines = [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        "PRODID:-//zhin.js-assistant-toolkit//EN",
+        "BEGIN:VEVENT",
+        `UID:${uid}`,
+        `DTSTAMP:${toUtcStamp(new Date())}`,
+        input.all_day
+            ? `DTSTART;VALUE=DATE:${input.start
+                .toISOString()
+                .slice(0, 10)
+                .replace(/-/g, "")}`
+            : `DTSTART:${toUtcStamp(input.start)}`,
+        input.all_day
+            ? `DTEND;VALUE=DATE:${input.end
+                .toISOString()
+                .slice(0, 10)
+                .replace(/-/g, "")}`
+            : `DTEND:${toUtcStamp(input.end)}`,
+        `SUMMARY:${input.title.replace(/\n/g, " ")}`,
+    ];
+    if (input.location)
+        lines.push(`LOCATION:${input.location.replace(/\n/g, " ")}`);
+    if (input.description)
+        lines.push(`DESCRIPTION:${input.description.replace(/\n/g, "\\n")}`);
+    lines.push("END:VEVENT", "END:VCALENDAR");
+    return lines.join("\r\n");
+}
+export function createCalDavProvider(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const auth = basicAuth(options.username, options.password);
+    const base = options.calendarUrl.endsWith("/")
+        ? options.calendarUrl
+        : `${options.calendarUrl}/`;
+    return {
+        name: "caldav",
+        async listEvents(from, to, signal) {
+            const body = `<?xml version="1.0" encoding="utf-8" ?>
+<C:calendar-query xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
+  <D:prop><D:getetag/><C:calendar-data/></D:prop>
+  <C:filter>
+    <C:comp-filter name="VCALENDAR">
+      <C:comp-filter name="VEVENT">
+        <C:time-range start="${toUtcStamp(from)}" end="${toUtcStamp(to)}"/>
+      </C:comp-filter>
+    </C:comp-filter>
+  </C:filter>
+</C:calendar-query>`;
+            const response = await fetchImpl(base, {
+                method: "REPORT",
+                headers: {
+                    authorization: auth,
+                    depth: "1",
+                    "content-type": "application/xml; charset=utf-8",
+                },
+                body,
+                signal,
+            });
+            if (!response.ok)
+                throw new Error(`CalDAV REPORT 失败：HTTP ${response.status}`);
+            return parseCalDavEvents(await response.text(), options.timezone);
+        },
+        async createEvent(input, signal) {
+            const uid = `${Date.now()}-${Math.random()
+                .toString(36)
+                .slice(2, 10)}@zhin`;
+            const url = new URL(`${uid}.ics`, base).toString();
+            const response = await fetchImpl(url, {
+                method: "PUT",
+                headers: {
+                    authorization: auth,
+                    "content-type": "text/calendar; charset=utf-8",
+                    "if-none-match": "*",
+                },
+                body: buildVevent(input, uid),
+                signal,
+            });
+            if (response.status !== 201 && response.status !== 204) {
+                throw new Error(`CalDAV PUT 失败：HTTP ${response.status}`);
+            }
+            return {
+                id: uid,
+                title: input.title,
+                start: formatInZone(input.start, options.timezone),
+                end: formatInZone(input.end, options.timezone),
+                location: input.location,
+                description: input.description,
+                all_day: input.all_day,
+            };
+        },
+    };
+}
+export { escapeXml };
+//# sourceMappingURL=caldav.js.map

package/lib/caldav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caldav.js","sourceRoot":"","sources":["../src/caldav.ts"],"names":[],"mappings":"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"}

package/lib/chat-auth.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Chat-driven OAuth authorization: `calendar auth <provider>` creates a PKCE
+ * link, the HTTP callback exchanges the code, stores the refresh token in the
+ * plugin database and notifies the conversation that requested it.
+ */
+import type { CalendarConfig } from "./config.js";
+import type { CalendarCredentialStore, CredentialOwner } from "./credential-store.js";
+import { type OAuthProviderKind, type OAuthTokenManager } from "./token-manager.js";
+export declare const DEFAULT_OAUTH_CALLBACK_PATH = "/calendar/oauth/callback";
+export declare const OAUTH_PROVIDERS: readonly OAuthProviderKind[];
+export type CalendarNotifier<Target> = (target: Target, text: string) => Promise<void>;
+export interface CalendarAuthServiceOptions<Target> {
+    readonly config: CalendarConfig;
+    readonly managers: Partial<Record<OAuthProviderKind, OAuthTokenManager>>;
+    readonly credentials: CalendarCredentialStore | undefined;
+    readonly notify: CalendarNotifier<Target> | undefined;
+    /** Returns the full callback URL, or undefined when no HTTP host is available. */
+    readonly resolveRedirectUri: () => string | undefined;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => number;
+}
+export interface CallbackResult {
+    readonly statusCode: number;
+    readonly message: string;
+}
+export declare function parseOAuthProvider(value: unknown): OAuthProviderKind | undefined;
+/** Joins a base URL and the callback path, tolerating extra/missing slashes. */
+export declare function buildRedirectUri(baseUrl: string, callbackPath: string): string;
+/** Turns a listening address into a browser-reachable local origin. */
+export declare function localOriginFromAddress(address: {
+    readonly protocol: string;
+    readonly host: string;
+    readonly port: number;
+}): string;
+export declare class CalendarAuthService<Target> {
+    #private;
+    constructor(options: CalendarAuthServiceOptions<Target>);
+    /** Handles `calendar auth <provider>` and returns the chat reply. */
+    startAuthorization(provider: OAuthProviderKind, requester: CredentialOwner<Target>): Promise<string>;
+    /** Handles the OAuth redirect back to the HTTP host. */
+    handleCallback(searchParams: URLSearchParams): Promise<CallbackResult>;
+    /** Handles `calendar status`. */
+    describeStatus(): Promise<string>;
+    /** Handles `calendar logout <provider>`: removes the stored token. */
+    logout(provider: OAuthProviderKind): Promise<string>;
+    /** Called by the token manager once when the refresh token is rejected. */
+    notifyAuthorizationLost(provider: OAuthProviderKind, message: string): Promise<void>;
+}
+//# sourceMappingURL=chat-auth.d.ts.map

package/lib/chat-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-auth.d.ts","sourceRoot":"","sources":["../src/chat-auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE,eAAO,MAAM,eAAe,EAAE,SAAS,iBAAiB,EAGvD,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,MAAM,IAAI,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,WAAW,0BAA0B,CAAC,MAAM;IAChD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACzE,QAAQ,CAAC,WAAW,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAaD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,GACb,iBAAiB,GAAG,SAAS,CAW/B;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,MAAM,CAIR;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAMT;AAED,qBAAa,mBAAmB,CAAC,MAAM;;gBASzB,OAAO,EAAE,0BAA0B,CAAC,MAAM,CAAC;IAUvD,qEAAqE;IAC/D,kBAAkB,CACtB,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,eAAe,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC;IA0ClB,wDAAwD;IAClD,cAAc,CAAC,YAAY,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAwE5E,iCAAiC;IAC3B,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAQvC,sEAAsE;IAChE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAU1D,2EAA2E;IACrE,uBAAuB,CAC3B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;CAwEjB"}