@wirecat/cli-core 0.538.0 → 0.540.0

package/dist/calendar/ics.js

@@ -0,0 +1,314 @@
+import { CliError } from "@wirecat/cli-base";
+import { zonedMoment } from "@wirecat/cli-base/query";
+const CRLF = "\r\n";
+const LINE_OCTETS = 75;
+const escapeText = (text) => text
+    .replace(/\\/gu, "\\\\")
+    .replace(/;/gu, "\\;")
+    .replace(/,/gu, "\\,")
+    .replace(/\r\n|\r|\n/gu, "\\n");
+/** A parameter value: quoted when it holds `:`, `;` or `,`; a double quote cannot be written in one, so it goes. */
+const paramValue = (text) => {
+    const clean = text.replace(/["\r\n]/gu, "");
+    return /[:;,]/u.test(clean) ? `"${clean}"` : clean;
+};
+/** Lines longer than 75 octets go on under a leading space, never splitting a character's UTF-8 bytes. */
+export const foldLine = (line) => {
+    const parts = [];
+    let current = "";
+    let octets = 0;
+    for (const char of line) {
+        const size = Buffer.byteLength(char, "utf8");
+        const room = parts.length === 0 ? LINE_OCTETS : LINE_OCTETS - 1;
+        if (octets + size > room) {
+            parts.push(current);
+            current = "";
+            octets = 0;
+        }
+        current += char;
+        octets += size;
+    }
+    parts.push(current);
+    return parts.join(`${CRLF} `);
+};
+const pad = (value) => String(value).padStart(2, "0");
+const utcStamp = (at) => {
+    const date = new Date(at);
+    return (`${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}T` +
+        `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}Z`);
+};
+const dateValue = (date) => date.replaceAll("-", "");
+const PARTSTAT = {
+    "needs-action": "NEEDS-ACTION",
+    accepted: "ACCEPTED",
+    tentative: "TENTATIVE",
+    declined: "DECLINED",
+    delegated: "DELEGATED",
+};
+const eventLines = (event, stamp) => {
+    const lines = ["BEGIN:VEVENT", `UID:${escapeText(event.uid)}`, `DTSTAMP:${stamp}`];
+    if (event.startDate !== undefined && event.endDate !== undefined)
+        lines.push(`DTSTART;VALUE=DATE:${dateValue(event.startDate)}`, `DTEND;VALUE=DATE:${dateValue(event.endDate)}`);
+    else if (event.startsAt !== undefined)
+        lines.push(`DTSTART:${utcStamp(event.startsAt)}`, `DTEND:${utcStamp(event.endsAt ?? event.startsAt)}`);
+    if (event.title)
+        lines.push(`SUMMARY:${escapeText(event.title)}`);
+    if (event.description)
+        lines.push(`DESCRIPTION:${escapeText(event.description)}`);
+    if (event.location)
+        lines.push(`LOCATION:${escapeText(event.location)}`);
+    for (const rule of event.recurrence ?? [])
+        lines.push(rule);
+    if (event.status)
+        lines.push(`STATUS:${event.status.toUpperCase()}`);
+    if (event.transparency)
+        lines.push(`TRANSP:${event.transparency.toUpperCase()}`);
+    if (event.organizer)
+        lines.push(`ORGANIZER${event.organizer.name ? `;CN=${paramValue(event.organizer.name)}` : ""}:mailto:${event.organizer.email}`);
+    for (const one of event.attendees ?? []) {
+        const params = [
+            ...(one.name ? [`CN=${paramValue(one.name)}`] : []),
+            ...(one.response ? [`PARTSTAT=${PARTSTAT[one.response]}`] : []),
+            ...(one.optional ? ["ROLE=OPT-PARTICIPANT"] : []),
+        ];
+        lines.push(`ATTENDEE${params.map((param) => `;${param}`).join("")}:mailto:${one.email}`);
+    }
+    if (event.url)
+        lines.push(`URL:${event.url}`);
+    lines.push("END:VEVENT");
+    return lines;
+};
+/** One VCALENDAR holding the events, CRLF line ends and folded lines, as RFC 5545 §3.1 asks. */
+export const writeIcs = (events, options) => [
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    `PRODID:-//WireCat//${options.product.replace(/[^\w .-]/gu, "")}//EN`,
+    "CALSCALE:GREGORIAN",
+    ...events.flatMap((event) => eventLines(event, utcStamp(options.now))),
+    "END:VCALENDAR",
+]
+    .map(foldLine)
+    .join(CRLF)
+    .concat(CRLF);
+const contentLine = (line) => {
+    let at = 0;
+    let quoted = false;
+    for (; at < line.length; at++) {
+        const char = line[at];
+        if (char === '"')
+            quoted = !quoted;
+        else if (char === ":" && !quoted)
+            break;
+    }
+    if (at === line.length)
+        return null;
+    const head = line.slice(0, at);
+    const parts = [];
+    let part = "";
+    quoted = false;
+    for (const char of head) {
+        if (char === '"')
+            quoted = !quoted;
+        if (char === ";" && !quoted) {
+            parts.push(part);
+            part = "";
+        }
+        else
+            part += char;
+    }
+    parts.push(part);
+    const [name = "", ...rest] = parts;
+    const params = {};
+    for (const param of rest) {
+        const equals = param.indexOf("=");
+        if (equals > 0)
+            params[param.slice(0, equals).toUpperCase()] = param.slice(equals + 1).replace(/^"|"$/gu, "");
+    }
+    return { name: name.toUpperCase(), params, value: line.slice(at + 1) };
+};
+const unescapeText = (text) => text.replace(/\\([\\;,nN])/gu, (_match, char) => (char === "n" || char === "N" ? "\n" : char));
+const DATE = /^(\d{4})(\d{2})(\d{2})$/u;
+const DATE_TIME = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z?)$/u;
+/** A DATE or DATE-TIME: UTC with `Z`, in its TZID, or floating, read in `zone`. */
+const momentOf = (line, zone) => {
+    const value = line.value.trim();
+    const date = DATE.exec(value);
+    if (date || line.params.VALUE === "DATE") {
+        if (!date)
+            throw new Error(`${line.name} ${value} is not a date`);
+        return { date: `${date[1]}-${date[2]}-${date[3]}` };
+    }
+    const time = DATE_TIME.exec(value);
+    if (!time)
+        throw new Error(`${line.name} ${value} is not a date or a time`);
+    const [, year, month, day, hour, minute, second, utc] = time;
+    const local = `${year}-${month}-${day}T${hour}:${minute}:${second}`;
+    if (utc)
+        return { at: Date.parse(`${local}Z`), zone: "UTC" };
+    const named = line.params.TZID;
+    const where = named ?? zone;
+    try {
+        return { at: zonedMoment(local, where, { start: 0, end: local.length }), zone: where };
+    }
+    catch {
+        throw new Error(`${line.name} names the time zone ${where}, which is not an IANA zone such as Europe/Madrid`);
+    }
+};
+const DURATION = /^([+-])?P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/u;
+const durationMs = (text) => {
+    const found = DURATION.exec(text.trim());
+    if (!found || found[1] === "-")
+        throw new Error(`DURATION ${text} is not a length of time`);
+    const [, , weeks, days, hours, minutes, seconds] = found.map((one) => Number(one ?? 0));
+    return ((((weeks * 7 + days) * 24 + hours) * 60 + minutes) * 60_000 +
+        seconds * 1000);
+};
+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);
+};
+const STATUS = { CONFIRMED: "confirmed", TENTATIVE: "tentative", CANCELLED: "cancelled" };
+const RESPONSE = {
+    "NEEDS-ACTION": "needs-action",
+    ACCEPTED: "accepted",
+    TENTATIVE: "tentative",
+    DECLINED: "declined",
+    DELEGATED: "delegated",
+};
+const emailOf = (value) => {
+    const email = value
+        .trim()
+        .replace(/^mailto:/iu, "")
+        .toLowerCase();
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(email) ? email : null;
+};
+const eventOf = (lines, zone) => {
+    const one = (name) => lines.find((line) => line.name === name);
+    const uid = one("UID")?.value.trim();
+    if (!uid)
+        throw new Error("the event has no UID");
+    if (one("RECURRENCE-ID"))
+        throw new Error("a changed occurrence of a repeating event (RECURRENCE-ID) is not imported on its own");
+    const startLine = one("DTSTART");
+    if (!startLine)
+        throw new Error("the event has no DTSTART");
+    const start = momentOf(startLine, zone);
+    const endLine = one("DTEND");
+    const duration = one("DURATION");
+    const text = (name) => {
+        const found = one(name);
+        return found ? unescapeText(found.value) : null;
+    };
+    const event = { uid, title: text("SUMMARY") };
+    if ("date" in start) {
+        const end = endLine ? momentOf(endLine, zone) : undefined;
+        if (end && !("date" in end))
+            throw new Error("DTSTART is a date and DTEND a time");
+        event.startDate = start.date;
+        event.endDate =
+            end?.date ?? plusDays(start.date, duration ? Math.max(1, Math.ceil(durationMs(duration.value) / 86_400_000)) : 1);
+        if (event.endDate <= event.startDate)
+            throw new Error("the event ends before it starts");
+    }
+    else {
+        const end = endLine ? momentOf(endLine, zone) : undefined;
+        if (end && "date" in end)
+            throw new Error("DTSTART is a time and DTEND a date");
+        event.startsAt = start.at;
+        event.endsAt = end?.at ?? start.at + (duration ? durationMs(duration.value) : 0);
+        event.timezone = start.zone;
+        if (event.endsAt < event.startsAt)
+            throw new Error("the event ends before it starts");
+    }
+    const description = text("DESCRIPTION");
+    if (description)
+        event.description = description;
+    const location = text("LOCATION");
+    if (location)
+        event.location = location;
+    const recurrence = lines
+        .filter(({ name }) => ["RRULE", "RDATE", "EXDATE"].includes(name))
+        .map(({ name, params, value }) => {
+        const kept = Object.entries(params).map(([key, param]) => `;${key}=${paramValue(param)}`);
+        return `${name}${kept.join("")}:${value.trim()}`;
+    });
+    if (recurrence.length)
+        event.recurrence = recurrence;
+    const status = STATUS[one("STATUS")?.value.trim().toUpperCase() ?? ""];
+    if (status)
+        event.status = status;
+    const transparency = one("TRANSP")?.value.trim().toUpperCase();
+    if (transparency === "TRANSPARENT" || transparency === "OPAQUE")
+        event.transparency = transparency === "TRANSPARENT" ? "transparent" : "opaque";
+    const organizerLine = one("ORGANIZER");
+    const organizer = organizerLine && emailOf(organizerLine.value);
+    if (organizerLine && organizer)
+        event.organizer = { email: organizer, name: organizerLine.params.CN ?? null };
+    const attendees = lines
+        .filter(({ name }) => name === "ATTENDEE")
+        .flatMap(({ params, value }) => {
+        const email = emailOf(value);
+        if (!email)
+            return [];
+        return [
+            {
+                email,
+                name: params.CN ?? null,
+                response: RESPONSE[(params.PARTSTAT ?? "").toUpperCase()] ?? null,
+                optional: (params.ROLE ?? "").toUpperCase() === "OPT-PARTICIPANT",
+            },
+        ];
+    });
+    if (attendees.length)
+        event.attendees = attendees;
+    const url = one("URL")?.value.trim();
+    if (url)
+        event.url = url;
+    return event;
+};
+/**
+ * The VEVENTs of an iCalendar text; times with neither `Z` nor a TZID are read in `zone`. An event that cannot be
+ * imported alone is in `skipped` with the reason; a text with no VCALENDAR is refused.
+ */
+export const readIcs = (text, zone) => {
+    const unfolded = text.replace(/^\uFEFF/u, "").replace(/\r?\n[ \t]/gu, "");
+    const lines = unfolded.split(/\r?\n/u).filter((line) => line.trim() !== "");
+    if (!/^BEGIN:VCALENDAR$/iu.test(lines[0]?.trim() ?? ""))
+        throw new CliError("validation_error", "the file is not iCalendar: it does not start with BEGIN:VCALENDAR", {
+            reason: "ics.not-icalendar",
+        });
+    const events = [];
+    const skipped = [];
+    let held = null;
+    // Components inside a VEVENT, such as VALARM, are passed over whole.
+    let inner = 0;
+    for (const raw of lines) {
+        const line = contentLine(raw);
+        if (!line)
+            continue;
+        const value = line.value.trim().toUpperCase();
+        if (line.name === "BEGIN" && value === "VEVENT" && held === null) {
+            held = [];
+            continue;
+        }
+        if (held === null)
+            continue;
+        if (line.name === "BEGIN")
+            inner++;
+        else if (line.name === "END" && inner > 0)
+            inner--;
+        else if (line.name === "END" && value === "VEVENT") {
+            try {
+                events.push(eventOf(held, zone));
+            }
+            catch (error) {
+                const uid = held.find(({ name }) => name === "UID")?.value.trim() || null;
+                skipped.push({ uid, reason: error instanceof Error ? error.message : String(error) });
+            }
+            held = null;
+        }
+        else if (inner === 0)
+            held.push(line);
+    }
+    return { events, skipped };
+};

