@dereekb/firebase 13.40.0 → 13.42.0

package/src/lib/model/notification/notification.message.d.ts

@@ -9,6 +9,7 @@
  * before dispatching them through the configured delivery channels.
  */
 import { type PromiseOrValue, type Maybe, type WebsiteUrl, type NameEmailPair, type ArrayOrValue } from '@dereekb/util';
+import { type ICalendarIcsString, type ICalendarMethod } from '@dereekb/date';
 import { type NotificationRecipient, type NotificationRecipientWithConfig } from './notification.config';
 import { type NotificationSendFlags, type Notification, type NotificationBox } from './notification';
 import { type NotificationItem, type NotificationItemMetadata } from './notification.item';
@@ -102,6 +103,80 @@ export interface NotificationMessageContent {
      */
     readonly templateVariables?: Maybe<NotificationMessageTemplateVariables>;
 }
+/**
+ * The iTIP method a {@link NotificationMessageCalendarAttachment} may carry.
+ *
+ * Deliberately the whole of {@link ICalendarMethod}, including its open string branch. A notification
+ * USUALLY speaks as the organizer -- PUBLISH for an informational copy, REQUEST for an invitation or an
+ * update to one, ADD for extra instances of a recurring event, CANCEL to withdraw one, and DECLINECOUNTER
+ * to reject a proposed change -- but an app that sends ON BEHALF of an attendee has an equally real use
+ * for the attendee-to-organizer methods: REPLY to RSVP, REFRESH to ask for the latest copy, and COUNTER
+ * to propose one. Narrowing to the organizer set would put that behind a library change, and closing the
+ * union would also drop the `X-` extension methods {@link ICalendarMethod} intentionally leaves room for.
+ *
+ * The invariant worth enforcing is not WHICH method but that it agrees with the METHOD property inside
+ * the payload, which no type can express -- so this alias exists to document the choice rather than to
+ * constrain it.
+ */
+export type NotificationMessageCalendarAttachmentMethod = ICalendarMethod;
+/**
+ * A rendered iTIP calendar payload for a single recipient, for the sending service to bundle as a calendar
+ * MIME part on the outgoing email.
+ *
+ * Produced by a {@link NotificationMessageCalendarAttachmentFactory} at SEND time and never stored: it is
+ * not on `NotificationItem.d`, because the item is re-embedded verbatim into `NotificationSummary.n[]`
+ * (capped at 1000 items) and `NotificationWeek.n[]`, which each share a single 1 MiB document — an ICS
+ * blob in `d` would consume the summary's whole budget. Store the IDENTIFIERS in `d` and render the ICS
+ * from the message factory, which is async and holds the notification document.
+ */
+export interface NotificationMessageCalendarAttachment {
+    /**
+     * The rendered ICS document.
+     */
+    readonly ics: ICalendarIcsString;
+    /**
+     * The iTIP method the document carries. Duplicated onto the part's Content-Type by the sending service,
+     * as RFC 6047 requires, and it MUST agree with the METHOD property inside {@link ics}.
+     */
+    readonly method: NotificationMessageCalendarAttachmentMethod;
+    /**
+     * File name of the part. Defaults to "invite.ics" when the sending service is given none.
+     */
+    readonly filename?: Maybe<string>;
+}
+/**
+ * The file name given to a {@link NotificationMessageCalendarAttachment} that carries none.
+ */
+export declare const DEFAULT_NOTIFICATION_MESSAGE_CALENDAR_ATTACHMENT_FILENAME = "invite.ics";
+/**
+ * Input for a {@link NotificationMessageCalendarAttachmentFactory}.
+ */
+export interface NotificationMessageCalendarAttachmentFactoryInput {
+    /**
+     * The message the part is being built for.
+     */
+    readonly message: NotificationMessage;
+    /**
+     * The address the sending service has resolved for this recipient, and the address the payload's
+     * ATTENDEE must name.
+     *
+     * Load-bearing for a REQUEST: a client only renders an invitation inline when it finds ITS OWN address
+     * in the ATTENDEE, which is why the payload is built here rather than once per notification.
+     */
+    readonly recipient: NameEmailPair;
+}
+/**
+ * Renders the iTIP calendar payload for one recipient of a message.
+ *
+ * A factory rather than a value because the payload is per-recipient and transient: it is never
+ * serialized, it is only meaningful to a sending service that delivers email, and the ATTENDEE varies by
+ * recipient. Deferring the render to the sending service means one of these can be built once per
+ * notification, closing over the event, and the ICS is only produced for the recipients that actually
+ * receive an email.
+ *
+ * Return `undefined` to send the email without a calendar part.
+ */
+export type NotificationMessageCalendarAttachmentFactory = (input: NotificationMessageCalendarAttachmentFactoryInput) => PromiseOrValue<Maybe<NotificationMessageCalendarAttachment>>;
 export interface NotificationMessageEmailContent extends NotificationMessageContent {
     /**
      * Email subject. If not defined, defaults to the title.
@@ -133,6 +208,14 @@ export interface NotificationMessageEmailContent extends NotificationMessageCont
      * If the "replyTo" is present, this value acts as a fallback if the entity key returns no match.
      */
     readonly replyToEmail?: Maybe<NameEmailPair>;
+    /**
+     * Renders an iTIP calendar payload to bundle onto the email as a calendar MIME part.
+     *
+     * Opt-in per sending service, like every other field here: a builder that does not call it simply sends
+     * the email without the invite. A builder that DOES call it must give each recipient the payload names a
+     * request of its own, since attachments live on the request rather than the recipient.
+     */
+    readonly calendarAttachmentFactory?: Maybe<NotificationMessageCalendarAttachmentFactory>;
 }
 export interface NotificationMessageNotificationSummaryContent {
 }

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

