@dereekb/firebase-server 13.4.1 → 13.5.0

package/model/index.cjs.js

@@ -193,6 +193,7 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * and dispatches them through the Mailgun API.
  *
  * @param config - service configuration including the Mailgun service, template builders, and batch size
+ * @returns a {@link NotificationEmailSendService} that batches and sends emails through Mailgun
  *
  * @example
  * ```ts
@@ -325,6 +326,8 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * Creates an error indicating that a required notification ID was missing during creation.
  *
  * Thrown when attempting to create a {@link Notification} document without providing the mandatory ID field.
+ *
+ * @returns a precondition conflict error with the notification ID required error code
  */ function createNotificationIdRequiredError() {
     return firebaseServer.preconditionConflictError({
         message: "The required id was not present when attempting to create a Notification.",
@@ -336,6 +339,8 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  *
  * Thrown during initialization when `throwErrorIfAlreadyInitialized` is true and the model's
  * setup flag (`s`) indicates it was previously initialized.
+ *
+ * @returns a precondition conflict error with the already-initialized error code
  */ function notificationModelAlreadyInitializedError() {
     return firebaseServer.preconditionConflictError({
         message: "This model has already been initialized.",
@@ -348,6 +353,7 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * Thrown when the model key's collection name does not match any registered notification model type.
  *
  * @param key - the Firestore model key that has no registered notification model type
+ * @returns a precondition conflict error with the unregistered model type error code
  */ function notificationBoxUnregistredModelTypeInitializationError(key) {
     return firebaseServer.preconditionConflictError({
         message: "This NotificationBox is associated with an unregistered model type.",
@@ -361,6 +367,8 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * Creates an error indicating that no {@link NotificationBox} exists for the target model.
  *
  * Thrown when an operation requires a NotificationBox but none has been created for the given model key.
+ *
+ * @returns a precondition conflict error with the box-not-found error code
  */ function notificationBoxDoesNotExist() {
     return firebaseServer.preconditionConflictError({
         message: "A NotificationBox does not exist for this model.",
@@ -372,6 +380,8 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  *
  * Thrown when the target recipient on the {@link NotificationBox} does not exist on the box
  * or does not have a UID, making it ineligible for exclusion.
+ *
+ * @returns a precondition conflict error with the invalid exclusion target error code
  */ function notificationBoxExclusionTargetInvalidError() {
     return firebaseServer.preconditionConflictError({
         message: "The target for exclusion is invalid. The target recipient on the NotificationBox must be exist on the NotificationBox and have a uid to be excluded.",
@@ -382,6 +392,8 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * Creates an error indicating that a {@link NotificationBox} already exists for this model.
  *
  * Thrown when attempting to create a duplicate NotificationBox for a model that already has one.
+ *
+ * @returns a precondition conflict error with the box-exists error code
  */ function notificationBoxExistsForModelError() {
     return firebaseServer.preconditionConflictError({
         message: "A NotificationBox already exists for this model.",
@@ -393,6 +405,8 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  *
  * Thrown when attempting to update a recipient that is not registered on the box
  * and `insert=true` was not passed to allow creating a new recipient entry.
+ *
+ * @returns a precondition conflict error with the recipient-not-found error code
  */ function notificationBoxRecipientDoesNotExistsError() {
     return firebaseServer.preconditionConflictError({
         message: "An existing NotificationBox recipient for the target does not exist. You must pass insert=true to create a new recipient.",
@@ -405,6 +419,7 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * Thrown during {@link NotificationUser} creation when the provided UID cannot be found in Firebase Auth.
  *
  * @param uid - the Firebase Auth user ID that was not found
+ * @returns a precondition conflict error with the invalid-uid error code
  */ function notificationUserInvalidUidForCreateError(uid) {
     return firebaseServer.preconditionConflictError({
         message: "The user with the uid '".concat(uid, "' does not exist. Cannot create a NotificationUser for them."),
@@ -421,6 +436,7 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * and an operation attempts to insert them into a {@link NotificationBox}'s recipient list.
  *
  * @param uid - the Firebase Auth user ID of the blocked user
+ * @returns a precondition conflict error with the blocked-from-add error code
  */ function notificationUserBlockedFromBeingAddedToRecipientsError(uid) {
     return firebaseServer.preconditionConflictError({
         message: "The user with the uid '".concat(uid, "' has blocked themselves from from being added recipients."),
@@ -437,6 +453,7 @@ var MAILGUN_NOTIFICATION_EMAIL_SEND_SERVICE_DEFAULT_MAX_BATCH_SIZE_PER_REQUEST =
  * and an operation attempts to modify their recipient settings on a {@link NotificationBox}.
  *
  * @param uid - the Firebase Auth user ID of the locked user
+ * @returns a precondition conflict error with the locked-config error code
  */ function notificationUserLockedConfigFromBeingUpdatedError(uid) {
     return firebaseServer.preconditionConflictError({
         message: "The user with the uid '".concat(uid, "' has locked their config from being updated."),
@@ -452,7 +469,7 @@ function _array_like_to_array$7(arr, len) {
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$5(arr) {
+function _array_without_holes$6(arr) {
     if (Array.isArray(arr)) return _array_like_to_array$7(arr);
 }
 function asyncGeneratorStep$e(gen, resolve, reject, _next, _throw, key, arg) {
@@ -497,10 +514,10 @@ function _define_property$d(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$5(iter) {
+function _iterable_to_array$6(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread$5() {
+function _non_iterable_spread$6() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _object_spread$c(target) {
@@ -537,8 +554,8 @@ function _object_spread_props$b(target, source) {
     }
     return target;
 }
-function _to_consumable_array$5(arr) {
-    return _array_without_holes$5(arr) || _iterable_to_array$5(arr) || _unsupported_iterable_to_array$7(arr) || _non_iterable_spread$5();
+function _to_consumable_array$6(arr) {
+    return _array_without_holes$6(arr) || _iterable_to_array$6(arr) || _unsupported_iterable_to_array$7(arr) || _non_iterable_spread$6();
 }
 function _unsupported_iterable_to_array$7(o, minLen) {
     if (!o) return;
@@ -655,6 +672,7 @@ function _ts_generator$e(thisArg, body) {
  * and initializes with an empty notifications array.
  *
  * @param model - the model key to associate the summary with
+ * @returns a blank {@link NotificationSummary} with creation timestamp and empty notifications
  *
  * @example
  * ```ts
