@dereekb/firebase-server 13.41.0 → 13.43.0

package/model/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.41.0",
+  "version": "13.43.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.43.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/firebase-server": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.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,123 @@
+import { type AppCalendarTypeConfigServiceRef, type CalendarDocument, type CalendarFirestoreCollections, type FlagStaleCalendarsForSyncParams, type FlagStaleCalendarsForSyncResult, type RotateCalendarIcsParams, type RotateCalendarIcsResult, type SyncAllFlaggedCalendarsParams, type SyncAllFlaggedCalendarsResult, type SyncCalendarParams, type SyncCalendarResult } from '@dereekb/firebase';
+import { type TransformAndValidateFunctionResult } from '@dereekb/model';
+import { type InjectionToken } from '@nestjs/common';
+import { type BaseStorageFileServerActionsContext } 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.
+ *
+ * Extends {@link BaseStorageFileServerActionsContext} because a Calendar's ICS feed IS a StorageFile: the
+ * sync and rotate paths re-flag it for processing, which builds a notification task. Taking the base
+ * context lets those paths build `processStorageFile` locally rather than injecting the whole
+ * StorageFileServerActions — and so keeps the Calendar module free of a StorageFileModule import.
+ */
+export interface BaseCalendarServerActionsContext extends BaseStorageFileServerActionsContext, CalendarFirestoreCollections {
+}
+/**
+ * Full context for the Calendar server actions, adding the type registry.
+ */
+export interface CalendarServerActionsContext extends BaseCalendarServerActionsContext, AppCalendarTypeConfigServiceRef {
+}
+/**
+ * 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,69 @@
+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';
+/**
+ * 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.
+ * @returns The fully assembled context.
+ */
+export declare function calendarServerActionsContextFactory(context: BaseCalendarServerActionsContext, appCalendarTypeConfigServiceInstance: AppCalendarTypeConfigService): 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)
+     *
+     * 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/formspace/formspace.action.server.d.ts

