@dereekb/firebase 13.2.2 → 13.3.1

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

@@ -0,0 +1,131 @@
+import { type Type } from 'arktype';
+import { type TargetModelParams, type OnCallCreateModelResult } from '../../common';
+import { type InferredTargetModelParams } from '../../common/model/model/model.param';
+import { type ModelFirebaseCrudFunction, type FirebaseFunctionTypeConfigMap, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap, type ModelFirebaseCreateFunction, type ModelFirebaseDeleteFunction, type ModelFirebaseUpdateFunction } from '../../client';
+import { type WebsiteUrlWithPrefix, type Maybe } from '@dereekb/util';
+import { type OidcEntryClientId } from './oidcmodel.id';
+import { type OidcModelTypes } from './oidcmodel';
+import { type OidcRedirectUri, type OidcTokenEndpointAuthMethod } from './oidcmodel.interaction';
+/**
+ * Fields that can be changed on an existing OIDC client.
+ *
+ * Does NOT include `token_endpoint_auth_method` — that is immutable after creation.
+ */
+export interface UpdateOidcClientFieldParams {
+    readonly client_name: string;
+    readonly redirect_uris: OidcRedirectUri[];
+    readonly logo_uri?: Maybe<WebsiteUrlWithPrefix>;
+    readonly client_uri?: Maybe<WebsiteUrlWithPrefix>;
+}
+export declare const updateOidcClientFieldParamsType: Type<UpdateOidcClientFieldParams>;
+export declare const createOidcClientFieldParamsType: import("arktype/internal/variants/object.ts").ObjectType<{
+    readonly client_name: string;
+    readonly redirect_uris: OidcRedirectUri[];
+    readonly logo_uri?: Maybe<string>;
+    readonly client_uri?: Maybe<string>;
+    token_endpoint_auth_method: "client_secret_basic" | "client_secret_post" | "client_secret_jwt" | "private_key_jwt";
+}, {}>;
+/**
+ * Parameters for registering a new OAuth client for the target entity.
+ *
+ * If no target model is provided, assumes the current user.
+ *
+ * The server generates `client_id` and `client_secret` and creates the adapter entry.
+ *
+ * Extends {@link UpdateOidcClientFieldParams} with `token_endpoint_auth_method` which is immutable after creation.
+ */
+export interface CreateOidcClientParams extends UpdateOidcClientFieldParams, InferredTargetModelParams {
+    readonly token_endpoint_auth_method: OidcTokenEndpointAuthMethod;
+    /**
+     * URL where the client's public JSON Web Key Set can be fetched.
+     *
+     * Used with `private_key_jwt` authentication so the provider can retrieve
+     * the client's public keys to verify `client_assertion` JWTs.
+     * The client manages key rotation at this URL independently.
+     */
+    readonly jwks_uri?: WebsiteUrlWithPrefix;
+}
+export declare const createOidcClientParamsType: Type<CreateOidcClientParams>;
+/**
+ * Result of creating a new OAuth client.
+ *
+ * Includes the generated `client_secret` in plaintext — this is the only time
+ * it is returned to the caller.
+ */
+export interface CreateOidcClientResult extends OnCallCreateModelResult {
+    readonly client_id: OidcEntryClientId;
+    readonly client_secret: string;
+}
+/**
+ * Parameters for updating an existing OAuth client.
+ *
+ * Uses {@link UpdateOidcClientFieldParams} — `token_endpoint_auth_method` is immutable.
+ */
+export interface UpdateOidcClientParams extends UpdateOidcClientFieldParams, TargetModelParams {
+}
+export declare const updateOidcClientParamsType: Type<UpdateOidcClientParams>;
+export type RotateOidcClientSecretParams = TargetModelParams;
+export declare const rotateOidcClientSecretParamsType: Type<RotateOidcClientSecretParams>;
+export type RotateOidcClientSecretResult = Pick<CreateOidcClientResult, 'client_id' | 'client_secret'>;
+/**
+ * Parameters for revoking/deleting an OAuth client.
+ */
+export type DeleteOidcClientParams = TargetModelParams;
+export declare const deleteOidcClientParamsType: Type<DeleteOidcClientParams>;
+/**
+ * Custom (non-CRUD) function type map for OIDC.
+ */
+export type OidcModelFunctionTypeMap = {};
+export declare const oidcFunctionTypeConfigMap: FirebaseFunctionTypeConfigMap<OidcModelFunctionTypeMap>;
+/**
+ * CRUD function configuration map for the OIDC client model.
+ *
+ * Uses `oidcEntry` as the key, matching the adapter collection identity.
+ */
+export type OidcModelCrudFunctionsConfig = {
+    readonly oidcEntry: {
+        create: {
+            client: [CreateOidcClientParams, CreateOidcClientResult];
+        };
+        update: {
+            client: UpdateOidcClientParams;
+            rotateClientSecret: [RotateOidcClientSecretParams, RotateOidcClientSecretResult];
+        };
+        delete: {
+            client: DeleteOidcClientParams;
+        };
+    };
+};
+export declare const oidcModelCrudFunctionsConfig: ModelFirebaseCrudFunctionConfigMap<OidcModelCrudFunctionsConfig, OidcModelTypes>;
+/**
+ * Abstract class defining all callable OIDC cloud functions.
+ *
+ * Implement this in your app module to wire up the function endpoints.
+ */
+export declare abstract class OidcModelFunctions implements ModelFirebaseFunctionMap<OidcModelFunctionTypeMap, OidcModelCrudFunctionsConfig> {
+    abstract oidcEntry: {
+        createOidcEntry: {
+            client: ModelFirebaseCreateFunction<CreateOidcClientParams, CreateOidcClientResult>;
+        };
+        updateOidcEntry: {
+            client: ModelFirebaseCrudFunction<UpdateOidcClientParams>;
+            rotateClientSecret: ModelFirebaseUpdateFunction<RotateOidcClientSecretParams, RotateOidcClientSecretResult>;
+        };
+        deleteOidcEntry: {
+            client: ModelFirebaseDeleteFunction<DeleteOidcClientParams>;
+        };
+    };
+}
+/**
+ * Client-side callable function map factory for OIDC client CRUD operations.
+ *
+ * @example
+ * ```ts
+ * const functions = oidcFunctionMap(callableFactory);
+ * const result = await functions.oidcEntry.createOidcEntry.create({
+ *   client_name: 'My App',
+ *   redirect_uris: ['https://myapp.com/callback']
+ * });
+ * ```
+ */
+export declare const oidcModelFunctionMap: import("../..").ModelFirebaseFunctionMapFactory<OidcModelFunctionTypeMap, OidcModelCrudFunctionsConfig>;

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

