@wirecat/cli-core 0.537.0 → 0.539.0

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, 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,19 @@ 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"],
         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 +111,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 +132,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 +156,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, [], ["event_type"]);
+    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 +201,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 +476,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/answers.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 /**
  * Parses what a shared calendar command handed its host against the command's entity, as a host prints it: keys in
- * snake_case, a list's items one by one, a search's hits each with the search's `untrusted`, and no `next`.
+ * snake_case, a list's items one by one, a search's hits each with the search's `untrusted`, and no `next`. A `meta`
+ * goes into the host's envelope, never into the item.
  */
 export declare const checkCalendarAnswer: (root: Command, argv: readonly string[], value: unknown) => void;

package/dist/calendar/testing/answers.js

@@ -13,14 +13,15 @@ const commandAt = (root, argv) => {
 };
 /**
  * Parses what a shared calendar command handed its host against the command's entity, as a host prints it: keys in
- * snake_case, a list's items one by one, a search's hits each with the search's `untrusted`, and no `next`.
+ * snake_case, a list's items one by one, a search's hits each with the search's `untrusted`, and no `next`. A `meta`
+ * goes into the host's envelope, never into the item.
  */
 export const checkCalendarAnswer = (root, argv, value) => {
     const command = commandAt(root, argv);
     const schema = answerEntitySchema(command);
     if (!schema)
         throw new Error(`${argv.join(" ")} declares no answer entity`);
-    const { next: _next, ...body } = snakeKeys(value);
+    const { next: _next, meta: _meta, ...body } = snakeKeys(value);
     const marker = body.untrusted
         ?.filter((field) => field.startsWith("hits."))
         .map((field) => field.slice("hits.".length));

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;

package/dist/calendar/testing/writer.js

@@ -73,6 +73,46 @@ export const fakeCalendarWriter = (options = {}) => {
             of(calendar.externalId).set(id, entry);
             return answer(entry);
         },
+        /** Reads no date: the event is the whole line as its title, an hour from noon UTC of 2 November 2026. */
+        async quickAdd(calendar, text, { notify }) {
+            const id = `quick${++version}`;
+            calls.push({ write: "quick-add", calendar: calendar.externalId, externalId: id, notify });
+            const noon = Date.UTC(2026, 10, 2, 12);
+            const entry = stamp({
+                externalId: id,
+                icalUid: `${id}@example.com`,
+                kind: "single",
+                status: "confirmed",
+                title: text,
+                startsAt: noon,
+                endsAt: noon + 3_600_000,
+                participants: [],
+            });
+            of(calendar.externalId).set(id, entry);
+            return answer(entry);
+        },
+        /** Keeps one event per UID on a calendar: a UID sent again replaces the event under the same id. */
+        async importEvent(calendar, event) {
+            const held = [...of(calendar.externalId).values()].find((one) => one.icalUid === event.uid);
+            const id = held?.externalId ?? `imported${++version}`;
+            calls.push({ write: "import", calendar: calendar.externalId, externalId: id, notify: false });
+            const entry = stamp({
+                externalId: id,
+                icalUid: event.uid,
+                kind: event.recurrence ? "series" : "single",
+                status: event.status ?? "confirmed",
+                title: event.title,
+                description: event.description ?? null,
+                location: event.location ?? null,
+                ...(event.startDate === undefined
+                    ? { startsAt: event.startsAt ?? null, endsAt: event.endsAt ?? null, timezone: event.timezone ?? null }
+                    : { allDay: true, startDate: event.startDate, endDate: event.endDate ?? null }),
+                ...(event.recurrence ? { recurrence: event.recurrence } : {}),
+                participants: (event.attendees ?? []).map(({ email, name }) => ({ email, name: name ?? null })),
+            });
+            of(calendar.externalId).set(id, entry);
+            return answer(entry);
+        },
         async update(calendar, externalId, patch, { scope, etag, notify }) {
             calls.push({ write: "update", calendar: calendar.externalId, externalId, notify, scope });
             const entry = stamp({ ...current(calendar, externalId, etag), ...fields(patch) });

package/dist/calendar/writer.d.ts

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import type { EntryInput, ParticipantResponse, StoredCalendar } from "../meetings/index.js";
 import type { Level, PermissionKey } from "../sends/permissions.js";
+import type { IcsEvent } from "./ics.js";
 /**
  * A new event in neutral words: a timed one has `startsAt` and `endsAt` (epoch ms, end exclusive) in `timezone`; an
  * all-day one has `startDate` and `endDate` (`YYYY-MM-DD`, end exclusive). A repeating one has `recurrence`, RFC 5545
@@ -64,6 +65,19 @@ export interface CalendarWriter {
         etag: string;
         notify: boolean;
     }): Promise<EntryInput>;
+    /**
+     * Optional: the provider makes an event from one line of text, reading its date, time and place its own way. The
+     * provider picks the id, so a retry after `outcome_unknown` may make a second event.
+     */
+    quickAdd?(calendar: StoredCalendar, text: string, options: {
+        notify: boolean;
+    }): Promise<EntryInput>;
+    /**
+     * Optional: adds a private copy of an event read from an iCalendar file, under its own UID, as Google's
+     * `events.import`. The provider mails nobody. Sending the same UID again goes to the provider again; what it does
+     * with an event it holds already is its own.
+     */
+    importEvent?(calendar: StoredCalendar, event: IcsEvent): Promise<EntryInput>;
     /**
      * Optional: moves the event, keeping its id, to `target`, another calendar of the same account. `etag` is checked
      * before the move; a provider whose move takes no precondition reads the event first. A retry after
@@ -75,7 +89,7 @@ export interface CalendarWriter {
     }): Promise<EntryInput>;
 }
 /** Which write a command makes, for `CalendarWrites.extraKeys`. */
-export type CalendarWrite = "create" | "update" | "delete" | "respond" | "move";
+export type CalendarWrite = "create" | "quick-add" | "import" | "update" | "delete" | "respond" | "move";
 /** Mailing the other attendees: an agent may write to the calendar and still not to people (WC-PERM-14's spirit). */
 export declare const EVENTS_NOTIFY_KEY: PermissionKey;
 export declare const EVENTS_DELETE_SERIES_KEY: PermissionKey;

package/dist/calendar/writer.js

@@ -10,6 +10,8 @@ export const CALENDAR_WRITE_KEYS = [EVENTS_NOTIFY_KEY, EVENTS_DELETE_SERIES_KEY]
  */
 export const CALENDAR_WRITE_DEFAULTS = {
     "events.create": "allow",
+    // One import writes a whole file of events, and may change events the calendar already holds under their UIDs.
+    "events.import": "ask",
     "events.update": "allow",
     "events.respond": "allow",
     "events.move": "allow",

package/dist/calendar/writes.d.ts

@@ -3,6 +3,7 @@ import type { AppIdentity } from "../ports/app.js";
 import type { Warn } from "../runs/events.js";
 import { type Asker, type GuardSettings } from "../sends/guard.js";
 import { type PermissionKey } from "../sends/permissions.js";
+import { entryItem } from "./reads.js";
 import { type CalendarWrite, type CalendarWriter, type EventPatch, type EventResponse } from "./writer.js";
 /** What a CLI or an MCP host hands the calendar writes for one profile. */
 export interface CalendarWrites {
@@ -83,6 +84,51 @@ export declare const createEvent: (context: WriteContext, calendarReference: str
     } | null;
     hint?: string | undefined;
 }>;
+/**
+ * An event the provider makes from one line of text, as Google's quickAdd. Nobody is mailed unless `notify` says so:
+ * the attendees are known only once the provider has read the text.
+ */
+export declare const createEventFromText: (context: WriteContext, calendarReference: string, text: string, options?: {
+    notify?: boolean;
+}) => Promise<{
+    operation_id: string;
+    event: string | null;
+    entry: {
+        id: string;
+        calendar_id: string;
+        external_id: string;
+        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;
+        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;
+    } | null;
+    hint?: string | undefined;
+}>;
+/** The most events one import sends: a file of more is refused before anything goes. */
+export declare const IMPORT_MAX = 500;
+/**
+ * The events of an iCalendar text into a calendar, one provider call each, in the file's order. The whole import is
+ * one write for the guard: one question, one journal line. A failure part way names the UIDs already imported.
+ */
+export declare const importEvents: (context: WriteContext, calendarReference: string, text: string) => Promise<{
+    operation_id: string;
+    calendar: string;
+    imported: {
+        uid: string;
+        event: string | null;
+        entry: ReturnType<typeof entryItem> | null;
+    }[];
+    skipped: {
+        uid: string | null;
+        reason: string;
+    }[];
+}>;
 interface ScopeChoice {
     calendar?: string;
     series?: boolean;

package/dist/calendar/writes.js

@@ -5,6 +5,7 @@ import { guardFor } from "../sends/guard.js";
 import { guardedWrite } from "../sends/guarded.js";
 import { DEFAULT_PERMISSIONS, levelFor } from "../sends/permissions.js";
 import { newOperationId } from "../sends/send-id.js";
+import { readIcs } from "./ics.js";
 import { calendarIn, entryItem, eventIdOf, eventOf, plusDays } from "./reads.js";
 import { kindBoundLines, repeatRule, ruleCount, ruleEnd, ruleEndingBefore, ruleLine, splitDates } from "./recurrence.js";
 import { CALENDAR_WRITE_DEFAULTS, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, } from "./writer.js";
@@ -12,6 +13,8 @@ export const EVENT_RESPONSES = ["accepted", "tentative", "declined"];
 /** Each write is checked by its command's path, the key a declared CLI's `commandPermissions` already knows. */
 const COMMAND_KEY = {
     create: "events.create",
+    "quick-add": "events.create",
+    import: "events.import",
     update: "events.update",
     delete: "events.delete",
     respond: "events.respond",
@@ -191,6 +194,101 @@ export const createEvent = async (context, calendarReference, fields, options =
     const [saved] = await savedAfterCreate(context, id, () => context.store.saveEntries(calendar.id, [entry], context.now));
     return answerOf(id, saved, draft.recurrence !== undefined);
 };
+/** The longest line `createEventFromText` sends; a quick add is one sentence, not a description. */
+const TEXT_MAX = 1000;
+/**
+ * An event the provider makes from one line of text, as Google's quickAdd. Nobody is mailed unless `notify` says so:
+ * the attendees are known only once the provider has read the text.
+ */
+export const createEventFromText = async (context, calendarReference, text, options = {}) => {
+    const quickAdd = context.writes.writer.quickAdd;
+    if (!quickAdd)
+        throw new CliError("configuration_error", "this provider cannot make an event from text");
+    const line = text.trim();
+    if (!line)
+        throw new CliError("validation_error", "the text is empty: say what, when and where");
+    if (line.length > TEXT_MAX || /[\r\n]/u.test(line))
+        throw new CliError("validation_error", `the text is one line of at most ${TEXT_MAX} characters`);
+    const calendar = await calendarIn(context.store, context.accountId, calendarReference);
+    const notify = options.notify ?? false;
+    const guard = writeGuard(context, keysFor(context, "quick-add", notify));
+    const id = newEventId();
+    let entry;
+    try {
+        entry = await guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY["quick-add"], operationId: id, sendId: id, notify }, () => quickAdd.call(context.writes.writer, calendar, line, { notify }));
+    }
+    catch (error) {
+        if (isCliError(error) && error.code === "outcome_unknown")
+            throw new CliError("outcome_unknown", `${error.message} — the provider may have made the event, and a create from text cannot be retried safely: ` +
+                "sync, then look with events list changed_at>=today before adding it again", { ...error.details, operation_id: id, retryable: false });
+        throw error;
+    }
+    let saved;
+    try {
+        ;
+        [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
+    }
+    catch (error) {
+        throw new CliError(isCliError(error) ? error.code : "invalid_response", `the provider made event ${entry.externalId}, but the local store did not save it ` +
+            `(${error instanceof Error ? error.message : String(error)}); sync to store it — do not create it again`, { ...(isCliError(error) ? error.details : {}), operation_id: id, id: entry.externalId, retryable: false });
+    }
+    return answerOf(id, saved, (entry.recurrence?.length ?? 0) > 0);
+};
+/** The most events one import sends: a file of more is refused before anything goes. */
+export const IMPORT_MAX = 500;
+/**
+ * The events of an iCalendar text into a calendar, one provider call each, in the file's order. The whole import is
+ * one write for the guard: one question, one journal line. A failure part way names the UIDs already imported.
+ */
+export const importEvents = async (context, calendarReference, text) => {
+    const writer = context.writes.writer;
+    if (!writer.importEvent)
+        throw new CliError("configuration_error", "this provider cannot import events");
+    const { events, skipped } = readIcs(text, context.zone);
+    if (events.length === 0)
+        throw new CliError("validation_error", skipped.length
+            ? `no event in the file can be imported: ${skipped.map(({ reason }) => reason).join("; ")}`
+            : "the file holds no event (VEVENT)", { reason: "ics.no-events", skipped: skipped.map(({ uid, reason }) => ({ uid, reason })) });
+    if (events.length > IMPORT_MAX)
+        throw new CliError("validation_error", `the file holds ${events.length} events; one import takes at most ${IMPORT_MAX}`, { reason: "ics.too-many" });
+    const calendar = await calendarIn(context.store, context.accountId, calendarReference);
+    const guard = writeGuard(context, keysFor(context, "import", false));
+    const id = newEventId();
+    const imported = [];
+    await guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY.import, operationId: id, sendId: id, notify: false }, async () => {
+        for (const event of events) {
+            try {
+                const entry = await writer.importEvent?.call(writer, calendar, event);
+                if (!entry)
+                    throw new CliError("invalid_response", "the provider returned no event");
+                const [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
+                imported.push({
+                    uid: event.uid,
+                    event: saved?.eventId == null ? null : `event:${saved.eventId}`,
+                    entry: saved ? entryItem(saved) : null,
+                });
+            }
+            catch (error) {
+                const done = imported.map(({ uid }) => uid);
+                throw new CliError(isCliError(error) ? error.code : "provider_error", `${error instanceof Error ? error.message : String(error)} — at the event with UID ${event.uid}; ` +
+                    `${done.length} of ${events.length} were imported before it (details.imported). Running the import ` +
+                    "again sends every event again under its UID", {
+                    ...(isCliError(error) ? error.details : {}),
+                    operation_id: id,
+                    imported: done,
+                    failed: event.uid,
+                    retryable: false,
+                });
+            }
+        }
+    });
+    return {
+        operation_id: id,
+        calendar: String(calendar.id),
+        imported,
+        skipped: skipped.map(({ uid, reason }) => ({ uid, reason })),
+    };
+};
 const targetOf = async (context, reference, { calendar, scope }) => {
     const details = await eventOf(context.store, context.accountId, eventIdOf(reference));
     const calendars = await context.store.calendars(context.accountId);

package/dist/cli/list-query.d.ts

@@ -39,9 +39,10 @@ export declare const queryArgument: (registry: QueryRegistry) => v.OptionalSchem
 export declare const nativeTerms: (ast: QueryAst | undefined, command: string) => Map<string, Predicate>;
 /**
  * As `nativeTerms`, but each `repeatable` field may be named again, every term kept in order: `person:a person:b`
- * asks for both, as AND reads.
+ * asks for both, as AND reads. A `negatable` field may also be excluded, `-field:value` or `NOT field:value`, as
+ * often as wanted; those terms are kept under `-field`.
  */
-export declare const nativeTermLists: (ast: QueryAst | undefined, command: string, repeatable?: readonly string[]) => Map<string, Predicate[]>;
+export declare const nativeTermLists: (ast: QueryAst | undefined, command: string, repeatable?: readonly string[], negatable?: readonly string[]) => Map<string, Predicate[]>;
 /**
  * A store that compares whole values: each field's `field:value` or `field:"two words"`, enum values lowercased
  * as validation already accepts them. A range or wildcard is refused rather than read as a value.

package/dist/cli/list-query.js

@@ -112,9 +112,10 @@ export const queryArgument = (registry) => {
 export const nativeTerms = (ast, command) => new Map([...nativeTermLists(ast, command)].map(([field, [node]]) => [field, node]));
 /**
  * As `nativeTerms`, but each `repeatable` field may be named again, every term kept in order: `person:a person:b`
- * asks for both, as AND reads.
+ * asks for both, as AND reads. A `negatable` field may also be excluded, `-field:value` or `NOT field:value`, as
+ * often as wanted; those terms are kept under `-field`.
  */
-export const nativeTermLists = (ast, command, repeatable = []) => {
+export const nativeTermLists = (ast, command, repeatable = [], negatable = []) => {
     const terms = new Map();
     if (!ast)
         return terms;
@@ -123,8 +124,16 @@ export const nativeTermLists = (ast, command, repeatable = []) => {
     const add = (node) => {
         if (node.kind === "boolean") {
             for (const clause of node.clauses) {
+                const excluded = clause.occur === "must_not" && clause.node.kind === "predicate" && negatable.includes(clause.node.field);
+                if (excluded && clause.node.kind === "predicate") {
+                    const key = `-${clause.node.field}`;
+                    terms.set(key, [...(terms.get(key) ?? []), clause.node]);
+                    continue;
+                }
                 if (clause.occur !== "must")
-                    queryError("query.unsupported-placement", clause.node.span, "this list takes only field:value terms joined by AND", context);
+                    queryError("query.unsupported-placement", clause.node.span, negatable.length
+                        ? `this list takes only field:value terms joined by AND, and -field:value for ${negatable.join(", ")}`
+                        : "this list takes only field:value terms joined by AND", context);
                 add(clause.node);
             }
             return;