@dereekb/firebase-server 13.41.0 → 13.43.0

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

@@ -0,0 +1,144 @@
+import { type FirestoreDocument, type SchedulerSystemStateRead, type SystemState, type SystemStateFirestoreCollectionLike, type SystemStateStoredData } from '@dereekb/firebase';
+import { type Getter, type Hours, type Maybe } from '@dereekb/util';
+/**
+ * Configuration for a single gate evaluation.
+ */
+export interface SchedulerSystemStateGateConfig {
+    /**
+     * Run every Nth hour of the day.
+     *
+     * Matched by modulo against the hour-of-day, so only divisors of 24 divide the day evenly. See
+     * `isNthHourOfDay()` in `@dereekb/firebase`.
+     */
+    readonly everyNHours: Hours;
+}
+/**
+ * The outcome of a {@link SchedulerSystemStateAccessor.checkAndClaim} call.
+ *
+ * Extends {@link SchedulerSystemStateRead}, so past the pass/fail answer it is also the read the
+ * decision was made from: the same `now`, the same hour-of-day, and the same bound predicates. That
+ * is what lets a single hourly claim fan out into per-task sub-gates without a second read or a
+ * second clock —
+ *
+ * ```ts
+ * const gate = await schedulerSystemState.checkAndClaim({ everyNHours: 1 });
+ *
+ * if (!gate.claimed) {
+ *   return;
+ * }
+ *
+ * await hourlyWork();
+ *
+ * if (gate.isNthHourOfDay(3)) {
+ *   await everyThreeHoursWork();
+ * }
+ * ```
+ *
+ * NOTE: this is an object, so it is ALWAYS truthy. `if (await checkAndClaim(...))` always passes —
+ * branch on {@link SchedulerSystemStateClaim.claimed}.
+ *
+ * The inherited {@link SchedulerSystemStateRead} members describe the state as it was read BEFORE
+ * the claim was stamped, deliberately: `lastRunAt` is the previous claim, `hasRunInCurrentHour` is
+ * false on a successful claim, and `isOpen()` still answers for the other intervals this hour rather
+ * than reporting closed against the claim this very call just wrote.
+ */
+export interface SchedulerSystemStateClaim extends SchedulerSystemStateRead {
+    /**
+     * The interval the claim was evaluated for.
+     */
+    readonly everyNHours: Hours;
+    /**
+     * Whether THIS call claimed the hour, and so whether the caller may run its work.
+     */
+    readonly claimed: boolean;
+    /**
+     * The moment stamped as the new `lat`, or null when the gate was closed and nothing was written.
+     *
+     * Always equal to {@link SchedulerSystemStateRead.now} when {@link claimed} is true.
+     */
+    readonly claimedAt: Maybe<Date>;
+}
+/**
+ * Reads and claims the scheduler's hourly run gate.
+ */
+export interface SchedulerSystemStateAccessor {
+    /**
+     * Reads the gate state without claiming it.
+     *
+     * @returns The state, which can be evaluated against any number of intervals.
+     */
+    read(): Promise<SchedulerSystemStateRead>;
+    /**
+     * Reads, evaluates the gate for the given interval, and CLAIMS the hour, in one transaction.
+     *
+     * The claim is stamped BEFORE this resolves, deliberately: a crash or a function timeout in the
+     * caller's work must still cost the whole window. Otherwise the hourly cron degrades into an
+     * hourly retry loop against work that is already failing.
+     *
+     * Remember that one gate is one `lat`. Two callers with different `everyNHours` sharing the
+     * document will have whichever one passes first claim the hour for BOTH — the second gets
+     * `claimed: false` even if its own interval matched. That is the intended semantics of a single
+     * gate, but it is the thing a future second caller will trip over. Prefer claiming ONCE at the top
+     * of the schedule function and sub-gating the individual tasks off the returned
+     * {@link SchedulerSystemStateClaim}.
+     *
+     * @param config - The interval to evaluate.
+     * @returns The claim outcome, which also carries the read it was decided from.
+     */
+    checkAndClaim(config: SchedulerSystemStateGateConfig): Promise<SchedulerSystemStateClaim>;
+}
+/**
+ * Configuration for {@link schedulerSystemStateAccessorFactory}.
+ */
+export interface SchedulerSystemStateAccessorFactoryConfig {
+    /**
+     * Clock used to evaluate the gate and to stamp `lat`. Defaults to the current time.
+     *
+     * Overriding it is what lets a test place "now" at a specific hour-of-day — the gate is a
+     * modulo against the hour, so there is otherwise no way to exercise a non-matching hour without
+     * waiting for one.
+     */
+    readonly nowFactory?: Maybe<Getter<Date>>;
+}
+/**
+ * Creates a {@link SchedulerSystemStateAccessor} for a SystemState collection.
+ */
+export type SchedulerSystemStateAccessorFactory = <D extends FirestoreDocument<SystemState<SystemStateStoredData>>>(systemStateCollection: SystemStateFirestoreCollectionLike<SystemStateStoredData, D>) => SchedulerSystemStateAccessor;
+/**
+ * Creates a {@link SchedulerSystemStateAccessorFactory}, the Firestore-backed half of the scheduler's
+ * hourly run gate.
+ *
+ * The gate answers "should the scheduler run its Nth-hour body during this hour?" for the app as a
+ * whole, off the single `lat` on the `sys/scheduler` document. Claim it ONCE at the top of a
+ * schedule function; the individual tasks it guards carry no throttle of their own and sub-gate off
+ * the returned {@link SchedulerSystemStateClaim} instead.
+ *
+ * The collection MUST have `schedulerSystemDataConverter` registered under
+ * {@link SCHEDULER_SYSTEM_STATE_TYPE}. Without it the collection falls back to the pass-through
+ * converter and `lat` reads back as a raw Firestore `Timestamp`, which no hour comparison can match —
+ * so the gate would silently open on every call. {@link SchedulerSystemStateAccessor.read} and
+ * `checkAndClaim` throw on that rather than let it through.
+ *
+ * @param config - The clock override, if any.
+ * @returns A factory producing an accessor over a given SystemState collection.
+ *
+ * @example
+ * ```ts
+ * const schedulerSystemState = schedulerSystemStateAccessorFactory()(systemStateCollection);
+ *
+ * export const hourlySchedule: MyScheduleFunction = async (request) => {
+ *   const gate = await schedulerSystemState.checkAndClaim({ everyNHours: 1 });
+ *
+ *   if (!gate.claimed) {
+ *     return;
+ *   }
+ *
+ *   await hourlyWork();
+ *
+ *   if (gate.isNthHourOfDay(3)) {
+ *     await everyThreeHoursWork();
+ *   }
+ * };
+ * ```
+ */
+export declare function schedulerSystemStateAccessorFactory(config?: Maybe<SchedulerSystemStateAccessorFactoryConfig>): SchedulerSystemStateAccessorFactory;