@@ -0,0 +1,114 @@
+import { type JsonSerializableObject, type Maybe } from '@dereekb/util';
+import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext, type FirebaseAuthOwnershipKey } from '../../common';
+import { type GrantedDeleteRole, type GrantedReadRole, type GrantedUpdateRole } from '@dereekb/model';
+/**
+ * Union of model identity types used in the OIDC function map.
+ */
+export type OidcModelTypes = typeof oidcEntryIdentity;
+/**
+ * Abstract class providing access to all oidc-related Firestore collections.
+ *
+ * Implementations provide concrete collection instances wired to a specific {@link FirestoreContext}.
+ * Used by both client and server code to access oidc model documents.
+ *
+ * @see `OidcModelServerActions` in `@dereekb/firebase-server/oidc` for server-side action processing
+ */
+export declare abstract class OidcModelFirestoreCollections {
+    abstract readonly oidcEntryCollection: OidcEntryFirestoreCollection;
+}
+/**
+ * Firestore model identity for {@link OidcEntry} documents.
+ *
+ * Collection name: `oidcEntry`, short code: `oidc_e`.
+ */
+export declare const oidcEntryIdentity: import("../..").RootFirestoreModelIdentity<"oidcEntry", "oidc_e">;
+/**
+ * Known oidc-provider model types stored in the adapter collection.
+ *
+ * Used as the discriminator in the {@link OidcEntry.type} field.
+ */
+export type OidcEntryType = 'Session' | 'AccessToken' | 'AuthorizationCode' | 'RefreshToken' | 'DeviceCode' | 'ClientCredentials' | 'Client' | 'InitialAccessToken' | 'RegistrationAccessToken' | 'Interaction' | 'ReplayDetection' | 'PushedAuthorizationRequest' | 'Grant' | 'BackchannelAuthenticationRequest' | (string & {});
+/**
+ * Type value for Client adapter entries.
+ */
+export declare const OIDC_ENTRY_CLIENT_TYPE: OidcEntryType;
+/**
+ * oidc-provider adapter entry stored in Firestore.
+ *
+ * All oidc-provider model types (Session, AccessToken, Client, etc.) are stored in a single collection,
+ * discriminated by the {@link type} field. The full oidc-provider payload is serialized as JSON in
+ * the {@link payload} field. Sensitive fields within the payload (e.g. `client_secret`) may be
+ * selectively encrypted at rest.
+ *
+ * The {@link o} ownership field enables Firestore security rules to restrict reads to the owning user
+ * (used primarily for Client entries so users can query their own registered OAuth clients).
+ */
+export interface OidcEntry {
+    /**
+     * The oidc-provider model type (e.g., 'Session', 'AccessToken', 'Client').
+     */
+    type: string;
+    /**
+     * Serialized JSON of the full oidc-provider AdapterPayload.
+     *
+     * The payload structure varies by model type. Sensitive fields may be
+     * selectively encrypted (prefixed with `$`) when encryption is configured.
+     */
+    payload: JsonSerializableObject;
+    /**
+     * Ownership key for Firestore security rules.
+     *
+     * Set to the Firebase Auth UID of the user who created this entry.
+     * Used primarily on Client entries to allow users to query their own OAuth clients.
+     */
+    o?: Maybe<FirebaseAuthOwnershipKey>;
+    /**
+     * User identifier. Extracted from the payload for indexed queries.
+     */
+    uid?: Maybe<string>;
+    /**
+     * Grant identifier for revocation support. Extracted from the payload for indexed queries.
+     */
+    grantId?: Maybe<string>;
+    /**
+     * User code for device flow. Extracted from the payload for indexed queries.
+     */
+    userCode?: Maybe<string>;
+    /**
+     * Epoch timestamp when this entry was consumed. Extracted from the payload for indexed queries.
+     */
+    consumed?: Maybe<number>;
+    /**
+     * When this entry expires.
+     */
+    expiresAt?: Maybe<Date>;
+}
+export type OidcEntryRoles = GrantedReadRole | GrantedUpdateRole | GrantedDeleteRole;
+/**
+ * Firestore document wrapper for {@link OidcEntry}.
+ */
+export declare class OidcEntryDocument extends AbstractFirestoreDocument<OidcEntry, OidcEntryDocument, typeof oidcEntryIdentity> {
+    get modelIdentity(): import("../..").RootFirestoreModelIdentity<"oidcEntry", "oidc_e">;
+}
+/**
+ * Firestore snapshot converter for {@link OidcEntry} documents.
+ */
+export declare const oidcEntryConverter: import("../..").SnapshotConverterFunctions<OidcEntry, Partial<import("@dereekb/util").ReplaceType<OidcEntry, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Typed Firestore collection for {@link OidcEntry} documents.
+ */
+export type OidcEntryFirestoreCollection = FirestoreCollection<OidcEntry, OidcEntryDocument>;
+/**
+ * Configuration for creating an {@link OidcEntryFirestoreCollection}.
+ */
+export interface OidcEntryFirestoreCollectionConfig {
+    readonly firestoreContext: FirestoreContext;
+}
+/**
+ * Returns the Firestore {@link CollectionReference} for {@link OidcEntry} documents.
+ */
+export declare function oidcEntryCollectionReference(context: FirestoreContext): CollectionReference<OidcEntry>;
+/**
+ * Creates an {@link OidcEntryFirestoreCollection} from the given configuration.
+ */
+export declare function oidcEntryFirestoreCollection(config: OidcEntryFirestoreCollectionConfig): OidcEntryFirestoreCollection;

