@dereekb/firebase 13.36.0 → 13.38.0

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

@@ -105,10 +105,15 @@ export declare abstract class AbstractFirestoreDocument<T, D extends AbstractFir
      */
     snapshot(): Promise<DocumentSnapshot<T>>;
     /**
-     * Retrieves the data of the document, checking the cache first.
+     * Retrieves the data of the document, always fetching from Firestore.
      *
-     * If a fresh cache entry exists, returns it without hitting Firestore.
-     * Otherwise falls through to {@link snapshot} which populates the cache.
+     * Delegates to {@link snapshot}, so the read is unconditional and the cache is only WRITTEN to, not
+     * consulted — a caller that wants the cached value should read {@link cache} directly.
+     *
+     * The returned data is converter-applied: declared defaults are filled in, undeclared fields are
+     * stripped, and encoded fields (`firestoreEncodedArray`, `firestoreBitwiseSet`) are decoded. This is
+     * byte-for-byte what the model API's `readDocument` returns, which is what lets `dbx-cli` read the
+     * same document over either transport and get the same answer.
      *
      * @param options - Overrides forwarded to `DocumentSnapshot.data()`, if any.
      * @returns Resolves with the document data, or undefined when the document does not exist.

package/src/lib/common/firestore/snapshot/snapshot.field.d.ts

@@ -30,7 +30,7 @@
  */
 import { type WebsiteLink, type GrantedRole, type WebsiteFileLink } from '@dereekb/model';
 import { type DateCellRange, type DateCellSchedule } from '@dereekb/date';
-import { type ModelFieldMapFunctionsConfig, type GetterOrValue, type Maybe, type ModelFieldMapConvertFunction, type PrimativeKey, type ReadKeyFunction, type ModelFieldMapFunctionsWithDefaultsConfig, type FilterUniqueStringsTransformConfig, type MapFunction, type FilterKeyValueTuplesInput, type ModelKey, type ToModelMapFunctionsInput, type ModelMapFunctionsRef, type LatLngPrecision, type LatLngString, type TimezoneString, type PrimativeKeyStringDencoderFunction, type PrimativeKeyDencoderFunction, type UnitedStatesAddress, type ZoomLevel, type FilterUniqueFunction, type BitwiseEncodedSet, type BitwiseObjectDencoder, type SortCompareFunctionRef, type TransformNumberFunctionConfigInput, type TransformStringFunctionConfigInput, type DecisionFunction, type ISO8601DateString, type FilterFunction } from '@dereekb/util';
+import { type ModelFieldMapFunctionsConfig, type GetterOrValue, type Maybe, type ModelFieldMapConvertFunction, type PrimativeKey, type ReadKeyFunction, type ModelFieldMapFunctionsWithDefaultsConfig, type FilterUniqueStringsTransformConfig, type MapFunction, type FilterKeyValueTuplesInput, type CopyValueDeepConfig, type ModelKey, type ToModelMapFunctionsInput, type ModelMapFunctionsRef, type LatLngPrecision, type LatLngString, type TimezoneString, type PrimativeKeyStringDencoderFunction, type PrimativeKeyDencoderFunction, type UnitedStatesAddress, type ZoomLevel, type FilterUniqueFunction, type BitwiseEncodedSet, type BitwiseObjectDencoder, type SortCompareFunctionRef, type TransformNumberFunctionConfigInput, type TransformStringFunctionConfigInput, type DecisionFunction, type ISO8601DateString, type FilterFunction } from '@dereekb/util';
 import { type FirestoreModelData } from './snapshot.type';
 /**
  * Base configuration for Firestore field mapping.
@@ -315,6 +315,69 @@ export declare function optionalFirestoreField<V, D>(config?: OptionalFirestoreF
  * @returns A field mapping configuration for optional values
  */
 export declare function optionalFirestoreField<T>(config?: OptionalFirestoreFieldConfigWithOneTypeTransform<T>): FirestoreModelFieldMapFunctionsConfig<Maybe<T>, Maybe<T>>;
