@dereekb/firebase 13.2.2 → 13.3.0

package/src/lib/common/storage/storage.d.ts

@@ -1,77 +1,134 @@
 import { type SlashPath, type FactoryWithRequiredInput } from '@dereekb/util';
 /**
- * Storage bucket identifier.
+ * Storage bucket identifier for Firebase Cloud Storage.
  *
- * Should contain no slashes, just the bucket's identifier.
+ * Should contain no slashes — just the bucket name (e.g., `"my-app.appspot.com"`).
  */
 export type StorageBucketId = string;
 /**
- * A reference to a StorageBucketId
+ * Contains a reference to a {@link StorageBucketId}.
  */
 export interface StorageBucketIdRef {
     readonly bucketId: StorageBucketId;
 }
 /**
- * A filepath to a file or folder.
+ * Slash-delimited file or folder path within a storage bucket.
+ *
+ * Does not include the bucket identifier — only the path relative to the bucket root.
  */
 export type StorageSlashPath = SlashPath;
 /**
- * A reference to a StorageSlashPath
+ * Contains a reference to a {@link StorageSlashPath}.
  */
 export interface StorageSlashPathRef {
     /**
-     * The full path/name of a file.
+     * The full path/name of a file relative to the bucket root.
      *
-     * For example, if a file is at the path '<bucket>/full/path/image.png', the pathString is 'full/path/image.png'.
+     * For example, if a file is at the path `<bucket>/full/path/image.png`, the pathString is `full/path/image.png`.
      */
     readonly pathString: StorageSlashPath;
 }
 /**
- * A bucket and path pair.
+ * A bucket and path pair that uniquely identifies a file or folder in Firebase Cloud Storage.
  *
  * If the bucket is not defined, it implies the default app bucket.
  */
 export interface StoragePath extends StorageBucketIdRef, StorageSlashPathRef {
 }
 /**
- * Creates a new StoragePath object with the same bucketId and pathString as the input.
+ * Creates a shallow copy of a {@link StoragePath}, preserving bucketId and pathString.
+ *
+ * Useful when you need an independent reference that won't be affected by mutations to the original.
+ *
+ * @param path - the storage path to copy
  *
- * @param path The StoragePath to copy.
- * @returns A new StoragePath object.
+ * @example
+ * ```ts
+ * const copy = copyStoragePath({ bucketId: 'my-bucket', pathString: 'images/photo.png' });
+ * ```
  */
 export declare function copyStoragePath(path: StoragePath): StoragePath;
 /**
- * Storage-Path related input.
+ * Flexible input that can be used to resolve a {@link StoragePath}.
+ *
+ * Accepts a raw slash path string, a {@link StoragePath}, or a {@link StorageSlashPathRef}.
  */
 export type StoragePathInput = StorageSlashPath | StoragePath | StorageSlashPathRef;
 /**
- * Converts the input to a StoragePath
+ * Factory that normalizes a {@link StoragePathInput} into a fully-resolved {@link StoragePath} with a bucket.
  */
 export type StoragePathFactory = FactoryWithRequiredInput<StoragePath, StoragePathInput>;
+/**
+ * Configuration for {@link storagePathFactory}.
+ */
 export interface StoragePathFactoryConfig extends StorageBucketIdRef {
     /**
-     * Whether or not to replace the bucketId on input that has it.
+     * Whether to always override the bucketId on inputs that already have one.
      *
-     * False by default.
+     * When `false` (default), input bucketIds are preserved and the configured bucket is used only as a fallback.
      */
     readonly replaceBucket?: boolean;
 }
 /**
- * Creates a StoragePathFactory.
+ * Creates a {@link StoragePathFactory} that normalizes various path inputs into {@link StoragePath} objects
+ * with a consistent bucket assignment.
  *
- * @param config
- * @returns
+ * @param config - bucket and replacement behavior
+ *
+ * @example
+ * ```ts
+ * const pathFactory = storagePathFactory({ bucketId: 'my-bucket' });
+ * const path = pathFactory('images/photo.png');
+ * // path === { bucketId: 'my-bucket', pathString: 'images/photo.png' }
+ * ```
  */
 export declare function storagePathFactory(config: StoragePathFactoryConfig): StoragePathFactory;
 /**
- * A reference to a StoragePath
+ * Contains a reference to a {@link StoragePath}.
  */
 export interface StoragePathRef {
     readonly storagePath: StoragePath;
 }
