@dereekb/firebase 13.41.0 → 13.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -22,10 +22,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "@marcbachmann/cel-js": "^7.6.1",
     "@typescript-eslint/parser": "8.59.3",

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

@@ -1520,6 +1520,10 @@ export interface FirestoreLatLngStringConfig extends DefaultMapConfiguredFiresto
  */
 export declare function firestoreLatLngString(config?: FirestoreLatLngStringConfig): FirestoreModelFieldMapFunctionsConfig<`${number},${number}`, `${number},${number}`>;
 export type FirestoreTimezoneStringConfig = DefaultMapConfiguredFirestoreFieldConfig<TimezoneString, TimezoneString>;
+/**
+ * Default value of a {@link firestoreTimezoneString} field that carries no explicit default.
+ */
+export declare const DEFAULT_FIRESTORE_TIMEZONE_STRING_VALUE: TimezoneString;
 /**
  * Default configuration for a TimezoneString.
  *

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

@@ -1,6 +1,6 @@
 import { type FirebaseStorageAccessor } from './driver/accessor';
 import { type FirebaseStorageDrivers } from './driver/driver';
-import { type StorageBucketId } from './storage';
+import { type StorageBucketId, type StoragePathFactory } from './storage';
 import { type FirebaseStorage } from './types';
 /**
  * Central context for Firebase Cloud Storage operations within `@dereekb/firebase`.
@@ -13,6 +13,14 @@ import { type FirebaseStorage } from './types';
 export interface FirebaseStorageContext<F extends FirebaseStorage = FirebaseStorage> extends FirebaseStorageAccessor {
     readonly storage: F;
     readonly drivers: FirebaseStorageDrivers;
+    /**
+     * Normalizes a {@link StoragePathInput} into the full {@link StoragePath} this context would use for it,
+     * applying the context's default bucket.
+     *
+     * Exposed so a caller that needs the resolved bucket and path — rather than an accessor — does not have to
+     * build a file accessor just to read its `storagePath` back off.
+     */
+    readonly storagePath: StoragePathFactory;
 }
 /**
  * Factory that creates a {@link FirebaseStorageContext} from a {@link FirebaseStorage} instance and optional configuration.

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

@@ -42,6 +42,18 @@ export interface FirebaseStorageAccessorFile<R = unknown> extends StoragePathRef
      * This is consistent between the client and server implementations.
      */
     getDownloadUrl(): Promise<StorageDownloadUrl>;
+    /**
+     * Returns the permanent, anonymously-readable url for the file WITHOUT checking that it exists.
+     *
+     * Unlike {@link getDownloadUrl}, this is a pure derivation of the file's bucket and path, so it can be
+     * called BEFORE the bytes are uploaded — which is what lets a publisher embed the url in the very content
+     * it is about to write.
+     *
+     * The url only actually resolves once the object exists AND has been made public (see {@link makePublic}).
+     *
+     * Generally a server-only implementation.
+     */
+    getPublicUrl?(): StorageDownloadUrl;
     /**
      * Returns a signed/temporary url
      */

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

@@ -3,3 +3,4 @@ export * from './driver';
 export * from './context';
 export * from './storage';
 export * from './types';
+export * from './storage.url';

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

