@dereekb/firebase-server 13.42.0 → 13.43.0

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

@@ -0,0 +1,174 @@
+import { type AppFormSpaceTypeConfigService, type FormSpace, type FormSpaceDocument, type FormSpaceFile, type FormSpaceFileSlot, type FormSpaceFileSlotConfig, type FormSpaceFileValidationSubtask, type FormSpaceFileValidationSubtaskMetadata, type FormSpaceFirestoreCollections, type FormSpaceType, type StorageFileDocument, type StorageFileFirestoreCollections, type StorageFileMetadata, type StoredFileReader } from '@dereekb/firebase';
+import { type Getter, type Maybe, type Milliseconds } from '@dereekb/util';
+import { type StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget } from '../storagefile/storagefile.task.service.handler';
+/**
+ * @module formspace.validation
+ *
+ * SERVER-ONLY registration of what a FormSpace slot's uploaded file must actually contain.
+ *
+ * The split mirrors the one the type registry already uses. Pure data — which mime types, how large, how
+ * many, whether validation is required at all — lives in `@dereekb/firebase` so the client pre-checks with
+ * the same rules the server enforces. The CHECK itself is a function, so it lives here: a validator may read
+ * the file's bytes, call out to a model, or consult another collection, none of which belongs in a bundle
+ * shipped to a browser.
+ *
+ * Registration is keyed by `(FormSpaceType, slot)` and consumed by one processor targeting the single
+ * `form_space` StorageFilePurpose, because the subtask framework dispatches on one target and that target is
+ * already spent on the purpose.
+ */
+/**
+ * How long a `pending` verdict waits before the validator is asked again, when it names no delay itself.
+ */
+export declare const DEFAULT_FORM_SPACE_FILE_VALIDATION_RETRY_DELAY: Milliseconds;
+/**
+ * How many times a validator may answer `pending` before the file is failed.
+ *
+ * Bounds a validator whose external dependency never resolves. A validator that legitimately needs longer
+ * should return a longer `retryIn` rather than more attempts.
+ */
+export declare const DEFAULT_FORM_SPACE_FILE_VALIDATION_MAX_ATTEMPTS = 10;
+/**
+ * What a {@link FormSpaceFileValidator} is handed.
+ */
+export interface FormSpaceFileValidatorInput {
+    /**
+     * The FormSpace the file was uploaded into.
+     */
+    readonly formSpaceDocument: FormSpaceDocument;
+    /**
+     * Loads the FormSpace, memoized for the duration of one task run.
+     */
+    readonly loadFormSpace: Getter<Promise<FormSpace>>;
+    /**
+     * The StorageFile holding the bytes.
+     */
+    readonly storageFileDocument: StorageFileDocument;
+    /**
+     * Reads the stored file's bytes, stream, and metadata.
+     */
+    readonly fileDetailsAccessor: StoredFileReader;
+    /**
+     * The entry on the FormSpace this validation is for.
+     */
+    readonly formSpaceFile: FormSpaceFile;
+    /**
+     * The slot the file fills.
+     */
+    readonly slot: FormSpaceFileSlot;
+    /**
+     * The slot's configuration, when its type declares one.
+     */
+    readonly slotConfig: Maybe<FormSpaceFileSlotConfig>;
+    /**
+     * How many times the validator has already been asked about this file, starting at 0.
+     */
+    readonly attempt: number;
+}
+/**
+ * A validator's answer about one file.
+ *
+ * `pending` is the third outcome rather than an error: a validator waiting on something external has not
+ * failed, and reporting it as a failure would consume the file's retry budget on a check still in flight.
+ */
+export type FormSpaceFileValidationVerdict = 'valid' | 'invalid' | 'pending';
+/**
+ * The result of validating one file.
+ */
+export interface FormSpaceFileValidationResult {
+    readonly verdict: FormSpaceFileValidationVerdict;
+    /**
+     * Why the file was judged invalid, written for the OWNER to read and act on.
+     *
+     * Free text rather than a code because a content rejection cannot be enumerated in advance — "the document
+     * expired in 2019" and "this is a photo of a receipt" are both correct answers from the same validator.
+     */
+    readonly reason?: Maybe<string>;
+    /**
+     * How long to wait before asking again. `pending` only; defaults to
+     * {@link DEFAULT_FORM_SPACE_FILE_VALIDATION_RETRY_DELAY}.
+     */
+    readonly retryIn?: Maybe<Milliseconds>;
+    /**
+     * Metadata to write onto the StorageFile's `d`, REPLACING the default verdict metadata.
+     */
+    readonly metadata?: Maybe<StorageFileMetadata>;
+}
+/**
+ * Decides whether one uploaded file satisfies one FormSpace slot.
+ */
+export type FormSpaceFileValidator = (input: FormSpaceFileValidatorInput) => Promise<FormSpaceFileValidationResult>;
+/**
+ * Registers a {@link FormSpaceFileValidator} for one {@link FormSpaceType}.
+ */
+export interface FormSpaceFileValidatorConfig {
+    /**
+     * The type this validator applies to.
+     */
+    readonly formSpaceType: FormSpaceType;
+    /**
+     * The slot this validator applies to. When absent it applies to every slot of the type that does not
+     * declare a validator of its own.
+     */
+    readonly slot?: Maybe<FormSpaceFileSlot>;
+    /**
+     * The check.
+     */
+    readonly validate: FormSpaceFileValidator;
+}
+/**
+ * Configuration for {@link formSpaceFileValidationStorageFileProcessor}.
+ */
+export interface FormSpaceFileValidationStorageFileProcessorConfig {
+    readonly formSpaceFirestoreCollections: FormSpaceFirestoreCollections;
+    /**
+     * Accessor for the StorageFile collection, used to flag a file the register step supersedes.
+     */
+    readonly storageFileFirestoreCollections: StorageFileFirestoreCollections;
+    /**
+     * The registry the processor resolves each file's slot rules from.
+     */
+    readonly appFormSpaceTypeConfigService: AppFormSpaceTypeConfigService;
+    /**
+     * The registered validators.
+     */
+    readonly validators: FormSpaceFileValidatorConfig[];
+    /**
+     * How many `pending` verdicts a file may collect before it is failed. Defaults to
+     * {@link DEFAULT_FORM_SPACE_FILE_VALIDATION_MAX_ATTEMPTS}.
+     */
+    readonly maxAttempts?: Maybe<number>;
+    /**
+     * When true, asserts at wiring time that every slot declaring `validationRequired` in
+     * `appFormSpaceTypeConfigService` has a validator registered here.
+     *
+     * On by default. A slot that asks for validation and gets none would otherwise pass every file silently,
+     * which is the one failure mode a validator exists to prevent.
+     */
+    readonly validateCoverage?: Maybe<boolean>;
+}
+/**
+ * Builds the `form_space` purpose's subtask processor: the thing that actually runs a slot's validator.
+ *
+ * ONE processor covers every form type and every slot, the same way one upload initializer does — the
+ * per-slot rules come from the registry keyed off the loaded space, not from the processor's registration.
+ *
+ * The verdict is written to BOTH the FormSpace's `f` entry and the StorageFile. The FormSpace copy is the
+ * one that matters: the owner can read their own space (and list it), but cannot list StorageFiles, so a
+ * verdict that never reaches `f` is a verdict the user never sees.
+ *
+ * @param config - The FormSpace collection, type registry, and registered validators.
+ * @returns The processor config, for the `processors` array of the storage-file processing handler.
+ *
+ * @example
+ * ```ts
+ * const processors = [
+ *   formSpaceFileValidationStorageFileProcessor({
+ *     formSpaceFirestoreCollections: context,
+ *     storageFileFirestoreCollections: context,
+ *     appFormSpaceTypeConfigService: appFormSpaceTypeConfigService(formSpaceTypeConfigRecord(APP_FORM_SPACE_TYPE_CONFIGS)),
+ *     validators: [MY_RESUME_VALIDATOR]
+ *   })
+ * ];
+ * ```
+ */
+export declare function formSpaceFileValidationStorageFileProcessor(config: FormSpaceFileValidationStorageFileProcessorConfig): StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget<FormSpaceFileValidationSubtaskMetadata, FormSpaceFileValidationSubtask>;

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