@@ -13,6 +13,11 @@ import { type ArrayOrValue } from '@dereekb/util';
  * Used by the server to discover users whose configs need to be synced to their NotificationBox recipients.
  *
  * @returns Array of Firestore query constraints filtering for users needing sync.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel NotificationUser
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
  */
 export declare function notificationUsersFlaggedForNeedsSyncQuery(): FirestoreQueryConstraint[];
 /**
@@ -20,18 +25,34 @@ export declare function notificationUsersFlaggedForNeedsSyncQuery(): FirestoreQu
  *
  * @param exclusionId - One or more box IDs or collection name prefixes to match against.
  * @returns Array of Firestore query constraints filtering for users with matching exclusions.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel NotificationUser
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
+ * @dbxModelFirebaseIndexAllowArrayContainsAny
  */
 export declare function notificationUserHasExclusionQuery(exclusionId: ArrayOrValue<NotificationBoxSendExclusion>): FirestoreQueryConstraint[];
 /**
  * Query constraints for finding {@link NotificationSummary} documents that need server-side initialization (`s == true`).
  *
  * @returns Array of Firestore query constraints filtering for summaries needing initialization.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel NotificationSummary
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory init
  */
 export declare function notificationSummariesFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
 /**
  * Query constraints for finding {@link NotificationBox} documents that need server-side initialization (`s == true`).
  *
  * @returns Array of Firestore query constraints filtering for boxes needing initialization.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel NotificationBox
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory init
  */
 export declare function notificationBoxesFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
 /**
@@ -40,6 +61,11 @@ export declare function notificationBoxesFlaggedForNeedsInitializationQuery(): F
  * Used by the server to clean up boxes that could not be initialized.
  *
  * @returns Array of Firestore query constraints filtering for boxes flagged as invalid.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel NotificationBox
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory cleanup
  */
 export declare function notificationBoxesFlaggedInvalidQuery(): FirestoreQueryConstraint[];
 /**
@@ -50,6 +76,11 @@ export declare function notificationBoxesFlaggedInvalidQuery(): FirestoreQueryCo
  *
  * @param now - Reference time for the `sat` comparison (defaults to current time)
  * @returns Array of Firestore query constraints filtering for notifications past their scheduled send time.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel Notification
+ * @dbxModelFirebaseIndexScope COLLECTION_GROUP
+ * @dbxModelFirebaseIndexCategory sweep
  */
 export declare function notificationsPastSendAtTimeQuery(now?: Date): FirestoreQueryConstraint[];
 /**
@@ -57,6 +88,11 @@ export declare function notificationsPastSendAtTimeQuery(now?: Date): FirestoreQ
  * and ready to be archived to {@link NotificationWeek} and then deleted.
  *
  * @returns Array of Firestore query constraints filtering for completed notifications ready to archive.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel Notification
+ * @dbxModelFirebaseIndexScope COLLECTION_GROUP
+ * @dbxModelFirebaseIndexCategory cleanup
  */
 export declare function notificationsReadyForCleanupQuery(): FirestoreQueryConstraint[];
 /**
@@ -74,5 +110,10 @@ export declare function notificationsReadyForCleanupQuery(): FirestoreQueryConst
  * @param retentionDays - Number of days of history to retain; days strictly older than `now - retentionDays` match.
  * @param now - Reference time for the cutoff (defaults to current time)
  * @returns Array of Firestore query constraints filtering by the day string.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel NotificationLoggedEventDay
+ * @dbxModelFirebaseIndexScope COLLECTION_GROUP
+ * @dbxModelFirebaseIndexCategory cleanup
  */
 export declare function notificationLoggedEventDaysOlderThanQuery(retentionDays: number, now?: Date): FirestoreQueryConstraint[];

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