@@ -0,0 +1,69 @@
+import { type StoragePath } from './storage';
+import { type StorageDownloadUrl } from './types';
+/**
+ * @module storage.url
+ *
+ * Derivation of a storage object's PUBLIC url from its bucket and path alone.
+ *
+ * Exists so the same string can be produced on either side of the wire. The server already mints it through
+ * `@google-cloud/storage`'s `File.publicUrl()`, but a client holding only a bucket and a path has no way to
+ * reach that — and no reason to pay a callable for a url that is a pure function of what it already knows.
+ */
+/**
+ * Origin (protocol and host, with no trailing slash) that serves GCS-native public object urls.
+ *
+ * @semanticType
+ * @semanticTopic url
+ * @semanticTopic string
+ * @semanticTopic dereekb-firebase:storage
+ */
+export type StoragePublicUrlApiEndpoint = string;
+/**
+ * The production origin that serves public objects.
+ *
+ * Note this is NOT the Firebase Storage host (`firebasestorage.googleapis.com`), which serves the
+ * rules-enforced `/v0/b/<bucket>/o/<object>` API instead. The two are distinct channels: this one is
+ * authorized by the object's ACL and security rules never apply to it.
+ */
+export declare const GOOGLE_CLOUD_STORAGE_PUBLIC_URL_API_ENDPOINT: StoragePublicUrlApiEndpoint;
+/**
+ * Input for {@link storagePublicDownloadUrl}.
+ */
+export interface StoragePublicDownloadUrlInput {
+    /**
+     * Origin that serves the object. Use {@link GOOGLE_CLOUD_STORAGE_PUBLIC_URL_API_ENDPOINT} in production,
+     * or the storage emulator's own origin when emulating.
+     */
+    readonly apiEndpoint: StoragePublicUrlApiEndpoint;
+    /**
+     * Bucket and path of the object.
+     */
+    readonly storagePath: StoragePath;
+}
+/**
+ * Derives the permanent, anonymously-readable url for a storage object.
+ *
+ * Mirrors `@google-cloud/storage`'s `File.publicUrl()` exactly — `<endpoint>/<bucket>/<encoded name>` — so a
+ * url derived here is byte-identical to the one the server records. The path is encoded whole rather than
+ * per-segment, which is what preserves the leading slash this workspace's `StoragePath` values carry
+ * (`/cal/<id>.ics` encodes to `%2Fcal%2F<id>.ics`, naming an object whose own name leads with a slash).
+ *
+ * This is a pure derivation, so it can be called before the bytes exist. The url only actually resolves
+ * once the object exists AND is public — an object ACL grant on an ordinary bucket, or an
+ * `allUsers:objectViewer` IAM binding on a bucket with uniform bucket-level access.
+ *
+ * @param input - The origin and the object's bucket and path.
+ * @returns The object's public download url.
+ *
+ * @example
+ * ```ts
+ * storagePublicDownloadUrl({
+ *   apiEndpoint: GOOGLE_CLOUD_STORAGE_PUBLIC_URL_API_ENDPOINT,
+ *   storagePath: { bucketId: 'my-bucket.appspot.com', pathString: '/cal/0mfR2xk8SqVe1Nb7.ics' }
+ * });
+ * // 'https://storage.googleapis.com/my-bucket.appspot.com/%2Fcal%2F0mfR2xk8SqVe1Nb7.ics'
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function storagePublicDownloadUrl(input: StoragePublicDownloadUrlInput): StorageDownloadUrl;

package/src/lib/model/calendar/calendar.action.d.ts

@@ -0,0 +1,34 @@
+import { type AsyncFirebaseFunctionCreateAction, type AsyncFirebaseFunctionDeleteAction, type AsyncFirebaseFunctionUpdateAction, type FirebaseFunctionCreateAction, type FirebaseFunctionDeleteAction, type FirebaseFunctionUpdateAction } from '../../common';
+import { type CalendarDocument } from './calendar';
+/**
+ * @module calendar.action
+ *
+ * Type aliases for Calendar server action functions, following the same pattern as the StorageFile and
+ * Notification actions. See `@dereekb/firebase-server/model` for the implementations.
+ *
+ * @template P - the parameter type for the action
+ */
+/**
+ * Synchronous create action targeting a {@link CalendarDocument}.
+ */
+export type CalendarCreateAction<P extends object> = FirebaseFunctionCreateAction<P, CalendarDocument>;
+/**
+ * Async create action targeting a {@link CalendarDocument}.
+ */
+export type AsyncCalendarCreateAction<P extends object> = AsyncFirebaseFunctionCreateAction<P, CalendarDocument>;
+/**
+ * Synchronous update action targeting a {@link CalendarDocument}.
+ */
+export type CalendarUpdateAction<P extends object> = FirebaseFunctionUpdateAction<P, CalendarDocument>;
+/**
+ * Async update action targeting a {@link CalendarDocument}.
+ */
+export type AsyncCalendarUpdateAction<P extends object> = AsyncFirebaseFunctionUpdateAction<P, CalendarDocument>;
+/**
+ * Synchronous delete action targeting a {@link CalendarDocument}.
+ */
+export type CalendarDeleteAction<P extends object> = FirebaseFunctionDeleteAction<P, CalendarDocument>;
+/**
+ * Async delete action targeting a {@link CalendarDocument}.
+ */
+export type AsyncCalendarDeleteAction<P extends object> = AsyncFirebaseFunctionDeleteAction<P, CalendarDocument>;

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