package/dist/calendar/index.d.ts

@@ -1,4 +1,5 @@
 export type { CalendarAccessRole, CalendarInput, EntryAttachment, EntryAttachmentInput, EntryEventType, EntryInput, EntryKind, EntryParticipantInput, EntryRevision, EntryStatus, EntryTransparency, EntryVisibility, EventDetails, EventFilter, EventStore, LinkReview, ParticipantResponse, ReviewDecision, StoredCalendar, StoredEntry, StoredParticipant, } from "../meetings/index.js";
+export { type IcsEvent, type IcsSkip, readIcs, writeIcs } from "./ics.js";
 export { repeatRule } from "./recurrence.js";
 export type { BusyTimes, CalendarExpander, CalendarSource, CalendarSourceTraits, ChangePage, ChangeResult, FreeBusyRequest, SearchPage, SyncWindow, } from "./source.js";
 export { type CalendarCursor, type CalendarSyncOptions, type CalendarSyncReport, type CalendarSyncResult, calendarStatus, calendarSyncWindow, type PendingRound, parseCalendarCursor, syncCalendars, } from "./sync.js";

package/dist/calendar/index.js

@@ -1,3 +1,4 @@
+export { readIcs, writeIcs } from "./ics.js";
 export { repeatRule } from "./recurrence.js";
 export { calendarStatus, calendarSyncWindow, parseCalendarCursor, syncCalendars, } from "./sync.js";
 export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, } from "./writer.js";

