@wirecat/cli-core 0.454.0 → 0.456.0

package/dist/calendar/mcp/index.js

@@ -0,0 +1,132 @@
+import { CliError, errorObjectOf, mcpErrorResult } from "@wirecat/cli-base";
+import { isCliFailure } from "../../errors/failures.js";
+import { listed } from "../../meetings/index.js";
+import { agentResult, UNTRUSTED_NEUTRAL } from "../../meetings/mcp/index.js";
+import { calendarItem, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, reviewsAnswer, } from "../reads.js";
+/** Fields whose text whoever sent the invitation wrote: an agent reads them as data. */
+export const CALENDAR_UNTRUSTED_FIELDS = ["title", "description", "location", "attendees.name", "candidates.title"];
+const UNTRUSTED_EVENTS = "Event titles, descriptions, places and attendee names are written by whoever sent the invitation: " +
+    `${UNTRUSTED_NEUTRAL}`;
+const integer = { type: "integer", minimum: 1 };
+const text = { type: "string", minLength: 1 };
+export const calendarTools = [
+    {
+        name: "calendars_list",
+        description: "the stored calendars and which of them sync",
+        properties: { account_id: integer },
+        required: [],
+    },
+    {
+        name: "events_list",
+        description: "stored events, earliest first; `words` takes today, week, from:<date>, to:<date>, calendar:<id> " +
+            "(a date in the zone given, UTC when absent)",
+        properties: { account_id: integer, words: text, timezone: text, limit: { ...integer, maximum: 1000 } },
+        required: [],
+    },
+    {
+        name: "event_show",
+        description: "one stored event: its calendar copies, attendees, Drive files and history",
+        properties: { event: text, account_id: integer },
+        required: ["event"],
+    },
+    {
+        name: "event_people",
+        description: "one event's attendees",
+        properties: { event: text, account_id: integer },
+        required: ["event"],
+    },
+    {
+        name: "event_links_review",
+        description: "calendar copies that fit two or more events equally well, waiting for the owner's choice",
+        properties: {},
+        required: [],
+    },
+].map(({ properties, required, description, ...tool }) => ({
+    ...tool,
+    description: `${description}. ${UNTRUSTED_EVENTS}`,
+    inputSchema: { type: "object", properties, required, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}));
+const argumentsOf = (name, input) => {
+    const tool = calendarTools.find((one) => one.name === name);
+    if (!tool)
+        throw new CliError("validation_error", "unknown calendar tool");
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        throw new CliError("validation_error", "expected argument object");
+    const args = input;
+    for (const key of Object.keys(args))
+        if (!Object.hasOwn(tool.inputSchema.properties, key))
+            throw new CliError("validation_error", `unknown argument: ${key}`);
+    for (const key of tool.inputSchema.required)
+        if (!Object.hasOwn(args, key))
+            throw new CliError("validation_error", `missing argument: ${key}`);
+    for (const [key, value] of Object.entries(args))
+        if (["account_id", "limit"].includes(key) &&
+            (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1))
+            throw new CliError("validation_error", `${key} must be a positive integer`);
+        else if (["words", "timezone", "event"].includes(key) && (typeof value !== "string" || !value.trim()))
+            throw new CliError("validation_error", `${key} must not be empty`);
+    return args;
+};
+/**
+ * Runs one calendar tool over the accounts the host serves. Without `account_id` a tool reads every one of them and
+ * names them in `accounts`; with one it must be among them.
+ */
+export const callCalendarTool = async (store, name, input, { accountIds, failure = {}, now = Date.now(), }) => {
+    try {
+        const args = argumentsOf(name, input);
+        const asked = args.account_id;
+        if (asked !== undefined && !accountIds.includes(asked))
+            throw new CliError("not_found", `no calendar account ${asked} here`);
+        const accounts = asked === undefined ? [...accountIds] : [asked];
+        const event = () => eventIdOf(args.event);
+        const eventIn = async () => {
+            for (const accountId of accounts)
+                try {
+                    return { accountId, details: await eventOf(store, accountId, event()) };
+                }
+                catch (error) {
+                    if (!isCliFailure(error) || error.code !== "not_found")
+                        throw error;
+                }
+            throw new CliError("not_found", `no event ${args.event} in ${asked === undefined ? "these accounts" : "this account"}`);
+        };
+        let answer;
+        switch (name) {
+            case "calendars_list":
+                answer = listed((await Promise.all(accounts.map((id) => store.calendars(id)))).flat().map(calendarItem));
+                break;
+            case "events_list": {
+                const words = typeof args.words === "string" ? args.words.trim().split(/\s+/u) : [];
+                const lists = await Promise.all(accounts.map(async (accountId) => (await eventsAnswer(store, await eventsFilter(words, {
+                    store,
+                    accountId,
+                    zone: args.timezone ?? "UTC",
+                    now,
+                }).then((filter) => filter && { ...filter, limit: args.limit ?? 100 }))).items));
+                const items = lists.flat().sort((a, b) => (a.starts_at ?? "").localeCompare(b.starts_at ?? ""));
+                answer = listed(items.slice(0, args.limit ?? 100));
+                break;
+            }
+            case "event_show":
+                answer = await eventAnswer((await eventIn()).details);
+                break;
+            case "event_people": {
+                const { accountId } = await eventIn();
+                answer = await peopleAnswer(store, accountId, { event: event() });
+                break;
+            }
+            default:
+                answer = await reviewsAnswer(store);
+        }
+        const result = { accounts, ...answer, untrusted: CALENDAR_UNTRUSTED_FIELDS };
+        return agentResult({
+            content: [{ type: "text", text: JSON.stringify(result) }],
+            structuredContent: result,
+        });
+    }
+    catch (error) {
+        const { content, structuredContent } = agentResult(mcpErrorResult(errorObjectOf(error, { ...failure, effects: { remote: "none", local: "read" } })));
+        return { content, structuredContent, isError: true };
+    }
+};

package/dist/calendar/reads.d.ts

@@ -0,0 +1,149 @@
+import { type EventDetails, type EventFilter, type EventStore, type StoredCalendar } from "../meetings/index.js";
+/** Who looks a person up: the shared store's `people.personOf`, for an attendee's `email` contact. */
+export type PersonOfEmail = (email: string) => Promise<string | null>;
+export declare const calendarItem: (one: StoredCalendar) => {
+    id: string;
+    external_id: string;
+    title: string | null;
+    timezone: string | null;
+    access_role: import("../meetings/event-store.js").CalendarAccessRole | null;
+    primary: boolean;
+    synced: boolean;
+    seen_at: string | null;
+};
+/** A stored calendar by its id or the provider's id, among the account's calendars. */
+export declare const calendarIn: (store: EventStore, accountId: number, reference: string) => Promise<StoredCalendar>;
+export declare const eventIdOf: (reference: string | number) => number;
+export declare const EVENTS_QUERY_HELP = "\nWords, any order:\n  today | week            today, or today and the next six days, in your time zone\n  from:<date> to:<date>   from the start of one day through the end of another (or a time with a zone)\n  person:<email|id>       events one person attends: an address, or a person id from search\n  calendar:<id>           one calendar, by its id or the provider's id\nWithout a time word: events from the start of today on.";
+/**
+ * `events list` words into a store filter, for one account. A person named by address is found through the shared
+ * store; one nobody knows matches no event.
+ */
+export declare const eventsFilter: (words: readonly string[], context: {
+    store: EventStore;
+    accountId: number;
+    zone: string;
+    now: number;
+    personOf?: (reference: string) => Promise<number | null>;
+}) => Promise<EventFilter | null>;
+/** An event the account holds, with only its copies, or `not_found`: another account's event is not shown. */
+export declare const eventOf: (store: EventStore, accountId: number, id: number) => Promise<EventDetails>;
+export declare const eventAnswer: (details: EventDetails, personOf?: PersonOfEmail) => Promise<{
+    id: string;
+    event_series_id: string | null;
+    title: string | null;
+    description: string | null;
+    location: string | null;
+    starts_at: string | null;
+    ends_at: string | null;
+    timezone: string | null;
+    origin: "auto" | "calendar" | "owner";
+    status: string | null;
+    all_day: boolean;
+    source_deleted_at: string | null;
+    deleted_at: string | null;
+    created_at: string;
+    updated_at: string;
+    ref: string;
+    entries: {
+        id: string;
+        calendar_id: string;
+        external_id: string;
+        kind: import("../meetings/event-store.js").EntryKind;
+        status: import("../meetings/event-store.js").EntryStatus;
+        event_type: import("../meetings/event-store.js").EntryEventType | null;
+        own_response: import("../meetings/event-store.js").ParticipantResponse | null;
+        starts_at: string | null;
+        ends_at: string | null;
+        join_url: string | null;
+        url: string | null;
+        deleted_at: string | null;
+    }[];
+    attendees: {
+        email: string;
+        name: string | null;
+        response: import("../meetings/event-store.js").ParticipantResponse | null;
+        organizer: boolean;
+        optional: boolean;
+        resource: boolean;
+        self: boolean;
+        person: string | null;
+    }[];
+    attachments: {
+        file_id: string;
+        title: string | null;
+        document: string | null;
+    }[];
+    history: {
+        title: string | null;
+        starts_at: string | null;
+        ends_at: string | null;
+        location: string | null;
+        status: string | null;
+        changed_at: string;
+    }[];
+}>;
+/** One event's attendees, or everyone attending the events of the filter, with how many of them each attends. */
+export declare const peopleAnswer: (store: EventStore, accountId: number, options: {
+    event?: number;
+    filter?: EventFilter;
+    personOf?: PersonOfEmail;
+}) => Promise<{
+    items: {
+        email: string;
+        name: string | null;
+        response: import("../meetings/event-store.js").ParticipantResponse | null;
+        organizer: boolean;
+        optional: boolean;
+        resource: boolean;
+        self: boolean;
+        person: string | null;
+    }[];
+    page: number;
+    limit: number;
+    hasMore: boolean;
+}>;
+/** Open link choices, with each candidate event's title and time so the owner can pick. */
+export declare const reviewsAnswer: (store: EventStore) => Promise<{
+    items: {
+        id: string;
+        entry_id: string;
+        reason: string;
+        candidates: {
+            ref: string;
+            title: string | null;
+            starts_at: string | null;
+        }[];
+    }[];
+    page: number;
+    limit: number;
+    hasMore: boolean;
+    accounts: string;
+}>;
+export declare const resolveAnswer: (store: EventStore, review: string, choice: string, now: number) => Promise<{
+    id: string;
+    status: "apart" | "linked" | "open";
+    chosen: string | null;
+}>;
+export declare const eventsAnswer: (store: EventStore, filter: EventFilter | null) => Promise<{
+    items: {
+        id: string;
+        event_series_id: string | null;
+        title: string | null;
+        description: string | null;
+        location: string | null;
+        starts_at: string | null;
+        ends_at: string | null;
+        timezone: string | null;
+        origin: "auto" | "calendar" | "owner";
+        status: string | null;
+        all_day: boolean;
+        source_deleted_at: string | null;
+        deleted_at: string | null;
+        created_at: string;
+        updated_at: string;
+    }[];
+    page: number;
+    limit: number;
+    hasMore: boolean;
+}>;

package/dist/calendar/reads.js

@@ -0,0 +1,214 @@
+import { CliError } from "@wirecat/cli-base";
+import { dayBoundary, zonedMoment } from "@wirecat/cli-base/query";
+import { eventItem, listed, } from "../meetings/index.js";
+const iso = (at) => (at === null ? null : new Date(at).toISOString());
+export const calendarItem = (one) => ({
+    id: String(one.id),
+    external_id: one.externalId,
+    title: one.title,
+    timezone: one.timezone,
+    access_role: one.accessRole,
+    primary: one.primary,
+    synced: one.synced,
+    seen_at: iso(one.seenAt),
+});
+/** A stored calendar by its id or the provider's id, among the account's calendars. */
+export const calendarIn = async (store, accountId, reference) => {
+    const calendars = await store.calendars(accountId);
+    const found = calendars.find((one) => String(one.id) === reference) ?? calendars.find((one) => one.externalId === reference);
+    if (!found)
+        throw new CliError("not_found", `no calendar ${reference} in this account; calendars list shows them`);
+    return found;
+};
+export const eventIdOf = (reference) => {
+    const text = String(reference).replace(/^event:/u, "");
+    if (!/^[1-9]\d*$/u.test(text) || !Number.isSafeInteger(Number(text)))
+        throw new CliError("validation_error", "an event is its id or event:<id>");
+    return Number(text);
+};
+const localDate = (at, zone) => new Intl.DateTimeFormat("en-CA", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit" }).format(at);
+const plusDays = (date, days) => {
+    const [year, month, day] = date.split("-").map(Number);
+    return new Date(Date.UTC(year, month - 1, day + days)).toISOString().slice(0, 10);
+};
+export const EVENTS_QUERY_HELP = `
+Words, any order:
+  today | week            today, or today and the next six days, in your time zone
+  from:<date> to:<date>   from the start of one day through the end of another (or a time with a zone)
+  person:<email|id>       events one person attends: an address, or a person id from search
+  calendar:<id>           one calendar, by its id or the provider's id
+Without a time word: events from the start of today on.`;
+/**
+ * `events list` words into a store filter, for one account. A person named by address is found through the shared
+ * store; one nobody knows matches no event.
+ */
+export const eventsFilter = async (words, context) => {
+    const filter = { accountId: context.accountId };
+    const today = localDate(context.now, context.zone);
+    const span = (text) => ({ start: 0, end: text.length });
+    const day = (date) => dayBoundary(date, context.zone, false, span(date));
+    let timed = false;
+    for (const word of words) {
+        const [, field, value = ""] = /^([a-z]+):(.+)$/u.exec(word) ?? [];
+        if (word === "today" || word === "week") {
+            filter.from = day(today);
+            filter.to = day(plusDays(today, word === "today" ? 1 : 7));
+            timed = true;
+        }
+        else if (field === "from") {
+            filter.from = zonedMoment(value, context.zone, span(value));
+            timed = true;
+        }
+        else if (field === "to") {
+            filter.to = zonedMoment(value, context.zone, span(value), { end: true }) + 1;
+            timed = true;
+        }
+        else if (field === "calendar")
+            filter.calendarId = (await calendarIn(context.store, context.accountId, value)).id;
+        else if (field === "person") {
+            if (!context.personOf)
+                throw new CliError("configuration_error", "this tool cannot look people up");
+            const person = await context.personOf(value);
+            if (person === null)
+                return null;
+            filter.personId = person;
+        }
+        else
+            throw new CliError("validation_error", `${word} is not an events list word${EVENTS_QUERY_HELP}`, {
+                reason: "query.unknown_word",
+            });
+    }
+    if (!timed)
+        filter.from = day(today);
+    return filter;
+};
+/**
+ * Only the account's own copies of an event, with their attendees, files and history. Rule 3 joins copies of one
+ * meeting across accounts into one event; the event's own fields (title, time) are shared, its copies are not.
+ */
+const ownCopies = (details, calendars) => {
+    const entries = details.entries.filter(({ calendarId }) => calendars.has(calendarId));
+    const ids = new Set(entries.map(({ id }) => id));
+    return {
+        event: details.event,
+        entries,
+        participants: details.participants.filter(({ entryId }) => ids.has(entryId)),
+        revisions: details.revisions.filter(({ entryId }) => ids.has(entryId)),
+        attachments: details.attachments.filter(({ entryId }) => ids.has(entryId)),
+    };
+};
+const calendarIds = async (store, accountId) => new Set((await store.calendars(accountId)).map(({ id }) => id));
+/** An event the account holds, with only its copies, or `not_found`: another account's event is not shown. */
+export const eventOf = async (store, accountId, id) => {
+    const details = await store.event(id);
+    const own = details && ownCopies(details, await calendarIds(store, accountId));
+    if (!own?.entries.length)
+        throw new CliError("not_found", `no event ${id} in this account`);
+    return own;
+};
+const attendees = async (participants, personOf) => {
+    const byEmail = new Map();
+    for (const one of participants)
+        if (!byEmail.has(one.email))
+            byEmail.set(one.email, one);
+    return Promise.all([...byEmail.values()].map(async (one) => ({
+        email: one.email,
+        name: one.name,
+        response: one.response,
+        organizer: one.organizer,
+        optional: one.optional,
+        resource: one.resource,
+        self: one.self,
+        person: one.resource || !personOf ? null : await personOf(one.email),
+    })));
+};
+export const eventAnswer = async (details, personOf) => ({
+    ...eventItem(details.event),
+    ref: `event:${details.event.id}`,
+    entries: details.entries.map((entry) => ({
+        id: String(entry.id),
+        calendar_id: String(entry.calendarId),
+        external_id: entry.externalId,
+        kind: entry.kind,
+        status: entry.status,
+        event_type: entry.eventType,
+        own_response: entry.ownResponse,
+        starts_at: iso(entry.startsAt),
+        ends_at: iso(entry.endsAt),
+        join_url: entry.joinUrl,
+        url: entry.url,
+        deleted_at: iso(entry.deletedAt),
+    })),
+    attendees: await attendees(details.participants, personOf),
+    attachments: details.attachments.map(({ fileId, title, documentId }) => ({
+        file_id: fileId,
+        title,
+        document: documentId === null ? null : `doc:${documentId}`,
+    })),
+    history: details.revisions.map((one) => ({
+        title: one.title,
+        starts_at: iso(one.startsAt),
+        ends_at: iso(one.endsAt),
+        location: one.location,
+        status: one.status,
+        changed_at: new Date(one.createdAt).toISOString(),
+    })),
+});
+/** One event's attendees, or everyone attending the events of the filter, with how many of them each attends. */
+export const peopleAnswer = async (store, accountId, options) => {
+    if (options.event !== undefined)
+        return listed(await attendees((await eventOf(store, accountId, options.event)).participants, options.personOf));
+    const counted = new Map();
+    const mine = await calendarIds(store, accountId);
+    for (const event of await store.events({ ...options.filter, accountId, limit: 1000 })) {
+        const details = await store.event(event.id);
+        const seen = new Set();
+        for (const one of details ? ownCopies(details, mine).participants : []) {
+            if (one.resource || one.self || seen.has(one.email))
+                continue;
+            seen.add(one.email);
+            const held = counted.get(one.email);
+            if (held)
+                held.events++;
+            else
+                counted.set(one.email, { participant: one, events: 1 });
+        }
+    }
+    const people = await attendees([...counted.values()].map(({ participant }) => participant), options.personOf);
+    return listed(people
+        .map((one) => ({ ...one, events: counted.get(one.email)?.events ?? 0 }))
+        .sort((a, b) => b.events - a.events || a.email.localeCompare(b.email)));
+};
+/** Open link choices, with each candidate event's title and time so the owner can pick. */
+export const reviewsAnswer = async (store) => {
+    const open = (await store.reviews({ status: "open" })).filter(({ linkableType }) => linkableType === "calendar_entry");
+    return {
+        ...listed(await Promise.all(open.map(async (review) => ({
+            id: String(review.id),
+            entry_id: String(review.linkableId),
+            reason: review.reason,
+            candidates: await Promise.all(review.candidates.map(async (id) => {
+                const event = review.entityType === "event" ? (await store.event(id))?.event : undefined;
+                return {
+                    ref: `event:${id}`,
+                    title: event?.title ?? null,
+                    starts_at: iso(event?.startsAt ?? null),
+                };
+            })),
+        })))),
+        // Link choices are kept per store, not per account, so every calendar account's are listed.
+        accounts: "all",
+    };
+};
+export const resolveAnswer = async (store, review, choice, now) => {
+    if (!/^[1-9]\d*$/u.test(review))
+        throw new CliError("validation_error", "a review is its id from links review");
+    const decision = choice === "apart" ? { apart: true } : { choose: eventIdOf(choice) };
+    const resolved = await store.resolveReview(Number(review), decision, now);
+    return {
+        id: String(resolved.id),
+        status: resolved.status,
+        chosen: resolved.chosenId === null ? null : `event:${resolved.chosenId}`,
+    };
+};
+export const eventsAnswer = async (store, filter) => listed(filter === null ? [] : (await store.events(filter)).map(eventItem));

package/dist/calendar/source.d.ts

@@ -0,0 +1,54 @@
+import type { CalendarInput, EntryInput, StoredCalendar } from "../meetings/index.js";
+/** Epoch milliseconds; `to` exclusive. */
+export interface SyncWindow {
+    from: number;
+    to: number;
+}
+export interface CalendarSourceTraits {
+    /**
+     * `on-request`: the engine asks `occurrences()` for each series (Google `events.instances`).
+     * `in-changes`: occurrences arrive in `changes()` (Graph `calendarView/delta`); no extra calls.
+     * `local`: the engine expands the RRULE lines with the expander it was given (ICS, CalDAV).
+     */
+    expands: "on-request" | "in-changes" | "local";
+    /** The cursor encodes the window (Graph delta): a new window means a new full round. */
+    cursorHoldsWindow: boolean;
+    /** No incremental cursor: every run is a full list (an ICS feed). */
+    fullListOnly: boolean;
+}
+export interface ChangePage {
+    entries: EntryInput[];
+    /**
+     * Entries the provider confirmed deleted, known only by `externalId` (CalDAV 404; Graph `@removed` that a GET by id
+     * answered 404). Never an entry that only left the window.
+     */
+    removed: string[];
+    /** More pages in this round. */
+    nextPage?: string;
+    /** On the last page: the cursor for the next run; `null` when the source has none. */
+    cursor?: string | null;
+}
+/** `reset`: the cursor is dead (Google 410, Graph `syncStateNotFound`, CalDAV `valid-sync-token`). */
+export type ChangeResult = ChangePage | {
+    reset: true;
+};
+/** One provider's calendars, as an adapter reads them. The engine never sees a provider word. */
+export interface CalendarSource {
+    /** The registry name: `google-calendar`, `outlook-calendar`, `caldav`, `ics`. */
+    readonly provider: string;
+    readonly traits: CalendarSourceTraits;
+    calendars(): Promise<CalendarInput[]>;
+    /** `cursor: null` asks for a full list of the window. */
+    changes(calendar: StoredCalendar, request: {
+        cursor: string | null;
+        page?: string;
+        window: SyncWindow;
+    }): Promise<ChangeResult>;
+    /** Required when `traits.expands` is `on-request`: the series' slots inside the window. */
+    occurrences?(calendar: StoredCalendar, seriesExternalId: string, window: SyncWindow): Promise<EntryInput[]>;
+}
+/**
+ * Core expansion for `expands: "local"`: a series' slots inside the window, as occurrences. A slot its EXDATE lines
+ * remove is returned `cancelled`, so a stored slot is cancelled rather than left behind.
+ */
+export type CalendarExpander = (series: EntryInput, window: SyncWindow) => EntryInput[] | Promise<EntryInput[]>;

package/dist/calendar/source.js

@@ -0,0 +1 @@
+export {};

package/dist/calendar/sync.d.ts

@@ -0,0 +1,65 @@
+import type { EventStore } from "../meetings/index.js";
+import type { CalendarExpander, CalendarSource, SyncWindow } from "./source.js";
+/** What the engine keeps in `EventStore.cursor`: the provider's token, the window it covers, the last full round. */
+export interface CalendarCursor {
+    v: 1;
+    token: string | null;
+    window: SyncWindow;
+    fullAt: number;
+}
+export declare const parseCalendarCursor: (value: string | null) => CalendarCursor | null;
+/**
+ * One year back and three months ahead (NEED-1706), from the start of today in UTC. Whole days, so the window moves
+ * once a day: a source whose cursor holds the window lists everything again once a day, not on every run.
+ */
+export declare const calendarSyncWindow: (now: number) => SyncWindow;
+export interface CalendarSyncOptions {
+    /** The calendar account; never a default. */
+    accountId: number;
+    now?: number;
+    /** List every synced calendar's window again instead of reading changes. */
+    full?: boolean;
+    /** Instead of `calendarSyncWindow(now)`. */
+    window?: SyncWindow;
+    /** Required for a source with `expands: "local"`. */
+    expand?: CalendarExpander;
+}
+export interface CalendarSyncResult {
+    calendarId: number;
+    externalId: string;
+    title: string | null;
+    /** `full`: the whole window was listed and entries it did not return were marked; `changes`: only what changed. */
+    round: "full" | "changes";
+    /** The cursor was dead, so the round became a full one. */
+    reset: boolean;
+    saved: number;
+    removed: number;
+    occurrences: number;
+    /** Entries a full round did not return, now marked deleted. */
+    unseen: number;
+    /** Set when the calendar failed; its cursor stays where it was, so the next run retries the same changes. */
+    error?: string;
+}
+export interface CalendarSyncReport {
+    provider: string;
+    accountId: number;
+    window: SyncWindow;
+    /** Calendars the provider listed. */
+    calendars: number;
+    synced: CalendarSyncResult[];
+    /** Listed calendars the owner does not sync (`calendars sync <id>` turns one on). */
+    notSynced: {
+        calendarId: number;
+        externalId: string;
+        title: string | null;
+    }[];
+    /** Every synced calendar finished. */
+    complete: boolean;
+}
+/**
+ * Brings one calendar account's synced calendars up to date (foundation §6.2): the calendar list first, then for
+ * each synced calendar its changes since the cursor, or a full list of the window, then the slots of the series that
+ * changed. Each calendar's cursor is saved last, only when all of it saved; a calendar that fails keeps its old one
+ * and the others go on.
+ */
+export declare const syncCalendars: (source: CalendarSource, store: EventStore, options: CalendarSyncOptions) => Promise<CalendarSyncReport>;