@dereekb/firebase 13.11.2 → 13.11.4

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

@@ -0,0 +1,82 @@
+import { type Maybe } from '@dereekb/util';
+import { type Transaction, type FirestoreDocumentSnapshotDataPair } from '../../common';
+import { type NotificationBoxDocument, type NotificationFirestoreCollections, type NotificationLoggedEventDayDocument } from './notification';
+import { type NotificationLoggedEventDayId, type NotificationTaskType, type NotificationTemplateType } from './notification.id';
+import { type NotificationItem } from './notification.item';
+/**
+ * Configuration for {@link notificationLoggedEventLoader}.
+ */
+export interface NotificationLoggedEventLoaderConfig {
+    readonly notificationFirestoreCollections: NotificationFirestoreCollections;
+    readonly notificationBox: NotificationBoxDocument;
+    readonly transaction?: Maybe<Transaction>;
+}
+/**
+ * Input for {@link NotificationLoggedEventLoader.getItemsForDayRange}.
+ */
+export interface NotificationLoggedEventLoaderItemsForDayRangeInput {
+    readonly from: Date;
+    readonly to: Date;
+    readonly type?: Maybe<NotificationTemplateType | NotificationTaskType>;
+}
+/**
+ * Per-day result yielded by {@link NotificationLoggedEventLoader.forEachDayInRange}.
+ */
+export interface NotificationLoggedEventLoaderDayResult {
+    readonly dayId: NotificationLoggedEventDayId;
+    readonly items: NotificationItem[];
+}
+/**
+ * Input for {@link NotificationLoggedEventLoader.forEachDayInRange}.
+ */
+export interface NotificationLoggedEventLoaderForEachDayInRangeInput {
+    readonly from: Date;
+    readonly to: Date;
+    readonly type?: Maybe<NotificationTemplateType | NotificationTaskType>;
+    readonly maxParallelTasks?: Maybe<number>;
+    readonly handler: (input: NotificationLoggedEventLoaderDayResult) => Promise<void> | void;
+}
+/**
+ * Cached, range-aware reader for the {@link NotificationLoggedEventDay} archive of a single
+ * {@link NotificationBoxDocument}. Mirrors the pattern of `regionalHeirarchyForRegionalObjectModelKeyLoader`
+ * — request-scoped, deduplicates reads via promise caching, and exposes both per-day and
+ * date-range methods.
+ */
+export interface NotificationLoggedEventLoader {
+    readonly notificationBox: NotificationBoxDocument;
+    /**
+     * Loads (and caches) the {@link NotificationLoggedEventDay} wrapper document for the given day.
+     */
+    getDay(dayId: NotificationLoggedEventDayId): Promise<FirestoreDocumentSnapshotDataPair<NotificationLoggedEventDayDocument>>;
+    /**
+     * Loads (and caches) every archived {@link NotificationItem} for the given day.
+     */
+    getItemsForDay(dayId: NotificationLoggedEventDayId): Promise<NotificationItem[]>;
+    /**
+     * Loads items for the given day, filtered to those whose `t` matches the given type.
+     * Reuses the underlying day cache; no extra Firestore reads.
+     */
+    getItemsForDayWithType(dayId: NotificationLoggedEventDayId, type: NotificationTemplateType | NotificationTaskType): Promise<NotificationItem[]>;
+    /**
+     * Loads items across all days in `[from, to]` (inclusive), optionally filtered by type.
+     * Days with no archive contribute zero items.
+     */
+    getItemsForDayRange(input: NotificationLoggedEventLoaderItemsForDayRangeInput): Promise<NotificationItem[]>;
+    /**
+     * Streams items per-day across `[from, to]` (inclusive). Each day is loaded via the same cache
+     * as the per-day getters and passed to `handler` exactly once. Concurrency is bounded by
+     * `maxParallelTasks` (defaults to unbounded — same as {@link performTasksFromFactoryInParallelFunction}).
+     */
+    forEachDayInRange(input: NotificationLoggedEventLoaderForEachDayInRangeInput): Promise<void>;
+}
+/**
+ * Creates a request-scoped {@link NotificationLoggedEventLoader} that caches both day wrapper
+ * snapshots (via {@link limitedFirestoreDocumentAccessorSnapshotCache}) and the per-day merged
+ * `NotificationItem[]` from the paged subcollection.
+ *
+ * Cache lifetime is the loader instance — create one per request/transaction; do not retain.
+ *
+ * @param config - notification collections, the parent {@link NotificationBoxDocument}, optional transaction.
+ * @returns the cached loader.
+ */
+export declare function notificationLoggedEventLoader(config: NotificationLoggedEventLoaderConfig): NotificationLoggedEventLoader;

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