+/**
+ * Google Cloud Storage bucket prefix in `gs://` URI format.
+ */
 export type GoogleCloudStorageBucketPrefix<S extends StorageBucketId = StorageBucketId> = `gs://${S}`;
+/**
+ * A file path in the default bucket — equivalent to the raw path string.
+ */
 export type GoogleCloudStorageDefaultBucketFilePath<P extends StorageSlashPath = StorageSlashPath> = P;
+/**
+ * A fully-qualified `gs://bucket/path` URI for a file in a specific bucket.
+ */
 export type GoogleCloudStorageBucketAndFilePath<P extends StorageSlashPath = StorageSlashPath, S extends StorageBucketId = StorageBucketId> = `${GoogleCloudStorageBucketPrefix<S>}/${P}`;
+/**
+ * A Google Cloud Storage file path — either a raw path (default bucket) or a full `gs://` URI.
+ */
 export type GoogleCloudStorageFilePath<P extends StorageSlashPath = StorageSlashPath> = GoogleCloudStorageDefaultBucketFilePath<P> | GoogleCloudStorageBucketAndFilePath<P>;
+/**
+ * Converts a {@link StoragePath} to a {@link GoogleCloudStorageFilePath} string.
+ *
+ * If the path has a bucketId, produces a `gs://bucket/path` URI. Otherwise, returns just the relative path
+ * (implying the default bucket).
+ *
+ * @param path - the storage path to convert
+ *
+ * @example
+ * ```ts
+ * const uri = firebaseStorageFilePathFromStorageFilePath({ bucketId: 'my-bucket', pathString: 'images/photo.png' });
+ * // uri === 'gs://my-bucket/images/photo.png'
+ * ```
+ */
 export declare function firebaseStorageFilePathFromStorageFilePath(path: StoragePath): GoogleCloudStorageFilePath;
+/**
+ * Returns the `gs://` bucket prefix URI for the given bucket identifier or ref.
+ *
+ * @param storage - bucket ID string or a {@link StorageBucketIdRef}
+ *
+ * @example
+ * ```ts
+ * firebaseStorageBucketFolderPath('my-bucket');
+ * // returns 'gs://my-bucket'
+ * ```
+ */
 export declare function firebaseStorageBucketFolderPath(storage: StorageBucketId | StorageBucketIdRef): GoogleCloudStorageBucketPrefix;

package/src/lib/common/storage/types.d.ts

@@ -1,5 +1,10 @@
 import { type ArrayOrValue, type DateOrUnixDateTimeMillisecondsNumber, type FileSize, type Milliseconds, type MimeTypeWithoutParameters, type ISO8601DateString, type Maybe, type ContentDispositionString, type ContentTypeMimeType } from '@dereekb/util';
 import { type Observable } from 'rxjs';
+/**
+ * Minimal shape of the Firebase client-side Storage object.
+ *
+ * Used to avoid depending on the concrete Firebase SDK type — keeps the library SDK-agnostic.
+ */
 export type FirebaseStorageLikeStorage = {
     /**
      * The maximum time to retry uploads in milliseconds.
@@ -11,12 +16,17 @@ export type FirebaseStorageLikeStorage = {
      */
     readonly maxOperationRetryTime: number;
 };
+/**
+ * Minimal shape of the Google Cloud Storage (server-side) object.
+ */
 export type GoogleCloudLikeStorage = {
     readonly baseUrl: string;
     readonly projectId: string;
 };
 /**
- * Cast to the local type's Storage if direct access is needed. In most cases, direct access to this type is unncessary.
+ * Union of client-side and server-side Firebase Storage types.
+ *
+ * Cast to the concrete type if direct SDK access is needed. In most cases, use {@link FirebaseStorageContext} instead.
  */
 export type FirebaseStorage = FirebaseStorageLikeStorage | GoogleCloudLikeStorage;
 /**
@@ -124,22 +134,30 @@ export type StorageDataUrlStringType = 'data_url';
 export type StorageDataString = StorageRawDataString | StorageBase64DataString | StorageBase64UrlDataString | StorageDataUrlString;
 export type StorageDataStringType = StorageRawDataStringType | StorageBase64DataStringType | StorageBase64UrlDataStringType | StorageDataUrlStringType;
 /**
- * Blob and Byte array types that can be uploaded by the client implementation.
+ * Binary types that can be uploaded via the client-side Firebase Storage SDK.
  */
 export type StorageClientUploadBytesInput = File | Blob | Uint8Array;
 /**
- * Known types that can be uploaded by the client implementation.
+ * All types that can be uploaded via the client-side Firebase Storage SDK (binary or string-encoded).
  */
 export type StorageClientUploadInput = StorageClientUploadBytesInput | StorageDataString;
 /**
- * Known types that can be uploaded by the client implementation.
+ * Binary types that can be uploaded via the server-side Google Cloud Storage SDK.
  */
 export type StorageServerUploadBytesInput = Buffer | Uint8Array;
 /**
- * Known types that can be uploaded by the server implementation.
+ * All types that can be uploaded via the server-side Google Cloud Storage SDK (binary or string-encoded).
  */
 export type StorageServerUploadInput = StorageServerUploadBytesInput | StorageDataString;
