@wirecat/cli-core 0.488.0 → 0.489.0

package/dist/calendar/writes.js

@@ -6,7 +6,7 @@ import { guardedWrite } from "../sends/guarded.js";
 import { DEFAULT_PERMISSIONS, levelFor } from "../sends/permissions.js";
 import { newOperationId } from "../sends/send-id.js";
 import { calendarIn, entryItem, eventIdOf, eventOf, plusDays } from "./reads.js";
-import { kindBoundLines, repeatRule } from "./recurrence.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";
 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. */
@@ -15,6 +15,7 @@ const COMMAND_KEY = {
     update: "events.update",
     delete: "events.delete",
     respond: "events.respond",
+    move: "events.move",
 };
 const DATE = /^\d{4}-\d{2}-\d{2}$/u;
 const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/u;
@@ -150,27 +151,44 @@ const answerOf = (operationId, saved, repeats = false) => ({
 /** An id every provider takes as a client-chosen one: Google's base32hex `[a-v0-9]`, a CalDAV UID, a Graph id. */
 export const newEventId = () => randomUUID().replaceAll("-", "");
 const ID = /^[a-v0-9]{5,1024}$/u;
-export const createEvent = async (context, calendarReference, fields, options = {}) => {
-    const calendar = await calendarIn(context.store, context.accountId, calendarReference);
-    const draft = draftOf(fields, context.zone, { whole: true });
-    if (options.id !== undefined && !ID.test(options.id))
-        throw new CliError("validation_error", `${context.names.id} is the id a create's outcome_unknown named: 5 to 1024 of a-v and 0-9`, {
-            param: context.names.id,
-        });
-    const notify = notifyOf(context, options.notify, (draft.attendees?.length ?? 0) > 0);
-    const id = options.id ?? newEventId();
-    const guard = writeGuard(context, keysFor(context, "create", notify));
-    let entry;
+const idOf = (context, given) => {
+    if (given !== undefined && !ID.test(given))
+        throw new CliError("validation_error", `${context.names.id} is the id a create's outcome_unknown named: 5 to 1024 of a-v and 0-9`, { param: context.names.id });
+    return given ?? newEventId();
+};
+/** A create whose answer was lost names its id, so the owner's retry finds the event instead of making another. */
+const retryable = async (context, id, write) => {
     try {
-        entry = await guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY.create, operationId: id, sendId: id, notify }, () => context.writes.writer.create(calendar, draft, { id, notify }));
+        return await write();
     }
     catch (error) {
         if (isCliError(error) && error.code === "outcome_unknown")
-            throw new CliError("outcome_unknown", `${error.message} — repeat the create with ${context.names.id} ${id}: the provider then finds the event ` +
+            throw new CliError("outcome_unknown", `${error.message} — repeat with ${context.names.id} ${id}: the provider then finds the event ` +
                 "instead of making a second one", { ...error.details, operation_id: id });
         throw error;
     }
-    const [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
+};
+/**
+ * The store's save of what the provider already made. A failure here names the id: without it the owner's retry makes
+ * the event a second time.
+ */
+const savedAfterCreate = async (context, id, save) => {
+    try {
+        return await save();
+    }
+    catch (error) {
+        throw new CliError(isCliError(error) ? error.code : "invalid_response", `the provider made event ${id}, but the local store did not save it (${error instanceof Error ? error.message : String(error)}); ` +
+            `sync to store it — do not create it again: a create repeated with ${context.names.id} ${id} finds it`, { ...(isCliError(error) ? error.details : {}), operation_id: id, id });
+    }
+};
+export const createEvent = async (context, calendarReference, fields, options = {}) => {
+    const calendar = await calendarIn(context.store, context.accountId, calendarReference);
+    const draft = draftOf(fields, context.zone, { whole: true });
+    const id = idOf(context, options.id);
+    const notify = notifyOf(context, options.notify, (draft.attendees?.length ?? 0) > 0);
+    const guard = writeGuard(context, keysFor(context, "create", notify));
+    const entry = await retryable(context, id, () => guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY.create, operationId: id, sendId: id, notify }, () => context.writes.writer.create(calendar, draft, { id, notify })));
+    const [saved] = await savedAfterCreate(context, id, () => context.store.saveEntries(calendar.id, [entry], context.now));
     return answerOf(id, saved, draft.recurrence !== undefined);
 };
 const targetOf = async (context, reference, { calendar, scope }) => {
@@ -185,11 +203,10 @@ const targetOf = async (context, reference, { calendar, scope }) => {
         throw new CliError("validation_error", `${reference} is on calendars ${live.map(({ calendarId }) => calendarId).join(", ")}; name one with ` +
             `${context.names.calendar}`, { param: context.names.calendar });
     let target = entry;
-    if (scope === "series") {
+    if (scope !== "this") {
+        const flag = scope === "series" ? context.names.series : context.names.following;
         if (entry.kind !== "occurrence" || !entry.seriesExternalId)
-            throw new CliError("validation_error", `${reference} does not repeat; leave out ${context.names.series}`, {
-                param: context.names.series,
-            });
+            throw new CliError("validation_error", `${reference} does not repeat; leave out ${flag}`, { param: flag });
         const series = await context.store.entry(entry.calendarId, entry.seriesExternalId);
         if (!series)
             throw new CliError("not_found", `the series of ${reference} is not stored; sync and try again`);
@@ -207,7 +224,39 @@ const targetOf = async (context, reference, { calendar, scope }) => {
         participants: details.participants.filter(({ entryId }) => entryId === entry.id),
     };
 };
+const scopeOf = (context, { series, following }) => {
+    if (series && following)
+        throw new CliError("validation_error", `choose ${context.names.series} or ${context.names.following}, not both`, {
+            param: context.names.following,
+        });
+    return following ? "following" : series ? "series" : "this";
+};
+/**
+ * A new COUNT or UNTIL that drops slots the series had deletes them as surely as a delete of the series does, so it
+ * takes that key too. A bound this cannot compare with the old one counts as shorter.
+ */
+const shortens = (target, rule, zone) => {
+    // A date UNTIL takes in its whole day.
+    const endOf = (line, in_) => {
+        const end = ruleEnd(line, in_);
+        return end !== undefined && /UNTIL=\d{8}(?:;|$)/iu.test(line) ? end + 86_400_000 - 1 : end;
+    };
+    const [until, count] = [endOf(rule, zone), ruleCount(rule)];
+    if (until === undefined && count === undefined)
+        return false;
+    const before = ruleLine(target.recurrence ?? []);
+    const [wasUntil, wasCount] = before === undefined ? [] : [endOf(before, target.timezone ?? zone), ruleCount(before)];
+    if (until !== undefined)
+        return wasUntil === undefined || until < wasUntil;
+    return wasCount === undefined || Number(count) < Number(wasCount);
+};
 export const updateEvent = async (context, reference, fields, options = {}) => {
+    if (scopeOf(context, options) === "following")
+        return updateFollowing(context, reference, fields, options);
+    if (options.id !== undefined)
+        throw new CliError("validation_error", `${context.names.id} goes with ${context.names.following} only`, {
+            param: context.names.id,
+        });
     const scope = options.series ? "series" : "this";
     if (fields.repeat !== undefined && scope !== "series")
         throw new CliError("validation_error", `a repeat rule belongs to the whole series: add ${context.names.series}`, {
@@ -226,12 +275,15 @@ export const updateEvent = async (context, reference, fields, options = {}) => {
                 ? "change its kind in the calendar itself"
                 : `give its rule again with ${context.names.repeat} and UNTIL as a ${target.allDay ? "UTC time" : "date"}`), { reason: "event.repeat-kind" });
     const notify = notifyOf(context, options.notify, hasOthers(participants) || (patch.attendees?.length ?? 0) > 0);
+    const ends = patch.recurrence !== undefined && shortens(target, patch.recurrence[0], context.zone);
     const operationId = newOperationId();
-    const entry = await guardedWrite(writeGuard(context, keysFor(context, "update", notify)), { chatId: null, kind: "edit", key: COMMAND_KEY.update, operationId, notify }, () => context.writes.writer.update(calendar, target.externalId, patch, { scope, etag: target.etag, notify }));
+    const entry = await guardedWrite(writeGuard(context, [...keysFor(context, "update", notify), ...(ends ? [EVENTS_DELETE_SERIES_KEY] : [])]), { chatId: null, kind: "edit", key: COMMAND_KEY.update, operationId, notify }, () => context.writes.writer.update(calendar, target.externalId, patch, { scope, etag: target.etag, notify }));
     const [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
     return answerOf(operationId, saved, patch.recurrence !== undefined || (switching && scope === "series"));
 };
 export const deleteEvent = async (context, reference, options = {}) => {
+    if (scopeOf(context, options) === "following")
+        return deleteFollowing(context, reference, options);
     const scope = options.series ? "series" : "this";
     const { calendar, entry, target, participants } = await targetOf(context, reference, { ...options, scope });
     const notify = notifyOf(context, options.notify, hasOthers(participants));
@@ -261,3 +313,190 @@ export const respondToEvent = async (context, reference, response, options = {})
     const [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
     return answerOf(operationId, saved);
 };
+const midnight = (date) => Date.parse(`${date}T00:00:00Z`);
+const splitOf = (context, reference, { entry, target }) => {
+    if (entry.originalStartsAt === null)
+        throw new CliError("not_found", `the slot of ${reference} in its series is not stored; sync and try again`);
+    const at = entry.originalStartsAt;
+    const rule = ruleLine(target.recurrence ?? []);
+    if (!rule)
+        throw new CliError("validation_error", `the series of ${reference} repeats by single dates only; change it in the calendar itself`, { reason: "event.repeat-split" });
+    const zone = target.timezone ?? context.zone;
+    const end = ruleEnd(rule, zone);
+    const first = target.allDay
+        ? target.startDate !== null && at <= midnight(target.startDate)
+        : at <= (target.startsAt ?? 0);
+    return { at, first, rule, ended: end !== undefined && end < at, zone };
+};
+/** The old series' rule ending before the split, with the dates and other lines that belong before it. */
+const endedRecurrence = (target, split) => [
+    ruleEndingBefore(split.rule, split.at, { allDay: target.allDay }),
+    ...(target.recurrence ?? []).filter((line) => !/^(RRULE|EXDATE|RDATE)[:;]/iu.test(line)),
+    ...splitDates(target.recurrence ?? [], split.at, split.zone).before,
+];
+/** Each later write of a split carries what was done already, so the owner's retry completes it without a double. */
+const afterCreate = async (context, id, write) => {
+    try {
+        return await write();
+    }
+    catch (error) {
+        if (!isCliError(error))
+            throw error;
+        // A lost answer may have ended the old series: after a sync this occurrence is gone, and a retry finds nothing.
+        const next = error.code === "outcome_unknown"
+            ? `sync: if the series now ends before this occurrence, the split is done; if not, repeat with ` +
+                `${context.names.id} ${id}, which finds the new series instead of making it again`
+            : `repeat with ${context.names.id} ${id}: the new series is found, not made again, and the old one ends`;
+        throw new CliError(error.code, `${error.message}; the new series ${id} is made — ${next}`, {
+            ...error.details,
+            operation_id: id,
+        });
+    }
+};
+/**
+ * "This and all following" from the writer's own writes, so every provider has it: neither RFC 5545 nor Google's API has
+ * such a change (https://developers.google.com/workspace/calendar/api/guides/recurringevents only warns against
+ * changing the instances one by one for it). The new series is made first, under an id journaled before the call, and then the old one ends before the slot:
+ * a conflict on the old series stops nothing being lost, and a retry with the id finds the new series. Until then
+ * later slots show twice, never none.
+ */
+const updateFollowing = async (context, reference, fields, options) => {
+    const found = await targetOf(context, reference, { ...options, scope: "following" });
+    const { calendar, entry, target, participants } = found;
+    const split = splitOf(context, reference, found);
+    if (split.first && !split.ended) {
+        const { following: _following, id: _id, ...rest } = options;
+        return updateEvent(context, reference, fields, { ...rest, series: true });
+    }
+    const patch = draftOf(fields, context.zone, { whole: false, allDay: target.allDay });
+    if ((patch.startDate !== undefined && !target.allDay) || (patch.startsAt !== undefined && target.allDay))
+        throw new CliError("validation_error", `a switch between timed and all-day changes the whole series: use ${context.names.series}`, { param: context.names.series, reason: "event.repeat-kind" });
+    const count = ruleCount(split.rule);
+    if (count !== undefined && !patch.recurrence)
+        throw new CliError("validation_error", `the series repeats COUNT=${count} times, and only the provider knows how many come from this occurrence on; ` +
+            `give the new part its own rule with ${context.names.repeat}, ending with UNTIL or its own COUNT`, { param: context.names.repeat, reason: "event.repeat-count" });
+    if (split.ended && options.id === undefined)
+        throw new CliError("validation_error", `the series of ${reference} already ends before it; if a split ended in outcome_unknown, repeat it with ` +
+            `${context.names.id} and the id it named`, { param: context.names.id, reason: "event.repeat-split" });
+    const id = idOf(context, options.id);
+    const draft = {
+        title: patch.title ?? target.title ?? "",
+        ...(patch.startsAt !== undefined || patch.startDate !== undefined
+            ? { startsAt: patch.startsAt, endsAt: patch.endsAt, startDate: patch.startDate, endDate: patch.endDate }
+            : target.allDay
+                ? {
+                    startDate: new Date(split.at).toISOString().slice(0, 10),
+                    endDate: new Date(split.at + midnight(target.endDate) - midnight(target.startDate))
+                        .toISOString()
+                        .slice(0, 10),
+                }
+                : { startsAt: split.at, endsAt: split.at + (target.endsAt ?? 0) - (target.startsAt ?? 0) }),
+        // A repeating event needs its zone at Google; the caller's stands in for a series stored without one.
+        timezone: patch.timezone ?? target.timezone ?? context.zone,
+        location: patch.location === undefined ? target.location : patch.location,
+        description: patch.description === undefined ? target.description : patch.description,
+        attendees: patch.attendees ??
+            participants
+                .filter(({ self }) => !self)
+                .map(({ email, optional }) => ({ email, ...(optional ? { optional: true } : {}) })),
+        recurrence: [
+            patch.recurrence?.[0] ?? split.rule,
+            ...splitDates(target.recurrence ?? [], split.at, split.zone).after,
+        ],
+    };
+    for (const key of ["startsAt", "endsAt", "startDate", "endDate"])
+        if (draft[key] === undefined)
+            delete draft[key];
+    const notify = notifyOf(context, options.notify, hasOthers(participants) || (patch.attendees?.length ?? 0) > 0);
+    const guard = writeGuard(context, [
+        ...new Set([...keysFor(context, "create", notify), ...keysFor(context, "update", notify)]),
+    ]);
+    const made = await retryable(context, id, () => guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY.update, operationId: id, sendId: id, notify }, () => context.writes.writer.create(calendar, draft, { id, notify })));
+    const written = [made];
+    if (!split.ended)
+        written.push(await afterCreate(context, id, () => guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY.update, operationId: newOperationId(), notify }, () => context.writes.writer.update(calendar, target.externalId, { recurrence: endedRecurrence(target, split) }, { scope: "series", etag: target.etag, notify }))));
+    const [saved, ended] = await savedAfterCreate(context, id, () => context.store.saveEntries(calendar.id, written, context.now));
+    return {
+        operation_id: id,
+        event: entry.eventId === null ? null : `event:${entry.eventId}`,
+        scope: "following",
+        entry: saved ? entryItem(saved) : null,
+        ended: ended ? entryItem(ended) : null,
+        hint: "sync to store the occurrences of both series",
+    };
+};
+/**
+ * The series ends before the occurrence. The earlier ones stay, so it takes the key of a deletion that asks, not the
+ * series'.
+ */
+const deleteFollowing = async (context, reference, options) => {
+    const found = await targetOf(context, reference, { ...options, scope: "following" });
+    const { calendar, entry, target, participants } = found;
+    const split = splitOf(context, reference, found);
+    if (split.first) {
+        const { following: _following, ...rest } = options;
+        return deleteEvent(context, reference, { ...rest, series: true });
+    }
+    if (split.ended)
+        throw new CliError("validation_error", `the series of ${reference} already ends before it; sync to see it`, {
+            reason: "event.repeat-split",
+        });
+    const notify = notifyOf(context, options.notify, hasOthers(participants));
+    const operationId = newOperationId();
+    const recurrence = endedRecurrence(target, split);
+    const written = await guardedWrite(writeGuard(context, keysFor(context, "update", notify)), { chatId: null, kind: "edit", key: COMMAND_KEY.delete, operationId, notify }, () => context.writes.writer.update(calendar, target.externalId, { recurrence }, { scope: "series", etag: target.etag, notify }));
+    const [ended] = await context.store.saveEntries(calendar.id, [written], context.now);
+    const removed = await context.store.removeEntries(calendar.id, [entry.externalId], context.now);
+    return {
+        operation_id: operationId,
+        event: entry.eventId === null ? null : `event:${entry.eventId}`,
+        scope: "following",
+        removed,
+        ended: ended ? entryItem(ended) : null,
+        ...(ruleCount(split.rule) === undefined ? {} : { converted: `COUNT became ${recurrence[0]?.slice(6)}` }),
+        hint: "sync to cancel the later occurrences stored",
+    };
+};
+const WRITABLE = new Set(["owner", "writer"]);
+/**
+ * The event, under the same id, to another calendar of the same account. A repeating event moves whole: an
+ * occurrence alone cannot change calendar at Google, and moving one copy of a series apart would split it.
+ */
+export const moveEvent = async (context, reference, toCalendar, options = {}) => {
+    const move = context.writes.writer.move?.bind(context.writes.writer);
+    if (!move)
+        throw new CliError("configuration_error", `${context.writes.writer.provider} cannot move events`);
+    const { calendar, target, participants } = await targetOf(context, reference, {
+        ...options,
+        scope: options.series ? "series" : "this",
+    });
+    if (target.kind === "occurrence")
+        throw new CliError("validation_error", `${reference} is one occurrence of a repeating event, which moves whole: add ${context.names.series}`, { param: context.names.series });
+    const destination = await calendarIn(context.store, context.accountId, toCalendar);
+    if (destination.id === calendar.id)
+        throw new CliError("validation_error", `${reference} is on calendar ${calendar.id} already`);
+    if (!WRITABLE.has(destination.accessRole ?? ""))
+        throw new CliError("permission_error", `calendar ${destination.id} takes no new events from this account`, {
+            reason: "calendar.read-only",
+        });
+    if (target.eventType && target.eventType !== "default")
+        // https://developers.google.com/workspace/calendar/api/v3/reference/events/move: only default events move.
+        throw new CliError("validation_error", `a ${target.eventType} event stays on its calendar`, {
+            reason: "event.unmovable",
+        });
+    const notify = notifyOf(context, options.notify, hasOthers(participants));
+    const operationId = newOperationId();
+    const moved = await guardedWrite(writeGuard(context, keysFor(context, "move", notify)), { chatId: null, kind: "edit", key: COMMAND_KEY.move, operationId, notify }, () => move(calendar, target.externalId, destination, { etag: target.etag, notify }));
+    await context.store.removeEntries(calendar.id, [target.externalId], context.now);
+    // The shared UID joins the new copy to the same event as the cancelled one; a provider may leave it out of a move.
+    const [saved] = await context.store.saveEntries(destination.id, [{ ...moved, icalUid: moved.icalUid ?? target.icalUid }], context.now);
+    return {
+        ...answerOf(operationId, saved, target.kind === "series"),
+        from_calendar: String(calendar.id),
+        calendar: String(destination.id),
+        // Stored once here, the copy would stay as it is now: no sync reads a calendar that does not sync.
+        ...(destination.synced
+            ? {}
+            : { hint: `calendar ${destination.id} does not sync: calendars sync ${destination.id} keeps the event current` }),
+    };
+};

package/dist/errors/reasons.d.ts

@@ -7,7 +7,7 @@ export declare const REASONS: ErrorReason[];
  * Detail keys an error from this package may carry, until each is registered on its own reason. Not `cause`:
  * that can hold a provider's or SQLite's raw text.
  */
-export declare const DETAILS: readonly ["contracts", "allowed", "alternative", "arguments", "at", "available", "batch", "budget", "built", "candidates", "chat", "chat_id", "cli", "complete", "emitted_bytes", "exact", "forum", "guide", "hint", "id", "index", "kind", "limit", "limit_source", "max_bytes", "model", "name", "operation_id", "operation_ids", "text_limit", "store_refused_in", "partial_output", "path", "permission", "person_ids", "previous_chat_id", "profiles", "provider_error", "provider", "recovery", "reference", "remembered", "retry_at", "runtime", "saved", "scheduled_for", "script", "sent", "sent_count", "settlement_failed", "span", "sqlite", "stage", "standing", "state", "stderr", "term", "total", "upgraded", "wanted"];
+export declare const DETAILS: readonly ["contracts", "calendars", "allowed", "alternative", "arguments", "at", "available", "batch", "budget", "built", "candidates", "chat", "chat_id", "cli", "complete", "emitted_bytes", "exact", "forum", "guide", "hint", "id", "index", "kind", "limit", "limit_source", "max_bytes", "model", "name", "operation_id", "operation_ids", "text_limit", "store_refused_in", "partial_output", "path", "permission", "person_ids", "previous_chat_id", "profiles", "provider_error", "provider", "recovery", "reference", "remembered", "retry_at", "runtime", "saved", "scheduled_for", "script", "sent", "sent_count", "settlement_failed", "span", "sqlite", "stage", "standing", "state", "stderr", "term", "total", "upgraded", "wanted"];
 /** What a CLI adds to the shared registry: its own reasons, and the detail keys its adapters raise. */
 export interface AppErrors {
     reasons?: readonly ErrorReason[];

package/dist/errors/reasons.js

@@ -59,6 +59,10 @@ const OTHERS = [
     validation("event.notify-required", "the event has other attendees; say whether to notify them"),
     validation("event.repeat-invalid", "the repeat rule is outside the RFC 5545 subset the calendars take"),
     validation("event.repeat-kind", "the series' rule holds a date or a time of the kind the event is leaving"),
+    validation("event.repeat-split", "the series cannot be split at this occurrence, or was split there already"),
+    validation("event.repeat-count", "a COUNT series is split only with a rule for its new part"),
+    validation("event.unmovable", "the provider keeps this kind of event on its calendar"),
+    ["calendar.read-only", "permission_error", "the calendar takes no new events from this account"],
     ["busy.offline", "permission_error", "calendars busy asks the provider; --offline was given"],
     validation("busy.no-calendars", "no calendar syncs and no person was named, so there is nobody to ask"),
     validation("store.refused", "the local store refused the document text"),
@@ -150,6 +154,7 @@ export const REASONS = defineReasons([
  */
 export const DETAILS = [
     "contracts",
+    "calendars",
     "allowed",
     "alternative",
     "arguments",

package/dist/meetings/event-store.d.ts

@@ -144,6 +144,10 @@ export interface StoredEntry {
     etag: string | null;
     seenAt: number | null;
     deletedAt: number | null;
+    /** When this copy was first stored. */
+    createdAt: number;
+    /** `transparent`: the copy does not take the owner's time. */
+    transparency: EntryTransparency | null;
 }
 export interface StoredParticipant {
     entryId: number;
@@ -183,6 +187,13 @@ export interface EventFilter {
     to?: number;
     /** All-day events, which have dates and no instant, ending after this local day (`YYYY-MM-DD`); `from` without it. */
     fromDate?: string;
+    /** Events `eventChange` finds new, moved or cancelled at or after this instant. */
+    changedSince?: number;
+    /**
+     * Events whose time overlaps another's. Only timed events that take the owner's time count: not cancelled, and with
+     * a live copy the owner did not decline or mark free.
+     */
+    overlapping?: boolean;
     /** All-day events starting before this local day (exclusive); `to` without it. */
     toDate?: string;
     accountId?: number;
@@ -195,10 +206,17 @@ export interface EventFilter {
     offset?: number;
 }
 /** Pairs the rules left unlinked because two or more entities fit equally well (requirements 3.6). */
+/** One series' slots for `EventStore.saveSlots`: what the provider gave, or `null` to keep what is stored. */
+export interface SeriesSlots {
+    series: string;
+    slots: EntryInput[] | null;
+}
 export interface LinkReview {
     id: number;
     linkableType: string;
     linkableId: number;
+    /** The calendar of a `calendar_entry` review's copy, so a choice is made only from that calendar's account. */
+    calendarId: number | null;
     entityType: string;
     candidates: number[];
     reason: string;
@@ -231,13 +249,22 @@ export interface EventStore {
      */
     removeEntries(calendarId: number, externalIds: string[], now: number): Promise<number>;
     /**
-     * After a full list: entries not seen since `seenBefore` get `deleted_at`. Plain occurrences come only from the
-     * window fetched, so only those inside it count. Events, series and links stay.
+     * After a full list: entries not seen since `seenBefore` get `deleted_at`. A full list holds only what falls in the
+     * window, so only entries `entryInWindow` puts there count. Events, series and links stay.
      */
     markUnseen(calendarId: number, seenBefore: number, window: {
         from: number;
         to: number;
     }, now: number): Promise<number>;
+    /**
+     * Takes `deleted_at` off the entries a full list marked although they were outside the window it listed:
+     * `windowAt(deletedAt)` is the window of the list that marked one. Their events take their fields again. Returns how
+     * many came back.
+     */
+    restoreUnseen(calendarId: number, windowAt: (deletedAt: number) => {
+        from: number;
+        to: number;
+    }, now: number): Promise<number>;
     /**
      * Where the calendar's last sync stopped, as the sync engine wrote it (`{"v":1,"token":…,"window":…,"fullAt":…}`),
      * or `null` before the first one.
@@ -247,8 +274,34 @@ export interface EventStore {
     setCursor(calendarId: number, value: string | null, now: number): Promise<void>;
     /** One entry by the provider's id; a series, which no event holds, is found only this way. */
     entry(calendarId: number, externalId: string): Promise<StoredEntry | null>;
+    /**
+     * Several series' slots in the window and the sync cursor, in one transaction: a sync commits once for many series
+     * instead of twice for each. A series' slots replace its stored plain slots in the window (one it no longer has is
+     * cancelled, as `removeEntries` does); `slots: null` keeps them and counts them as seen now.
+     */
+    saveSlots(calendarId: number, groups: SeriesSlots[], window: {
+        from: number;
+        to: number;
+    }, cursor: string, now: number): Promise<{
+        saved: number;
+        removed: number;
+    }>;
+    /** The series' stored slots, moved ones too, whose original start falls in the window; deleted ones left out. */
+    slotsOf(calendarId: number, seriesExternalId: string, window: {
+        from: number;
+        to: number;
+    }): Promise<StoredEntry[]>;
     events(filter?: EventFilter): Promise<Event[]>;
     event(id: number): Promise<EventDetails | null>;
+    /** These events' copies on these calendars, deleted ones too, and their revisions since the instant, for `eventChange`. */
+    historyOf(eventIds: number[], calendarIds: number[], since: number): Promise<{
+        entries: StoredEntry[];
+        revisions: EntryRevision[];
+    }>;
+    /** The participants of these events' copies on these calendars, deleted copies too, as `event` gives them. */
+    participantsOf(eventIds: number[], calendarIds: number[]): Promise<(StoredParticipant & {
+        eventId: number;
+    })[]>;
     /** The owner's link of an entry to an event; no rule replaces it. */
     linkEntry(entryId: number, eventId: number, now: number): Promise<void>;
     /** The owner's unlink: the rules leave the entry alone after it. */
@@ -258,3 +311,28 @@ export interface EventStore {
     }): Promise<LinkReview[]>;
     resolveReview(id: number, decision: ReviewDecision, now: number): Promise<LinkReview>;
 }
+/**
+ * Whether a full list of the window would return the entry: a single or a moved slot by its own time, a plain slot by
+ * the time its series gave it, a series while it repeats into the window. An entry with no time is never counted.
+ */
+export declare const entryInWindow: (entry: Pick<StoredEntry, "kind" | "exception" | "startsAt" | "endsAt" | "originalStartsAt" | "recurrence" | "recurrenceEndsAt">, window: {
+    from: number;
+    to: number;
+}) => boolean;
+/** What happened to an event at or after an instant, from its copies: first stored, a new time, or cancelled. */
+export interface EventChange {
+    change: "new" | "moved" | "cancelled";
+    /** When the store saw it. */
+    at: number;
+    /** The time a moved event had at the instant. */
+    was?: {
+        startsAt: number | null;
+        endsAt: number | null;
+    };
+}
+/**
+ * The event's change since `since`, from its copies and their revisions (each revision holds the fields before one
+ * change): cancelled when the event is gone and a copy was cancelled or removed since; new when its first copy was
+ * stored since; moved when a live copy's time now differs from its time at `since`. `null` when none of these.
+ */
+export declare const eventChange: (event: Pick<Event, "status" | "sourceDeletedAt">, entries: readonly StoredEntry[], revisions: readonly EntryRevision[], since: number) => EventChange | null;

package/dist/meetings/event-store.js

@@ -1 +1,65 @@
-export {};
+const UNTIL = /(?:^|;)UNTIL=(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2})Z?)?(?:;|$)/iu;
+/** The last moment a series can have a slot, when its rule says; a COUNT rule or none repeats as far as this knows. */
+const seriesEnd = (entry) => {
+    if (entry.recurrenceEndsAt !== null)
+        return entry.recurrenceEndsAt;
+    const rule = entry.recurrence?.find((line) => /^RRULE:/iu.test(line));
+    const until = rule === undefined ? null : UNTIL.exec(rule.slice("RRULE:".length));
+    if (!until)
+        return Number.POSITIVE_INFINITY;
+    const [, year, month, day, hour = "23", minute = "59", second = "59"] = until;
+    // A floating or zoned UNTIL is read as UTC; a day later keeps a series near the edge counted as inside.
+    return (Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second)) + 86_400_000);
+};
+/**
+ * Whether a full list of the window would return the entry: a single or a moved slot by its own time, a plain slot by
+ * the time its series gave it, a series while it repeats into the window. An entry with no time is never counted.
+ */
+export const entryInWindow = (entry, window) => {
+    if (entry.kind === "occurrence" && !entry.exception)
+        return (entry.originalStartsAt !== null && entry.originalStartsAt >= window.from && entry.originalStartsAt < window.to);
+    const start = entry.startsAt ?? (entry.kind === "occurrence" ? entry.originalStartsAt : null);
+    if (start === null || start >= window.to)
+        return false;
+    if (entry.kind === "series")
+        return seriesEnd(entry) >= window.from;
+    return Math.max(entry.endsAt ?? start, start + 1) > window.from;
+};
+/**
+ * The event's change since `since`, from its copies and their revisions (each revision holds the fields before one
+ * change): cancelled when the event is gone and a copy was cancelled or removed since; new when its first copy was
+ * stored since; moved when a live copy's time now differs from its time at `since`. `null` when none of these.
+ */
+export const eventChange = (event, entries, revisions, since) => {
+    const after = (entryId) => revisions
+        .filter((one) => one.entryId === entryId && one.createdAt >= since)
+        .sort((a, b) => a.createdAt - b.createdAt);
+    if (event.status === "cancelled" || event.sourceDeletedAt !== null) {
+        const times = entries.flatMap((entry) => [
+            ...(entry.deletedAt !== null && entry.deletedAt >= since ? [entry.deletedAt] : []),
+            ...(entry.status === "cancelled"
+                ? after(entry.id)
+                    .filter((one) => one.status !== "cancelled")
+                    .map(({ createdAt }) => createdAt)
+                : []),
+        ]);
+        if (times.length)
+            return { change: "cancelled", at: Math.max(...times) };
+    }
+    const first = Math.min(...entries.map(({ createdAt }) => createdAt));
+    if (entries.length && first >= since)
+        return { change: "new", at: first };
+    for (const entry of entries) {
+        if (entry.deletedAt !== null || entry.status === "cancelled")
+            continue;
+        const changes = after(entry.id);
+        const [was] = changes;
+        if (was && (was.startsAt !== entry.startsAt || was.endsAt !== entry.endsAt))
+            return {
+                change: "moved",
+                at: changes.at(-1).createdAt,
+                was: { startsAt: was.startsAt, endsAt: was.endsAt },
+            };
+    }
+    return null;
+};

package/dist/meetings/index.d.ts

@@ -4,7 +4,8 @@ export { calendarText, ENTRY_METADATA_KEYS, entryMetadata, withoutLinkQueries }
 export type { MeetingContextStore, MeetingEventLinkInput, MeetingEventLinkReceipt, ParticipantPerson, ParticipantPersonInput, ParticipantPersonLinkInput, ParticipantPersonLinkReceipt, } from "./context-store.js";
 export { type MeetingCueIdentity, meetingCueFingerprint } from "./cue-fingerprint.js";
 export { EVENT_QUERY } from "./event-query.js";
-export type { CalendarAccessRole, CalendarInput, EntryAttachment, EntryAttachmentInput, EntryEventType, EntryInput, EntryKind, EntryParticipantInput, EntryRevision, EntryStatus, EntryTransparency, EntryVisibility, EventDetails, EventFilter, EventStore, LinkReview, ParticipantResponse, ReviewDecision, StoredCalendar, StoredEntry, StoredParticipant, } from "./event-store.js";
+export type { CalendarAccessRole, CalendarInput, EntryAttachment, EntryAttachmentInput, EntryEventType, EntryInput, EntryKind, EntryParticipantInput, EntryRevision, EntryStatus, EntryTransparency, EntryVisibility, EventChange, EventDetails, EventFilter, EventStore, LinkReview, ParticipantResponse, ReviewDecision, SeriesSlots, StoredCalendar, StoredEntry, StoredParticipant, } from "./event-store.js";
+export { entryInWindow, eventChange } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, type MeetingExport, type MeetingExportFormat, type MeetingExportOptions, serializeVtt, } from "./export.js";
 export { type FindingEvidence, type FindingOutcome, findingHash, MEETING_FINDINGS_KIND, type MeetingFactFinding, type MeetingFinding, type MeetingFindingsInput, type MeetingFindingsReceipt, type MeetingTaskFinding, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";

package/dist/meetings/index.js

@@ -2,6 +2,7 @@ export { MEETING_STEPS, meetingDetails, meetingHit, meetingHitsList, meetingSumm
 export { calendarText, ENTRY_METADATA_KEYS, entryMetadata, withoutLinkQueries } from "./calendar-text.js";
 export { meetingCueFingerprint } from "./cue-fingerprint.js";
 export { EVENT_QUERY } from "./event-query.js";
+export { entryInWindow, eventChange } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, serializeVtt, } from "./export.js";
 export { findingHash, MEETING_FINDINGS_KIND, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";

package/dist/meetings/testing/event-store-contract.d.ts

@@ -1,4 +1,4 @@
-import type { EventStore } from "../event-store.js";
+import { type EventStore } from "../event-store.js";
 import type { ContractCase } from "../store.js";
 /** A fresh, empty store and one calendar account in it. */
 export interface EventStoreFixture {