@@ -280,6 +280,7 @@ export type NotificationMessageFunction = NotificationMessageFunctionWithoutExtr
  *   { globalRecipients: [adminRecipient] }
  * );
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function notificationMessageFunction(fn: NotificationMessageFunctionWithoutExtras, extras?: NotificationMessageFunctionExtras): NotificationMessageFunction;
 /**
@@ -296,5 +297,6 @@ export declare function notificationMessageFunction(fn: NotificationMessageFunct
  * const msg = await msgFn(inputContext);
  * // msg.flag === NotificationMessageFlag.NO_CONTENT
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function noContentNotificationMessageFunctionFactory<D extends NotificationItemMetadata = {}>(): NotificationMessageFunctionFactory<D>;

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

@@ -59,3 +59,20 @@ export declare function notificationsPastSendAtTimeQuery(now?: Date): FirestoreQ
  * @returns array of Firestore query constraints filtering for completed notifications ready to archive
  */
 export declare function notificationsReadyForCleanupQuery(): FirestoreQueryConstraint[];
+/**
+ * Query constraints for finding {@link NotificationLoggedEventDay} documents whose ISO day string
+ * is older than `now - retentionDays`.
+ *
+ * Intended for use against the {@link NotificationLoggedEventDayFirestoreCollectionGroup} during
+ * scheduled retention cleanup. Documents older than the cutoff (and their nested page subcollection
+ * contents) should be deleted.
+ *
+ * Uses the `d` field rather than document ID — Firestore collection-group queries cannot filter on
+ * `FieldPath.documentId()` with a bare day string (it requires a full path). The `d` field stores
+ * the same ISO 8601 day string as the document ID and supports a plain inequality.
+ *
+ * @param retentionDays - number of days of history to retain; days strictly older than `now - retentionDays` match
+ * @param now - reference time for the cutoff (defaults to current time)
+ * @returns array of Firestore query constraints filtering by the day string
+ */
+export declare function notificationLoggedEventDaysOlderThanQuery(retentionDays: number, now?: Date): FirestoreQueryConstraint[];

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

@@ -126,11 +126,22 @@ export interface AllowedNotificationRecipients {
  * @returns an object indicating which recipient groups are permitted for this notification
  */
 export declare function allowedNotificationRecipients(flag?: Maybe<NotificationRecipientSendFlag>): AllowedNotificationRecipients;
+/**
+ * Returns true if the given notification is a logged-event record (`st === LOGGED_EVENT`).
+ *
+ * Logged-event notifications bypass the normal send pipeline entirely and are archived to the
+ * day-keyed {@link NotificationLoggedEventDay} collection during cleanup.
+ *
+ * @param notification - the notification to check
+ * @returns true if the notification has the LOGGED_EVENT send type
+ */
+export declare function isLoggedEventNotification(notification: Pick<Notification, 'st'>): boolean;
 /**
  * Returns true if the notification should be archived to a {@link NotificationWeek} after delivery.
  *
  * Only notifications that can be sent to box recipients are archived (notifications restricted
- * to only explicit or only global recipients are not saved to the weekly archive).
+ * to only explicit or only global recipients are not saved to the weekly archive). Logged-event
+ * notifications are archived to {@link NotificationLoggedEventDay} instead and never to the weekly archive.
  *
  * @param notification - the notification to check
  * @returns true if the notification should be saved to the weekly archive after delivery

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

@@ -16,6 +16,15 @@ export interface UpdateOidcClientFieldParams {
     readonly redirect_uris: OidcRedirectUri[];
     readonly logo_uri?: Maybe<WebsiteUrlWithPrefix>;
     readonly client_uri?: Maybe<WebsiteUrlWithPrefix>;
+    /**
+     * Optional per-client maximum login duration (seconds).
+     *
+     * When set, caps any value the client requests via the `dbx_session_ttl` auth-URL param.
+     * The effective ceiling for that client is `min(this, OidcModuleConfig.maxRequestedLoginDuration)`.
+     *
+     * Set to `null` to clear an existing value.
+     */
+    readonly dbx_max_session_ttl?: Maybe<number>;
 }
 export declare const updateOidcClientFieldParamsType: Type<UpdateOidcClientFieldParams>;
 export declare const createOidcClientFieldParamsType: import("arktype/internal/variants/object.ts").ObjectType<{
@@ -23,6 +32,7 @@ export declare const createOidcClientFieldParamsType: import("arktype/internal/v
     readonly redirect_uris: OidcRedirectUri[];
     readonly logo_uri?: Maybe<string>;
     readonly client_uri?: Maybe<string>;
+    readonly dbx_max_session_ttl?: Maybe<number>;
     token_endpoint_auth_method: "client_secret_basic" | "client_secret_post" | "client_secret_jwt" | "private_key_jwt";
 }, {}>;
 /**
@@ -76,6 +86,17 @@ export type RotateOidcClientSecretResult = Pick<CreateOidcClientResult, 'client_
  */
 export type DeleteOidcClientParams = TargetModelParams;
 export declare const deleteOidcClientParamsType: import("arktype/internal/variants/object.ts").ObjectType<TargetModelParams, {}>;
+/**
+ * Parameters for revoking a user's own OIDC token entry.
+ *
+ * The target {@link OidcEntry} must be of type `Grant` and have its `uid`
+ * matching the authenticated user. Revoking a grant cascades through
+ * oidc-provider's grantable models (`AccessToken`, `RefreshToken`,
+ * `AuthorizationCode`, `DeviceCode`, `BackchannelAuthenticationRequest`),
+ * deleting all entries that share the grant id.
+ */
+export type DeleteOidcTokenParams = TargetModelParams;
+export declare const deleteOidcTokenParamsType: import("arktype/internal/variants/object.ts").ObjectType<TargetModelParams, {}>;
 /**
  * Custom (non-CRUD) function type map for OIDC.
  */
@@ -97,6 +118,7 @@ export type OidcModelCrudFunctionsConfig = {
         };
         delete: {
             client: DeleteOidcClientParams;
+            token: DeleteOidcTokenParams;
         };
     };
 };