package/oidc/index.esm.js

@@ -3625,7 +3625,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  * @returns The union of config-level and profile-level admin-only scopes.
  */ function adminOnlyScopesForOidcProviderConfig(providerConfig) {
     var _providerConfig_adminOnlyScopes, _providerConfig_providerProfiles;
-    return new Set(_to_consumable_array$5((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []).concat(_to_consumable_array$5(adminOnlyScopesForOidcProviderProfiles((_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : []))));
+    return new Set(_to_consumable_array$5((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []).concat(_to_consumable_array$5(Array.from(adminOnlyScopesForOidcProviderProfiles((_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : [])))));
 }
 
 /**
@@ -6571,7 +6571,7 @@ var OidcInteractionController_1;
                                 effectiveOIDCScopes = resolveEffectiveSubset({
                                     missing: missingOIDCScope,
                                     requestedSubset: body.grantedOIDCScopes,
-                                    alwaysGranted: _to_consumable_array$1(ALWAYS_GRANTED_OIDC_SCOPES).concat(_to_consumable_array$1(clientRequiredScopes)),
+                                    alwaysGranted: _to_consumable_array$1(ALWAYS_GRANTED_OIDC_SCOPES).concat(_to_consumable_array$1(Array.from(clientRequiredScopes))),
                                     alreadyEncountered: encounteredOIDCScopes
                                 });
                                 // Scopes the existing Grant already holds (granted, minus any it rejected). Nothing here revokes

package/oidc/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.41.0",
-    "@dereekb/date": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/firebase-server": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
-    "@dereekb/zoho": "13.41.0",
+    "@dereekb/analytics": "13.43.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/firebase-server": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
+    "@dereekb/zoho": "13.43.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -58,17 +58,17 @@
   },
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.41.0",
-    "@dereekb/calcom": "13.41.0",
-    "@dereekb/date": "13.41.0",
-    "@dereekb/dbx-core": "13.41.0",
-    "@dereekb/discord": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
-    "@dereekb/zoho": "13.41.0",
+    "@dereekb/analytics": "13.43.0",
+    "@dereekb/calcom": "13.43.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/dbx-core": "13.43.0",
+    "@dereekb/discord": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
+    "@dereekb/zoho": "13.43.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/node": "2.0.0",

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

@@ -20,7 +20,7 @@ export declare function googleCloudStorageFileForStorageFilePath(storage: Google
 /**
  * Server-side file accessor type that guarantees stream operations are available.
  */
-export type GoogleCloudStorageAccessorFile = FirebaseStorageAccessorFile<GoogleCloudFile> & Required<Pick<FirebaseStorageAccessorFile<GoogleCloudFile>, 'uploadStream' | 'getStream'>>;
+export type GoogleCloudStorageAccessorFile = FirebaseStorageAccessorFile<GoogleCloudFile> & Required<Pick<FirebaseStorageAccessorFile<GoogleCloudFile>, 'uploadStream' | 'getStream' | 'getPublicUrl'>>;
 /**
  * Converts Google Cloud Storage {@link FileMetadata} into the normalized {@link StorageMetadata} format.
  *

package/test/index.esm.js

@@ -4952,7 +4952,7 @@ function _ts_generator$1(thisArg, body) {
         }
     }
     function cookieHeader() {
-        return _to_consumable_array(cookieJar.values()).join('; ');
+        return Array.from(cookieJar.values()).join('; ');
     }
     return {
         collectCookies: collectCookies,
@@ -4990,7 +4990,7 @@ function _ts_generator$1(thisArg, body) {
                 accountService = nestApp.get(OidcAccountService);
                 providerConfig = accountService.providerConfig;
                 providerProfiles = (_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : [];
-                adminOnlyScopes = new Set(_to_consumable_array((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []).concat(_to_consumable_array(adminOnlyScopesForOidcProviderProfiles(providerProfiles))));
+                adminOnlyScopes = new Set(_to_consumable_array((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []).concat(_to_consumable_array(Array.from(adminOnlyScopesForOidcProviderProfiles(providerProfiles)))));
                 profileGatedScopes = assignmentOnlyScopesForOidcProviderProfiles(providerProfiles);
                 result = Object.keys(providerConfig.claims).filter(function(scope) {
                     return !adminOnlyScopes.has(scope) && !profileGatedScopes.has(scope);

package/test/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.41.0",
-    "@dereekb/date": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/firebase-server": "13.41.0",
-    "@dereekb/firebase-server/oidc": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/analytics": "13.43.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/firebase-server": "13.43.0",
+    "@dereekb/firebase-server/oidc": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -24,7 +24,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.41.0"
+    "@dereekb/nestjs": "13.43.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/firebase-server": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/util": "13.41.0"
+    "@dereekb/date": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/firebase-server": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/util": "13.43.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.41.0",
-    "@dereekb/date": "13.41.0",
-    "@dereekb/model": "13.41.0",
-    "@dereekb/nestjs": "13.41.0",
-    "@dereekb/rxjs": "13.41.0",
-    "@dereekb/firebase": "13.41.0",
-    "@dereekb/firebase-server": "13.41.0",
-    "@dereekb/util": "13.41.0",
-    "@dereekb/zoho": "13.41.0",
+    "@dereekb/analytics": "13.43.0",
+    "@dereekb/date": "13.43.0",
+    "@dereekb/model": "13.43.0",
+    "@dereekb/nestjs": "13.43.0",
+    "@dereekb/rxjs": "13.43.0",
+    "@dereekb/firebase": "13.43.0",
+    "@dereekb/firebase-server": "13.43.0",
+    "@dereekb/util": "13.43.0",
+    "@dereekb/zoho": "13.43.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1"