@dereekb/firebase-server 13.41.0 → 13.42.0

package/model/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.41.0",
-    "@dereekb/date": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/firebase-server": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/analytics": "13.42.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/firebase": "13.42.0",
+    "@dereekb/firebase-server": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",

package/model/src/lib/calendar/calendar.action.server.d.ts

@@ -0,0 +1,121 @@
+import { type AppCalendarTypeConfigServiceRef, type CalendarDocument, type CalendarFirestoreCollections, type FirestoreContextReference, type FlagStaleCalendarsForSyncParams, type FlagStaleCalendarsForSyncResult, type RotateCalendarIcsParams, type RotateCalendarIcsResult, type StorageFileFirestoreCollections, type SyncAllFlaggedCalendarsParams, type SyncAllFlaggedCalendarsResult, type SyncCalendarParams, type SyncCalendarResult } from '@dereekb/firebase';
+import { type FirebaseServerActionsContext, type FirebaseServerStorageServiceRef } from '@dereekb/firebase-server';
+import { type TransformAndValidateFunctionResult } from '@dereekb/model';
+import { type InjectionToken } from '@nestjs/common';
+import { type StorageFileServerActions } from '../storagefile/storagefile.action.server';
+/**
+ * NestJS injection token for the {@link BaseCalendarServerActionsContext}.
+ */
+export declare const BASE_CALENDAR_SERVER_ACTION_CONTEXT_TOKEN: InjectionToken;
+/**
+ * NestJS injection token for the fully assembled {@link CalendarServerActionsContext}.
+ */
+export declare const CALENDAR_SERVER_ACTION_CONTEXT_TOKEN: InjectionToken;
+/**
+ * Minimal context providing the Firebase infrastructure, storage and Firestore collections every Calendar
+ * server action needs.
+ */
+export interface BaseCalendarServerActionsContext extends FirebaseServerActionsContext, CalendarFirestoreCollections, StorageFileFirestoreCollections, FirebaseServerStorageServiceRef, FirestoreContextReference {
+}
+/**
+ * Full context for the Calendar server actions, adding the type registry and the StorageFile actions the
+ * sweep re-flags through.
+ */
+export interface CalendarServerActionsContext extends BaseCalendarServerActionsContext, AppCalendarTypeConfigServiceRef {
+    readonly storageFileServerActions: StorageFileServerActions;
+}
+/**
+ * The publish-side server actions for the Calendar model.
+ *
+ * PUBLISH-ONLY BY DESIGN. There is no `upsertCalendarEvents` / `removeCalendarEvents` action: a caller
+ * already holds a transaction and an accessor when it decides to touch a calendar, so an action that opened
+ * its own transaction would either fight the caller's or force an awkward split write. Callers merge the
+ * `calendar.util.ts` templates into their own write instead, and those templates carry the `s: true`
+ * invariant that makes this sweep correct.
+ *
+ * {@link CalendarServerActions.rotateCalendarIcs} is the one action with a callable surface
+ * (`calendar/update/rotateIcs`), since revoking a published feed url has to be reachable by its owner. It
+ * enforces no permission of its own — the callable's role gate is the authorization.
+ *
+ * @see {@link calendarServerActions} for the concrete implementation factory.
+ */
+export declare abstract class CalendarServerActions {
+    abstract syncCalendar(params: SyncCalendarParams): Promise<TransformAndValidateFunctionResult<SyncCalendarParams, (calendarDocument: CalendarDocument) => Promise<SyncCalendarResult>>>;
+    abstract rotateCalendarIcs(params: RotateCalendarIcsParams): Promise<TransformAndValidateFunctionResult<RotateCalendarIcsParams, (calendarDocument: CalendarDocument) => Promise<RotateCalendarIcsResult>>>;
+    abstract syncAllFlaggedCalendars(params: SyncAllFlaggedCalendarsParams): Promise<TransformAndValidateFunctionResult<SyncAllFlaggedCalendarsParams, () => Promise<SyncAllFlaggedCalendarsResult>>>;
+    abstract flagStaleCalendarsForSync(params: FlagStaleCalendarsForSyncParams): Promise<TransformAndValidateFunctionResult<FlagStaleCalendarsForSyncParams, () => Promise<FlagStaleCalendarsForSyncResult>>>;
+}
+/**
+ * Creates a concrete {@link CalendarServerActions} implementation from the given context.
+ *
+ * @param context - The fully assembled calendar server actions context.
+ * @returns The server actions.
+ */
+export declare function calendarServerActions(context: CalendarServerActionsContext): CalendarServerActions;
+/**
+ * Factory for the `syncCalendar` action, the Calendar counterpart of
+ * `regenerateStorageFileGroupContentFactory`.
+ *
+ * In ONE transaction it prunes the calendar, ensures its ICS StorageFile exists, and clears `s`. It does not
+ * write `sat` — that belongs to the processor's success path alone, which is what makes
+ * `s === false && sat < uat` mean "queued, not yet published" and lets `flagStaleCalendarsForSync()` heal a
+ * run that died in between.
+ *
+ * The re-flag of an EXISTING ICS StorageFile happens AFTER the transaction commits, through the public
+ * `processStorageFile` action rather than the by-convention-private in-transaction helper. That is safe
+ * precisely because of the invariant above: a lost re-flag self-heals within one resync interval instead of
+ * silently stranding the calendar.
+ *
+ * @param context - The calendar server actions context.
+ * @returns An async transform-and-validate function that syncs a single Calendar.
+ */
+export declare function syncCalendarFactory(context: CalendarServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<SyncCalendarParams, (calendarDocument: CalendarDocument) => Promise<SyncCalendarResult>, object, unknown>;
+/**
+ * Factory for the `rotateCalendarIcs` action: the REVOCATION primitive for a published feed url.
+ *
+ * A published feed url is a bearer credential — unguessable, but permanent until rotated, and stored by a
+ * subscriber (Google keeps it in the subscriber's account). Rotation is the only revocation available for a
+ * zero-auth feed, which is why it is a first-class action rather than a manual cleanup.
+ *
+ * It invents no new mechanism. `calendarIcsFileStoragePath()` keys the published object by the ICS
+ * StorageFile's OWN id, and `syncCalendarFactory` already mints a fresh StorageFile — new id, new path, new
+ * url — whenever the existing one is absent or QUEUED_FOR_DELETE. So in ONE transaction this simply:
+ *
+ * - flags the current ICS StorageFile for delete (the existing StorageFile delete machinery is what actually
+ *   removes the old object, and therefore what actually revokes the old url)
+ * - clears `isf` and `iu`, and sets `s: true`
+ *
+ * `syncCalendar` is then called immediately after the transaction commits, so the replacement exists without
+ * waiting for the hourly sweep — and its publish is EXPEDITED (`runImmediately`) rather than left queued, so
+ * `iu` normally holds the new url by the time this returns.
+ *
+ * That expedite is the difference between a rotation and any other sync. Every other path can afford to let
+ * the sweep publish, because the calendar still has a working url in the meantime. A rotation does not: it
+ * has already revoked the old one, so until the replacement uploads the user has NO link at all. Result
+ * field `publishedIcs` reports whether the inline publish landed; the sweep remains the backstop when it
+ * did not.
+ *
+ * @param context - The calendar server actions context.
+ * @returns An async transform-and-validate function that rotates a single Calendar's ICS link.
+ */
+export declare function rotateCalendarIcsFactory(context: CalendarServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<RotateCalendarIcsParams, (calendarDocument: CalendarDocument) => Promise<RotateCalendarIcsResult>, object, unknown>;
+/**
+ * Factory for the `syncAllFlaggedCalendars` action, the Calendar counterpart of
+ * `regenerateAllFlaggedStorageFileGroupsContentFactory`.
+ *
+ * @param context - The calendar server actions context.
+ * @returns An async transform-and-validate function that sweeps every flagged Calendar.
+ */
+export declare function syncAllFlaggedCalendarsFactory(context: CalendarServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<SyncAllFlaggedCalendarsParams, () => Promise<SyncAllFlaggedCalendarsResult>, object, unknown>;
+/**
+ * Factory for the `flagStaleCalendarsForSync` action: the self-healing backstop.
+ *
+ * For every registered {@link CalendarType} it re-flags Calendars whose last successful publish predates that
+ * type's resync interval. That covers a sweep that cleared `s` but whose ICS never finished publishing, and
+ * it keeps an `expand`-mode calendar from sliding off the end of its expansion window — with no extra field
+ * and no extra mechanism.
+ *
+ * @param context - The calendar server actions context.
+ * @returns An async transform-and-validate function that re-flags stale Calendars.
+ */
+export declare function flagStaleCalendarsForSyncFactory(context: CalendarServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<FlagStaleCalendarsForSyncParams, () => Promise<FlagStaleCalendarsForSyncResult>, object, unknown>;

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

@@ -0,0 +1,22 @@
+/**
+ * Creates an error indicating the Calendar module was configured without an ICS domain.
+ *
+ * @returns An internal-server HttpsError with the CALENDAR_ICS_DOMAIN_NOT_CONFIGURED error code.
+ */
+export declare function calendarIcsDomainNotConfiguredError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the Calendar's ICS StorageFile could not be resolved or created.
+ *
+ * @returns A precondition-conflict HttpsError with the CALENDAR_ICS_STORAGE_FILE_UNAVAILABLE error code.
+ */
+export declare function calendarIcsStorageFileUnavailableError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the Calendar's ICS link was rotated again before its throttle window passed.
+ *
+ * Thrown by the rotate action when the calendar's stored rotation instant is too recent. The client derives
+ * the same window from the same field, so reaching this error means the caller bypassed the UI.
+ *
+ * @param nextRotateAt - The time the next rotation is allowed.
+ * @returns A precondition-conflict HttpsError with the CALENDAR_ICS_ROTATE_THROTTLED error code.
+ */
+export declare function calendarIcsRotateThrottledError(nextRotateAt: Date): import("firebase-functions/https").HttpsError;

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

@@ -0,0 +1,72 @@
+import { type InjectionToken, type ModuleMetadata } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+import { AppCalendarTypeConfigService, type CalendarTypeConfig } from '@dereekb/firebase';
+import { type BaseCalendarServerActionsContext, CalendarServerActions, type CalendarServerActionsContext } from './calendar.action.server';
+import { StorageFileServerActions } from '../storagefile/storagefile.action.server';
+/**
+ * NestJS injection token for the app's `CalendarTypeConfig[]` registry.
+ *
+ * Apps bind this token via {@link appCalendarModuleMetadata} by passing `calendarTypeConfigs`.
+ */
+export declare const CALENDAR_TYPE_CONFIGS_TOKEN: InjectionToken;
+/**
+ * NestJS injection token for the domain every generated event UID is suffixed with.
+ */
+export declare const CALENDAR_ICS_DOMAIN_TOKEN: InjectionToken;
+/**
+ * Factory that builds the app's {@link AppCalendarTypeConfigService} from its registered configs.
+ *
+ * @param calendarTypeConfigs - The app's calendar type registry.
+ * @returns The service.
+ */
+export declare function appCalendarTypeConfigServiceFactory(calendarTypeConfigs: CalendarTypeConfig[]): AppCalendarTypeConfigService;
+/**
+ * Factory that assembles the full {@link CalendarServerActionsContext}.
+ *
+ * @param context - The base context providing Firebase infrastructure and collections.
+ * @param appCalendarTypeConfigServiceInstance - The app's calendar type registry service.
+ * @param storageFileServerActions - The StorageFile actions the sweep re-flags through.
+ * @returns The fully assembled context.
+ */
+export declare function calendarServerActionsContextFactory(context: BaseCalendarServerActionsContext, appCalendarTypeConfigServiceInstance: AppCalendarTypeConfigService, storageFileServerActions: StorageFileServerActions): CalendarServerActionsContext;
+/**
+ * Factory that creates a {@link CalendarServerActions} instance from the assembled context.
+ *
+ * @param context - The fully assembled calendar server actions context.
+ * @returns The server actions.
+ */
+export declare function calendarServerActionsFactory(context: CalendarServerActionsContext): CalendarServerActions;
+export interface ProvideAppCalendarMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * The AppCalendarModule requires the following dependencies in order to initialize properly:
+     * - BaseCalendarServerActionsContext (BASE_CALENDAR_SERVER_ACTION_CONTEXT_TOKEN)
+     * - StorageFileServerActions
+     *
+     * This module declaration makes it easier to import a module that exports those dependencies.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+    /**
+     * The app's {@link CalendarType} registry. Bound to {@link CALENDAR_TYPE_CONFIGS_TOKEN}.
+     */
+    readonly calendarTypeConfigs: CalendarTypeConfig[];
+    /**
+     * The domain every generated event UID is suffixed with. I.E. "example.com".
+     *
+     * REQUIRED: the UID 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 icsDomain: string;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's CalendarModule.
+ *
+ * By default this module exports:
+ * - CalendarServerActionsContext (CALENDAR_SERVER_ACTION_CONTEXT_TOKEN)
+ * - CalendarServerActions
+ * - AppCalendarTypeConfigService
+ * - CALENDAR_ICS_DOMAIN_TOKEN
+ *
+ * @param config - The module configuration.
+ * @returns The assembled {@link ModuleMetadata} for the calendar module.
+ */
+export declare function appCalendarModuleMetadata(config: ProvideAppCalendarMetadataConfig): ModuleMetadata;

package/model/src/lib/calendar/calendar.task.service.handler.d.ts

@@ -0,0 +1,52 @@
+import { type AppCalendarTypeConfigService, type CalendarFirestoreCollections, type CalendarIcsStorageFileProcessingSubtask, type CalendarIcsStorageFileProcessingSubtaskMetadata, type FirebaseStorageAccessor } from '@dereekb/firebase';
+import { type StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget } from '../storagefile/storagefile.task.service.handler';
+/**
+ * Cache-Control set on the published ICS object.
+ *
+ * A public GCS object otherwise defaults to `public, max-age=3600`, which lets a freshly regenerated feed be
+ * served stale from the edge for an hour on top of the subscriber's own polling lag. `Last-Modified` / `ETag`
+ * need no work here — GCS derives and serves them, and answers `304` to conditional GETs, automatically.
+ */
+export declare const CALENDAR_ICS_PUBLISHED_CACHE_CONTROL = "public, max-age=300, stale-while-revalidate=60";
+/**
+ * Content-Disposition set on the published ICS object.
+ *
+ * `attachment` because the STORED disposition is now the only one a downloader gets: the download button
+ * derives the public url client-side, and a public url — unlike a signed one, whose `responseDisposition`
+ * the button used to set per-request — carries no override. Without this a browser hands `text/calendar`
+ * straight to the OS calendar app rather than saving it.
+ *
+ * Harmless for the subscribe channel, which was the reason this was `inline`: a calendar client fetches the
+ * feed programmatically and ignores `Content-Disposition` entirely.
+ */
+export declare const CALENDAR_ICS_PUBLISHED_CONTENT_DISPOSITION = "attachment; filename=\"calendar.ics\"";
+/**
+ * Configuration for {@link calendarIcsStorageFileProcessingPurposeSubtaskProcessor}.
+ */
+export interface CalendarIcsStorageFileProcessingPurposeSubtaskProcessorConfig {
+    readonly calendarFirestoreCollections: CalendarFirestoreCollections;
+    readonly storageAccessor: FirebaseStorageAccessor;
+    readonly appCalendarTypeConfigService: AppCalendarTypeConfigService;
+    /**
+     * The domain every generated event UID is suffixed with.
+     */
+    readonly icsDomain: string;
+}
+/**
+ * Creates the ICS subtask processor for Calendar publishing.
+ *
+ * Far shorter than the StorageFileGroup zip processor, and deliberately so: there is no stream branch,
+ * because `FirebaseStorageAccessorFile.upload()` is non-optional while `uploadStream?` is not, and an ICS for
+ * a few hundred events is tens of kilobytes.
+ *
+ * It renders with `now: calendar.uat` rather than the wall clock, so DTSTAMP moves only when the content
+ * moves — which is what makes the output byte-identical for identical input. The processor is idempotent: a
+ * retry simply re-renders and re-uploads.
+ *
+ * The shared cleanup step then writes `ps: SUCCESS`, `pcat: now`, `pn: null`, which is exactly "the published
+ * ICS is uploaded and current".
+ *
+ * @param config - The collections, storage accessor, type registry, and UID domain.
+ * @returns A subtask processor config targeting the Calendar ICS purpose.
+ */
+export declare function calendarIcsStorageFileProcessingPurposeSubtaskProcessor(config: CalendarIcsStorageFileProcessingPurposeSubtaskProcessorConfig): StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget<CalendarIcsStorageFileProcessingSubtaskMetadata, CalendarIcsStorageFileProcessingSubtask>;

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

@@ -0,0 +1,4 @@
+export * from './calendar.action.server';
+export * from './calendar.error';
+export * from './calendar.module';
+export * from './calendar.task.service.handler';

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

@@ -1,3 +1,4 @@
+export * from './calendar';
 export * from './mailgun';
 export * from './notification';
 export * from './storagefile';

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

@@ -1,2 +1,3 @@
 export * from './notification.healthcheck.mailgun';
 export * from './notification.send.service.mailgun';
+export * from './notification.send.service.mailgun.attachment';

package/model/src/lib/mailgun/notification.send.service.mailgun.attachment.d.ts

@@ -0,0 +1,40 @@
+import { type Maybe } from '@dereekb/util';
+import { type MailgunFileAttachment } from '@dereekb/nestjs/mailgun';
+import { type NotificationMessageCalendarAttachment, type NotificationMessageCalendarAttachmentFactoryInput } from '@dereekb/firebase';
+/**
+ * @module notification.send.service.mailgun.attachment
+ *
+ * Bridges a notification message's iTIP calendar payload onto a Mailgun request as a calendar MIME part.
+ *
+ * The payload cannot ride a batched `to[]`: attachments live on the REQUEST, a `MailgunRecipient` has no
+ * per-recipient attachment slot, and a `METHOD:REQUEST` invite is only rendered inline by a client that
+ * finds its OWN address in the payload's ATTENDEE. A builder must therefore give a recipient with a payload
+ * a request of its own -- either by emitting one directly, or by setting the result on that recipient's
+ * `MailgunRecipientBatchSendTarget.attachments` and letting
+ * `expandMailgunRecipientBatchSendTargetRequestFactory()` expand it while the rest still batch.
+ */
+/**
+ * Converts a rendered iTIP calendar payload into the Mailgun attachment that carries it.
+ *
+ * The `contentType` is the whole point: a calendar part typed `text/calendar; method=REQUEST; charset=utf-8`
+ * is auto-processed as an invitation by Gmail, Outlook and Apple Mail, while the same bytes under Mailgun's
+ * default type render as an ordinary paperclip.
+ *
+ * @param calendarAttachment - The rendered payload.
+ * @returns The Mailgun attachment.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function notificationMessageCalendarAttachmentToMailgunFileAttachment(calendarAttachment: NotificationMessageCalendarAttachment): MailgunFileAttachment;
+/**
+ * Renders the message's calendar payload for one recipient and converts it to a Mailgun attachment.
+ *
+ * The single entry point a template builder needs: it reads the message's `calendarAttachmentFactory`,
+ * invokes it for the recipient, and returns `undefined` when the message carries no factory or the factory
+ * declines this recipient. That is the signal to batch the recipient normally rather than give it a request
+ * of its own; a non-undefined return belongs on that recipient's `MailgunRecipientBatchSendTarget.attachments`.
+ *
+ * @param input - The message and the address the payload's ATTENDEE must name.
+ * @returns The Mailgun attachment, or `undefined` when this recipient gets no calendar part.
+ */
+export declare function mailgunCalendarFileAttachmentForNotificationMessage(input: NotificationMessageCalendarAttachmentFactoryInput): Promise<Maybe<MailgunFileAttachment>>;

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

@@ -1,5 +1,6 @@
 import { type StorageFilePurposeUploadPolicy } from '@dereekb/firebase';
 import { type McpToolDetailsBuilder } from '@dereekb/firebase-server';
+import { type Maybe } from '@dereekb/util';
 /**
  * Config for {@link storageFileCreateSignedUploadUrlToolDetailsFactory}.
  */
@@ -30,3 +31,40 @@ export interface StorageFileCreateSignedUploadUrlToolDetailsFactoryConfig {
  * @__NO_SIDE_EFFECTS__
  */
 export declare function storageFileCreateSignedUploadUrlToolDetailsFactory(config: StorageFileCreateSignedUploadUrlToolDetailsFactoryConfig): McpToolDetailsBuilder;
+/**
+ * Config for {@link storageFileProcessToolDetailsFactory}.
+ */
+export interface StorageFileProcessToolDetailsFactoryConfig {
+    /**
+     * App-specific guidance appended to the generated description.
+     *
+     * Use this to describe what processing means for the app's own purposes — for example which
+     * purposes run a validation flow, and where that flow records its verdict.
+     */
+    readonly additionalGuidance?: Maybe<string>;
+}
+/**
+ * Builds the {@link McpToolDetailsBuilder} that customizes the MCP tool description for the
+ * `storageFileProcess` update-function.
+ *
+ * The generated description spells out which flag each processing state requires. The default
+ * schema-derived description cannot convey that a file whose processor ran to completion sits in
+ * the SUCCESS state even when the outcome was a rejection, so a caller re-validating a rejected
+ * file would otherwise reach for the flagless call and get an "already processed" error.
+ *
+ * The factory captures the description once at wiring time; the returned builder is a pure
+ * synchronous function called by the framework on every `tools/list` request.
+ *
+ * @param config - Optional factory config carrying app-specific guidance to append.
+ * @returns A builder that emits the state-aware tool description and leaves the input schema at its default.
+ *
+ * @example
+ * ```ts
+ * const toolDetails = storageFileProcessToolDetailsFactory({
+ *   additionalGuidance: 'The "resume" purpose records its verdict on the parent Profile.'
+ * });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function storageFileProcessToolDetailsFactory(config?: Maybe<StorageFileProcessToolDetailsFactoryConfig>): McpToolDetailsBuilder;

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

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

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

@@ -0,0 +1,144 @@
+import { type FirestoreDocument, type SchedulerSystemStateRead, type SystemState, type SystemStateFirestoreCollectionLike, type SystemStateStoredData } from '@dereekb/firebase';
+import { type Getter, type Hours, type Maybe } from '@dereekb/util';
+/**
+ * Configuration for a single gate evaluation.
+ */
+export interface SchedulerSystemStateGateConfig {
+    /**
+     * Run every Nth hour of the day.
+     *
+     * Matched by modulo against the hour-of-day, so only divisors of 24 divide the day evenly. See
+     * `isNthHourOfDay()` in `@dereekb/firebase`.
+     */
+    readonly everyNHours: Hours;
+}
+/**
+ * The outcome of a {@link SchedulerSystemStateAccessor.checkAndClaim} call.
+ *
+ * Extends {@link SchedulerSystemStateRead}, so past the pass/fail answer it is also the read the
+ * decision was made from: the same `now`, the same hour-of-day, and the same bound predicates. That
+ * is what lets a single hourly claim fan out into per-task sub-gates without a second read or a
+ * second clock —
+ *
+ * ```ts
+ * const gate = await schedulerSystemState.checkAndClaim({ everyNHours: 1 });
+ *
+ * if (!gate.claimed) {
+ *   return;
+ * }
+ *
+ * await hourlyWork();
+ *
+ * if (gate.isNthHourOfDay(3)) {
+ *   await everyThreeHoursWork();
+ * }
+ * ```
+ *
+ * NOTE: this is an object, so it is ALWAYS truthy. `if (await checkAndClaim(...))` always passes —
+ * branch on {@link SchedulerSystemStateClaim.claimed}.
+ *
+ * The inherited {@link SchedulerSystemStateRead} members describe the state as it was read BEFORE
+ * the claim was stamped, deliberately: `lastRunAt` is the previous claim, `hasRunInCurrentHour` is
+ * false on a successful claim, and `isOpen()` still answers for the other intervals this hour rather
+ * than reporting closed against the claim this very call just wrote.
+ */
+export interface SchedulerSystemStateClaim extends SchedulerSystemStateRead {
+    /**
+     * The interval the claim was evaluated for.
+     */
+    readonly everyNHours: Hours;
+    /**
+     * Whether THIS call claimed the hour, and so whether the caller may run its work.
+     */
+    readonly claimed: boolean;
+    /**
+     * The moment stamped as the new `lat`, or null when the gate was closed and nothing was written.
+     *
+     * Always equal to {@link SchedulerSystemStateRead.now} when {@link claimed} is true.
+     */
+    readonly claimedAt: Maybe<Date>;
+}
+/**
+ * Reads and claims the scheduler's hourly run gate.
+ */
+export interface SchedulerSystemStateAccessor {
+    /**
+     * Reads the gate state without claiming it.
+     *
+     * @returns The state, which can be evaluated against any number of intervals.
+     */
+    read(): Promise<SchedulerSystemStateRead>;
+    /**
+     * Reads, evaluates the gate for the given interval, and CLAIMS the hour, in one transaction.
+     *
+     * The claim is stamped BEFORE this resolves, deliberately: a crash or a function timeout in the
+     * caller's work must still cost the whole window. Otherwise the hourly cron degrades into an
+     * hourly retry loop against work that is already failing.
+     *
+     * Remember that one gate is one `lat`. Two callers with different `everyNHours` sharing the
+     * document will have whichever one passes first claim the hour for BOTH — the second gets
+     * `claimed: false` even if its own interval matched. That is the intended semantics of a single
+     * gate, but it is the thing a future second caller will trip over. Prefer claiming ONCE at the top
+     * of the schedule function and sub-gating the individual tasks off the returned
+     * {@link SchedulerSystemStateClaim}.
+     *
+     * @param config - The interval to evaluate.
+     * @returns The claim outcome, which also carries the read it was decided from.
+     */
+    checkAndClaim(config: SchedulerSystemStateGateConfig): Promise<SchedulerSystemStateClaim>;
+}
+/**
+ * Configuration for {@link schedulerSystemStateAccessorFactory}.
+ */
+export interface SchedulerSystemStateAccessorFactoryConfig {
+    /**
+     * Clock used to evaluate the gate and to stamp `lat`. Defaults to the current time.
+     *
+     * Overriding it is what lets a test place "now" at a specific hour-of-day — the gate is a
+     * modulo against the hour, so there is otherwise no way to exercise a non-matching hour without
+     * waiting for one.
+     */
+    readonly nowFactory?: Maybe<Getter<Date>>;
+}
+/**
+ * Creates a {@link SchedulerSystemStateAccessor} for a SystemState collection.
+ */
+export type SchedulerSystemStateAccessorFactory = <D extends FirestoreDocument<SystemState<SystemStateStoredData>>>(systemStateCollection: SystemStateFirestoreCollectionLike<SystemStateStoredData, D>) => SchedulerSystemStateAccessor;
+/**
+ * Creates a {@link SchedulerSystemStateAccessorFactory}, the Firestore-backed half of the scheduler's
+ * hourly run gate.
+ *
+ * The gate answers "should the scheduler run its Nth-hour body during this hour?" for the app as a
+ * whole, off the single `lat` on the `sys/scheduler` document. Claim it ONCE at the top of a
+ * schedule function; the individual tasks it guards carry no throttle of their own and sub-gate off
+ * the returned {@link SchedulerSystemStateClaim} instead.
+ *
+ * The collection MUST have `schedulerSystemDataConverter` registered under
+ * {@link SCHEDULER_SYSTEM_STATE_TYPE}. Without it the collection falls back to the pass-through
+ * converter and `lat` reads back as a raw Firestore `Timestamp`, which no hour comparison can match —
+ * so the gate would silently open on every call. {@link SchedulerSystemStateAccessor.read} and
+ * `checkAndClaim` throw on that rather than let it through.
+ *
+ * @param config - The clock override, if any.
+ * @returns A factory producing an accessor over a given SystemState collection.
+ *
+ * @example
+ * ```ts
+ * const schedulerSystemState = schedulerSystemStateAccessorFactory()(systemStateCollection);
+ *
+ * export const hourlySchedule: MyScheduleFunction = async (request) => {
+ *   const gate = await schedulerSystemState.checkAndClaim({ everyNHours: 1 });
+ *
+ *   if (!gate.claimed) {
+ *     return;
+ *   }
+ *
+ *   await hourlyWork();
+ *
+ *   if (gate.isNthHourOfDay(3)) {
+ *     await everyThreeHoursWork();
+ *   }
+ * };
+ * ```
+ */
+export declare function schedulerSystemStateAccessorFactory(config?: Maybe<SchedulerSystemStateAccessorFactoryConfig>): SchedulerSystemStateAccessorFactory;

package/oidc/index.esm.js

@@ -3625,7 +3625,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * @returns The union of config-level and profile-level admin-only scopes.
  */ function adminOnlyScopesForOidcProviderConfig(providerConfig) {
     var _providerConfig_adminOnlyScopes, _providerConfig_providerProfiles;
-    return new Set(_to_consumable_array$5((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []).concat(_to_consumable_array$5(adminOnlyScopesForOidcProviderProfiles((_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : []))));
+    return new Set(_to_consumable_array$5((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []).concat(_to_consumable_array$5(Array.from(adminOnlyScopesForOidcProviderProfiles((_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : [])))));
 }
 
 /**
@@ -6571,7 +6571,7 @@ var OidcInteractionController_1;
                                 effectiveOIDCScopes = resolveEffectiveSubset({
                                     missing: missingOIDCScope,
                                     requestedSubset: body.grantedOIDCScopes,
-                                    alwaysGranted: _to_consumable_array$1(ALWAYS_GRANTED_OIDC_SCOPES).concat(_to_consumable_array$1(clientRequiredScopes)),
+                                    alwaysGranted: _to_consumable_array$1(ALWAYS_GRANTED_OIDC_SCOPES).concat(_to_consumable_array$1(Array.from(clientRequiredScopes))),
                                     alreadyEncountered: encounteredOIDCScopes
                                 });
                                 // Scopes the existing Grant already holds (granted, minus any it rejected). Nothing here revokes

package/oidc/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.41.0",
-    "@dereekb/date": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/firebase-server": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
-    "@dereekb/zoho": "13.41.0",
+    "@dereekb/analytics": "13.42.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/firebase": "13.42.0",
+    "@dereekb/firebase-server": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
+    "@dereekb/zoho": "13.42.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.41.0",
+  "version": "13.42.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -58,17 +58,17 @@
   },
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.41.0",
-    "@dereekb/calcom": "13.41.0",
-    "@dereekb/date": "13.41.0",
-    "@dereekb/dbx-core": "13.41.0",
-    "@dereekb/discord": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
-    "@dereekb/zoho": "13.41.0",
+    "@dereekb/analytics": "13.42.0",
+    "@dereekb/calcom": "13.42.0",
+    "@dereekb/date": "13.42.0",
+    "@dereekb/dbx-core": "13.42.0",
+    "@dereekb/discord": "13.42.0",
+    "@dereekb/firebase": "13.42.0",
+    "@dereekb/model": "13.42.0",
+    "@dereekb/nestjs": "13.42.0",
+    "@dereekb/rxjs": "13.42.0",
+    "@dereekb/util": "13.42.0",
+    "@dereekb/zoho": "13.42.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/node": "2.0.0",