@dereekb/firebase-server 13.2.1 → 13.3.0

package/zoho/index.esm.js

@@ -1,109 +1,442 @@
 import { firestoreSubObject, firestoreDate, firestoreNumber, firestoreString, firestoreObjectArray } from '@dereekb/firebase';
 import { isPast, filterUniqueFunction } from '@dereekb/util';
 
-const ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE = 'zoho_access_token';
-const zohoAccessTokenSystemStateEmbeddedTokenConverter = firestoreSubObject({
+/**
+ * {@link SystemState} type identifier for storing Zoho access tokens in Firestore.
+ */ var ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE = 'zoho_access_token';
+var zohoAccessTokenSystemStateEmbeddedTokenConverter = firestoreSubObject({
     objectField: {
         fields: {
             key: firestoreString(),
             accessToken: firestoreString(),
             scope: firestoreString(),
             apiDomain: firestoreString(),
-            expiresIn: firestoreNumber({ default: 3600 }),
+            expiresIn: firestoreNumber({
+                default: 3600
+            }),
             expiresAt: firestoreDate()
         }
     }
 });
 /**
- * NOTE: Be sure to register this data converter with the SystemStateStoredDataConverterMap for your app.
- */
-const zohoAccessTokenSystemStateDataConverter = firestoreSubObject({
+ * Firestore field converter for {@link ZohoAccessTokenSystemStateData}.
+ *
+ * Automatically filters out expired tokens on read and enforces uniqueness by service key.
+ * Must be registered in the app's {@link SystemStateStoredDataConverterMap} under
+ * the {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} key.
+ */ var zohoAccessTokenSystemStateDataConverter = firestoreSubObject({
     objectField: {
         fields: {
             tokens: firestoreObjectArray({
                 firestoreField: zohoAccessTokenSystemStateEmbeddedTokenConverter,
-                filterUnique: filterUniqueFunction((x) => x.key), // only one token per key is allowed
-                filter: (x) => (x?.expiresAt ? !isPast(x.expiresAt) : true) // filter out expired values or values that have no expiration
+                filterUnique: filterUniqueFunction(function(x) {
+                    return x.key;
+                }),
+                filter: function filter(x) {
+                    return (x === null || x === void 0 ? void 0 : x.expiresAt) ? !isPast(x.expiresAt) : true // filter out expired values or values that have no expiration
+                    ;
+                }
             }),
-            lat: firestoreDate({ saveDefaultAsNow: true })
+            lat: firestoreDate({
+                saveDefaultAsNow: true
+            })
         }
     }
 });
 /**
- * Convenience function for loading the document for ZohoAccessTokenSystemStateData.
+ * Loads the {@link SystemStateDocument} that stores {@link ZohoAccessTokenSystemStateData},
+ * using {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} as the document ID.
+ *
+ * @param accessor - the document accessor for the SystemState collection
  *
- * @param accessor
- * @returns
- */
-function loadZohoAccessTokenSystemState(accessor) {
+ * @example
+ * ```ts
+ * const doc = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessor());
+ * const data = await doc.snapshotData();
+ * ```
+ */ function loadZohoAccessTokenSystemState(accessor) {
     return accessor.loadDocumentForId(ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE);
 }
 
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
 /**
- * Creates a ZohoAccountsAccessTokenCacheService from the input SystemStateFirestoreCollection.
+ * Creates a {@link ZohoAccountsAccessTokenCacheService} backed by Firestore {@link SystemState} documents.
  *
- * @param collection
- */
-function firebaseZohoAccountsAccessTokenCacheService(systemStateCollection) {
-    const systemStateDocumentAccessor = systemStateCollection.documentAccessor();
-    const service = {
-        loadZohoAccessTokenCache: function (serviceKey) {
-            const cache = {
-                loadCachedToken: async function () {
-                    const document = loadZohoAccessTokenSystemState(systemStateDocumentAccessor);
-                    const existingData = await document.snapshotData();
-                    let result = null;
-                    if (existingData != null) {
-                        const tokensArray = existingData?.data?.tokens ?? [];
-                        result = tokensArray.find((x) => x.key === serviceKey);
-                    }
-                    return result;
-                },
-                updateCachedToken: async function (accessToken) {
-                    // run in a transaction
-                    await systemStateCollection.firestoreContext.runTransaction(async (transaction) => {
-                        const documentInTransaction = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessorForTransaction(transaction));
-                        const existingData = await documentInTransaction.snapshotData();
-                        const existingTokens = existingData?.data?.tokens ?? [];
-                        const tokens = [
-                            // filter any potential old token for this service key
-                            ...existingTokens.filter((x) => x.key !== serviceKey),
-                            // add the new token
-                            {
-                                ...accessToken,
-                                key: serviceKey
+ * Each Zoho service integration gets its own cached access token entry keyed by the service key.
+ * Tokens are stored in a single {@link SystemState} document (type {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE})
+ * and token updates/clears use Firestore transactions for concurrency safety.
+ *
+ * @param systemStateCollection - the Firestore collection for system state documents
+ *
+ * @example
+ * ```ts
+ * const cacheService = firebaseZohoAccountsAccessTokenCacheService(systemStateCollection);
+ * const cache = cacheService.loadZohoAccessTokenCache('my-zoho-service');
+ * const token = await cache.loadCachedToken();
+ * ```
+ */ function firebaseZohoAccountsAccessTokenCacheService(systemStateCollection) {
+    var systemStateDocumentAccessor = systemStateCollection.documentAccessor();
+    var service = {
+        loadZohoAccessTokenCache: function loadZohoAccessTokenCache(serviceKey) {
+            var cache = {
+                loadCachedToken: function loadCachedToken() {
+                    return _async_to_generator(function() {
+                        var document, existingData, result, _ref, _existingData_data, tokensArray;
+                        return _ts_generator(this, function(_state) {
+                            switch(_state.label){
+                                case 0:
+                                    document = loadZohoAccessTokenSystemState(systemStateDocumentAccessor);
+                                    return [
+                                        4,
+                                        document.snapshotData()
+                                    ];
+                                case 1:
+                                    existingData = _state.sent();
+                                    result = null;
+                                    if (existingData != null) {
+                                        tokensArray = (_ref = existingData === null || existingData === void 0 ? void 0 : (_existingData_data = existingData.data) === null || _existingData_data === void 0 ? void 0 : _existingData_data.tokens) !== null && _ref !== void 0 ? _ref : [];
+                                        result = tokensArray.find(function(x) {
+                                            return x.key === serviceKey;
+                                        });
+                                    }
+                                    return [
+                                        2,
+                                        result
+                                    ];
                             }
-                        ];
-                        const templateOrUpdate = {
-                            data: {
-                                tokens,
-                                lat: new Date()
+                        });
+                    })();
+                },
+                updateCachedToken: function updateCachedToken(accessToken) {
+                    return _async_to_generator(function() {
+                        return _ts_generator(this, function(_state) {
+                            switch(_state.label){
+                                case 0:
+                                    // run in a transaction
+                                    return [
+                                        4,
+                                        systemStateCollection.firestoreContext.runTransaction(function(transaction) {
+                                            return _async_to_generator(function() {
+                                                var _ref, _existingData_data, documentInTransaction, existingData, existingTokens, tokens, templateOrUpdate;
+                                                return _ts_generator(this, function(_state) {
+                                                    switch(_state.label){
+                                                        case 0:
+                                                            documentInTransaction = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessorForTransaction(transaction));
+                                                            return [
+                                                                4,
+                                                                documentInTransaction.snapshotData()
+                                                            ];
+                                                        case 1:
+                                                            existingData = _state.sent();
+                                                            existingTokens = (_ref = existingData === null || existingData === void 0 ? void 0 : (_existingData_data = existingData.data) === null || _existingData_data === void 0 ? void 0 : _existingData_data.tokens) !== null && _ref !== void 0 ? _ref : [];
+                                                            tokens = // filter any potential old token for this service key
+                                                            _to_consumable_array(existingTokens.filter(function(x) {
+                                                                return x.key !== serviceKey;
+                                                            })).concat([
+                                                                // add the new token
+                                                                _object_spread_props(_object_spread({}, accessToken), {
+                                                                    key: serviceKey
+                                                                })
+                                                            ]);
+                                                            templateOrUpdate = {
+                                                                data: {
+                                                                    tokens: tokens,
+                                                                    lat: new Date()
+                                                                }
+                                                            };
+                                                            if (!!existingData) return [
+                                                                3,
+                                                                3
+                                                            ];
+                                                            return [
+                                                                4,
+                                                                documentInTransaction.create(templateOrUpdate)
+                                                            ];
+                                                        case 2:
+                                                            _state.sent();
+                                                            return [
+                                                                3,
+                                                                5
+                                                            ];
+                                                        case 3:
+                                                            return [
+                                                                4,
+                                                                documentInTransaction.update(templateOrUpdate)
+                                                            ];
+                                                        case 4:
+                                                            _state.sent();
+                                                            _state.label = 5;
+                                                        case 5:
+                                                            return [
+                                                                2
+                                                            ];
+                                                    }
+                                                });
+                                            })();
+                                        })
+                                    ];
+                                case 1:
+                                    _state.sent();
+                                    return [
+                                        2
+                                    ];
                             }
-                        };
-                        // create/update depending on the current document's existence
-                        if (!existingData) {
-                            await documentInTransaction.create(templateOrUpdate);
-                        }
-                        else {
-                            await documentInTransaction.update(templateOrUpdate);
-                        }
-                    });
+                        });
+                    })();
                 },
-                clearCachedToken: async function () {
-                    await systemStateCollection.firestoreContext.runTransaction(async (transaction) => {
-                        const documentInTransaction = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessorForTransaction(transaction));
-                        const existingData = await documentInTransaction.snapshotData();
-                        const templateOrUpdate = {
-                            data: {
-                                tokens: [],
-                                lat: new Date()
+                clearCachedToken: function clearCachedToken() {
+                    return _async_to_generator(function() {
+                        return _ts_generator(this, function(_state) {
+                            switch(_state.label){
+                                case 0:
+                                    return [
+                                        4,
+                                        systemStateCollection.firestoreContext.runTransaction(function(transaction) {
+                                            return _async_to_generator(function() {
+                                                var documentInTransaction, existingData, templateOrUpdate;
+                                                return _ts_generator(this, function(_state) {
+                                                    switch(_state.label){
+                                                        case 0:
+                                                            documentInTransaction = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessorForTransaction(transaction));
+                                                            return [
+                                                                4,
+                                                                documentInTransaction.snapshotData()
+                                                            ];
+                                                        case 1:
+                                                            existingData = _state.sent();
+                                                            templateOrUpdate = {
+                                                                data: {
+                                                                    tokens: [],
+                                                                    lat: new Date()
+                                                                }
+                                                            };
+                                                            if (!existingData) return [
+                                                                3,
+                                                                3
+                                                            ];
+                                                            return [
+                                                                4,
+                                                                documentInTransaction.update(templateOrUpdate)
+                                                            ];
+                                                        case 2:
+                                                            _state.sent();
+                                                            _state.label = 3;
+                                                        case 3:
+                                                            return [
+                                                                2
+                                                            ];
+                                                    }
+                                                });
+                                            })();
+                                        })
+                                    ];
+                                case 1:
+                                    _state.sent();
+                                    return [
+                                        2
+                                    ];
                             }
-                        };
-                        // clear the tokens
-                        if (existingData) {
-                            await documentInTransaction.update(templateOrUpdate);
-                        }
-                    });
+                        });
+                    })();
                 }
             };
             return cache;

package/zoho/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.2.1",
+  "version": "13.3.0",
   "peerDependencies": {
-    "@dereekb/date": "13.2.1",
-    "@dereekb/model": "13.2.1",
-    "@dereekb/nestjs": "13.2.1",
-    "@dereekb/rxjs": "13.2.1",
-    "@dereekb/firebase": "13.2.1",
-    "@dereekb/util": "13.2.1",
-    "@dereekb/zoho": "13.2.1"
+    "@dereekb/date": "13.3.0",
+    "@dereekb/model": "13.3.0",
+    "@dereekb/nestjs": "13.3.0",
+    "@dereekb/rxjs": "13.3.0",
+    "@dereekb/firebase": "13.3.0",
+    "@dereekb/util": "13.3.0",
+    "@dereekb/zoho": "13.3.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/src/lib/zoho.accounts.firebase.d.ts

@@ -1,8 +1,19 @@
 import { type SystemStateFirestoreCollection } from '@dereekb/firebase';
 import { type ZohoAccountsAccessTokenCacheService } from '@dereekb/zoho/nestjs';
 /**
- * Creates a ZohoAccountsAccessTokenCacheService from the input SystemStateFirestoreCollection.
+ * Creates a {@link ZohoAccountsAccessTokenCacheService} backed by Firestore {@link SystemState} documents.
  *
- * @param collection
+ * Each Zoho service integration gets its own cached access token entry keyed by the service key.
+ * Tokens are stored in a single {@link SystemState} document (type {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE})
+ * and token updates/clears use Firestore transactions for concurrency safety.
+ *
+ * @param systemStateCollection - the Firestore collection for system state documents
+ *
+ * @example
+ * ```ts
+ * const cacheService = firebaseZohoAccountsAccessTokenCacheService(systemStateCollection);
+ * const cache = cacheService.loadZohoAccessTokenCache('my-zoho-service');
+ * const token = await cache.loadCachedToken();
+ * ```
  */
 export declare function firebaseZohoAccountsAccessTokenCacheService(systemStateCollection: SystemStateFirestoreCollection): ZohoAccountsAccessTokenCacheService;

package/zoho/src/lib/zoho.accounts.firebase.system.d.ts

@@ -1,7 +1,14 @@
 import { type ZohoAccessToken, type ZohoServiceAccessTokenKey } from '@dereekb/zoho';
 import { type FirestoreDocumentAccessor, type SystemState, type SystemStateDocument, type SystemStateStoredData, type SystemStateStoredDataFieldConverterConfig } from '@dereekb/firebase';
 import { type Configurable } from '@dereekb/util';
+/**
+ * {@link SystemState} type identifier for storing Zoho access tokens in Firestore.
+ */
 export declare const ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE = "zoho_access_token";
+/**
+ * Represents a single Zoho access token stored within the {@link SystemState} document,
+ * keyed by the service access token key to support multiple Zoho service integrations.
+ */
 export interface ZohoAccessTokenSystemStateEmbeddedToken extends Configurable<ZohoAccessToken> {
     /**
      * The access token key
@@ -9,24 +16,40 @@ export interface ZohoAccessTokenSystemStateEmbeddedToken extends Configurable<Zo
     key: ZohoServiceAccessTokenKey;
 }
 export declare const zohoAccessTokenSystemStateEmbeddedTokenConverter: import("@dereekb/firebase").FirestoreSubObjectFieldMapFunctionsConfig<ZohoAccessTokenSystemStateEmbeddedToken, Partial<import("@dereekb/util").ReplaceType<ZohoAccessTokenSystemStateEmbeddedToken, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Data shape stored within a {@link SystemState} document for caching multiple Zoho access tokens.
+ *
+ * Expired tokens are automatically filtered out during Firestore read via the converter,
+ * and only one token per service key is retained (enforced by {@link filterUniqueFunction}).
+ */
 export interface ZohoAccessTokenSystemStateData extends SystemStateStoredData {
     /**
-     * The array of access tokens
+     * The array of cached access tokens, one per Zoho service integration.
      */
     tokens: ZohoAccessTokenSystemStateEmbeddedToken[];
     /**
-     * Last updated at
+     * Timestamp of the last token update.
      */
     lat: Date;
 }
 /**
- * NOTE: Be sure to register this data converter with the SystemStateStoredDataConverterMap for your app.
+ * Firestore field converter for {@link ZohoAccessTokenSystemStateData}.
+ *
+ * Automatically filters out expired tokens on read and enforces uniqueness by service key.
+ * Must be registered in the app's {@link SystemStateStoredDataConverterMap} under
+ * the {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} key.
  */
 export declare const zohoAccessTokenSystemStateDataConverter: SystemStateStoredDataFieldConverterConfig<ZohoAccessTokenSystemStateData>;
 /**
- * Convenience function for loading the document for ZohoAccessTokenSystemStateData.
+ * Loads the {@link SystemStateDocument} that stores {@link ZohoAccessTokenSystemStateData},
+ * using {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} as the document ID.
+ *
+ * @param accessor - the document accessor for the SystemState collection
  *
- * @param accessor
- * @returns
+ * @example
+ * ```ts
+ * const doc = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessor());
+ * const data = await doc.snapshotData();
+ * ```
  */
 export declare function loadZohoAccessTokenSystemState(accessor: FirestoreDocumentAccessor<SystemState<SystemStateStoredData>, SystemStateDocument<SystemStateStoredData>>): SystemStateDocument<ZohoAccessTokenSystemStateData>;