@dereekb/firebase 13.9.0 → 13.10.1

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.api.d.ts

@@ -69,13 +69,13 @@ export interface UpdateOidcClientParams extends UpdateOidcClientFieldParams, Tar
 }
 export declare const updateOidcClientParamsType: Type<UpdateOidcClientParams>;
 export type RotateOidcClientSecretParams = TargetModelParams;
-export declare const rotateOidcClientSecretParamsType: Type<RotateOidcClientSecretParams>;
+export declare const rotateOidcClientSecretParamsType: import("arktype/internal/variants/object.ts").ObjectType<TargetModelParams, {}>;
 export type RotateOidcClientSecretResult = Pick<CreateOidcClientResult, 'client_id' | 'client_secret'>;
 /**
  * Parameters for revoking/deleting an OAuth client.
  */
 export type DeleteOidcClientParams = TargetModelParams;
-export declare const deleteOidcClientParamsType: Type<DeleteOidcClientParams>;
+export declare const deleteOidcClientParamsType: import("arktype/internal/variants/object.ts").ObjectType<TargetModelParams, {}>;
 /**
  * Custom (non-CRUD) function type map for OIDC.
  */

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;
@@ -27,7 +29,7 @@ export declare const oidcEntryIdentity: import("../..").RootFirestoreModelIdenti
  *
  * Used as the discriminator in the {@link OidcEntry.type} field.
  */
-export type OidcEntryType = 'Session' | 'AccessToken' | 'AuthorizationCode' | 'RefreshToken' | 'DeviceCode' | 'ClientCredentials' | 'Client' | 'InitialAccessToken' | 'RegistrationAccessToken' | 'Interaction' | 'ReplayDetection' | 'PushedAuthorizationRequest' | 'Grant' | 'BackchannelAuthenticationRequest' | string;
+export type OidcEntryType = 'Session' | 'AccessToken' | 'AuthorizationCode' | 'RefreshToken' | 'DeviceCode' | 'ClientCredentials' | 'Client' | 'InitialAccessToken' | 'RegistrationAccessToken' | 'Interaction' | 'ReplayDetection' | 'PushedAuthorizationRequest' | 'Grant' | 'BackchannelAuthenticationRequest' | (string & {});
 /**
  * Type value for Client adapter entries.
  */
@@ -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;
 /**