@dereekb/firebase-server 13.42.0 → 13.43.0

package/model/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@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/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

@@ -1,8 +1,7 @@
-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 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 StorageFileServerActions } from '../storagefile/storagefile.action.server';
+import { type BaseStorageFileServerActionsContext } from '../storagefile/storagefile.action.server';
 /**
  * NestJS injection token for the {@link BaseCalendarServerActionsContext}.
  */
@@ -14,15 +13,18 @@ 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 FirebaseServerActionsContext, CalendarFirestoreCollections, StorageFileFirestoreCollections, FirebaseServerStorageServiceRef, FirestoreContextReference {
+export interface BaseCalendarServerActionsContext extends BaseStorageFileServerActionsContext, CalendarFirestoreCollections {
 }
 /**
- * Full context for the Calendar server actions, adding the type registry and the StorageFile actions the
- * sweep re-flags through.
+ * Full context for the Calendar server actions, adding the type registry.
  */
 export interface CalendarServerActionsContext extends BaseCalendarServerActionsContext, AppCalendarTypeConfigServiceRef {
-    readonly storageFileServerActions: StorageFileServerActions;
 }
 /**
  * The publish-side server actions for the Calendar model.

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

@@ -2,7 +2,6 @@ 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.
  *
@@ -25,10 +24,9 @@ export declare function appCalendarTypeConfigServiceFactory(calendarTypeConfigs:
  *
  * @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;
+export declare function calendarServerActionsContextFactory(context: BaseCalendarServerActionsContext, appCalendarTypeConfigServiceInstance: AppCalendarTypeConfigService): CalendarServerActionsContext;
 /**
  * Factory that creates a {@link CalendarServerActions} instance from the assembled context.
  *
@@ -40,7 +38,6 @@ export interface ProvideAppCalendarMetadataConfig extends Pick<ModuleMetadata, '
     /**
      * 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.
      */

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;

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

@@ -0,0 +1,97 @@
+import { type FormSpace, type FormSpaceDocument, type FormSpaceFirestoreCollections, FormSpaceProcessingState, type FormSpaceSubmissionNotificationTaskData, type FormSpaceSubmissionSubtask, type FormSpaceSubmissionSubtaskMetadata } from '@dereekb/firebase';
+import { type Getter, type Maybe } from '@dereekb/util';
+import { type NotificationTaskServiceTaskHandlerConfig } from '../notification/notification.task.service.handler';
+import { type NotificationTaskSubtaskCleanupInstructions, type NotificationTaskSubtaskFlowEntry, type NotificationTaskSubtaskInput, type NotificationTaskSubtaskResult, type NotificationTaskSubtaskNotificationTaskHandlerConfig, type NotificationTaskSubtaskProcessorConfig } from '../notification/notification.task.subtask.handler';
+/**
+ * @module formspace.task.service.handler
+ *
+ * The submission-processing handler: one NotificationTask type dispatching, by {@link FormSpaceType}, to
+ * the app's registered processors.
+ *
+ * This is a thin specialization of {@link notificationTaskSubtaskNotificationTaskHandlerFactory}, exactly
+ * as `storageFileProcessingNotificationTaskHandler` is — the checkpoint / retry / delay semantics are the
+ * framework's, and the only thing FormSpace supplies is "how to load the space" and "what to write when
+ * processing concludes".
+ */
+/**
+ * Input handed to every FormSpace submission subtask.
+ *
+ * @template M - subtask metadata type
+ * @template S - subtask checkpoint string type
+ */
+export interface FormSpaceSubmissionSubtaskInput<M extends FormSpaceSubmissionSubtaskMetadata = FormSpaceSubmissionSubtaskMetadata, S extends FormSpaceSubmissionSubtask = FormSpaceSubmissionSubtask> extends NotificationTaskSubtaskInput<FormSpaceSubmissionNotificationTaskData<M, S>, M, S> {
+    /**
+     * The FormSpaceDocument being processed.
+     */
+    readonly formSpaceDocument: FormSpaceDocument;
+    /**
+     * Loads the FormSpace, memoized for the duration of one task run.
+     *
+     * A getter rather than the value: a processor whose first checkpoint never touches the form data should
+     * not pay for a read, and a processor that touches it in three checkpoints should pay for one.
+     */
+    readonly loadFormSpace: Getter<Promise<FormSpace>>;
+}
+/**
+ * Result of a FormSpace submission subtask.
+ */
+export type FormSpaceSubmissionSubtaskResult<M extends FormSpaceSubmissionSubtaskMetadata = FormSpaceSubmissionSubtaskMetadata, S extends FormSpaceSubmissionSubtask = FormSpaceSubmissionSubtask> = NotificationTaskSubtaskResult<M, S>;
+/**
+ * One entry in a FormSpace submission processor's checkpoint flow.
+ */
+export type FormSpaceSubmissionSubtaskFlowEntry<M extends FormSpaceSubmissionSubtaskMetadata = FormSpaceSubmissionSubtaskMetadata, S extends FormSpaceSubmissionSubtask = FormSpaceSubmissionSubtask> = NotificationTaskSubtaskFlowEntry<FormSpaceSubmissionSubtaskInput<M, S>, FormSpaceSubmissionNotificationTaskData<M, S>, M, S>;
+/**
+ * What a FormSpace submission processor asks the cleanup step to write.
+ */
+export interface FormSpaceSubmissionSubtaskCleanupOutput extends NotificationTaskSubtaskCleanupInstructions {
+    /**
+     * The processing state to leave the FormSpace in. Defaults to SUCCESS.
+     */
+    readonly nextProcessingState?: Maybe<FormSpaceProcessingState>;
+    /**
+     * Whether to move the space to ARCHIVED as part of cleanup. Defaults to false.
+     */
+    readonly archive?: Maybe<boolean>;
+}
+/**
+ * A processor for one {@link FormSpaceType}, keyed by that type as its subtask target.
+ *
+ * @template M - subtask metadata type
+ * @template S - subtask checkpoint string type
+ */
+export type FormSpaceSubmissionProcessorConfig<M extends FormSpaceSubmissionSubtaskMetadata = FormSpaceSubmissionSubtaskMetadata, S extends FormSpaceSubmissionSubtask = FormSpaceSubmissionSubtask> = NotificationTaskSubtaskProcessorConfig<FormSpaceSubmissionSubtaskInput<M, S>, FormSpaceSubmissionSubtaskCleanupOutput, FormSpaceSubmissionNotificationTaskData<M, S>, M, S>;
+/**
+ * Configuration for {@link formSpaceSubmissionNotificationTaskHandler}.
+ */
+export interface FormSpaceSubmissionNotificationTaskHandlerConfig extends Omit<NotificationTaskSubtaskNotificationTaskHandlerConfig<FormSpaceSubmissionSubtaskInput, FormSpaceSubmissionSubtaskCleanupOutput, FormSpaceSubmissionNotificationTaskData>, 'processors'> {
+    /**
+     * The per-type processors.
+     */
+    readonly processors: FormSpaceSubmissionProcessorConfig[];
+    /**
+     * Accessor for the FormSpace collection.
+     */
+    readonly formSpaceFirestoreCollections: FormSpaceFirestoreCollections;
+}
+/**
+ * The cleanup instructions applied when a processor asks for none: mark the submission successful.
+ *
+ * @returns The default cleanup instructions.
+ */
+export declare const formSpaceSubmissionNotificationTaskHandlerDefaultCleanup: () => FormSpaceSubmissionSubtaskCleanupOutput;
+/**
+ * Creates the {@link NotificationTaskServiceTaskHandlerConfig} that processes FormSpace submissions.
+ *
+ * @param config - Handler configuration including the per-type processors and the FormSpace collection.
+ * @returns A NotificationTaskServiceTaskHandlerConfig wired for FormSpace submission processing.
+ *
+ * @example
+ * ```ts
+ * const handler = formSpaceSubmissionNotificationTaskHandler({
+ *   processors: [demoExampleFormSpaceProcessor],
+ *   validate: DEMO_FORM_SPACE_TYPE_CONFIGS.map((x) => x.formSpaceType),
+ *   formSpaceFirestoreCollections: context
+ * });
+ * ```
+ */
+export declare function formSpaceSubmissionNotificationTaskHandler(config: FormSpaceSubmissionNotificationTaskHandlerConfig): NotificationTaskServiceTaskHandlerConfig<FormSpaceSubmissionNotificationTaskData>;

package/model/src/lib/formspace/formspace.upload.initializer.d.ts

@@ -0,0 +1,89 @@
+import { type FirebaseAuthUserId, type FormSpace, type FormSpaceFileSlot, type FormSpaceId } from '@dereekb/firebase';
+import { type Maybe, type PromiseOrValue } from '@dereekb/util';
+import { type StorageFileInitializeFromUploadServiceInitializer } from '../storagefile/storagefile.upload.service.initializer';
+import { type FormSpaceServerActionsContext } from './formspace.action.server';
+/**
+ * @module formspace.upload.initializer
+ *
+ * The AUTHORITATIVE upload gate for FormSpace files.
+ *
+ * `storage.rules` can enforce the outer size and content-type bound and can keep the write inside the
+ * uploader's own namespace, but it cannot read Firestore — so it cannot know whether the FormSpace exists,
+ * whether it is still a draft, whether this slot belongs to its type, or whether the space has already
+ * used up its upload budget. All of that is decided HERE, after the bytes have landed but before any
+ * StorageFile document exists, and a rejection returns a PERMANENT failure so the stray upload is deleted
+ * rather than retried forever.
+ */
+/**
+ * Input handed to a {@link FormSpaceUploadAuthorizationDelegate}.
+ */
+export interface FormSpaceUploadAuthorizationDelegateInput {
+    /**
+     * The space the bytes landed against, as loaded before any transaction.
+     */
+    readonly formSpace: FormSpace;
+    /**
+     * The space's id, as parsed from the upload path.
+     */
+    readonly formSpaceId: FormSpaceId;
+    /**
+     * The uid whose uploads folder the file landed in. Never equal to `formSpace.u` here.
+     */
+    readonly uploaderId: FirebaseAuthUserId;
+    /**
+     * The slot being filled.
+     */
+    readonly slot: FormSpaceFileSlot;
+}
+/**
+ * Decides whether an uploader who is NOT the space's own `u` may nonetheless upload into it.
+ *
+ * The DEFAULT FormSpace is single-user: `u` is set at creation, never changes, and is the only party that
+ * may upload into it. A SHARED space — one whose `o` names a model many users can reach — needs a second
+ * answer, and that answer is app policy (typically a read against some other collection), so it cannot live
+ * in this package.
+ *
+ * Consulted ONCE, BEFORE the claim transaction, and ONLY when `formSpace.u !== uploaderId`. Two
+ * consequences worth stating:
+ *
+ * - An owner's own upload never reaches the delegate, so a broken delegate cannot regress the single-user
+ *   path every existing FormSpaceType uses.
+ * - Resolving it outside the transactions is safe because the decision reads only `u`, `o` and `t`, none of
+ *   which ever change after creation. Inside `runTransaction` it would be re-run on every contention retry
+ *   and would still read outside the transaction's snapshot, so the transaction would buy nothing.
+ *
+ * Returning `false` is a DECISION: it becomes {@link formSpaceUploadUserMismatchError}, which
+ * {@link FORM_SPACE_UPLOAD_REFUSAL_ERROR_CODES} already classifies as a permanent refusal, so the stray
+ * upload is discarded rather than retried forever. THROWING is infrastructure: it falls through to the
+ * transient branch and the source is left for the next sweep.
+ */
+export type FormSpaceUploadAuthorizationDelegate = (input: FormSpaceUploadAuthorizationDelegateInput) => PromiseOrValue<boolean>;
+/**
+ * Configuration for {@link formSpaceStorageFileUploadInitializers}.
+ *
+ * Extends the actions context rather than wrapping it, so an existing call site that passes the context
+ * object directly keeps compiling unchanged.
+ */
+export interface FormSpaceStorageFileUploadInitializersConfig extends FormSpaceServerActionsContext {
+    /**
+     * Optional policy for an upload by someone other than the space's `u`.
+     *
+     * Absent by default, which is the original behaviour exactly: any uploader that is not `u` is refused.
+     */
+    readonly uploadAuthorizationDelegate?: Maybe<FormSpaceUploadAuthorizationDelegate>;
+}
+/**
+ * Creates the {@link StorageFileInitializeFromUploadServiceInitializer} entries for FormSpace uploads.
+ *
+ * ONE initializer covers every form type: the per-type rules come from the {@link FormSpaceTypeConfig}
+ * registry keyed off the loaded space, not from the initializer's own registration.
+ *
+ * @param config - The FormSpace server actions context, plus the optional shared-space upload policy.
+ * @returns The initializers to spread into the app's upload service config.
+ *
+ * @example
+ * ```ts
+ * initializer: [...appInitializers, ...formSpaceStorageFileUploadInitializers(context)]
+ * ```
+ */
+export declare function formSpaceStorageFileUploadInitializers(config: FormSpaceStorageFileUploadInitializersConfig): StorageFileInitializeFromUploadServiceInitializer[];