@yanhaidao/wecom 2.3.150 → 2.3.180

package/src/capability/calendar/client.ts

@@ -0,0 +1,815 @@
+// ============================================================================
+// Calendar Client - Complete Implementation
+// 严格遵循企业微信官方 API 文档：https://developer.work.weixin.qq.com/document/path/93329
+// ============================================================================
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import { getAccessToken } from "../../transport/agent-api/core.js";
+import { wecomFetch } from "../../http.js";
+import { resolveWecomEgressProxyUrlFromNetwork } from "../../config/index.js";
+import { LIMITS } from "../../types/constants.js";
+import type {
+    CreateCalendarRequest, CreateCalendarResponse, UpdateCalendarRequest, UpdateCalendarResponse,
+    GetCalendarRequest, GetCalendarResponse, DeleteCalendarResponse,
+    CreateScheduleRequest, CreateScheduleResponse, UpdateScheduleRequest, UpdateScheduleResponse,
+    AddScheduleAttendeesRequest, AddScheduleAttendeesResponse,
+    DeleteScheduleAttendeesRequest, DeleteScheduleAttendeesResponse,
+    GetScheduleByCalendarRequest, GetScheduleByCalendarResponse,
+    GetScheduleRequest, GetScheduleResponse, DeleteScheduleRequest, DeleteScheduleResponse,
+    GetSystemCalendarIdRequest, GetSystemCalendarIdResponse,
+    CreateSystemScheduleRequest, RespondScheduleRequest, RespondScheduleResponse,
+    SyncScheduleRequest, SyncScheduleResponse, CalendarInfo, ScheduleInfo,
+    ScheduleReminders,
+} from "./types.js";
+
+// ============================================================================
+// Constants - 官方 API 限定值
+// ============================================================================
+
+const CALENDAR_LIMITS = {
+    ADMINS_MAX: 3,
+    SHARES_MAX: 2000,
+    PUBLIC_USERS_MAX: 1000,
+    PUBLIC_PARTIES_MAX: 100,
+    SUMMARY_MIN_LENGTH: 1,
+    SUMMARY_MAX_LENGTH: 128,
+    DESCRIPTION_MAX_LENGTH: 512,
+    COLOR_PATTERN: /^#?[0-9A-Fa-f]{6}$/,
+    SCHEDULE_ATTENDEES_MAX: 1000,
+    SCHEDULE_DESCRIPTION_MAX_LENGTH: 1000,
+    SCHEDULE_LOCATION_MAX_LENGTH: 128,
+    SCHEDULE_SUMMARY_MAX_LENGTH: 128,
+    REMINDER_BEFORE_EVENT_VALUES: [0, 300, 900, 3600, 86400],
+    REMINDER_TIME_DIFFS_VALUES: [0, -300, -900, -3600, -86400, 32400, -172800, -604800],
+    REPEAT_TYPE_VALUES: [0, 1, 2, 5, 7],
+    TIMEZONE_MIN: -12,
+    TIMEZONE_MAX: 12,
+    CAL_ID_LIST_MAX: 1000,
+    SCHEDULE_ID_LIST_MAX: 1000,
+    GET_SCHEDULE_LIMIT_MIN: 1,
+    GET_SCHEDULE_LIMIT_MAX: 1000,
+    OP_MODE_VALUES: [0, 1, 2],
+    PERMISSION_VALUES: [1, 3],
+    RESPONSE_STATUS_VALUES: [1, 2, 4],
+} as const;
+
+// ============================================================================
+// Validation Functions
+// ============================================================================
+
+function validateString(value: unknown, fieldName: string, opts?: { min?: number; max?: number; pattern?: RegExp; allowEmpty?: boolean }): string {
+    const str = String(value ?? "");
+    if (!opts?.allowEmpty && !str.trim()) {
+        throw new Error(`${fieldName} 不能为空`);
+    }
+    if (opts?.min !== undefined && str.length < opts.min) {
+        throw new Error(`${fieldName} 长度不能少于 ${opts.min} 字符`);
+    }
+    if (opts?.max !== undefined && str.length > opts.max) {
+        throw new Error(`${fieldName} 长度不能超过 ${opts.max} 字符`);
+    }
+    if (opts?.pattern && !opts.pattern.test(str)) {
+        throw new Error(`${fieldName} 格式不正确`);
+    }
+    return str;
+}
+
+function validateNumber(value: unknown, fieldName: string, opts?: { min?: number; max?: number; required?: boolean }): number {
+    if (value === undefined || value === null) {
+        if (opts?.required) throw new Error(`${fieldName} 是必填项`);
+        return 0;
+    }
+    const num = Number(value);
+    if (isNaN(num)) throw new Error(`${fieldName} 必须是数字`);
+    if (opts?.min !== undefined && num < opts.min) throw new Error(`${fieldName} 不能小于 ${opts.min}`);
+    if (opts?.max !== undefined && num > opts.max) throw new Error(`${fieldName} 不能大于 ${opts.max}`);
+    return num;
+}
+
+function validateArray<T>(value: unknown, fieldName: string, opts?: { min?: number; max?: number; required?: boolean }): any[] {
+    if (!Array.isArray(value)) {
+        if (opts?.required) throw new Error(`${fieldName} 必须是数组`);
+        return [];
+    }
+    if (opts?.min !== undefined && value.length < opts.min) {
+        throw new Error(`${fieldName} 至少需要 ${opts.min} 项`);
+    }
+    if (opts?.max !== undefined && value.length > opts.max) {
+        throw new Error(`${fieldName} 不能超过 ${opts.max} 项`);
+    }
+    return value;
+}
+
+function validateCalendarAdmins(admins?: string[]): string[] | undefined {
+    if (!admins) return undefined;
+    validateArray(admins, "admins", { max: CALENDAR_LIMITS.ADMINS_MAX });
+    return admins.map((id, i) => validateString(id, `admins[${i}]`, { allowEmpty: false }));
+}
+
+function validateCalendarShares(shares?: Array<{ userid: string; permission?: 1 | 3 }>): Array<{ userid: string; permission?: 1 | 3 }> | undefined {
+    if (!shares) return undefined;
+    validateArray(shares, "shares", { max: CALENDAR_LIMITS.SHARES_MAX });
+    return shares.map((s, i) => {
+        const userid = validateString(s.userid, `shares[${i}].userid`, { allowEmpty: false });
+        if (s.permission !== undefined && !CALENDAR_LIMITS.PERMISSION_VALUES.includes(s.permission)) {
+            throw new Error(`shares[${i}].permission 必须是 1 或 3`);
+        }
+        return { userid, permission: s.permission };
+    });
+}
+
+function validatePublicRange(publicRange?: { userids?: string[]; partyids?: number[] }): { userids?: string[]; partyids?: number[] } | undefined {
+    if (!publicRange) return undefined;
+    const result: { userids?: string[]; partyids?: number[] } = {};
+    if (publicRange.userids) {
+        validateArray(publicRange.userids, "public_range.userids", { max: CALENDAR_LIMITS.PUBLIC_USERS_MAX });
+        result.userids = publicRange.userids.map((id, i) => validateString(id, `public_range.userids[${i}]`, { allowEmpty: false }));
+    }
+    if (publicRange.partyids) {
+        validateArray(publicRange.partyids, "public_range.partyids", { max: CALENDAR_LIMITS.PUBLIC_PARTIES_MAX });
+        result.partyids = publicRange.partyids.map((id, i) => validateNumber(id, `public_range.partyids[${i}]`, { min: 1, required: true }));
+    }
+    return result;
+}
+
+function validateScheduleAttendees(attendees?: Array<{ userid: string }>): Array<{ userid: string }> | undefined {
+    if (!attendees) return undefined;
+    validateArray(attendees, "attendees", { max: CALENDAR_LIMITS.SCHEDULE_ATTENDEES_MAX });
+    return attendees.map((a, i) => ({
+        userid: validateString(a.userid, `attendees[${i}].userid`, { allowEmpty: false, max: 64 })
+    }));
+}
+
+function validateReminders(reminders?: any): any | undefined {
+    if (!reminders) return undefined;
+    const result: any = {};
+
+    if (reminders.is_remind !== undefined) {
+        if (![0, 1].includes(reminders.is_remind)) throw new Error("reminders.is_remind 必须是 0 或 1");
+        result.is_remind = reminders.is_remind;
+    }
+
+    if (reminders.is_repeat !== undefined) {
+        if (![0, 1].includes(reminders.is_repeat)) throw new Error("reminders.is_repeat 必须是 0 或 1");
+        result.is_repeat = reminders.is_repeat;
+    }
+
+    if (reminders.remind_before_event_secs !== undefined) {
+        const val = reminders.remind_before_event_secs;
+        if (!CALENDAR_LIMITS.REMINDER_BEFORE_EVENT_VALUES.includes(val)) {
+            throw new Error(`reminders.remind_before_event_secs 必须是 ${CALENDAR_LIMITS.REMINDER_BEFORE_EVENT_VALUES.join(",")}`);
+        }
+        result.remind_before_event_secs = val;
+    }
+
+    if (reminders.remind_time_diffs !== undefined) {
+        validateArray(reminders.remind_time_diffs, "reminders.remind_time_diffs");
+        result.remind_time_diffs = reminders.remind_time_diffs.map((v: number, i: number) => {
+            if (!CALENDAR_LIMITS.REMINDER_TIME_DIFFS_VALUES.includes(v as any)) {
+                throw new Error(`reminders.remind_time_diffs[${i}] 必须是 ${CALENDAR_LIMITS.REMINDER_TIME_DIFFS_VALUES.join(",")}`);
+            }
+            return v as any;
+        });
+    }
+
+    if (reminders.repeat_type !== undefined) {
+        if (!CALENDAR_LIMITS.REPEAT_TYPE_VALUES.includes(reminders.repeat_type)) {
+            throw new Error(`reminders.repeat_type 必须是 ${CALENDAR_LIMITS.REPEAT_TYPE_VALUES.join(",")}`);
+        }
+        result.repeat_type = reminders.repeat_type;
+    }
+
+    if (reminders.repeat_until !== undefined) {
+        result.repeat_until = validateNumber(reminders.repeat_until, "reminders.repeat_until", { min: 0 });
+    }
+
+    if (reminders.is_custom_repeat !== undefined) {
+        if (![0, 1].includes(reminders.is_custom_repeat)) {
+            throw new Error("reminders.is_custom_repeat 必须是 0 或 1");
+        }
+        result.is_custom_repeat = reminders.is_custom_repeat;
+    }
+
+    if (reminders.repeat_interval !== undefined) {
+        result.repeat_interval = validateNumber(reminders.repeat_interval, "reminders.repeat_interval", { min: 1 });
+    }
+
+    if (reminders.repeat_day_of_week !== undefined) {
+        validateArray(reminders.repeat_day_of_week, "reminders.repeat_day_of_week");
+        result.repeat_day_of_week = reminders.repeat_day_of_week.map((v: number, i: number) => {
+            if (v < 1 || v > 7) throw new Error(`reminders.repeat_day_of_week[${i}] 必须是 1-7`);
+            return v;
+        });
+    }
+
+    if (reminders.repeat_day_of_month !== undefined) {
+        validateArray(reminders.repeat_day_of_month, "reminders.repeat_day_of_month");
+        result.repeat_day_of_month = reminders.repeat_day_of_month.map((v: number, i: number) => {
+            if (v < 1 || v > 31) throw new Error(`reminders.repeat_day_of_month[${i}] 必须是 1-31`);
+            return v;
+        });
+    }
+
+    if (reminders.timezone !== undefined) {
+        result.timezone = validateNumber(reminders.timezone, "reminders.timezone", {
+            min: CALENDAR_LIMITS.TIMEZONE_MIN,
+            max: CALENDAR_LIMITS.TIMEZONE_MAX
+        });
+    }
+
+    if (reminders.exclude_time_list !== undefined) {
+        validateArray(reminders.exclude_time_list, "reminders.exclude_time_list");
+        result.exclude_time_list = reminders.exclude_time_list.map((item: any, i: number) => ({
+            start_time: validateNumber(item.start_time, `reminders.exclude_time_list[${i}].start_time`, { min: 0, required: true })
+        }));
+    }
+
+    return result;
+}
+
+function validateOpMode(opMode?: number): 0 | 1 | 2 | undefined {
+    if (opMode === undefined) return undefined;
+    if (!CALENDAR_LIMITS.OP_MODE_VALUES.includes(opMode as any)) {
+        throw new Error(`op_mode 必须是 ${CALENDAR_LIMITS.OP_MODE_VALUES.join(",")}`);
+    }
+    return opMode as 0 | 1 | 2;
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+async function parseResponse<T>(res: Response, label: string): Promise<T> {
+    let json: any;
+    try {
+        json = await res.json();
+    } catch {
+        throw new Error(`${label}: 无效的 JSON 响应`);
+    }
+
+    if (!json || typeof json !== "object") {
+        throw new Error(`${label}: 空响应`);
+    }
+
+    if (Array.isArray(json)) {
+        const failed = json.find((i: any) => Number(i?.errcode ?? 0) !== 0);
+        if (failed) throw new Error(`${label}: ${failed?.errmsg || "failed"} (${failed?.errcode})`);
+        return json as T;
+    }
+
+    const errCode = Number(json.errcode ?? 0);
+    if (errCode !== 0) {
+        throw new Error(`${label}: ${json.errmsg || "failed"} (${errCode})`);
+    }
+
+    return json as T;
+}
+
+function normalizeColor(color: string): string {
+    const trimmed = color.trim();
+    return trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+}
+
+// ============================================================================
+// WecomCalendarClient Class
+// ============================================================================
+
+export class WecomCalendarClient {
+    private async post<T>(path: string, label: string, agent: ResolvedAgentAccount, body: any): Promise<T> {
+        if (!agent?.corpId || !agent?.corpSecret) {
+            throw new Error(`${label}: 账号配置不完整，需要 corpId 和 corpSecret`);
+        }
+
+        const token = await getAccessToken(agent);
+        const url = `https://qyapi.weixin.qq.com${path}?access_token=${encodeURIComponent(token)}`;
+        const proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
+
+        let lastError: Error | undefined;
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                const res = await wecomFetch(
+                    url,
+                    {
+                        method: "POST",
+                        headers: { "content-type": "application/json" },
+                        body: JSON.stringify(body || {}),
+                    },
+                    { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS }
+                );
+                return await parseResponse<T>(res, label);
+            } catch (e) {
+                lastError = e instanceof Error ? e : new Error(String(e));
+                if (attempt < 3) {
+                    await new Promise(r => setTimeout(r, 1000 * attempt));
+                }
+            }
+        }
+        throw lastError || new Error(`${label}: 请求失败`);
+    }
+
+    // ========================================================================
+    // Calendar APIs
+    // ========================================================================
+
+    /**
+     * 创建日历
+     * POST /cgi-bin/oa/calendar/add
+     */
+    async createCalendar(p: { agent: ResolvedAgentAccount; request: CreateCalendarRequest }): Promise<{ raw: CreateCalendarResponse; calId: string }> {
+        const calendar = p.request.calendar;
+
+        // 验证必填字段
+        const summary = validateString(calendar.summary, "calendar.summary", {
+            min: CALENDAR_LIMITS.SUMMARY_MIN_LENGTH,
+            max: CALENDAR_LIMITS.SUMMARY_MAX_LENGTH
+        });
+        const color = validateString(calendar.color, "calendar.color", { pattern: CALENDAR_LIMITS.COLOR_PATTERN });
+
+        // 验证可选字段
+        const description = calendar.description !== undefined
+            ? validateString(calendar.description, "calendar.description", { max: CALENDAR_LIMITS.DESCRIPTION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const admins = validateCalendarAdmins(calendar.admins);
+        const shares = validateCalendarShares(calendar.shares);
+        const publicRange = validatePublicRange(calendar.public_range);
+
+        if (calendar.set_as_default !== undefined && ![0, 1].includes(calendar.set_as_default)) {
+            throw new Error("calendar.set_as_default 必须是 0 或 1");
+        }
+        if (calendar.is_public !== undefined && ![0, 1].includes(calendar.is_public)) {
+            throw new Error("calendar.is_public 必须是 0 或 1");
+        }
+        if (calendar.is_corp_calendar !== undefined && ![0, 1].includes(calendar.is_corp_calendar)) {
+            throw new Error("calendar.is_corp_calendar 必须是 0 或 1");
+        }
+
+        // 全员日历必须是公共日历且必须指定 public_range
+        if (calendar.is_corp_calendar === 1) {
+            if (calendar.is_public !== 1) {
+                throw new Error("全员日历必须设置 is_public=1");
+            }
+            if (!publicRange || (!publicRange.userids && !publicRange.partyids)) {
+                throw new Error("全员日历必须指定 public_range");
+            }
+        }
+
+        const request: CreateCalendarRequest = {
+            calendar: {
+                summary,
+                color: normalizeColor(color),
+                description,
+                admins,
+                set_as_default: calendar.set_as_default,
+                shares,
+                is_public: calendar.is_public,
+                public_range: publicRange,
+                is_corp_calendar: calendar.is_corp_calendar,
+            },
+        };
+
+        if (p.request.agentid !== undefined) {
+            request.agentid = p.request.agentid;
+        }
+
+        const json = await this.post<CreateCalendarResponse>("/cgi-bin/oa/calendar/add", "create_calendar", p.agent, request);
+        return { raw: json, calId: json.cal_id };
+    }
+
+    /**
+     * 更新日历
+     * POST /cgi-bin/oa/calendar/update
+     * 注意：更新操作是覆盖式，不是增量式
+     */
+    async updateCalendar(p: { agent: ResolvedAgentAccount; request: UpdateCalendarRequest }): Promise<{ raw: UpdateCalendarResponse; calId: string }> {
+        const calendar = p.request.calendar;
+
+        const calId = validateString(calendar.cal_id, "calendar.cal_id", { allowEmpty: false });
+        const summary = validateString(calendar.summary, "calendar.summary", {
+            min: CALENDAR_LIMITS.SUMMARY_MIN_LENGTH,
+            max: CALENDAR_LIMITS.SUMMARY_MAX_LENGTH
+        });
+        const color = validateString(calendar.color, "calendar.color", { pattern: CALENDAR_LIMITS.COLOR_PATTERN });
+        const description = calendar.description !== undefined
+            ? validateString(calendar.description, "calendar.description", { max: CALENDAR_LIMITS.DESCRIPTION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const admins = validateCalendarAdmins(calendar.admins);
+        const shares = validateCalendarShares(calendar.shares);
+        const publicRange = validatePublicRange(calendar.public_range);
+
+        if (p.request.skip_public_range !== undefined && ![0, 1].includes(p.request.skip_public_range)) {
+            throw new Error("skip_public_range 必须是 0 或 1");
+        }
+
+        const request: UpdateCalendarRequest = {
+            calendar: {
+                cal_id: calId,
+                summary,
+                color: normalizeColor(color),
+                description,
+                admins,
+                shares,
+                public_range: publicRange,
+            },
+            skip_public_range: p.request.skip_public_range,
+        };
+
+        const json = await this.post<UpdateCalendarResponse>("/cgi-bin/oa/calendar/update", "update_calendar", p.agent, request);
+        return { raw: json, calId: calId };
+    }
+
+    /**
+     * 获取日历详情
+     * POST /cgi-bin/oa/calendar/get
+     */
+    async getCalendar(p: { agent: ResolvedAgentAccount; request: GetCalendarRequest }): Promise<{ raw: GetCalendarResponse; calendarList: CalendarInfo[] }> {
+        const calIdList = validateArray(p.request.cal_id_list, "cal_id_list", {
+            min: 1,
+            max: CALENDAR_LIMITS.CAL_ID_LIST_MAX,
+            required: true
+        }).map((id, i) => validateString(id, `cal_id_list[${i}]`, { allowEmpty: false }));
+
+        const request: GetCalendarRequest = { cal_id_list: calIdList };
+        const json = await this.post<GetCalendarResponse>("/cgi-bin/oa/calendar/get", "get_calendar", p.agent, request);
+        return { raw: json, calendarList: json.calendar_list || [] };
+    }
+
+    /**
+     * 删除日历
+     * POST /cgi-bin/oa/calendar/del
+     */
+    async deleteCalendar(p: { agent: ResolvedAgentAccount; calId: string }): Promise<{ raw: DeleteCalendarResponse; calId: string }> {
+        const calId = validateString(p.calId, "calId", { allowEmpty: false });
+        const json = await this.post<DeleteCalendarResponse>("/cgi-bin/oa/calendar/del", "delete_calendar", p.agent, { cal_id: calId });
+        return { raw: json, calId: calId };
+    }
+
+    // ========================================================================
+    // Schedule APIs
+    // ========================================================================
+
+    /**
+     * 创建日程
+     * POST /cgi-bin/oa/schedule/add
+     */
+    async createSchedule(p: { agent: ResolvedAgentAccount; request: CreateScheduleRequest }): Promise<{ raw: CreateScheduleResponse; scheduleId: string }> {
+        const schedule = p.request.schedule;
+
+        const startTime = validateNumber(schedule.start_time, "schedule.start_time", { min: 0, required: true });
+        const endTime = validateNumber(schedule.end_time, "schedule.end_time", { min: 0, required: true });
+
+        if (endTime <= startTime) {
+            throw new Error("schedule.end_time 必须大于 schedule.start_time");
+        }
+
+        if (schedule.is_whole_day !== undefined && ![0, 1].includes(schedule.is_whole_day)) {
+            throw new Error("schedule.is_whole_day 必须是 0 或 1");
+        }
+
+        const summary = schedule.summary !== undefined
+            ? validateString(schedule.summary, "schedule.summary", { max: CALENDAR_LIMITS.SCHEDULE_SUMMARY_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const description = schedule.description !== undefined
+            ? validateString(schedule.description, "schedule.description", { max: CALENDAR_LIMITS.SCHEDULE_DESCRIPTION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const location = schedule.location !== undefined
+            ? validateString(schedule.location, "schedule.location", { max: CALENDAR_LIMITS.SCHEDULE_LOCATION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const admins = validateCalendarAdmins(schedule.admins);
+        const attendees = validateScheduleAttendees(schedule.attendees);
+        const reminders = validateReminders(schedule.reminders);
+
+        const calId = schedule.cal_id !== undefined
+            ? validateString(schedule.cal_id, "schedule.cal_id", { max: 64, allowEmpty: true })
+            : undefined;
+
+        const request: CreateScheduleRequest = {
+            schedule: {
+                start_time: startTime,
+                end_time: endTime,
+                is_whole_day: schedule.is_whole_day,
+                summary,
+                description,
+                location,
+                admins,
+                attendees,
+                reminders,
+                cal_id: calId,
+            },
+        };
+
+        if (p.request.agentid !== undefined) {
+            request.agentid = p.request.agentid;
+        }
+
+        const json = await this.post<CreateScheduleResponse>("/cgi-bin/oa/schedule/add", "create_schedule", p.agent, request);
+        return { raw: json, scheduleId: json.schedule_id };
+    }
+
+    /**
+     * 更新日程
+     * POST /cgi-bin/oa/schedule/update
+     * 注意：更新操作是覆盖式，不是增量式
+     */
+    async updateSchedule(p: { agent: ResolvedAgentAccount; request: UpdateScheduleRequest }): Promise<{ raw: UpdateScheduleResponse; scheduleId: string }> {
+        const schedule = p.request.schedule;
+
+        const scheduleId = validateString(schedule.schedule_id, "schedule.schedule_id", { allowEmpty: false });
+        const startTime = validateNumber(schedule.start_time, "schedule.start_time", { min: 0, required: true });
+        const endTime = validateNumber(schedule.end_time, "schedule.end_time", { min: 0, required: true });
+
+        if (endTime <= startTime) {
+            throw new Error("schedule.end_time 必须大于 schedule.start_time");
+        }
+
+        if (schedule.is_whole_day !== undefined && ![0, 1].includes(schedule.is_whole_day)) {
+            throw new Error("schedule.is_whole_day 必须是 0 或 1");
+        }
+
+        const summary = schedule.summary !== undefined
+            ? validateString(schedule.summary, "schedule.summary", { max: CALENDAR_LIMITS.SCHEDULE_SUMMARY_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const description = schedule.description !== undefined
+            ? validateString(schedule.description, "schedule.description", { max: CALENDAR_LIMITS.SCHEDULE_DESCRIPTION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const location = schedule.location !== undefined
+            ? validateString(schedule.location, "schedule.location", { max: CALENDAR_LIMITS.SCHEDULE_LOCATION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const admins = validateCalendarAdmins(schedule.admins);
+        const attendees = validateScheduleAttendees(schedule.attendees);
+        const reminders = validateReminders(schedule.reminders);
+
+        if (p.request.skip_attendees !== undefined && ![0, 1].includes(p.request.skip_attendees)) {
+            throw new Error("skip_attendees 必须是 0 或 1");
+        }
+
+        const opMode = validateOpMode(p.request.op_mode);
+        const opStartTime = p.request.op_start_time !== undefined
+            ? validateNumber(p.request.op_start_time, "op_start_time", { min: 0 })
+            : undefined;
+
+        const request: UpdateScheduleRequest = {
+            schedule: {
+                schedule_id: scheduleId,
+                start_time: startTime,
+                end_time: endTime,
+                is_whole_day: schedule.is_whole_day,
+                summary,
+                description,
+                location,
+                admins,
+                attendees,
+                reminders,
+            },
+            skip_attendees: p.request.skip_attendees as any,
+            op_mode: opMode as any,
+            op_start_time: opStartTime,
+        };
+
+        const json = await this.post<UpdateScheduleResponse>("/cgi-bin/oa/schedule/update", "update_schedule", p.agent, request);
+        return { raw: json, scheduleId: json.schedule_id || scheduleId };
+    }
+
+    /**
+     * 新增日程参与者
+     * POST /cgi-bin/oa/schedule/add_attendees
+     * 注意：该接口是增量式
+     */
+    async addScheduleAttendees(p: { agent: ResolvedAgentAccount; request: AddScheduleAttendeesRequest }): Promise<{ raw: AddScheduleAttendeesResponse; scheduleId: string }> {
+        const scheduleId = validateString(p.request.schedule_id, "schedule_id", { allowEmpty: false });
+        const attendees = validateScheduleAttendees(p.request.attendees);
+
+        if (!attendees || attendees.length === 0) {
+            throw new Error("attendees 不能为空");
+        }
+
+        const request: AddScheduleAttendeesRequest = {
+            schedule_id: scheduleId,
+            attendees,
+        };
+
+        const json = await this.post<AddScheduleAttendeesResponse>("/cgi-bin/oa/schedule/add_attendees", "add_attendees", p.agent, request);
+        return { raw: json, scheduleId: scheduleId };
+    }
+
+    /**
+     * 删除日程参与者
+     * POST /cgi-bin/oa/schedule/del_attendees
+     * 注意：该接口是增量式
+     */
+    async deleteScheduleAttendees(p: { agent: ResolvedAgentAccount; request: DeleteScheduleAttendeesRequest }): Promise<{ raw: DeleteScheduleAttendeesResponse; scheduleId: string }> {
+        const scheduleId = validateString(p.request.schedule_id, "schedule_id", { allowEmpty: false });
+        const attendees = validateScheduleAttendees(p.request.attendees);
+
+        if (!attendees || attendees.length === 0) {
+            throw new Error("attendees 不能为空");
+        }
+
+        const request: DeleteScheduleAttendeesRequest = {
+            schedule_id: scheduleId,
+            attendees,
+        };
+
+        const json = await this.post<DeleteScheduleAttendeesResponse>("/cgi-bin/oa/schedule/del_attendees", "del_attendees", p.agent, request);
+        return { raw: json, scheduleId: scheduleId };
+    }
+
+    /**
+     * 获取日历下的日程列表
+     * POST /cgi-bin/oa/schedule/get_by_calendar
+     */
+    async getScheduleByCalendar(p: { agent: ResolvedAgentAccount; request: GetScheduleByCalendarRequest }): Promise<{ raw: GetScheduleByCalendarResponse; scheduleList: ScheduleInfo[] }> {
+        const calId = validateString(p.request.cal_id, "cal_id", { allowEmpty: false });
+
+        if (p.request.offset !== undefined && p.request.offset < 0) {
+            throw new Error("offset 不能小于 0");
+        }
+
+        let limit = p.request.limit;
+        if (limit !== undefined) {
+            if (limit < CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MIN || limit > CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MAX) {
+                throw new Error(`limit 必须在 ${CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MIN}-${CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MAX} 之间`);
+            }
+        }
+
+        const request: GetScheduleByCalendarRequest = {
+            cal_id: calId,
+            offset: p.request.offset,
+            limit: limit,
+        };
+
+        const json = await this.post<GetScheduleByCalendarResponse>("/cgi-bin/oa/schedule/get_by_calendar", "get_by_calendar", p.agent, request);
+        return { raw: json, scheduleList: json.schedule_list || [] };
+    }
+
+    /**
+     * 获取日程详情
+     * POST /cgi-bin/oa/schedule/get
+     */
+    async getSchedule(p: { agent: ResolvedAgentAccount; request: GetScheduleRequest }): Promise<{ raw: GetScheduleResponse; scheduleList: ScheduleInfo[]; meetingCode?: string; meetingLink?: string }> {
+        const scheduleIdList = validateArray(p.request.schedule_id_list, "schedule_id_list", {
+            min: 1,
+            max: CALENDAR_LIMITS.SCHEDULE_ID_LIST_MAX,
+            required: true
+        }).map((id, i) => validateString(id, `schedule_id_list[${i}]`, { allowEmpty: false }));
+
+        const request: GetScheduleRequest = { schedule_id_list: scheduleIdList };
+        const json = await this.post<GetScheduleResponse>("/cgi-bin/oa/schedule/get", "get_schedule", p.agent, request);
+        return {
+            raw: json,
+            scheduleList: json.schedule_list || [],
+            meetingCode: json.meeting_code,
+            meetingLink: json.meeting_link,
+        };
+    }
+
+    /**
+     * 取消日程
+     * POST /cgi-bin/oa/schedule/del
+     */
+    async deleteSchedule(p: { agent: ResolvedAgentAccount; request: DeleteScheduleRequest }): Promise<{ raw: DeleteScheduleResponse; scheduleId: string }> {
+        const scheduleId = validateString(p.request.schedule_id, "schedule_id", { allowEmpty: false });
+        const opMode = validateOpMode(p.request.op_mode);
+        const opStartTime = p.request.op_start_time !== undefined
+            ? validateNumber(p.request.op_start_time, "op_start_time", { min: 0 })
+            : undefined;
+
+        const request: DeleteScheduleRequest = {
+            schedule_id: scheduleId,
+            op_mode: opMode as any,
+            op_start_time: opStartTime,
+        };
+
+        const json = await this.post<DeleteScheduleResponse>("/cgi-bin/oa/schedule/del", "delete_schedule", p.agent, request);
+        return { raw: json, scheduleId: scheduleId };
+    }
+
+    // ========================================================================
+    // System Calendar APIs
+    // ========================================================================
+
+    /**
+     * 获取默认日历本 ID
+     * POST /cgi-bin/oa/calendar/get_system_calid
+     */
+    async getSystemCalendarId(p: { agent: ResolvedAgentAccount; userid: string }): Promise<{ raw: GetSystemCalendarIdResponse; calId: string }> {
+        const userid = validateString(p.userid, "userid", { allowEmpty: false });
+        const json = await this.post<GetSystemCalendarIdResponse>("/cgi-bin/oa/calendar/get_system_calid", "get_system_calid", p.agent, { userid });
+        return { raw: json, calId: json.cal_id };
+    }
+
+    /**
+     * 在默认日历本中创建日程
+     * POST /cgi-bin/oa/schedule/add_schedule_in_system_cal
+     */
+    async createSystemSchedule(p: { agent: ResolvedAgentAccount; request: CreateSystemScheduleRequest }): Promise<{ raw: CreateScheduleResponse; scheduleId: string }> {
+        const schedule = p.request.schedule;
+
+        const organizer = validateString(schedule.organizer, "schedule.organizer", { allowEmpty: false });
+        const startTime = validateNumber(schedule.start_time, "schedule.start_time", { min: 0, required: true });
+        const endTime = validateNumber(schedule.end_time, "schedule.end_time", { min: 0, required: true });
+
+        if (endTime <= startTime) {
+            throw new Error("schedule.end_time 必须大于 schedule.start_time");
+        }
+
+        if (schedule.is_whole_day !== undefined && ![0, 1].includes(schedule.is_whole_day)) {
+            throw new Error("schedule.is_whole_day 必须是 0 或 1");
+        }
+
+        const summary = schedule.summary !== undefined
+            ? validateString(schedule.summary, "schedule.summary", { max: CALENDAR_LIMITS.SCHEDULE_SUMMARY_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const description = schedule.description !== undefined
+            ? validateString(schedule.description, "schedule.description", { max: CALENDAR_LIMITS.SCHEDULE_DESCRIPTION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const location = schedule.location !== undefined
+            ? validateString(schedule.location, "schedule.location", { max: CALENDAR_LIMITS.SCHEDULE_LOCATION_MAX_LENGTH, allowEmpty: true })
+            : undefined;
+
+        const attendees = validateScheduleAttendees(schedule.attendees);
+        const reminders = validateReminders(schedule.reminders);
+
+        const request: CreateSystemScheduleRequest = {
+            schedule: {
+                organizer,
+                start_time: startTime,
+                end_time: endTime,
+                is_whole_day: schedule.is_whole_day,
+                summary,
+                description,
+                location,
+                attendees,
+                reminders,
+            },
+        };
+
+        const json = await this.post<CreateScheduleResponse>("/cgi-bin/oa/schedule/add_schedule_in_system_cal", "create_system_schedule", p.agent, request);
+        return { raw: json, scheduleId: json.schedule_id };
+    }
+
+    /**
+     * 日程回执
+     * POST /cgi-bin/oa/schedule/respond
+     */
+    async respondSchedule(p: { agent: ResolvedAgentAccount; request: RespondScheduleRequest }): Promise<{ raw: RespondScheduleResponse; scheduleId: string }> {
+        const scheduleId = validateString(p.request.schedule_id, "schedule_id", { allowEmpty: false });
+        const opMode = validateOpMode(p.request.op_mode);
+        const opStartTime = p.request.op_start_time !== undefined
+            ? validateNumber(p.request.op_start_time, "op_start_time", { min: 0 })
+            : undefined;
+
+        const attendee = validateString(p.request.attendee, "attendee", { allowEmpty: false });
+
+        if (!CALENDAR_LIMITS.RESPONSE_STATUS_VALUES.includes(p.request.response_status)) {
+            throw new Error(`response_status 必须是 ${CALENDAR_LIMITS.RESPONSE_STATUS_VALUES.join(",")}`);
+        }
+
+        const request: RespondScheduleRequest = {
+            schedule_id: scheduleId,
+            op_mode: opMode as any,
+            op_start_time: opStartTime,
+            attendee,
+            response_status: p.request.response_status as any,
+        };
+
+        const json = await this.post<RespondScheduleResponse>("/cgi-bin/oa/schedule/respond", "respond_schedule", p.agent, request);
+        return { raw: json, scheduleId: scheduleId };
+    }
+
+    /**
+     * 同步日程
+     * POST /cgi-bin/oa/schedule/sync
+     */
+    async syncSchedule(p: { agent: ResolvedAgentAccount; request: SyncScheduleRequest }): Promise<{ raw: SyncScheduleResponse; nextCursor: string; scheduleList: ScheduleInfo[] }> {
+        const calId = validateString(p.request.cal_id, "cal_id", { allowEmpty: false });
+
+        let limit = p.request.limit;
+        if (limit !== undefined) {
+            if (limit < CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MIN || limit > CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MAX) {
+                throw new Error(`limit 必须在 ${CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MIN}-${CALENDAR_LIMITS.GET_SCHEDULE_LIMIT_MAX} 之间`);
+            }
+        }
+
+        const request: SyncScheduleRequest = {
+            cal_id: calId,
+            cursor: p.request.cursor,
+            limit: limit,
+        };
+
+        const json = await this.post<SyncScheduleResponse>("/cgi-bin/oa/schedule/sync", "sync_schedule", p.agent, request);
+        return {
+            raw: json,
+            nextCursor: json.next_cursor,
+            scheduleList: json.schedule_list || [],
+        };
+    }
+}