@dereekb/firebase 13.41.0 → 13.43.0

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

@@ -0,0 +1,110 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirestoreQueryConstraint } from '../../common/firestore/query/constraint';
+import { type FirebaseAuthOwnershipKey } from '../../common/auth/auth';
+import { type FormSpaceKey } from './formspace.id';
+/**
+ * @module formspace.query
+ *
+ * SINGLE-FIELD BY CONSTRUCTION. `firestore.indexes.json` is generated from downstream `-firebase`
+ * components and cannot resolve an identity declared upstream here, so a FormSpace query that needed a
+ * composite index would have no way to declare one. Every query below is therefore one field plus an
+ * optional sort on that same field, which Firestore serves from its automatic single-field indexes.
+ */
+/**
+ * Returns query constraints for FormSpaces awaiting a processing task (`ps == QUEUED_FOR_PROCESSING`).
+ *
+ * This is the backstop sweep: submission normally creates the task inline, so a space that is still sitting
+ * here is one whose task creation was lost.
+ *
+ * @param limitCount - Maximum number of results. Omit for unbounded.
+ * @returns Firestore query constraints for FormSpaces queued for processing.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel FormSpace
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory sweep
+ *
+ * @example
+ * ```ts
+ * const constraints = formSpacesQueuedForProcessingQuery(100);
+ * ```
+ */
+export declare function formSpacesQueuedForProcessingQuery(limitCount?: Maybe<number>): FirestoreQueryConstraint[];
+/**
+ * Input for {@link formSpacesDueForExpirationQuery}.
+ */
+export interface FormSpacesDueForExpirationQueryInput {
+    /**
+     * FormSpaces whose `eat` is at or before this instant are due.
+     *
+     * PIN THIS for the whole sweep rather than re-deriving it per page — a cutoff that advances with the
+     * clock lets a space that ages mid-sweep join a page not yet reached, making the pass unbounded.
+     */
+    readonly before: Date;
+    /**
+     * Maximum number of results per page.
+     */
+    readonly limit?: Maybe<number>;
+}
+/**
+ * Returns query constraints for FormSpaces whose expiration instant has arrived.
+ *
+ * NOTE: a Firestore inequality skips documents where the field is absent, so a space with no `eat` — one
+ * whose type does not expire, or one that has already been submitted or expired and had `eat` cleared — is
+ * not matched. That absence IS the exclusion mechanism; there is no second flag to keep in step.
+ *
+ * @param input - The pinned cutoff and page size.
+ * @returns Firestore query constraints for FormSpaces due for expiration.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel FormSpace
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory cleanup
+ *
+ * @example
+ * ```ts
+ * const constraints = formSpacesDueForExpirationQuery({ before: new Date(), limit: 50 });
+ * ```
+ */
+export declare function formSpacesDueForExpirationQuery(input: FormSpacesDueForExpirationQueryInput): FirestoreQueryConstraint[];
+/**
+ * Returns query constraints for every StorageFile that belongs to a FormSpace.
+ *
+ * A single `array-contains` on the group id, which Firestore serves from its automatic array index — the
+ * FormSpace's own group id is the only handle needed, so nothing here requires a composite index.
+ *
+ * @param formSpaceKey - The FormSpace whose files to select.
+ * @returns Firestore query constraints for the space's StorageFiles.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel StorageFile
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
+ * @dbxModelFirebaseIndexSkip true
+ *
+ * @example
+ * ```ts
+ * const constraints = storageFilesForFormSpaceQuery('fsp/abc123');
+ * ```
+ */
+export declare function storageFilesForFormSpaceQuery(formSpaceKey: FormSpaceKey): FirestoreQueryConstraint[];
+/**
+ * Returns query constraints for every FormSpace carrying the given ownership key.
+ *
+ * Ordering is deliberately left to the caller/client: a second field here would need a composite index this
+ * package has no way to declare.
+ *
+ * @param ownerKey - The ownership key to filter by.
+ * @returns Firestore query constraints for the owner's FormSpaces.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel FormSpace
+ * @dbxModelFirebaseIndexScope COLLECTION
+ * @dbxModelFirebaseIndexCategory lookup
+ *
+ * @example
+ * ```ts
+ * const constraints = formSpacesForOwnerQuery('pr/abc123');
+ * ```
+ */
+export declare function formSpacesForOwnerQuery(ownerKey: FirebaseAuthOwnershipKey): FirestoreQueryConstraint[];

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