@@ -117,6 +139,7 @@ export declare abstract class OidcModelFunctions implements ModelFirebaseFunctio
         };
         deleteOidcEntry: {
             client: ModelFirebaseDeleteFunction<DeleteOidcClientParams>;
+            token: ModelFirebaseDeleteFunction<DeleteOidcTokenParams>;
         };
     };
 }

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

@@ -84,6 +84,13 @@ export interface OidcEntry {
      * @dbxModelVariable grantId
      */
     grantId?: Maybe<string>;
+    /**
+     * OAuth client identifier. Extracted from the payload for indexed queries
+     * (e.g. listing or revoking every grant/token issued to a particular client).
+     *
+     * @dbxModelVariable clientId
+     */
+    clientId?: Maybe<string>;
     /**
      * User code for device flow. Extracted from the payload for indexed queries.
      *
@@ -96,6 +103,17 @@ export interface OidcEntry {
      * @dbxModelVariable consumedAt
      */
     consumed?: Maybe<number>;
+    /**
+     * When this entry was created. Derived from `payload.iat` on grantable
+     * tokens (AccessToken, RefreshToken, AuthorizationCode, Grant, etc.) and
+     * from `payload.created_at` on Client entries.
+     *
+     * Enables Firestore-level `orderBy` and date-range queries (e.g. "grants
+     * issued in the last 7 days") without parsing the payload.
+     *
+     * @dbxModelVariable createdAt
+     */
+    createdAt?: Maybe<Date>;
     /**
      * When this entry expires.
      *

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

@@ -14,4 +14,30 @@ export interface OidcEntryOAuthClientPayloadData {
     readonly logo_uri?: Maybe<string>;
     readonly client_uri?: Maybe<string>;
     readonly created_at?: string;
+    /**
+     * Optional per-client maximum login duration (seconds).
+     *
+     * Custom oidc-provider client metadata (registered via `extraClientMetadata`).
+     * Caps how long a client may request via the `dbx_session_ttl` auth-URL param.
+     */
+    readonly dbx_max_session_ttl?: Maybe<number>;
+}
+/**
+ * Subset of an oidc-provider Grant adapter payload that is safe to expose to the
+ * granting user when they manage their issued tokens.
+ *
+ * Mirrors the relevant fields of oidc-provider's `lib/models/grant.js` payload.
+ */
+export interface OidcEntryGrantPayloadData {
+    readonly accountId?: Maybe<string>;
+    readonly clientId?: Maybe<OidcEntryClientId>;
+    readonly exp?: Maybe<number>;
+    readonly iat?: Maybe<number>;
+    /**
+     * Space-delimited string of scopes that apply across all resources, e.g. `'openid email offline_access'`.
+     */
+    readonly openid?: Maybe<{
+        readonly scope?: Maybe<string>;
+        readonly claims?: Maybe<string[]>;
+    }>;
 }

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