+/**
+ * Union of all uploadable input types across client and server.
+ */
 export type StorageUploadInput = StorageClientUploadInput | StorageServerUploadInput;
+/**
+ * Represents a resumable upload task with controls for pausing, cancelling, and monitoring progress.
+ *
+ * Primarily used on the client side via `uploadResumable()` on {@link FirebaseStorageAccessorFile}.
+ */
 export interface StorageUploadTask<R = unknown> {
     /**
      * Exposes the internal reference type.

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

@@ -1,4 +1,5 @@
 export * from './user';
 export * from './notification';
+export * from './oidcmodel';
 export * from './storagefile';
 export * from './system';

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

@@ -1,3 +1,11 @@
+/**
+ * @module notification.action
+ *
+ * Generic CRUD action type aliases for each notification document type.
+ * These types parameterize the server-side action factories in `@dereekb/firebase-server/model`.
+ *
+ * Sync variants return the result directly; Async variants return a Promise.
+ */
 import { type AsyncFirebaseFunctionCreateAction, type AsyncFirebaseFunctionDeleteAction, type AsyncFirebaseFunctionUpdateAction, type FirebaseFunctionCreateAction, type FirebaseFunctionDeleteAction, type FirebaseFunctionUpdateAction } from '../../common';
 import { type NotificationSummaryDocument, type NotificationBoxDocument, type NotificationDocument, type NotificationWeekDocument, type NotificationUserDocument } from './notification';
 export type NotificationUserCreateAction<P extends object> = FirebaseFunctionCreateAction<P, NotificationUserDocument>;

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

@@ -1,3 +1,11 @@
+/**
+ * @module notification.api
+ *
+ * API parameter types, Arktype validation schemas, and Firebase function definitions for the notification CRUD operations.
+ *
+ * Each param interface has a corresponding Arktype validator (e.g., {@link updateNotificationUserParamsType}).
+ * The {@link NotificationFunctions} abstract class defines the client-callable function map.
+ */
 import { type Type } from 'arktype';
 import { type TargetModelParams, type FirestoreModelKey, type FirebaseAuthUserId } from '../../common';
 import { type ModelFirebaseCrudFunction, type FirebaseFunctionTypeConfigMap, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap } from '../../client';
@@ -192,6 +200,9 @@ export interface SendNotificationResultOnSendCompleteResult<T = unknown> {
     readonly value?: T;
     readonly error?: Maybe<unknown>;
 }
+/**
+ * Detailed result returned by the `sendNotification` function, describing the outcome of sending a single notification.
+ */
 export interface SendNotificationResult {
     readonly notificationTemplateType: Maybe<NotificationTemplateType>;
     readonly isKnownTemplateType: Maybe<boolean>;
@@ -228,6 +239,9 @@ export interface SendQueuedNotificationsParams {
     readonly sendNotificationLoopsTaskExcessThreshold?: Maybe<number>;
 }
 export declare const sendQueuedNotificationsParamsType: Type<SendQueuedNotificationsParams>;
+/**
+ * Aggregate result of processing the notification send queue, with counts of visited, succeeded, failed, and deleted notifications.
+ */
 export interface SendQueuedNotificationsResult extends Omit<SendNotificationResult, 'throttled' | 'isNotificationTask' | 'isUniqueNotificationTask' | 'notificationTaskCompletionType' | 'uniqueNotificationTaskConflict' | 'isConfiguredTemplateType' | 'isKnownTemplateType' | 'notificationTemplateType' | 'notificationMarkedDone' | 'deletedNotification' | 'createdBox' | 'success' | 'exists' | 'boxExists' | 'notificationBoxNeedsInitialization' | 'tryRun' | 'loadMessageFunctionFailure' | 'buildMessageFailure'> {
     readonly excessLoopsDetected: boolean;
     readonly notificationLoopCount: number;
@@ -252,6 +266,9 @@ export interface CleanupSentNotificationsResult {
     readonly notificationWeeksCreated: number;
     readonly notificationWeeksUpdated: number;
 }
+/**
+ * Custom (non-CRUD) function type map for notifications. Currently empty — all operations use the CRUD pattern.
+ */
 export type NotificationFunctionTypeMap = {};
 export declare const notificationFunctionTypeConfigMap: FirebaseFunctionTypeConfigMap<NotificationFunctionTypeMap>;
 export type NotificationBoxModelCrudFunctionsConfig = {
@@ -280,6 +297,12 @@ export type NotificationBoxModelCrudFunctionsConfig = {
     readonly notificationWeek: null;
 };
 export declare const notificationBoxModelCrudFunctionsConfig: ModelFirebaseCrudFunctionConfigMap<NotificationBoxModelCrudFunctionsConfig, NotificationTypes>;
+/**
+ * Abstract client-callable function map for notification CRUD operations.
+ *
+ * Implementations are generated by {@link notificationFunctionMap} for client-side use,
+ * and by the server-side function registration in the demo-api or application module.
+ */
 export declare abstract class NotificationFunctions implements ModelFirebaseFunctionMap<NotificationFunctionTypeMap, NotificationBoxModelCrudFunctionsConfig> {
     abstract notificationUser: {
         updateNotificationUser: {
@@ -304,4 +327,7 @@ export declare abstract class NotificationFunctions implements ModelFirebaseFunc
         };
     };
 }
+/**
+ * Factory for creating client-side callable function instances from the notification CRUD configuration.
+ */
 export declare const notificationFunctionMap: import("../..").ModelFirebaseFunctionMapFactory<NotificationFunctionTypeMap, NotificationBoxModelCrudFunctionsConfig>;

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

@@ -1,9 +1,24 @@
+/**
+ * @module notification.api.error
+ *
+ * Error code constants thrown by the notification server action service.
+ * These codes are returned in Firebase function error responses for client-side handling.
+ */
+/** Thrown when a notification creation request is missing a required ID. */
 export declare const CREATE_NOTIFICATION_ID_REQUIRED_ERROR_CODE = "CREATE_NOTIFICATION_ID_REQUIRED";
+/** Thrown when attempting to initialize a NotificationBox or NotificationSummary that is already initialized. */
 export declare const NOTIFICATION_MODEL_ALREADY_INITIALIZED_ERROR_CODE = "NOTIFICATION_MODEL_ALREADY_INITIALIZED";
+/** Thrown when the target NotificationBox does not exist. */
 export declare const NOTIFICATION_BOX_DOES_NOT_EXIST_ERROR_CODE = "NOTIFICATION_BOX_DOES_NOT_EXIST";
+/** Thrown when attempting to create a NotificationBox for a model that already has one. */
 export declare const NOTIFICATION_BOX_EXISTS_FOR_MODEL_ERROR_CODE = "NOTIFICATION_BOX_EXISTS_FOR_MODEL";
+/** Thrown when the target recipient does not exist in the NotificationBox. */
 export declare const NOTIFICATION_BOX_RECIPIENT_DOES_NOT_EXIST_ERROR_CODE = "NOTIFICATION_BOX_RECIPIENT_DOES_NOT_EXIST";
+/** Thrown when an exclusion target is invalid (e.g., user not associated with the box). */
 export declare const NOTIFICATION_BOX_EXCLUSION_TARGET_INVALID_ERROR_CODE = "NOTIFICATION_BOX_EXCLUSION_TARGET_INVALID";
+/** Thrown when the UID provided for NotificationUser creation is invalid. */
 export declare const NOTIFICATION_USER_INVALID_UID_FOR_CREATE_ERROR_CODE = "NOTIFICATION_USER_INVALID_UID_FOR_CREATE";
+/** Thrown when attempting to add a user who has blocked themselves from being added as a recipient. */
 export declare const NOTIFICATION_USER_BLOCKED_FROM_BEING_ADD_TO_RECIPIENTS_ERROR_CODE = "NOTIFICATION_USER_BLOCKED_FROM_BEING_ADD_TO_RECIPIENTS";
+/** Thrown when attempting to update a recipient config that is locked by the user. */
 export declare const NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED_ERROR_CODE = "NOTIFICATION_USER_LOCKED_CONFIG_FROM_BEING_UPDATED";

package/src/lib/model/notification/notification.api.util.d.ts

@@ -1,31 +1,46 @@
+/**
+ * @module notification.api.util
+ *
+ * Utility functions for applying {@link UpdateNotificationUserParams} changes to notification config objects.
+ * Used by the server action service when processing user config update requests.
+ */
 import { type Maybe } from '@dereekb/util';
 import { type NotificationBoxRecipientTemplateConfigRecord, type NotificationUserDefaultNotificationBoxRecipientConfig, type NotificationUserNotificationBoxRecipientConfig } from './notification.config';
 import { type NotificationBoxRecipientTemplateConfigArrayEntryParam, type UpdateNotificationUserDefaultNotificationBoxRecipientConfigParams, type UpdateNotificationUserNotificationBoxRecipientParams } from './notification.api';
 import { type AppNotificationTemplateTypeInfoRecordService } from './notification.details';
 import { type NotificationTemplateType } from './notification.id';
 /**
- * Updates a NotificationUserDefaultNotificationBoxRecipientConfig with the input UpdateNotificationUserDefaultNotificationBoxRecipientConfigParams.
+ * Applies an array of config entry params to a {@link NotificationBoxRecipientTemplateConfigRecord},
+ * inserting new entries, merging updates, and removing entries marked with `remove: true`.
  *
- * @param a
- * @param b
- * @returns
+ * @param a - existing config record
+ * @param b - array of update params to apply
+ * @param limitToAllowedConfigTypes - when provided, filters the result to only include these template types
  */
 export declare function updateNotificationBoxRecipientTemplateConfigRecord(a: NotificationBoxRecipientTemplateConfigRecord, b: NotificationBoxRecipientTemplateConfigArrayEntryParam[], limitToAllowedConfigTypes?: Maybe<Iterable<NotificationTemplateType>>): NotificationBoxRecipientTemplateConfigRecord | undefined;
 /**
- * Updates a NotificationUserDefaultNotificationBoxRecipientConfig with the input UpdateNotificationUserDefaultNotificationBoxRecipientConfigParams.
+ * Applies {@link UpdateNotificationUserDefaultNotificationBoxRecipientConfigParams} to an existing
+ * {@link NotificationUserDefaultNotificationBoxRecipientConfig}, producing an updated config.
  *
- * @param a
- * @param b
- * @returns
+ * @param a - existing config
+ * @param b - update params to apply
+ * @param limitToAllowedConfigTypes - when provided, filters config types to only allowed template types
  */
 export declare function updateNotificationUserDefaultNotificationBoxRecipientConfig(a: NotificationUserDefaultNotificationBoxRecipientConfig, b: UpdateNotificationUserDefaultNotificationBoxRecipientConfigParams, limitToAllowedConfigTypes?: Maybe<Iterable<NotificationTemplateType>>): NotificationUserDefaultNotificationBoxRecipientConfig;
+/**
+ * Applies update params to a {@link NotificationUserNotificationBoxRecipientConfig} and returns the updated config
+ * only if it actually changed. Returns `undefined` if no changes were detected.
+ *
+ * Automatically sets `ns = true` (needs sync) when changes are detected and the recipient has been indexed.
+ */
 export declare function updateNotificationUserNotificationBoxRecipientConfigIfChanged(a: NotificationUserNotificationBoxRecipientConfig, b: UpdateNotificationUserNotificationBoxRecipientParams, limitToAllowedConfigTypes?: Maybe<Iterable<NotificationTemplateType>>): NotificationUserNotificationBoxRecipientConfig | undefined;
 /**
- * Updates the target NotificationUserNotificationBoxRecipientConfig array with the input UpdateNotificationUserNotificationBoxRecipientParams.
+ * Batch-applies an array of {@link UpdateNotificationUserNotificationBoxRecipientParams} to the user's
+ * per-box config array. Only updates configs for boxes that already exist in the user's config.
  *
- * If the target NotificationBox does not exist in the config, it is ignored.
+ * Handles deletion of removed configs (when `deleteRemovedConfig` is set) and filters template types
+ * through the optional {@link AppNotificationTemplateTypeInfoRecordService}.
  *
- * @param a
- * @param b
+ * Returns `undefined` if no changes were made.
  */
 export declare function updateNotificationUserNotificationBoxRecipientConfigs(a: NotificationUserNotificationBoxRecipientConfig[], b: UpdateNotificationUserNotificationBoxRecipientParams[], filterWithService?: AppNotificationTemplateTypeInfoRecordService): NotificationUserNotificationBoxRecipientConfig[] | undefined;