@dereekb/firebase 13.41.0 → 13.43.0

package/src/lib/model/calendar/calendar.type.d.ts

@@ -0,0 +1,188 @@
+import { type Days, type Maybe, type Milliseconds, type Minutes } from '@dereekb/util';
+import { type CalendarType } from './calendar.id';
+/**
+ * @module calendar.type
+ *
+ * The {@link CalendarType} registry: the per-type retention policy and ICS emission config an app declares
+ * once and the publish pipeline reads on every sweep.
+ *
+ * The type and the factory live here, in the model folder rather than in `firebase-server`, so a client-side
+ * ICS preview or the future dbx-calendar adapter reads the SAME expansion window the server publishes with.
+ * Only the service INSTANCE is constructed server-side, as a NestJS provider — the same split
+ * {@link AppNotificationTemplateTypeInfoRecordService} uses.
+ */
+/**
+ * How a {@link Calendar}'s recurring events are represented in its published ICS.
+ *
+ * - `rrule` emits one VEVENT per series carrying an RRULE, which is compact and lets a subscriber handle
+ *   recurrence natively.
+ * - `expand` emits one VEVENT per occurrence within the expansion window, which is what
+ *   `@dereekb/date`'s iCalendar layer documents as its preferred authoring path: a published feed gets no
+ *   chance to correct a client's misinterpretation of a rule before the next poll, 12-24 hours later.
+ */
+export type CalendarIcsRecurrenceMode = 'rrule' | 'expand';
+/**
+ * Retention and ICS-emission configuration for a single {@link CalendarType}.
+ *
+ * Retention is what keeps the embedded-event design inside Firestore's 1 MiB document ceiling without any
+ * manual gardening: every sweep prunes before it publishes.
+ */
+export interface CalendarTypeConfig {
+    /**
+     * The type this configuration applies to.
+     */
+    readonly calendarType: CalendarType;
+    /**
+     * Human-readable name of the type, for tooling and logs.
+     */
+    readonly name?: Maybe<string>;
+    /**
+     * How many days of already-ended one-off events to keep. Defaults to {@link DEFAULT_CALENDAR_RETAIN_PAST_EVENT_DAYS}.
+     */
+    readonly retainPastEventDays?: Maybe<Days>;
+    /**
+     * Maximum number of stored events, counting one-off and recurring events together.
+     * Defaults to {@link DEFAULT_CALENDAR_MAX_EVENTS}.
+     */
+    readonly maxEvents?: Maybe<number>;
+    /**
+     * Whether an ended recurrence is eligible for pruning at all. Defaults to true.
+     *
+     * A forever recurrence is never pruned regardless of this value.
+     */
+    readonly pruneEndedRecurrences?: Maybe<boolean>;
+    /**
+     * How many days of already-ended recurrences to keep. Defaults to the resolved {@link retainPastEventDays}.
+     */
+    readonly retainEndedRecurrenceDays?: Maybe<Days>;
+    /**
+     * How recurring events are emitted. Defaults to {@link DEFAULT_CALENDAR_ICS_RECURRENCE_MODE}.
+     */
+    readonly icsRecurrenceMode?: Maybe<CalendarIcsRecurrenceMode>;
+    /**
+     * How far back the ICS expansion window reaches, used only in `expand` mode.
+     * Defaults to {@link DEFAULT_CALENDAR_ICS_EXPANSION_PAST_DAYS}.
+     */
+    readonly icsExpansionPastDays?: Maybe<Days>;
+    /**
+     * How far forward the ICS expansion window reaches, used only in `expand` mode.
+     * Defaults to {@link DEFAULT_CALENDAR_ICS_EXPANSION_FUTURE_DAYS}.
+     */
+    readonly icsExpansionFutureDays?: Maybe<Days>;
+    /**
+     * Emitted as REFRESH-INTERVAL / X-PUBLISHED-TTL.
+     *
+     * ADVISORY ONLY: Google re-fetches a subscribed feed every ~12-24 hours regardless.
+     */
+    readonly refreshInterval?: Maybe<Minutes>;
+    /**
+     * How long a Calendar of this type may go without a successful publish before the backstop sweep re-flags
+     * it. Defaults to {@link DEFAULT_CALENDAR_RESYNC_INTERVAL}.
+     *
+     * This is also what keeps an `expand`-mode calendar from sliding off the end of its expansion window.
+     */
+    readonly resyncInterval?: Maybe<Milliseconds>;
+}
+/**
+ * Default for {@link CalendarTypeConfig.retainPastEventDays}.
+ */
+export declare const DEFAULT_CALENDAR_RETAIN_PAST_EVENT_DAYS: Days;
+/**
+ * Default for {@link CalendarTypeConfig.maxEvents}.
+ *
+ * At roughly 300 stored bytes per item this leaves about 6x headroom under Firestore's 1 MiB ceiling.
+ */
+export declare const DEFAULT_CALENDAR_MAX_EVENTS = 500;
+/**
+ * Default for {@link CalendarTypeConfig.icsRecurrenceMode}.
+ */
+export declare const DEFAULT_CALENDAR_ICS_RECURRENCE_MODE: CalendarIcsRecurrenceMode;
+/**
+ * Default for {@link CalendarTypeConfig.icsExpansionPastDays}.
+ */
+export declare const DEFAULT_CALENDAR_ICS_EXPANSION_PAST_DAYS: Days;
+/**
+ * Default for {@link CalendarTypeConfig.icsExpansionFutureDays}.
+ */
+export declare const DEFAULT_CALENDAR_ICS_EXPANSION_FUTURE_DAYS: Days;
+/**
+ * Default for {@link CalendarTypeConfig.resyncInterval}: seven days.
+ */
+export declare const DEFAULT_CALENDAR_RESYNC_INTERVAL: Milliseconds;
+/**
+ * The {@link CalendarType} of {@link DEFAULT_CALENDAR_TYPE_CONFIG}, used for a type the app never registered.
+ */
+export declare const UNKNOWN_CALENDAR_TYPE: CalendarType;
+/**
+ * The configuration applied to a Calendar whose type the app did not register.
+ *
+ * An unregistered type falls back rather than throwing on purpose: a scheduled sweep over every calendar in
+ * the app must not be taken down by one badly-typed document.
+ */
+export declare const DEFAULT_CALENDAR_TYPE_CONFIG: CalendarTypeConfig;
+/**
+ * Record of {@link CalendarTypeConfig} keyed by {@link CalendarType}.
+ */
+export type CalendarTypeConfigRecord = Record<CalendarType, CalendarTypeConfig>;
+/**
+ * Creates a {@link CalendarTypeConfigRecord} from an array of configs.
+ *
+ * @param configs - The configs to index.
+ * @returns A record keyed by calendar type.
+ * @throws {Error} When two configs declare the same {@link CalendarType}.
+ *
+ * @example
+ * ```ts
+ * const record = calendarTypeConfigRecord([{ calendarType: 'demo_profile', maxEvents: 100 }]);
+ * ```
+ */
+export declare function calendarTypeConfigRecord(configs: CalendarTypeConfig[]): CalendarTypeConfigRecord;
+/**
+ * Runtime service for resolving a {@link CalendarTypeConfig} from a {@link CalendarType}.
+ *
+ * Built from a {@link CalendarTypeConfigRecord} via {@link appCalendarTypeConfigService}.
+ */
+export declare abstract class AppCalendarTypeConfigService {
+    /**
+     * All registered configs for this app.
+     */
+    abstract readonly appCalendarTypeConfigRecord: CalendarTypeConfigRecord;
+    /**
+     * Returns the config for the given type, falling back to the service's default when it is not registered.
+     *
+     * @param calendarType - The type to look up.
+     */
+    abstract configForCalendarType(calendarType: CalendarType): CalendarTypeConfig;
+    /**
+     * Returns every registered {@link CalendarType}.
+     *
+     * This is what the backstop sweep iterates, since each type carries its own resync interval.
+     */
+    abstract getAllKnownCalendarTypes(): CalendarType[];
+    /**
+     * Returns every registered {@link CalendarTypeConfig}.
+     */
+    abstract getAllKnownCalendarTypeConfigs(): CalendarTypeConfig[];
+}
+/**
+ * Reference to an {@link AppCalendarTypeConfigService} instance, for dependency injection.
+ */
+export interface AppCalendarTypeConfigServiceRef {
+    readonly appCalendarTypeConfigService: AppCalendarTypeConfigService;
+}
+/**
+ * Creates an {@link AppCalendarTypeConfigService} from the given record.
+ *
+ * @param appCalendarTypeConfigRecord - The complete calendar type registry for the application.
+ * @param defaultConfig - Config used for an unregistered type. Defaults to {@link DEFAULT_CALENDAR_TYPE_CONFIG}.
+ * @returns The service.
+ *
+ * @example
+ * ```ts
+ * const service = appCalendarTypeConfigService(calendarTypeConfigRecord(DEMO_CALENDAR_TYPE_CONFIGS));
+ * const config = service.configForCalendarType('demo_profile');
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function appCalendarTypeConfigService(appCalendarTypeConfigRecord: CalendarTypeConfigRecord, defaultConfig?: CalendarTypeConfig): AppCalendarTypeConfigService;

package/src/lib/model/calendar/calendar.util.d.ts

@@ -0,0 +1,485 @@
+import { type ArrayOrValue, type Hours, type Maybe, type TimezoneString, unixDateTimeSecondsNumberFromDate } from '@dereekb/util';
+import { type CalendarDate, DateSet, type ModelRecurrenceInfo } from '@dereekb/date';
+import { type FirebaseAuthOwnershipKey, type FirestoreModelKey } from '../../common';
+import { type Calendar, type CalendarEventItem, type CalendarRecurringEventItem } from './calendar';
+import { type CalendarEventId, type CalendarExtensionData, type CalendarType } from './calendar.id';
+import { type CalendarTypeConfig } from './calendar.type';
+/**
+ * @module calendar.util
+ *
+ * The CALLER-FACING surface of the Calendar model: pure array operations and update TEMPLATES.
+ *
+ * Other models create and mutate a Calendar inside THEIR OWN transaction, holding the accessor and the
+ * document themselves. So this module ships no `upsert…` / `remove…` server actions — an action that opened
+ * its own transaction would either fight the caller's or force an awkward split write. It ships the
+ * `Pick<Calendar, …>` templates the caller merges into its own `create()` / `update()`, the same convention
+ * `markStorageFileForDeleteTemplate()` follows.
+ *
+ * The `s: true` invariant that makes the sweep correct is carried by {@link calendarTemplate} and
+ * {@link updateCalendarEventsTemplate}, so it remains impossible to mutate events and forget to flag the
+ * calendar for sync.
+ */
+/**
+ * Returns the instant a one-off event ends at.
+ *
+ * @param item - The event.
+ * @returns The end instant.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemEndDate(item: CalendarEventItem): Date;
+/**
+ * Returns the {@link CalendarDate} view of an event, which is the input shape every `@dereekb/date`
+ * expansion and iCalendar factory consumes.
+ *
+ * @param item - The event.
+ * @returns The calendar date.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemCalendarDate(item: CalendarEventItem): CalendarDate;
+/**
+ * Returns the {@link DateSet} of a recurring event's excluded occurrences, which is exactly what
+ * `DateRRuleInstanceOptions.exclude` wants.
+ *
+ * @param item - The recurring event.
+ * @returns The excluded instants. Empty when the event excludes nothing.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemExceptionDateSet(item: Pick<CalendarRecurringEventItem, 'rex'>): DateSet;
+/**
+ * Returns the timezone an event's wall clock is anchored to, falling back to the calendar's timezone.
+ *
+ * @param item - The event.
+ * @param calendarTimezone - The owning calendar's timezone.
+ * @returns The resolved timezone.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemTimezone(item: Pick<CalendarEventItem, 'tz'>, calendarTimezone: TimezoneString): TimezoneString;
+/**
+ * Projects a recurring event onto the workspace's {@link ModelRecurrenceInfo} shape.
+ *
+ * The mapping is total and lossless because the event's base `sa` IS the recurrence's start and its base
+ * `tz` IS the recurrence's timezone — which is exactly why there is no separate `recurrenceStartsAt`.
+ *
+ * @param item - The recurring event.
+ * @param calendarTimezone - The owning calendar's timezone, used when the event carries none.
+ * @returns The recurrence info.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarRecurringEventItemModelRecurrenceInfo(item: CalendarRecurringEventItem, calendarTimezone: TimezoneString): ModelRecurrenceInfo;
+/**
+ * The recurrence half of a {@link CalendarRecurringEventItem}, as produced from a {@link ModelRecurrenceInfo}.
+ */
+export type CalendarRecurringEventItemRecurrenceFields = Pick<CalendarRecurringEventItem, 'sa' | 'tz' | 'rr' | 'rea' | 'rfe'>;
+/**
+ * Projects a {@link ModelRecurrenceInfo} back onto the recurrence fields of a recurring event.
+ *
+ * @param info - The recurrence info.
+ * @returns The recurrence fields, ready to merge into an event item.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarRecurringEventItemRecurrenceFields(info: ModelRecurrenceInfo): CalendarRecurringEventItemRecurrenceFields;
+/**
+ * Configuration for {@link calendarTemplate}.
+ */
+export interface CalendarTemplateConfig {
+    readonly calendarType: CalendarType;
+    readonly name: string;
+    readonly timezone?: Maybe<TimezoneString>;
+    readonly description?: Maybe<string>;
+    readonly color?: Maybe<string>;
+    readonly ownerKey?: Maybe<FirebaseAuthOwnershipKey>;
+    readonly events?: Maybe<CalendarEventItem[]>;
+    readonly recurringEvents?: Maybe<CalendarRecurringEventItem[]>;
+    readonly extensionData?: Maybe<CalendarExtensionData>;
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Builds the initial document data for a new Calendar.
+ *
+ * The caller creates the document itself, typically as
+ * `accessor.loadDocumentForId(calendarIdForModel(relatedModelKey)).create(calendarTemplate({ … }))`.
+ *
+ * `s` defaults to true, so a newly created Calendar is picked up by the very next sweep.
+ *
+ * @param config - The calendar's type, display metadata and initial events.
+ * @returns The Calendar data.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarTemplate(config: CalendarTemplateConfig): Calendar;
+/**
+ * The fields {@link markCalendarForSyncTemplate} produces.
+ */
+export type MarkCalendarForSyncTemplate = Pick<Calendar, 's' | 'uat'>;
+/**
+ * Builds the update that flags a Calendar for its next sync without touching its events.
+ *
+ * A caller that changed only display metadata (name, description, color) merges this.
+ *
+ * @param now - The update instant. Defaults to the current time.
+ * @returns The update fields.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function markCalendarForSyncTemplate(now?: Maybe<Date>): MarkCalendarForSyncTemplate;
+/**
+ * Where a Calendar sits in the publish pipeline, as derived from the calendar itself.
+ *
+ * The read-side counterpart of {@link markCalendarForSyncTemplate}: it decodes the `s` / `sat` / `uat`
+ * invariant the sweep and the ICS processor maintain, so a reader never has to re-derive it (and never
+ * mistakes a stale `sat` for "the published feed is current").
+ */
+export declare enum CalendarSyncState {
+    /**
+     * The calendar's content has moved and no sweep has claimed it yet.
+     *
+     * `s` is set by {@link calendarTemplate}, {@link updateCalendarEventsTemplate} and
+     * {@link markCalendarForSyncTemplate}, so this is the state every content change lands in.
+     */
+    QUEUED = "queued",
+    /**
+     * A sweep cleared `s` but the ICS upload that writes `sat` has not landed yet.
+     *
+     * This is the `s === false && sat < uat` window the resync backstop self-heals, and it also covers a
+     * calendar whose first ICS has never published.
+     */
+    PUBLISHING = "publishing",
+    /**
+     * The published ICS reflects the calendar's current content.
+     */
+    SYNCED = "synced"
+}
+/**
+ * The fields {@link calendarSyncState} reads.
+ */
+export type CalendarSyncStateInput = Pick<Calendar, 's' | 'sat' | 'uat'>;
+/**
+ * Returns where a Calendar sits in the publish pipeline.
+ *
+ * `sat` ALONE is not "synced": it is the instant of the last successful upload, which says nothing about
+ * whether the content has moved since. Only `sat > uat` with the sync flag clear means the published feed
+ * matches the model.
+ *
+ * @param calendar - The calendar's sync flag, last publish instant and update instant.
+ * @returns The calendar's sync state.
+ *
+ * @example
+ * ```ts
+ * const isPublished = calendarSyncState(calendar) === CalendarSyncState.SYNCED;
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarSyncState(calendar: CalendarSyncStateInput): CalendarSyncState;
+/**
+ * How long a caller must wait between rotations of a Calendar's published ICS link.
+ *
+ * Rotation is rate-limited rather than free because it is DESTRUCTIVE to subscribers: the old url stops
+ * working, and every calendar client already holding it breaks until its owner re-subscribes. A run of
+ * rotations would also leave a trail of orphaned ICS objects while each replacement uploads.
+ *
+ * Twelve hours is chosen against the subscriber refresh cadence rather than against server cost — Google
+ * re-reads a subscribed feed only every 8-24 hours, so rotating faster than that guarantees a window where
+ * the feed a subscriber holds is already dead and its replacement has not been fetched yet.
+ *
+ * Only the default. An app wanting a different cadence passes its own value to both the server (which
+ * enforces the window) and the client (which counts down to it); both sides must use the same value, or the
+ * UI will offer a rotation the server rejects.
+ */
+export declare const DEFAULT_CALENDAR_ICS_ROTATE_THROTTLE_HOURS: Hours;
+/**
+ * The fields {@link calendarNextIcsRotateAt} reads.
+ */
+export type CalendarNextIcsRotateAtInput = Pick<Calendar, 'rat'>;
+/**
+ * Input for {@link calendarNextIcsRotateAt}.
+ */
+export interface CalendarNextIcsRotateAtConfig {
+    /**
+     * The calendar's last rotation instant, if any.
+     */
+    readonly calendar?: Maybe<CalendarNextIcsRotateAtInput>;
+    /**
+     * Overrides {@link DEFAULT_CALENDAR_ICS_ROTATE_THROTTLE_HOURS}.
+     */
+    readonly throttleHours?: Maybe<Hours>;
+}
+/**
+ * The earliest time a Calendar's published ICS link may be rotated again.
+ *
+ * Both the server (which enforces the throttle) and the client (which disables the action until then) derive
+ * the window from the same stored instant, so the UI cannot offer a rotation the server would reject.
+ *
+ * @param config - The calendar, and optionally a throttle window to use instead of the default.
+ * @returns The time the next rotation is allowed, or undefined when the link has never been rotated.
+ *
+ * @example
+ * ```ts
+ * const nextRotateAt = calendarNextIcsRotateAt({ calendar });
+ * const isThrottled = nextRotateAt != null && isAfter(nextRotateAt, new Date());
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarNextIcsRotateAt(config: CalendarNextIcsRotateAtConfig): Maybe<Date>;
+/**
+ * Whether a Calendar's published ICS link is still inside its rotation throttle window.
+ *
+ * The predicate half of {@link calendarNextIcsRotateAt}, and the one the server rejects on. A calendar that
+ * has never been rotated is never throttled, which `isThrottled()` already encodes by treating an absent
+ * `lastRunAt` as expired.
+ *
+ * @param config - The calendar, and optionally a throttle window to use instead of the default.
+ * @param now - Overrides the current time.
+ * @returns True while another rotation would be rejected.
+ *
+ * @example
+ * ```ts
+ * if (isCalendarIcsRotateThrottled({ calendar })) {
+ *   // the link was rotated too recently
+ * }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isCalendarIcsRotateThrottled(config: CalendarNextIcsRotateAtConfig, now?: Maybe<Date>): boolean;
+/**
+ * A partial event item update. The id is required, since it is what an upsert matches on.
+ */
+export type CalendarEventItemUpdate<T extends CalendarEventItem = CalendarEventItem> = Partial<T> & Pick<CalendarEventItem, 'id'>;
+/**
+ * Configuration for {@link upsertCalendarEventItems}.
+ */
+export interface UpsertCalendarEventItemsConfig {
+    /**
+     * The update instant, applied to `uat` (and `cat` for a newly inserted item). Defaults to the current time.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Merges updates into an event array, inserting an item whose id is not present yet.
+ *
+ * An update that changes something a subscriber can observe bumps `q` (SEQUENCE) and moves `uat`; an update
+ * that changes nothing leaves the item, and therefore the published feed, byte-identical.
+ *
+ * @param items - The current items.
+ * @param updates - The partial updates, each carrying the id it applies to.
+ * @param config - Optional update instant.
+ * @returns A new array, sorted ascending by start instant and unique by id.
+ *
+ * @example
+ * ```ts
+ * const events = upsertCalendarEventItems(calendar.e, [{ id: 'a', n: 'Renamed' }]);
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function upsertCalendarEventItems<T extends CalendarEventItem>(items: T[], updates: CalendarEventItemUpdate<T>[], config?: Maybe<UpsertCalendarEventItemsConfig>): T[];
+/**
+ * Configuration for {@link removeCalendarEventItems}.
+ */
+export interface RemoveCalendarEventItemsConfig {
+    /**
+     * If true, the items are SPLICED OUT rather than tombstoned.
+     *
+     * Only correct for an event that was never published: a subscriber that already holds the event has no way
+     * to learn it is gone once its VEVENT simply stops appearing in the feed.
+     */
+    readonly hard?: Maybe<boolean>;
+    /**
+     * The update instant. Defaults to the current time.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Removes events from an array.
+ *
+ * By default this TOMBSTONES: the item is marked `CANCELLED` and its `q` is bumped, which is the only way a
+ * published feed communicates a deletion to a client that already holds the event. Retention is what
+ * eventually drops the tombstone.
+ *
+ * @param items - The current items.
+ * @param ids - The ids to remove.
+ * @param config - Optional hard-remove flag and update instant.
+ * @returns A new array.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function removeCalendarEventItems<T extends CalendarEventItem>(items: T[], ids: ArrayOrValue<CalendarEventId>, config?: Maybe<RemoveCalendarEventItemsConfig>): T[];
+/**
+ * Finds a single event in a calendar by its id, looking in BOTH the one-off and the recurring arrays.
+ *
+ * The two arrays share one id space -- an id is unique within its calendar, not merely within its array --
+ * so a caller holding only an id (an emailed invite, a targeted update) has no way to know which array to
+ * look in, and no reason to care.
+ *
+ * @param calendar - The calendar to search.
+ * @param eventId - The id to find.
+ * @returns The matching event, or undefined.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemForId(calendar: Pick<Calendar, 'e' | 'r'>, eventId: CalendarEventId): Maybe<CalendarEventItem | CalendarRecurringEventItem>;
+/**
+ * Returns the events that were generated from the given model key.
+ *
+ * @param items - The current items.
+ * @param modelKey - The key to match on.
+ * @returns The matching events, in their original order.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemsForModelKey<T extends CalendarEventItem>(items: T[], modelKey: FirestoreModelKey): T[];
+/**
+ * Configuration for {@link replaceCalendarEventItemsForModelKey}.
+ */
+export interface ReplaceCalendarEventItemsForModelKeyConfig<T extends CalendarEventItem = CalendarEventItem> {
+    /**
+     * The key whose events are being replaced. Every item in {@link items} is stamped with it, so a caller
+     * cannot accidentally write events that the next replace would fail to find.
+     */
+    readonly modelKey: FirestoreModelKey;
+    /**
+     * The COMPLETE desired set of events for this key. Anything previously carrying the key and absent here is
+     * removed.
+     */
+    readonly items: CalendarEventItemUpdate<T>[];
+    /**
+     * If true, events dropped by the replacement are SPLICED OUT rather than tombstoned.
+     *
+     * Only correct when they were never published: a subscriber holding an event has no way to learn it is
+     * gone once its VEVENT simply stops appearing.
+     */
+    readonly hard?: Maybe<boolean>;
+    /**
+     * The update instant. Defaults to the current time.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Replaces the whole set of events belonging to one model key, leaving every other event untouched.
+ *
+ * This is the primitive a producer needs when it regenerates its events from source: it cannot know which
+ * generated ids it wrote last time, only which model they came from. Matching on {@link CalendarEventItem.m}
+ * rather than on `id` is what makes "publish the current state of this model" a single idempotent call.
+ *
+ * An event that survives the replacement is UPSERTED, so it keeps its `cat` and only bumps `q` / `uat` if
+ * something a subscriber can observe actually changed. An event that disappears is tombstoned by default.
+ *
+ * @param items - The current items.
+ * @param config - The model key, the complete desired set, and the removal mode.
+ * @returns A new array, sorted ascending by start instant and unique by id.
+ *
+ * @example
+ * ```ts
+ * const events = replaceCalendarEventItemsForModelKey(calendar.e, { modelKey: job.key, items: generated });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function replaceCalendarEventItemsForModelKey<T extends CalendarEventItem>(items: T[], config: ReplaceCalendarEventItemsForModelKeyConfig<T>): T[];
+/**
+ * Configuration for {@link updateCalendarEventsTemplate}.
+ */
+export interface UpdateCalendarEventsTemplateConfig {
+    /**
+     * The calendar's current events.
+     */
+    readonly calendar: Pick<Calendar, 'e' | 'r'>;
+    readonly upsertEvents?: Maybe<CalendarEventItemUpdate<CalendarEventItem>[]>;
+    readonly upsertRecurringEvents?: Maybe<CalendarEventItemUpdate<CalendarRecurringEventItem>[]>;
+    readonly removeEventIds?: Maybe<ArrayOrValue<CalendarEventId>>;
+    /**
+     * Replaces the COMPLETE set of events belonging to one model key, in both arrays.
+     *
+     * This is the "republish this model" path: the caller supplies what the model produces now and anything
+     * else previously carrying the key is removed. Applied BEFORE {@link removeEventIds}, so an explicit
+     * removal still wins.
+     */
+    readonly replaceForModelKey?: Maybe<ReplaceCalendarEventsForModelKey>;
+    readonly hardRemove?: Maybe<boolean>;
+    readonly now?: Maybe<Date>;
+}
+/**
+ * The complete desired event set for one model key, as consumed by {@link updateCalendarEventsTemplate}.
+ */
+export interface ReplaceCalendarEventsForModelKey {
+    readonly modelKey: FirestoreModelKey;
+    readonly events?: Maybe<CalendarEventItemUpdate<CalendarEventItem>[]>;
+    readonly recurringEvents?: Maybe<CalendarEventItemUpdate<CalendarRecurringEventItem>[]>;
+}
+/**
+ * The fields {@link updateCalendarEventsTemplate} produces.
+ */
+export type UpdateCalendarEventsTemplate = Pick<Calendar, 'e' | 'r' | 's' | 'uat'>;
+/**
+ * Builds the update a caller merges into its own `document.update()` to change a calendar's events.
+ *
+ * ALWAYS includes `s: true` and `uat`, so a caller cannot mutate events and forget to flag the calendar for
+ * sync — the invariant the whole publish pipeline rests on.
+ *
+ * @param config - The calendar's current events plus the upserts, replacements and removals to apply.
+ * @returns The update fields.
+ *
+ * @example
+ * ```ts
+ * await calendarDocument.update(updateCalendarEventsTemplate({ calendar, upsertEvents: [item] }));
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function updateCalendarEventsTemplate(config: UpdateCalendarEventsTemplateConfig): UpdateCalendarEventsTemplate;
+/**
+ * Input for {@link pruneCalendarEvents}.
+ */
+export interface PruneCalendarEventsInput {
+    readonly calendar: Pick<Calendar, 'e' | 'r'>;
+    readonly config: CalendarTypeConfig;
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Result of {@link pruneCalendarEvents}.
+ */
+export interface PruneCalendarEventsResult {
+    readonly e: CalendarEventItem[];
+    readonly r: CalendarRecurringEventItem[];
+    readonly prunedEventCount: number;
+    readonly prunedRecurringEventCount: number;
+    /**
+     * False when nothing was dropped.
+     *
+     * The sync transaction only writes `e` / `r` when this is true, otherwise every hourly sweep would rewrite
+     * both arrays — and burn a full document write — for nothing.
+     */
+    readonly changed: boolean;
+}
+/**
+ * Applies a {@link CalendarTypeConfig}'s retention policy to a calendar's events. Pure; performs no I/O.
+ *
+ * 1. Drops recurrences whose series ended before the recurrence cutoff. A forever recurrence is NEVER dropped.
+ * 2. Drops one-off events whose end instant is before the past cutoff.
+ * 3. If still over `maxEvents`, drops the oldest one-off events first, then the oldest-started recurrences.
+ *    Both arrays are already ascending by start, so this is a `slice`. A FUTURE-dated item is never dropped
+ *    before a past-dated one.
+ *
+ * @param input - The calendar's events, its type config, and the reference instant.
+ * @returns The retained events plus what was dropped.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function pruneCalendarEvents(input: PruneCalendarEventsInput): PruneCalendarEventsResult;
+/**
+ * Converts a Date into the unix seconds form stored inside a {@link CalendarRecurringEventItem.rex} array.
+ *
+ * @param date - The instant to encode.
+ * @returns The unix seconds value.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare const calendarEventItemExceptionDateValue: typeof unixDateTimeSecondsNumberFromDate;

package/src/lib/model/calendar/index.d.ts

@@ -0,0 +1,12 @@
+export * from './calendar.action';
+export * from './calendar.api.error';
+export * from './calendar.api';
+export * from './calendar.expand';
+export * from './calendar.ics';
+export * from './calendar.id';
+export * from './calendar.processing';
+export * from './calendar.query';
+export * from './calendar.schedule';
+export * from './calendar.type';
+export * from './calendar.util';
+export * from './calendar';