@dereekb/firebase 13.41.0 → 13.43.0

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

@@ -0,0 +1,139 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId } from '../../common/auth/auth';
+import { type StorageFile } from '../storagefile/storagefile';
+import { type FormSpace, type FormSpaceFile, type FormSpaceFirestoreCollections } from './formspace';
+import { type FormSpaceFileSlot, type FormSpaceKey } from './formspace.id';
+import { type AppFormSpaceTypeConfigService, type FormSpaceFileAccess, type FormSpaceTypeConfig } from './formspace.type';
+/**
+ * Input for {@link formSpaceSlotFileAccess}.
+ */
+export interface FormSpaceSlotFileAccessInput {
+    readonly config: FormSpaceTypeConfig;
+    readonly slot: Maybe<FormSpaceFileSlot>;
+}
+/**
+ * Resolves the {@link FormSpaceFileAccess} governing one slot.
+ *
+ * Slot narrows type narrows default, the same precedence `allowedMimeTypes` and `maxFileSizeBytes` use.
+ *
+ * @param input - The type config and the slot.
+ * @returns The effective file access policy.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceSlotFileAccess(input: FormSpaceSlotFileAccessInput): FormSpaceFileAccess;
+/**
+ * Input for {@link formSpaceFileUploaderId}.
+ */
+export interface FormSpaceFileUploaderIdInput {
+    readonly formSpace: Pick<FormSpace, 'u'>;
+    readonly file: Pick<FormSpaceFile, 'ub'>;
+}
+/**
+ * The uid that owns one file for access purposes.
+ *
+ * Falls back to the space's `u` when the entry carries no `ub`. That is not a guess: `ub` was added after
+ * FormSpace shipped, and every entry written before it existed came from the only party that could upload
+ * at the time — the space's own user. Falling back keeps an older single-user space working unchanged
+ * under an `'uploader'` policy instead of locking its owner out of their own files.
+ *
+ * @param input - The space and the file entry.
+ * @returns The uploader's uid.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceFileUploaderId(input: FormSpaceFileUploaderIdInput): FirebaseAuthUserId;
+/**
+ * Input for {@link isFormSpaceFileAccessibleWithAccess}.
+ */
+export interface IsFormSpaceFileAccessibleWithAccessInput {
+    readonly fileAccess: FormSpaceFileAccess;
+    readonly formSpace: Pick<FormSpace, 'u'>;
+    readonly file: Pick<FormSpaceFile, 'ub'>;
+    readonly uid: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * THE per-file rule, applied to an ALREADY-RESOLVED {@link FormSpaceFileAccess}.
+ *
+ * Split from {@link isFormSpaceFileAccessibleByUser} so a caller holding the policy but not the whole
+ * `FormSpaceTypeConfig` — a UI handed `fileAccess` as an input, say — decides with the same function the
+ * server enforces with, rather than a second copy of `ub ?? u` that could drift from it.
+ *
+ * @param input - The resolved policy, the space, the file entry, and the caller.
+ * @returns True when the caller may read and remove this file.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isFormSpaceFileAccessibleWithAccess(input: IsFormSpaceFileAccessibleWithAccessInput): boolean;
+/**
+ * Input for {@link isFormSpaceFileAccessibleByUser}.
+ */
+export interface IsFormSpaceFileAccessibleByUserInput {
+    readonly formSpace: Pick<FormSpace, 'u'>;
+    readonly config: FormSpaceTypeConfig;
+    readonly file: Pick<FormSpaceFile, 'sl' | 'ub'>;
+    readonly uid: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * THE per-file predicate: may this user read or remove this file, given they already reach the space?
+ *
+ * One function for both verbs on purpose. "You can see it but not delete it" and "you can delete it but not
+ * see it" are both worse than either consistent answer, and two policies would be two things to keep in
+ * step. A type that genuinely needs to split them should keep files in separate slots and narrow one.
+ *
+ * @param input - The space, its type config, the file entry, and the caller.
+ * @returns True when the caller may read and remove this file.
+ *
+ * @example
+ * ```ts
+ * const allowed = isFormSpaceFileAccessibleByUser({ formSpace, config, file, uid: context.auth?.uid });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isFormSpaceFileAccessibleByUser(input: IsFormSpaceFileAccessibleByUserInput): boolean;
+/**
+ * Returns the {@link FormSpaceKey} a StorageFile was uploaded into, or null when it is not a FormSpace file.
+ *
+ * Reads the group ids rather than a dedicated field: a FormSpace upload joins the group
+ * {@link formSpaceStorageFileGroupId} keys by the space's own model key, so the key is already recoverable
+ * and a second copy of it could only drift. The purpose is checked first, so a file from any other pipeline
+ * costs one string comparison.
+ *
+ * Decoded by splitting the FIRST separator rather than through
+ * {@link inferStorageFileGroupRelatedModelKey}, which replaces EVERY `_` with a `/`. That generic inverse is
+ * only two-way for an id that contains no underscore, and a space keyed by {@link formSpaceIdForModel}
+ * always does — a guestbook's album is `fsp/gb_<id>`, which the generic inverse turns into the three-segment
+ * `fsp/gb/<id>`: not a document path at all. FormSpace is a ROOT collection, so everything after the first
+ * separator is the id, underscores and all.
+ *
+ * @param storageFile - The StorageFile to inspect.
+ * @returns The FormSpace's model key, or null.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function formSpaceKeyForStorageFile(storageFile: Pick<StorageFile, 'p' | 'g'>): Maybe<FormSpaceKey>;
+/**
+ * Input for {@link isFormSpaceStorageFileAccessibleByUser}.
+ */
+export interface IsFormSpaceStorageFileAccessibleByUserInput {
+    readonly collections: FormSpaceFirestoreCollections;
+    readonly appFormSpaceTypeConfigService: AppFormSpaceTypeConfigService;
+    readonly storageFile: Pick<StorageFile, 'p' | 'g' | 'pg' | 'uby'>;
+    readonly uid: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * {@link isFormSpaceFileAccessibleByUser}, asked from the StorageFile side — where a download is authorized.
+ *
+ * Returns true for a StorageFile that is not a FormSpace upload at all, so a caller can AND it into an
+ * existing role grant without first classifying the file: this narrows FormSpace files and abstains on
+ * everything else.
+ *
+ * Costs at most one FormSpace read, and usually none. A caller who IS the file's `uby` is allowed under
+ * BOTH policies, so the space never has to be loaded to answer for them — which is the common case, since
+ * the person downloading a file is overwhelmingly the person who uploaded it.
+ *
+ * @param input - The collections, the type registry, the StorageFile, and the caller.
+ * @returns True when the caller may read this file.
+ */
+export declare function isFormSpaceStorageFileAccessibleByUser(input: IsFormSpaceStorageFileAccessibleByUserInput): Promise<boolean>;

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

@@ -0,0 +1,34 @@
+import { type AsyncFirebaseFunctionCreateAction, type AsyncFirebaseFunctionDeleteAction, type AsyncFirebaseFunctionUpdateAction, type FirebaseFunctionCreateAction, type FirebaseFunctionDeleteAction, type FirebaseFunctionUpdateAction } from '../../common';
+import { type FormSpaceDocument } from './formspace';
+/**
+ * @module formspace.action
+ *
+ * Type aliases for FormSpace server action functions, following the same pattern as the StorageFile and
+ * Calendar actions. See `@dereekb/firebase-server/model` for the implementations.
+ *
+ * @template P - the parameter type for the action
+ */
+/**
+ * Synchronous create action targeting a {@link FormSpaceDocument}.
+ */
+export type FormSpaceCreateAction<P extends object> = FirebaseFunctionCreateAction<P, FormSpaceDocument>;
+/**
+ * Async create action targeting a {@link FormSpaceDocument}.
+ */
+export type AsyncFormSpaceCreateAction<P extends object> = AsyncFirebaseFunctionCreateAction<P, FormSpaceDocument>;
+/**
+ * Synchronous update action targeting a {@link FormSpaceDocument}.
+ */
+export type FormSpaceUpdateAction<P extends object> = FirebaseFunctionUpdateAction<P, FormSpaceDocument>;
+/**
+ * Async update action targeting a {@link FormSpaceDocument}.
+ */
+export type AsyncFormSpaceUpdateAction<P extends object> = AsyncFirebaseFunctionUpdateAction<P, FormSpaceDocument>;
+/**
+ * Synchronous delete action targeting a {@link FormSpaceDocument}.
+ */
+export type FormSpaceDeleteAction<P extends object> = FirebaseFunctionDeleteAction<P, FormSpaceDocument>;
+/**
+ * Async delete action targeting a {@link FormSpaceDocument}.
+ */
+export type AsyncFormSpaceDeleteAction<P extends object> = AsyncFirebaseFunctionDeleteAction<P, FormSpaceDocument>;

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

@@ -0,0 +1,216 @@
+import { type Type } from 'arktype';
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type FirestoreModelKey, type OnCallCreateModelResult, type TargetModelParams } from '../../common';
+import { type FirebaseFunctionTypeConfigMap, type ModelFirebaseCreateFunction, type ModelFirebaseCrudFunction, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap } from '../../client';
+import { type StorageFileId } from '../storagefile/storagefile.id';
+import { type FormSpaceData, type FormSpaceTypes } from './formspace';
+import { type FormSpaceFileSlot, type FormSpaceType } from './formspace.id';
+/**
+ * @module formspace.api
+ *
+ * ARKTYPE PARAM/RESULT TYPES plus the callable CRUD map for the FormSpace model.
+ *
+ * Unlike Calendar — which is driven entirely internally — a FormSpace is a CLIENT-FACING container: the
+ * user creates it, edits it, and submits it, so every one of those is a callable.
+ */
+/**
+ * Parameters for creating a FormSpace.
+ *
+ * @dbxModelApiParams
+ */
+export interface CreateFormSpaceParams<T extends FormSpaceData = FormSpaceData> {
+    /**
+     * The registered {@link FormSpaceType} to create. Creation of an unregistered type is rejected.
+     */
+    readonly formSpaceType: FormSpaceType;
+    /**
+     * Display name for the space.
+     */
+    readonly displayName?: Maybe<string>;
+    /**
+     * The model this space is being opened against, if any.
+     */
+    readonly targetModelKey?: Maybe<FirestoreModelKey>;
+    /**
+     * Initial form data.
+     */
+    readonly data?: Maybe<T>;
+}
+export declare const createFormSpaceParamsType: Type<CreateFormSpaceParams>;
+/**
+ * Parameters for updating a draft FormSpace's content.
+ *
+ * `data` REPLACES the stored JSON rather than merging into it. The client owns the whole form; a merge
+ * would make clearing a field impossible to express.
+ *
+ * @dbxModelApiParams
+ */
+export interface UpdateFormSpaceParams<T extends FormSpaceData = FormSpaceData> extends TargetModelParams {
+    readonly displayName?: Maybe<string>;
+    readonly data?: Maybe<T>;
+}
+export declare const updateFormSpaceParamsType: Type<UpdateFormSpaceParams>;
+/**
+ * Parameters for submitting a FormSpace.
+ *
+ * @dbxModelApiParams
+ */
+export interface SubmitFormSpaceParams extends TargetModelParams {
+    /**
+     * Whether to run the submission's processing task immediately rather than waiting for the queue.
+     */
+    readonly runImmediately?: Maybe<boolean>;
+}
+export declare const submitFormSpaceParamsType: Type<SubmitFormSpaceParams>;
+/**
+ * Result of submitting a FormSpace.
+ */
+export interface SubmitFormSpaceResult {
+    /**
+     * The key of the NotificationTask processing the submission.
+     */
+    readonly processingNotificationKey: string;
+    /**
+     * True if the processing task was newly created by this call.
+     */
+    readonly processingTaskCreated: boolean;
+}
+/**
+ * Parameters for removing one uploaded file from a FormSpace slot.
+ *
+ * The file is dropped from the space's `f` array and its StorageFile is FLAGGED for deletion, never deleted
+ * inline — the StorageFile delete sweep owns removing the object, and a second code path that removed it
+ * here is how an orphaned object gets left behind.
+ *
+ * @dbxModelApiParams
+ */
+export interface RemoveFormSpaceFileParams extends TargetModelParams {
+    /**
+     * The slot holding the file.
+     */
+    readonly slot: FormSpaceFileSlot;
+    /**
+     * The StorageFile to remove.
+     *
+     * Optional only when the slot holds exactly one file: a folder slot with several files has no unambiguous
+     * "the" file, so omitting it there is an error rather than a guess.
+     */
+    readonly storageFileId?: Maybe<StorageFileId>;
+}
+export declare const removeFormSpaceFileParamsType: Type<RemoveFormSpaceFileParams>;
+/**
+ * Parameters for deleting a FormSpace and flagging its uploaded files for deletion.
+ *
+ * @dbxModelApiParams
+ */
+export interface DeleteFormSpaceParams extends TargetModelParams {
+}
+export declare const deleteFormSpaceParamsType: Type<DeleteFormSpaceParams>;
+/**
+ * Parameters for the backstop sweep over FormSpaces stuck in QUEUED_FOR_PROCESSING.
+ */
+export interface ProcessAllQueuedFormSpacesParams {
+    /**
+     * Maximum number of spaces to visit. Defaults to unbounded.
+     */
+    readonly limit?: Maybe<number>;
+}
+export declare const processAllQueuedFormSpacesParamsType: Type<ProcessAllQueuedFormSpacesParams>;
+/**
+ * Result of the backstop processing sweep.
+ */
+export interface ProcessAllQueuedFormSpacesResult {
+    readonly formSpacesVisited: number;
+    readonly formSpacesProcessStarted: number;
+    readonly formSpacesFailedStarting: number;
+}
+/**
+ * Parameters for the expiration sweep.
+ */
+export interface ExpireAllExpiredFormSpacesParams {
+    /**
+     * Spaces whose `eat` is at or before this instant are expired. Defaults to now.
+     */
+    readonly before?: Maybe<Date>;
+    /**
+     * Spaces expired per page.
+     */
+    readonly pageSize?: Maybe<number>;
+    /**
+     * Hard wall-clock budget for the whole sweep.
+     */
+    readonly maxRunTimeMs?: Maybe<Milliseconds>;
+    /**
+     * Maximum number of pages. Defaults to unlimited, bounded by the time budget.
+     */
+    readonly maxPages?: Maybe<number>;
+}
+export declare const expireAllExpiredFormSpacesParamsType: Type<ExpireAllExpiredFormSpacesParams>;
+/**
+ * Result of the expiration sweep.
+ */
+export interface ExpireAllExpiredFormSpacesResult {
+    readonly formSpacesExpired: number;
+    readonly storageFilesFlaggedForDelete: number;
+    readonly pages: number;
+    /**
+     * Whether the sweep stopped because its time budget ran out rather than because nothing was left.
+     */
+    readonly stoppedForTimeBudget: boolean;
+    readonly durationMs: Milliseconds;
+}
+/**
+ * Custom (non-CRUD) function type map for FormSpace. Currently empty — all operations use CRUD functions.
+ */
+export type FormSpaceFunctionTypeMap = {};
+export declare const FORM_SPACE_FUNCTION_TYPE_CONFIG_MAP: FirebaseFunctionTypeConfigMap<FormSpaceFunctionTypeMap>;
+/**
+ * CRUD function configuration map for the FormSpace model family.
+ */
+export type FormSpaceModelCrudFunctionsConfig = {
+    readonly formSpace: {
+        create: {
+            _: CreateFormSpaceParams;
+        };
+        update: {
+            _: UpdateFormSpaceParams;
+            submit: [SubmitFormSpaceParams, SubmitFormSpaceResult];
+            removeFile: RemoveFormSpaceFileParams;
+        };
+        delete: {
+            _: DeleteFormSpaceParams;
+        };
+    };
+};
+export declare const FORM_SPACE_MODEL_CRUD_FUNCTIONS_CONFIG: ModelFirebaseCrudFunctionConfigMap<FormSpaceModelCrudFunctionsConfig, FormSpaceTypes>;
+/**
+ * Abstract class defining all callable FormSpace cloud functions.
+ *
+ * Implement this in your app module to wire up the function endpoints.
+ * Use {@link formSpaceFunctionMap} to create a client-side callable map.
+ */
+export declare abstract class FormSpaceFunctions implements ModelFirebaseFunctionMap<FormSpaceFunctionTypeMap, FormSpaceModelCrudFunctionsConfig> {
+    abstract formSpace: {
+        createFormSpace: {
+            create: ModelFirebaseCreateFunction<CreateFormSpaceParams, OnCallCreateModelResult>;
+        };
+        updateFormSpace: {
+            update: ModelFirebaseCrudFunction<UpdateFormSpaceParams>;
+            submit: ModelFirebaseCrudFunction<SubmitFormSpaceParams, SubmitFormSpaceResult>;
+            removeFile: ModelFirebaseCrudFunction<RemoveFormSpaceFileParams>;
+        };
+        deleteFormSpace: {
+            delete: ModelFirebaseCrudFunction<DeleteFormSpaceParams>;
+        };
+    };
+}
+/**
+ * Client-side callable function map factory for all FormSpace CRUD operations.
+ *
+ * @example
+ * ```ts
+ * const functions = formSpaceFunctionMap(callableFactory);
+ * const result = await functions.formSpace.createFormSpace.create({ formSpaceType: 'demo_example' });
+ * ```
+ */
+export declare const formSpaceFunctionMap: import("../..").ModelFirebaseFunctionMapFactory<FormSpaceFunctionTypeMap, FormSpaceModelCrudFunctionsConfig>;

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

@@ -0,0 +1,71 @@
+/**
+ * @module formspace.api.error
+ *
+ * Error codes raised by the FormSpace actions and its upload initializer.
+ */
+/**
+ * Thrown when a FormSpace is created for a {@link FormSpaceType} the app never registered.
+ *
+ * Unlike a SWEEP over existing documents — which falls back to {@link DEFAULT_FORM_SPACE_TYPE_CONFIG} so one
+ * bad document cannot take the pass down — creation is strict: an unregistered type has no upload rules and
+ * no handler, so a space of that type could never be filled in or submitted.
+ */
+export declare const FORM_SPACE_TYPE_NOT_REGISTERED_ERROR_CODE = "FORM_SPACE_TYPE_NOT_REGISTERED";
+/**
+ * Thrown when a FormSpace is edited, uploaded into, or submitted after it stopped being a draft.
+ */
+export declare const FORM_SPACE_NOT_EDITABLE_ERROR_CODE = "FORM_SPACE_NOT_EDITABLE";
+/**
+ * Thrown when a FormSpace is submitted while one of its type's required slots is still empty.
+ */
+export declare const FORM_SPACE_REQUIRED_SLOT_MISSING_ERROR_CODE = "FORM_SPACE_REQUIRED_SLOT_MISSING";
+/**
+ * Thrown when a FormSpace is submitted while one of its slots holds a file validation judged invalid.
+ *
+ * Separate from {@link FORM_SPACE_REQUIRED_SLOT_MISSING_ERROR_CODE}: the slot IS filled, so telling the owner
+ * to upload something would be wrong — they need to remove or replace what is already there.
+ */
+export declare const FORM_SPACE_HAS_INVALID_FILES_ERROR_CODE = "FORM_SPACE_HAS_INVALID_FILES";
+/**
+ * Thrown when a FormSpace is submitted while a slot that requires validation is still awaiting a verdict.
+ *
+ * Transient by nature — the same submission succeeds once validation concludes — which is why it is not
+ * folded into {@link FORM_SPACE_HAS_INVALID_FILES_ERROR_CODE}.
+ */
+export declare const FORM_SPACE_VALIDATION_PENDING_ERROR_CODE = "FORM_SPACE_VALIDATION_PENDING";
+/**
+ * Thrown when a file is removed from a FormSpace slot that does not hold it.
+ */
+export declare const FORM_SPACE_FILE_NOT_FOUND_ERROR_CODE = "FORM_SPACE_FILE_NOT_FOUND";
+/**
+ * Thrown when a caller who may reach the FormSpace may not touch THAT file of it.
+ *
+ * Distinct from a plain FORBIDDEN: the caller does hold the space-level role, and the refusal is the type's
+ * {@link FormSpaceFileAccess} narrowing it to the file's own uploader.
+ */
+export declare const FORM_SPACE_FILE_ACCESS_DENIED_ERROR_CODE = "FORM_SPACE_FILE_ACCESS_DENIED";
+/**
+ * Thrown when an upload is rejected by {@link assertFormSpaceUploadAllowed}.
+ */
+export declare const FORM_SPACE_UPLOAD_NOT_ALLOWED_ERROR_CODE = "FORM_SPACE_UPLOAD_NOT_ALLOWED";
+/**
+ * Thrown when a file is uploaded into a FormSpace by someone other than the user the space belongs to.
+ */
+export declare const FORM_SPACE_UPLOAD_USER_MISMATCH_ERROR_CODE = "FORM_SPACE_UPLOAD_USER_MISMATCH";
+/**
+ * Thrown when a FormSpace upload path names a FormSpace that does not exist.
+ */
+export declare const FORM_SPACE_NOT_FOUND_ERROR_CODE = "FORM_SPACE_NOT_FOUND";
+/**
+ * Thrown when a FormSpace is created at an explicit id that is already taken, without `getOrCreate`.
+ *
+ * Only reachable for a space keyed by {@link formSpaceIdForModel}; a generated id can never collide.
+ */
+export declare const FORM_SPACE_ALREADY_EXISTS_ERROR_CODE = "FORM_SPACE_ALREADY_EXISTS";
+/**
+ * Thrown when a get-or-create resolves to an existing FormSpace of a DIFFERENT {@link FormSpaceType}.
+ *
+ * Two types keyed to the same target model derive the same id, and returning the other type's space would
+ * hand the caller a document whose slots, expiration and submission handler are all someone else's.
+ */
+export declare const FORM_SPACE_TYPE_MISMATCH_ERROR_CODE = "FORM_SPACE_TYPE_MISMATCH";