@dereekb/firebase-server 13.42.0 → 14.0.0

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[];

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.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 {

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.
  */