@@ -0,0 +1,75 @@
+import { type Maybe } from '@dereekb/util';
+import { type CreateNotificationTaskTemplate } from '../notification/notification.create.task';
+import { type NotificationTaskSubtaskCheckpointString, type NotificationTaskSubtaskData, type NotificationTaskSubtaskMetadata } from '../notification/notification.task.subtask';
+import { type NotificationTaskType } from '../notification/notification.id';
+import { type FormSpaceDocument } from './formspace';
+import { type FormSpaceId, type FormSpaceType } from './formspace.id';
+/**
+ * @module formspace.task
+ *
+ * The NotificationTask that processes a submitted FormSpace.
+ *
+ * ONE task type for every form type. The task's SUBTASK TARGET is the {@link FormSpaceType}, so a new form
+ * type registers a processor rather than a task type — the same specialization
+ * `StorageFileProcessingNotificationTask` already does by purpose.
+ */
+/**
+ * NotificationTask type identifier for FormSpace submission processing.
+ */
+export declare const FORM_SPACE_SUBMISSION_NOTIFICATION_TASK_TYPE: NotificationTaskType;
+/**
+ * Checkpoint string for a FormSpace submission subtask.
+ */
+export type FormSpaceSubmissionSubtask = NotificationTaskSubtaskCheckpointString;
+/**
+ * Arbitrary metadata carried between a FormSpace submission's subtasks.
+ */
+export type FormSpaceSubmissionSubtaskMetadata = NotificationTaskSubtaskMetadata;
+/**
+ * Data payload for a FormSpace submission NotificationTask.
+ *
+ * @template M - subtask metadata type
+ * @template S - subtask checkpoint string type
+ */
+export interface FormSpaceSubmissionNotificationTaskData<M extends FormSpaceSubmissionSubtaskMetadata = FormSpaceSubmissionSubtaskMetadata, S extends FormSpaceSubmissionSubtask = FormSpaceSubmissionSubtask> extends NotificationTaskSubtaskData<M, S> {
+    /**
+     * The FormSpaceDocument id.
+     */
+    readonly formSpace: FormSpaceId;
+    /**
+     * The FormSpace's type, which is also the subtask target.
+     *
+     * Retrieved from the FormSpace the first time the task runs and re-copied onto the metadata afterwards,
+     * so subsequent runs do not re-read the document only to learn which processor to dispatch to.
+     */
+    readonly t?: Maybe<FormSpaceType>;
+}
+/**
+ * Input for {@link formSpaceSubmissionNotificationTaskTemplate}.
+ */
+export interface FormSpaceSubmissionNotificationTaskInput<M extends FormSpaceSubmissionSubtaskMetadata = FormSpaceSubmissionSubtaskMetadata> extends Omit<FormSpaceSubmissionNotificationTaskData<M>, 'formSpace' | 't' | 'sfps'> {
+    readonly formSpaceDocument: FormSpaceDocument;
+    readonly overrideExistingTask?: Maybe<boolean>;
+}
+/**
+ * Creates a {@link CreateNotificationTaskTemplate} for a FormSpace submission task.
+ *
+ * The task is UNIQUE to the FormSpace: a space submits once, and a second template for the same space must
+ * resolve to the same document rather than racing a second processor against the first.
+ *
+ * @param input - The target FormSpaceDocument and optional subtask data.
+ * @returns A CreateNotificationTaskTemplate for the submission task.
+ *
+ * @example
+ * ```ts
+ * const template = formSpaceSubmissionNotificationTaskTemplate({ formSpaceDocument: doc });
+ * ```
+ */
+export declare function formSpaceSubmissionNotificationTaskTemplate(input: FormSpaceSubmissionNotificationTaskInput): CreateNotificationTaskTemplate;
+/**
+ * All NotificationTask types used by the FormSpace system.
+ *
+ * Register these with the notification task service so an unhandled type is caught at wiring time rather
+ * than at the first submission.
+ */
+export declare const ALL_FORM_SPACE_NOTIFICATION_TASK_TYPES: NotificationTaskType[];

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

