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

package/src/oauth.ts

@@ -0,0 +1,298 @@
+/**
+ * Google Calendar and Microsoft Graph providers backed by OAuthTokenManager
+ * (refresh_token flow; access tokens are never stored in config).
+ */
+import type {
+  CalendarEvent,
+  CalendarProvider,
+  CreateEventInput,
+} from "./types.js";
+import { formatInZone } from "./time.js";
+import {
+  OAuthTokenManager,
+  type AuthorizationLostListener,
+  type RefreshTokenStore,
+  type TokenManagerLogger,
+} from "./token-manager.js";
+
+export interface OAuthCalendarOptions {
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  /** Fallback refresh token from config/env. */
+  readonly refreshToken?: string;
+  readonly tokenStore?: RefreshTokenStore;
+  readonly onAuthorizationLost?: AuthorizationLostListener;
+  /** Use an existing manager (shared with the chat auth flow) instead of creating one. */
+  readonly tokenManager?: OAuthTokenManager;
+  readonly calendarId: string;
+  readonly timezone: string;
+  readonly tenant?: string;
+  /** Optional JSON file to persist rotated refresh tokens. */
+  readonly tokenFile?: string;
+  readonly fetchImpl?: typeof fetch;
+  readonly logger?: TokenManagerLogger;
+}
+
+function mapGoogleEvent(
+  item: Record<string, unknown>,
+  timezone: string
+): CalendarEvent {
+  const start = (item.start as { dateTime?: string; date?: string }) ?? {};
+  const end = (item.end as { dateTime?: string; date?: string }) ?? {};
+  const startDate = new Date(start.dateTime ?? start.date ?? "");
+  const endDate = new Date(end.dateTime ?? end.date ?? "");
+  return {
+    id: String(item.id ?? ""),
+    title: String(item.summary ?? "(无标题)"),
+    start: formatInZone(startDate, timezone),
+    end: formatInZone(endDate, timezone),
+    location: item.location ? String(item.location) : undefined,
+    description: item.description ? String(item.description) : undefined,
+    all_day: Boolean(start.date && !start.dateTime),
+  };
+}
+
+function mapMicrosoftEvent(
+  item: Record<string, unknown>,
+  timezone: string
+): CalendarEvent {
+  const start = (item.start as { dateTime?: string }) ?? {};
+  const end = (item.end as { dateTime?: string }) ?? {};
+  const startRaw = start.dateTime ?? "";
+  const endRaw = end.dateTime ?? "";
+  const startDate = new Date(
+    /[zZ]|[+-]\d{2}:?\d{2}$/.test(startRaw) ? startRaw : `${startRaw}Z`
+  );
+  const endDate = new Date(
+    /[zZ]|[+-]\d{2}:?\d{2}$/.test(endRaw) ? endRaw : `${endRaw}Z`
+  );
+  return {
+    id: String(item.id ?? ""),
+    title: String(item.subject ?? "(无标题)"),
+    start: formatInZone(startDate, timezone),
+    end: formatInZone(endDate, timezone),
+    location: item.location
+      ? String((item.location as { displayName?: string }).displayName ?? "")
+      : undefined,
+    description: item.bodyPreview ? String(item.bodyPreview) : undefined,
+    all_day: Boolean(item.isAllDay),
+  };
+}
+
+async function withBearer(
+  manager: OAuthTokenManager,
+  fetchImpl: typeof fetch,
+  url: string,
+  init: RequestInit,
+  extraHeaders?: Record<string, string>
+): Promise<Response> {
+  const token = await manager.getAccessToken();
+  const headers = {
+    ...(init.headers as Record<string, string> | undefined),
+    ...extraHeaders,
+    authorization: `Bearer ${token}`,
+  };
+  let response = await fetchImpl(url, { ...init, headers });
+  if (response.status === 401) {
+    const fresh = await manager.forceRefresh();
+    response = await fetchImpl(url, {
+      ...init,
+      headers: { ...headers, authorization: `Bearer ${fresh}` },
+    });
+  }
+  return response;
+}
+
+export function createGoogleCalendarProvider(
+  options: OAuthCalendarOptions
+): CalendarProvider {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const manager =
+    options.tokenManager ??
+    new OAuthTokenManager({
+      provider: "google",
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      initialRefreshToken: options.refreshToken,
+      tokenFile: options.tokenFile,
+      fetchImpl,
+      logger: options.logger,
+      tokenStore: options.tokenStore,
+      onAuthorizationLost: options.onAuthorizationLost,
+    });
+  const calendarId = encodeURIComponent(options.calendarId.trim() || "primary");
+  let hydrated = false;
+  async function ensureHydrated(): Promise<void> {
+    if (hydrated) return;
+    await manager.hydrate();
+    hydrated = true;
+  }
+
+  return {
+    name: "google",
+    async listEvents(from, to, signal) {
+      await ensureHydrated();
+      const url = new URL(
+        `https://www.googleapis.com/calendar/v3/calendars/${calendarId}/events`
+      );
+      url.searchParams.set("timeMin", from.toISOString());
+      url.searchParams.set("timeMax", to.toISOString());
+      url.searchParams.set("singleEvents", "true");
+      url.searchParams.set("orderBy", "startTime");
+      const response = await withBearer(manager, fetchImpl, url.toString(), {
+        signal,
+      });
+      if (!response.ok) {
+        const detail = (await response.text().catch(() => "")).slice(0, 300);
+        throw new Error(
+          `Google Calendar 列表失败：HTTP ${response.status} ${detail}`
+        );
+      }
+      const data = (await response.json()) as {
+        items?: Record<string, unknown>[];
+      };
+      return (data.items ?? []).map((item) =>
+        mapGoogleEvent(item, options.timezone)
+      );
+    },
+    async createEvent(input, signal) {
+      await ensureHydrated();
+      const body = {
+        summary: input.title,
+        description: input.description,
+        location: input.location,
+        start: input.all_day
+          ? { date: input.start.toISOString().slice(0, 10) }
+          : { dateTime: input.start.toISOString(), timeZone: options.timezone },
+        end: input.all_day
+          ? { date: input.end.toISOString().slice(0, 10) }
+          : { dateTime: input.end.toISOString(), timeZone: options.timezone },
+      };
+      const response = await withBearer(
+        manager,
+        fetchImpl,
+        `https://www.googleapis.com/calendar/v3/calendars/${calendarId}/events`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          signal,
+        }
+      );
+      if (!response.ok)
+        throw new Error(`Google Calendar 创建失败：HTTP ${response.status}`);
+      return mapGoogleEvent(
+        (await response.json()) as Record<string, unknown>,
+        options.timezone
+      );
+    },
+  };
+}
+
+/** Default calendar when id empty / primary / me. */
+export function microsoftCalendarBase(calendarId: string): string {
+  const id = calendarId.trim();
+  if (!id || id === "primary" || id === "me") {
+    return "https://graph.microsoft.com/v1.0/me/calendar";
+  }
+  return `https://graph.microsoft.com/v1.0/me/calendars/${encodeURIComponent(
+    id
+  )}`;
+}
+
+export function createMicrosoftCalendarProvider(
+  options: OAuthCalendarOptions
+): CalendarProvider {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const manager =
+    options.tokenManager ??
+    new OAuthTokenManager({
+      provider: "microsoft",
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      tenant: options.tenant,
+      initialRefreshToken: options.refreshToken,
+      tokenFile: options.tokenFile,
+      fetchImpl,
+      logger: options.logger,
+      tokenStore: options.tokenStore,
+      onAuthorizationLost: options.onAuthorizationLost,
+    });
+  const base = microsoftCalendarBase(options.calendarId);
+  let hydrated = false;
+  async function ensureHydrated(): Promise<void> {
+    if (hydrated) return;
+    await manager.hydrate();
+    hydrated = true;
+  }
+
+  return {
+    name: "microsoft",
+    async listEvents(from, to, signal) {
+      await ensureHydrated();
+      const url = new URL(`${base}/calendarView`);
+      url.searchParams.set("startDateTime", from.toISOString());
+      url.searchParams.set("endDateTime", to.toISOString());
+      url.searchParams.set("$orderby", "start/dateTime");
+      url.searchParams.set("$top", "50");
+      const response = await withBearer(
+        manager,
+        fetchImpl,
+        url.toString(),
+        { signal },
+        {
+          prefer: `outlook.timezone="${options.timezone}"`,
+        }
+      );
+      if (!response.ok) {
+        const detail = (await response.text().catch(() => "")).slice(0, 300);
+        throw new Error(
+          `Microsoft Graph 列表失败：HTTP ${response.status} ${detail}`
+        );
+      }
+      const data = (await response.json()) as {
+        value?: Record<string, unknown>[];
+      };
+      return (data.value ?? []).map((item) =>
+        mapMicrosoftEvent(item, options.timezone)
+      );
+    },
+    async createEvent(input, signal) {
+      await ensureHydrated();
+      const body = {
+        subject: input.title,
+        body: input.description
+          ? { contentType: "Text", content: input.description }
+          : undefined,
+        location: input.location ? { displayName: input.location } : undefined,
+        start: {
+          dateTime: input.start.toISOString().replace(/\.\d{3}Z$/, ""),
+          timeZone: "UTC",
+        },
+        end: {
+          dateTime: input.end.toISOString().replace(/\.\d{3}Z$/, ""),
+          timeZone: "UTC",
+        },
+        isAllDay: Boolean(input.all_day),
+      };
+      const response = await withBearer(
+        manager,
+        fetchImpl,
+        `${base}/events`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          signal,
+        },
+        { prefer: `outlook.timezone="${options.timezone}"` }
+      );
+      if (!response.ok)
+        throw new Error(`Microsoft Graph 创建失败：HTTP ${response.status}`);
+      return mapMicrosoftEvent(
+        (await response.json()) as Record<string, unknown>,
+        options.timezone
+      );
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,16 @@
+import { createToken } from "zhin.js";
+import type { CalendarConfig } from "./config.js";
+import type { CalendarProvider } from "./types.js";
+import type { CalendarAuthService } from "./chat-auth.js";
+
+export interface CalendarRuntime {
+  readonly config: CalendarConfig;
+  readonly provider: CalendarProvider | undefined;
+  /** Chat authorization flow used by the `calendar` commands. */
+  readonly auth: CalendarAuthService<unknown>;
+}
+
+export const calendarRuntimeToken = createToken<CalendarRuntime>(
+  "zhin.calendar.runtime",
+  "Owner-scoped calendar provider and config"
+);

package/src/secrets.ts

@@ -0,0 +1,5 @@
+/** Treat unresolved ${ENV} placeholders as empty. */
+export function cleanSecret(value: string): string {
+  const text = (value ?? "").trim();
+  return /^\$\{[^}]*\}$/.test(text) ? "" : text;
+}

package/src/time.ts

@@ -0,0 +1,167 @@
+/**
+ * Timezone helpers built on Intl (no dependencies).
+ */
+
+export interface ZonedParts {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  weekday: number;
+}
+
+const formatterCache = new Map<string, Intl.DateTimeFormat>();
+
+function formatterFor(timeZone: string): Intl.DateTimeFormat {
+  let formatter = formatterCache.get(timeZone);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      second: "numeric",
+      weekday: "short",
+    });
+    formatterCache.set(timeZone, formatter);
+  }
+  return formatter;
+}
+
+const WEEKDAYS: Readonly<Record<string, number>> = {
+  Sun: 0,
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6,
+};
+
+/** Throws a readable error for unknown IANA zones. */
+export function assertTimeZone(timeZone: string): void {
+  try {
+    formatterFor(timeZone);
+  } catch {
+    throw new Error(`未知时区：${timeZone}`);
+  }
+}
+
+/** Wall-clock parts of `date` in `timeZone`. */
+export function zonedParts(date: Date, timeZone: string): ZonedParts {
+  const parts: Record<string, string> = {};
+  for (const part of formatterFor(timeZone).formatToParts(date))
+    parts[part.type] = part.value;
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    hour: Number(parts.hour),
+    minute: Number(parts.minute),
+    second: Number(parts.second),
+    weekday: WEEKDAYS[parts.weekday ?? "Sun"] ?? 0,
+  };
+}
+
+/** Offset (ms) of `timeZone` from UTC at instant `date`. */
+export function timeZoneOffsetMs(date: Date, timeZone: string): number {
+  const parts = zonedParts(date, timeZone);
+  const asUtc = Date.UTC(
+    parts.year,
+    parts.month - 1,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second
+  );
+  return asUtc - Math.floor(date.getTime() / 1000) * 1000;
+}
+
+/** Converts a wall-clock time in `timeZone` to a UTC instant. */
+export function zonedTimeToUtc(
+  wall: {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second?: number;
+  },
+  timeZone: string
+): Date {
+  const guess = Date.UTC(
+    wall.year,
+    wall.month - 1,
+    wall.day,
+    wall.hour,
+    wall.minute,
+    wall.second ?? 0
+  );
+  const first = guess - timeZoneOffsetMs(new Date(guess), timeZone);
+  const second = guess - timeZoneOffsetMs(new Date(first), timeZone);
+  return new Date(second);
+}
+
+/** Formats an instant as `YYYY-MM-DD HH:mm` in `timeZone`. */
+export function formatInZone(date: Date, timeZone: string): string {
+  const p = zonedParts(date, timeZone);
+  const pad = (value: number) => String(value).padStart(2, "0");
+  return `${p.year}-${pad(p.month)}-${pad(p.day)} ${pad(p.hour)}:${pad(
+    p.minute
+  )}`;
+}
+
+/**
+ * Parses an ISO-8601 date-time. Without an explicit offset/`Z`, the value is
+ * interpreted as wall-clock time in `timeZone`.
+ */
+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}`);
+    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 格式）`);
+  return zonedTimeToUtc(
+    {
+      year: Number(match[1]),
+      month: Number(match[2]),
+      day: Number(match[3]),
+      hour: Number(match[4] ?? 0),
+      minute: Number(match[5] ?? 0),
+      second: Number(match[6] ?? 0),
+    },
+    timeZone
+  );
+}
+
+/** Parses durations like `10m`, `2h30m`, `1d`, `90s`. */
+export function parseDuration(value: string): number {
+  const text = value.trim().toLowerCase();
+  const pattern = /(\d+)\s*(d|h|m|s)/g;
+  let total = 0;
+  let consumed = "";
+  for (const match of text.matchAll(pattern)) {
+    const amount = Number(match[1]);
+    const unit = match[2]!;
+    total +=
+      amount *
+      { d: 86400000, h: 3600000, m: 60000, s: 1000 }[
+        unit as "d" | "h" | "m" | "s"
+      ];
+    consumed += match[0];
+  }
+  if (total <= 0 || consumed.replace(/\s/g, "") !== text.replace(/\s/g, "")) {
+    throw new Error(`无法解析时长：${value}（示例：10m、2h30m、1d）`);
+  }
+  return total;
+}