package/src/lib/model/oidcmodel/oidcmodel.data.d.ts

@@ -0,0 +1,17 @@
+import { type Maybe } from '@dereekb/util';
+import { type OidcEntryClientId } from './oidcmodel.id';
+import { type OidcRedirectUri } from './oidcmodel.interaction';
+/**
+ * Corresponds with readable content from a OidcEntry's payload.
+ */
+export interface OidcEntryOAuthClientPayloadData {
+    readonly client_id: OidcEntryClientId;
+    readonly client_name?: Maybe<string>;
+    readonly redirect_uris: OidcRedirectUri[];
+    readonly grant_types: string[];
+    readonly response_types?: Maybe<string[]>;
+    readonly token_endpoint_auth_method?: Maybe<string>;
+    readonly logo_uri?: Maybe<string>;
+    readonly client_uri?: Maybe<string>;
+    readonly created_at?: string;
+}

package/src/lib/model/oidcmodel/oidcmodel.id.d.ts

@@ -0,0 +1,18 @@
+import { type FirestoreModelId, type FirestoreModelKey } from '../../common';
+/**
+ * Document ID for an OidcEntry.
+ *
+ * NOTE: This id may include dashes or underscores, so this type is not compatable with TwoWayFlatFirestoreModelKey usage.
+ *
+ * The ID is assigned by the oidc-provider library and varies by model type
+ * (e.g., opaque token string for AccessToken, random string for Session).
+ */
+export type OidcEntryId = FirestoreModelId;
+/**
+ * Full Firestore model key path for an OidcEntry document.
+ */
+export type OidcEntryKey = FirestoreModelKey;
+/**
+ * Unique client identifier for an OIDC client registration.
+ */
+export type OidcEntryClientId = string;