@@ -0,0 +1,6 @@
+export * from './formspace.action.server';
+export * from './formspace.error';
+export * from './formspace.module';
+export * from './formspace.task.service.handler';
+export * from './formspace.upload.initializer';
+export * from './formspace.validation';

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

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

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

@@ -210,20 +210,27 @@ export interface ProcessStorageFileInTransactionInput {
  * Creates or restarts a notification task for the file based on its current processing state,
  * handling stuck-processing detection, forced restarts, and re-processing of already-successful files.
  *
- * @param context - The storage file server actions context.
+ * Takes the BASE context rather than the full one so a sibling model's actions (Calendar's ICS re-flag,
+ * for instance) can build this without standing up the upload service and signed-upload policy registry
+ * it has no use for.
+ *
+ * @param context - The base storage file server actions context.
  * @returns An async function that processes a storage file within a transaction.
  */
-export declare function _processStorageFileInTransactionFactory(context: StorageFileServerActionsContext): (input: ProcessStorageFileInTransactionInput, transaction: Transaction) => Promise<void>;
+export declare function _processStorageFileInTransactionFactory(context: BaseStorageFileServerActionsContext): (input: ProcessStorageFileInTransactionInput, transaction: Transaction) => Promise<void>;
 /**
  * Factory for the `processStorageFile` action.
  *
  * Processes a single {@link StorageFile} by creating a notification task for it
  * and marking it as processing. Validates the file is in a valid state for processing.
  *
- * @param context - The storage file server actions context.
+ * Takes the BASE context, so a sibling model that needs to re-flag a StorageFile it owns can build this
+ * action directly instead of injecting the whole {@link StorageFileServerActions}.
+ *
+ * @param context - The base storage file server actions context.
  * @returns An async transform-and-validate function that processes a single StorageFile.
  */
