dsh-calendar 0.1.0 → 0.2.0

package/README.en.md

@@ -0,0 +1,119 @@
+# dsh-calendar
+
+DSH community plugin: read/write calendar events via CalDAV. Provides 5 model-facing tools (calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search), supporting Google / iCloud / Nextcloud and any CalDAV server. This round is a node half-body with no settings-page UI; all configuration goes through the profile's cordis.patch.yml.
+
+## Installation
+
+```bash
+dsh plugin --profile web add dsh-calendar
+```
+
+After installing, restart dsh. The plugin inserts a `calendar` config line into the profile (see this package's cordis.patch.yml). The default provider is custom with no credentials filled in; the plugin still loads, but tools throw a Chinese guidance error when called, prompting you to complete the configuration.
+
+## Configuration
+
+All configuration lives in your profile's cordis.patch.yml; override the `calendar` line by id (overriding replaces that line's config wholesale). Common fields:
+
+- `provider`: google | icloud | nextcloud | custom
+- `caldavUrl`: full calendar collection URL (required for custom / icloud; google / nextcloud can also override the preset manually)
+- `username`: CalDAV account (account email for Google / iCloud)
+- `password`: password; for Google / iCloud use an app-specific password. Recommended to use the `DSH_CALENDAR_PASSWORD` env var to avoid storing it in plaintext.
+- `calendarId`: google-specific, the calendar ID (usually your email)
+- `host` / `user` / `calendar`: nextcloud-specific
+
+### Google example
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: google
+    username: you@gmail.com
+    calendarId: you@gmail.com
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+Google's CalDAV collection URL is assembled by the plugin: `https://apidata.googleusercontent.com/caldav/v2/<calendarId>/events`.
+
+### iCloud example
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: icloud
+    username: you@icloud.com
+    caldavUrl: https://caldav.icloud.com/123456789/calendars/<日历ID>/
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+iCloud needs the full calendar collection URL (with your user ID and calendar ID); you can find the specific calendar address in the calendar CalDAV settings on icloud.com.
+
+### Nextcloud example
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: nextcloud
+    username: alice
+    host: https://cloud.example.com
+    user: alice
+    calendar: personal
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+The plugin assembles: `https://cloud.example.com/remote.php/dav/calendars/alice/personal/`.
+
+### Custom CalDAV example
+
+```yaml
+- id: calendar
+  name: dsh-calendar
+  config:
+    provider: custom
+    caldavUrl: https://dav.example.com/calendars/me/work/
+    username: me
+    # password 推荐用环境变量 DSH_CALENDAR_PASSWORD
+```
+
+## App-specific password guidance
+
+Google: sign in to myaccount.google.com → Security → 2-Step Verification (must be enabled first) → App passwords, choose "Other" to generate a 16-character password, and fill it into `password` or `DSH_CALENDAR_PASSWORD`. You cannot use your Google login password.
+
+iCloud: sign in to appleid.apple.com → Sign-In and Security → App-Specific Passwords, generate one and fill it into `password` or `DSH_CALENDAR_PASSWORD`. You cannot use your Apple ID password.
+
+If a call returns 401/403, it's usually the wrong password (login password used instead of an app-specific password); the plugin returns a Chinese hint.
+
+## Tool reference
+
+- `calendar_list`: list events in a time range (start/end, ISO 8601; defaults to the next 7 days). Recurring events are expanded by default (`expand` defaults to true, `maxOccurrences` defaults to 30, clamped to 1-200): each occurrence is a separate row with `isOccurrence: true` and `seriesStart`; non-recurring events keep `isOccurrence: false`. With `expand=false`, recurring events are returned as a single original entry with `rrule`
+- `calendar_create`: create an event (summary/start/end required; description/location/allDay optional)
+- `calendar_update`: edit an event by uid (summary/start/end/description/location/allDay optional; omitted fields keep their original values)
+- `calendar_delete`: delete an event by uid
+- `calendar_search`: search events by keyword (client-side filter over title/description/location/UID, case-insensitive)
+
+The stable event identifier `uid` is the CalDAV href (full object URL); `calendar_update` / `calendar_delete` use it.
+
+## Time and timezone
+
+Input and output are uniformly ISO 8601. Timed events are output in UTC (e.g. `2025-01-15T01:00:00Z`); all-day events output `YYYY-MM-DD`. Input may carry a timezone offset (e.g. `2025-01-15T09:00:00+08:00`); the plugin converts to UTC internally for storage.
+
+## Known limitations
+
+- Recurring event expansion: calendar_list expands RRULE by default via ICAL.RecurExpansion (`expand=true`), capped by `maxOccurrences`; calendar_search still returns the original series (not expanded).
+- No single-instance edit/delete: calendar_update / calendar_delete operate on the whole recurring series (by uid); you cannot modify or delete just one occurrence (no RECURRENCE-ID instance-level operations).
+- No OAuth: Basic auth only (app-specific password); Google / iCloud OAuth login flows are not supported.
+- Timezone rules: events with TZID (named timezone) are output converted to UTC (Z); all-day boundaries, DST, and other complex timezone rules are not handled finely.
+- No settings-page UI: this round is a node half-body; config only via cordis.patch.yml, no Web settings page.
+- Calendar discovery: iCloud requires manually filling the full calendar collection URL; no principal auto-discovery or multi-calendar selection.
+- Cancellation/timeout: tools rely on `timeoutMs` (60 seconds) for overall timeout; AbortSignal is not propagated to individual network requests.
+
+## Development
+
+```bash
+pnpm install
+pnpm test   # 构建 + node --test
+```
+
+Build output in `lib/`; tests in `test/*.test.mjs` (no real account needed).