package/src/lib/model/oidcmodel/oidcmodel.interaction.d.ts

@@ -0,0 +1,40 @@
+import { type LabeledValue, type LabeledValueWithDescription } from '@dereekb/util';
+/**
+ * Unique identifier for an oidc-provider interaction session, not to be confused with a Firebase UID/Auth User Identifier.
+ *
+ * Generated by the provider when user interaction is needed (login/consent).
+ * Used to look up the interaction session via cookies and to build
+ * backend interaction endpoint URLs (e.g., `/interaction/${uid}/login`).
+ */
+export type OidcInteractionUid = string;
+/**
+ * Base type for OIDC scope string unions.
+ *
+ * Applications define their own scope union extending this type to get
+ * compile-time validation of scope names throughout the delegate and config.
+ *
+ * @example
+ * ```typescript
+ * type MyScopes = 'openid' | 'profile' | 'email';
+ * ```
+ */
+export type OidcScope = string;
+/**
+ * Scope details with a human-readable label and description.
+ */
+export type OidcScopeDetails<T extends OidcScope = OidcScope> = LabeledValueWithDescription<T>;
+/**
+ * A redirect URI registered to an OIDC client.
+ *
+ * Must be a valid absolute URL (e.g. `https://myapp.example.com/callback`).
+ */
+export type OidcRedirectUri = string;
+/**
+ * Supported values for `token_endpoint_auth_method` when creating an OIDC client.
+ */
+export type OidcTokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'client_secret_jwt' | 'private_key_jwt';
+export declare const PRIVATE_KEY_JWT_TOKEN_ENDPOINT_AUTH_METHOD: OidcTokenEndpointAuthMethod;
+/**
+ * All available token endpoint auth method options with display labels.
+ */
+export declare const ALL_OIDC_TOKEN_ENDPOINT_AUTH_METHOD_OPTIONS: LabeledValue<OidcTokenEndpointAuthMethod>[];

package/src/lib/model/oidcmodel/oidcmodel.interaction.oauth.d.ts