@@ -5,6 +5,11 @@ import { type OidcEntryType } from './oidcmodel';
  *
  * @param type - The OIDC entry type to filter by.
  * @returns Firestore query constraints for the given type.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel OidcEntry
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
  */
 export declare function oidcEntriesWithTypeQuery(type: OidcEntryType): FirestoreQueryConstraint[];
 /**
@@ -13,6 +18,11 @@ export declare function oidcEntriesWithTypeQuery(type: OidcEntryType): Firestore
  * @param type - The OIDC entry type to filter by.
  * @param userCode - The user code to match.
  * @returns Firestore query constraints for the given type and userCode.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel OidcEntry
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
  */
 export declare function oidcEntriesByUserCodeQuery(type: OidcEntryType, userCode: string): FirestoreQueryConstraint[];
 /**
@@ -21,6 +31,11 @@ export declare function oidcEntriesByUserCodeQuery(type: OidcEntryType, userCode
  * @param type - The OIDC entry type to filter by.
  * @param uid - The Firebase user ID to match.
  * @returns Firestore query constraints for the given type and uid.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel OidcEntry
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
  */
 export declare function oidcEntriesByUidQuery(type: OidcEntryType, uid: FirebaseAuthUserId): FirestoreQueryConstraint[];
 /**
@@ -29,6 +44,11 @@ export declare function oidcEntriesByUidQuery(type: OidcEntryType, uid: Firebase
  * @param type - The OIDC entry type to filter by.
  * @param grantId - The grant ID to match.
  * @returns Firestore query constraints for the given type and grantId.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel OidcEntry
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
  */
 export declare function oidcEntriesByGrantIdQuery(type: OidcEntryType, grantId: string): FirestoreQueryConstraint[];
 /**
@@ -37,6 +57,11 @@ export declare function oidcEntriesByGrantIdQuery(type: OidcEntryType, grantId:
  * @param type - The OIDC entry type to filter by.
  * @param clientId - The OAuth client ID to match.
  * @returns Firestore query constraints for the given type and clientId.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel OidcEntry
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
  */
 export declare function oidcEntriesByClientIdQuery(type: OidcEntryType, clientId: string): FirestoreQueryConstraint[];
 /**
@@ -44,6 +69,11 @@ export declare function oidcEntriesByClientIdQuery(type: OidcEntryType, clientId
  *
  * @param ownershipKey - The ownership key identifying the owner.
  * @returns Firestore query constraints for Client entries matching the ownership key.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel OidcEntry
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
  */
 export declare function oidcClientEntriesByOwnerQuery(ownershipKey: FirebaseAuthOwnershipKey): FirestoreQueryConstraint[];
 /**
@@ -54,5 +84,11 @@ export declare function oidcClientEntriesByOwnerQuery(ownershipKey: FirebaseAuth
  *
  * @param uid - The Firebase user id the grants were issued to.
  * @returns Firestore query constraints for Grant entries matching the uid.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel OidcEntry
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
+ * @dbxModelFirebaseIndexDispatcher true
  */
 export declare function oidcGrantEntriesByUidQuery(uid: FirebaseAuthUserId): FirestoreQueryConstraint[];

package/src/lib/model/storagefile/storagefile.api.d.ts