@@ -0,0 +1,267 @@
+import { type ContentTypeMimeType, type Maybe, type Milliseconds } from '@dereekb/util';
+import { type FormSpaceFileSlot, type FormSpaceType } from './formspace.id';
+/**
+ * @module formspace.type
+ *
+ * The {@link FormSpaceType} registry: the per-type upload restrictions, expiration policy, and submission
+ * metadata an app declares once and both the client and the server read.
+ *
+ * The type and the factory live here, in the model folder rather than in `firebase-server`, so a client-side
+ * pre-check rejects an oversized file with the SAME rule the server enforces authoritatively. Only the
+ * service INSTANCE is constructed server-side, as a NestJS provider — the same split
+ * {@link AppCalendarTypeConfigService} uses.
+ */
+/**
+ * Who may read and remove an individual file, among the users who already reach the FormSpace itself.
+ *
+ * Narrows access; it never widens it. A caller that cannot read the space at all is refused before this is
+ * ever consulted, so `'space'` is not "public" — it is "whoever the space already lets in".
+ *
+ * - `'space'` — anyone holding the corresponding role on the space. The DEFAULT, and the only sensible
+ *   answer for a single-user form, where every file was uploaded by the one person who can reach it.
+ * - `'uploader'` — only the user who uploaded that file, per {@link FormSpaceFile.ub}. For a SHARED space
+ *   whose members contribute side by side rather than collaborating on one pile: a member adds their own
+ *   photos and can take them back, and cannot read or delete anybody else's. The space's own `u` is NOT
+ *   exempt — on a shared space `u` is whoever the space was opened for, not an administrator of its
+ *   contents, and exempting them would quietly hand one member the whole album.
+ */
+export type FormSpaceFileAccess = 'space' | 'uploader';
+/**
+ * Default for {@link FormSpaceFileSlotConfig.fileAccess} and {@link FormSpaceTypeConfig.fileAccess}.
+ *
+ * `'space'`, so a type declared before per-file access existed keeps behaving exactly as it did.
+ */
+export declare const DEFAULT_FORM_SPACE_FILE_ACCESS: FormSpaceFileAccess;
+/**
+ * Restrictions for a single named upload slot within a {@link FormSpaceTypeConfig}.
+ *
+ * A slot is a LOGICAL position, not a file: uploading into an occupied slot supersedes what was there, so
+ * "one current resume" needs no extra bookkeeping.
+ */
+export interface FormSpaceFileSlotConfig {
+    /**
+     * The slot this configuration applies to.
+     */
+    readonly slot: FormSpaceFileSlot;
+    /**
+     * Human-readable name of the slot, for tooling and logs.
+     */
+    readonly name?: Maybe<string>;
+    /**
+     * Whether the space may be submitted without a file in this slot. Defaults to false.
+     */
+    readonly required?: Maybe<boolean>;
+    /**
+     * Mime types accepted in this slot. Defaults to the type's {@link FormSpaceTypeConfig.allowedMimeTypes}.
+     */
+    readonly allowedMimeTypes?: Maybe<readonly ContentTypeMimeType[]>;
+    /**
+     * Size cap for a file in this slot. Defaults to the type's {@link FormSpaceTypeConfig.maxFileSizeBytes}.
+     */
+    readonly maxFileSizeBytes?: Maybe<number>;
+    /**
+     * How many files this slot may hold at once. Defaults to {@link DEFAULT_FORM_SPACE_SLOT_MAX_FILES}.
+     *
+     * At 1 the slot is a POSITION: a new upload supersedes whatever was there, which is the original "one
+     * current resume" behaviour. Above 1 it is a FOLDER: uploads accumulate, and one is refused once the
+     * folder is full rather than quietly evicting the oldest file the user put there.
+     */
+    readonly maxFiles?: Maybe<number>;
+    /**
+     * How many files this slot must hold before the space may be submitted.
+     *
+     * Defaults to 1 when {@link required} is true, and 0 otherwise, so `required` keeps meaning exactly what it
+     * meant before folders existed.
+     */
+    readonly minFiles?: Maybe<number>;
+    /**
+     * Who may read and remove an individual file in this slot.
+     *
+     * Defaults to the type's {@link FormSpaceTypeConfig.fileAccess}, which itself defaults to
+     * {@link DEFAULT_FORM_SPACE_FILE_ACCESS}. Narrowing it per slot is what lets one shared space hold a
+     * public banner everybody sees alongside a folder of each member's own documents.
+     */
+    readonly fileAccess?: Maybe<FormSpaceFileAccess>;
+    /**
+     * Whether a file here must pass validation before the space may be submitted. Defaults to false.
+     *
+     * Setting it does two things: an accepted upload enters the StorageFile processing pipeline instead of
+     * being stored as-is, and a file left PENDING or judged INVALID blocks submission. A type that sets this
+     * MUST register a validator for the slot server-side; the wiring asserts that at boot.
+     */
+    readonly validationRequired?: Maybe<boolean>;
+}
+/**
+ * Upload, expiration, and submission configuration for a single {@link FormSpaceType}.
+ *
+ * This is the contract a FormSpace of the type is held to. It is pure data and is shared by the client and
+ * the server; the server-side PROCESSING of a submission is registered separately, as a
+ * `FormSpaceSubmissionProcessorConfig` keyed by the same type string.
+ */
+export interface FormSpaceTypeConfig {
+    /**
+     * The type this configuration applies to.
+     */
+    readonly formSpaceType: FormSpaceType;
+    /**
+     * Human-readable name of the type, for tooling and logs.
+     */
+    readonly name?: Maybe<string>;
+    /**
+     * Longer description of what the type collects.
+     */
+    readonly description?: Maybe<string>;
+    /**
+     * The upload slots this type declares.
+     *
+     * When empty, the type accepts no uploads at all — a FormSpace can be a pure JSON container.
+     */
+    readonly slots?: Maybe<readonly FormSpaceFileSlotConfig[]>;
+    /**
+     * Whether a slot NOT declared in {@link slots} may be uploaded into. Defaults to false.
+     *
+     * False is the safe default: an undeclared slot has no size or mime restriction of its own, so allowing
+     * one silently widens the type's contract to the global defaults.
+     */
+    readonly allowUndeclaredSlots?: Maybe<boolean>;
+    /**
+     * Maximum number of uploads a single FormSpace of this type may ACCEPT over its whole lifetime.
+     *
+     * Counted against the space's monotonic `uc` counter, which is why superseding a slot still consumes one:
+     * the cap bounds work done, not files retained. Defaults to {@link DEFAULT_FORM_SPACE_MAX_UPLOADS}.
+     */
+    readonly maxUploads?: Maybe<number>;
+    /**
+     * Mime types accepted by any slot that does not narrow them further.
+     * Defaults to {@link DEFAULT_FORM_SPACE_ALLOWED_MIME_TYPES}.
+     */
+    readonly allowedMimeTypes?: Maybe<readonly ContentTypeMimeType[]>;
+    /**
+     * Size cap for any slot that does not narrow it further.
+     * Defaults to {@link DEFAULT_FORM_SPACE_MAX_FILE_SIZE_BYTES}.
+     */
+    readonly maxFileSizeBytes?: Maybe<number>;
+    /**
+     * Who may read and remove an individual file in any slot that does not narrow it further.
+     * Defaults to {@link DEFAULT_FORM_SPACE_FILE_ACCESS}.
+     */
+    readonly fileAccess?: Maybe<FormSpaceFileAccess>;
+    /**
+     * How long a newly created FormSpace of this type stays editable before the expiration sweep retires it.
+     *
+     * When absent the space never expires and `eat` is never written, which is exactly what keeps it out of
+     * the sweep's inequality query.
+     */
+    readonly expiresIn?: Maybe<Milliseconds>;
+}
+/**
+ * Default for {@link FormSpaceTypeConfig.maxUploads}.
+ */
+export declare const DEFAULT_FORM_SPACE_MAX_UPLOADS = 20;
+/**
+ * Default for {@link FormSpaceFileSlotConfig.maxFiles}.
+ *
+ * One, so a slot declared before folders existed keeps superseding rather than silently accumulating.
+ */
+export declare const DEFAULT_FORM_SPACE_SLOT_MAX_FILES = 1;
+/**
+ * Default for {@link FormSpaceTypeConfig.maxFileSizeBytes}: 10 MiB.
+ */
+export declare const DEFAULT_FORM_SPACE_MAX_FILE_SIZE_BYTES: number;
+/**
+ * Default for {@link FormSpaceTypeConfig.allowedMimeTypes}.
+ *
+ * Deliberately narrow: a form attachment is a document or an image, and an open list on the DEFAULT path is
+ * how an upload endpoint becomes a general-purpose file host.
+ */
+export declare const DEFAULT_FORM_SPACE_ALLOWED_MIME_TYPES: readonly ContentTypeMimeType[];
+/**
+ * Default expiration applied to {@link DEFAULT_FORM_SPACE_TYPE_CONFIG}-shaped types that opt in: seven days.
+ */
+export declare const DEFAULT_FORM_SPACE_EXPIRES_IN: Milliseconds;
+/**
+ * The {@link FormSpaceType} of {@link DEFAULT_FORM_SPACE_TYPE_CONFIG}, used for a type the app never registered.
+ */
+export declare const UNKNOWN_FORM_SPACE_TYPE: FormSpaceType;
+/**
+ * The configuration applied to a FormSpace whose type the app did not register.
+ *
+ * An unregistered type falls back rather than throwing on purpose: a scheduled sweep over every FormSpace in
+ * the app must not be taken down by one badly-typed document. CREATION is the opposite — `createFormSpace`
+ * rejects an unregistered type outright, so this fallback only ever governs a document that already exists.
+ *
+ * It declares no slots and does not allow undeclared ones, so an unregistered space accepts no uploads.
+ */
+export declare const DEFAULT_FORM_SPACE_TYPE_CONFIG: FormSpaceTypeConfig;
+/**
+ * Record of {@link FormSpaceTypeConfig} keyed by {@link FormSpaceType}.
+ */
+export type FormSpaceTypeConfigRecord = Record<FormSpaceType, FormSpaceTypeConfig>;
+/**
+ * Creates a {@link FormSpaceTypeConfigRecord} from an array of configs.
+ *
+ * @param configs - The configs to index.
+ * @returns A record keyed by form space type.
+ * @throws {Error} When two configs declare the same {@link FormSpaceType}.
+ *
+ * @example
+ * ```ts
+ * const record = formSpaceTypeConfigRecord([{ formSpaceType: 'demo_example' }]);
+ * ```
+ */
+export declare function formSpaceTypeConfigRecord(configs: FormSpaceTypeConfig[]): FormSpaceTypeConfigRecord;
+/**
+ * Runtime service for resolving a {@link FormSpaceTypeConfig} from a {@link FormSpaceType}.
+ *
+ * Built from a {@link FormSpaceTypeConfigRecord} via {@link appFormSpaceTypeConfigService}.
+ */
+export declare abstract class AppFormSpaceTypeConfigService {
+    /**
+     * All registered configs for this app.
+     */
+    abstract readonly appFormSpaceTypeConfigRecord: FormSpaceTypeConfigRecord;
+    /**
+     * Returns the config for the given type, falling back to the service's default when it is not registered.
+     *
+     * @param formSpaceType - The type to look up.
+     */
+    abstract configForFormSpaceType(formSpaceType: FormSpaceType): FormSpaceTypeConfig;
+    /**
+     * Returns the config for the given type, or null when it is not registered.
+     *
+     * This is what `createFormSpace` gates on: a space may only be CREATED for a type the app declared.
+     *
+     * @param formSpaceType - The type to look up.
+     */
+    abstract registeredConfigForFormSpaceType(formSpaceType: FormSpaceType): Maybe<FormSpaceTypeConfig>;
+    /**
+     * Returns every registered {@link FormSpaceType}.
+     */
+    abstract getAllKnownFormSpaceTypes(): FormSpaceType[];
+    /**
+     * Returns every registered {@link FormSpaceTypeConfig}.
+     */
+    abstract getAllKnownFormSpaceTypeConfigs(): FormSpaceTypeConfig[];
+}
+/**
+ * Reference to an {@link AppFormSpaceTypeConfigService} instance, for dependency injection.
+ */
+export interface AppFormSpaceTypeConfigServiceRef {
+    readonly appFormSpaceTypeConfigService: AppFormSpaceTypeConfigService;
+}
+/**
+ * Creates an {@link AppFormSpaceTypeConfigService} from the given record.
+ *
+ * @param appFormSpaceTypeConfigRecord - The complete form space type registry for the application.
+ * @param defaultConfig - Config used for an unregistered type. Defaults to {@link DEFAULT_FORM_SPACE_TYPE_CONFIG}.
+ * @returns The service.
+ *
+ * @example
+ * ```ts
+ * const service = appFormSpaceTypeConfigService(formSpaceTypeConfigRecord(DEMO_FORM_SPACE_TYPE_CONFIGS));
+ * const config = service.configForFormSpaceType('demo_example');
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function appFormSpaceTypeConfigService(appFormSpaceTypeConfigRecord: FormSpaceTypeConfigRecord, defaultConfig?: FormSpaceTypeConfig): AppFormSpaceTypeConfigService;

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

@@ -0,0 +1,204 @@
+import { type ContentTypeMimeType, type Maybe, type SlashPath, type SlashPathFile, type SlashPathFolder, type SlashPathTypedFileExtension, type SlashPathUntypedFile } from '@dereekb/util';
+import { type FirebaseAuthUserId } from '../../common/auth/auth';
+import { type StorageFilePurpose } from '../storagefile/storagefile.id';
+import { type StorageFilePurposeUploadPolicy, type UploadedFileTypeIdentifier } from '../storagefile/storagefile.upload';
+import { type FormSpaceFileSlot, type FormSpaceId } from './formspace.id';
+/**
+ * @module formspace.upload
+ *
+ * Where a FormSpace's uploads land, and how a landed file is read back into `{ formSpaceId, slot }`.
+ *
+ * ONE purpose for every FormSpace file, across every type. The per-type rules live in the
+ * {@link FormSpaceTypeConfig} registry and are enforced by the initializer against the loaded FormSpace, so
+ * a new form type needs no new purpose, no new storage-rules block, and no new initializer.
+ */
+/**
+ * {@link UploadedFileTypeIdentifier} for a file uploaded into a FormSpace.
+ */
+export declare const FORM_SPACE_UPLOADED_FILE_TYPE_IDENTIFIER: UploadedFileTypeIdentifier;
+/**
+ * The single {@link StorageFilePurpose} carried by every FormSpace upload.
+ */
+export declare const FORM_SPACE_PURPOSE: StorageFilePurpose;
+/**
+ * The folder under a user's uploads folder that FormSpace uploads land in.
+ */
+export declare const FORM_SPACE_UPLOADS_FOLDER_NAME = "formSpace";
+/**
+ * Returns the uploads folder path for one FormSpace slot.
+ *
+ * @param uid - The uploading Firebase Auth user id.
+ * @param formSpaceId - The FormSpace being uploaded into.
+ * @param slot - The slot being filled.
+ * @returns The SlashPathFolder the slot's uploads land in.
+ *
+ * @example
+ * ```ts
+ * formSpaceUploadsFolderPath('user123', 'fsp1', 'resume');
+ * // 'uploads/u/user123/formSpace/fsp1/resume/'
+ * ```
+ */
+export declare function formSpaceUploadsFolderPath(uid: FirebaseAuthUserId, formSpaceId: FormSpaceId, slot: FormSpaceFileSlot): SlashPathFolder;
+/**
+ * Input for {@link formSpaceUploadsFilePath}.
+ */
+export interface FormSpaceUploadsFilePathInput {
+    readonly uid: FirebaseAuthUserId;
+    readonly formSpaceId: FormSpaceId;
+    readonly slot: FormSpaceFileSlot;
+    readonly filename: SlashPathFile;
+}
+/**
+ * Returns the full uploads path for one file in one FormSpace slot.
+ *
+ * The FormSpace id and the slot are IN THE PATH rather than in custom metadata because the initializer runs
+ * from a storage-triggered sweep that only ever sees the path — and because the storage rules can then keep
+ * the write inside the uploader's own namespace with no Firestore read.
+ *
+ * @param input - The uploader, the target space and slot, and the file name.
+ * @returns The full upload path.
+ *
+ * @example
+ * ```ts
+ * formSpaceUploadsFilePath({ uid: 'user123', formSpaceId: 'fsp1', slot: 'resume', filename: 'resume.pdf' });
+ * // 'uploads/u/user123/formSpace/fsp1/resume/resume.pdf'
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceUploadsFilePath(input: FormSpaceUploadsFilePathInput): SlashPath;
+/**
+ * Root folder every FormSpace's accepted files are moved to, out of the transient uploads folder.
+ */
+export declare const FORM_SPACE_FILES_ROOT_FOLDER_PATH: SlashPathFolder;
+/**
+ * Input for {@link formSpaceFileStoragePath}.
+ */
+export interface FormSpaceFileStoragePathInput {
+    readonly formSpaceId: FormSpaceId;
+    readonly slot: FormSpaceFileSlot;
+    /**
+     * The index claimed from the space's `fi` counter.
+     */
+    readonly index: number;
+    /**
+     * The extension, without its leading separator. Absent when neither the uploaded name nor its mime type
+     * named one.
+     */
+    readonly extension?: Maybe<SlashPathTypedFileExtension>;
+}
+/**
+ * Returns the permanent storage path an accepted FormSpace file is moved to.
+ *
+ * Keyed by the space, the slot, and a monotonic INDEX rather than by the uploaded name. A name-keyed
+ * destination is not unique: a file removed from the space's `f` keeps its object until the delete sweep
+ * runs, so re-uploading the same name overwrote it — leaving two StorageFiles on one object, where
+ * deleting the first destroyed the second's bytes.
+ *
+ * The leaf carries at most one separator, which is also the only shape {@link slashPathDetails} can read
+ * ({@link slashPathType} calls two or more `invalid`), so the destination always parses back into a name
+ * and an extension.
+ *
+ * @param input - The space, the slot, the claimed index, and the file's extension.
+ * @returns The permanent storage path.
+ *
+ * @example
+ * ```ts
+ * formSpaceFileStoragePath({ formSpaceId: 'fsp1', slot: 'resume', index: 0, extension: 'pdf' });
+ * // '/fsp/fsp1/resume/0.pdf'
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceFileStoragePath(input: FormSpaceFileStoragePathInput): SlashPath;
+/**
+ * Input for {@link formSpaceUploadFileNameDetails}.
+ */
+export interface FormSpaceUploadFileNameDetailsInput {
+    readonly filename: SlashPathFile;
+    /**
+     * The uploaded file's content type, used to name the extension when the filename does not.
+     */
+    readonly mimeType?: Maybe<ContentTypeMimeType>;
+}
+/**
+ * The uploaded name, split into the parts each layer stores.
+ */
+export interface FormSpaceUploadFileNameDetails {
+    /**
+     * The name without its extension, for the StorageFile's `n` — which is UNTYPED by contract (see
+     * {@link StorageFileDisplayName}) because the zip builder merges it with the path's extension.
+     *
+     * Absent for a name that is nothing but an extension, such as `.gitignore`.
+     */
+    readonly displayName?: Maybe<SlashPathUntypedFile>;
+    /**
+     * The extension for the destination leaf.
+     */
+    readonly extension?: Maybe<SlashPathTypedFileExtension>;
+    /**
+     * The two recomposed — what the FormSpace's `f` entry records as the file's name, and what a download
+     * of it is named.
+     */
+    readonly fileName: SlashPathFile;
+}
+/**
+ * Splits an uploaded filename into the display name and extension the rest of the pipeline stores.
+ *
+ * Normalizes first: an uploaded name may carry any number of separators, and {@link slashPathDetails}
+ * reads a path with two or more as `invalid` and yields neither a name nor an extension for it. The
+ * canonical {@link replaceInvalidFilePathTypeSeparatorsInSlashPath} collapses it to at most one, so
+ * `my.report.pdf` becomes `my_report.pdf` rather than losing its extension entirely.
+ *
+ * Falls back to the mime type for a name that has no extension, which keeps the stored object
+ * self-describing and keeps `fileName` in step with what a download or a zip entry is actually called.
+ *
+ * @param input - The uploaded filename and its content type.
+ * @returns The display name, the extension, and the two recomposed.
+ *
+ * @example
+ * ```ts
+ * formSpaceUploadFileNameDetails({ filename: 'resume.pdf' });
+ * // { displayName: 'resume', extension: 'pdf', fileName: 'resume.pdf' }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceUploadFileNameDetails(input: FormSpaceUploadFileNameDetailsInput): FormSpaceUploadFileNameDetails;
+/**
+ * The pieces {@link parseFormSpaceUploadPath} recovers from a FormSpace upload path.
+ */
+export interface ParsedFormSpaceUploadPath {
+    readonly uid: FirebaseAuthUserId;
+    readonly formSpaceId: FormSpaceId;
+    readonly slot: FormSpaceFileSlot;
+    readonly filename: SlashPathFile;
+}
+/**
+ * Reads a FormSpace upload path back into its parts.
+ *
+ * Returns null for anything that is not exactly a FormSpace upload path, including a path with extra
+ * segments: a nested path would otherwise resolve to a slot name that no config declares, and silently
+ * widening the parse is how an upload lands somewhere nobody validated.
+ *
+ * @param path - The path to parse.
+ * @returns The parsed parts, or null when the path is not a FormSpace upload path.
+ *
+ * @example
+ * ```ts
+ * parseFormSpaceUploadPath('uploads/u/user123/formSpace/fsp1/resume/resume.pdf');
+ * // { uid: 'user123', formSpaceId: 'fsp1', slot: 'resume', filename: 'resume.pdf' }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function parseFormSpaceUploadPath(path: SlashPath): Maybe<ParsedFormSpaceUploadPath>;
+/**
+ * Upload policy for {@link FORM_SPACE_PURPOSE}.
+ *
+ * The caps here are the OUTER bound — the widest a FormSpace upload may ever be — and they are what
+ * `storage.rules` mirrors. The per-type and per-slot rules in the {@link FormSpaceTypeConfig} registry
+ * narrow it further, and are enforced by the initializer, which is the only layer that can read the
+ * FormSpace to learn which type it even is.
+ */
+export declare const FORM_SPACE_UPLOAD_POLICY: StorageFilePurposeUploadPolicy;