@@ -0,0 +1,73 @@
+import { type Maybe, type SpaceSeparatedString, type WebsiteUrlWithPrefix } from '@dereekb/util';
+import { type FirebaseAuthIdToken } from '../../common/auth/auth';
+import { type OidcEntryClientId } from './oidcmodel.id';
+import { type OidcScope } from './oidcmodel.interaction';
+/**
+ * Request body sent by the frontend to complete a login interaction.
+ *
+ * Posted to `POST /interaction/:uid/login` by the frontend after
+ * the user authenticates via Firebase.
+ */
+export interface OAuthInteractionLoginRequest {
+    /**
+     * Firebase Auth ID token.
+     *
+     * The backend verifies this token via `admin.auth().verifyIdToken()` and
+     * uses the decoded UID as the `accountId` for the oidc-provider login result.
+     */
+    readonly idToken: FirebaseAuthIdToken;
+}
+/**
+ * Space-separated string of scopes requested by the client.
+ */
+export type OAuthInteractionScopes<T extends OidcScope = OidcScope> = SpaceSeparatedString<T>;
+/**
+ * Details about oauth client and interaction.
+ */
+export interface OAuthInteractionLoginDetails<T extends OidcScope = OidcScope> {
+    readonly client_id: OidcEntryClientId;
+    readonly client_name?: Maybe<string>;
+    readonly logo_uri?: Maybe<string>;
+    readonly client_uri?: Maybe<string>;
+    readonly scopes: OAuthInteractionScopes<T>;
+}
+/**
+ * Response from the server after a successful interaction submission.
+ *
+ * The server returns a redirect URL that the client should navigate to
+ * in order to complete the OIDC flow.
+ */
+export interface OAuthInteractionLoginResponse {
+    readonly redirectTo: WebsiteUrlWithPrefix;
+}
+/**
+ * Request body sent by the frontend to complete a consent interaction.
+ *
+ * Posted to `POST /interaction/:uid/consent` by the frontend after
+ * the user approves or denies the requested scopes/claims.
+ */
+export interface OAuthInteractionConsentRequest {
+    /**
+     * Firebase Auth ID token.
+     *
+     * The backend verifies this token to confirm the caller is the
+     * same user who completed the login interaction.
+     */
+    readonly idToken: FirebaseAuthIdToken;
+    /**
+     * Whether the user approved the consent.
+     *
+     * When `true`, the backend grants missing scopes/claims and completes the interaction.
+     * When `false`, the backend returns `access_denied` to the OAuth client.
+     */
+    readonly approved: boolean;
+}
+/**
+ * Response from the server after a successful interaction submission.
+ *
+ * The server returns a redirect URL that the client should navigate to
+ * in order to complete the OIDC flow.
+ */
+export interface OAuthInteractionConsentResponse {
+    readonly redirectTo: WebsiteUrlWithPrefix;
+}

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

@@ -0,0 +1,21 @@
+import { type FirebaseAuthOwnershipKey, type FirestoreQueryConstraint } from '../../common';
+/**
+ * Query for OidcEntry documents with a specific type.
+ */
+export declare function oidcEntriesWithTypeQuery(type: string): FirestoreQueryConstraint[];
+/**
+ * Query for OidcEntry documents with a specific type and userCode.
+ */
+export declare function oidcEntriesByUserCodeQuery(type: string, userCode: string): FirestoreQueryConstraint[];
+/**
+ * Query for OidcEntry documents with a specific type and uid.
+ */
+export declare function oidcEntriesByUidQuery(type: string, uid: string): FirestoreQueryConstraint[];
+/**
+ * Query for OidcEntry documents with a specific type and grantId.
+ */
+export declare function oidcEntriesByGrantIdQuery(type: string, grantId: string): FirestoreQueryConstraint[];
+/**
+ * Query for OidcEntry Client documents owned by a specific user.
+ */
+export declare function oidcClientEntriesByOwnerQuery(ownershipKey: FirebaseAuthOwnershipKey): FirestoreQueryConstraint[];

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

@@ -1,14 +1,61 @@
 import { type AsyncFirebaseFunctionDeleteAction, type FirebaseFunctionDeleteAction, type AsyncFirebaseFunctionCreateAction, type AsyncFirebaseFunctionUpdateAction, type FirebaseFunctionCreateAction, type FirebaseFunctionUpdateAction } from '../../common';
 import { type StorageFileGroupDocument, type StorageFileDocument } from './storagefile';
+/**
+ * @module storagefile.action
+ *
+ * Type aliases for StorageFile and StorageFileGroup server action functions.
+ *
+ * These connect API parameter types to their target document types, following the same
+ * pattern as notification actions. See `@dereekb/firebase-server/model` for the
+ * server-side action service implementations.
+ *
+ * @template P - the API parameter type for the action
+ */
+/**
+ * Synchronous create action targeting a {@link StorageFileDocument}.
+ */
 export type StorageFileCreateAction<P extends object> = FirebaseFunctionCreateAction<P, StorageFileDocument>;
+/**
+ * Async create action targeting a {@link StorageFileDocument}.
+ */
 export type AsyncStorageFileCreateAction<P extends object> = AsyncFirebaseFunctionCreateAction<P, StorageFileDocument>;
+/**
+ * Synchronous update action targeting a {@link StorageFileDocument}.
+ */
 export type StorageFileUpdateAction<P extends object> = FirebaseFunctionUpdateAction<P, StorageFileDocument>;
