@dereekb/firebase 13.9.0 → 13.10.0

package/index.cjs.js

@@ -13682,6 +13682,8 @@ function _is_native_reflect_construct$3() {
  * Used by both client and server code to access notification documents.
  *
  * @see `NotificationServerActions` in `@dereekb/firebase-server/model` for server-side action processing
+ *
+ * @dbxModelGroup Notification
  */ var NotificationFirestoreCollections = function NotificationFirestoreCollections() {
     _class_call_check$7(this, NotificationFirestoreCollections);
 };
@@ -16207,6 +16209,8 @@ function _is_native_reflect_construct$2() {
  * Used by both client and server code to access oidc model documents.
  *
  * @see `OidcModelServerActions` in `@dereekb/firebase-server/oidc` for server-side action processing
+ *
+ * @dbxModelGroup OidcModel
  */ var OidcModelFirestoreCollections = function OidcModelFirestoreCollections() {
     _class_call_check$4(this, OidcModelFirestoreCollections);
 };
@@ -16668,6 +16672,8 @@ function _is_native_reflect_construct$1() {
  * Abstract base providing access to StorageFile and StorageFileGroup Firestore collections.
  *
  * Implement this in your app module to wire up the collections for dependency injection.
+ *
+ * @dbxModelGroup StorageFile
  */ var StorageFileFirestoreCollections = function StorageFileFirestoreCollections() {
     _class_call_check$1(this, StorageFileFirestoreCollections);
 };
@@ -18798,6 +18804,8 @@ function _is_native_reflect_construct() {
  * Abstract base providing access to the SystemState Firestore collection.
  *
  * Implement this in your app module to wire up dependency injection.
+ *
+ * @dbxModelGroup SystemState
  */ var SystemStateFirestoreCollections = function SystemStateFirestoreCollections() {
     _class_call_check(this, SystemStateFirestoreCollections);
 };

package/index.esm.js

@@ -13680,6 +13680,8 @@ function _is_native_reflect_construct$3() {
  * Used by both client and server code to access notification documents.
  *
  * @see `NotificationServerActions` in `@dereekb/firebase-server/model` for server-side action processing
+ *
+ * @dbxModelGroup Notification
  */ var NotificationFirestoreCollections = function NotificationFirestoreCollections() {
     _class_call_check$7(this, NotificationFirestoreCollections);
 };
@@ -16205,6 +16207,8 @@ function _is_native_reflect_construct$2() {
  * Used by both client and server code to access oidc model documents.
  *
  * @see `OidcModelServerActions` in `@dereekb/firebase-server/oidc` for server-side action processing
+ *
+ * @dbxModelGroup OidcModel
  */ var OidcModelFirestoreCollections = function OidcModelFirestoreCollections() {
     _class_call_check$4(this, OidcModelFirestoreCollections);
 };
@@ -16666,6 +16670,8 @@ function _is_native_reflect_construct$1() {
  * Abstract base providing access to StorageFile and StorageFileGroup Firestore collections.
  *
  * Implement this in your app module to wire up the collections for dependency injection.
+ *
+ * @dbxModelGroup StorageFile
  */ var StorageFileFirestoreCollections = function StorageFileFirestoreCollections() {
     _class_call_check$1(this, StorageFileFirestoreCollections);
 };
@@ -18796,6 +18802,8 @@ function _is_native_reflect_construct() {
  * Abstract base providing access to the SystemState Firestore collection.
  *
  * Implement this in your app module to wire up dependency injection.
+ *
+ * @dbxModelGroup SystemState
  */ var SystemStateFirestoreCollections = function SystemStateFirestoreCollections() {
     _class_call_check(this, SystemStateFirestoreCollections);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.9.0",
+  "version": "13.10.0",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -17,10 +17,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.9.0",
-    "@dereekb/date": "13.9.0",
-    "@dereekb/model": "13.9.0",
-    "@dereekb/rxjs": "13.9.0",
+    "@dereekb/util": "13.10.0",
+    "@dereekb/date": "13.10.0",
+    "@dereekb/model": "13.10.0",
+    "@dereekb/rxjs": "13.10.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.0.0",

package/src/lib/client/function/function.d.ts

@@ -1,5 +1,10 @@
 /**
  * Key that corresponds with a function on the server.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:functions
  */
 export type FirebaseFunctionKey = string;
 /**

package/src/lib/client/function/function.factory.d.ts

@@ -43,6 +43,11 @@ export type FirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap> = (fun
 export declare function firebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap>(configMap: FirebaseFunctionTypeConfigMap<M>): FirebaseFunctionMapFactory<M>;
 /**
  * String key used to identify a function group in the app-level functions map.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:functions
  */
 export type FirebaseFunctionMapKey = string;
 /**

package/src/lib/client/function/model.function.factory.d.ts

@@ -9,6 +9,11 @@ import { type OnCallCreateModelResult } from '../../common/model/function';
  * String identifier that routes a CRUD request to a specific sub-handler within a model's
  * CRUD function. For example, a model's `update` might have specifiers like `'status'` or `'config'`
  * to target different update behaviors.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:functions
  */
 export type ModelFirebaseCrudFunctionSpecifier = string;
 /**

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

@@ -13,6 +13,11 @@ export declare const FIREBASE_AUTH_PASSWORD_MIN_LENGTH = 6;
 export declare const FIREBASE_AUTH_PASSWORD_MAX_LENGTH = 128;
 /**
  * Unique identifier for a Firebase Authentication user (the `uid` from Firebase Auth).
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:auth
  */
 export type FirebaseAuthUserId = string;
 /**
@@ -25,6 +30,10 @@ export interface FirebaseAuthUserIdRef {
  * Raw encoded JWT for Firebase Auth.
  *
  * Corresponds with IdToken type in Firebase Auth.
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:auth
  */
 export type FirebaseAuthIdToken = string;
 /**
@@ -65,6 +74,11 @@ export interface FirebaseAuthDetails extends FirebaseAuthToken, Readonly<Firebas
  * A string key used to test for ownership of a particular set of objects.
  *
  * For instance, a database model (or its parent) may have an ownership key associated with it that is compared with the user's current claims.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:auth
  */
 export type FirebaseAuthOwnershipKey = string;
 /**

package/src/lib/common/development/function.d.ts

@@ -2,6 +2,11 @@
  * Identifies a specific development function endpoint to route requests to.
  *
  * Used in dev/test environments to invoke specific server-side functions by name.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:functions
  */
 export type DevelopmentFirebaseFunctionSpecifier = string;
 /**

package/src/lib/common/firestore/accessor/document.d.ts

@@ -405,6 +405,14 @@ export declare function firestoreSingleDocumentAccessor<T, D extends FirestoreDo
  * Default document ID used for single-document collections. The document is stored at path `<collection>/0`.
  */
 export declare const DEFAULT_SINGLE_ITEM_FIRESTORE_COLLECTION_DOCUMENT_IDENTIFIER = "0";
+/**
+ * Document ID used for the single document in a single-item Firestore collection.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:firestore
+ */
 export type SingleItemFirestoreCollectionDocumentIdentifier = string;
 export interface SingleItemFirestoreCollectionDocumentIdentifierRef {
     /**

package/src/lib/common/firestore/collection/collection.d.ts

@@ -26,6 +26,11 @@ export type FirestoreModelType = ModelTypeString;
  * with the same name to be returned regardless of their location in the document hierarchy.
  *
  * @example 'u', 'ps', 'or'
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:firestore
  */
 export type FirestoreCollectionName = string;
 /**
@@ -218,6 +223,11 @@ export interface FirestoreModelIdentityRef<I extends FirestoreModelIdentity = Fi
  * Example:
  *
  * 12345
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:firestore
  */
 export type FirestoreModelId = string;
 /**
@@ -431,6 +441,11 @@ export declare function firestoreModelKeyPairObject(input: FirestoreModelKey | D
  * String that is composed of the FirestoreCollectionNames derived from an input FirestoreModelKey and joined together via a separator.
  *
  * Is equivalent to a FirestoreCollectionType if the FIRESTORE_COLLECTION_NAME_SEPARATOR is used as the separator.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:firestore
  */
 export type FirestoreModelCollectionTypeArrayName = string;
 /**

package/src/lib/common/firestore/driver/driver.d.ts

@@ -2,6 +2,11 @@ import { type FirestoreAccessorDriverRef } from './accessor';
 import { type FirestoreQueryDriverRef } from './query';
 /**
  * Optional human-readable identifier for the Firestore driver (e.g., 'firebase-admin', 'firebase-web', 'testing').
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:firestore
  */
 export type FirestoreDriverIdentifier = string;
 /**

package/src/lib/common/firestore/query/constraint.d.ts

@@ -5,6 +5,11 @@ import { type ArrayOrValue, type SeparateResult, type SortingOrder, type Maybe,
  *
  * Used to uniquely identify different types of query constraints, such as
  * where, limit, orderBy, etc.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:firestore
  */
 export type FirestoreQueryConstraintType = string;
 /**

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

@@ -146,6 +146,11 @@ export interface StorageGetAclsResult {
 }
 /**
  * String used as a cursor for iterating pages of file results.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
  */
 export type StorageListFilesPageToken = string;
 export interface StorageListFilesOptions {
@@ -192,6 +197,14 @@ export interface StorageListFileResult extends StorageListItemResult {
      */
     file(): FirebaseStorageAccessorFile;
 }
+/**
+ * Token returned with a list-files result for resuming pagination on the next call.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
+ */
 export type StorageListFileResultNextPageToken = string;
 export interface StorageListFilesResult<R = unknown> {
     /**

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

@@ -1,6 +1,11 @@
 import { type FirebaseStorageAccessorDriverRef } from './accessor';
 /**
  * Unique identifier string for a storage driver implementation.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
  */
 export type FirebaseStorageDriverIdentifier = string;
 /**

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

@@ -3,6 +3,11 @@ import { type SlashPath, type FactoryWithRequiredInput } from '@dereekb/util';
  * Storage bucket identifier for Firebase Cloud Storage.
  *
  * Should contain no slashes — just the bucket name (e.g., `"my-app.appspot.com"`).
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
  */
 export type StorageBucketId = string;
 /**

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

@@ -31,10 +31,20 @@ export type GoogleCloudLikeStorage = {
 export type FirebaseStorage = FirebaseStorageLikeStorage | GoogleCloudLikeStorage;
 /**
  * The public storage url link.
+ *
+ * @semanticType
+ * @semanticTopic url
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
  */
 export type StorageDownloadUrl = string;
 /**
  * A signed download link.
+ *
+ * @semanticType
+ * @semanticTopic url
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
  */
 export type StorageSignedDownloadUrl = string;
 /**
@@ -79,6 +89,10 @@ export interface StorageSignedDownloadUrlConfig {
 /**
  * Example:
  * 'Hello! \\ud83d\\ude0a';
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
  */
 export type StorageRawDataString = string;
 /**
@@ -92,6 +106,11 @@ export type StorageRawDataStringType = 'raw';
 /**
  * Example:
  * '5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
+ * @semanticTopic dereekb-firebase:encoding
  */
 export type StorageBase64DataString = string;
 /**
@@ -104,6 +123,11 @@ export type StorageBase64DataStringType = 'base64';
 /**
  * Example:
  * '5b6p5Y-344GX44G-44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
+ * @semanticTopic dereekb-firebase:encoding
  */
 export type StorageBase64UrlDataString = string;
 /**
@@ -116,6 +140,11 @@ export type StorageBase64UrlDataStringType = 'base64url';
 /**
  * Example:
  * 'data:text/plain;base64,5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB'
+ *
+ * @semanticType
+ * @semanticTopic url
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
  */
 export type StorageDataUrlString = string;
 /**

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

@@ -30,6 +30,8 @@ import { type NotificationItem } from './notification.item';
  * Used by both client and server code to access notification documents.
  *
  * @see `NotificationServerActions` in `@dereekb/firebase-server/model` for server-side action processing
+ *
+ * @dbxModelGroup Notification
  */
 export declare abstract class NotificationFirestoreCollections {
     abstract readonly notificationUserCollection: NotificationUserFirestoreCollection;
@@ -54,6 +56,8 @@ export interface InitializedNotificationModel {
      * True if this model needs to be sync'd/initialized with the original model.
      *
      * Is set false if/when "fi" is set true.
+     *
+     * @dbxModelVariable needsSync
      */
     s?: Maybe<NeedsSyncBoolean>;
     /**
@@ -62,6 +66,8 @@ export interface InitializedNotificationModel {
      * This is for cases where the model cannot be properly initiialized.
      *
      * NOTE: The server can also be configured to automatically delete these models instead of marking them as invalid.
+     *
+     * @dbxModelVariable flaggedInvalid
      */
     fi?: Maybe<SavedToFirestoreIfTrue>;
 }
@@ -79,10 +85,14 @@ export declare const notificationUserIdentity: import("../..").RootFirestoreMode
  *
  * @see {@link NotificationBoxRecipient} for the per-box recipient entry that mirrors these configs
  * @see `NotificationServerActions.updateNotificationUser` in `@dereekb/firebase-server/model` for server-side sync logic
+ *
+ * @dbxModel
  */
 export interface NotificationUser extends UserRelated, UserRelatedById {
     /**
      * Notification box IDs this user is subscribed to. Managed by the server — not directly editable by clients.
+     *
+     * @dbxModelVariable boxes
      */
     b: NotificationBoxId[];
     /**
@@ -93,28 +103,38 @@ export interface NotificationUser extends UserRelated, UserRelatedById {
      * Exclusions are synced to the corresponding `bc` configs, which then propagate to the NotificationBoxes.
      *
      * Non-matching entries (where the user isn't associated with a matching box) are automatically removed.
+     *
+     * @dbxModelVariable boxExclusions
      */
     x: NotificationBoxSendExclusionList;
     /**
      * Global config override. Overrides all other configs (both per-box `bc` and direct/default `dc`) at send time.
      *
      * Unlike `dc`/`bc`, changes to `gc` are NOT copied to other config fields — they apply as a final override during notification delivery.
+     *
+     * @dbxModelVariable globalConfig
      */
     gc: NotificationUserDefaultNotificationBoxRecipientConfig;
     /**
      * Direct/default config. Used when a recipient is added ad-hoc (by uid) to a notification that isn't associated with any of their subscribed boxes.
      *
      * Acts as the fallback config when no per-box config (`bc`) matches.
+     *
+     * @dbxModelVariable defaultConfig
      */
     dc: NotificationUserDefaultNotificationBoxRecipientConfig;
     /**
      * Per-box recipient configurations. Each entry corresponds to one of the user's subscribed notification boxes.
      *
      * These configs are synced bidirectionally with the {@link NotificationBoxRecipient} entries on the corresponding {@link NotificationBox}.
+     *
+     * @dbxModelVariable boxConfigs
      */
     bc: NotificationUserNotificationBoxRecipientConfig[];
     /**
      * Whether one or more configs need to be synced to their corresponding NotificationBox recipients.
+     *
+     * @dbxModelVariable needsConfigSync
      */
     ns?: Maybe<NeedsSyncBoolean>;
 }
@@ -168,34 +188,50 @@ export declare const NOTIFICATION_SUMMARY_EMBEDDED_NOTIFICATION_ITEM_MESSAGE_MAX
  * Items are capped at {@link NOTIFICATION_SUMMARY_ITEM_LIMIT} entries.
  *
  * Implements {@link InitializedNotificationModel} — requires server-side initialization to populate the owner (`o`) field.
+ *
+ * @dbxModel
  */
 export interface NotificationSummary extends InitializedNotificationModel {
     /**
      * Creation date of this summary document.
+     *
+     * @dbxModelVariable createdAt
      */
     cat: Date;
     /**
      * Model key of the model this summary represents (e.g., `'project/abc123'`).
+     *
+     * @dbxModelVariable modelKey
      */
     m: FirestoreModelKey;
     /**
      * Owner model key. Set to a dummy value on creation and populated during server-side initialization.
+     *
+     * @dbxModelVariable ownerKey
      */
     o: FirestoreModelKey;
     /**
      * Embedded notification items, sorted ascending by date (newest at end).
+     *
+     * @dbxModelVariable notifications
      */
     n: NotificationItem[];
     /**
      * Timestamp of the most recently added notification item.
+     *
+     * @dbxModelVariable lastNotificationAt
      */
     lat?: Maybe<Date>;
     /**
      * Timestamp of when the user last read this summary. Items with dates after this are considered unread.
+     *
+     * @dbxModelVariable lastReadAt
      */
     rat?: Maybe<Date>;
     /**
      * Whether this summary needs server-side sync/initialization with its source model.
+     *
+     * @dbxModelVariable needsSync
      */
     s?: Maybe<NeedsSyncBoolean>;
 }
@@ -246,39 +282,55 @@ export declare const notificationBoxIdentity: import("../..").RootFirestoreModel
  *
  * @see {@link NotificationBoxRecipient} for per-recipient configuration embedded in this document
  * @see `NotificationServerActions.createNotificationBox` in `@dereekb/firebase-server/model` for creation logic
+ *
+ * @dbxModel
  */
 export interface NotificationBox extends InitializedNotificationModel {
     /**
      * Creation date of this NotificationBox document.
+     *
+     * @dbxModelVariable createdAt
      */
     cat: Date;
     /**
      * Model key of the model this box is assigned to (e.g., `'project/abc123'`).
+     *
+     * @dbxModelVariable modelKey
      */
     m: FirestoreModelKey;
     /**
      * Owner model key. Set to a dummy value on creation and populated during server-side initialization.
+     *
+     * @dbxModelVariable ownerKey
      */
     o: FirestoreModelKey;
     /**
      * Embedded recipient entries. Each entry represents a user who can receive notifications from this box.
      *
      * Synced from the corresponding {@link NotificationUser} `bc` configs.
+     *
+     * @dbxModelVariable recipients
      */
     r: NotificationBoxRecipient[];
     /**
      * Year-week code of the latest {@link NotificationWeek} subcollection document.
+     *
+     * @dbxModelVariable latestWeek
      */
     w: YearWeekCode;
     /**
      * Whether this box needs server-side sync/initialization with its source model.
      * Cleared when `fi` is set true (flagged invalid).
+     *
+     * @dbxModelVariable needsSync
      */
     s?: Maybe<NeedsSyncBoolean>;
     /**
      * Flagged invalid — set when the box cannot be properly initialized (e.g., source model deleted).
      *
      * The server can be configured to either flag or auto-delete invalid boxes.
+     *
+     * @dbxModelVariable flaggedInvalid
      */
     fi?: Maybe<SavedToFirestoreIfTrue>;
 }
@@ -426,27 +478,42 @@ export declare enum NotificationRecipientSendFlag {
 export interface NotificationSendFlags {
     /**
      * Text/SMS send state.
+     *
+     * @dbxModelVariable textSendState
      */
     ts: NotificationSendState;
     /**
      * Email send state.
+     *
+     * @dbxModelVariable emailSendState
      */
     es: NotificationSendState;
     /**
      * Push notification send state.
+     *
+     * @dbxModelVariable pushSendState
      */
     ps: NotificationSendState;
     /**
      * In-app notification summary send state (delivery to {@link NotificationSummary}).
+     *
+     * @dbxModelVariable summarySendState
      */
     ns: NotificationSendState;
     /**
      * Recipient send flag controlling who receives this notification and whether it should be archived to {@link NotificationWeek} after delivery.
+     *
+     * @dbxModelVariable recipientSendFlag
      */
     rf?: Maybe<NotificationRecipientSendFlag>;
 }
 /**
  * Arbitrary unique string that denotes checkpoint progress for a multi-step task.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:notification
  */
 export type NotificationTaskCheckpointString = string;
 /**
@@ -458,16 +525,22 @@ export type NotificationTaskCheckpointString = string;
 export interface NotificationSendCheckpoints {
     /**
      * Phone numbers that have already received the text/SMS for this notification.
+     *
+     * @dbxModelVariable textRecipients
      */
     tsr: E164PhoneNumber[];
     /**
      * Email addresses that have already received the email for this notification.
+     *
+     * @dbxModelVariable emailRecipients
      */
     esr: EmailAddress[];
     /**
      * Completed checkpoint strings for multi-step task notifications.
      *
      * @see {@link NotificationTaskCheckpointString}
+     *
+     * @dbxModelVariable taskCheckpoints
      */
     tpr: NotificationTaskCheckpointString[];
 }
@@ -484,18 +557,26 @@ export interface NotificationSendCheckpoints {
  * @see {@link NotificationSendFlags} for per-channel delivery state
  * @see {@link NotificationSendCheckpoints} for idempotent retry tracking
  * @see `NotificationServerActions.sendQueuedNotifications` in `@dereekb/firebase-server/model` for the send pipeline
+ *
+ * @dbxModel
  */
 export interface Notification extends NotificationSendFlags, NotificationSendCheckpoints {
     /**
      * Creation timestamp.
+     *
+     * @dbxModelVariable createdAt
      */
     cat: Date;
     /**
      * Send type controlling how this notification interacts with its parent NotificationBox.
+     *
+     * @dbxModelVariable sendType
      */
     st: NotificationSendType;
     /**
      * Embedded notification content (subject, message, template type, metadata).
+     *
+     * @dbxModelVariable notificationItem
      */
     n: NotificationItem;
     /**
@@ -504,12 +585,16 @@ export interface Notification extends NotificationSendFlags, NotificationSendChe
      * Any `NotificationBoxRecipientTemplateConfig` values on these recipients affect opt-in/opt-out resolution.
      * For example, setting `st: true` opts a user into text/SMS for this notification's template type,
      * unless overridden by the user's own {@link NotificationUser} config.
+     *
+     * @dbxModelVariable recipients
      */
     r: NotificationRecipientWithConfig[];
     /**
      * Explicit opt-in send only. When true, only sends to users who have explicitly opted in for each channel.
      *
      * Overrides the system-level default for this notification's template type.
+     *
+     * @dbxModelVariable optInSendOnly
      */
     ois?: Maybe<SavedToFirestoreIfTrue>;
     /**
@@ -517,6 +602,8 @@ export interface Notification extends NotificationSendFlags, NotificationSendChe
      * (still respects explicit opt-outs).
      *
      * Overrides the system-level default for this notification's template type.
+     *
+     * @dbxModelVariable optInTextSend
      */
     ots?: Maybe<SavedToFirestoreIfFalse>;
     /**
@@ -524,22 +611,30 @@ export interface Notification extends NotificationSendFlags, NotificationSendChe
      *
      * Also serves as a lock mechanism: during active sending, `sat` is pushed forward by a few minutes
      * and the attempt counter is incremented, preventing concurrent send attempts.
+     *
+     * @dbxModelVariable sendAt
      */
     sat: Date;
     /**
      * Total error attempt count. Incremented only when sending encounters an error (not on success).
+     *
+     * @dbxModelVariable attempts
      */
     a: number;
     /**
      * Current task attempt count for the active checkpoint. Incremented on delay or failure responses.
      *
      * Reset to 0 when a checkpoint completes successfully or when a new checkpoint begins.
+     *
+     * @dbxModelVariable taskAttempts
      */
     at?: Maybe<number>;
     /**
      * Delivery complete flag. When true, content has been delivered and is ready to archive to {@link NotificationWeek}.
      *
      * For task-type notifications this is always false — tasks are deleted upon completion instead of archived.
+     *
+     * @dbxModelVariable done
      */
     d: boolean;
     /**
@@ -548,6 +643,8 @@ export interface Notification extends NotificationSendFlags, NotificationSendChe
      * When true, the server re-reads the document and compares `cat` before committing a task step.
      * If `cat` has changed (indicating the task was replaced), the step is abandoned silently.
      * This prevents stale task executions when a unique task ID is reused.
+     *
+     * @dbxModelVariable uniqueTask
      */
     ut?: Maybe<SavedToFirestoreIfTrue>;
 }
@@ -615,14 +712,20 @@ export declare const NOTIFICATION_WEEK_NOTIFICATION_ITEM_LIMIT = 5000;
  * a {@link Notification} completes delivery and is cleaned up. Capped at {@link NOTIFICATION_WEEK_NOTIFICATION_ITEM_LIMIT} items.
  *
  * Used for historical browsing of past notifications per box.
+ *
+ * @dbxModel
  */
 export interface NotificationWeek {
     /**
      * Year-week code identifying this week. Matches the document ID.
+     *
+     * @dbxModelVariable yearWeek
      */
     w: YearWeekCode;
     /**
      * Archived notification items delivered during this week.
+     *
+     * @dbxModelVariable notifications
      */
     n: NotificationItem[];
 }

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

@@ -150,12 +150,22 @@ export declare const DEFAULT_NOTIFICATION_TASK_NOTIFICATION_MODEL_KEY: Firestore
  * Types are generally intended to be handled case-insensitively by notification services.
  *
  * Ideally type values are shorter to reduce database size impact.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:notification
  */
 export type NotificationTemplateType = string;
 /**
  * Task type identifier of the notification, which is used to pass this task to the appropriate handler.
  *
  * Ideally type values are shorter to reduce database size impact.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:notification
  */
 export type NotificationTaskType = string;
 /**

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

@@ -27,10 +27,20 @@ export interface NotificationMessageInputContext {
  * Arbitrary key used by the sending configuration service for choosing a pre-configured entity.
  *
  * Typically used for customizing the "from" or "replyTo" addresses while maintaining a separation of concerns.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:notification
  */
 export type NotificationMessageEntityKey = string;
 /**
  * Arbitrary template name/key that is used to configure which template to use by the sending service.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:notification
  */
 export type NotificationSendMessageTemplateName = string;
 /**

package/src/lib/model/notification/notification.task.subtask.d.ts

@@ -15,6 +15,10 @@ import { type NotificationItemMetadata } from './notification.item';
 import { type NotificationTaskServiceHandleNotificationTaskResult } from './notification.task';
 /**
  * Discriminator string that routes the subtask to the correct processing configuration.
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:notification
  */
 export type NotificationTaskSubtaskTarget = string;
 /**

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

@@ -12,6 +12,8 @@ export type OidcModelTypes = typeof oidcEntryIdentity;
  * Used by both client and server code to access oidc model documents.
  *
  * @see `OidcModelServerActions` in `@dereekb/firebase-server/oidc` for server-side action processing
+ *
+ * @dbxModelGroup OidcModel
  */
 export declare abstract class OidcModelFirestoreCollections {
     abstract readonly oidcEntryCollection: OidcEntryFirestoreCollection;
@@ -42,10 +44,14 @@ export declare const OIDC_ENTRY_CLIENT_TYPE: OidcEntryType;
  *
  * The {@link o} ownership field enables Firestore security rules to restrict reads to the owning user
  * (used primarily for Client entries so users can query their own registered OAuth clients).
+ *
+ * @dbxModel
  */
 export interface OidcEntry {
     /**
      * The oidc-provider model type (e.g., 'Session', 'AccessToken', 'Client').
+     *
+     * @dbxModelVariable type
      */
     type: OidcEntryType;
     /**
@@ -53,6 +59,8 @@ export interface OidcEntry {
      *
      * The payload structure varies by model type. Sensitive fields may be
      * selectively encrypted (prefixed with `$`) when encryption is configured.
+     *
+     * @dbxModelVariable payload
      */
     payload: JsonSerializableObject;
     /**
@@ -60,26 +68,38 @@ export interface OidcEntry {
      *
      * Set to the Firebase Auth UID of the user who created this entry.
      * Used primarily on Client entries to allow users to query their own OAuth clients.
+     *
+     * @dbxModelVariable ownerKey
      */
     o?: Maybe<FirebaseAuthOwnershipKey>;
     /**
      * User identifier. Extracted from the payload for indexed queries.
+     *
+     * @dbxModelVariable uid
      */
     uid?: Maybe<FirebaseAuthUserId>;
     /**
      * Grant identifier for revocation support. Extracted from the payload for indexed queries.
+     *
+     * @dbxModelVariable grantId
      */
     grantId?: Maybe<string>;
     /**
      * User code for device flow. Extracted from the payload for indexed queries.
+     *
+     * @dbxModelVariable userCode
      */
     userCode?: Maybe<string>;
     /**
      * Epoch timestamp when this entry was consumed. Extracted from the payload for indexed queries.
+     *
+     * @dbxModelVariable consumedAt
      */
     consumed?: Maybe<number>;
     /**
      * When this entry expires.
+     *
+     * @dbxModelVariable expiresAt
      */
     expiresAt?: Maybe<Date>;
 }

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

@@ -14,5 +14,10 @@ export type OidcEntryId = FirestoreModelId;
 export type OidcEntryKey = FirestoreModelKey;
 /**
  * Unique client identifier for an OIDC client registration.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:oidc
  */
 export type OidcEntryClientId = string;

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

@@ -5,6 +5,11 @@ import { type LabeledValue, type LabeledValueWithDescription } from '@dereekb/ut
  * Generated by the provider when user interaction is needed (login/consent).
  * Used to look up the interaction session via cookies and to build
  * backend interaction endpoint URLs (e.g., `/interaction/${uid}/login`).
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:oidc
  */
 export type OidcInteractionUid = string;
 /**
@@ -17,6 +22,10 @@ export type OidcInteractionUid = string;
  * ```typescript
  * type MyScopes = 'openid' | 'profile' | 'email';
  * ```
+ *
+ * @semanticType
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:oidc
  */
 export type OidcScope = string;
 /**
@@ -27,6 +36,11 @@ export type OidcScopeDetails<T extends OidcScope = OidcScope> = LabeledValueWith
  * A redirect URI registered to an OIDC client.
  *
  * Must be a valid absolute URL (e.g. `https://myapp.example.com/callback`).
+ *
+ * @semanticType
+ * @semanticTopic url
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:oidc
  */
 export type OidcRedirectUri = string;
 /**

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

@@ -22,6 +22,8 @@ import { type NotificationKey } from '../notification';
  * Abstract base providing access to StorageFile and StorageFileGroup Firestore collections.
  *
  * Implement this in your app module to wire up the collections for dependency injection.
+ *
+ * @dbxModelGroup StorageFile
  */
 export declare abstract class StorageFileFirestoreCollections {
     abstract readonly storageFileCollection: StorageFileFirestoreCollection;
@@ -41,6 +43,8 @@ export interface InitializedStorageFileModel {
      * True if this model needs to be sync'd/initialized with the original model.
      *
      * Is set false if/when "fi" is set true.
+     *
+     * @dbxModelVariable needsSync
      */
     s?: Maybe<NeedsSyncBoolean>;
     /**
@@ -49,6 +53,8 @@ export interface InitializedStorageFileModel {
      * This is for cases where the model cannot be properly initiialized.
      *
      * Typically this results in this model and related data being deleted.
+     *
+     * @dbxModelVariable flaggedInvalid
      */
     fi?: Maybe<SavedToFirestoreIfTrue>;
 }
@@ -254,10 +260,13 @@ export type StorageFileDownloadUrl = StorageFilePublicDownloadUrl | StorageFileS
  * `StorageFileActionServerActions` in `@dereekb/firebase-server/model`.
  *
  * @template M - type of the arbitrary metadata stored in the `d` field
+ * @dbxModel
  */
 export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata> extends StoragePath {
     /**
      * Created at date.
+     *
+     * @dbxModelVariable createdAt
      */
     cat: Date;
     /**
@@ -265,14 +274,20 @@ export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata
      *
      * This name is used in StorageFileGroup composite file generations, instead
      * of the file's normal path file name, if available.
+     *
+     * @dbxModelVariable displayName
      */
     n?: Maybe<StorageFileDisplayName>;
     /**
      * Type of creation.
+     *
+     * @dbxModelVariable creationType
      */
     ct?: Maybe<StorageFileCreationType>;
     /**
      * State of the storage file.
+     *
+     * @dbxModelVariable fileState
      */
     fs: StorageFileState;
     /**
@@ -281,6 +296,8 @@ export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata
      * The state is important for managing the processing of the StorageFile.
      *
      * Once processing is finished, the state determines whether or not the StorageFile can be processed again.
+     *
+     * @dbxModelVariable processingState
      */
     ps: StorageFileProcessingState;
     /**
@@ -289,50 +306,70 @@ export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata
      * Set only if the StorageFile has an associated NotificationTask.
      *
      * Cleared once the processing stage is no longer PROCESSING.
+     *
+     * @dbxModelVariable processingNotificationKey
      */
     pn?: Maybe<NotificationKey>;
     /**
      * The date that state was last updated to PROCESSING.
      *
      * Is used as a way to track if processing should be checked on.
+     *
+     * @dbxModelVariable processingAt
      */
     pat?: Maybe<Date>;
     /**
      * The date that the cleanup step of the processing task was run, and the notification ended.
+     *
+     * @dbxModelVariable processingCleanupAt
      */
     pcat?: Maybe<Date>;
     /**
      * User this file is associated with, if applicable.
+     *
+     * @dbxModelVariable userId
      */
     u?: Maybe<FirebaseAuthUserId>;
     /**
      * User who uploaded this file, if applicable.
+     *
+     * @dbxModelVariable uploadedBy
      */
     uby?: Maybe<FirebaseAuthUserId>;
     /**
      * Ownership key, if applicable.
+     *
+     * @dbxModelVariable ownerKey
      */
     o?: Maybe<FirebaseAuthOwnershipKey>;
     /**
      * Purpose of the file, if applicable.
      *
      * Is required for processing a StorageFile.
+     *
+     * @dbxModelVariable purpose
      */
     p?: Maybe<StorageFilePurpose>;
     /**
      * Subgroup of the purpose of the file, if applicable.
      *
      * If a StorageFilePurpose should have subgroups, then all StorageFiles should have subgroups too.
+     *
+     * @dbxModelVariable purposeSubgroup
      */
     pg?: Maybe<StorageFilePurposeSubgroup>;
     /**
      * Arbitrary metadata attached to the StorageFile.
+     *
+     * @dbxModelVariable data
      */
     d?: Maybe<M>;
     /**
      * Scheduled delete at date. The StorageFile cannot be deleted before this set time.
      *
      * Is the main trigger for determining a StorageFile should be deleted.
+     *
+     * @dbxModelVariable scheduledDeleteAt
      */
     sdat?: Maybe<Date>;
     /**
@@ -346,10 +383,14 @@ export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata
      * but there is no gurantee about timeliness when this will happen. StorageFiles, when deleted, are removed from StorageFileGroups immediately, which are flagged for another regeneration automatically.
      *
      * In cases where you need to have the StorageFileGroup be updated promptly, you should manually handle those cases.
+     *
+     * @dbxModelVariable groupIds
      */
     g: StorageFileGroupId[];
     /**
      * If true, this file should be re-synced with each StorageFileGroup that it references.
+     *
+     * @dbxModelVariable groupsNeedSync
      */
     gs?: Maybe<NeedsSyncBoolean>;
 }
@@ -416,20 +457,28 @@ export declare const storageFileGroupIdentity: import("../..").RootFirestoreMode
  */
 export interface StorageFileGroupEmbeddedFile {
     /**
-     * StorageFile id
+     * StorageFile id.
+     *
+     * @dbxModelVariable storageFileId
      */
     s: StorageFileId;
     /**
      * Overrides the display name for this file within the group when generating
      * a composite file (zip, etc.).
+     *
+     * @dbxModelVariable displayName
      */
     n?: Maybe<StorageFileDisplayName>;
     /**
      * The time number it was added to the group.
+     *
+     * @dbxModelVariable addedAt
      */
     sat: Date;
     /**
      * The first time the StorageFile's file was added to the zip, if applicable.
+     *
+     * @dbxModelVariable zippedAt
      */
     zat?: Maybe<Date>;
 }
@@ -447,42 +496,60 @@ export declare const storageFileGroupEmbeddedFile: import("../..").FirestoreSubO
  *
  * Implements {@link InitializedStorageFileModel} for async initialization tracking —
  * the `s` (needs sync) flag is set on creation and cleared once initialized.
+ *
+ * @dbxModel
  */
 export interface StorageFileGroup extends InitializedStorageFileModel {
     /**
      * List of embedded files in this group currently.
+     *
+     * @dbxModelVariable files
      */
     f: StorageFileGroupEmbeddedFile[];
     /**
      * Created at date.
+     *
+     * @dbxModelVariable createdAt
      */
     cat: Date;
     /**
      * Ownership key, if applicable.
+     *
+     * @dbxModelVariable ownerKey
      */
     o?: Maybe<FirebaseAuthOwnershipKey>;
     /**
      * True if a zip file should be generated for this group.
      *
      * This should remain true while a zip file
+     *
+     * @dbxModelVariable shouldZip
      */
     z?: Maybe<SavedToFirestoreIfTrue>;
     /**
      * StorageFile that contains the zip file for this group.
+     *
+     * @dbxModelVariable zipStorageFileId
      */
     zsf?: Maybe<StorageFileId>;
     /**
      * The last date the zip file was regenerated for this group.
+     *
+     * @dbxModelVariable zippedAt
      */
     zat?: Maybe<Date>;
     /**
      * True if this StorageFileGroup should flag regeneration of output StorageFiles/content.
+     *
+     * @dbxModelVariable shouldRegenerate
      */
     re?: Maybe<SavedToFirestoreIfTrue>;
     /**
      * True if this StorageFileGroup should clean up file references.
      *
      * This cleanup process will occur during the next regeneration.
+     *
+     * @dbxModelVariable shouldCleanup
      */
     c?: Maybe<SavedToFirestoreIfTrue>;
 }

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

@@ -26,6 +26,11 @@ export type StorageFileKey = FirestoreModelKey;
  * set on files that do not get processed.
  *
  * Can be used for querying.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage-file
  */
 export type StorageFilePurpose = string;
 /**
@@ -34,6 +39,11 @@ export type StorageFilePurpose = string;
  * This is useful for being able to query StorageFiles that have a specific purpose and purpose subgroup.
  *
  * Example use case: Documents with the same StorageFilePurpose/processing, but should only have a single StorageFile per subgroup.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage-file
  */
 export type StorageFilePurposeSubgroup = string;
 /**

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

@@ -75,6 +75,11 @@ export declare function userUploadsFolderStoragePathFactory({ bucketId, basePath
  * - folder name: A specific folder name (e.g. 'photos' in 'photos/12345.png')
  * - metadata: specific metadata value in the uploaded file's custom metadata
  * - data: specific data in the uploaded file
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage-file
  */
 export type UploadedFileTypeIdentifier = string;
 /**

package/src/lib/model/storagefile/storagefile.upload.determiner.d.ts

@@ -33,6 +33,10 @@ import { type StoredFileReader } from './storagefile.file';
  * it is processed properly.
  *
  * In the ideal case there generally shouldn't be two determiners that could potentially match the same file.
+ *
+ * @semanticType
+ * @semanticTopic numeric
+ * @semanticTopic dereekb-firebase:storage-file
  */
 export type UploadedFileTypeDeterminationLevel = number;
 /**

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

@@ -20,6 +20,8 @@ import { type ModelFieldMapFunctionsConfig } from '@dereekb/util';
  * Abstract base providing access to the SystemState Firestore collection.
  *
  * Implement this in your app module to wire up dependency injection.
+ *
+ * @dbxModelGroup SystemState
  */
 export declare abstract class SystemStateFirestoreCollections {
     abstract readonly systemStateCollection: SystemStateFirestoreCollection;
@@ -34,6 +36,11 @@ export type SystemStateTypes = typeof systemStateIdentity;
 export declare const systemStateIdentity: import("../..").RootFirestoreModelIdentity<"systemState", "sys">;
 /**
  * Used to identify a SystemStateId.
+ *
+ * @semanticType
+ * @semanticTopic identifier
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:system-state
  */
 export type SystemStateTypeIdentifier = string;
 /**
@@ -52,8 +59,14 @@ export type SystemStateStoredData = Record<string, any>;
  * or any system-wide state that needs persistence.
  *
  * @template T - shape of the stored data record
+ * @dbxModel
  */
 export interface SystemState<T extends SystemStateStoredData = SystemStateStoredData> {
+    /**
+     * Arbitrary persisted data for this system state singleton.
+     *
+     * @dbxModelVariable data
+     */
     data: T;
 }
 /**

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.9.0",
+  "version": "13.10.0",
   "peerDependencies": {
-    "@dereekb/date": "13.9.0",
-    "@dereekb/firebase": "13.9.0",
-    "@dereekb/model": "13.9.0",
-    "@dereekb/rxjs": "13.9.0",
-    "@dereekb/util": "13.9.0",
+    "@dereekb/date": "13.10.0",
+    "@dereekb/firebase": "13.10.0",
+    "@dereekb/model": "13.10.0",
+    "@dereekb/rxjs": "13.10.0",
+    "@dereekb/util": "13.10.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.0.0",
     "firebase": "^12.12.0",