+/**
+ * Configuration for {@link optionalFirestorePassthroughJsonField}.
+ *
+ * Extends {@link CopyValueDeepConfig}, which is what configures the filtering applied on the way in: by
+ * default `filter` strips `undefined` values at every depth. `arrayValues`, `filterEmptyValues`, and
+ * `transform` are passed through to the copy as-is.
+ *
+ * @template T - Type for both the model field and Firestore field
+ */
+export interface OptionalFirestorePassthroughJsonFieldConfig<T extends object> extends CopyValueDeepConfig, Pick<OptionalFirestoreFieldConfig<T, T>, 'defaultReadValue'> {
+    /**
+     * Whether to store `null` instead of an object that has no keys left after filtering. Defaults to `false`.
+     */
+    readonly dontStoreIfEmpty?: boolean;
+}
+/**
+ * Creates a field mapping configuration for an optional object field that is stored as-is, aside from
+ * the values the filter strips out on the way in.
+ *
+ * This is the field for json a converter should not model: a third-party api response, a request config
+ * whose parameters the vendor extends without warning, an sdk-shaped payload. A strict converter would
+ * silently drop whatever it does not name; this one keeps everything.
+ *
+ * The one thing it does not keep is a value Firestore rejects. Firestore refuses an explicit `undefined`
+ * outright — one absent optional field anywhere in the payload fails the whole write — and such a value
+ * is exactly what assembling json from `Maybe` inputs produces (a usage object built from whichever
+ * token counts a response happened to report, a config a caller spread a `Maybe` into). Solved per-writer
+ * it has to be remembered at every call site; solved here it cannot be forgotten.
+ *
+ * The filtering is RECURSIVE, since json of this kind is nested and its interior is just as capable of
+ * carrying an `undefined` as its top level. Non-plain values are retained by reference, so a `Date` (or
+ * a `Timestamp`, or a `DocumentReference`) survives the copy intact.
+ *
+ * Filtering happens on WRITE only. Reads are the plain passthrough — no copy, no traversal — since data
+ * that came out of Firestore cannot contain the values being filtered in the first place.
+ *
+ * A top-level `null` still clears the field: {@link optionalFirestoreField} short-circuits `x == null`
+ * ahead of the transform, so `update({ myField: null })` is untouched by this.
+ *
+ * @param config - Filtering and storage configuration. Defaults to stripping `undefined` values at every depth.
+ * @returns A field mapping configuration for optional passthrough json values.
+ *
+ * @dbxModelSnapshotField
+ * @dbxModelSnapshotFieldCategory object
+ * @dbxModelSnapshotFieldOptional true
+ * @dbxModelSnapshotFieldTags json, passthrough, object, raw, optional, undefined, filter, recursive, factory
+ * @dbxModelSnapshotFieldRelated optional-firestore-field, firestore-pass-through-field, firestore-sub-object
+ * @template T - Type for both the model field and Firestore field
+ *
+ * @example
+ * ```ts
+ * fields: {
+ *   // { model: 'm', temperature: undefined, provider: { only: ['openai'], sort: undefined } }
+ *   // stores as { model: 'm', provider: { only: ['openai'] } }
+ *   config: optionalFirestorePassthroughJsonField<MyVendorConfig>(),
+ *   // store null rather than an empty object when nothing survives the filtering
+ *   usage: optionalFirestorePassthroughJsonField<MyVendorUsage>({ filterEmptyValues: true, dontStoreIfEmpty: true })
+ * }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function optionalFirestorePassthroughJsonField<T extends object>(config?: OptionalFirestorePassthroughJsonFieldConfig<T>): FirestoreModelFieldMapFunctionsConfig<Maybe<T>, Maybe<T>>;
 /**
  * Configuration for a Firestore field with default model value but without conversion functions.
  *

package/src/lib/common/model/model.service.d.ts

@@ -21,6 +21,12 @@ export type FirebaseModelServiceContext = FirebasePermissionContext & FirebasePe
  * @template R - the granted role type for this model
  */
 export interface FirebaseModelService<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> extends FirebaseModelPermissionService<C, T, D, R>, FirebaseModelLoader<C, T, D>, FirebaseModelCollectionLoader<any, T, D> {
+    /**
+     * Whether this model is SERVER-ONLY: unreachable by any client, on any read path.
+     *
+     * See {@link FirebaseModelServiceConfig.serverOnly}.
+     */
+    readonly serverOnly?: boolean;
 }
 /**
  * Lazy getter for a {@link FirebaseModelService}, typically used in the service factory map.
@@ -33,6 +39,22 @@ export type FirebaseModelServiceGetter<C extends FirebaseModelServiceContext, T,
  * from the collection loader.
  */
 export interface FirebaseModelServiceConfig<C extends FirebaseModelServiceContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> extends Omit<FirebasePermissionServiceInstanceDelegate<C, T, D, R>, 'loadModelForKey'>, FirebaseModelCollectionLoader<C, T, D> {
+    /**
+     * Marks this model SERVER-ONLY: no client may read it, on any path.
+     *
+     * `roleMapForModel` and `firestore.rules` are two independent authorization systems, and the
+     * model API runs under the Admin SDK — so it evaluates the former and bypasses the latter
+     * entirely. For a model whose rules file has no match block (or an `allow read: if false`), that
+     * divergence is a LEAK: the rules say server-only, and the model API hands the document to a
+     * client anyway.
+     *
+     * Setting this closes the gap by refusing the read ahead of `useModel`, so both read paths agree.
+     * It is a routing decision, not a permission computation — hence a flag rather than a role.
+     *
+     * Opt-in by design: absent means today's behaviour, which is the backward-compatible direction
+     * for a framework. Downstream apps are unaffected until they set it.
+     */
+    readonly serverOnly?: boolean;
 }
 /**
  * Creates a {@link FirebaseModelService} that wires together model loading and permission evaluation.
@@ -78,7 +100,13 @@ export type LimitedInContextFirebaseModelService<C extends FirebasePermissionErr
  * Calling `service(modelOrKey)` returns an {@link InModelContextFirebaseModelService} with role checking and assertions.
  * Also provides `forKey(key)` for key-based lookup.
  */