+/**
+ * Async update action targeting a {@link StorageFileDocument}.
+ */
 export type AsyncStorageFileUpdateAction<P extends object> = AsyncFirebaseFunctionUpdateAction<P, StorageFileDocument>;
+/**
+ * Synchronous delete action targeting a {@link StorageFileDocument}.
+ */
 export type StorageFileDeleteAction<P extends object> = FirebaseFunctionDeleteAction<P, StorageFileDocument>;
+/**
+ * Async delete action targeting a {@link StorageFileDocument}.
+ */
 export type AsyncStorageFileDeleteAction<P extends object> = AsyncFirebaseFunctionDeleteAction<P, StorageFileDocument>;
+/**
+ * Synchronous create action targeting a {@link StorageFileGroupDocument}.
+ */
 export type StorageFileGroupCreateAction<P extends object> = FirebaseFunctionCreateAction<P, StorageFileGroupDocument>;
+/**
+ * Async create action targeting a {@link StorageFileGroupDocument}.
+ */
 export type AsyncStorageFileGroupCreateAction<P extends object> = AsyncFirebaseFunctionCreateAction<P, StorageFileGroupDocument>;
+/**
+ * Synchronous update action targeting a {@link StorageFileGroupDocument}.
+ */
 export type StorageFileGroupUpdateAction<P extends object> = FirebaseFunctionUpdateAction<P, StorageFileGroupDocument>;
+/**
+ * Async update action targeting a {@link StorageFileGroupDocument}.
+ */
 export type AsyncStorageFileGroupUpdateAction<P extends object> = AsyncFirebaseFunctionUpdateAction<P, StorageFileGroupDocument>;
+/**
+ * Synchronous delete action targeting a {@link StorageFileGroupDocument}.
+ */
 export type StorageFileGroupDeleteAction<P extends object> = FirebaseFunctionDeleteAction<P, StorageFileGroupDocument>;
+/**
+ * Async delete action targeting a {@link StorageFileGroupDocument}.
+ */
 export type AsyncStorageFileGroupDeleteAction<P extends object> = AsyncFirebaseFunctionDeleteAction<P, StorageFileGroupDocument>;

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