@@ -677,8 +695,8 @@ function _ts_generator$e(thisArg, body) {
  *
  * Recipients are each configurable and may be defined with as little info as a single contact info, or have multiple contact info pieces associated with them.
  *
- * @param input
- * @returns
+ * @param input - the notification, box, auth service, and recipient configuration
+ * @returns channel-specific recipient lists (email, text, notification summary) ready for delivery
  */ function expandNotificationRecipients(input) {
     return _async_to_generator$e(function() {
         var _ref, notificationUserAccessor, authService, notification, notificationBox, inputGlobalRecipients, recipientFlagOverride, inputNotificationSummaryIdForUid, inputOnlySendToExplicitlyEnabledRecipients, inputOnlyTextExplicitlyEnabledRecipients, notificationBoxId, notificationSummaryIdForUid, notificationTemplateType, recipientFlag, onlyTextExplicitlyEnabledRecipients, onlySendToExplicitlyEnabledRecipients, onlyEmailExplicitlyEnabledRecipients, onlySendNotificationSummaryExplicitlyEnabledRecipients, _allowedNotificationRecipients, canSendToGlobalRecipients, canSendToBoxRecipients, canSendToExplicitRecipients, initialExplicitRecipients, initialGlobalRecipients, explicitRecipients, globalRecipients, explicitAndGlobalRecipients, allBoxRecipientConfigs, recipientUids, relevantBoxRecipientConfigs, nonNotificationBoxUidRecipientConfigs, otherNotificationUserUidOptOuts, otherNotificationUserUidSendExclusions, notificationUserRecipientConfigs, nonNotificationBoxRecipientUids, notificationUserDocuments, notificationUsers, otherRecipientConfigs, explicitOtherRecipientEmailAddresses, explicitOtherRecipientTextNumbers, explicitOtherRecipientNotificationSummaryIds, allUserDetails, userDetailsMap, _internal, emails, emailUidsSet, texts, textUidsSet, notificationSummaries, notificationSummaryKeysSet, notificationSummaryUidsSet, result;
@@ -704,6 +722,7 @@ function _ts_generator$e(thisArg, body) {
                     onlyTextExplicitlyEnabledRecipients = inputOnlyTextExplicitlyEnabledRecipients !== false; // defaults to true
                     onlySendToExplicitlyEnabledRecipients = inputOnlySendToExplicitlyEnabledRecipients === true; // defaults to false
                     onlyEmailExplicitlyEnabledRecipients = onlySendToExplicitlyEnabledRecipients;
+                    // const onlySendPushNotificationExplicitlyEnabledRecipients = onlySendToExplicitlyEnabledRecipients;
                     onlySendNotificationSummaryExplicitlyEnabledRecipients = onlySendToExplicitlyEnabledRecipients;
                     _allowedNotificationRecipients = firebase.allowedNotificationRecipients(recipientFlag), canSendToGlobalRecipients = _allowedNotificationRecipients.canSendToGlobalRecipients, canSendToBoxRecipients = _allowedNotificationRecipients.canSendToBoxRecipients, canSendToExplicitRecipients = _allowedNotificationRecipients.canSendToExplicitRecipients;
                     initialExplicitRecipients = canSendToExplicitRecipients ? notification.r : [];
@@ -714,7 +733,7 @@ function _ts_generator$e(thisArg, body) {
                     globalRecipients = initialGlobalRecipients.map(function(x) {
                         return _object_spread$c({}, x, firebase.effectiveNotificationBoxRecipientTemplateConfig(x));
                     });
-                    explicitAndGlobalRecipients = _to_consumable_array$5(explicitRecipients).concat(_to_consumable_array$5(globalRecipients));
+                    explicitAndGlobalRecipients = _to_consumable_array$6(explicitRecipients).concat(_to_consumable_array$6(globalRecipients));
                     allBoxRecipientConfigs = canSendToBoxRecipients && notificationBox ? notificationBox.r : [];
                     recipientUids = new Set();
                     relevantBoxRecipientConfigs = [];
@@ -751,7 +770,7 @@ function _ts_generator$e(thisArg, body) {
                         3,
                         2
                     ];
-                    nonNotificationBoxRecipientUids = Array.from(nonNotificationBoxUidRecipientConfigs.keys());
+                    nonNotificationBoxRecipientUids = _to_consumable_array$6(nonNotificationBoxUidRecipientConfigs.keys());
                     notificationUserDocuments = firebase.loadDocumentsForIds(notificationUserAccessor, nonNotificationBoxRecipientUids);
                     return [
                         4,
@@ -815,7 +834,7 @@ function _ts_generator$e(thisArg, body) {
                     });
                     return [
                         4,
-                        Promise.all(Array.from(recipientUids).map(function(uid) {
+                        Promise.all(_to_consumable_array$6(recipientUids).map(function(uid) {
                             return authService.userContext(uid).loadDetails().then(function(details) {
                                 return [
                                     uid,
@@ -1027,17 +1046,15 @@ function _ts_generator$e(thisArg, body) {
                                 } else if (x.s) {
                                     notificationSummaryId = x.s;
                                 }
-                                if (notificationSummaryId) {
-                                    if (!notificationSummaryKeysSet.has(notificationSummaryId)) {
-                                        var name = displayName || x.n;
-                                        var notificationSummary = {
-                                            notificationSummaryId: notificationSummaryId,
-                                            otherRecipient: x,
-                                            name: name
-                                        };
-                                        notificationSummaries.push(notificationSummary);
-                                        explicitOtherRecipientNotificationSummaryIds.delete(notificationSummaryId);
-                                    }
+                                if (notificationSummaryId && !notificationSummaryKeysSet.has(notificationSummaryId)) {
+                                    var name = displayName || x.n;
+                                    var notificationSummary = {
+                                        notificationSummaryId: notificationSummaryId,
+                                        otherRecipient: x,
+                                        name: name
+                                    };
+                                    notificationSummaries.push(notificationSummary);
+                                    explicitOtherRecipientNotificationSummaryIds.delete(notificationSummaryId);
                                 }
                             }
                         }
@@ -1082,6 +1099,7 @@ function _ts_generator$e(thisArg, body) {
  * Also re-applies send exclusions to the updated config array.
  *
  * @param input - the current state and intended change
+ * @returns the updated box config array and notification box recipient, if changes occurred
  * @throws notificationUserBlockedFromBeingAddedToRecipientsError when inserting a blocked user
  * @throws notificationUserLockedConfigFromBeingUpdatedError when updating a locked user's config
  */ function updateNotificationUserNotificationBoxRecipientConfig(input) {
@@ -1101,7 +1119,7 @@ function _ts_generator$e(thisArg, body) {
         // flag as removed in the NotificationUser details if not already flagged as such
         if (currentNotificationUserBoxIndexExists && currentNotificationUserBoxConfig.rm !== true) {
             var _currentNotificationUserBoxConfig_c;
-            updatedBc = _to_consumable_array$5(notificationUser.bc);
+            updatedBc = _to_consumable_array$6(notificationUser.bc);
             updatedBc[currentNotificationUserBoxIndex] = _object_spread_props$b(_object_spread$c({}, currentNotificationUserBoxConfig), {
                 nb: notificationBoxId,
                 c: (_currentNotificationUserBoxConfig_c = currentNotificationUserBoxConfig.c) !== null && _currentNotificationUserBoxConfig_c !== void 0 ? _currentNotificationUserBoxConfig_c : {},
@@ -1147,7 +1165,7 @@ function _ts_generator$e(thisArg, body) {
             nb: notificationBoxId,
             rm: false // remove/clear the removed flag
         }), updateWithNotificationBoxRecipient);
-        updatedBc = _to_consumable_array$5(notificationUser.bc);
+        updatedBc = _to_consumable_array$6(notificationUser.bc);
         if (currentNotificationUserBoxIndexExists) {
             updatedBc[currentNotificationUserBoxIndex] = updatedNotificationUserBoxEntry;
         } else {
@@ -1179,6 +1197,7 @@ function _ts_generator$e(thisArg, body) {
  *
  * @param inputCompletions - the current list of completed checkpoint strings
  * @param handleTaskResult - the handler result containing removal instructions
+ * @returns the filtered completions array with specified checkpoints removed
  *
  * @example
  * ```ts
@@ -1212,7 +1231,7 @@ function _array_like_to_array$6(arr, len) {
 function _array_with_holes$2(arr) {
     if (Array.isArray(arr)) return arr;
 }
-function _array_without_holes$4(arr) {
+function _array_without_holes$5(arr) {
     if (Array.isArray(arr)) return _array_like_to_array$6(arr);
 }
 function asyncGeneratorStep$d(gen, resolve, reject, _next, _throw, key, arg) {
@@ -1262,7 +1281,7 @@ function _define_property$c(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$4(iter) {
+function _iterable_to_array$5(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
 function _iterable_to_array_limit$2(arr, i) {
@@ -1292,7 +1311,7 @@ function _iterable_to_array_limit$2(arr, i) {
 function _non_iterable_rest$2() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _non_iterable_spread$4() {
+function _non_iterable_spread$5() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _object_spread$b(target) {
@@ -1332,8 +1351,8 @@ function _object_spread_props$a(target, source) {
 function _sliced_to_array$2(arr, i) {
     return _array_with_holes$2(arr) || _iterable_to_array_limit$2(arr, i) || _unsupported_iterable_to_array$6(arr, i) || _non_iterable_rest$2();
 }
-function _to_consumable_array$4(arr) {
-    return _array_without_holes$4(arr) || _iterable_to_array$4(arr) || _unsupported_iterable_to_array$6(arr) || _non_iterable_spread$4();
+function _to_consumable_array$5(arr) {
+    return _array_without_holes$5(arr) || _iterable_to_array$5(arr) || _unsupported_iterable_to_array$6(arr) || _non_iterable_spread$5();
 }
 function _unsupported_iterable_to_array$6(o, minLen) {
     if (!o) return;
@@ -1474,6 +1493,7 @@ function _ts_generator$d(thisArg, body) {
  * to its factory function using the provided context.
  *
  * @param context - the fully assembled notification server actions context
+ * @returns a fully wired {@link NotificationServerActions} instance
  *
  * @example
  * ```ts
@@ -1503,6 +1523,9 @@ function _ts_generator$d(thisArg, body) {
  *
  * Validates the UID exists in Firebase Auth, then creates a new {@link NotificationUser} document
  * with empty default and global configs. Throws if the UID is not found in Auth.
+ *
+ * @param context - the notification server actions context with auth and collection access
+ * @returns a transform-and-validate function that creates a new notification user document
  */ function createNotificationUserFactory(context) {
     var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationUserCollection = context.notificationUserCollection, authService = context.authService;
     return firebaseServerActionTransformFunctionFactory(firebase.createNotificationUserParamsType, function(params) {
@@ -1567,6 +1590,9 @@ function _ts_generator$d(thisArg, body) {
  * Updates a {@link NotificationUser}'s default config (`dc`), global config (`gc`), and/or
  * box configs (`bc`). When the global config changes, iterates all box configs to propagate
  * effective recipient changes and marks affected entries for sync.
+ *
+ * @param context - the notification server actions context with Firestore and collection access
+ * @returns a transform-and-validate function that updates an existing notification user document
  */ function updateNotificationUserFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationUserCollection = context.notificationUserCollection, appNotificationTemplateTypeInfoRecordService = context.appNotificationTemplateTypeInfoRecordService;
     return firebaseServerActionTransformFunctionFactory(firebase.updateNotificationUserParamsType, function(params) {
@@ -1686,6 +1712,9 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
  * entries flagged with `ns=true` (needs-sync), loading the corresponding {@link NotificationBox},
  * and merging the user's preferences back into the box's recipient list. Handles removed entries
  * and cleans up stale box references.
+ *
+ * @param context - the notification server actions context with Firestore and collection access
+ * @returns a transform-and-validate function that resyncs a notification user's box configurations
  */ function resyncNotificationUserFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationBoxCollection = context.notificationBoxCollection, notificationUserCollection = context.notificationUserCollection, appNotificationTemplateTypeInfoRecordService = context.appNotificationTemplateTypeInfoRecordService;
     return firebaseServerActionTransformFunctionFactory(firebase.resyncNotificationUserParamsType, function() {
@@ -1739,7 +1768,7 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
                                                                 notificationBoxConfigsToSyncInThisBatchMap = util.makeModelMap(notificationBoxConfigsToSyncInThisBatch, function(x) {
                                                                     return x.nb;
                                                                 });
-                                                                notificationBoxIdsToSyncInThisBatch = Array.from(notificationBoxConfigsToSyncInThisBatchMap.keys());
+                                                                notificationBoxIdsToSyncInThisBatch = _to_consumable_array$5(notificationBoxConfigsToSyncInThisBatchMap.keys());
                                                                 notificationBoxDocuments = firebase.loadDocumentsForIds(notificationBoxCollection.documentAccessorForTransaction(transaction), notificationBoxIdsToSyncInThisBatch);
                                                                 return [
                                                                     4,
@@ -1797,7 +1826,7 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
                                                                                             recipientHasChange = !util.areEqualPOJOValues(nextRecipient, recipient);
                                                                                             // only update recipients if the next/new recipient is not equal to the existing one
                                                                                             if (recipientHasChange) {
-                                                                                                r = _to_consumable_array$4(notificationBox.r);
+                                                                                                r = _to_consumable_array$5(notificationBox.r);
                                                                                                 r[recipientIndex] = nextRecipient;
                                                                                                 nextRecipientsMap.set(nb, nextRecipient);
                                                                                             } else {
@@ -1847,13 +1876,12 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
                                                                                 i: util.UNSET_INDEX_NUMBER
                                                                             });
                                                                         } else {
-                                                                            var _updatedRecipient_i;
                                                                             // else, use the updated recipient and keep/copy the
                                                                             var updatedRecipient = nextRecipientsMap.get(nb);
                                                                             nextConfig = _object_spread_props$a(_object_spread$b({}, existingConfig), {
                                                                                 nb: nb,
                                                                                 rm: false,
-                                                                                i: (_updatedRecipient_i = updatedRecipient.i) !== null && _updatedRecipient_i !== void 0 ? _updatedRecipient_i : util.UNSET_INDEX_NUMBER
+                                                                                i: updatedRecipient.i
                                                                             });
                                                                         }
                                                                     }
@@ -1921,6 +1949,9 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
  * Batch-processes all {@link NotificationUser} documents flagged for sync by querying
  * for entries with `ns=true`, then calling the resync logic for each in parallel
  * (up to 5 concurrent tasks). Loops until no more flagged users are found.
+ *
+ * @param context - the notification server actions context with collection access
+ * @returns an async function that resyncs all flagged notification users and returns aggregate results
  */ function resyncAllNotificationUsersFactory(context) {
     var notificationUserCollection = context.notificationUserCollection;
     var resyncNotificationUser = resyncNotificationUserFactory(context);
@@ -2006,6 +2037,9 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
  *
  * Creates a new {@link NotificationSummary} document for a model, generating the summary ID
  * from the model key and initializing it with a blank template.
+ *
+ * @param context - the notification server actions context with collection access
+ * @returns a transform-and-validate function that creates a new notification summary document
  */ function createNotificationSummaryFactory(context) {
     var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationSummaryCollection = context.notificationSummaryCollection;
     return firebaseServerActionTransformFunctionFactory(firebase.createNotificationSummaryParamsType, function(params) {
@@ -2048,6 +2082,9 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
  *
  * Updates an existing {@link NotificationSummary} document's owner or setup flag.
  * Runs within a Firestore transaction to ensure consistency.
+ *
+ * @param context - the notification server actions context
+ * @returns a transform-and-validate function that updates an existing notification summary document
  */ function updateNotificationSummaryFactory(context) {
     var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.updateNotificationSummaryParamsType, function(params) {
@@ -2102,6 +2139,9 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
  *
  * Checks for existing boxes and throws if one already exists for the model.
  * Also syncs initial recipients with their corresponding {@link NotificationUser} documents.
+ *
+ * @param context - the base notification server actions context with collection access
+ * @returns an async function that creates a notification box within a transaction and returns the document and template
  */ function createNotificationBoxInTransactionFactory(context) {
     var notificationBoxCollection = context.notificationBoxCollection;
     return function(params, transaction) {
@@ -2150,6 +2190,9 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
  *
  * Wraps {@link createNotificationBoxInTransactionFactory} in a Firestore transaction
  * and follows the transform-and-validate pattern.
+ *
+ * @param context - the notification server actions context with Firestore and collection access
+ * @returns a transform-and-validate function that creates a new notification box document
  */ function createNotificationBoxFactory(context) {
     var firestoreContext = context.firestoreContext, notificationBoxCollection = context.notificationBoxCollection, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var createNotificationBoxInTransaction = createNotificationBoxInTransactionFactory(context);
@@ -2206,8 +2249,16 @@ var MAX_NOTIFICATION_BOXES_TO_UPDATE_PER_BATCH = 50;
         })();
     });
 }
-function updateNotificationBoxFactory(param) {
-    var firebaseServerActionTransformFunctionFactory = param.firebaseServerActionTransformFunctionFactory;
+/**
+ * Factory for the `updateNotificationBox` action.
+ *
+ * Currently a no-op placeholder that returns the document unchanged.
+ * Reserved for future box-level update logic.
+ *
+ * @param context - the notification server actions context (destructured for the transform factory)
+ * @returns a transform-and-validate function that returns the notification box document unchanged
+ */ function updateNotificationBoxFactory(context) {
+    var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.updateNotificationBoxParamsType, function() {
         return _async_to_generator$d(function() {
             return _ts_generator$d(this, function(_state) {
@@ -2234,6 +2285,9 @@ function updateNotificationBoxFactory(param) {
  *
  * Manages the exclusion list (`x`) on both the box recipient and the corresponding
  * {@link NotificationUser}'s send exclusion array, keeping them in sync.
+ *
+ * @param context - the base notification server actions context with collection access
+ * @returns an async function that updates recipient exclusions within a transaction
  */ function updateNotificationBoxRecipientExclusionInTransactionFactory(context) {
     var notificationBoxCollection = context.notificationBoxCollection, notificationUserCollection = context.notificationUserCollection;
     return function(input, transaction) {
@@ -2269,7 +2323,7 @@ function updateNotificationBoxFactory(param) {
                         targetRecipient = notificationBox.r.find(function(x) {
                             return x.i === i;
                         });
-                        if (!targetRecipient || !targetRecipient.uid) {
+                        if (!(targetRecipient === null || targetRecipient === void 0 ? void 0 : targetRecipient.uid)) {
                             throw notificationBoxExclusionTargetInvalidError();
                         } else {
                             targetUid = targetRecipient.uid;
@@ -2279,21 +2333,16 @@ function updateNotificationBoxFactory(param) {
                         if (!targetUid) {
                             throw notificationBoxExclusionTargetInvalidError();
                         }
-                        return [
-                            4,
-                            notificationUserCollection.documentAccessorForTransaction(transaction).loadDocumentForId(targetUid)
-                        ];
-                    case 4:
-                        notificationUserDocument = _state.sent();
+                        notificationUserDocument = notificationUserCollection.documentAccessorForTransaction(transaction).loadDocumentForId(targetUid);
                         return [
                             4,
                             notificationUserDocument.snapshotData()
                         ];
-                    case 5:
+                    case 4:
                         notificationUser = _state.sent();
                         if (!notificationUser) return [
                             3,
-                            7
+                            6
                         ];
                         // only update if the user exists
                         targetExclusions = [
@@ -2308,13 +2357,13 @@ function updateNotificationBoxFactory(param) {
                             4,
                             notificationUserDocument.update(notificationUserUpdate)
                         ];
-                    case 6:
+                    case 5:
                         _state.sent();
                         result = {
                             notificationUserUpdate: notificationUserUpdate
                         };
-                        _state.label = 7;
-                    case 7:
+                        _state.label = 6;
+                    case 6:
                         return [
                             2,
                             result
@@ -2330,6 +2379,9 @@ function updateNotificationBoxFactory(param) {
  * Handles inserting new recipients, updating existing ones, and removing recipients.
  * Syncs changes with the recipient's {@link NotificationUser} document and manages
  * recipient index assignment via a sorted-values free-index calculator.
+ *
+ * @param context - the base notification server actions context with auth and collection access
+ * @returns an async function that updates a recipient on a notification box within a transaction
  */ function updateNotificationBoxRecipientInTransactionFactory(context) {
     var authService = context.authService, notificationBoxCollection = context.notificationBoxCollection, notificationUserCollection = context.notificationUserCollection;
     var createNotificationBoxInTransaction = createNotificationBoxInTransactionFactory(context);
@@ -2387,14 +2439,14 @@ function updateNotificationBoxFactory(param) {
                     case 4:
                         if (!notificationBox) return [
                             3,
-                            18
+                            17
                         ];
                         notificationBox.m;
                         targetRecipientIndex = notificationBox.r.findIndex(findRecipientFn);
                         targetRecipient = notificationBox.r[targetRecipientIndex];
                         if (remove) {
-                            if (targetRecipientIndex != null) {
-                                r = _to_consumable_array$4(notificationBox.r); // remove if they exist.
+                            if (targetRecipientIndex !== -1) {
+                                r = _to_consumable_array$5(notificationBox.r); // remove if they exist.
                                 delete r[targetRecipientIndex];
                             }
                         } else {
@@ -2407,7 +2459,7 @@ function updateNotificationBoxFactory(param) {
                                 i: (_ref1 = targetRecipient === null || targetRecipient === void 0 ? void 0 : targetRecipient.i) !== null && _ref1 !== void 0 ? _ref1 : util.UNSET_INDEX_NUMBER,
                                 c: c
                             }, firebase.updateNotificationRecipient(targetRecipient !== null && targetRecipient !== void 0 ? targetRecipient : {}, params));
-                            r = _to_consumable_array$4(notificationBox.r);
+                            r = _to_consumable_array$5(notificationBox.r);
                             if (targetRecipient) {
                                 nextRecipient.i = targetRecipient.i;
                                 nextRecipient = firebase.mergeNotificationBoxRecipients(targetRecipient, nextRecipient);
@@ -2422,30 +2474,25 @@ function updateNotificationBoxFactory(param) {
                         }
                         if (!(r != null)) return [
                             3,
-                            18
+                            17
                         ];
                         notificationUserId = (_ref2 = targetRecipient === null || targetRecipient === void 0 ? void 0 : targetRecipient.uid) !== null && _ref2 !== void 0 ? _ref2 : nextRecipient === null || nextRecipient === void 0 ? void 0 : nextRecipient.uid;
                         if (!(notificationUserId != null)) return [
                             3,
-                            13
+                            12
                         ];
                         notificationBoxId = notificationBoxDocument.id;
-                        return [
-                            4,
-                            notificationUserCollection.documentAccessorForTransaction(transaction).loadDocumentForId(notificationUserId)
-                        ];
-                    case 5:
-                        notificationUserDocument = _state.sent();
+                        notificationUserDocument = notificationUserCollection.documentAccessorForTransaction(transaction).loadDocumentForId(notificationUserId);
                         return [
                             4,
                             notificationUserDocument.snapshotData()
                         ];
-                    case 6:
+                    case 5:
                         notificationUser = _state.sent();
                         createNotificationUser = !notificationUser && !remove && insert;
                         if (!createNotificationUser) return [
                             3,
-                            8
+                            7
                         ];
                         // assert they exist in the auth system
                         userContext = authService.userContext(notificationUserId);
@@ -2453,7 +2500,7 @@ function updateNotificationBoxFactory(param) {
                             4,
                             userContext.exists()
                         ];
-                    case 7:
+                    case 6:
                         userExistsInAuth = _state.sent();
                         if (!userExistsInAuth) {
                             throw notificationUserInvalidUidForCreateError(notificationUserId);
@@ -2472,11 +2519,11 @@ function updateNotificationBoxFactory(param) {
                             }
                         };
                         notificationUser = notificationUserTemplate;
-                        _state.label = 8;
-                    case 8:
+                        _state.label = 7;
+                    case 7:
                         if (!(notificationUser != null)) return [
                             3,
-                            13
+                            12
                         ];
                         _updateNotificationUserNotificationBoxRecipientConfig = updateNotificationUserNotificationBoxRecipientConfig({
                             notificationBoxId: notificationBoxId,
@@ -2491,7 +2538,7 @@ function updateNotificationBoxFactory(param) {
                         }) : undefined;
                         if (!createNotificationUser) return [
                             3,
-                            10
+                            9
                         ];
                         newUserTemplate = _object_spread_props$a(_object_spread$b({}, notificationUser), {
                             bc: updatedBc !== null && updatedBc !== void 0 ? updatedBc : [],
@@ -2501,16 +2548,16 @@ function updateNotificationBoxFactory(param) {
                             4,
                             notificationUserDocument.create(newUserTemplate)
                         ];
-                    case 9:
+                    case 8:
                         _state.sent();
                         return [
                             3,
-                            12
+                            11
                         ];
-                    case 10:
+                    case 9:
                         if (!(updatedBc != null)) return [
                             3,
-                            12
+                            11
                         ];
                         return [
                             4,
@@ -2519,53 +2566,53 @@ function updateNotificationBoxFactory(param) {
                                 b: updatedB
                             })
                         ];
-                    case 11:
+                    case 10:
                         _state.sent();
-                        _state.label = 12;
-                    case 12:
+                        _state.label = 11;
+                    case 11:
                         // Set if nextRecipient is updated/influence from existing configuration
-                        if (targetRecipientIndex != null && updatedNotificationBoxRecipient && !remove) {
+                        if (targetRecipientIndex !== -1 && updatedNotificationBoxRecipient && !remove) {
                             r[targetRecipientIndex] = updatedNotificationBoxRecipient; // set the updated value in r
                         }
-                        _state.label = 13;
-                    case 13:
+                        _state.label = 12;
+                    case 12:
                         updatedNotificationBox = _object_spread_props$a(_object_spread$b({}, notificationBox), {
                             r: r
                         });
                         notificationBoxWasCreated = false;
                         if (!createNotificationBox) return [
                             3,
-                            15
+                            14
                         ];
                         return [
                             4,
                             notificationBoxDocument.create(updatedNotificationBox)
                         ];
-                    case 14:
+                    case 13:
                         _state.sent();
                         notificationBoxWasCreated = true;
                         return [
                             3,
-                            17
+                            16
                         ];
-                    case 15:
+                    case 14:
                         return [
                             4,
                             notificationBoxDocument.update({
                                 r: r
                             })
                         ];
-                    case 16:
+                    case 15:
                         _state.sent();
-                        _state.label = 17;
-                    case 17:
+                        _state.label = 16;
+                    case 16:
                         result = {
                             updatedNotificationBox: updatedNotificationBox,
                             notificationBoxWasCreated: notificationBoxWasCreated,
                             notificationBoxDocument: notificationBoxDocument
                         };
-                        _state.label = 18;
-                    case 18:
+                        _state.label = 17;
+                    case 17:
                         return [
                             2,
                             result
@@ -2580,6 +2627,9 @@ function updateNotificationBoxFactory(param) {
  *
  * Wraps the in-transaction recipient update logic, handling both recipient changes
  * and send exclusion updates in a single Firestore transaction.
+ *
+ * @param context - the notification server actions context with Firestore and collection access
+ * @returns a transform-and-validate function that updates a recipient on a notification box
  */ function updateNotificationBoxRecipientFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var updateNotificationBoxRecipientInTransaction = updateNotificationBoxRecipientInTransactionFactory(context);
@@ -2681,6 +2731,9 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
  *
  * Supports throttling via `sendAt` time, configurable send flags, and task-based
  * async workflows for notifications that require multi-step processing.
+ *
+ * @param context - the notification server actions context with template, send, and task services
+ * @returns a transform-and-validate function that processes and sends a notification document
  */ function sendNotificationFactory(context) {
     var appNotificationTemplateTypeInfoRecordService = context.appNotificationTemplateTypeInfoRecordService, notificationSendService = context.notificationSendService, notificationTaskService = context.notificationTaskService, notificationTemplateService = context.notificationTemplateService, authService = context.authService, notificationBoxCollection = context.notificationBoxCollection, notificationCollectionGroup = context.notificationCollectionGroup, notificationUserCollection = context.notificationUserCollection, firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var createNotificationBoxInTransaction = createNotificationBoxInTransactionFactory(context);
@@ -2761,7 +2814,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                             notificationTemplate.at = 0; // reset checkpoint attempt/delay count
                                                         }
                                                         // add the checkpoint to the notification
-                                                        notificationTemplate.tpr = _to_consumable_array$4(removeFromCompletionsArrayWithTaskResult(notification.tpr, handleTaskResult)).concat(_to_consumable_array$4(util.asArray(completion)));
+                                                        notificationTemplate.tpr = _to_consumable_array$5(removeFromCompletionsArrayWithTaskResult(notification.tpr, handleTaskResult)).concat(_to_consumable_array$5(util.asArray(completion)));
                                                         // calculate the updated notification item
                                                         notificationTemplate.n = _object_spread_props$a(_object_spread$b({}, notification.n), {
                                                             d: _object_spread$b({}, notification.n.d, updateMetadata ? util.filterOnlyUndefinedValues(updateMetadata) : undefined // ignore any undefined values
@@ -2771,7 +2824,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                         // if the tpr has not changed, then it is also considered a reversal
                                                         if (tryRunNextPart) {
                                                             tprChanged = !util.iterablesAreSetEquivalent(notification.tpr, notificationTemplate.tpr);
-                                                            partTprReversal = !tprChanged || tprChanged && notificationTemplate.tpr.length <= notification.tpr.length;
+                                                            partTprReversal = !tprChanged || notificationTemplate.tpr.length <= notification.tpr.length;
                                                             if (allCompletedSubTasks != null) {
                                                                 switch(allCompletedSubTasks){
                                                                     case true:
@@ -2780,11 +2833,13 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                         tryRunNextPart = !partTprReversal;
                                                                         break;
                                                                     default:
-                                                                        // check subtask tpr changes
-                                                                        nextCompleteSubTasks = util.asArray(allCompletedSubTasks);
-                                                                        subtaskTprChanged = !util.iterablesAreSetEquivalent(previouslyCompleteSubTasks, nextCompleteSubTasks);
-                                                                        partTprReversal = !subtaskTprChanged || subtaskTprChanged && nextCompleteSubTasks.length <= previouslyCompleteSubTasks.length;
-                                                                        break;
+                                                                        {
+                                                                            // check subtask tpr changes
+                                                                            nextCompleteSubTasks = util.asArray(allCompletedSubTasks);
+                                                                            subtaskTprChanged = !util.iterablesAreSetEquivalent(previouslyCompleteSubTasks, nextCompleteSubTasks);
+                                                                            partTprReversal = !subtaskTprChanged || nextCompleteSubTasks.length <= previouslyCompleteSubTasks.length;
+                                                                            break;
+                                                                        }
                                                                 }
                                                             }
                                                         }
@@ -3003,7 +3058,8 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                 ];
                                             case 2:
                                                 _ref = _state.sent(), emailRecipients = _ref.emails, textRecipients = _ref.texts, notificationSummaryRecipients = _ref.notificationSummaries;
-                                                es = notification.es, ts = notification.ts, ps = notification.ps, ns = notification.ns, currentEsr = notification.esr, currentTsr = notification.tsr;
+                                                es = notification.es, ts = notification.ts, ps = notification.ps, ns = notification.ns;
+                                                currentEsr = notification.esr, currentTsr = notification.tsr;
                                                 if (!(es === firebase.NotificationSendState.QUEUED || es === firebase.NotificationSendState.SENT_PARTIAL)) return [
                                                     3,
                                                     15
@@ -3110,9 +3166,9 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                             case 13:
                                                 if (sendEmailsResult != null) {
                                                     success1 = sendEmailsResult.success, failed = sendEmailsResult.failed;
-                                                    esr = success1.length ? currentEsr.concat(success1.map(function(x) {
+                                                    esr = success1.length ? _to_consumable_array$5(currentEsr).concat(_to_consumable_array$5(success1.map(function(x) {
                                                         return x.toLowerCase();
-                                                    })) : undefined;
+                                                    }))) : undefined;
                                                     if (failed.length > 0) {
                                                         es = firebase.NotificationSendState.SENT_PARTIAL;
                                                     } else {
@@ -3231,7 +3287,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                             case 26:
                                                 if (sendTextsResult != null) {
                                                     success2 = sendTextsResult.success, failed1 = sendTextsResult.failed;
-                                                    tsr = success2.length ? currentTsr.concat(success2) : undefined;
+                                                    tsr = success2.length ? _to_consumable_array$5(currentTsr).concat(_to_consumable_array$5(success2)) : undefined;
                                                     if (failed1.length > 0) {
                                                         ts = firebase.NotificationSendState.SENT_PARTIAL;
                                                     } else {
@@ -3439,6 +3495,10 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                         // deleted successfully
                                                         success = deletedNotification;
                                                         break;
+                                                    case firebase.NotificationSendType.INIT_BOX_AND_SEND:
+                                                    case firebase.NotificationSendType.SEND_WITHOUT_CREATING_BOX:
+                                                    case firebase.NotificationSendType.TASK_NOTIFICATION:
+                                                        break;
                                                 }
                                                 _state.label = 48;
                                             case 48:
@@ -3459,7 +3519,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                             4,
                                             firestoreContext.runTransaction(function(transaction) {
                                                 return _async_to_generator$d(function() {
-                                                    var notificationBoxDocument, notificationDocumentInTransaction, _ref, notificationBox, notification, model, isNotificationTask, tryRun, throttled, nextSat, createdBox, deletedNotification, notificationBoxNeedsInitialization, isKnownTemplateType, isConfiguredTemplateType, onlySendToExplicitlyEnabledRecipients, onlyTextExplicitlyEnabledRecipients, templateInstance, notificationTaskHandler, t // notification task/template type
+                                                    var notificationBoxDocument, notificationDocumentInTransaction, _ref, initialNotificationBox, notification, notificationBox, model, isNotificationTask, tryRun, throttled, nextSat, createdBox, deletedNotification, notificationBoxNeedsInitialization, isKnownTemplateType, isConfiguredTemplateType, onlySendToExplicitlyEnabledRecipients, onlyTextExplicitlyEnabledRecipients, templateInstance, notificationTaskHandler, t // notification task/template type
                                                     , delay, _notification_ois, _notification_ots, templateTypeInfo, retryAttempts, delay1, _, notificationBoxTemplate, isAtMaxAttempts, a;
                                                     function deleteNotification() {
                                                         return _async_to_generator$d(function() {
@@ -3497,7 +3557,8 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                 _ref = _sliced_to_array$2.apply(void 0, [
                                                                     _state.sent(),
                                                                     2
-                                                                ]), notificationBox = _ref[0], notification = _ref[1];
+                                                                ]), initialNotificationBox = _ref[0], notification = _ref[1];
+                                                                notificationBox = initialNotificationBox;
                                                                 model = firebase.inferKeyFromTwoWayFlatFirestoreModelKey(notificationBoxDocument.id);
                                                                 isNotificationTask = (notification === null || notification === void 0 ? void 0 : notification.st) === firebase.NotificationSendType.TASK_NOTIFICATION;
                                                                 tryRun = true;
@@ -3525,7 +3586,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                 notificationBoxNeedsInitialization = false;
                                                                 if (!(notification && tryRun)) return [
                                                                     3,
-                                                                    18
+                                                                    19
                                                                 ];
                                                                 // if we're still trying to run, check the template is ok. If not, cancel the run.
                                                                 t = notification.n.t;
@@ -3582,7 +3643,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                             case 7:
                                                                 return [
                                                                     3,
-                                                                    18
+                                                                    19
                                                                 ];
                                                             case 8:
                                                                 templateInstance = notificationTemplateService.templateInstanceForType(t);
@@ -3603,7 +3664,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                     9
                                                                 ];
                                                                 if (isKnownTemplateType) {
-                                                                    console.warn('Unconfigured but known template type of "'.concat(t, '" (').concat(templateTypeInfo.name, ") was found in a Notification. Send is being delayed by ").concat(delay1, " hours."));
+                                                                    console.warn('Unconfigured but known template type of "'.concat(t, '" (').concat(templateTypeInfo === null || templateTypeInfo === void 0 ? void 0 : templateTypeInfo.name, ") was found in a Notification. Send is being delayed by ").concat(delay1, " hours."));
                                                                 } else {
                                                                     console.warn('Unknown template type of "'.concat(t, '" was found in a Notification. Send is being delayed by ').concat(delay1, " hours."));
                                                                 }
@@ -3627,7 +3688,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                             case 11:
                                                                 if (!(!notificationBox && tryRun)) return [
                                                                     3,
-                                                                    17
+                                                                    18
                                                                 ];
                                                                 _ = notification.st;
                                                                 switch(_){
@@ -3646,10 +3707,15 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                             3,
                                                                             16
                                                                         ];
+                                                                    case firebase.NotificationSendType.TASK_NOTIFICATION:
+                                                                        return [
+                                                                            3,
+                                                                            17
+                                                                        ];
                                                                 }
                                                                 return [
                                                                     3,
-                                                                    17
+                                                                    18
                                                                 ];
                                                             case 12:
                                                                 return [
@@ -3664,7 +3730,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                 createdBox = true;
                                                                 return [
                                                                     3,
-                                                                    17
+                                                                    18
                                                                 ];
                                                             case 14:
                                                                 // delete the notification since it won't get sent.
@@ -3676,43 +3742,49 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                 _state.sent();
                                                                 return [
                                                                     3,
-                                                                    17
+                                                                    18
                                                                 ];
                                                             case 16:
                                                                 // continue with current tryRun
                                                                 return [
                                                                     3,
-                                                                    17
+                                                                    18
                                                                 ];
                                                             case 17:
+                                                                // task notifications do not require a notification box; continue with current tryRun
+                                                                return [
+                                                                    3,
+                                                                    18
+                                                                ];
+                                                            case 18:
                                                                 // if the notification box is not initialized/synchronized yet, do not run.
                                                                 if (tryRun && notificationBox && notificationBox.s) {
                                                                     notificationBoxNeedsInitialization = true;
                                                                     tryRun = false;
                                                                     nextSat = dateFns.addMinutes(now, NOTIFICATION_BOX_NOT_INITIALIZED_DELAY_MINUTES);
                                                                 }
-                                                                _state.label = 18;
-                                                            case 18:
+                                                                _state.label = 19;
+                                                            case 19:
                                                                 if (!(notification != null && nextSat != null && !deletedNotification)) return [
                                                                     3,
-                                                                    22
+                                                                    23
                                                                 ];
                                                                 isAtMaxAttempts = notification.a >= NOTIFICATION_MAX_SEND_ATTEMPTS;
                                                                 if (!(isAtMaxAttempts && notificationBoxNeedsInitialization)) return [
                                                                     3,
-                                                                    20
+                                                                    21
                                                                 ];
                                                                 return [
                                                                     4,
                                                                     deleteNotification()
                                                                 ];
-                                                            case 19:
-                                                                _state.sent(); // just delete the notification if the box still hasn't been initialized successfully at this point.
-                                                                _state.label = 20;
                                                             case 20:
+                                                                _state.sent(); // just delete the notification if the box still hasn't been initialized successfully at this point.
+                                                                _state.label = 21;
+                                                            case 21:
                                                                 if (!!deletedNotification) return [
                                                                     3,
-                                                                    22
+                                                                    23
                                                                 ];
                                                                 a = isNotificationTask && tryRun ? notification.a : notification.a + 1; // do not update a notification task's attempt count here, unless tryRun fails
                                                                 // NOTE: It is important to update sat so the notification task queue running doesn't get stuck in a query loop by notifications/tasks that have a sat value that is in the past, but was just run.
@@ -3723,10 +3795,10 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                         a: a
                                                                     })
                                                                 ];
-                                                            case 21:
-                                                                _state.sent();
-                                                                _state.label = 22;
                                                             case 22:
+                                                                _state.sent();
+                                                                _state.label = 23;
+                                                            case 23:
                                                                 return [
                                                                     2,
                                                                     {
@@ -3838,6 +3910,9 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
  * and an optional {@link NotificationExpediteService} for immediate delivery.
  * Continues processing batches until no more queued notifications are found
  * or the time budget is exhausted.
+ *
+ * @param context - the notification server actions context with collection group and send factory access
+ * @returns a transform-and-validate function that processes all queued notifications and returns aggregate results
  */ function sendQueuedNotificationsFactory(context) {
     var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationCollectionGroup = context.notificationCollectionGroup;
     var sendNotification = sendNotificationFactory(context);
@@ -3879,7 +3954,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                         excessLoopsDetected = false;
                                         sendQueuedNotifications = function sendQueuedNotifications() {
                                             return _async_to_generator$d(function() {
-                                                var query, notificationDocuments, result;
+                                                var query, notificationDocuments;
                                                 return _ts_generator$d(this, function(_state) {
                                                     switch(_state.label){
                                                         case 0:
@@ -3891,7 +3966,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                         case 1:
                                                             notificationDocuments = _state.sent();
                                                             return [
-                                                                4,
+                                                                2,
                                                                 util.performAsyncTasks(notificationDocuments, function(notificationDocument) {
                                                                     return _async_to_generator$d(function() {
                                                                         var result;
@@ -3916,12 +3991,6 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                     maxParallelTasks: maxParallelTasks
                                                                 })
                                                             ];
-                                                        case 2:
-                                                            result = _state.sent();
-                                                            return [
-                                                                2,
-                                                                result
-                                                            ];
                                                     }
                                                 });
                                             })();
@@ -4011,6 +4080,9 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
  * Queries for {@link Notification} documents that are ready for cleanup (fully sent,
  * past the retention window) and deletes them in batches. Continues until no more
  * cleanup-eligible notifications are found.
+ *
+ * @param context - the notification server actions context with Firestore and collection access
+ * @returns a transform-and-validate function that cleans up sent notification documents and returns aggregate results
  */ function cleanupSentNotificationsFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationCollectionGroup = context.notificationCollectionGroup, notificationBoxCollection = context.notificationBoxCollection, notificationWeekCollectionFactory = context.notificationWeekCollectionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.cleanupSentNotificationsParamsType, function() {
@@ -4023,7 +4095,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                             var notificationBoxesUpdatesCount, notificationsDeleted, notificationTasksDeletedCount, notificationWeeksCreated, notificationWeeksUpdated, cleanupSentNotificationsResults, notificationBoxesUpdated, result;
                             function cleanupSentNotifications() {
                                 return _async_to_generator$d(function() {
-                                    var query, notificationDocuments, notificationDocumentsGroupedByNotificationBox, result;
+                                    var query, notificationDocuments, notificationDocumentsGroupedByNotificationBox;
                                     return _ts_generator$d(this, function(_state) {
                                         switch(_state.label){
                                             case 0:
@@ -4034,14 +4106,14 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                 ];
                                             case 1:
                                                 notificationDocuments = _state.sent();
-                                                notificationDocumentsGroupedByNotificationBox = Array.from(util.makeValuesGroupMap(notificationDocuments, function(x) {
+                                                notificationDocumentsGroupedByNotificationBox = _to_consumable_array$5(util.makeValuesGroupMap(notificationDocuments, function(x) {
                                                     return x.parent.id;
                                                 }).values());
                                                 return [
-                                                    4,
+                                                    2,
                                                     util.performAsyncTasks(notificationDocumentsGroupedByNotificationBox, function(notificationDocumentsInSameBox) {
                                                         return _async_to_generator$d(function() {
-                                                            var allPairs, allPairsWithDataAndMarkedDeleted, _separateValues, taskPairsWithDataAndMarkedDeleted, normalPairsWithDataAndMarkedDeleted, pairsGroupedByWeek, pairsGroupedByWeekInBatches, notificationBoxDocument, notificationWeekResults, writeBatch, writeBatchAccessor, weeksCreated, weeksUpdated, tasksDeleted, result;
+                                                            var allPairs, allPairsWithDataAndMarkedDeleted, _separateValues, taskPairsWithDataAndMarkedDeleted, normalPairsWithDataAndMarkedDeleted, pairsGroupedByWeek, pairsGroupedByWeekInBatches, notificationBoxDocument, notificationWeekResults, writeBatch, writeBatchAccessor, weeksCreated, weeksUpdated, tasksDeleted;
                                                             return _ts_generator$d(this, function(_state) {
                                                                 switch(_state.label){
                                                                     case 0:
@@ -4059,11 +4131,11 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                             var _x_data;
                                                                             return ((_x_data = x.data) === null || _x_data === void 0 ? void 0 : _x_data.st) === firebase.NotificationSendType.TASK_NOTIFICATION;
                                                                         }), taskPairsWithDataAndMarkedDeleted = _separateValues.included, normalPairsWithDataAndMarkedDeleted = _separateValues.excluded;
-                                                                        pairsGroupedByWeek = Array.from(util.makeValuesGroupMap(normalPairsWithDataAndMarkedDeleted, function(x) {
+                                                                        pairsGroupedByWeek = _to_consumable_array$5(util.makeValuesGroupMap(normalPairsWithDataAndMarkedDeleted, function(x) {
                                                                             return date.yearWeekCode(x.data.sat);
                                                                         }).entries());
                                                                         // batch incase there are a lot of new notifications to move to week
-                                                                        pairsGroupedByWeekInBatches = pairsGroupedByWeek.map(function(x) {
+                                                                        pairsGroupedByWeekInBatches = pairsGroupedByWeek.flatMap(function(x) {
                                                                             var batches = util.batch(x[1], 40);
                                                                             return batches.map(function(batch) {
                                                                                 return [
@@ -4071,13 +4143,8 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                                     batch
                                                                                 ];
                                                                             });
-                                                                        }).flat();
-                                                                        return [
-                                                                            4,
-                                                                            notificationBoxCollection.documentAccessor().loadDocument(notificationDocumentsInSameBox[0].parent)
-                                                                        ];
-                                                                    case 2:
-                                                                        notificationBoxDocument = _state.sent();
+                                                                        });
+                                                                        notificationBoxDocument = notificationBoxCollection.documentAccessor().loadDocument(notificationDocumentsInSameBox[0].parent);
                                                                         return [
                                                                             4,
                                                                             util.performAsyncTasks(pairsGroupedByWeekInBatches, function(param) {
@@ -4107,7 +4174,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                                                                     var shouldSaveToNotificationWeek = firebase.shouldSaveNotificationToNotificationWeek(data);
                                                                                                                     return shouldSaveToNotificationWeek ? data.n : undefined;
                                                                                                                 }));
-                                                                                                                n = _to_consumable_array$4((_ref = notificationWeek === null || notificationWeek === void 0 ? void 0 : notificationWeek.n) !== null && _ref !== void 0 ? _ref : []).concat(_to_consumable_array$4(newItems));
+                                                                                                                n = _to_consumable_array$5((_ref = notificationWeek === null || notificationWeek === void 0 ? void 0 : notificationWeek.n) !== null && _ref !== void 0 ? _ref : []).concat(_to_consumable_array$5(newItems));
                                                                                                                 if (!!notificationWeek) return [
                                                                                                                     3,
                                                                                                                     3
@@ -4162,7 +4229,7 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                                 })();
                                                                             })
                                                                         ];
-                                                                    case 3:
+                                                                    case 2:
                                                                         notificationWeekResults = _state.sent();
                                                                         // delete all the task notifications
                                                                         writeBatch = firestoreContext.batch();
@@ -4173,13 +4240,13 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                                 return writeBatchAccessor.loadDocumentFrom(x.document).accessor.delete();
                                                                             }))
                                                                         ];
-                                                                    case 4:
+                                                                    case 3:
                                                                         _state.sent();
                                                                         return [
                                                                             4,
                                                                             writeBatch.commit()
                                                                         ];
-                                                                    case 5:
+                                                                    case 4:
                                                                         _state.sent();
                                                                         weeksCreated = 0;
                                                                         weeksUpdated = 0;
@@ -4191,15 +4258,14 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                                                 weeksUpdated += 1;
                                                                             }
                                                                         });
-                                                                        result = {
-                                                                            weeksCreated: weeksCreated,
-                                                                            weeksUpdated: weeksUpdated,
-                                                                            itemsDeleted: allPairsWithDataAndMarkedDeleted.length,
-                                                                            tasksDeleted: tasksDeleted
-                                                                        };
                                                                         return [
                                                                             2,
-                                                                            result
+                                                                            {
+                                                                                weeksCreated: weeksCreated,
+                                                                                weeksUpdated: weeksUpdated,
+                                                                                itemsDeleted: allPairsWithDataAndMarkedDeleted.length,
+                                                                                tasksDeleted: tasksDeleted
+                                                                            }
                                                                         ];
                                                                 }
                                                             });
@@ -4208,12 +4274,6 @@ var NOTIFICATION_TASK_TYPE_FAILURE_DELAY_MS = dateFns.hoursToMilliseconds(NOTIFI
                                                         maxParallelTasks: 10
                                                     })
                                                 ];
-                                            case 2:
-                                                result = _state.sent();
-                                                return [
-                                                    2,
-                                                    result
-                                                ];
                                         }
                                     });
                                 })();
@@ -4478,6 +4538,7 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  * initialization action to its factory function.
  *
  * @param context - the initialization context with template functions and Firestore access
+ * @returns a fully wired {@link NotificationInitServerActions} instance
  *
  * @example
  * ```ts
@@ -4504,6 +4565,7 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  * Skips initialization if the model is already initialized, optionally throwing an error.
  *
  * @param input - the document, transaction, template function, and options
+ * @returns an object with `initialized` and `alreadyInitialized` boolean flags
  * @throws notificationModelAlreadyInitializedError when `throwErrorIfAlreadyInitialized` is true
  */ function initializeNotificationModelInTransaction(input) {
     return _async_to_generator$c(function() {
@@ -4605,6 +4667,9 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  *
  * Loads the box document in the transaction, reads its current data, and delegates
  * to {@link initializeNotificationModelInTransaction} with the box-specific template function.
+ *
+ * @param context - the initialization context with collection references and template functions
+ * @returns an async function that initializes a notification box given params, document, and transaction
  */ function initializeNotificationBoxInTransactionFactory(context) {
     var notificationBoxCollection = context.notificationBoxCollection, makeTemplateForNotificationBoxInitialization = context.makeTemplateForNotificationBoxInitialization;
     return function(params, notificationBoxDocument, transaction) {
@@ -4641,6 +4706,9 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  *
  * Wraps the in-transaction initialization in a Firestore transaction
  * and follows the transform-and-validate pattern.
+ *
+ * @param context - the initialization context with Firestore access and template functions
+ * @returns a transform-and-validate function that initializes a single notification box
  */ function initializeNotificationBoxFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var initializeNotificationBoxInTransaction = initializeNotificationBoxInTransactionFactory(context);
@@ -4681,8 +4749,11 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  * Batch-processes all {@link NotificationBox} documents flagged for initialization
  * by querying for entries with `s=true` (setup needed), then initializing each in
  * parallel (up to 5 concurrent tasks). Loops until no more flagged boxes are found.
+ *
+ * @param context - the initialization context with Firestore access and collection references
+ * @returns a transform-and-validate function that batch-initializes all applicable notification boxes
  */ function initializeAllApplicableNotificationBoxesFactory(context) {
-    var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationBoxCollection = context.notificationBoxCollection; context.notificationCollectionGroup;
+    var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationBoxCollection = context.notificationBoxCollection;
     var initializeNotificationBoxInTransaction = initializeNotificationBoxInTransactionFactory(context);
     return firebaseServerActionTransformFunctionFactory(firebase.initializeAllApplicableNotificationBoxesParamsType, function() {
         return _async_to_generator$c(function() {
@@ -4798,6 +4869,9 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  *
  * Loads the summary document in the transaction, reads its current data, and delegates
  * to {@link initializeNotificationModelInTransaction} with the summary-specific template function.
+ *
+ * @param context - the initialization context with collection references and template functions
+ * @returns an async function that initializes a notification summary given params, document, and transaction
  */ function initializeNotificationSummaryInTransactionFactory(context) {
     var notificationSummaryCollection = context.notificationSummaryCollection, makeTemplateForNotificationSummaryInitialization = context.makeTemplateForNotificationSummaryInitialization;
     return function(params, notificationSummaryDocument, transaction) {
@@ -4834,6 +4908,9 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  *
  * Wraps the in-transaction summary initialization in a Firestore transaction
  * and follows the transform-and-validate pattern.
+ *
+ * @param context - the initialization context with Firestore access and template functions
+ * @returns a transform-and-validate function that initializes a single notification summary
  */ function initializeNotificationSummaryFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var initializeNotificationSummaryInTransaction = initializeNotificationSummaryInTransactionFactory(context);
@@ -4874,8 +4951,11 @@ var MAKE_TEMPLATE_FOR_NOTIFICATION_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_
  * Batch-processes all {@link NotificationSummary} documents flagged for initialization
  * by querying for entries with `s=true` (setup needed), then initializing each in
  * parallel (up to 5 concurrent tasks). Loops until no more flagged summaries are found.
+ *
+ * @param context - the initialization context with Firestore access and collection references
+ * @returns a transform-and-validate function that batch-initializes all applicable notification summaries
  */ function initializeAllApplicableNotificationSummariesFactory(context) {
-    var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationSummaryCollection = context.notificationSummaryCollection; context.notificationCollectionGroup;
+    var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, notificationSummaryCollection = context.notificationSummaryCollection;
     var initializeNotificationSummaryInTransaction = initializeNotificationSummaryInTransactionFactory(context);
     return firebaseServerActionTransformFunctionFactory(firebase.initializeAllApplicableNotificationSummariesParamsType, function() {
         return _async_to_generator$c(function() {
@@ -5229,6 +5309,7 @@ function _ts_generator$b(thisArg, body) {
      * pre-wired with the resolved factory for that type.
      *
      * @param type - the notification template type
+     * @returns a new {@link NotificationTemplateServiceInstance} bound to the given type
      */ key: "templateInstanceForType",
             value: function templateInstanceForType(type) {
                 return notificationTemplateServiceInstance(this, type);
@@ -5250,6 +5331,7 @@ exports.NotificationTemplateService = __decorate([
  *
  * @param service - the parent template service
  * @param type - the template type to bind
+ * @returns a {@link NotificationTemplateServiceInstance} with the resolved factory for the type
  *
  * @example
  * ```ts
@@ -5471,6 +5553,7 @@ function _ts_generator$a(thisArg, body) {
  * Does not support Firestore transactions, as running should occur outside of a transaction.
  *
  * @param input - creation and run configuration
+ * @returns the creation pair result with optional send/enqueue outcomes
  * @throws Error if the notification template is not flagged as unique
  *
  * @example
@@ -5829,8 +5912,8 @@ function _ts_generator$9(thisArg, body) {
 /**
  * Creates a new NotificationExpediteServiceInstance with the input NotificationExpediteService.
  
- * @param notificationExpediteService
- * @returns
+ * @param notificationExpediteService - the expedite service to use for sending
+ * @returns a new {@link NotificationExpediteServiceInstance} with an internal queue
  */ function notificationExpediteServiceInstance(notificationExpediteService) {
     var _documentsToSend = [];
     var initialize = function initialize() {
@@ -5849,28 +5932,18 @@ function _ts_generator$9(thisArg, body) {
     };
     var send = function send(options) {
         return _async_to_generator$9(function() {
-            var results;
             return _ts_generator$9(this, function(_state) {
-                switch(_state.label){
-                    case 0:
-                        return [
-                            4,
-                            util.runAsyncTasksForValues(_documentsToSend, function(x) {
-                                return notificationExpediteService.sendNotification(x, options);
-                            }, {
-                                nonConcurrentTaskKeyFactory: function nonConcurrentTaskKeyFactory(x) {
-                                    return x.parent.id // only send one notification at a time for a notification box
-                                    ;
-                                }
-                            })
-                        ];
-                    case 1:
-                        results = _state.sent();
-                        return [
-                            2,
-                            results
-                        ];
-                }
+                return [
+                    2,
+                    util.runAsyncTasksForValues(_documentsToSend, function(x) {
+                        return notificationExpediteService.sendNotification(x, options);
+                    }, {
+                        nonConcurrentTaskKeyFactory: function nonConcurrentTaskKeyFactory(x) {
+                            return x.parent.id // only send one notification at a time for a notification box
+                            ;
+                        }
+                    })
+                ];
             });
         })();
     };
@@ -5898,6 +5971,8 @@ function _ts_generator$9(thisArg, body) {
         {
             /**
      * Returns the configured NotificationServerActions instance.
+     *
+     * @returns the current {@link NotificationServerActions} instance
      */ key: "getNotificationServerActions",
             value: function getNotificationServerActions() {
                 return this._notificationServerActions;
@@ -5906,6 +5981,8 @@ function _ts_generator$9(thisArg, body) {
         {
             /**
      * Sets the NotificationServerActions instance to use.
+     *
+     * @param notificationServerActions - the actions instance to configure
      */ key: "setNotificationServerActions",
             value: function setNotificationServerActions(notificationServerActions) {
                 this._notificationServerActions = notificationServerActions;
@@ -5953,6 +6030,8 @@ exports.MutableNotificationExpediteService = __decorate([
  * Provides an instance of MutableNotificationExpediteService and NotificationExpediteService.
  *
  * This should generally be used in the global module of an app.
+ *
+ * @returns an array of NestJS providers for both MutableNotificationExpediteService and NotificationExpediteService
  */ function provideMutableNotificationExpediteService() {
     return [
         exports.MutableNotificationExpediteService,
@@ -5966,6 +6045,8 @@ exports.MutableNotificationExpediteService = __decorate([
  * Convenience function that exports NotificationExpediteService and MutableNotificationExpediteService.
  *
  * This should generally be used in the global module of an app.
+ *
+ * @returns an array of abstract classes to export from the NestJS module
  */ function exportMutableNotificationExpediteService() {
     return [
         NotificationExpediteService,
@@ -5978,7 +6059,7 @@ function _array_like_to_array$5(arr, len) {
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$3(arr) {
+function _array_without_holes$4(arr) {
     if (Array.isArray(arr)) return _array_like_to_array$5(arr);
 }
 function _class_call_check$4(instance, Constructor) {
@@ -5999,10 +6080,10 @@ function _define_property$7(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$3(iter) {
+function _iterable_to_array$4(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread$3() {
+function _non_iterable_spread$4() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _object_spread$7(target) {
@@ -6039,8 +6120,8 @@ function _object_spread_props$7(target, source) {
     }
     return target;
 }
-function _to_consumable_array$3(arr) {
-    return _array_without_holes$3(arr) || _iterable_to_array$3(arr) || _unsupported_iterable_to_array$5(arr) || _non_iterable_spread$3();
+function _to_consumable_array$4(arr) {
+    return _array_without_holes$4(arr) || _iterable_to_array$4(arr) || _unsupported_iterable_to_array$5(arr) || _non_iterable_spread$4();
 }
 function _unsupported_iterable_to_array$5(o, minLen) {
     if (!o) return;
@@ -6054,7 +6135,15 @@ function _unsupported_iterable_to_array$5(o, minLen) {
 /**
  * Factory that assembles the full {@link NotificationServerActionsContext} by combining
  * the base context with the template, send, task, and expedite services.
- */ function notificationServerActionsContextFactory(context, notificationTemplateService, notificationSendService, notificationTaskService, notificationsExpediteService) {
+ *
+ * @param context - the base server actions context
+ * @param notificationTemplateService - resolves message factories for notification template types
+ * @param notificationSendService - handles sending notification messages
+ * @param notificationTaskService - handles notification task dispatch
+ * @param notificationsExpediteService - expedites immediate notification delivery
+ * @returns the assembled {@link NotificationServerActionsContext}
+ */ // eslint-disable-next-line @typescript-eslint/max-params
+function notificationServerActionsContextFactory(context, notificationTemplateService, notificationSendService, notificationTaskService, notificationsExpediteService) {
     return _object_spread_props$7(_object_spread$7({}, context), {
         notificationTemplateService: notificationTemplateService,
         notificationSendService: notificationSendService,
@@ -6064,12 +6153,19 @@ function _unsupported_iterable_to_array$5(o, minLen) {
 }
 /**
  * Factory that creates a {@link NotificationServerActions} instance from the assembled context.
- */ function notificationServerActionsFactory(context, mutableNotificationExpediteService) {
+ *
+ * @param context - the assembled notification server actions context
+ * @returns a new {@link NotificationServerActions} instance
+ */ function notificationServerActionsFactory(context) {
     return notificationServerActions(context);
 }
 /**
  * Factory that creates a {@link NotificationInitServerActions} instance by merging the
  * server actions context with the init-specific configuration.
+ *
+ * @param context - the assembled notification server actions context
+ * @param notificationInitServerActionsContextConfig - init-specific configuration
+ * @returns a new {@link NotificationInitServerActions} instance
  */ function notificationInitServerActionsFactory(context, notificationInitServerActionsContextConfig) {
     return notificationInitServerActions(_object_spread$7({}, context, notificationInitServerActionsContextConfig));
 }
@@ -6085,9 +6181,8 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  *
  * Be sure the class that delares the module using this function also extends AbstractAppNotificationModule.
  *
- * @param provide
- * @param useFactory
- * @returns
+ * @param config - module metadata configuration including dependency module and additional providers
+ * @returns the assembled {@link ModuleMetadata} for the notification module
  */ function appNotificationModuleMetadata(config$1) {
     var dependencyModule = config$1.dependencyModule, imports = config$1.imports, exports$1 = config$1.exports, providers = config$1.providers;
     var dependencyModuleImport = dependencyModule ? [
@@ -6096,14 +6191,14 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     return {
         imports: [
             config.ConfigModule
-        ].concat(_to_consumable_array$3(dependencyModuleImport), _to_consumable_array$3(imports !== null && imports !== void 0 ? imports : [])),
+        ].concat(_to_consumable_array$4(dependencyModuleImport), _to_consumable_array$4(imports !== null && imports !== void 0 ? imports : [])),
         exports: [
             NOTIFICATION_SERVER_ACTION_CONTEXT_TOKEN,
             NotificationExpediteService,
             exports.NotificationTemplateService,
             NotificationServerActions,
             NotificationInitServerActions
-        ].concat(_to_consumable_array$3(exports$1 !== null && exports$1 !== void 0 ? exports$1 : [])),
+        ].concat(_to_consumable_array$4(exports$1 !== null && exports$1 !== void 0 ? exports$1 : [])),
         providers: [
             {
                 provide: NotificationExpediteService,
@@ -6128,8 +6223,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
                 provide: NotificationServerActions,
                 useFactory: notificationServerActionsFactory,
                 inject: [
-                    NOTIFICATION_SERVER_ACTION_CONTEXT_TOKEN,
-                    NotificationExpediteService
+                    NOTIFICATION_SERVER_ACTION_CONTEXT_TOKEN
                 ]
             },
             {
@@ -6140,7 +6234,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
                     NOTIFICATION_INIT_SERVER_ACTIONS_CONTEXT_CONFIG_TOKEN
                 ]
             }
-        ].concat(_to_consumable_array$3(providers !== null && providers !== void 0 ? providers : []))
+        ].concat(_to_consumable_array$4(providers !== null && providers !== void 0 ? providers : []))
     };
 }
 /**
@@ -6175,6 +6269,9 @@ function _array_like_to_array$4(arr, len) {
 function _array_with_holes$1(arr) {
     if (Array.isArray(arr)) return arr;
 }
+function _array_without_holes$3(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$4(arr);
+}
 function asyncGeneratorStep$8(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
@@ -6217,6 +6314,9 @@ function _define_property$6(obj, key, value) {
     }
     return obj;
 }
+function _iterable_to_array$3(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
 function _iterable_to_array_limit$1(arr, i) {
     var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
     if (_i == null) return;
@@ -6244,6 +6344,9 @@ function _iterable_to_array_limit$1(arr, i) {
 function _non_iterable_rest$1() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
+function _non_iterable_spread$3() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
 function _object_spread$6(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
@@ -6281,6 +6384,9 @@ function _object_spread_props$6(target, source) {
 function _sliced_to_array$1(arr, i) {
     return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$4(arr, i) || _non_iterable_rest$1();
 }
+function _to_consumable_array$3(arr) {
+    return _array_without_holes$3(arr) || _iterable_to_array$3(arr) || _unsupported_iterable_to_array$4(arr) || _non_iterable_spread$3();
+}
 function _unsupported_iterable_to_array$4(o, minLen) {
     if (!o) return;
     if (typeof o === "string") return _array_like_to_array$4(o, minLen);
@@ -6399,6 +6505,7 @@ function _ts_generator$8(thisArg, body) {
  * Each summary update runs in a Firestore transaction to prevent concurrent write conflicts.
  *
  * @param config - service configuration including Firestore context and collection references
+ * @returns a {@link NotificationSummarySendService} backed by Firestore
  *
  * @example
  * ```ts
@@ -6432,6 +6539,7 @@ function _ts_generator$8(thisArg, body) {
                     cutMessage = util.cutStringFunction({
                         maxLength: firebase.NOTIFICATION_SUMMARY_EMBEDDED_NOTIFICATION_ITEM_MESSAGE_MAX_LENGTH
                     });
+                    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
                     messagesGroups = messagesGroupedByNotificationSummaryMapBuilder.entries();
                     return [
                         2,
@@ -6478,7 +6586,7 @@ function _ts_generator$8(thisArg, body) {
                                                                                             });
                                                                                             if (messagesToSend.length > 0) {
                                                                                                 // add the new items to existing n, then keep the last 1000
-                                                                                                sortedN = existingMessages.concat(messagesToSend.map(function(x) {
+                                                                                                sortedN = _to_consumable_array$3(existingMessages).concat(_to_consumable_array$3(messagesToSend.map(function(x) {
                                                                                                     var message = '';
                                                                                                     if (x.content.openingMessage) {
                                                                                                         message = x.content.openingMessage;
@@ -6491,7 +6599,7 @@ function _ts_generator$8(thisArg, body) {
                                                                                                         g: cutMessage(message)
                                                                                                     });
                                                                                                     return item;
-                                                                                                })).sort(firebase.sortNotificationItemsFunction);
+                                                                                                }))).sort(firebase.sortNotificationItemsFunction);
                                                                                                 n = util.takeLast(sortedN, firebase.NOTIFICATION_SUMMARY_ITEM_LIMIT);
                                                                                                 updateTemplate = {
                                                                                                     n: n,
@@ -6719,6 +6827,8 @@ function _ts_generator$7(thisArg, body) {
  * Useful as a placeholder when your app's notification pipeline is fully wired for SMS
  * but actual delivery is not yet enabled, avoiding the need for conditional logic elsewhere.
  *
+ * @returns a no-op {@link NotificationTextSendService} that ignores all messages
+ *
  * @example
  * ```ts
  * const textService = ignoreSendNotificationTextSendService();
@@ -6898,6 +7008,7 @@ function _ts_generator$6(thisArg, body) {
  * If all checkpoints are complete, the task is marked as done.
  *
  * @param config - handler configurations and optional validation list
+ * @returns a {@link NotificationTaskService} that dispatches tasks to the registered handlers
  *
  * @example
  * ```ts
@@ -6943,14 +7054,16 @@ function _ts_generator$6(thisArg, body) {
                                         fn = (_this = (_nonCheckpointFlows_ = nonCheckpointFlows[0]) !== null && _nonCheckpointFlows_ !== void 0 ? _nonCheckpointFlows_ : checkpointFlows[0]) === null || _this === void 0 ? void 0 : _this.fn;
                                         break;
                                     default:
-                                        completedCheckpointsSet = new Set(completedCheckpoints);
-                                        /**
+                                        {
+                                            completedCheckpointsSet = new Set(completedCheckpoints);
+                                            /**
                          * Find the next flow function that hasn't had its checkpoint completed yet.
                          */ nextCheckpoint = checkpointFlows.find(function(x) {
-                                            return !completedCheckpointsSet.has(x.checkpoint);
-                                        });
-                                        fn = nextCheckpoint === null || nextCheckpoint === void 0 ? void 0 : nextCheckpoint.fn;
-                                        break;
+                                                return !completedCheckpointsSet.has(x.checkpoint);
+                                            });
+                                            fn = nextCheckpoint === null || nextCheckpoint === void 0 ? void 0 : nextCheckpoint.fn;
+                                            break;
+                                        }
                                 }
                                 if (!fn) return [
                                     3,
@@ -7277,6 +7390,7 @@ function _ts_generator$5(thisArg, body) {
  * such as storage file processing or other async workflows.
  *
  * @param factoryConfig - shared configuration including the input function, cleanup logic, and task type
+ * @returns a factory function that produces {@link NotificationTaskServiceTaskHandlerConfig} entries
  *
  * @example
  * ```ts
@@ -7299,6 +7413,9 @@ function _ts_generator$5(thisArg, body) {
     return function(subtaskHandlerConfig) {
         var processorFunctionForConfig = /**
          * Structure is similar to notificationTaskService(), but contained to handle the subtasks.
+         *
+         * @param processorConfig - the processor configuration with target, flow, and cleanup
+         * @returns a processor with process and optional cleanup functions
          */ function processorFunctionForConfig(processorConfig) {
             var inputFlows = processorConfig.flow, cleanup = processorConfig.cleanup, processorAllowRunMultipleParts = processorConfig.allowRunMultipleParts;
             var _separateValues = util.separateValues(inputFlows, function(x) {
@@ -7326,14 +7443,16 @@ function _ts_generator$5(thisArg, body) {
                                             fn = (_this = (_nonSubtaskFlows_ = nonSubtaskFlows[0]) !== null && _nonSubtaskFlows_ !== void 0 ? _nonSubtaskFlows_ : subtaskFlows[0]) === null || _this === void 0 ? void 0 : _this.fn;
                                             break;
                                         default:
-                                            completedSubtasksSet = new Set(completedSubtasks);
-                                            /**
+                                            {
+                                                completedSubtasksSet = new Set(completedSubtasks);
+                                                /**
                              * Find the next flow function that hasn't had its checkpoint completed yet.
                              */ nextSubtask = subtaskFlows.find(function(x) {
-                                                return !completedSubtasksSet.has(x.subtask);
-                                            });
-                                            fn = nextSubtask === null || nextSubtask === void 0 ? void 0 : nextSubtask.fn;
-                                            break;
+                                                    return !completedSubtasksSet.has(x.subtask);
+                                                });
+                                                fn = nextSubtask === null || nextSubtask === void 0 ? void 0 : nextSubtask.fn;
+                                                break;
+                                            }
                                     }
                                     if (!fn) return [
                                         3,
@@ -7358,13 +7477,15 @@ function _ts_generator$5(thisArg, body) {
                                             sfps = removeFromCompletionsArrayWithTaskResult(sfps, subtaskResult);
                                             break;
                                         default:
-                                            sfps = util.unique(_to_consumable_array$2(removeFromCompletionsArrayWithTaskResult(sfps, subtaskResult)).concat(_to_consumable_array$2(util.asArray(subtaskCompletion))));
-                                            completedSubtasksSet1 = new Set(sfps);
-                                            incompleteSubtasks = allKnownSubtasks.filter(function(x) {
-                                                return !completedSubtasksSet1.has(x);
-                                            });
-                                            allSubtasksDone = incompleteSubtasks.length === 0;
-                                            break;
+                                            {
+                                                sfps = util.unique(_to_consumable_array$2(removeFromCompletionsArrayWithTaskResult(sfps, subtaskResult)).concat(_to_consumable_array$2(util.asArray(subtaskCompletion))));
+                                                completedSubtasksSet1 = new Set(sfps);
+                                                incompleteSubtasks = allKnownSubtasks.filter(function(x) {
+                                                    return !completedSubtasksSet1.has(x);
+                                                });
+                                                allSubtasksDone = incompleteSubtasks.length === 0;
+                                                break;
+                                            }
                                     }
                                     // configure the update metadata result
                                     sd = _object_spread$5({}, subtaskData, subtaskUpdateMetadata);
@@ -7578,7 +7699,7 @@ function _ts_generator$5(thisArg, body) {
                                             8
                                         ];
                                         processor = processors[target];
-                                        if (!(processor && processor.cleanup)) return [
+                                        if (!(processor === null || processor === void 0 ? void 0 : processor.cleanup)) return [
                                             3,
                                             5
                                         ];
@@ -7691,12 +7812,16 @@ function _ts_generator$5(thisArg, body) {
 }(makeError.BaseError);
 /**
  * Creates a NotificationTaskSubTaskMissingRequiredDataTermination.
+ *
+ * @returns a new {@link NotificationTaskSubTaskMissingRequiredDataTermination} error instance
  */ function notificationTaskSubTaskMissingRequiredDataTermination() {
     return new NotificationTaskSubTaskMissingRequiredDataTermination();
 }
 
 /**
  * Creates an error indicating that a storage file model has already been initialized.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_MODEL_ALREADY_INITIALIZED error code
  */ function storageFileModelAlreadyInitializedError() {
     return firebaseServer.preconditionConflictError({
         message: "This model has already been initialized.",
@@ -7705,6 +7830,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the StorageFile is not flagged for group sync.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_NOT_FLAGGED_FOR_GROUPS_SYNC error code
  */ function storageFileNotFlaggedForGroupsSyncError() {
     return firebaseServer.preconditionConflictError({
         message: "This StorageFile has not been flagged for sync with its groups.",
@@ -7713,6 +7840,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the target uploaded file does not exist in storage.
+ *
+ * @returns a precondition-conflict HttpsError with the UPLOADED_FILE_DOES_NOT_EXIST error code
  */ function uploadedFileDoesNotExistError() {
     return firebaseServer.preconditionConflictError({
         message: "The target uploaded file does not exist.",
@@ -7721,6 +7850,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the file is not allowed to be initialized (rejected by the check function).
+ *
+ * @returns a precondition-conflict HttpsError with the UPLOADED_FILE_NOT_ALLOWED_TO_BE_INITIALIZED error code
  */ function uploadedFileIsNotAllowedToBeInitializedError() {
     return firebaseServer.preconditionConflictError({
         message: "The target uploaded file is not allowed to be initialized.",
@@ -7731,6 +7862,7 @@ function _ts_generator$5(thisArg, body) {
  * Creates an error indicating that the file initialization failed with the given result type.
  *
  * @param data - error data containing the result type that caused the failure
+ * @returns an internal-server HttpsError with the UPLOADED_FILE_INITIALIZATION_FAILED error code and the result type
  */ function uploadedFileInitializationFailedError(data) {
     return firebaseServer.internalServerError({
         message: 'The target uploaded file initialization failed with result type "'.concat(data.resultType, '".'),
@@ -7742,6 +7874,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the initialization result was discarded (e.g., the created file no longer exists).
+ *
+ * @returns an internal-server HttpsError with the UPLOADED_FILE_INITIALIZATION_DISCARDED error code
  */ function uploadedFileInitializationDiscardedError() {
     return firebaseServer.internalServerError({
         message: "The target uploaded file initialization was discarded.",
@@ -7750,6 +7884,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the StorageFile is not in a valid state for processing.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_PROCESSING_NOT_ALLOWED_FOR_INVALID_STATE error code
  */ function storageFileProcessingNotAllowedForInvalidStateError() {
     return firebaseServer.preconditionConflictError({
         message: "The target StorageFileDocument must be in an OK state to be processed and processing not flagged as SHOULD_NOT_PROCESS.",
@@ -7758,6 +7894,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the StorageFile is not queued for processing.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_PROCESSING_NOT_QUEUED_FOR_PROCESSING error code
  */ function storageFileProcessingNotQueuedForProcessingError() {
     return firebaseServer.preconditionConflictError({
         message: "The target StorageFileDocument is not queued for processing.",
@@ -7766,6 +7904,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that no processor is configured for the StorageFile's type.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_PROCESSING_NOT_AVAILABLE_FOR_TYPE error code
  */ function storageFileProcessingNotAvailableForTypeError() {
     return firebaseServer.preconditionConflictError({
         message: "The target StorageFileDocument is not available for processing.",
@@ -7774,6 +7914,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the StorageFile has already finished processing.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_ALREADY_PROCESSED error code
  */ function storageFileAlreadyProcessedError() {
     return firebaseServer.preconditionConflictError({
         message: "The target StorageFileDocument has already finished processing.",
@@ -7782,6 +7924,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the StorageFile is not flagged for deletion.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_NOT_FLAGGED_FOR_DELETION error code
  */ function storageFileNotFlaggedForDeletionError() {
     return firebaseServer.preconditionConflictError({
         message: "The target StorageFileDocument is not flagged for deletion.",
@@ -7790,6 +7934,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the StorageFile's scheduled deletion time has not yet passed.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_CANNOT_BE_DELETED_YET error code
  */ function storageFileCannotBeDeletedYetError() {
     return firebaseServer.preconditionConflictError({
         message: "The target StorageFileDocument cannot be deleted yet.",
@@ -7798,6 +7944,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the StorageFileGroup is still queued for initialization and cannot be operated on.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_GROUP_QUEUED_FOR_INITIALIZATION error code
  */ function storageFileGroupQueuedForInitializationError() {
     return firebaseServer.preconditionConflictError({
         message: "The target StorageFileGroupDocument is queued for initialization.",
@@ -7806,6 +7954,8 @@ function _ts_generator$5(thisArg, body) {
 }
 /**
  * Creates an error indicating that the required model key or storageFileId is missing when creating a StorageFileGroup.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_GROUP_CREATE_INPUT error code
  */ function createStorageFileGroupInputError() {
     return firebaseServer.preconditionConflictError({
         message: "The model or storageFileId is required for creating a StorageFileGroup.",
@@ -7895,10 +8045,6 @@ function _iterable_to_array_limit(arr, i) {
 function _non_iterable_rest() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _object_destructuring_empty(o) {
-    if (o === null || o === void 0) throw new TypeError("Cannot destructure " + o);
-    return o;
-}
 function _object_spread$4(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
@@ -8075,6 +8221,9 @@ function _ts_generator$4(thisArg, body) {
  *
  * @param context - the fully assembled storage file server actions context
  *
+ * @param context - the fully assembled storage file server actions context
+ * @returns a concrete {@link StorageFileServerActions} with all action methods wired to their factories
+ *
  * @example
  * ```ts
  * const actions = storageFileServerActions(context);
@@ -8105,23 +8254,23 @@ function _ts_generator$4(thisArg, body) {
  * Factory for the `createStorageFile` action.
  *
  * Creates a new {@link StorageFile} document using the provided template data.
+ *
+ * @param context - the base server actions context providing Firestore and storage access
+ * @returns an async transform-and-validate function that creates a StorageFile document
  */ function createStorageFileFactory(context) {
-    context.storageFileCollection; context.firestoreContext; var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
+    var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.createStorageFileParamsType, function(params) {
         return _async_to_generator$4(function() {
             return _ts_generator$4(this, function(_state) {
-                _object_destructuring_empty(params);
                 return [
                     2,
                     function() {
                         return _async_to_generator$4(function() {
-                            var storageFileDocument;
                             return _ts_generator$4(this, function(_state) {
-                                storageFileDocument = null;
                                 // TODO: check the file exists, and pull the metadata, and create the document
                                 return [
                                     2,
-                                    storageFileDocument
+                                    null
                                 ];
                             });
                         })();
@@ -8137,6 +8286,9 @@ function _ts_generator$4(thisArg, body) {
  * Scans the uploads folder in Firebase Storage, identifies new uploaded files,
  * initializes each one via the upload service, and cleans up the source upload
  * on success. Failed initializations are logged but do not halt the batch.
+ *
+ * @param context - the storage file server actions context with storage service and upload initialization
+ * @returns an async transform-and-validate function that returns batch initialization results
  */ function initializeAllStorageFilesFromUploadsFactory(context) {
     var storageService = context.storageService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var _initializeStorageFileFromUploadFile = _initializeStorageFileFromUploadFileFactory(context);
@@ -8230,7 +8382,15 @@ function _ts_generator$4(thisArg, body) {
         })();
     });
 }
-function _initializeStorageFileFromUploadFileFactory(context) {
+/**
+ * Internal factory that creates a function to initialize a {@link StorageFile} from an uploaded file.
+ *
+ * Validates the file exists and is allowed, runs the upload initializer, deletes the upload source
+ * on success, and optionally expedites processing of the created storage file.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that accepts an upload file input and returns the created StorageFileDocument
+ */ function _initializeStorageFileFromUploadFileFactory(context) {
     var firestoreContext = context.firestoreContext, storageFileInitializeFromUploadService = context.storageFileInitializeFromUploadService, notificationExpediteService = context.notificationExpediteService;
     var processStorageFileInTransaction = _processStorageFileInTransactionFactory(context);
     return function(input) {
@@ -8358,7 +8518,7 @@ function _initializeStorageFileFromUploadFileFactory(context) {
                             11
                         ];
                         storageFileDocument = initializationResult.storageFileDocument;
-                        if (!(storageFileDocument != null && expediteProcessing)) return [
+                        if (!expediteProcessing) return [
                             3,
                             10
                         ];
@@ -8494,6 +8654,9 @@ function _initializeStorageFileFromUploadFileFactory(context) {
  * Initializes a single {@link StorageFile} from an uploaded file at the given storage path.
  * Validates the file exists and is allowed, runs the type determiner and initializer,
  * then cleans up the upload source on success.
+ *
+ * @param context - the storage file server actions context with storage and upload services
+ * @returns an async transform-and-validate function that creates a StorageFile from an upload
  */ function initializeStorageFileFromUploadFactory(context) {
     var storageService = context.storageService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var _initializeStorageFileFromUploadFile = _initializeStorageFileFromUploadFileFactory(context);
@@ -8527,8 +8690,15 @@ function _initializeStorageFileFromUploadFileFactory(context) {
         })();
     });
 }
-function updateStorageFileFactory(context) {
-    context.storageFileCollection; context.firestoreContext; var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
+/**
+ * Factory for the `updateStorageFile` action.
+ *
+ * Updates an existing {@link StorageFile} document with the provided schedule-delete-at time.
+ *
+ * @param context - the base server actions context providing Firestore access
+ * @returns an async transform-and-validate function that updates a StorageFile document
+ */ function updateStorageFileFactory(context) {
+    var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.updateStorageFileParamsType, function(params) {
         return _async_to_generator$4(function() {
             var sdat;
@@ -8564,7 +8734,15 @@ function updateStorageFileFactory(context) {
         })();
     });
 }
-function updateStorageFileGroupFactory(context) {
+/**
+ * Factory for the `updateStorageFileGroup` action.
+ *
+ * Updates embedded file entries within a {@link StorageFileGroup} document inside a
+ * Firestore transaction, merging display name changes into the existing entries.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that updates a StorageFileGroup document
+ */ function updateStorageFileGroupFactory(context) {
     var firestoreContext = context.firestoreContext, storageFileGroupCollection = context.storageFileGroupCollection, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     return firebaseServerActionTransformFunctionFactory(firebase.updateStorageFileGroupParamsType, function(params) {
         return _async_to_generator$4(function() {
@@ -8646,10 +8824,13 @@ function updateStorageFileGroupFactory(context) {
  * Batch-processes all {@link StorageFile} documents queued for processing. Creates a
  * processing notification task for each file and optionally expedites delivery.
  * Handles stuck-processing detection with a throttle check.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch processing results
  */ function processAllQueuedStorageFilesFactory(context) {
     var storageFileCollection = context.storageFileCollection, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var processStorageFile = processStorageFileFactory(context);
-    return firebaseServerActionTransformFunctionFactory(firebase.processAllQueuedStorageFilesParamsType, function(params) {
+    return firebaseServerActionTransformFunctionFactory(firebase.processAllQueuedStorageFilesParamsType, function(_params) {
         return _async_to_generator$4(function() {
             return _ts_generator$4(this, function(_state) {
                 return [
@@ -8733,7 +8914,15 @@ function updateStorageFileGroupFactory(context) {
         })();
     });
 }
-function _processStorageFileInTransactionFactory(context) {
+/**
+ * Internal factory that creates a function for processing a {@link StorageFile} within a Firestore transaction.
+ *
+ * Creates or restarts a notification task for the file based on its current processing state,
+ * handling stuck-processing detection, forced restarts, and re-processing of already-successful files.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that processes a storage file within a transaction
+ */ function _processStorageFileInTransactionFactory(context) {
     var storageFileCollection = context.storageFileCollection, notificationCollectionGroup = context.notificationCollectionGroup;
     return function(input, transaction) {
         return _async_to_generator$4(function() {
@@ -8823,20 +9012,30 @@ function _processStorageFileInTransactionFactory(context) {
                                     3,
                                     10
                                 ];
-                            case firebase.StorageFileProcessingState.DO_NOT_PROCESS:
+                            case firebase.StorageFileProcessingState.FAILED:
                                 return [
                                     3,
                                     20
                                 ];
+                            case firebase.StorageFileProcessingState.DO_NOT_PROCESS:
+                                return [
+                                    3,
+                                    22
+                                ];
                             case firebase.StorageFileProcessingState.SUCCESS:
                                 return [
                                     3,
-                                    21
+                                    23
+                                ];
+                            case firebase.StorageFileProcessingState.ARCHIVED:
+                                return [
+                                    3,
+                                    27
                                 ];
                         }
                         return [
                             3,
-                            25
+                            28
                         ];
                     case 4:
                         if (!!storageFile.p) return [
@@ -8855,7 +9054,7 @@ function _processStorageFileInTransactionFactory(context) {
                     case 7:
                         return [
                             3,
-                            25
+                            28
                         ];
                     case 8:
                         // begin processing
@@ -8867,7 +9066,7 @@ function _processStorageFileInTransactionFactory(context) {
                         _state.sent();
                         return [
                             3,
-                            25
+                            28
                         ];
                     case 10:
                         // check if the processing task is still running
@@ -8941,33 +9140,47 @@ function _processStorageFileInTransactionFactory(context) {
                     case 19:
                         return [
                             3,
-                            25
+                            28
                         ];
                     case 20:
-                        throw storageFileProcessingNotQueuedForProcessingError();
+                        // restart processing on failure
+                        return [
+                            4,
+                            beginProcessing(true)
+                        ];
                     case 21:
+                        _state.sent();
+                        return [
+                            3,
+                            28
+                        ];
+                    case 22:
+                        throw storageFileProcessingNotQueuedForProcessingError();
+                    case 23:
                         if (!(forceRestartProcessing || processAgainIfSuccessful)) return [
                             3,
-                            23
+                            25
                         ];
                         return [
                             4,
                             beginProcessing(true)
                         ];
-                    case 22:
+                    case 24:
                         _state.sent();
                         return [
                             3,
-                            24
+                            26
                         ];
-                    case 23:
+                    case 25:
                         throw storageFileAlreadyProcessedError();
-                    case 24:
+                    case 26:
                         return [
                             3,
-                            25
+                            28
                         ];
-                    case 25:
+                    case 27:
+                        throw storageFileProcessingNotQueuedForProcessingError();
+                    case 28:
                         return [
                             2
                         ];
@@ -8981,6 +9194,9 @@ function _processStorageFileInTransactionFactory(context) {
  *
  * Processes a single {@link StorageFile} by creating a notification task for it
  * and marking it as processing. Validates the file is in a valid state for processing.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that processes a single StorageFile
  */ function processStorageFileFactory(context) {
     var firestoreContext = context.firestoreContext, notificationExpediteService = context.notificationExpediteService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var processStorageFileInTransaction = _processStorageFileInTransactionFactory(context);
@@ -9064,10 +9280,13 @@ function _processStorageFileInTransactionFactory(context) {
  * Batch-deletes all {@link StorageFile} documents flagged for deletion whose
  * scheduled delete time has passed. Removes both the Firestore document and
  * the associated file in Cloud Storage.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch deletion results
  */ function deleteAllQueuedStorageFilesFactory(context) {
     var storageFileCollection = context.storageFileCollection, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var deleteStorageFile = deleteStorageFileFactory(context);
-    return firebaseServerActionTransformFunctionFactory(firebase.deleteAllQueuedStorageFilesParamsType, function(params) {
+    return firebaseServerActionTransformFunctionFactory(firebase.deleteAllQueuedStorageFilesParamsType, function(_params) {
         return _async_to_generator$4(function() {
             return _ts_generator$4(this, function(_state) {
                 return [
@@ -9158,6 +9377,9 @@ function _processStorageFileInTransactionFactory(context) {
  *
  * Deletes a single {@link StorageFile} document and its associated Cloud Storage file.
  * Validates the file is flagged for deletion and the scheduled delete time has passed.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that deletes a StorageFile and its storage object
  */ function deleteStorageFileFactory(context) {
     var firestoreContext = context.firestoreContext, storageService = context.storageService, storageFileCollection = context.storageFileCollection, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var syncStorageFileWithGroupsInTransaction = _syncStorageFileWithGroupsInTransactionFactory(context);
@@ -9181,17 +9403,12 @@ function _processStorageFileInTransactionFactory(context) {
                                                     return _ts_generator$4(this, function(_state) {
                                                         switch(_state.label){
                                                             case 0:
-                                                                return [
-                                                                    4,
-                                                                    storageFileCollection.documentAccessorForTransaction(transaction).loadDocumentFrom(inputStorageFileDocument)
-                                                                ];
-                                                            case 1:
-                                                                storageFileDocument = _state.sent();
+                                                                storageFileDocument = storageFileCollection.documentAccessorForTransaction(transaction).loadDocumentFrom(inputStorageFileDocument);
                                                                 return [
                                                                     4,
                                                                     firebaseServer.assertSnapshotData(storageFileDocument)
                                                                 ];
-                                                            case 2:
+                                                            case 1:
                                                                 storageFile = _state.sent();
                                                                 fileAccessor = storageService.file(storageFile);
                                                                 if (!force) {
@@ -9211,7 +9428,7 @@ function _processStorageFileInTransactionFactory(context) {
                                                                         removeAllStorageFileGroups: true
                                                                     }, transaction)
                                                                 ];
-                                                            case 3:
+                                                            case 2:
                                                                 _state.sent();
                                                                 // delete the file
                                                                 return [
@@ -9220,14 +9437,14 @@ function _processStorageFileInTransactionFactory(context) {
                                                                         return null;
                                                                     })
                                                                 ];
-                                                            case 4:
+                                                            case 3:
                                                                 _state.sent();
                                                                 // delete the document
                                                                 return [
                                                                     4,
                                                                     storageFileDocument.accessor.delete()
                                                                 ];
-                                                            case 5:
+                                                            case 4:
                                                                 _state.sent();
                                                                 return [
                                                                     2
@@ -9257,6 +9474,9 @@ function _processStorageFileInTransactionFactory(context) {
  * Generates a signed download URL for a {@link StorageFile}'s associated Cloud Storage file.
  * The URL expires after the configured duration. Supports loading the storage file document
  * by key if not provided directly.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that generates a signed download URL
  */ function downloadStorageFileFactory(context) {
     var storageService = context.storageService, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, storageFileCollection = context.storageFileCollection;
     return firebaseServerActionTransformFunctionFactory(firebase.downloadStorageFileParamsType, function(params) {
@@ -9273,9 +9493,7 @@ function _processStorageFileInTransactionFactory(context) {
                                 switch(_state.label){
                                     case 0:
                                         // if the StorageFileDocument was not provided, set it from the target key
-                                        if (!storageFileDocument) {
-                                            storageFileDocument = storageFileCollection.documentAccessor().loadDocumentForKey(targetStorageFileDocumentKey);
-                                        }
+                                        storageFileDocument !== null && storageFileDocument !== void 0 ? storageFileDocument : storageFileDocument = storageFileCollection.documentAccessor().loadDocumentForKey(targetStorageFileDocumentKey);
                                         return [
                                             4,
                                             firebaseServer.assertSnapshotData(storageFileDocument)
@@ -9293,9 +9511,9 @@ function _processStorageFileInTransactionFactory(context) {
                                             expiresAt: expiresAt,
                                             expiresIn: expiresIn
                                         });
-                                        downloadUrlExpiresAt = expires.getExpirationDate();
+                                        downloadUrlExpiresAt = expires.getExpirationDate(); // always returns a Date when defaultExpiresFromDateToNow and expiresIn are set
                                         // if they're not an admin, limit the expiration to a max of 30 days.
-                                        if (downloadUrlExpiresAt && !asAdmin) {
+                                        if (!asAdmin) {
                                             maxExpirationDate = dateFns.addDays(new Date(), 30);
                                             downloadUrlExpiresAt = date.findMinDate([
                                                 downloadUrlExpiresAt,
@@ -9307,7 +9525,7 @@ function _processStorageFileInTransactionFactory(context) {
                                             Promise.all([
                                                 fileAccessor.getSignedUrl({
                                                     action: 'read',
-                                                    expiresAt: downloadUrlExpiresAt !== null && downloadUrlExpiresAt !== void 0 ? downloadUrlExpiresAt : undefined,
+                                                    expiresAt: downloadUrlExpiresAt,
                                                     responseDisposition: responseDisposition !== null && responseDisposition !== void 0 ? responseDisposition : undefined,
                                                     responseType: asAdmin ? responseContentType !== null && responseContentType !== void 0 ? responseContentType : undefined : undefined // can only be set by admins
                                                 }),
@@ -9345,7 +9563,16 @@ function _processStorageFileInTransactionFactory(context) {
         })();
     });
 }
-function createStorageFileGroupInTransactionFactory(context) {
+/**
+ * Internal factory that creates a function for creating a {@link StorageFileGroup} document
+ * within a Firestore transaction.
+ *
+ * The created group is flagged for initialization (`s=true`) and uses a dummy owner key
+ * that will be set during the initialization step.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that creates a StorageFileGroup within a transaction
+ */ function createStorageFileGroupInTransactionFactory(context) {
     var storageFileGroupCollection = context.storageFileGroupCollection;
     return function(params, transaction) {
         return _async_to_generator$4(function() {
@@ -9391,6 +9618,9 @@ function createStorageFileGroupInTransactionFactory(context) {
  *
  * Creates a new {@link StorageFileGroup} document within a Firestore transaction,
  * associating it with a model key or storage file.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that creates a new StorageFileGroup
  */ function createStorageFileGroupFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var createStorageFileGroupInTransaction = createStorageFileGroupInTransactionFactory(context);
@@ -9399,7 +9629,7 @@ function createStorageFileGroupInTransactionFactory(context) {
             var model, storageFileId, storageFileGroupRelatedModelKey;
             return _ts_generator$4(this, function(_state) {
                 model = params.model, storageFileId = params.storageFileId;
-                storageFileGroupRelatedModelKey = model ? model : storageFileId ? firebase.inferKeyFromTwoWayFlatFirestoreModelKey(storageFileId) : undefined;
+                storageFileGroupRelatedModelKey = model !== null && model !== void 0 ? model : storageFileId ? firebase.inferKeyFromTwoWayFlatFirestoreModelKey(storageFileId) : undefined;
                 if (!storageFileGroupRelatedModelKey) {
                     throw createStorageFileGroupInputError();
                 }
@@ -9407,42 +9637,32 @@ function createStorageFileGroupInTransactionFactory(context) {
                     2,
                     function() {
                         return _async_to_generator$4(function() {
-                            var result;
                             return _ts_generator$4(this, function(_state) {
-                                switch(_state.label){
-                                    case 0:
-                                        return [
-                                            4,
-                                            firestoreContext.runTransaction(function(transaction) {
-                                                return _async_to_generator$4(function() {
-                                                    var storageFileGroupDocument;
-                                                    return _ts_generator$4(this, function(_state) {
-                                                        switch(_state.label){
-                                                            case 0:
-                                                                return [
-                                                                    4,
-                                                                    createStorageFileGroupInTransaction({
-                                                                        storageFileGroupRelatedModelKey: storageFileGroupRelatedModelKey
-                                                                    }, transaction)
-                                                                ];
-                                                            case 1:
-                                                                storageFileGroupDocument = _state.sent().storageFileGroupDocument;
-                                                                return [
-                                                                    2,
-                                                                    storageFileGroupDocument
-                                                                ];
-                                                        }
-                                                    });
-                                                })();
-                                            })
-                                        ];
-                                    case 1:
-                                        result = _state.sent();
-                                        return [
-                                            2,
-                                            result
-                                        ];
-                                }
+                                return [
+                                    2,
+                                    firestoreContext.runTransaction(function(transaction) {
+                                        return _async_to_generator$4(function() {
+                                            var storageFileGroupDocument;
+                                            return _ts_generator$4(this, function(_state) {
+                                                switch(_state.label){
+                                                    case 0:
+                                                        return [
+                                                            4,
+                                                            createStorageFileGroupInTransaction({
+                                                                storageFileGroupRelatedModelKey: storageFileGroupRelatedModelKey
+                                                            }, transaction)
+                                                        ];
+                                                    case 1:
+                                                        storageFileGroupDocument = _state.sent().storageFileGroupDocument;
+                                                        return [
+                                                            2,
+                                                            storageFileGroupDocument
+                                                        ];
+                                                }
+                                            });
+                                        })();
+                                    })
+                                ];
                             });
                         })();
                     }
@@ -9451,12 +9671,21 @@ function createStorageFileGroupInTransactionFactory(context) {
         })();
     });
 }
-function _syncStorageFileWithGroupsInTransactionFactory(context) {
+/**
+ * Internal factory that creates a function for syncing a {@link StorageFile} with its
+ * associated {@link StorageFileGroup} documents within a Firestore transaction.
+ *
+ * Adds the storage file to groups it is missing from, removes it from groups when requested,
+ * and optionally creates new groups for references that do not yet exist.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that syncs a storage file with its groups within a transaction
+ */ function _syncStorageFileWithGroupsInTransactionFactory(context) {
     var storageFileCollection = context.storageFileCollection, storageFileGroupCollection = context.storageFileGroupCollection;
     var createStorageFileGroupInTransaction = createStorageFileGroupInTransactionFactory(context);
     return function(input, transaction) {
         return _async_to_generator$4(function() {
-            var _storageFile_g, storageFileDocument, inputStorageFile, force, removeAllStorageFileGroups, skipStorageFileUpdate, storageFileDocumentInTransaction, storageFileGroupDocumentAccessor, storageFile, _tmp, g, storageFileGroupDocuments, storageFileGroupPairs, storageFilesGroupsCreated, storageFilesGroupsUpdated, result;
+            var storageFileDocument, inputStorageFile, force, removeAllStorageFileGroups, skipStorageFileUpdate, storageFileDocumentInTransaction, storageFileGroupDocumentAccessor, storageFile, _tmp, g, storageFileGroupDocuments, storageFileGroupPairs, storageFilesGroupsCreated, storageFilesGroupsUpdated, result;
             return _ts_generator$4(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -9485,7 +9714,7 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
                         if (!storageFile.gs && !force) {
                             throw storageFileNotFlaggedForGroupsSyncError();
                         }
-                        g = (_storageFile_g = storageFile.g) !== null && _storageFile_g !== void 0 ? _storageFile_g : [];
+                        g = storageFile.g;
                         storageFileGroupDocuments = firebase.loadDocumentsForIds(storageFileGroupDocumentAccessor, g);
                         return [
                             4,
@@ -9519,10 +9748,15 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
                                                             3,
                                                             6
                                                         ];
+                                                    case undefined:
+                                                        return [
+                                                            3,
+                                                            8
+                                                        ];
                                                 }
                                                 return [
                                                     3,
-                                                    8
+                                                    9
                                                 ];
                                             case 1:
                                                 // add it if it doesn't exist
@@ -9569,7 +9803,7 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
                                             case 5:
                                                 return [
                                                     3,
-                                                    8
+                                                    9
                                                 ];
                                             case 6:
                                                 // remove it
@@ -9590,9 +9824,15 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
                                                 storageFilesGroupsUpdated += 1;
                                                 return [
                                                     3,
-                                                    8
+                                                    9
                                                 ];
                                             case 8:
+                                                // no change needed
+                                                return [
+                                                    3,
+                                                    9
+                                                ];
+                                            case 9:
                                                 return [
                                                     2
                                                 ];
@@ -9635,8 +9875,11 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
  *
  * Syncs a single {@link StorageFile}'s embedded data into its associated {@link StorageFileGroup}
  * documents and clears the sync flag on completion.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that syncs a StorageFile with its groups
  */ function syncStorageFileWithGroupsFactory(context) {
-    var firestoreContext = context.firestoreContext; context.storageFileCollection; context.storageFileGroupCollection; var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
+    var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var syncStorageFileWithGroupsInTransaction = _syncStorageFileWithGroupsInTransactionFactory(context);
     return firebaseServerActionTransformFunctionFactory(firebase.syncStorageFileWithGroupsParamsType, function(params) {
         return _async_to_generator$4(function() {
@@ -9678,10 +9921,13 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
  * Batch-processes all {@link StorageFile} documents flagged for group sync,
  * updating their associated {@link StorageFileGroup} documents and flagging
  * groups for content regeneration when changes occur.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch sync results
  */ function syncAllFlaggedStorageFilesWithGroupsFactory(context) {
     var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, storageFileCollection = context.storageFileCollection;
     var syncStorageFileWithGroups = syncStorageFileWithGroupsFactory(context);
-    return firebaseServerActionTransformFunctionFactory(firebase.syncAllFlaggedStorageFilesWithGroupsParamsType, function(params) {
+    return firebaseServerActionTransformFunctionFactory(firebase.syncAllFlaggedStorageFilesWithGroupsParamsType, function(_params) {
         return _async_to_generator$4(function() {
             return _ts_generator$4(this, function(_state) {
                 return [
@@ -9793,6 +10039,9 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
  *
  * Regenerates the content of a single {@link StorageFileGroup}, including building a ZIP
  * archive from the group's embedded files and updating the group's content metadata.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that regenerates a StorageFileGroup's content
  */ function regenerateStorageFileGroupContentFactory(context) {
     var firestoreContext = context.firestoreContext, storageService = context.storageService, storageFileCollection = context.storageFileCollection, storageFileGroupCollection = context.storageFileGroupCollection, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var processStorageFileInTransaction = _processStorageFileInTransactionFactory(context);
@@ -9932,10 +10181,13 @@ function _syncStorageFileWithGroupsInTransactionFactory(context) {
  *
  * Batch-processes all {@link StorageFileGroup} documents flagged for content regeneration,
  * rebuilding their ZIP archives and updating content metadata.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch regeneration results
  */ function regenerateAllFlaggedStorageFileGroupsContentFactory(context) {
     var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, storageFileGroupCollection = context.storageFileGroupCollection;
     var regenerateStorageFileGroupContent = regenerateStorageFileGroupContentFactory(context);
-    return firebaseServerActionTransformFunctionFactory(firebase.regenerateAllFlaggedStorageFileGroupsContentParamsType, function(params) {
+    return firebaseServerActionTransformFunctionFactory(firebase.regenerateAllFlaggedStorageFileGroupsContentParamsType, function(_params) {
         return _async_to_generator$4(function() {
             return _ts_generator$4(this, function(_state) {
                 return [
@@ -10220,6 +10472,7 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
  * initialization action to its factory function.
  *
  * @param context - the initialization context with template function and Firestore access
+ * @returns a {@link StorageFileInitServerActions} wired to the provided context
  */ function storageFileInitServerActions(context) {
     return {
         initializeStorageFileGroup: initializeStorageFileGroupFactory(context),
@@ -10235,6 +10488,7 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
  * - Returns `false` → deletes the document entirely
  *
  * @param input - the document, transaction, template function, and options
+ * @returns an object indicating whether the document was initialized or was already initialized
  * @throws storageFileModelAlreadyInitializedError when `throwErrorIfAlreadyInitialized` is true
  */ function initializeStorageFileModelInTransaction(input) {
     return _async_to_generator$3(function() {
@@ -10336,6 +10590,9 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
  *
  * Applies the app-specific template function, restricting the template to only the `o` (owner)
  * and content flag properties, and always flags the group for content regeneration.
+ *
+ * @param context - the initialization context providing collection access and the template function
+ * @returns an async function that initializes a storage file group document within a transaction
  */ function initializeStorageFileGroupInTransactionFactory(context) {
     var storageFileGroupCollection = context.storageFileGroupCollection, makeTemplateForStorageFileGroupInitialization = context.makeTemplateForStorageFileGroupInitialization;
     return function(params, storageFileGroupDocument, transaction) {
@@ -10396,6 +10653,9 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
  *
  * Wraps the in-transaction group initialization in a Firestore transaction
  * and follows the transform-and-validate pattern.
+ *
+ * @param context - the initialization context with Firestore access and template function
+ * @returns a transform-and-validate function for single storage file group initialization
  */ function initializeStorageFileGroupFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory;
     var initializeStorageFileGroupInTransaction = initializeStorageFileGroupInTransactionFactory(context);
@@ -10436,6 +10696,9 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
  * Batch-processes all {@link StorageFileGroup} documents flagged for initialization,
  * initializing each in parallel (up to 5 concurrent tasks). Loops until no more
  * flagged groups are found.
+ *
+ * @param context - the initialization context with Firestore access, collection, and template function
+ * @returns a transform-and-validate function for batch storage file group initialization
  */ function initializeAllApplicableStorageFileGroupsFactory(context) {
     var firestoreContext = context.firestoreContext, firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, storageFileGroupCollection = context.storageFileGroupCollection;
     var initializeStorageFileGroupInTransaction = initializeStorageFileGroupInTransactionFactory(context);
@@ -10449,7 +10712,7 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
                             var storageFileGroupsVisited, storageFileGroupsSucceeded, storageFileGroupsFailed, storageFileGroupsAlreadyInitialized, initializeStorageFileGroupParams, initializeStorageFileGroupsResults, found, result;
                             function initializeStorageFileGroups() {
                                 return _async_to_generator$3(function() {
-                                    var query, storageFileGroupDocuments, result;
+                                    var query, storageFileGroupDocuments;
                                     return _ts_generator$3(this, function(_state) {
                                         switch(_state.label){
                                             case 0:
@@ -10461,7 +10724,7 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
                                             case 1:
                                                 storageFileGroupDocuments = _state.sent();
                                                 return [
-                                                    4,
+                                                    2,
                                                     util.performAsyncTasks(storageFileGroupDocuments, function(storageFileGroupDocument) {
                                                         return _async_to_generator$3(function() {
                                                             return _ts_generator$3(this, function(_state) {
@@ -10477,12 +10740,6 @@ var MAKE_TEMPLATE_FOR_STORAGEFILE_RELATED_MODEL_INITIALIZATION_FUNCTION_DELETE_R
                                                         maxParallelTasks: 5
                                                     })
                                                 ];
-                                            case 2:
-                                                result = _state.sent();
-                                                return [
-                                                    2,
-                                                    result
-                                                ];
                                         }
                                     });
                                 })();
@@ -10642,6 +10899,10 @@ function _unsupported_iterable_to_array$1(o, minLen) {
 /**
  * Factory that assembles the full {@link StorageFileServerActionsContext} by combining
  * the base context with the upload initialization service.
+ *
+ * @param context - the base server actions context providing Firebase infrastructure
+ * @param storageFileInitializeFromUploadService - the service for initializing storage files from uploads
+ * @returns the fully assembled StorageFileServerActionsContext
  */ function storageFileServerActionsContextFactory(context, storageFileInitializeFromUploadService) {
     return _object_spread_props$2(_object_spread$2({}, context), {
         storageFileInitializeFromUploadService: storageFileInitializeFromUploadService
@@ -10649,12 +10910,19 @@ function _unsupported_iterable_to_array$1(o, minLen) {
 }
 /**
  * Factory that creates a {@link StorageFileServerActions} instance from the assembled context.
+ *
+ * @param context - the fully assembled storage file server actions context
+ * @returns a concrete StorageFileServerActions instance
  */ function storageFileServerActionsFactory(context) {
     return storageFileServerActions(context);
 }
 /**
  * Factory that creates a {@link StorageFileInitServerActions} instance by merging the
  * server actions context with the init-specific configuration.
+ *
+ * @param context - the storage file server actions context
+ * @param storageFileInitServerActionsContextConfig - init-specific configuration with the template function
+ * @returns a concrete StorageFileInitServerActions instance
  */ function storageFileInitServerActionsFactory(context, storageFileInitServerActionsContextConfig) {
     return storageFileInitServerActions(_object_spread$2({}, context, storageFileInitServerActionsContextConfig));
 }
@@ -10668,9 +10936,8 @@ function _unsupported_iterable_to_array$1(o, minLen) {
  *
  * Be sure the class that delares the module using this function also extends AbstractAppStorageFileModule.
  *
- * @param provide
- * @param useFactory
- * @returns
+ * @param config - the module configuration including optional dependency module, imports, exports, and providers
+ * @returns the assembled {@link ModuleMetadata} for the storage file module
  */ function appStorageFileModuleMetadata(config$1) {
     var dependencyModule = config$1.dependencyModule, imports = config$1.imports, exports$1 = config$1.exports, providers = config$1.providers;
     var dependencyModuleImport = dependencyModule ? [
@@ -11134,6 +11401,13 @@ var storageFileProcessingNotificationTaskHandlerDefaultCleanup = function storag
 };
 /**
  * Creates a NotificationTaskServiceTaskHandlerConfig that handles the StorageFileProcessingNotificationTask.
+ *
+ * Builds a subtask-based notification handler that loads the storage file document,
+ * determines its purpose, and dispatches to the appropriate purpose-specific processor.
+ * Includes optional StorageFileGroup processors (e.g., ZIP generation) by default.
+ *
+ * @param config - handler configuration including processors, storage accessor, and Firestore collections
+ * @returns a NotificationTaskServiceTaskHandlerConfig wired for storage file processing
  */ function storageFileProcessingNotificationTaskHandler(config) {
     var inputProcessors = config.processors, storageAccessor = config.storageAccessor, storageFileFirestoreCollections = config.storageFileFirestoreCollections, allStorageFileGroupProcessorConfig = config.allStorageFileGroupProcessorConfig;
     var storageFileDocumentAccessor = storageFileFirestoreCollections.storageFileCollection.documentAccessor();
@@ -11152,16 +11426,11 @@ var storageFileProcessingNotificationTaskHandlerDefaultCleanup = function storag
         subtaskHandlerFunctionName: 'storageFileProcessingNotificationTaskHandler',
         inputFunction: function inputFunction(data) {
             return _async_to_generator$1(function() {
-                var storageFileDocument, loadStorageFile, purpose, storagePath, file, fileDetailsAccessor, input;
+                var storageFileDocument, loadStorageFile, purpose, storagePath, file, fileDetailsAccessor;
                 return _ts_generator$1(this, function(_state) {
                     switch(_state.label){
                         case 0:
-                            return [
-                                4,
-                                storageFileDocumentAccessor.loadDocumentForId(data.storageFile)
-                            ];
-                        case 1:
-                            storageFileDocument = _state.sent();
+                            storageFileDocument = storageFileDocumentAccessor.loadDocumentForId(data.storageFile);
                             loadStorageFile = util.cachedGetter(function() {
                                 return _async_to_generator$1(function() {
                                     var storageFile;
@@ -11185,11 +11454,17 @@ var storageFileProcessingNotificationTaskHandlerDefaultCleanup = function storag
                                     });
                                 })();
                             });
-                            purpose = data === null || data === void 0 ? void 0 : data.p;
-                            if (!!purpose) return [
+                            purpose = data.p;
+                            if (!(// attempt to load the purpose from the storage file, if it exists.
+                            purpose !== null && purpose !== void 0)) return [
+                                3,
+                                1
+                            ];
+                            return [
                                 3,
                                 3
                             ];
+                        case 1:
                             return [
                                 4,
                                 loadStorageFile().then(function(x) {
@@ -11197,7 +11472,6 @@ var storageFileProcessingNotificationTaskHandlerDefaultCleanup = function storag
                                 })
                             ];
                         case 2:
-                            // attempt to load the purpose from the storage file, if it exists.
                             purpose = _state.sent();
                             _state.label = 3;
                         case 3:
@@ -11226,15 +11500,14 @@ var storageFileProcessingNotificationTaskHandlerDefaultCleanup = function storag
                         case 6:
                             file = storageAccessor.file(storagePath);
                             fileDetailsAccessor = makeFileDetailsAccessor(file);
-                            input = {
-                                target: purpose,
-                                loadStorageFile: loadStorageFile,
-                                fileDetailsAccessor: fileDetailsAccessor,
-                                storageFileDocument: storageFileDocument
-                            };
                             return [
                                 2,
-                                input
+                                {
+                                    target: purpose,
+                                    loadStorageFile: loadStorageFile,
+                                    fileDetailsAccessor: fileDetailsAccessor,
+                                    storageFileDocument: storageFileDocument
+                                }
                             ];
                     }
                 });
@@ -11287,7 +11560,12 @@ var storageFileProcessingNotificationTaskHandlerDefaultCleanup = function storag
         processors: processors
     }));
 }
-function allStorageFileGroupStorageFileProcessingPurposeSubtaskProcessors(config) {
+/**
+ * Assembles all built-in StorageFileGroup subtask processors, such as ZIP generation.
+ *
+ * @param config - configuration controlling which group processors to include
+ * @returns an array of subtask processor configs for StorageFileGroup processing purposes
+ */ function allStorageFileGroupStorageFileProcessingPurposeSubtaskProcessors(config) {
     var excludeZipProcessing = config.excludeZipProcessing;
     var processors = [];
     if (!excludeZipProcessing) {
@@ -11295,7 +11573,15 @@ function allStorageFileGroupStorageFileProcessingPurposeSubtaskProcessors(config
     }
     return processors;
 }
-function storageFileGroupZipStorageFileProcessingPurposeSubtaskProcessor(config) {
+/**
+ * Creates the ZIP subtask processor for {@link StorageFileGroup} processing.
+ *
+ * This processor streams all files in the group into a ZIP archive, attaches an info JSON
+ * manifest, and uploads the result to the group's designated storage path.
+ *
+ * @param config - configuration providing Firestore collections, storage accessor, and ZIP options
+ * @returns a subtask processor config targeting the StorageFileGroup ZIP purpose
+ */ function storageFileGroupZipStorageFileProcessingPurposeSubtaskProcessor(config) {
     var _ref;
     var storageFileFirestoreCollections = config.storageFileFirestoreCollections, storageAccessor = config.storageAccessor, zip = config.zip;
     var storageFileCollection = storageFileFirestoreCollections.storageFileCollection, storageFileGroupCollection = storageFileFirestoreCollections.storageFileGroupCollection;
@@ -11425,7 +11711,7 @@ function storageFileGroupZipStorageFileProcessingPurposeSubtaskProcessor(config)
                                         4,
                                         util.performAsyncTasks(storageFileDataPairsToZip, function(storageFileDataPair) {
                                             return _async_to_generator$1(function() {
-                                                var storageFile, storageFileDisplayName, referencesStorageFileGroup, fileAccessor, metadata, fileSlashPathDetails, storageFileGroupEmbeddedFile, embeddedFileNameOverride, nameFromFactory, untypedName, extension, name, fileStream;
+                                                var storageFile, storageFileDisplayName, referencesStorageFileGroup, fileAccessor, metadata, _ref, _ref1, fileSlashPathDetails, storageFileGroupEmbeddedFile, embeddedFileNameOverride, nameFromFactory, untypedName, extension, name, fileStream;
                                                 return _ts_generator$1(this, function(_state) {
                                                     switch(_state.label){
                                                         case 0:
@@ -11436,9 +11722,7 @@ function storageFileGroupZipStorageFileProcessingPurposeSubtaskProcessor(config)
                                                             ];
                                                             storageFileDisplayName = storageFile.n;
                                                             // make sure it references the storage file group
-                                                            referencesStorageFileGroup = storageFile.g.some(function(x) {
-                                                                return x === storageFileGroupId;
-                                                            });
+                                                            referencesStorageFileGroup = storageFile.g.includes(storageFileGroupId);
                                                             if (!referencesStorageFileGroup) return [
                                                                 3,
                                                                 6
@@ -11471,15 +11755,20 @@ function storageFileGroupZipStorageFileProcessingPurposeSubtaskProcessor(config)
                                                             ];
                                                         case 2:
                                                             nameFromFactory = _state.sent();
-                                                            untypedName = nameFromFactory || storageFileDisplayName || embeddedFileNameOverride || fileSlashPathDetails.fileName;
+                                                            untypedName = (_ref = (_ref1 = nameFromFactory !== null && nameFromFactory !== void 0 ? nameFromFactory : storageFileDisplayName) !== null && _ref1 !== void 0 ? _ref1 : embeddedFileNameOverride) !== null && _ref !== void 0 ? _ref : fileSlashPathDetails.fileName;
                                                             if (fileSlashPathDetails.typedFileExtension) {
                                                                 extension = fileSlashPathDetails.typedFileExtension;
                                                             } else if (metadata.contentType) {
                                                                 extension = util.documentFileExtensionForMimeType(metadata.contentType);
                                                             }
                                                             // set the default name if still unset
-                                                            untypedName = untypedName || "sf_".concat(storageFile.id);
+                                                            untypedName = untypedName !== null && untypedName !== void 0 ? untypedName : "sf_".concat(storageFile.id);
                                                             name = extension ? "".concat(untypedName, ".").concat(extension) : untypedName;
+                                                            if (!fileAccessor.getStream) {
+                                                                return [
+                                                                    2
+                                                                ]; // skip files where getStream is not available
+                                                            }
                                                             fileStream = fileAccessor.getStream();
                                                             return [
                                                                 4,
@@ -11830,6 +12119,7 @@ function _ts_generator(thisArg, body) {
  *
  * @param error - the error that caused the permanent failure
  * @param createdFile - optional path to a file that was created before the error and should be deleted
+ * @returns a permanent failure result with the error and optional created file reference
  */ function storageFileInitializeFromUploadServiceInitializerResultPermanentFailure(error, createdFile) {
     return {
         error: error,
@@ -11849,6 +12139,7 @@ function _ts_generator(thisArg, body) {
  * 4. Optionally, previous files for the same purpose/user are flagged for deletion
  *
  * @param config - service configuration including determiners, initializers, and storage references
+ * @returns a {@link StorageFileInitializeFromUploadService} with type detection and upload initialization
  *
  * @example
  * ```ts
@@ -11885,10 +12176,9 @@ function _ts_generator(thisArg, body) {
         }
     });
     var determiner = firebase.combineUploadFileTypeDeterminers(_object_spread({
-        determiners: allDeterminers
-    }, _object_spread({
+        determiners: allDeterminers,
         completeSearchOnFirstMatch: true
-    }, config.combineDeterminersConfig)));
+    }, config.combineDeterminersConfig));
     // validate initializers
     if (validate) {
         var allInitializerTypes = Object.keys(initializers);
@@ -11916,6 +12206,7 @@ function _ts_generator(thisArg, body) {
     return {
         checkFileIsAllowedToBeInitialized: inputCheckFileIsAllowedToBeInitialized !== null && inputCheckFileIsAllowedToBeInitialized !== void 0 ? inputCheckFileIsAllowedToBeInitialized : util.asDecisionFunction(true),
         determineUploadFileType: determineUploadFileType,
+        // eslint-disable-next-line sonarjs/cognitive-complexity
         initializeFromUpload: function initializeFromUpload(input) {
             return _async_to_generator(function() {
                 var determinerResult, resultType, createdFilePath, storageFileDocument, processorError, previousStorageFilesFlaggedForDeletion, fileDetailsAccessor, initializer, initializerResult, error, permanentFailure, createdFile, flagPreviousForDelete, createStorageFileResult, flagPreviousForDeleteResult, _createStorageFileResult_storageFile, p, pg, u, createdFile1, fileMetadata, e, flagForDeleteResult, e1, result;