@dereekb/firebase-server 13.42.0 → 14.0.0

package/model/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.42.0",
+  "version": "14.0.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",
-    "@nestjs/common": "^11.1.19",
-    "@nestjs/config": "^4.0.4",
-    "archiver": "^7.0.1",
+    "@dereekb/analytics": "14.0.0",
+    "@dereekb/date": "14.0.0",
+    "@dereekb/firebase": "14.0.0",
+    "@dereekb/firebase-server": "14.0.0",
+    "@dereekb/model": "14.0.0",
+    "@dereekb/nestjs": "14.0.0",
+    "@dereekb/rxjs": "14.0.0",
+    "@dereekb/util": "14.0.0",
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/config": "^12.0.0",
+    "archiver": "^8.0.0",
     "date-fns": "^4.1.0",
     "express": "^5.2.1",
-    "firebase-functions": "^7.2.5",
+    "firebase-functions": "^7.3.2",
     "make-error": "^1.3.6",
     "@cantoo/pdf-lib": "^2.6.5",
-    "sharp": "0.35.2"
+    "sharp": "0.35.4"
   },
   "exports": {
     "./package.json": "./package.json",

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,266 @@
+import { type AppFormSpaceTypeConfigServiceRef, type DeleteFormSpaceParams, type ExpireAllExpiredFormSpacesParams, type ExpireAllExpiredFormSpacesResult, type FirebaseAuthUserId, type FirestoreContextReference, type FormSpaceDocument, type FormSpaceFirestoreCollections, type FormSpaceId, type LockFormSpaceParams, type NotificationFirestoreCollections, type ProcessAllQueuedFormSpacesParams, type ProcessAllQueuedFormSpacesResult, type RemoveFormSpaceFileParams, type ReopenFormSpaceParams, 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>;
+}
+/**
+ * Extra input for {@link FormSpaceServerActions.reopenFormSpace}, supplied by the callable rather than by the
+ * caller: WHO reopened is recorded on `rby`, so it can never be a value in the request body.
+ */
+export interface ReopenFormSpaceActionInput {
+    /**
+     * The uid of the caller.
+     */
+    readonly uid?: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * Extra input for {@link FormSpaceServerActions.lockFormSpace}, on the same terms: `lby` records who made
+ * the submission final.
+ */
+export interface LockFormSpaceActionInput {
+    /**
+     * The uid of the caller.
+     */
+    readonly uid?: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * 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 reopenFormSpace(params: ReopenFormSpaceParams): Promise<TransformAndValidateFunctionResult<ReopenFormSpaceParams, (formSpaceDocument: FormSpaceDocument, input: ReopenFormSpaceActionInput) => Promise<FormSpaceDocument>>>;
+    abstract lockFormSpace(params: LockFormSpaceParams): Promise<TransformAndValidateFunctionResult<LockFormSpaceParams, (formSpaceDocument: FormSpaceDocument, input: LockFormSpaceActionInput) => Promise<FormSpaceDocument>>>;
+    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.
+ *
+ * Also serves a RESUBMISSION after a reopen, unchanged: the space is a draft again, so the same editable
+ * check and the same submit blockers apply. The only difference is that the task is keyed by the space's
+ * reopen count, so it gets a document and a checkpoint flow of its own instead of colliding with the
+ * finished task of the attempt before it.
+ *
+ * @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 `reopenFormSpace` action.
+ *
+ * The inverse of `submitFormSpace`, and deliberately NOT a widening of `isFormSpaceEditable`: it restores
+ * every condition that predicate tests instead, so update, upload, `removeFile` and a resubmit all come
+ * back with no further change anywhere.
+ *
+ * The reopen task story is handled by KEYING rather than cleanup. The superseded attempt's task document is
+ * left where it is: it is either already done and waiting for the notification cleanup sweep, or still
+ * pending and about to be fenced off by its own handler, which compares the count it was created with
+ * against the space's. Deleting it here would mean reaching into a Notification subcollection whose parent
+ * this action cannot reconstruct once the task's own cleanup has nulled `pn` — for no gain, since the
+ * resubmission keys a document of its own either way.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that reopens a submitted FormSpace.
+ */
+export declare function reopenFormSpaceFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ReopenFormSpaceParams, (formSpaceDocument: FormSpaceDocument, input: ReopenFormSpaceActionInput) => Promise<FormSpaceDocument>, object, unknown>;
+/**
+ * Factory for the `lockFormSpace` action.
+ *
+ * Not a state transition. The space stays exactly where it is and its processing is untouched; the only
+ * thing that moves is `lat`, brought forward to now so every reopen predicate answers false from here on.
+ *
+ * Accepts a reopened DRAFT as well as a SUBMITTED space — locking a draft that has been submitted before is
+ * how a reviewer says "the next submission is the last one", and it survives the resubmit because
+ * {@link submitFormSpaceTemplate} only writes `lat` for a space that has never been submitted. A space with
+ * no submission at all is the one case refused.
+ *
+ * @param context - The FormSpace server actions context.
+ * @returns An async transform-and-validate function that locks a FormSpace's submission.
+ */
+export declare function lockFormSpaceFactory(context: FormSpaceServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<LockFormSpaceParams, (formSpaceDocument: FormSpaceDocument, input: LockFormSpaceActionInput) => Promise<FormSpaceDocument>, 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>;
+/**
+ * Input for the function {@link _queueFormSpaceForProcessingFactory} returns.
+ */
+export interface QueueFormSpaceForProcessingInput {
+    readonly formSpaceDocument: FormSpaceDocument;
+    /**
+     * The space's reopen count — the submission ATTEMPT to key the task by. Defaults to 0.
+     *
+     * Getting this wrong is not cosmetic: a resubmission keyed to attempt 0 resolves to the finished task of
+     * the first submission, which `createOrRunUniqueNotificationDocument` leaves exactly as it found it.
+     */
+    readonly reopenCount?: Maybe<number>;
+    readonly runImmediately?: Maybe<boolean>;
+}
+/**
+ * Creates (or re-runs) the unique submission task for one ATTEMPT of 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 attempt, so a second call for the same
+ * 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): (input: QueueFormSpaceForProcessingInput) => 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,112 @@
+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 the FormSpace has never been submitted, so there is no submission to lock.
+ *
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_NOT_SUBMITTED error code.
+ */
+export declare function formSpaceNotSubmittedError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the FormSpace's submission is final, so it cannot be reopened.
+ *
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_NOT_REOPENABLE error code.
+ */
+export declare function formSpaceNotReopenableError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the FormSpace's submission is being processed right now.
+ *
+ * Deliberately separate from {@link formSpaceNotReopenableError}: this one clears on its own, and telling
+ * a caller their submission is final when the processor is simply mid-run would be wrong.
+ *
+ * @returns A precondition-conflict HttpsError with the FORM_SPACE_PROCESSING_IN_PROGRESS error code.
+ */
+export declare function formSpaceProcessingInProgressError(): 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,98 @@
+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.
+     *
+     * Still a getter rather than the value, so a processor reads it the same way whether or not the handler
+     * happened to have it already. It resolves the snapshot the run's attempt fence was checked against, so
+     * every checkpoint in one run sees one consistent space.
+     */
+    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>;