@@ -7,13 +7,18 @@ import { type ContentDispositionString, type ContentTypeMimeType, type Maybe, ty
 import { type StorageFileId } from './storagefile.id';
 import { type SendNotificationResult } from '../notification/notification.api';
 /**
- * Used for directly create a new StorageFile.
+ * Parameters for directly creating a new StorageFile document (no upload initialization).
+ *
+ * Typically used server-side or for testing. Validated with {@link createStorageFileParamsType}.
  */
 export interface CreateStorageFileParams {
 }
 export declare const createStorageFileParamsType: Type<CreateStorageFileParams>;
 /**
- * Initializes all StorageFiles in the uploads folder.
+ * Parameters for batch-initializing all files found in the uploads folder.
+ *
+ * Scans the uploads folder (or a custom path) and runs the upload determination/initialization
+ * pipeline for each file found. Validated with {@link initializeAllStorageFilesFromUploadsParamsType}.
  */
 export interface InitializeAllStorageFilesFromUploadsParams {
     readonly maxFilesToInitialize?: Maybe<number>;
@@ -21,13 +26,19 @@ export interface InitializeAllStorageFilesFromUploadsParams {
     readonly overrideUploadsFolderPath?: Maybe<StorageSlashPath>;
 }
 export declare const initializeAllStorageFilesFromUploadsParamsType: Type<InitializeAllStorageFilesFromUploadsParams>;
+/**
+ * Result of batch upload initialization, reporting visit and success/failure counts.
+ */
 export interface InitializeAllStorageFilesFromUploadsResult extends OnCallCreateModelResult {
     readonly filesVisited: number;
     readonly initializationsSuccessCount: number;
     readonly initializationsFailureCount: number;
 }
 /**
- * Initializes a StorageFile from the document at the given path.
+ * Parameters for initializing a single StorageFile from an uploaded file at a specific storage path.
+ *
+ * The file is run through the upload type determination pipeline and, if matched,
+ * creates a corresponding StorageFile document. Validated with {@link initializeStorageFileFromUploadParamsType}.
  */
 export interface InitializeStorageFileFromUploadParams extends Pick<StoragePath, 'pathString'> {
     readonly bucketId?: Maybe<StorageBucketId>;
@@ -35,6 +46,12 @@ export interface InitializeStorageFileFromUploadParams extends Pick<StoragePath,
     readonly expediteProcessing?: boolean;
 }
 export declare const initializeStorageFileFromUploadParamsType: Type<InitializeStorageFileFromUploadParams>;
+/**
+ * Parameters for triggering processing of a specific StorageFile.
+ *
+ * Supports various modes: immediate processing, retry checking, force restart,
+ * and reprocessing already-successful files. Validated with {@link processStorageFileParamsType}.
+ */
 export interface ProcessStorageFileParams extends TargetModelParams {
     readonly runImmediately?: Maybe<boolean>;
     readonly checkRetryProcessing?: Maybe<boolean>;
@@ -76,6 +93,12 @@ export interface DeleteAllQueuedStorageFilesResult {
     readonly storageFilesDeleted: number;
     readonly storageFilesFailedDeleting: number;
 }
+/**
+ * Parameters for generating a signed download URL for a StorageFile.
+ *
+ * Supports custom expiration, content disposition, and content type overrides.
+ * Admin downloads (`asAdmin`) allow longer expiration times. Validated with {@link downloadStorageFileParamsType}.
+ */
 export interface DownloadStorageFileParams extends TargetModelParams {
     readonly expiresAt?: Maybe<Date>;
     readonly expiresIn?: Maybe<Milliseconds>;
@@ -160,8 +183,20 @@ export interface InitializeAllApplicableStorageFileGroupsResult {
     readonly storageFileGroupsFailed: number;
     readonly storageFileGroupsAlreadyInitialized: number;
 }
+/**
+ * Custom (non-CRUD) function type map for StorageFile. Currently empty — all operations use CRUD functions.
+ */
 export type StorageFileFunctionTypeMap = {};
 export declare const storageFileFunctionTypeConfigMap: FirebaseFunctionTypeConfigMap<StorageFileFunctionTypeMap>;
+/**
+ * CRUD function configuration map for the StorageFile model family.
+ *
+ * Defines all callable cloud function endpoints for StorageFile and StorageFileGroup,
+ * including creation (direct, from upload, batch), processing, sync, download, and deletion.
+ *
+ * Used by {@link StorageFileFunctions} and {@link storageFileFunctionMap} to generate
+ * typed callable function references.
+ */
 export type StorageFileModelCrudFunctionsConfig = {
     readonly storageFile: {
         create: {
@@ -181,7 +216,7 @@ export type StorageFileModelCrudFunctionsConfig = {
             _: DeleteStorageFileParams;
         };
     };
-    storageFileGroup: {
+    readonly storageFileGroup: {
         update: {
             _: UpdateStorageFileGroupParams;
             regenerateContent: [RegenerateStorageFileGroupContentParams, RegenerateStorageFileGroupContentResult];
@@ -189,6 +224,12 @@ export type StorageFileModelCrudFunctionsConfig = {
     };
 };
 export declare const storageFileModelCrudFunctionsConfig: ModelFirebaseCrudFunctionConfigMap<StorageFileModelCrudFunctionsConfig, StorageFileTypes>;
+/**
+ * Abstract class defining all callable StorageFile cloud functions.
+ *
+ * Implement this in your app module to wire up the function endpoints.
+ * Use {@link storageFileFunctionMap} to create a client-side callable map.
+ */
 export declare abstract class StorageFileFunctions implements ModelFirebaseFunctionMap<StorageFileFunctionTypeMap, StorageFileModelCrudFunctionsConfig> {
     abstract storageFile: {
         createStorageFile: {
@@ -215,4 +256,13 @@ export declare abstract class StorageFileFunctions implements ModelFirebaseFunct
         };
     };
 }
+/**
+ * Client-side callable function map factory for all StorageFile and StorageFileGroup CRUD operations.
+ *
+ * @example
+ * ```ts
+ * const functions = storageFileFunctionMap(callableFactory);
+ * const result = await functions.storageFile.createStorageFile.fromUpload({ pathString: 'uploads/u/123/avatar.png' });
+ * ```
+ */
 export declare const storageFileFunctionMap: import("../..").ModelFirebaseFunctionMapFactory<StorageFileFunctionTypeMap, StorageFileModelCrudFunctionsConfig>;