package/README.md

@@ -1,3 +1,5 @@
+[English](README.en.md)
+
 # dsh-calendar
 
 DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个面向模型的工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search），支持 Google / iCloud / Nextcloud 及任意 CalDAV 服务器。本轮为 node 半身，不含设置页 UI，配置全部走 profile 的 cordis.patch.yml。
@@ -87,7 +89,7 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 ## 工具清单
 
-- `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）
+- `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）。默认展开重复事件（`expand` 默认 true，`maxOccurrences` 默认 30、clamp 1-200）：每个实例独立成行，带 `isOccurrence: true` 与 `seriesStart`；非重复事件保持 `isOccurrence: false`。`expand=false` 时重复事件按原始单条返回并带 `rrule`
 - `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay 可选）
 - `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay 可选，未提供保留原值）
 - `calendar_delete`：按 uid 删事件
@@ -101,7 +103,8 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 ## 已知限制
 
-- 重复事件（RRULE）不展开：calendar_list / calendar_search 返回的是原始事件时间与 `rrule` 字段，重复实例需要模型自行按 rrule 计算。
+- 重复事件展开：calendar_list 默认用 ICAL.RecurExpansion 展开 RRULE（`expand=true`），受 `maxOccurrences` 封顶；calendar_search 仍返回原始系列（不展开）。
+- 不支持单次实例的改/删：calendar_update / calendar_delete 针对整个重复系列（按 uid 操作），无法只修改或删除某一次发生（不支持 RECURRENCE-ID 实例级操作）。
 - 不做 OAuth：仅支持 Basic 认证（应用专用密码），不支持 Google / iCloud 的 OAuth 登录流程。
 - 时区规则：带 TZID（命名时区）的事件输出会转成 UTC（Z）；全天边界、夏令时等复杂时区规则不做精细化处理。
 - 无设置页 UI：本轮为 node 半身，配置只走 cordis.patch.yml，不提供 Web 设置页。