-export declare function processStorageFileFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ProcessStorageFileParams, (storageFileDocument: StorageFileDocument) => Promise<ProcessStorageFileResult>, object, unknown>;
+export declare function processStorageFileFactory(context: BaseStorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ProcessStorageFileParams, (storageFileDocument: StorageFileDocument) => Promise<ProcessStorageFileResult>, object, unknown>;
 /**
  * Factory for the `deleteAllQueuedStorageFiles` action.
  *

package/model/src/lib/storagefile/storagefile.upload.service.initializer.d.ts

@@ -74,6 +74,22 @@ export interface StorageFileInitializeFromUploadServiceInitializerStorageFileDoc
  * @returns A permanent failure result with the error and optional created file reference.
  */
 export declare function storageFileInitializeFromUploadServiceInitializerResultPermanentFailure(error: unknown, createdFile?: Maybe<StoragePathRef>): StorageFileInitializeFromUploadServiceInitializerResult;
+/**
+ * Convenience factory for creating a TRANSIENT failure result, indicating the initializer could not
+ * finish for a reason that may not recur.
+ *
+ * The difference from a permanent failure is what happens to the SOURCE upload: a permanent failure
+ * discards it, while a transient one leaves it in place for the next sweep to retry. Any intermediate
+ * file named by `createdFile` is deleted either way, so a retry never finds a half-written destination.
+ *
+ * Use this for infrastructure — a contended transaction, a storage blip — and reserve the permanent
+ * result for a decision that no retry will reverse.
+ *
+ * @param error - The error that caused the failure.
+ * @param createdFile - Optional path to a file that was created before the error and should be deleted.
+ * @returns A transient failure result with the error and optional created file reference.
+ */
+export declare function storageFileInitializeFromUploadServiceInitializerResultTransientFailure(error: unknown, createdFile?: Maybe<StoragePathRef>): StorageFileInitializeFromUploadServiceInitializerResult;
 /**
  * Processes the input details accessor and returns the results.
  */

package/oidc/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "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/zoho": "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",
+    "@dereekb/zoho": "13.43.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

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

package/test/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "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/firebase-server/oidc": "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/firebase-server/oidc": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -24,7 +24,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.42.0"
+    "@dereekb/nestjs": "13.43.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.42.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@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/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"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

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