@@ -51,13 +51,34 @@ export declare const initializeStorageFileFromUploadParamsType: Type<InitializeS
 /**
  * Parameters for triggering processing of a specific StorageFile.
  *
- * Supports various modes: immediate processing, retry checking, force restart,
- * and reprocessing already-successful files. Validated with {@link processStorageFileParamsType}.
+ * Which flag is required depends on the file's current processing state. A `FAILED` file
+ * restarts with no flag, while a `SUCCESS` file needs `processAgainIfSuccessful` (or
+ * `forceRestartProcessing`) — note that a file whose processor ran to completion is `SUCCESS`
+ * even when the outcome was a rejection, so re-validating a rejected file normally needs one of
+ * those flags. `ARCHIVED` and `DO_NOT_PROCESS` files cannot be processed at all.
+ *
+ * Validated with {@link processStorageFileParamsType}.
  */
 export interface ProcessStorageFileParams extends TargetModelParams {
+    /**
+     * Runs the first step of the processing task inline instead of waiting for the scheduled task runner.
+     */
     readonly runImmediately?: Maybe<boolean>;
+    /**
+     * Checks an in-flight `PROCESSING` task immediately, instead of waiting for it to age past the
+     * stuck-check throttle.
+     */
     readonly checkRetryProcessing?: Maybe<boolean>;
+    /**
+     * Abandons the file's existing processing task and begins a new one, clearing the completed
+     * checkpoints so the flow runs again from the start. For a `PROCESSING` file this is only applied
+     * once the retry check runs, so pair it with `checkRetryProcessing` to force a restart while the
+     * existing task is still within the stuck-check throttle.
+     */
     readonly forceRestartProcessing?: Maybe<boolean>;
+    /**
+     * Allows processing a file that has already finished processing and is in the `SUCCESS` state.
+     */
     readonly processAgainIfSuccessful?: Maybe<boolean>;
 }
 export declare const processStorageFileParamsType: Type<ProcessStorageFileParams>;

package/src/lib/model/storagefile/storagefile.create.d.ts

@@ -5,7 +5,7 @@ import { type FirestoreDocumentAccessor } from '../../common/firestore/accessor/
 import { type FirebaseStorageAccessorFile } from '../../common/storage/driver/accessor';
 import { type StoragePathRef, type StoragePath } from '../../common/storage/storage';
 import { type FirebaseAuthOwnershipKey, type FirebaseAuthUserId } from '../../common/auth/auth';
