@dereekb/firebase-server 13.43.0 → 14.0.0

package/model/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.43.0",
+  "version": "14.0.0",
   "type": "module",
   "peerDependencies": {
-    "@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",
+    "@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/formspace/formspace.action.server.d.ts

@@ -1,4 +1,4 @@
-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 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';
@@ -69,6 +69,26 @@ export interface RemoveFormSpaceFileActionInput {
      */
     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.
  *
@@ -78,6 +98,8 @@ 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>>>;
@@ -119,10 +141,48 @@ export declare function updateFormSpaceFactory(context: FormSpaceServerActionsCo
  * 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.
  *
@@ -144,16 +204,30 @@ export declare function submitFormSpaceFactory(context: FormSpaceServerActionsCo
  */
 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`.
+ * 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 space, so a second attempt resolves to
- * the same document rather than racing a second processor.
+ * 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): (formSpaceDocument: FormSpaceDocument, runImmediately?: Maybe<boolean>) => Promise<SubmitFormSpaceResult>;
+export declare function _queueFormSpaceForProcessingFactory(context: FormSpaceServerActionsContext): (input: QueueFormSpaceForProcessingInput) => Promise<SubmitFormSpaceResult>;
 /**
  * Factory for the `deleteFormSpace` action.
  *

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

@@ -12,6 +12,27 @@ export declare function formSpaceTypeNotRegisteredError(formSpaceType: FormSpace
  * @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.
  *

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

@@ -27,8 +27,9 @@ export interface FormSpaceSubmissionSubtaskInput<M extends FormSpaceSubmissionSu
     /**
      * 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.
+     * 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>>;
 }

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

@@ -3,7 +3,7 @@ import { type NotificationTaskServiceTaskHandlerConfig } from '../notification/n
 import { type PromiseOrValue, type Maybe } from '@dereekb/util';
 import { type StorageFileQueueForDeleteTime } from './storagefile.util';
 import { type NotificationTaskSubtaskCleanupInstructions, type NotificationTaskSubtaskFlowEntry, type NotificationTaskSubtaskInput, type NotificationTaskSubtaskNotificationTaskHandlerConfig, type NotificationTaskSubtaskProcessorConfig } from '../notification/notification.task.subtask.handler';
-import archiver from 'archiver';
+import { type Archiver, type ArchiverOptions } from 'archiver';
 /**
  * Input for a purpose-specific storage file processing subtask.
  *
@@ -132,9 +132,9 @@ export interface StorageFileGroupStorageFileZipConfigureZipArchiverOptionsInput
     readonly input: StorageFileProcessingPurposeSubtaskInput<StorageFileGroupZipStorageFileProcessingSubtaskMetadata, StorageFileGroupZipStorageFileProcessingSubtask>;
     readonly storageFileGroup: StorageFileGroup;
 }
-export type StorageFileGroupStorageFileZipConfigureZipArchiverOptionsFunction = (input: StorageFileGroupStorageFileZipConfigureZipArchiverOptionsInput) => PromiseOrValue<archiver.ArchiverOptions>;
+export type StorageFileGroupStorageFileZipConfigureZipArchiverOptionsFunction = (input: StorageFileGroupStorageFileZipConfigureZipArchiverOptionsInput) => PromiseOrValue<ArchiverOptions>;
 export interface StorageFileGroupStorageFileZipFinalizeArchiveInput extends StorageFileGroupStorageFileZipConfigureZipArchiverOptionsInput {
-    readonly archive: archiver.Archiver;
+    readonly archive: Archiver;
 }
 export type StorageFileGroupStorageFileZipFinalizeArchiveFunction = (input: StorageFileGroupStorageFileZipFinalizeArchiveInput) => Promise<void>;
 export interface StorageFileGroupStorageFileZipFileDisplayNameFunctionInput {