-export type InContextFirebaseModelService<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = InModelContextFirebaseModelServiceFactory<C, T, D, R> & LimitedInContextFirebaseModelService<C, T, D, R>;
+export type InContextFirebaseModelService<C extends FirebasePermissionErrorContext, T, D extends FirestoreDocument<T> = FirestoreDocument<T>, R extends GrantedRole = GrantedRole> = InModelContextFirebaseModelServiceFactory<C, T, D, R> & LimitedInContextFirebaseModelService<C, T, D, R> & {
+    /**
+     * Mirrors {@link FirebaseModelServiceConfig.serverOnly}, so a caller holding only the
+     * context-bound service can gate on it without reaching back for the config.
+     */
+    readonly serverOnly?: boolean;
+};
 /**
  * Factory that binds a {@link FirebaseModelService} to a specific context, producing an {@link InContextFirebaseModelService}.
  */

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

@@ -593,6 +593,7 @@ export interface NotificationSendCheckpoints {
  *
  * @dbxModel
  * @dbxModelRead system
+ * @dbxModelServerOnly
  */
 export interface Notification extends NotificationSendFlags, NotificationSendCheckpoints {
     /**
@@ -753,6 +754,7 @@ export declare const NOTIFICATION_WEEK_NOTIFICATION_ITEM_LIMIT = 5000;
  *
  * @dbxModel
  * @dbxModelRead system
+ * @dbxModelServerOnly
  */
 export interface NotificationWeek {
     /**
@@ -854,6 +856,7 @@ export declare const NOTIFICATION_LOGGED_EVENT_DAY_ITEM_CONVERTER: PagedItemConv
  *
  * @dbxModel
  * @dbxModelRead system
+ * @dbxModelServerOnly
  */
 export interface NotificationLoggedEventDay {
     /**

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

@@ -68,6 +68,7 @@ export type SystemStateStoredData = Record<string, any>;
  * @dbxModel
  * @dbxModelRead system
  * @dbxModelArchetype system-state-singleton
+ * @dbxModelServerOnly
  */
 export interface SystemState<T extends SystemStateStoredData = SystemStateStoredData> {
     /**

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.36.0",
+  "version": "13.38.0",
   "peerDependencies": {
-    "@dereekb/date": "13.36.0",
-    "@dereekb/firebase": "13.36.0",
-    "@dereekb/model": "13.36.0",
-    "@dereekb/rxjs": "13.36.0",
-    "@dereekb/util": "13.36.0",
+    "@dereekb/date": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/rxjs": "13.38.0",
+    "@dereekb/util": "13.38.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",