@@ -0,0 +1,147 @@
+import { type Type } from 'arktype';
+import { type Maybe } from '@dereekb/util';
+import { type TargetModelParams } from '../../common';
+import { type FirebaseFunctionTypeConfigMap, type ModelFirebaseCrudFunction, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap } from '../../client';
+import { type CalendarTypes } from './calendar';
+import { type CalendarType } from './calendar.id';
+/**
+ * @module calendar.api
+ *
+ * The Calendar exposes exactly ONE callable — `calendar/update/rotateIcs`. A published .ics url is a
+ * permanent zero-auth bearer credential, and rotating it is the only revocation such a url has, so it has to
+ * be reachable by the owner who minted it rather than buried in an admin tool.
+ *
+ * Event mutation is deliberately NOT part of that surface — a caller already holds a transaction and an
+ * accessor when it decides to touch a calendar, so it merges the `calendar.util.ts` templates into its own
+ * write instead.
+ *
+ * The publish-side sweeps (`syncCalendar`, `syncAllFlaggedCalendars`, `flagStaleCalendarsForSync`) stay
+ * internal to the scheduled processor. Their arktypes live here only because
+ * `firebaseServerActionTransformFunctionFactory` needs one per action.
+ */
+/**
+ * Parameters for syncing a single Calendar: pruning it and queueing its ICS for regeneration.
+ */
+export interface SyncCalendarParams extends TargetModelParams {
+}
+export declare const syncCalendarParamsType: Type<SyncCalendarParams>;
+/**
+ * Result of syncing a single Calendar.
+ */
+export interface SyncCalendarResult {
+    /**
+     * True if a new ICS StorageFile was created, false if the existing one was re-flagged.
+     */
+    readonly createdIcsStorageFile: boolean;
+    readonly prunedEventCount: number;
+    readonly prunedRecurringEventCount: number;
+}
+/**
+ * Parameters for rotating a Calendar's published ICS link.
+ */
+export interface RotateCalendarIcsParams extends TargetModelParams {
+}
+export declare const rotateCalendarIcsParamsType: Type<RotateCalendarIcsParams>;
+/**
+ * Result of rotating a Calendar's published ICS link.
+ */
+export interface RotateCalendarIcsResult {
+    /**
+     * True if an existing ICS StorageFile was flagged for delete, revoking the url that named it.
+     *
+     * False when the calendar had never published one, in which case the rotation is a no-op that still
+     * queues a first publish.
+     */
+    readonly revokedIcsStorageFile: boolean;
+    /**
+     * True if the immediate re-sync minted the replacement ICS StorageFile.
+     */
+    readonly createdIcsStorageFile: boolean;
+    /**
+     * True if the expedited publish finished, meaning the replacement url is already live in `Calendar.iu`.
+     *
+     * False means only that the publish did not complete INLINE — the replacement is still queued and the
+     * regular sweep will publish it. Rotation itself has already succeeded either way, so a caller treats this
+     * as "is the new link ready to show yet", never as a failure.
+     */
+    readonly publishedIcs: boolean;
+}
+/**
+ * Parameters for sweeping every Calendar flagged for sync.
+ */
+export interface SyncAllFlaggedCalendarsParams {
+}
+export declare const syncAllFlaggedCalendarsParamsType: Type<SyncAllFlaggedCalendarsParams>;
+/**
+ * Result of the flagged-calendar sweep.
+ */
+export interface SyncAllFlaggedCalendarsResult {
+    readonly calendarsVisited: number;
+    readonly calendarsSyncedCount: number;
+    readonly calendarsFailedCount: number;
+}
+/**
+ * Parameters for the backstop sweep that re-flags Calendars whose published ICS has gone stale.
+ */
+export interface FlagStaleCalendarsForSyncParams {
+    /**
+     * Restricts the sweep to a single type. All registered types are swept when absent.
+     */
+    readonly calendarType?: Maybe<CalendarType>;
+}
+export declare const flagStaleCalendarsForSyncParamsType: Type<FlagStaleCalendarsForSyncParams>;
+/**
+ * Result of the backstop sweep.
+ */
+export interface FlagStaleCalendarsForSyncResult {
+    readonly calendarsVisited: number;
+    readonly calendarsFlaggedCount: number;
+}
+/**
+ * Custom (non-CRUD) function type map for Calendar. Empty — the only callable is a CRUD update.
+ */
+export type CalendarFunctionTypeMap = {};
+export declare const calendarFunctionTypeConfigMap: FirebaseFunctionTypeConfigMap<CalendarFunctionTypeMap>;
+/**
+ * CRUD function configuration map for the Calendar model.
+ *
+ * Intentionally minimal. See the module docblock for why rotation is the only operation here.
+ */
+export type CalendarModelCrudFunctionsConfig = {
+    readonly calendar: {
+        update: {
+            /**
+             * Rotates the calendar's public ICS link, revoking the previous one.
+             *
+             * Flags the current ICS StorageFile for delete and clears the calendar's pointer + url, then re-syncs
+             * so a fresh StorageFile — and therefore a fresh url — is minted. Existing subscribers to the old url
+             * break by design; that is the revocation.
+             */
+            rotateIcs: [RotateCalendarIcsParams, RotateCalendarIcsResult];
+        };
+    };
+};
+export declare const calendarModelCrudFunctionsConfig: ModelFirebaseCrudFunctionConfigMap<CalendarModelCrudFunctionsConfig, CalendarTypes>;
+/**
+ * Client-side callable function map factory for the Calendar's CRUD operations.
+ *
+ * @example
+ * ```ts
+ * const functions = calendarFunctionMap(callableFactory);
+ * const result = await functions.calendar.updateCalendar.rotateIcs({ key: 'cal/pr_abc123' });
+ * ```
+ */
+export declare const calendarFunctionMap: import("../..").ModelFirebaseFunctionMapFactory<CalendarFunctionTypeMap, CalendarModelCrudFunctionsConfig>;
+/**
+ * Abstract class defining the callable Calendar cloud functions.
+ *
+ * Register it in an app's functions config map to make it injectable. Use {@link calendarFunctionMap} to
+ * create the client-side callable map.
+ */
+export declare abstract class CalendarFunctions implements ModelFirebaseFunctionMap<CalendarFunctionTypeMap, CalendarModelCrudFunctionsConfig> {
+    abstract calendar: {
+        updateCalendar: {
+            rotateIcs: ModelFirebaseCrudFunction<RotateCalendarIcsParams, RotateCalendarIcsResult>;
+        };
+    };
+}