-import { type StorageFilePurposeSubgroup, type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
+import { type StorageFilePurposeSubgroup, type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileId, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
 import { type ReadFirestoreModelKeyInput } from '../../common';
 /**
  * Input for creating a StorageFile document paired with its storage path.
@@ -13,8 +13,8 @@ import { type ReadFirestoreModelKeyInput } from '../../common';
  * Provides all the fields needed to create a fully-configured {@link StorageFile} Firestore document,
  * including ownership, purpose, group membership, and processing state.
  *
- * Either a `file`, `storagePathRef`, or `storagePath` must be provided to identify the storage location.
- * Either an `accessor` or `context` must be provided for Firestore document creation.
+ * Either a `file`, `storagePathRef`, `storagePath`, or `storagePathFactory` must be provided to identify the
+ * storage location. Either an `accessor` or `context` must be provided for Firestore document creation.
  *
  * @template M - type of arbitrary metadata stored in the `d` field
  */
@@ -43,6 +43,17 @@ export interface CreateStorageFileDocumentPairInput<M extends StorageFileMetadat
      * File to use when creating the StorageFile.
      */
     readonly file?: FirebaseStorageAccessorFile;
+    /**
+     * Builds the storage path from the id of the StorageFile document being created.
+     *
+     * Use this when the path should be keyed by the StorageFile itself rather than by the model it belongs
+     * to. Two StorageFiles then can never resolve to the same path, so replacing one cannot delete the
+     * other's content, and the path is not guessable from the owning model's id.
+     *
+     * Only consulted when no `file`, `storagePathRef`, or `storagePath` is provided, and only for a
+     * DIRECTLY_CREATED StorageFile — a FOR_STORAGE_FILE_GROUP file has a deterministic id by design.
+     */
+    readonly storagePathFactory?: Maybe<(storageFileId: StorageFileId) => StoragePath>;
     /**
      * The display name of the StorageFile.
      *

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

@@ -9,6 +9,11 @@ import { type FirebaseAuthUserId } from '../../common/auth/auth';
  *
  * @returns Firestore query constraints for StorageFiles queued for processing.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
  * @example
  * ```ts
  * const constraints = storageFilesQueuedForProcessingQuery();
@@ -24,6 +29,11 @@ export declare function storageFilesQueuedForProcessingQuery(): FirestoreQueryCo
  * @param now - Reference time for comparison; defaults to current time.
  * @returns Firestore query constraints for StorageFiles whose scheduled delete date has passed.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory cleanup
+ *
  * @example
  * ```ts
  * const constraints = storageFilesQueuedForDeleteQuery();
@@ -48,6 +58,12 @@ export interface StorageFilePurposeAndUserQueryInput {
  * @param input - The user, purpose, and optional subgroup to filter by.
  * @returns Firestore query constraints for the given purpose and user.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
+ * @dbxModelFirebaseIndexSkip true
+ *
  * @example
  * @example
  * ```ts
@@ -65,6 +81,11 @@ export declare function storageFilePurposeAndUserQuery(input: StorageFilePurpose
  *
  * @returns Firestore query constraints for StorageFiles flagged for group synchronization.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
  * @example
  * @example
  * ```ts
@@ -79,6 +100,11 @@ export declare function storageFileFlaggedForSyncWithGroupsQuery(): FirestoreQue
  *
  * @returns Firestore query constraints for StorageFileGroups needing initialization.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFileGroup
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory init
+ *
  * @example
  * @example
  * ```ts
@@ -91,6 +117,11 @@ export declare function storageFileGroupsFlaggedForNeedsInitializationQuery(): F
  *
  * @returns Firestore query constraints for StorageFileGroups flagged for content regeneration.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFileGroup
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
  * @example
  * @example
  * ```ts
@@ -105,6 +136,11 @@ export declare function storageFileGroupsFlaggedForContentRegenerationQuery(): F
  *
  * @returns Firestore query constraints for StorageFileGroups flagged as invalid.
  *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFileGroup
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory cleanup
+ *
  * @example
  * @example
  * ```ts

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

@@ -1,2 +1,3 @@
 export * from './system';
 export * from './system.action';
+export * from './system.scheduler';

package/src/lib/model/system/system.scheduler.d.ts

@@ -0,0 +1,235 @@
+/**
+ * @module system.scheduler
+ *
+ * Declares the framework-owned `scheduler` {@link SystemState} type, plus the pure predicates and
+ * the moment-bound read object that make up the "has this schedule already run in this hour?" gate.
+ *
+ * The gate exists so a cron that fires every hour can run a body that should only run every Nth
+ * hour, without each individual task having to carry a throttle of its own. Evaluate it ONCE at the
+ * top of a schedule function: pass, run the work; fail, return.
+ *
+ * The stateful half — read, evaluate, and claim the hour against Firestore — lives in
+ * `@dereekb/firebase-server/model` as `schedulerSystemStateAccessorFactory()`. Only the shape, the
+ * predicates, and {@link schedulerSystemStateRead} live here, so the evaluation can be exercised
+ * without an emulator and the converter can be registered from an app's client-shared converter
+ * map.
+ */
+import { type HourOfDay, type Hours, type Maybe } from '@dereekb/util';
+import { type FirestoreDocument, type FirestoreDocumentAccessor } from '../../common';
+import { type SystemState, type SystemStateDocument, type SystemStateStoredData, type SystemStateStoredDataFieldConverterConfig } from './system';
+/**
+ * {@link SystemState} type identifier for the scheduler's run-gate state.
+ *
+ * Also the document id, per the SystemState singleton convention — so this state lives at
+ * `sys/scheduler`.
+ */
+export declare const SCHEDULER_SYSTEM_STATE_TYPE = "scheduler";
+/**
+ * Scheduler state for gating scheduled work to at most one run per hour window.
+ *
+ * ONE gate, ONE `lat`. This is deliberately not per-task and not per-table state: it answers
+ * "has the scheduler already run its Nth-hour body during this hour?" for the app as a whole. Two
+ * callers sharing the document with different `everyNHours` values will have whichever one passes
+ * first claim the hour for both.
+ *
+ * @dbxModelSubObject
+ */
+export interface SchedulerSystemData extends SystemStateStoredData {
+    /**
+     * Last run at. The single gate anchor — the moment the most recent passing check claimed its hour.
+     *
+     * @dbxModelVariable lastRunAt
+     */
+    lat?: Maybe<Date>;
+}
+/**
+ * Firestore field converter for {@link SchedulerSystemData}.
+ *
+ * Register it in the app's `SystemStateStoredDataConverterMap` under
+ * {@link SCHEDULER_SYSTEM_STATE_TYPE}. This is NOT optional: without it the collection falls back to
+ * the pass-through converter, `lat` reads back as a raw Firestore `Timestamp` instead of a `Date`,
+ * and {@link hasRunInCurrentHour} can never match — so the gate would open on every single call.
+ */
+export declare const schedulerSystemDataConverter: SystemStateStoredDataFieldConverterConfig<SchedulerSystemData>;
+/**
+ * Loads the {@link SystemStateDocument} that stores {@link SchedulerSystemData}, using
+ * {@link SCHEDULER_SYSTEM_STATE_TYPE} as the document id.
+ *
+ * @param accessor - The document accessor for the SystemState collection.
+ * @returns The SystemState document for the scheduler state.
+ *
+ * @example
+ * ```ts
+ * const doc = loadSchedulerSystemState(systemStateCollection.documentAccessor());
+ * const data = await doc.snapshotData();
+ * ```
+ */
+export declare function loadSchedulerSystemState<D extends FirestoreDocument<SystemState<SystemStateStoredData>>>(accessor: FirestoreDocumentAccessor<SystemState<SystemStateStoredData>, D>): SystemStateDocument<SchedulerSystemData>;
+/**
+ * Whether the date's hour-of-day is an Nth hour, in the ambient timezone.
+ *
+ * This is a modulo against the hour-of-day, NOT an interval since some epoch — so at hour 12 it is
+ * true for N = 1, 2, 3, 4, 6, and 12, and false for N = 5. Only divisors of 24 divide the day
+ * evenly; a non-divisor (5, 7, 9, …) will still fire, just with a short window across midnight.
+ *
+ * An `everyNHours` of zero or less has no meaningful Nth hour and returns false rather than
+ * dividing by zero.
+ *
+ * @param everyNHours - Run every Nth hour of the day.
+ * @param date - Moment to test; defaults to now.
+ * @returns True when the date's hour-of-day is an Nth hour.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags schedule, hour, throttle, cron, gate, modulo
+ * @dbxUtilRelated has-run-in-current-hour
+ *
+ * @example
+ * ```ts
+ * isNthHourOfDay(3, new Date('2024-01-01T12:30:00')); // true (12 % 3 === 0)
+ * isNthHourOfDay(5, new Date('2024-01-01T12:30:00')); // false (12 % 5 === 2)
+ * ```
+ */
+export declare function isNthHourOfDay(everyNHours: Hours, date?: Maybe<Date>): boolean;
+/**
+ * Whether the last run falls inside the same hour as now.
+ *
+ * This is a same-hour-bucket compare, not an elapsed-time compare: a run at 12:59 and a `now` of
+ * 13:01 are two minutes apart but in different hours, so this returns false. That is what makes the
+ * gate track the hourly cron rather than drift with it.
+ *
+ * A null `lastRunAt` means nothing has run, so it returns false.
+ *
+ * @param lastRunAt - Moment the work last ran.
+ * @param now - Moment to compare against; defaults to now.
+ * @returns True when both moments fall in the same hour.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags schedule, hour, throttle, cron, gate, window
+ * @dbxUtilRelated is-nth-hour-of-day, round-down-to-hour
+ *
+ * @example
+ * ```ts
+ * hasRunInCurrentHour(new Date('2024-01-01T12:05:00'), new Date('2024-01-01T12:55:00')); // true
+ * hasRunInCurrentHour(new Date('2024-01-01T12:59:00'), new Date('2024-01-01T13:01:00')); // false
+ * ```
+ */
+export declare function hasRunInCurrentHour(lastRunAt: Maybe<Date>, now?: Maybe<Date>): boolean;
+/**
+ * The zero-based index of the date's hour within the day's every-N-hours schedule, or null when the
+ * hour is not an Nth hour.
+ *
+ * At hour 12 with N=3 the day's matching hours are 0, 3, 6, 9, 12 — so the index is 4. Use it to
+ * rotate work across a day's windows ("do the expensive pass only on index 0") without each caller
+ * re-deriving the arithmetic from the hour-of-day.
+ *
+ * Returns null rather than a number for a non-matching hour, so a falsy check cannot confuse
+ * "index 0" — the first window of the day — with "no window".
+ *
+ * @param everyNHours - Run every Nth hour of the day.
+ * @param date - Moment to test; defaults to now.
+ * @returns The zero-based window index, or null when the hour is not an Nth hour.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags schedule, hour, throttle, cron, gate, index, window
+ * @dbxUtilRelated is-nth-hour-of-day
+ *
+ * @example
+ * ```ts
+ * nthHourOfDayIndex(3, new Date('2024-01-01T12:30:00')); // 4 (0, 3, 6, 9, 12)
+ * nthHourOfDayIndex(3, new Date('2024-01-01T13:30:00')); // null (13 % 3 !== 0)
+ * ```
+ */
+export declare function nthHourOfDayIndex(everyNHours: Hours, date?: Maybe<Date>): Maybe<number>;
+/**
+ * A read of the scheduler's gate state, evaluated against a single moment.
+ *
+ * Holds the `now` and the `lastRunAt` it was built from, so every question below is answered against
+ * the same moment. Asking about N=2 and then N=3 cannot straddle an hour boundary mid-evaluation,
+ * and no question re-reads the document.
+ *
+ * This is the pure half of the gate. The Firestore-backed half — read, evaluate, and CLAIM the hour
+ * in a transaction — is `schedulerSystemStateAccessorFactory()` in `@dereekb/firebase-server/model`.
+ */
+export interface SchedulerSystemStateRead {
+    /**
+     * The moment this read was taken at.
+     */
+    readonly now: Date;
+    /**
+     * The hour-of-day of {@link SchedulerSystemStateRead.now}, in the ambient timezone.
+     */
+    readonly hourOfDay: HourOfDay;
+    /**
+     * The moment the most recent passing check claimed its hour, or null if the gate has never been
+     * claimed.
+     */
+    readonly lastRunAt: Maybe<Date>;
+    /**
+     * Whether {@link SchedulerSystemStateRead.lastRunAt} falls inside the same hour as `now` — that is,
+     * whether the gate has already been claimed during this hour.
+     */
+    readonly hasRunInCurrentHour: boolean;
+    /**
+     * Whether the gate is open for the given interval: `now` is an Nth hour of the day AND the gate
+     * has not already been claimed during this hour.
+     *
+     * This is a pure evaluation — it does NOT claim the hour. Use
+     * `SchedulerSystemStateAccessor.checkAndClaim()` to actually gate work.
+     *
+     * @param everyNHours - Run every Nth hour of the day.
+     * @returns True when the gate is open.
+     */
+    isOpen(everyNHours: Hours): boolean;
+    /**
+     * {@link isNthHourOfDay} bound to this read's `now`.
+     *
+     * Unlike {@link SchedulerSystemStateRead.isOpen} this ignores `lastRunAt` entirely, which is what
+     * makes it the right sub-gate for work running INSIDE an already-claimed hour: the hour is spent
+     * either way, so each task only needs to ask whether this is its hour.
+     *
+     * @param everyNHours - Run every Nth hour of the day.
+     * @returns True when this read's hour-of-day is an Nth hour.
+     */
+    isNthHourOfDay(everyNHours: Hours): boolean;
+    /**
+     * {@link nthHourOfDayIndex} bound to this read's `now`.
+     *
+     * @param everyNHours - Run every Nth hour of the day.
+     * @returns The zero-based window index, or null when this read's hour is not an Nth hour.
+     */
+    nthHourOfDayIndex(everyNHours: Hours): Maybe<number>;
+}
+/**
+ * Configuration for {@link schedulerSystemStateRead}.
+ */
+export interface SchedulerSystemStateReadConfig {
+    /**
+     * The moment to evaluate the gate against. Defaults to the current time.
+     */
+    readonly now?: Maybe<Date>;
+    /**
+     * The `lat` read off the scheduler document, or null/undefined when it has never been claimed.
+     */
+    readonly lastRunAt: Maybe<Date>;
+}
+/**
+ * Creates a {@link SchedulerSystemStateRead} from a moment and a last-run.
+ *
+ * Every predicate on the result closes over the single `now` resolved here, so a caller can ask
+ * about any number of intervals off one read without drifting across an hour boundary.
+ *
+ * @param config - The moment and the document's last-run.
+ * @returns The evaluated read.
+ *
+ * @example
+ * ```ts
+ * const read = schedulerSystemStateRead({ now, lastRunAt });
+ *
+ * read.isOpen(3); // should the every-3-hours body run?
+ * read.isNthHourOfDay(6); // is this also a 6th hour, for a sub-gated task?
+ * ```
+ */
+export declare function schedulerSystemStateRead(config: SchedulerSystemStateReadConfig): SchedulerSystemStateRead;