package/dist/calendar/mcp/index.js

@@ -30,7 +30,8 @@ export const calendarTools = [
         name: "events_list",
         description: "stored events, earliest first; `query` takes field terms joined by AND: starts_at (>=, <, or " +
             "[a TO b}), ends_at>=, changed_at>= (events new, moved or cancelled since, each with change and was), " +
-            "overlapping:true (timed events that clash, each with overlaps), calendar:<id>; a date in the zone given, " +
+            "overlapping:true (timed events that clash, each with overlaps), calendar:<id>, event_type:<kind>, and " +
+            "-event_type:<kind> to leave one kind out; a date in the zone given, " +
             "UTC when absent; without starts_at or ends_at, from today on",
         properties: {
             account_id: integer,

package/dist/calendar/prepare.d.ts

@@ -126,6 +126,8 @@ export declare const eventPreparation: (details: EventDetails, options: Preparat
         }[] | undefined;
         truncated?: boolean | undefined;
         timezone?: string | undefined;
+        now?: string | undefined;
+        now_local?: string | undefined;
         window?: {
             since?: string | undefined;
             until?: string | undefined;

package/dist/calendar/reads.d.ts

@@ -1,7 +1,7 @@
 import { type Predicate, type QueryRegistry } from "@wirecat/cli-base/query";
 import type { Issue, Meta } from "@wirecat/cli-base/standards";
 import { type QueryWords } from "../cli/list-query.js";
-import { type EventDetails, type EventFilter, type EventStore, type StoredCalendar, type StoredEntry } from "../meetings/index.js";
+import { type EntryEventType, type EventDetails, type EventFilter, type EventStore, type StoredCalendar, type StoredEntry } from "../meetings/index.js";
 import type { AccountKey, MessageStore } from "../store/store.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>;
@@ -17,10 +17,12 @@ export declare const calendarItem: (one: StoredCalendar) => {
     synced: boolean;
     seen_at: string | null;
 };
-/** A stored calendar by its id or the provider's id, among the account's calendars. */
+/** A stored calendar of the account by its id, the provider's id, or its title when only one has it. */
 export declare const calendarIn: (store: EventStore, accountId: number, reference: string) => Promise<StoredCalendar>;
 export declare const eventIdOf: (reference: string | number) => number;
 export declare const plusDays: (date: string, days: number) => string;
+/** The kinds a calendar entry is stored as (`EntryEventType`); a copy with none is `default`. */
+export declare const EVENT_TYPES: readonly EntryEventType[];
 /** `events list`'s query. The store answers `ends_at` and `changed_at` from below only; `starts_at` either way. */
 export declare const EVENTS_QUERY: QueryRegistry;
 export declare const EVENTS_QUERY_NOTE: string;
@@ -53,7 +55,7 @@ export declare const entryItem: (entry: StoredEntry) => {
     kind: import("../meetings/event-store.js").EntryKind;
     title: string | null;
     status: import("../meetings/event-store.js").EntryStatus;
-    event_type: import("../meetings/event-store.js").EntryEventType | null;
+    event_type: EntryEventType | null;
     own_response: import("../meetings/event-store.js").ParticipantResponse | null;
     starts_at: string | null;
     ends_at: string | null;
@@ -94,7 +96,7 @@ export declare const eventAnswer: (details: EventDetails, personOf?: PersonOfEma
         kind: import("../meetings/event-store.js").EntryKind;
         title: string | null;
         status: import("../meetings/event-store.js").EntryStatus;
-        event_type: import("../meetings/event-store.js").EntryEventType | null;
+        event_type: EntryEventType | null;
         own_response: import("../meetings/event-store.js").ParticipantResponse | null;
         starts_at: string | null;
         ends_at: string | null;
@@ -238,3 +240,14 @@ export declare const sourceAccounts: (messages: MessageStore, running: AccountKe
  * calendar, or a calendar whose sync never finished or is in the middle of a round, so its events may be missing.
  */
 export declare const accountsMeta: (store: EventStore, accounts: readonly ReadAccount[], skipped: readonly Issue[], now: number) => Promise<Pick<Meta, "accounts" | "complete" | "issues">>;
+/** The most events one `events export` writes: what the store reads in one go. */
+export declare const EXPORT_MAX = 1000;
+/** The events of a filter as one iCalendar text; a filter that finds more than `EXPORT_MAX` is refused. */
+export declare const eventsIcs: (store: EventStore, accountId: number, filter: EventFilter | null, options: {
+    now: number;
+    product: string;
+}) => Promise<{
+    format: "ics";
+    events: number;
+    content: string;
+}>;

package/dist/calendar/reads.js

@@ -1,9 +1,10 @@
 import { CliError } from "@wirecat/cli-base";
 import { dateRange, dayBoundary, queryError, queryFieldsOf, } from "@wirecat/cli-base/query";
-import { LIST_QUERY_GUIDE, listQuery, nativeTerms, typedQuery } from "../cli/list-query.js";
+import { LIST_QUERY_GUIDE, listQuery, nativeTermLists, negatableOf, typedQuery, } from "../cli/list-query.js";
 import { event, eventChange, eventItem, listed, } from "../meetings/index.js";
 import { entriesOfList, fitting } from "../search/account-list.js";
 import { listContextOf } from "../services/search-kind.js";
+import { writeIcs } from "./ics.js";
 import { calendarStatus } from "./sync.js";
 const iso = (at) => (at === null ? null : new Date(at).toISOString());
 /** Fields whose text whoever sent the invitation wrote: an agent reads them as data. */
@@ -30,30 +31,33 @@ export const calendarItem = (one) => ({
     synced: one.synced,
     seen_at: iso(one.seenAt),
 });
-/** A stored calendar by its id or the provider's id, among the accounts' calendars; one the id names twice is refused. */
-const calendarAmong = async (store, accountIds, reference) => {
-    if (accountIds.length === 1)
-        return calendarIn(store, accountIds[0], reference);
-    const calendars = (await Promise.all(accountIds.map((id) => store.calendars(id)))).flat();
+const sameTitle = (one, reference) => one.title !== null && one.title.trim().toLocaleLowerCase() === reference.trim().toLocaleLowerCase();
+/**
+ * A calendar by its id, then the provider's id, then its title, case aside. Two calendars may share a title, a shared
+ * one beside the owner's own: such a title is refused with their ids, never one of them picked.
+ */
+const calendarOfList = (calendars, reference, where) => {
     const byId = calendars.find((one) => String(one.id) === reference);
     if (byId)
         return byId;
     const byExternal = calendars.filter((one) => one.externalId === reference);
-    if (byExternal.length > 1)
-        throw new CliError("validation_error", `calendar ${reference} is in more than one of these accounts; name it by its id: ` +
-            byExternal.map(({ id }) => id).join(", "));
-    if (!byExternal[0])
-        throw new CliError("not_found", `no calendar ${reference} in these accounts`);
-    return byExternal[0];
+    const found = byExternal.length ? byExternal : calendars.filter((one) => sameTitle(one, reference));
+    if (found.length > 1)
+        throw new CliError("validation_error", `calendar ${reference} names ${found.length} calendars ${where}; name one by its id: ` +
+            found.map(({ id, title }) => (title === null ? String(id) : `${id} (${title})`)).join(", "), { reason: "calendar.ambiguous", candidates: found.map(({ id }) => String(id)) });
+    if (!found[0])
+        throw new CliError("not_found", `no calendar ${reference} ${where}; calendars list shows them`);
+    return found[0];
 };
-/** 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;
+/** A stored calendar among the accounts' calendars, as `calendarIn` finds one. */
+const calendarAmong = async (store, accountIds, reference) => {
+    if (accountIds.length === 1)
+        return calendarIn(store, accountIds[0], reference);
+    const calendars = (await Promise.all(accountIds.map((id) => store.calendars(id)))).flat();
+    return calendarOfList(calendars, reference, "in these accounts");
 };
+/** A stored calendar of the account by its id, the provider's id, or its title when only one has it. */
+export const calendarIn = async (store, accountId, reference) => calendarOfList(await store.calendars(accountId), reference, "in this account");
 export const eventIdOf = (reference) => {
     const text = String(reference).replace(/^event:/u, "");
     if (!/^[1-9]\d*$/u.test(text) || !Number.isSafeInteger(Number(text)))
@@ -66,6 +70,15 @@ export const plusDays = (date, days) => {
     return new Date(Date.UTC(year, month - 1, day + days)).toISOString().slice(0, 10);
 };
 const LIST = "events list";
+/** The kinds a calendar entry is stored as (`EntryEventType`); a copy with none is `default`. */
+export const EVENT_TYPES = [
+    "default",
+    "out-of-office",
+    "focus",
+    "working-location",
+    "birthday",
+    "from-mail",
+];
 const oneSided = (field, example) => (node) => {
     if (node.operator !== "range" || node.upper !== "*")
         queryError("query.unsupported-operator", node.span, `${field} takes only an earliest moment, such as ${example}`, {
@@ -78,9 +91,20 @@ export const EVENTS_QUERY = {
     entity: "event",
     backend: "native",
     fields: queryFieldsOf(event, {
-        native: ["starts_at", "ends_at", "changed_at", "overlapping", "calendar", "person"],
+        native: ["id", "starts_at", "ends_at", "changed_at", "overlapping", "calendar", "person", "event_type"],
+        negatable: ["event_type"],
         relations: {
-            calendar: { type: "kw", example: "calendar:3", relation: "one calendar, by its id or the provider's id" },
+            event_type: {
+                type: "enum",
+                values: EVENT_TYPES,
+                example: "event_type:default",
+                relation: "events with a copy of this kind; -event_type:<kind> leaves out events with one",
+            },
+            calendar: {
+                type: "kw",
+                example: "calendar:3",
+                relation: "one calendar, by its id, the provider's id or its title",
+            },
             person: {
                 type: "kw",
                 example: "person:ana@example.com",
@@ -88,6 +112,7 @@ export const EVENTS_QUERY = {
             },
         },
         examples: {
+            id: "id:42",
             starts_at: "starts_at:[2026-11-02 TO 2026-11-07}",
             ends_at: "ends_at>=2026-11-02",
             changed_at: "changed_at>=2026-10-01",
@@ -108,9 +133,9 @@ export const EVENTS_QUERY = {
         }
         : field),
 };
-export const EVENTS_QUERY_NOTE = "\nends_at keeps events that end after its moment, so one that ends exactly then is left out. Without starts_at " +
-    "or ends_at: events that end after the start of today, in your time zone.\noverlapping:true keeps timed events " +
-    "that overlap another in the accounts read, each with overlaps: the others. Left out: all-day, cancelled, " +
+export const EVENTS_QUERY_NOTE = "\nends_at keeps events that end after its moment, so one that ends exactly then is left out. Without id, " +
+    "starts_at or ends_at: events that end after the start of today, in your time zone.\noverlapping:true keeps timed " +
+    "events that overlap another in the accounts read, each with overlaps: the others. Left out: all-day, cancelled, " +
     "declined and free events and working-location blocks; back-to-back events do not overlap.";
 /** A time term as epoch ms: from `lower` on, and before `upper`. */
 export const timeWindow = (node, zone, now) => {
@@ -132,8 +157,20 @@ export const eventsFilter = async (query, context) => {
     const { zone, now } = context;
     const span = (text) => ({ start: 0, end: text.length });
     const day = (date) => dayBoundary(date, zone, false, span(date));
-    for (const [field, node] of nativeTerms(listQuery(typedQuery(query), EVENTS_QUERY, LIST), LIST)) {
-        if (field === "starts_at") {
+    const terms = nativeTermLists(listQuery(typedQuery(query), EVENTS_QUERY, LIST), LIST, [], negatableOf(EVENTS_QUERY));
+    const kinds = (nodes = []) => nodes.map(({ value }) => value.toLowerCase());
+    const excluded = kinds(terms.get("-event_type"));
+    if (excluded.length)
+        filter.notEventTypes = [...new Set(excluded)];
+    for (const [field, nodes] of terms) {
+        const node = nodes[0];
+        if (field === "-event_type")
+            continue;
+        if (field === "event_type")
+            filter.eventType = kinds(nodes)[0];
+        else if (field === "id")
+            filter.id = eventIdOf(node.value);
+        else if (field === "starts_at") {
             const { lower, upper } = timeWindow(node, zone, now);
             if (lower !== undefined)
                 filter.startsFrom = lower;
@@ -165,7 +202,11 @@ export const eventsFilter = async (query, context) => {
             filter.personId = person;
         }
     }
-    if (filter.from === undefined && filter.startsFrom === undefined && filter.to === undefined)
+    // One event named by its id is found whenever it is.
+    if (filter.id === undefined &&
+        filter.from === undefined &&
+        filter.startsFrom === undefined &&
+        filter.to === undefined)
         filter.from = day(localDate(now, zone));
     return datedFilter(filter, zone);
 };
@@ -436,3 +477,51 @@ export const accountsMeta = async (store, accounts, skipped, now) => {
         ...(issues.length ? { issues } : {}),
     };
 };
+/** The most events one `events export` writes: what the store reads in one go. */
+export const EXPORT_MAX = 1000;
+const stampOf = (at) => new Date(at)
+    .toISOString()
+    .replace(/[-:]/gu, "")
+    .replace(/\.\d{3}/u, "");
+/**
+ * One event as iCalendar, from its first live copy in the account. An occurrence of a repeating event is written as
+ * an event of its own, its UID the series' with its slot after it, so a file never holds two events with one UID.
+ */
+const icsEventOf = (details) => {
+    const entry = details.entries.find((one) => one.deletedAt === null) ?? details.entries[0];
+    const { event } = details;
+    const participants = details.participants.filter(({ entryId }) => entryId === entry.id);
+    const organizer = participants.find((one) => one.organizer);
+    const slot = entry.originalStartsAt ?? entry.startsAt;
+    const uid = entry.kind === "occurrence" && slot !== null
+        ? `${entry.icalUid ?? entry.seriesExternalId ?? entry.externalId}_${stampOf(slot)}`
+        : (entry.icalUid ?? entry.externalId);
+    const times = event.allDay && entry.startDate !== null && entry.endDate !== null
+        ? { startDate: entry.startDate, endDate: entry.endDate }
+        : event.startsAt === null
+            ? {}
+            : { startsAt: event.startsAt, endsAt: event.endsAt ?? event.startsAt };
+    return {
+        uid,
+        title: event.title,
+        description: event.description,
+        location: event.location,
+        ...times,
+        status: entry.status,
+        transparency: entry.transparency,
+        organizer: organizer ? { email: organizer.email, name: organizer.name } : null,
+        attendees: participants
+            .filter((one) => !one.organizer)
+            .map(({ email, name, response, optional }) => ({ email, name, response, optional })),
+    };
+};
+/** The events of a filter as one iCalendar text; a filter that finds more than `EXPORT_MAX` is refused. */
+export const eventsIcs = async (store, accountId, filter, options) => {
+    const { rows, hasMore } = filter === null ? { rows: [], hasMore: false } : await page(store, { ...filter, limit: EXPORT_MAX, offset: 0 });
+    if (hasMore)
+        throw new CliError("validation_error", `the query finds more than ${EXPORT_MAX} events; narrow it, such as with starts_at:[2026-11-01 TO 2026-12-01}`, { reason: "export.too-many" });
+    const events = [];
+    for (const row of rows)
+        events.push(icsEventOf(await eventOf(store, accountId, row.id)));
+    return { format: "ics", events: events.length, content: writeIcs(events, options) };
+};

package/dist/calendar/testing/memory.js

@@ -489,8 +489,13 @@ export const memoryEventStore = () => {
                     (event.allDay && filter.startsFromDate !== undefined
                         ? has(event, (one) => one.startDate !== null && one.startDate >= (filter.startsFromDate ?? ""))
                         : event.startsAt !== null && event.startsAt >= filter.startsFrom)) &&
+                (filter.id === undefined || event.id === filter.id) &&
                 (filter.calendarId === undefined || has(event, (one) => one.calendarId === filter.calendarId)) &&
                 (accounts === undefined || has(event, inAccounts)) &&
+                (filter.eventType === undefined ||
+                    has(event, (one) => inAccounts(one) && (one.eventType ?? "default") === filter.eventType)) &&
+                (!filter.notEventTypes?.length ||
+                    !has(event, (one) => inAccounts(one) && (filter.notEventTypes ?? []).includes(one.eventType ?? "default"))) &&
                 (filter.personId === undefined ||
                     has(event, (one) => participants.some((p) => p.entryId === one.id && p.identityId === filter.personId))) &&
                 (filter.changedSince === undefined ||

package/dist/calendar/testing/writer.d.ts

@@ -1,7 +1,7 @@
 import type { EntryInput } from "../../meetings/index.js";
 import { type CalendarWriter } from "../writer.js";
 export interface FakeCalendarWriterCall {
-    write: "create" | "update" | "remove" | "respond" | "move";
+    write: "create" | "quick-add" | "import" | "update" | "remove" | "respond" | "move";
     calendar: string;
     externalId: string;
     notify: boolean;