package/src/lib/model/calendar/calendar.api.error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module calendar.api.error
+ *
+ * Error codes raised by the Calendar publish pipeline.
+ */
+/**
+ * Thrown when the Calendar module has no ICS domain configured.
+ *
+ * The UID factory deliberately has no random fallback — a UID that changes between publishes makes every
+ * client create a duplicate event rather than update the one it holds — so a missing domain is a hard error
+ * rather than something to paper over at emit time.
+ */
+export declare const CALENDAR_ICS_DOMAIN_NOT_CONFIGURED_ERROR_CODE = "CALENDAR_ICS_DOMAIN_NOT_CONFIGURED";
+/**
+ * Thrown when a Calendar's ICS StorageFile could not be resolved or created.
+ */
+export declare const CALENDAR_ICS_STORAGE_FILE_UNAVAILABLE_ERROR_CODE = "CALENDAR_ICS_STORAGE_FILE_UNAVAILABLE";
+/**
+ * Thrown when a Calendar's ICS link is rotated again before its throttle window has passed.
+ *
+ * Rotation is destructive to subscribers — the old url dies and every client holding it breaks — so it is
+ * rate-limited. See `calendarNextIcsRotateAt()` for the window both sides derive.
+ */
+export declare const CALENDAR_ICS_ROTATE_THROTTLED_ERROR_CODE = "CALENDAR_ICS_ROTATE_THROTTLED";