@@ -31,6 +31,14 @@ export declare function oidcEntriesByUidQuery(type: OidcEntryType, uid: Firebase
  * @returns Firestore query constraints for the given type and grantId
  */
 export declare function oidcEntriesByGrantIdQuery(type: OidcEntryType, grantId: string): FirestoreQueryConstraint[];
+/**
+ * Query for OidcEntry documents with a specific type and clientId.
+ *
+ * @param type - the OIDC entry type to filter by
+ * @param clientId - the OAuth client ID to match
+ * @returns Firestore query constraints for the given type and clientId
+ */
+export declare function oidcEntriesByClientIdQuery(type: OidcEntryType, clientId: string): FirestoreQueryConstraint[];
 /**
  * Query for OidcEntry Client documents owned by a specific user.
  *
@@ -38,3 +46,13 @@ export declare function oidcEntriesByGrantIdQuery(type: OidcEntryType, grantId:
  * @returns Firestore query constraints for Client entries matching the ownership key
  */
 export declare function oidcClientEntriesByOwnerQuery(ownershipKey: FirebaseAuthOwnershipKey): FirestoreQueryConstraint[];
+/**
+ * Query for OidcEntry Grant documents issued to a specific user.
+ *
+ * Used by the "apps with access to my account" UI to list every outstanding
+ * grant the signed-in user has authorized.
+ *
+ * @param uid - the Firebase user id the grants were issued to
+ * @returns Firestore query constraints for Grant entries matching the uid
+ */
+export declare function oidcGrantEntriesByUidQuery(uid: FirebaseAuthUserId): FirestoreQueryConstraint[];

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

@@ -188,6 +188,7 @@ export type CreateStorageFileDocumentPairFactory = <M extends StorageFileMetadat
  *   context: collections
  * });
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function createStorageFileDocumentPairFactory(config?: CreateStorageFileDocumentPairFactoryConfig): CreateStorageFileDocumentPairFactory;
 /**

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

@@ -82,6 +82,7 @@ export type StorageFileGroupCreateStorageFileKeyFactory<P extends StorageFileGro
  *
  * @param purpose The purpose of the StorageFileGroupCreatedStorageFileKey.
  * @returns A factory function that takes a StorageFileGroupId and returns a StorageFileGroupCreatedStorageFileKey.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function storageFileGroupCreateStorageFileKeyFactory<P extends StorageFileGroupRelatedStorageFilePurpose>(purpose: P): StorageFileGroupCreateStorageFileKeyFactory<P>;
 /**

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

@@ -68,5 +68,6 @@ export interface StoredFileReader {
  * const reader = factory(storageAccessorFile);
  * const bytes = await reader.loadFileBytes();
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function storedFileReaderFactory(): StoredFileReaderFactory;

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

@@ -44,5 +44,6 @@ export type GrantStorageFileRolesForUserAuthFunction = (input: GrantStorageFileR
  *   rolesForStorageFileOwnershipKey: (key) => ({ read: true })
  * });
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function grantStorageFileRolesForUserAuthFunction<T extends FirebaseModelContext>(config: GrantStorageFileRolesForUserAuthFunctionConfig<T>): GrantStorageFileRolesForUserAuthFunction;

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

@@ -36,6 +36,7 @@ export type UserUploadsFolderSlashPathFactory = FactoryWithRequiredInput<SlashPa
  * const path = factory('user123');
  * // path === '/uploads/u/user123'
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function userUploadsFolderSlashPathFactory(inputBasePath?: Maybe<string>): UserUploadsFolderSlashPathFactory;
 /**
@@ -63,6 +64,7 @@ export interface UserUploadsFolderStoragePathFactoryConfig {
  * const storagePath = factory('user123');
  * // storagePath === { pathString: '/uploads/u/user123', bucketId: 'my-bucket' }
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function userUploadsFolderStoragePathFactory({ bucketId, basePath: inputBasePath }: UserUploadsFolderStoragePathFactoryConfig): UserUploadsFolderStoragePathFactory;
 /**

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

@@ -276,6 +276,7 @@ export type DetermineUserByFolderDeterminerWrapperFunction = (determiner: Upload
  * });
  * const withUser = addUser(myDeterminer);
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function determineUserByFolderWrapperFunction(config: DetermineUserByFolderWrapperFunctionConfig): DetermineUserByFolderDeterminerWrapperFunction;
 /**
@@ -289,6 +290,7 @@ export declare function determineUserByFolderWrapperFunction(config: DetermineUs
  * const addUser = determineUserByUserUploadsFolderWrapperFunction();
  * const withUser = addUser(myDeterminer);
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function determineUserByUserUploadsFolderWrapperFunction(config?: Omit<DetermineUserByFolderWrapperFunctionConfig, 'rootFolder' | 'userFolderPrefix'>): DetermineUserByFolderDeterminerWrapperFunction;
 /**