@@ -116,3 +119,9 @@ pnpm test   # 构建 + node --test
 ```
 
 构建产物在 `lib/`，测试在 `test/*.test.mjs`（不依赖真实账号）。
+
+## 相关插件
+
+- [dsh-calendar](https://github.com/STARDUSTLC666/dsh-calendar) — CalDAV 日历五件套
+- [dsh-slack](https://github.com/STARDUSTLC666/dsh-slack) — Slack 通知/收件箱
+- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）

package/lib/caldav.d.ts

@@ -19,11 +19,16 @@ export declare class CalendarService {
     constructor(config: ResolvedConfig);
     private client;
     private calendar;
-    /** 列出某时间段内的事件（不展开 RRULE）。 */
-    list(startIso: string, endIso: string): Promise<CalendarEvent[]>;
+    /** 列出某时间段内的事件；expand 为 true 时在窗口内展开 RRULE。 */
+    list(startIso: string, endIso: string, options?: {
+        expand?: boolean;
+        maxOccurrences?: number;
+    }): Promise<CalendarEvent[]>;
     /** 列出全部事件（客户端过滤用）。 */
     all(): Promise<CalendarEvent[]>;
     private toEvents;
+    /** 列出并展开：每个对象经 expandEventFromICal 展开为若干实例行。 */
+    private toExpandedEvents;
     /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
     private findObject;
     /** 新建事件，返回带 href/uid 的事件。 */

package/lib/caldav.js

@@ -5,7 +5,7 @@
  * @module dsh-calendar/caldav
  */
 import { createDAVClient } from 'tsdav';