@@ -0,0 +1,192 @@
+import { type AppFormSpaceTypeConfigServiceRef, type DeleteFormSpaceParams, type ExpireAllExpiredFormSpacesParams, type ExpireAllExpiredFormSpacesResult, type FirestoreContextReference, type FormSpaceDocument, type FormSpaceFirestoreCollections, type FormSpaceId, type NotificationFirestoreCollections, type ProcessAllQueuedFormSpacesParams, type ProcessAllQueuedFormSpacesResult, type RemoveFormSpaceFileParams, type StorageFileFirestoreCollections, type SubmitFormSpaceParams, type SubmitFormSpaceResult, type CreateFormSpaceParams, type UpdateFormSpaceParams } from '@dereekb/firebase';
+import { type FirebaseServerActionsContext, type FirebaseServerAuthServiceRef } from '@dereekb/firebase-server';
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type TransformAndValidateFunctionResult } from '@dereekb/model';
+import { type InjectionToken } from '@nestjs/common';
+import { type NotificationExpediteServiceRef } from '../notification/notification.expedite.service';
+/**
+ * NestJS injection token for the {@link BaseFormSpaceServerActionsContext}.
+ */
+export declare const BASE_FORM_SPACE_SERVER_ACTION_CONTEXT_TOKEN: InjectionToken;
+/**
+ * NestJS injection token for the fully assembled {@link FormSpaceServerActionsContext}.
+ */
+export declare const FORM_SPACE_SERVER_ACTION_CONTEXT_TOKEN: InjectionToken;
+/**
+ * Default page size for {@link expireAllExpiredFormSpacesFactory}.
+ */
+export declare const DEFAULT_FORM_SPACE_EXPIRATION_SWEEP_PAGE_SIZE = 50;
+/**
+ * Default wall-clock budget for {@link expireAllExpiredFormSpacesFactory}: one minute.
+ */
+export declare const DEFAULT_FORM_SPACE_EXPIRATION_SWEEP_MAX_RUN_TIME: Milliseconds;
+/**
+ * Minimal context providing the Firebase infrastructure and Firestore collections every FormSpace server
+ * action needs.
+ */
+export interface BaseFormSpaceServerActionsContext extends FirebaseServerActionsContext, FormSpaceFirestoreCollections, StorageFileFirestoreCollections, NotificationFirestoreCollections, NotificationExpediteServiceRef, FirebaseServerAuthServiceRef, FirestoreContextReference {
+}
+/**
+ * Full context for the FormSpace server actions, adding the type registry.
+ */
+export interface FormSpaceServerActionsContext extends BaseFormSpaceServerActionsContext, AppFormSpaceTypeConfigServiceRef {
+}
+/**
+ * Extra input for {@link FormSpaceServerActions.createFormSpace}, supplied by the callable rather than by
+ * the caller: the space's owner is WHO IS CALLING, never a value in the request body.
+ */
+export interface CreateFormSpaceActionInput {
+    readonly uid: string;
+    readonly ownerKey?: Maybe<string>;
+    /**
+     * Create the space at THIS id rather than at a generated one.
+     *
+     * For the SHARED shape — one space per target model, reached by everyone who reaches the target — a
+     * generated id lets two concurrent callers each mint one, and neither sees the other's files. Deriving
+     * the id with {@link formSpaceIdForModel} makes the create idempotent and lets a client read the space
+     * with a plain `get` before it has ever called create.
+     */
+    readonly formSpaceId?: Maybe<FormSpaceId>;
+    /**
+     * Return the existing space when {@link formSpaceId} is already taken, instead of failing.
+     *
+     * Only meaningful alongside {@link formSpaceId} — a generated id can never collide.
+     */
+    readonly getOrCreate?: Maybe<boolean>;
+}
+/**
+ * Extra input for {@link FormSpaceServerActions.removeFormSpaceFile}, supplied by the callable rather than by
+ * the caller: WHO is removing decides which files they may remove, so it can never be a value in the request
+ * body.
+ */
+export interface RemoveFormSpaceFileActionInput {
+    /**
+     * The uid of the caller.
+     *
+     * A REQUIRED key with a nullable value, so a call site has to state it rather than inherit an unrestricted
+     * remove by forgetting an optional argument. A null uid is refused by any slot whose
+     * {@link FormSpaceFileAccess} is `'uploader'`, which is the fail-closed direction.
+     */
+    readonly uid: Maybe<string>;
+}
+/**
+ * The server actions for the FormSpace model.
+ *
+ * @see {@link formSpaceServerActions} for the concrete implementation factory.
+ */
+export declare abstract class FormSpaceServerActions {
+    abstract createFormSpace(params: CreateFormSpaceParams): Promise<TransformAndValidateFunctionResult<CreateFormSpaceParams, (input: CreateFormSpaceActionInput) => Promise<FormSpaceDocument>>>;
+    abstract updateFormSpace(params: UpdateFormSpaceParams): Promise<TransformAndValidateFunctionResult<UpdateFormSpaceParams, (formSpaceDocument: FormSpaceDocument) => Promise<FormSpaceDocument>>>;
+    abstract submitFormSpace(params: SubmitFormSpaceParams): Promise<TransformAndValidateFunctionResult<SubmitFormSpaceParams, (formSpaceDocument: FormSpaceDocument) => Promise<SubmitFormSpaceResult>>>;
+    abstract removeFormSpaceFile(params: RemoveFormSpaceFileParams): Promise<TransformAndValidateFunctionResult<RemoveFormSpaceFileParams, (formSpaceDocument: FormSpaceDocument, input: RemoveFormSpaceFileActionInput) => Promise<FormSpaceDocument>>>;
+    abstract deleteFormSpace(params: DeleteFormSpaceParams): Promise<TransformAndValidateFunctionResult<DeleteFormSpaceParams, (formSpaceDocument: FormSpaceDocument) => Promise<void>>>;
+    abstract processAllQueuedFormSpaces(params: ProcessAllQueuedFormSpacesParams): Promise<TransformAndValidateFunctionResult<ProcessAllQueuedFormSpacesParams, () => Promise<ProcessAllQueuedFormSpacesResult>>>;
+    abstract expireAllExpiredFormSpaces(params: ExpireAllExpiredFormSpacesParams): Promise<TransformAndValidateFunctionResult<ExpireAllExpiredFormSpacesParams, () => Promise<ExpireAllExpiredFormSpacesResult>>>;
+}
+/**
+ * Creates a concrete {@link FormSpaceServerActions} implementation from the given context.
+ *
+ * @param context - The fully assembled FormSpace server actions context.
+ * @returns The server actions.
+ */
+export declare function formSpaceServerActions(context: FormSpaceServerActionsContext): FormSpaceServerActions;
+/**
+ * Factory for the `createFormSpace` action.
+ *
+ * Rejects an unregistered {@link FormSpaceType} outright. This is the one place the registry is STRICT —
+ * a sweep over existing documents falls back to the default config so one bad document cannot take the
+ * pass down, but a space that could never be filled in or submitted should not be created at all.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that creates a FormSpace.
+ */
+export declare function createFormSpaceFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateFormSpaceParams<import("@dereekb/firebase").FormSpaceData>, ({ uid, ownerKey, formSpaceId, getOrCreate }: CreateFormSpaceActionInput) => Promise<FormSpaceDocument>, object, unknown>;
+/**
+ * Factory for the `updateFormSpace` action.
+ *
+ * `data` REPLACES the stored JSON rather than merging into it — the client owns the whole form, and a
+ * merge would make clearing a field impossible to express.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that updates a draft FormSpace.
+ */
+export declare function updateFormSpaceFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateFormSpaceParams<import("@dereekb/firebase").FormSpaceData>, (formSpaceDocument: FormSpaceDocument) => Promise<FormSpaceDocument>, object, unknown>;
+/**
+ * Factory for the `submitFormSpace` action.
+ *
+ * The LOCK is taken in a transaction; the processing task is created afterwards. That split is deliberate:
+ * `createOrRunUniqueNotificationDocument()` does not accept a transaction, since running a task inside one
+ * would hold the lock across the whole handler. A crash in between leaves the space in
+ * QUEUED_FOR_PROCESSING with no task, which {@link processAllQueuedFormSpacesFactory} is the backstop for.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that submits a FormSpace.
+ */
+export declare function submitFormSpaceFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<SubmitFormSpaceParams, (formSpaceDocument: FormSpaceDocument) => Promise<SubmitFormSpaceResult>, object, unknown>;
+/**
+ * Factory for the `removeFormSpaceFile` action.
+ *
+ * Drops one file from a slot. The StorageFile is FLAGGED, never deleted inline — the StorageFile delete
+ * sweep owns removing the object from GCS, and a second code path that removed it here is how an orphaned
+ * object gets left behind.
+ *
+ * `uc` is deliberately NOT decremented: it counts uploads ACCEPTED over the space's lifetime, and letting a
+ * remove refund it would turn `maxUploads` from a bound on work done into a bound on files retained, which
+ * an upload/remove loop could then evade entirely.
+ *
+ * The caller's `removeFile` ROLE opened the door; the type's {@link FormSpaceFileAccess} decides which files
+ * inside it are theirs. That second check is made HERE rather than in the callable because it is per-file
+ * and needs the space's own `f` array — the same snapshot the removal writes, read under the same
+ * transaction, so a concurrent supersede cannot slip a different file under the decision.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that removes one file from a draft FormSpace.
+ */
+export declare function removeFormSpaceFileFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<RemoveFormSpaceFileParams, (formSpaceDocument: FormSpaceDocument, input: RemoveFormSpaceFileActionInput) => Promise<FormSpaceDocument>, object, unknown>;
+/**
+ * Creates (or re-runs) the unique submission task for a FormSpace and records its key on `pn`.
+ *
+ * Shared by `submitFormSpace` and the queued backstop sweep, which is what makes the backstop safe to run
+ * against a space whose task already exists: the task is unique per space, so a second attempt resolves to
+ * the same document rather than racing a second processor.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns Queues one FormSpace, reporting the task key and whether this call created it.
+ */
+export declare function _queueFormSpaceForProcessingFactory(context: FormSpaceServerActionsContext): (formSpaceDocument: FormSpaceDocument, runImmediately?: Maybe<boolean>) => Promise<SubmitFormSpaceResult>;
+/**
+ * Factory for the `deleteFormSpace` action.
+ *
+ * Files are FLAGGED, not deleted: the StorageFile delete sweep owns removing the object from GCS, and
+ * duplicating that here would mean a second code path that can leave an orphaned object behind.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that deletes a FormSpace and flags its files.
+ */
+export declare function deleteFormSpaceFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<DeleteFormSpaceParams, (formSpaceDocument: FormSpaceDocument) => Promise<void>, object, unknown>;
+/**
+ * Factory for the `processAllQueuedFormSpaces` action.
+ *
+ * The BACKSTOP for a submission whose task creation was lost between the lock transaction and the task
+ * write. It is safe to run against a space whose task already exists because the task is unique per space.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that returns batch processing results.
+ */
+export declare function processAllQueuedFormSpacesFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ProcessAllQueuedFormSpacesParams, () => Promise<ProcessAllQueuedFormSpacesResult>, object, unknown>;
+/**
+ * Factory for the `expireAllExpiredFormSpaces` action.
+ *
+ * A PAGED sweep with a pinned cutoff and a hard time budget, copying `openRouterRunTaskExpirationSweep`.
+ * `firestoreDate` persists an ISO8601 string, so Firestore's native TTL cannot be pointed at `eat` — this
+ * sweep is the mechanism, not a stopgap.
+ *
+ * No cursor is needed and one would be meaningless: expiring a page clears its `eat`, so the page no
+ * longer matches and re-running the query IS the next page. An empty page is therefore the only "done"
+ * signal, which is why the cutoff must be pinned — a cutoff advancing with the clock would let a space
+ * that ages mid-sweep join a page not yet reached, making the pass unbounded.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that expires due FormSpaces.
+ */
+export declare function expireAllExpiredFormSpacesFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ExpireAllExpiredFormSpacesParams, () => Promise<ExpireAllExpiredFormSpacesResult>, object, unknown>;

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

