@dereekb/firebase 13.40.0 → 13.42.0

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

@@ -0,0 +1,322 @@
+import { type ArrayOrValue, type Maybe, type Minutes, type TimezoneString, type WebsiteUrl } from '@dereekb/util';
+import { type DateRange, type ICalendar, type ICalendarAttendee, type ICalendarAttendeeRole, type ICalendarEvent, type ICalendarExtraProperty, type ICalendarIcsString, type ICalendarMethod, type ICalendarOrganizer, type ICalendarParticipationStatus, type ICalendarSerializeConfig, type ICalendarUid, type ICalendarUidFactory } from '@dereekb/date';
+import { type Calendar, type CalendarEventItem, type CalendarRecurringEventItem } from './calendar';
+import { type CalendarExtensionData, type CalendarId } from './calendar.id';
+import { type CalendarIcsRecurrenceMode, type CalendarTypeConfig } from './calendar.type';
+import { type CalendarEventOccurrence } from './calendar.expand';
+/**
+ * @module calendar.ics
+ *
+ * Renders a {@link Calendar} into the `@dereekb/date` iCalendar model, and from there into an ICS document.
+ *
+ * The output is DETERMINISTIC for a fixed `now`: every property is emitted in a fixed order and no object
+ * keys are iterated in insertion order. That is what lets the publisher content-hash a payload and skip a
+ * no-op upload, and it is why the processor passes `now: calendar.uat` rather than `new Date()` — DTSTAMP
+ * then moves only when the content moves.
+ */
+/**
+ * The "X-" prefix an extension property name is given when it does not already carry one.
+ */
+export declare const CALENDAR_EXTENSION_PROPERTY_PREFIX = "X-";
+/**
+ * Converts a calendar's or event's {@link CalendarExtensionData} into iCalendar extra properties.
+ *
+ * The stored key is a SUFFIX: it is uppercased, stripped of anything outside `[A-Z0-9-]`, and prefixed with
+ * "X-" unless it already carries one. Storing the suffix and prefixing at emit time is what makes it
+ * impossible for stored data to shadow a standard property such as SUMMARY.
+ *
+ * Emitted in sorted key order, because `Record` iteration order is insertion order and data round-tripped
+ * through Firestore carries no insertion-order guarantee.
+ *
+ * @param data - The stored extension data.
+ * @returns The extra properties. Empty when nothing survives sanitization.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarExtensionDataToICalendarExtraProperties(data: Maybe<CalendarExtensionData>): ICalendarExtraProperty[];
+/**
+ * Configuration for {@link calendarToICalendar}.
+ */
+export interface CalendarToICalendarConfig {
+    /**
+     * The calendar's document id. Used as the UID prefix, so an event's UID stays stable across republishes.
+     */
+    readonly calendarId: CalendarId;
+    /**
+     * How recurring events are emitted. Defaults to {@link DEFAULT_CALENDAR_ICS_RECURRENCE_MODE}.
+     */
+    readonly recurrenceMode?: Maybe<CalendarIcsRecurrenceMode>;
+    /**
+     * The window expanded in `expand` mode. Defaults to the type config's expansion days around `now`.
+     */
+    readonly expansionRange?: Maybe<DateRange>;
+    /**
+     * The UID factory. Built from {@link domain} when absent.
+     */
+    readonly uidFactory?: Maybe<ICalendarUidFactory>;
+    /**
+     * The domain the UID factory is built around. REQUIRED when no {@link uidFactory} is supplied — the
+     * factory deliberately has no random fallback, since a UID that changes between publishes makes every
+     * client create a duplicate event rather than update the one it holds.
+     */
+    readonly domain?: Maybe<string>;
+    /**
+     * The canonical URL the feed is published at. Emitted as SOURCE.
+     */
+    readonly source?: Maybe<WebsiteUrl>;
+    /**
+     * Emitted as REFRESH-INTERVAL / X-PUBLISHED-TTL.
+     */
+    readonly refreshInterval?: Maybe<Minutes>;
+    /**
+     * Whether a VTIMEZONE is derived for every zone the events reference. Defaults to true.
+     *
+     * Free to leave on: the deriver returns the calendar unchanged when no zoned value exists.
+     */
+    readonly deriveTimezones?: Maybe<boolean>;
+    /**
+     * The reference instant for the default expansion window. Defaults to the current time.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Builds the {@link CalendarToICalendarConfig} fragment a {@link CalendarTypeConfig} contributes.
+ *
+ * @param config - The calendar type config.
+ * @returns The ICS emission settings it carries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarTypeConfigIcsConfig(config: CalendarTypeConfig): Pick<CalendarToICalendarConfig, 'recurrenceMode' | 'refreshInterval'>;
+/**
+ * Returns the expansion window used by `expand` mode when the caller supplies none.
+ *
+ * @param config - The calendar type config carrying the window sizes.
+ * @param now - The reference instant.
+ * @returns The expansion range.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarTypeConfigIcsExpansionRange(config: CalendarTypeConfig, now: Date): DateRange;
+/**
+ * The identity a single event item is rendered under.
+ */
+export interface CalendarEventItemToICalendarEventConfig {
+    /**
+     * The event's UID. Produced by the feed's UID factory, so a VEVENT rendered here and the same event in
+     * the published feed are the same event to a client rather than two.
+     */
+    readonly uid: ICalendarUid;
+    /**
+     * The timezone the event's wall clock is anchored to. Normally `calendarEventItemTimezone(item, calendar.tz)`.
+     */
+    readonly timezone: TimezoneString;
+}
+/**
+ * Renders a ONE-OFF event item as a VEVENT.
+ *
+ * Goes through `iCalendarEventForCalendarDate()`, which already handles the all-day `VALUE=DATE` path and
+ * RFC 5545 3.8.2.2's exclusive DTEND. A consequence worth knowing: a TIMED one-off emits UTC instants,
+ * because that factory has no zoned path. Deliberate -- it needs no VTIMEZONE and reads identically in
+ * every client.
+ *
+ * @param item - The stored event item.
+ * @param config - The UID and timezone to render it under.
+ * @returns The event.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemToICalendarEvent(item: CalendarEventItem, config: CalendarEventItemToICalendarEventConfig): ICalendarEvent;
+/**
+ * Renders a RECURRING event item as a single rule-bearing VEVENT.
+ *
+ * Gets a ZONED DTSTART when its timezone is not UTC. This is where it matters: a `FREQ=WEEKLY;BYDAY=MO`
+ * rule anchored to a UTC instant drifts across a DST boundary. It carries `duration`, never `end` -- the
+ * serializer prefers DTEND when both are set, and a per-series DTEND is wrong.
+ *
+ * @param item - The stored recurring event item.
+ * @param config - The UID and timezone to render it under.
+ * @returns The event.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarRecurringEventItemToICalendarEvent(item: CalendarRecurringEventItem, config: CalendarEventItemToICalendarEventConfig): ICalendarEvent;
+/**
+ * Converts a {@link Calendar} into the format-agnostic {@link ICalendar} model.
+ *
+ * - A ONE-OFF event goes through `iCalendarEventForCalendarDate()`, which already handles the all-day
+ *   `VALUE=DATE` path and RFC 5545 3.8.2.2's exclusive DTEND. A consequence worth knowing: a TIMED one-off
+ *   emits UTC instants, because that factory has no zoned path. Deliberate — it needs no VTIMEZONE and reads
+ *   identically in every client.
+ * - A RECURRING event gets a ZONED DTSTART when its timezone is not UTC. This is where it matters: a
+ *   `FREQ=WEEKLY;BYDAY=MO` rule anchored to a UTC instant drifts across a DST boundary. It carries
+ *   `duration`, never `end` — the serializer prefers DTEND when both are set, and a per-series DTEND is wrong.
+ * - `recurrenceMode: 'expand'` instead emits one VEVENT per occurrence, each carrying a RECURRENCE-ID.
+ *
+ * @param calendar - The calendar to render.
+ * @param config - The UID source, recurrence mode, and feed metadata.
+ * @returns The iCalendar model.
+ * @throws {Error} If neither a uidFactory nor a domain is supplied.
+ *
+ * @example
+ * ```ts
+ * const iCalendar = calendarToICalendar(calendar, { calendarId, domain: 'example.com' });
+ * ```
+ */
+export declare function calendarToICalendar(calendar: Calendar, config: CalendarToICalendarConfig): ICalendar;
+/**
+ * Converts a single expanded occurrence into a discrete VEVENT.
+ *
+ * Used by `expand` mode, and by any caller that wants one event per occurrence rather than a rule.
+ *
+ * @param occurrence - The occurrence to render.
+ * @param uidFactory - The UID factory, fed the occurrence's stable key.
+ * @returns The event.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventOccurrenceToICalendarEvent(occurrence: CalendarEventOccurrence, uidFactory: ICalendarUidFactory): ICalendarEvent;
+/**
+ * Renders a {@link Calendar} into a complete, folded, CRLF-terminated ICS document.
+ *
+ * @param calendar - The calendar to render.
+ * @param config - The iCalendar config plus serialization settings (notably `now`, the DTSTAMP source).
+ * @returns The ICS document.
+ *
+ * @example
+ * ```ts
+ * const ics = calendarToIcsString(calendar, { calendarId, domain: 'example.com', now: calendar.uat });
+ * ```
+ */
+export declare function calendarToIcsString(calendar: Calendar, config: CalendarToICalendarConfig & ICalendarSerializeConfig): ICalendarIcsString;
+/**
+ * The timezone treated as "no zone needed" when deciding whether a recurring DTSTART must be zoned.
+ */
+export declare const CALENDAR_ICS_DEFAULT_TIMEZONE = "UTC";
+/**
+ * The iTIP method an invite carries when its caller names none.
+ *
+ * REQUEST rather than PUBLISH deliberately: REQUEST is the only method that can ever carry a real RSVP, so
+ * starting here makes adding accept/decline later a parameter change rather than a redesign. The cost is
+ * that REQUEST needs an ATTENDEE matching the recipient's own address, which is what forces a sending
+ * service to emit one request per recipient rather than one batched request.
+ */
+export declare const DEFAULT_CALENDAR_INVITE_METHOD: ICalendarMethod;
+/**
+ * The PARTSTAT an invite attendee is given when its caller names none.
+ *
+ * Pre-accepting suppresses the RSVP prompt in most clients while still getting auto-add and a proper inline
+ * invitation card. A strong hint rather than a guarantee -- some clients render RSVP buttons regardless.
+ */
+export declare const DEFAULT_CALENDAR_INVITE_ATTENDEE_PARTICIPATION_STATUS: ICalendarParticipationStatus;
+/**
+ * The ROLE an invite attendee is given when its caller names none.
+ */
+export declare const DEFAULT_CALENDAR_INVITE_ATTENDEE_ROLE: ICalendarAttendeeRole;
+/**
+ * Configuration for {@link calendarEventItemToInviteICalendar} / {@link calendarEventItemToInviteIcsString}.
+ */
+export interface CalendarEventItemToInviteConfig {
+    /**
+     * The event to invite to. A recurring item (one carrying `rr`) is emitted as a single rule-bearing VEVENT,
+     * exactly as the feed emits it in `rule` mode.
+     */
+    readonly item: CalendarEventItem | CalendarRecurringEventItem;
+    /**
+     * The calendar's document id. The UID prefix, and it MUST be the same id the feed publishes the event
+     * under -- see {@link uidFactory}.
+     */
+    readonly calendarId: CalendarId;
+    /**
+     * The iTIP method. Defaults to {@link DEFAULT_CALENDAR_INVITE_METHOD}.
+     *
+     * CANCEL emits a CANCELLED status and, absent an explicit {@link sequence}, bumps the sequence -- see
+     * {@link sequence}.
+     */
+    readonly method?: Maybe<ICalendarMethod>;
+    /**
+     * Who the invite is from.
+     *
+     * Point this at a mailbox that ARCHIVES OR DISCARDS: we are the ORGANIZER, so inbound `METHOD:REPLY`
+     * mail is possible even when every attendee is sent `RSVP=FALSE`, and it will arrive at this address.
+     */
+    readonly organizer: ICalendarOrganizer;
+    /**
+     * Who the invite is to. Defaults are applied per attendee -- see
+     * {@link DEFAULT_CALENDAR_INVITE_ATTENDEE_PARTICIPATION_STATUS} and
+     * {@link DEFAULT_CALENDAR_INVITE_ATTENDEE_ROLE}.
+     *
+     * A REQUEST is only rendered inline by a client that finds ITS OWN address here, which is why an invite
+     * is built per recipient rather than once per notification.
+     */
+    readonly attendees: ArrayOrValue<ICalendarAttendee>;
+    /**
+     * SEQUENCE override.
+     *
+     * Defaults to the item's own revision counter (`q`), which the Calendar model already bumps on every
+     * change a subscriber can observe -- so an updated event re-sent under the same UID outranks the copy the
+     * client holds. Load-bearing: an update with a stale or absent SEQUENCE is SILENTLY IGNORED.
+     *
+     * For CANCEL the default is `q + 1` instead, so a cancellation always outranks the last REQUEST sent for
+     * the same revision. Pass an explicit value when the caller owns its own sequence source.
+     */
+    readonly sequence?: Maybe<number>;
+    /**
+     * The UID factory.
+     *
+     * MUST be the FEED's factory (or an identical one built from the feed's {@link domain}). A second UID
+     * scheme means a recipient who is both subscribed to the feed and holding the invite sees the event
+     * twice, and no update or cancellation reaches the invited copy.
+     */
+    readonly uidFactory?: Maybe<ICalendarUidFactory>;
+    /**
+     * The domain the UID factory is built around. REQUIRED when no {@link uidFactory} is supplied.
+     */
+    readonly domain?: Maybe<string>;
+    /**
+     * The timezone the event's wall clock is anchored to. Normally the parent calendar's `tz`. Defaults to
+     * {@link CALENDAR_ICS_DEFAULT_TIMEZONE}.
+     */
+    readonly timezone?: Maybe<TimezoneString>;
+    /**
+     * Optional display name for the enclosing VCALENDAR.
+     */
+    readonly name?: Maybe<string>;
+}
+/**
+ * Builds the single-event iTIP {@link ICalendar} an emailed invite carries.
+ *
+ * The counterpart to {@link calendarToICalendar}: same model, same UID scheme, one event, and a METHOD.
+ * The METHOD is what makes it an iTIP message (RFC 5546) rather than a feed -- which is right for an
+ * emailed attachment and wrong for a subscription, hence the two entry points.
+ *
+ * @param config - The event, the parties, and the UID source.
+ * @returns The iCalendar model.
+ * @throws {Error} If neither a uidFactory nor a domain is supplied.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarEventItemToInviteICalendar(config: CalendarEventItemToInviteConfig): ICalendar;
+/**
+ * Renders the emailed iTIP invite for a single event as a complete, folded, CRLF-terminated ICS document.
+ *
+ * The output is used directly as the calendar MIME part's data. The part must ALSO be typed
+ * `text/calendar; method=<method>; charset=utf-8` (see `iCalendarITipContentType()`) -- a client decides
+ * whether to auto-process from the part type, and the same bytes typed as an octet stream are a paperclip.
+ *
+ * @param config - The event, the parties, the UID source, and the DTSTAMP source.
+ * @returns The ICS document.
+ *
+ * @example
+ * ```ts
+ * const ics = calendarEventItemToInviteIcsString({
+ *   item,
+ *   calendarId,
+ *   domain: 'example.com',
+ *   organizer: { address: 'calendar@example.com', name: 'Example' },
+ *   attendees: { address: recipientEmail },
+ *   now: item.uat
+ * });
+ * ```
+ */
+export declare function calendarEventItemToInviteIcsString(config: CalendarEventItemToInviteConfig & ICalendarSerializeConfig): ICalendarIcsString;

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

@@ -0,0 +1,110 @@
+import { type FlatFirestoreModelKey, inferKeyFromTwoWayFlatFirestoreModelKey, twoWayFlatFirestoreModelKey, type FirestoreModelId, type FirestoreModelKey } from '../../common';
+/**
+ * @module calendar.id
+ *
+ * Identity types and id-generation patterns for the Calendar model.
+ *
+ * A Calendar that belongs to another model uses that model's key, two-way flat encoded, as its own document
+ * id — the same mechanism {@link StorageFileGroupId} uses. The profile "pr/abc123" therefore owns the
+ * calendar "cal/pr_abc123", loadable directly with no query and no lookup field.
+ *
+ * There is deliberately NO `modelKey` field on the Calendar itself: the id IS the association, and a
+ * queryable duplicate of it would be a second source of truth for the same fact.
+ */
+/**
+ * Firestore document id for a Calendar.
+ *
+ * For a Calendar that belongs to a model this is a {@link FlatFirestoreModelKey}; for a standalone
+ * calendar it is an arbitrary id.
+ */
+export type CalendarId = FirestoreModelId;
+/**
+ * Full Firestore document key (collection path + id) for a Calendar.
+ */
+export type CalendarKey = FirestoreModelKey;
+/**
+ * Identifier for a single event embedded in a Calendar. Unique within its own calendar only.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:calendar
+ */
+export type CalendarEventId = string;
+/**
+ * Identifier for a single expanded OCCURRENCE of a calendar event.
+ *
+ * A one-off event's occurrence key is its {@link CalendarEventId}. A recurring event's occurrence key is
+ * its id plus the occurrence's unix seconds, which is what keeps a published VEVENT's UID stable across
+ * republishes of the same series.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:calendar
+ */
+export type CalendarOccurrenceKey = string;
+/**
+ * Separates a recurring event's id from its occurrence's unix seconds within a {@link CalendarOccurrenceKey}.
+ */
+export declare const CALENDAR_OCCURRENCE_KEY_SEPARATOR = "_";
+/**
+ * Arbitrary string describing the kind of calendar a document is, driving its retention policy and its ICS
+ * emission config through the app's {@link CalendarTypeConfig} registry.
+ *
+ * Open by design, exactly like {@link StorageFilePurpose}: a downstream app registers its own types without
+ * a library change.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:calendar
+ */
+export type CalendarType = string;
+/**
+ * Arbitrary extension data attached to a Calendar or one of its events.
+ *
+ * THIS IS AN ICS EXTENSION LEVER, not general-purpose storage. Every entry is emitted as an "X-" property
+ * on the corresponding VCALENDAR/VEVENT, so values are STRINGS ONLY — an ICS property value simply is text.
+ * Anything structured is JSON-stringified into a single key by the caller.
+ *
+ * Keys are stored WITHOUT the "X-" prefix and are prefixed at emit time, which is what makes it impossible
+ * for a stored key to shadow a standard property like SUMMARY.
+ */
+export type CalendarExtensionData = Readonly<Record<string, string>>;
+/**
+ * The status of a calendar event, mirroring RFC 5545 3.8.1.11.
+ *
+ * CANCELLED is the only way a published feed communicates a deletion to a client that already holds the
+ * event, so removing an event tombstones it as CANCELLED rather than splicing it out.
+ */
+export declare enum CalendarEventStatus {
+    TENTATIVE = "TENTATIVE",
+    CONFIRMED = "CONFIRMED",
+    CANCELLED = "CANCELLED"
+}
+/**
+ * Encodes a {@link FirestoreModelKey} into the {@link CalendarId} of the Calendar that belongs to it.
+ *
+ * @example
+ * ```ts
+ * const calendarId = calendarIdForModel('pr/abc123'); // 'pr_abc123'
+ * ```
+ */
+export declare const calendarIdForModel: typeof twoWayFlatFirestoreModelKey;
+/**
+ * Decodes a {@link CalendarId} back into the {@link FirestoreModelKey} of the model it belongs to.
+ *
+ * Returns a meaningless value for a standalone calendar with a random id, exactly as
+ * {@link inferStorageFileGroupRelatedModelKey} does.
+ *
+ * @example
+ * ```ts
+ * const modelKey = inferCalendarRelatedModelKey('pr_abc123'); // 'pr/abc123'
+ * ```
+ */
+export declare const inferCalendarRelatedModelKey: typeof inferKeyFromTwoWayFlatFirestoreModelKey;
+/**
+ * A Calendar id that encodes the key of the model it belongs to.
+ */
+export type CalendarModelId = FlatFirestoreModelKey;

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

@@ -0,0 +1,77 @@
+import { type SlashPath, type SlashPathFolder } from '@dereekb/util';
+import { type StorageFileId, type StorageFileMetadata, type StorageFilePurpose } from '../storagefile/storagefile.id';
+import { type StorageFileProcessingSubtask, type StorageFileProcessingSubtaskMetadata } from '../storagefile/storagefile.task';
+import { type CalendarId } from './calendar.id';
+/**
+ * @module calendar.processing
+ *
+ * The StorageFile purpose that publishes a Calendar's ".ics", mirroring `storagefile.group.processing.ts`.
+ *
+ * DIVERGENCE FROM THE ZIP FLOW, stated explicitly: a StorageFileGroup's zip StorageFile uses
+ * {@link StorageFileCreationType.FOR_STORAGE_FILE_GROUP}, which derives a DETERMINISTIC document id from its
+ * parent group. A Calendar is not a StorageFileGroup, so its ICS StorageFile is `DIRECTLY_CREATED` and its id
+ * is carried on `Calendar.isf`. That is the `zsf` half of the pattern without the deterministic-key half.
+ *
+ * BECAUSE the id is non-deterministic, the ICS path is keyed by the STORAGE FILE's id, not the calendar's.
+ * A calendar-keyed path would let two StorageFiles resolve to the same object: when the previous ICS
+ * StorageFile is QUEUED_FOR_DELETE but not yet swept, the sync creates a replacement, and the sweep's
+ * `storageService.file(oldStorageFile).delete()` would then delete the REPLACEMENT's content while its own
+ * document still read SUCCESS — a hole `flagStaleCalendarsForSync()` cannot heal, since it compares `sat`
+ * against `uat` and `sat` is newer. A StorageFile-keyed path makes that collision unrepresentable, and has
+ * the side benefit that the published object is not guessable from the owner's uid.
+ */
+/**
+ * {@link StorageFilePurpose} identifier for a Calendar's published ICS file.
+ */
+export declare const CALENDAR_ICS_STORAGE_FILE_PURPOSE: StorageFilePurpose;
+/**
+ * Subtask checkpoint identifier for the ICS generation step of Calendar processing.
+ */
+export declare const CALENDAR_ICS_STORAGE_FILE_PURPOSE_GENERATE_ICS_SUBTASK: StorageFileProcessingSubtask;
+/**
+ * Type alias for the ICS generation subtask checkpoint string.
+ */
+export type CalendarIcsStorageFileProcessingSubtask = typeof CALENDAR_ICS_STORAGE_FILE_PURPOSE_GENERATE_ICS_SUBTASK;
+/**
+ * Metadata type for the ICS generation subtask.
+ */
+export type CalendarIcsStorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata;
+/**
+ * Metadata stored on the ICS StorageFile, linking it back to the Calendar it publishes.
+ *
+ * This is the ONLY link the processor has: the StorageFile is directly created, so its id carries no
+ * information about its calendar.
+ */
+export interface CalendarIcsStorageFileMetadata extends StorageFileMetadata {
+    /**
+     * Calendar id. Id of the Calendar this ICS file was generated for.
+     */
+    readonly cal: CalendarId;
+}
+/**
+ * Root folder in Firebase Storage where all Calendar-generated files are stored.
+ *
+ * Flat by design: a Calendar has exactly one derived artifact, so there is nothing for a per-calendar
+ * subfolder to group. Contrast `storageFileGroupFolderPath()`, whose variadic sub-path earns its keep
+ * because a group holds many derived files.
+ */
+export declare const CALENDAR_ROOT_FOLDER_PATH: SlashPathFolder;
+/**
+ * File extension of a Calendar's published ICS.
+ */
+export declare const CALENDAR_ICS_FILE_EXTENSION = ".ics";
+/**
+ * Returns the storage path for a Calendar's published ICS file.
+ *
+ * Keyed by the ICS StorageFile's OWN id rather than the calendar's, so two StorageFiles can never resolve
+ * to the same object — see this module's header for the deletion collision that would otherwise exist.
+ *
+ * @param storageFileId - The id of the StorageFile that holds the published ICS.
+ * @returns The full path to the calendar's ICS file.
+ *
+ * @example
+ * ```ts
+ * const icsPath = calendarIcsFileStoragePath('0mfR2xk8SqVe1Nb7'); // '/cal/0mfR2xk8SqVe1Nb7.ics'
+ * ```
+ */
+export declare function calendarIcsFileStoragePath(storageFileId: StorageFileId): SlashPath;

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

@@ -0,0 +1,76 @@
+import { type FirestoreQueryConstraint } from '../../common/firestore/query/constraint';
+import { type CalendarType } from './calendar.id';
+/**
+ * Returns query constraints for Calendars flagged for sync (`s == true`).
+ *
+ * This is what the hourly sweep iterates.
+ *
+ * @returns Firestore query constraints for Calendars flagged for sync.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel Calendar
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
+ * @example
+ * ```ts
+ * const constraints = calendarsFlaggedForSyncQuery();
+ * ```
+ */
+export declare function calendarsFlaggedForSyncQuery(): FirestoreQueryConstraint[];
+/**
+ * Input for {@link calendarsDueForResyncQuery}.
+ */
+export interface CalendarsDueForResyncQueryInput {
+    /**
+     * The type to sweep. Each type carries its own resync interval, so the backstop sweeps one type at a time.
+     */
+    readonly calendarType: CalendarType;
+    /**
+     * Calendars whose last successful publish predates this instant are due.
+     */
+    readonly before: Date;
+}
+/**
+ * Returns query constraints for Calendars of a type whose last successful publish (`sat`) is older than the
+ * given instant.
+ *
+ * This is the self-healing backstop: it catches a Calendar whose sweep cleared `s` but whose ICS never
+ * finished publishing, and it keeps an `expand`-mode calendar from sliding off the end of its expansion
+ * window without any extra field or mechanism.
+ *
+ * NOTE: a Firestore inequality skips documents where the field is absent, so a Calendar that has NEVER
+ * published is not matched here. That case is already covered — it still carries `s == true` until its first
+ * successful sweep, and the ICS StorageFile's own retry / stuck-detection owns everything after that.
+ *
+ * @param input - The type to sweep and the staleness cutoff.
+ * @returns Firestore query constraints for Calendars due for a resync.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel Calendar
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory maintenance
+ *
+ * @example
+ * ```ts
+ * const constraints = calendarsDueForResyncQuery({ calendarType: 'demo_profile', before: subDays(new Date(), 7) });
+ * ```
+ */
+export declare function calendarsDueForResyncQuery(input: CalendarsDueForResyncQueryInput): FirestoreQueryConstraint[];
+/**
+ * Returns query constraints for every Calendar of a given type.
+ *
+ * @param calendarType - The type to filter by.
+ * @returns Firestore query constraints for Calendars of the given type.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel Calendar
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
+ *
+ * @example
+ * ```ts
+ * const constraints = calendarsForTypeQuery('demo_profile');
+ * ```
+ */
+export declare function calendarsForTypeQuery(calendarType: CalendarType): FirestoreQueryConstraint[];

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

@@ -0,0 +1,82 @@
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { type FullDateCellScheduleRange } from '@dereekb/date';
+import { type FirestoreModelKey } from '../../common';
+import { type CalendarRecurringEventItem } from './calendar';
+import { type CalendarEventId, type CalendarEventStatus, type CalendarExtensionData } from './calendar.id';
+/**
+ * @module calendar.schedule
+ *
+ * Turns a `@dereekb/date` {@link FullDateCellScheduleRange} into a {@link CalendarRecurringEventItem}.
+ *
+ * This is the bridge that makes any model carrying a date-cell schedule publishable as calendar content. It
+ * is deliberately generic rather than living next to whichever model needs it first: nothing here knows what
+ * produced the schedule, only how a schedule becomes an event.
+ */
+/**
+ * Configuration for {@link calendarRecurringEventItemForScheduleRange}.
+ */
+export interface CalendarRecurringEventItemForScheduleRangeConfig {
+    /**
+     * The schedule to publish.
+     */
+    readonly range: FullDateCellScheduleRange;
+    /**
+     * Identifier for the generated event, unique within its calendar. Drives the published UID, so it must be
+     * STABLE across republishes of the same source model.
+     */
+    readonly id: CalendarEventId;
+    /**
+     * Key of the model this schedule came from. Set this to make the event replaceable as a set via
+     * `replaceCalendarEventItemsForModelKey()`.
+     */
+    readonly modelKey?: Maybe<FirestoreModelKey>;
+    /**
+     * Display name. Emitted as SUMMARY.
+     */
+    readonly name: string;
+    readonly description?: Maybe<string>;
+    readonly location?: Maybe<string>;
+    readonly url?: Maybe<WebsiteUrl>;
+    readonly status?: Maybe<CalendarEventStatus>;
+    readonly categories?: Maybe<string[]>;
+    readonly allDay?: Maybe<boolean>;
+    readonly extensionData?: Maybe<CalendarExtensionData>;
+    /**
+     * Emit `FREQ=DAILY` rather than `FREQ=WEEKLY` with all seven BYDAY tokens when every day is enabled.
+     * Defaults to true.
+     */
+    readonly preferDailyFrequency?: boolean;
+    /**
+     * The creation/update instant. Defaults to the current time.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Builds the recurring event that publishes a date-cell schedule.
+ *
+ * Returns undefined when the schedule yields no occurrences at all — an empty encoded week with no included
+ * days, or every day excluded. There is deliberately no "empty recurrence" value: an event whose rule
+ * produced nothing would still be retained and republished forever.
+ *
+ * EXCLUSIONS GO IN `rex`, NOT IN `rr`. The generator emits a self-contained rule with its own EXDATE line,
+ * but `calendarRecurringEventItemICalendarRecurrence()` (calendar.ics.ts) CONCATENATES the rule's exception
+ * dates with the ones from `rex` without deduplicating, so carrying them in both places emits every EXDATE
+ * twice. `rex` is the field the model documents for this, and keeping it there also holds `rr` to a single
+ * RRULE line plus an optional RDATE.
+ *
+ * @param config - The schedule, its identity, and the event's display metadata.
+ * @returns The recurring event, or undefined when the schedule has no occurrences.
+ *
+ * @example
+ * ```ts
+ * const item = calendarRecurringEventItemForScheduleRange({
+ *   range: fullDateCellScheduleRangeForJob(job),
+ *   id: job.id,
+ *   modelKey: jobDocument.key,
+ *   name: job.n
+ * });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function calendarRecurringEventItemForScheduleRange(config: CalendarRecurringEventItemForScheduleRangeConfig): Maybe<CalendarRecurringEventItem>;