-import { buildICalString, generateUid, parseEventFromICal, } from './ical.js';
+import { buildICalString, expandEventFromICal, generateUid, parseEventFromICal, } from './ical.js';
 /** CalDAV 操作错误：带中文指引。 */
 export class CalDAVError extends Error {
     status;
@@ -53,8 +53,10 @@ export class CalendarService {
     calendar() {
         return { url: this.collectionUrl };
     }
-    /** 列出某时间段内的事件（不展开 RRULE）。 */
-    async list(startIso, endIso) {
+    /** 列出某时间段内的事件；expand 为 true 时在窗口内展开 RRULE。 */
+    async list(startIso, endIso, options) {
+        const expand = options?.expand !== false;
+        const maxOccurrences = options?.maxOccurrences ?? 30;
         try {
             const client = await this.client();
             const objects = await client.fetchCalendarObjects({
@@ -62,7 +64,9 @@ export class CalendarService {
                 timeRange: { start: startIso, end: endIso },
                 urlFilter: (url) => typeof url === 'string' && url.length > 0,
             });
-            return this.toEvents(objects);
+            return expand
+                ? this.toExpandedEvents(objects, startIso, endIso, maxOccurrences)
+                : this.toEvents(objects);
         }
         catch (error) {
             throw translateError(error, '读取日历');
@@ -91,6 +95,14 @@ export class CalendarService {
         }
         return events;
     }
+    /** 列出并展开：每个对象经 expandEventFromICal 展开为若干实例行。 */
+    toExpandedEvents(objects, startIso, endIso, maxOccurrences) {
+        const events = [];
+        for (const object of objects) {
+            events.push(...expandEventFromICal(String(object.data ?? ''), object.url, object.etag, startIso, endIso, maxOccurrences));
+        }
+        return events;
+    }
     /** 按 uid（href）找到服务器对象（含 etag 与原始 data）。 */
     async findObject(uid) {
         const client = await this.client();

package/lib/ical.d.ts

@@ -1,10 +1,10 @@
 /**
- * iCal 解析与生成：用 ical.js 处理 VEVENT 的字段提取与 round-trip 序列化。
+ * iCal 解析与生成：用 ical.js 处理 VEVENT 的字段提取、round-trip 序列化与重复展开。
  * 输入输出统一 ISO 8601（含时区偏移）：全天事件用 YYYY-MM-DD，定时事件转 UTC（Z）。
  *
  * @module dsh-calendar/ical
  */
-/** 一个暴露给模型的日历事件。 */
+/** 一个暴露给模型的日历事件（或重复系列的一个展开实例）。 */
 export interface CalendarEvent {
     /** 稳定标识（CalDAV href），calendar_update / calendar_delete 用它。 */
     uid: string;
@@ -22,8 +22,12 @@ export interface CalendarEvent {
     /** 结束时间，同上；无 DTEND/DURATION 时等于 start。 */
     end: string;
     allDay: boolean;
-    /** 重复规则原样返回，不展开（见 README 已知限制）。 */
+    /** 重复规则原样返回（未展开时）；展开后的实例不带此字段。 */
     rrule?: string;
+    /** 是否为重复系列展开出的实例；非重复事件为 false。 */
+    isOccurrence?: boolean;
+    /** 系列原开始时间（仅 isOccurrence 为 true 的实例存在）。 */
+    seriesStart?: string;
     status?: string;
     url?: string;
     created?: string;
@@ -47,6 +51,18 @@ export interface EventFields {
  * @param etag - 服务器 ETag。
  */
 export declare function parseEventFromICal(data: string, href: string, etag?: string): CalendarEvent | null;
+/**
+ * 解析并（可选）展开一个 VEVENT：非重复事件原样返回（isOccurrence: false）；
+ * 重复事件用 ICAL.RecurExpansion 在 [rangeStart, rangeEnd] 内展开，最多返回
+ * maxOccurrences 个实例（isOccurrence: true + seriesStart）。
+ * @param data - iCal 文本。
+ * @param href - CalDAV 对象 href，作为稳定 uid。
+ * @param etag - 服务器 ETag。
+ * @param rangeStart - 查询窗口起始（ISO 8601）。
+ * @param rangeEnd - 查询窗口结束（ISO 8601）。
+ * @param maxOccurrences - 每个事件最多展开的实例数（防死循环）。
+ */
+export declare function expandEventFromICal(data: string, href: string, etag: string | undefined, rangeStart: string, rangeEnd: string, maxOccurrences: number): CalendarEvent[];
 /** 生成随机 iCal UID（带 host 后缀，形如 UUID）。 */
 export declare function generateUid(): string;
 /** 把字段生成一段完整 iCal 文本（单个 VEVENT）。 */

package/lib/ical.js

@@ -1,5 +1,5 @@
 /**
- * iCal 解析与生成：用 ical.js 处理 VEVENT 的字段提取与 round-trip 序列化。
+ * iCal 解析与生成：用 ical.js 处理 VEVENT 的字段提取、round-trip 序列化与重复展开。
  * 输入输出统一 ISO 8601（含时区偏移）：全天事件用 YYYY-MM-DD，定时事件转 UTC（Z）。
  *
  * @module dsh-calendar/ical
@@ -31,10 +31,22 @@ function icalTimeToIso(time) {
     }
     return time.toJSDate().toISOString().replace(/\.\d{3}Z$/, 'Z');
 }
+/** 把 ISO 字符串转成 epoch 毫秒，用于时间窗口比较。 */
+function isoToEpochMs(value) {
+    return new Date(value).getTime();
+}
 function timePropertyValue(vevent, name) {
     const value = vevent.getFirstPropertyValue(name);
     return value instanceof ICAL.Time ? value : undefined;
 }
+/** 计算事件时长：优先 DTEND，其次 DURATION；两者皆无返回 null（时长视为 0）。 */
+function veventDuration(vevent, dtstart) {
+    const dtend = timePropertyValue(vevent, 'dtend');
+    if (dtend !== undefined)
+        return dtend.subtractDate(dtstart);
+    const duration = vevent.getFirstPropertyValue('duration');
+    return duration instanceof ICAL.Duration ? duration : null;
+}
 /**
  * 解析一段 iCal 文本中的首个 VEVENT 为 CalendarEvent；解析失败返回 null。
  * @param data - iCal 文本（通常来自服务器的 calendar-data）。
@@ -52,6 +64,10 @@ export function parseEventFromICal(data, href, etag) {
     const vevent = vcal.getFirstSubcomponent('vevent');
     if (vevent === null)
         return null;
+    return veventToEvent(vevent, href, etag);
+}
+/** 把单个 VEVENT 组件映射为 CalendarEvent（不展开重复）。 */
+function veventToEvent(vevent, href, etag) {
     const icalUid = asString(vevent.getFirstPropertyValue('uid'));
     const summary = asString(vevent.getFirstPropertyValue('summary')) ?? '';
     const description = asString(vevent.getFirstPropertyValue('description'));
@@ -98,6 +114,88 @@ export function parseEventFromICal(data, href, etag) {
     };
     return event;
 }
+/** 由一次 occurrence 起始时间构造实例行。 */
+function buildOccurrence(base, occurrenceStart, duration) {
+    const start = icalTimeToIso(occurrenceStart);
+    let end = start;
+    if (duration !== null) {
+        const endTime = occurrenceStart.clone();
+        endTime.addDuration(duration);
+        end = icalTimeToIso(endTime);
+    }
+    return {
+        uid: base.uid,
+        href: base.href,
+        summary: base.summary,
+        start,
+        end,
+        allDay: base.allDay,
+        isOccurrence: true,
+        seriesStart: base.start,
+        ...(base.icalUid !== undefined ? { icalUid: base.icalUid } : {}),
+        ...(base.etag !== undefined ? { etag: base.etag } : {}),
+        ...(base.description !== undefined ? { description: base.description } : {}),
+        ...(base.location !== undefined ? { location: base.location } : {}),
+        ...(base.status !== undefined ? { status: base.status } : {}),
+        ...(base.url !== undefined ? { url: base.url } : {}),
+        ...(base.created !== undefined ? { created: base.created } : {}),
+        ...(base.lastModified !== undefined ? { lastModified: base.lastModified } : {}),
+    };
+}
+/**
+ * 解析并（可选）展开一个 VEVENT：非重复事件原样返回（isOccurrence: false）；
+ * 重复事件用 ICAL.RecurExpansion 在 [rangeStart, rangeEnd] 内展开，最多返回
+ * maxOccurrences 个实例（isOccurrence: true + seriesStart）。
+ * @param data - iCal 文本。
+ * @param href - CalDAV 对象 href，作为稳定 uid。
+ * @param etag - 服务器 ETag。
+ * @param rangeStart - 查询窗口起始（ISO 8601）。
+ * @param rangeEnd - 查询窗口结束（ISO 8601）。
+ * @param maxOccurrences - 每个事件最多展开的实例数（防死循环）。
+ */
+export function expandEventFromICal(data, href, etag, rangeStart, rangeEnd, maxOccurrences) {
+    const base = parseEventFromICal(data, href, etag);
+    if (base === null)
+        return [];
+    let vcal;
+    try {
+        vcal = new ICAL.Component(ICAL.parse(data));
+    }
+    catch {
+        return [{ ...base, isOccurrence: false }];
+    }
+    const vevent = vcal.getFirstSubcomponent('vevent');
+    if (vevent === null)
+        return [{ ...base, isOccurrence: false }];
+    if (!vevent.hasProperty('rrule') && !vevent.hasProperty('rdate')) {
+        return [{ ...base, isOccurrence: false }];
+    }
+    const dtstart = timePropertyValue(vevent, 'dtstart');
+    if (dtstart === undefined)
+        return [{ ...base, isOccurrence: false }];
+    const duration = veventDuration(vevent, dtstart);
+    const expansion = new ICAL.RecurExpansion({ component: vevent, dtstart });
+    const rangeStartMs = isoToEpochMs(rangeStart);
+    const rangeEndMs = isoToEpochMs(rangeEnd);
+    const occurrences = [];
+    try {
+        while (occurrences.length < maxOccurrences) {
+            const next = expansion.next();
+            if (next === null || next === undefined)
+                break;
+            const occMs = next.toUnixTime() * 1000;
+            if (occMs > rangeEndMs)
+                break;
+            if (occMs < rangeStartMs)
+                continue;
+            occurrences.push(buildOccurrence(base, next, duration));
+        }
+    }
+    catch {
+        // 规则无法满足或迭代异常时，返回已成功展开的部分实例。
+    }
+    return occurrences;
+}
 /** 生成随机 iCal UID（带 host 后缀，形如 UUID）。 */
 export function generateUid() {
     return randomUUID();

package/lib/tools.js

@@ -31,6 +31,17 @@ function optionalInteger(args, key) {
     const value = args[key];
     return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
 }
+function booleanWithDefault(args, key, fallback) {
+    const value = args[key];
+    return typeof value === 'boolean' ? value : fallback;
+}
+/** 读取整数并 clamp 到 [min, max]；非法值返回 fallback。 */
+function clampedInteger(args, key, fallback, min, max) {
+    const value = args[key];
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return fallback;
+    return Math.min(max, Math.max(min, value));
+}
 function assertIsoTime(value, label) {
     if (/^\d{4}-\d{2}-\d{2}$/.test(value))
         return;
@@ -60,10 +71,12 @@ export function buildCalendarTools(config) {
     const service = () => new CalendarService(resolveConfig(config));
     const list = {
         name: 'calendar_list',
-        description: '列出某时间段内的日历事件（默认未来 7 天）。start/end 为 ISO 8601 时间（含时区偏移，如 2025-01-01T09:00:00+08:00），全天事件返回 YYYY-MM-DD。重复事件不展开，原始重复规则见每个事件的 rrule 字段。返回每个事件的稳定标识 uid，供 calendar_update / calendar_delete 使用。',
+        description: '列出某时间段内的日历事件（默认未来 7 天）。start/end 为 ISO 8601 时间（含时区偏移，如 2025-01-01T09:00:00+08:00），全天事件返回 YYYY-MM-DD。默认展开重复事件（RRULE）：每个实例作为独立行返回，start/end 为该次发生时间，并带 isOccurrence=true 与 seriesStart（系列原开始时间）；非重复事件保持单行且 isOccurrence=false。expand=false 时重复事件按原始单条返回并带 rrule 字段。maxOccurrences 为每个重复事件的展开次数上限。返回每个事件的稳定标识 uid，供 calendar_update / calendar_delete 使用。',
         parameters: compileParameters({
             start: { type: 'string', description: '起始时间（ISO 8601，含时区偏移）。缺省为当前时间（UTC）。' },
             end: { type: 'string', description: '结束时间（ISO 8601，含时区偏移）。缺省为 start 后 7 天。' },
+            expand: { type: 'boolean', description: '是否展开重复事件（RRULE）。默认 true；设为 false 时重复事件按原始单条返回并带 rrule 字段。' },
+            maxOccurrences: { type: 'integer', description: '每个重复事件最多展开的实例数上限（默认 30，自动 clamp 到 1-200），防止无终止规则死循环。' },
         }),
         output: {
             schema: {
@@ -93,7 +106,9 @@ export function buildCalendarTools(config) {
             const end = optionalString(input, 'end') ?? isoNoMillis(defaultEnd.toISOString());
             assertIsoTime(start, 'start');
             assertIsoTime(end, 'end');
-            const events = await service().list(start, end);
+            const expand = booleanWithDefault(input, 'expand', true);
+            const maxOccurrences = clampedInteger(input, 'maxOccurrences', 30, 1, 200);
+            const events = await service().list(start, end, { expand, maxOccurrences });
             return { count: events.length, start, end, events };
         },
         timeoutMs: TIMEOUT_MS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calendar",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
   "type": "module",
   "main": "lib/index.js",
@@ -58,5 +58,6 @@
     "url": "https://github.com/STARDUSTLC666/dsh-calendar/issues"
   },
   "homepage": "https://github.com/STARDUSTLC666/dsh-calendar#readme",
-  "author": "stardustlc"
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
 }