@@ -0,0 +1,91 @@
+import { type FormSpaceFileSlot, type FormSpaceId, type FormSpaceSubmitBlocker, type FormSpaceType, type FormSpaceUploadRejectionReason } from '@dereekb/firebase';
+/**
+ * Creates an error indicating the app never registered the requested {@link FormSpaceType}.
+ *
+ * @param formSpaceType - The unregistered type.
+ * @returns A bad-request HttpsError with the FORM_SPACE_TYPE_NOT_REGISTERED error code.
+ */
+export declare function formSpaceTypeNotRegisteredError(formSpaceType: FormSpaceType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the FormSpace is no longer a draft, so it cannot be changed.
+ *
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_NOT_EDITABLE error code.
+ */
+export declare function formSpaceNotEditableError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating a required upload slot is still empty at submission time.
+ *
+ * @param slots - The unsatisfied slots.
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_REQUIRED_SLOT_MISSING error code.
+ */
+export declare function formSpaceRequiredSlotMissingError(slots: FormSpaceFileSlot[]): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating a slot holds a file that failed validation.
+ *
+ * Carries the per-file reasons rather than only the slot names: "the slot is not acceptable" is not
+ * actionable, "scan.png is not a readable PDF" is.
+ *
+ * @param blockers - The invalid-file blockers reported by `formSpaceSubmitBlockers`.
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_HAS_INVALID_FILES error code.
+ */
+export declare function formSpaceHasInvalidFilesError(blockers: FormSpaceSubmitBlocker[]): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating a slot is still awaiting a validation verdict.
+ *
+ * @param slots - The slots still being validated.
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_VALIDATION_PENDING error code.
+ */
+export declare function formSpaceValidationPendingError(slots: FormSpaceFileSlot[]): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the slot does not hold the file that was asked to be removed.
+ *
+ * @param slot - The slot that was targeted.
+ * @returns A bad-request HttpsError with the FORM_SPACE_FILE_NOT_FOUND error code.
+ */
+export declare function formSpaceFileNotFoundError(slot: FormSpaceFileSlot): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the caller may reach the FormSpace but not this file of it.
+ *
+ * Deliberately NOT a plain forbidden: the caller passed the space-level role check, and what refused them is
+ * the type's `FormSpaceFileAccess` narrowing to the file's own uploader. A distinct code lets a client say
+ * "that is someone else's file" rather than "you cannot edit this form".
+ *
+ * @param slot - The slot holding the file.
+ * @returns A bad-request HttpsError with the FORM_SPACE_FILE_ACCESS_DENIED error code.
+ */
+export declare function formSpaceFileAccessDeniedError(slot: FormSpaceFileSlot): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the upload was rejected by the type's rules.
+ *
+ * @param reason - Why the upload was rejected.
+ * @returns A bad-request HttpsError with the FORM_SPACE_UPLOAD_NOT_ALLOWED error code.
+ */
+export declare function formSpaceUploadNotAllowedError(reason: FormSpaceUploadRejectionReason): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the uploader is not the user the FormSpace belongs to.
+ *
+ * @returns A bad-request HttpsError with the FORM_SPACE_UPLOAD_USER_MISMATCH error code.
+ */
+export declare function formSpaceUploadUserMismatchError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the referenced FormSpace does not exist.
+ *
+ * @returns An unavailable HttpsError with the FORM_SPACE_NOT_FOUND error code.
+ */
+export declare function formSpaceNotFoundError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating an explicit FormSpace id is already taken.
+ *
+ * @param formSpaceId - The id that already exists.
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_ALREADY_EXISTS error code.
+ */
+export declare function formSpaceAlreadyExistsError(formSpaceId: FormSpaceId): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating a get-or-create resolved to a space of a different type.
+ *
+ * @param formSpaceId - The id that resolved.
+ * @param expected - The type that was asked for.
+ * @param found - The type the existing space actually carries.
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_TYPE_MISMATCH error code.
+ */
+export declare function formSpaceTypeMismatchError(formSpaceId: FormSpaceId, expected: FormSpaceType, found: FormSpaceType): import("firebase-functions/https").HttpsError;

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

@@ -0,0 +1,57 @@
+import { type InjectionToken, type ModuleMetadata } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+import { AppFormSpaceTypeConfigService, type FormSpaceTypeConfig } from '@dereekb/firebase';
+import { type BaseFormSpaceServerActionsContext, FormSpaceServerActions, type FormSpaceServerActionsContext } from './formspace.action.server';
+/**
+ * NestJS injection token for the app's `FormSpaceTypeConfig[]` registry.
+ *
+ * Apps bind this token via {@link appFormSpaceModuleMetadata} by passing `formSpaceTypeConfigs`.
+ */
+export declare const FORM_SPACE_TYPE_CONFIGS_TOKEN: InjectionToken;
+/**
+ * Factory that builds the app's {@link AppFormSpaceTypeConfigService} from its registered configs.
+ *
+ * @param formSpaceTypeConfigs - The app's form space type registry.
+ * @returns The service.
+ */
+export declare function appFormSpaceTypeConfigServiceFactory(formSpaceTypeConfigs: FormSpaceTypeConfig[]): AppFormSpaceTypeConfigService;
+/**
+ * Factory that assembles the full {@link FormSpaceServerActionsContext}.
+ *
+ * @param context - The base context providing Firebase infrastructure and collections.
+ * @param appFormSpaceTypeConfigServiceInstance - The app's form space type registry service.
+ * @returns The fully assembled context.
+ */
+export declare function formSpaceServerActionsContextFactory(context: BaseFormSpaceServerActionsContext, appFormSpaceTypeConfigServiceInstance: AppFormSpaceTypeConfigService): FormSpaceServerActionsContext;
+/**
+ * Factory that creates a {@link FormSpaceServerActions} instance from the assembled context.
+ *
+ * @param context - The fully assembled form space server actions context.
+ * @returns The server actions.
+ */
+export declare function formSpaceServerActionsFactory(context: FormSpaceServerActionsContext): FormSpaceServerActions;
+export interface ProvideAppFormSpaceMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * The AppFormSpaceModule requires the following dependencies in order to initialize properly:
+     * - BaseFormSpaceServerActionsContext (BASE_FORM_SPACE_SERVER_ACTION_CONTEXT_TOKEN)
+     *
+     * 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 FormSpaceType} registry. Bound to {@link FORM_SPACE_TYPE_CONFIGS_TOKEN}.
+     */
+    readonly formSpaceTypeConfigs: FormSpaceTypeConfig[];
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's FormSpaceModule.
+ *
+ * By default this module exports:
+ * - FormSpaceServerActionsContext (FORM_SPACE_SERVER_ACTION_CONTEXT_TOKEN)
+ * - FormSpaceServerActions
+ * - AppFormSpaceTypeConfigService
+ *
+ * @param config - The module configuration.
+ * @returns The assembled {@link ModuleMetadata} for the form space module.
+ */
+export declare function appFormSpaceModuleMetadata(config: ProvideAppFormSpaceMetadataConfig): ModuleMetadata;