@dereekb/calcom 13.32.0 → 13.34.0

package/nestjs/index.esm.js

@@ -1,5 +1,5 @@
-import { Injectable, Inject, Logger, Post, Res, Req, Controller, Module } from '@nestjs/common';
-import { calcomOAuthFactory, exchangeAuthorizationCode, calcomFactory, getMe, getSchedules, createBooking, getBooking, cancelBooking, getEventTypes, createEventType, updateEventType, deleteEventType, getCalendars, getBusyTimes, createWebhook, getWebhooks, getWebhook, updateWebhook, deleteWebhook, getAvailableSlots } from '@dereekb/calcom';
+import { Logger, Injectable, Inject, Post, Res, Req, Controller, Module } from '@nestjs/common';
+import { calcomOAuthFactory, calcomAuthCredentialFromValues, exchangeAuthorizationCode, calcomAccessTokenFromTokenResponse, calcomFactory, getMe, getSchedules, createBooking, getBooking, cancelBooking, getEventTypes, createEventType, updateEventType, deleteEventType, getCalendars, getBusyTimes, createWebhook, getWebhooks, getWebhook, updateWebhook, deleteWebhook, getAvailableSlots } from '@dereekb/calcom';
 import { inMemoryAsyncValueCache, inMemoryAsyncKeyedValueCache, mergeAsyncValueCaches, isExpired, filterMaybeArrayValues, cachedGetter, handlerFactory, handlerConfigurerFactory, handlerMappedSetFunctionFactory } from '@dereekb/util';
 import { createMemoizedJsonFileAsyncValueCache, RawBody } from '@dereekb/nestjs';
 import { createHash, createHmac } from 'node:crypto';
@@ -78,6 +78,8 @@ var CALCOM_API_KEY_CONFIG_KEY = 'CALCOM_API_KEY';
                 if (!calcomOAuth) {
                     throw new Error('CalcomOAuthServiceConfig.calcomOAuth is required');
                 }
+                // mirrors the guard in calcomOAuthFactory(): an api key IS a token, anything else is an exchange
+                // the token endpoint authenticates with the client pair. The two must not drift
                 var hasApiKey = !!calcomOAuth.apiKey;
                 var hasOAuth = !!calcomOAuth.clientId && !!calcomOAuth.clientSecret;
                 if (!hasApiKey && !hasOAuth) {
@@ -106,6 +108,12 @@ var CALCOM_API_KEY_CONFIG_KEY = 'CALCOM_API_KEY';
             apiKey: apiKey || undefined
         }
     };
+    // the api key wins for ambient calls because it does not expire, so a configured refresh token is
+    // silently unused. Warned here rather than in assertValidConfig, which tests call directly and
+    // which stays side-effect-free
+    if (apiKey && refreshToken) {
+        new Logger('CalcomOAuthServiceConfig').warn("Both ".concat(CALCOM_API_KEY_CONFIG_KEY, " and ").concat(CALCOM_REFRESH_TOKEN_CONFIG_KEY, " are set. The api key takes precedence for ambient calls and the refresh token is ignored — unset one to make the intent explicit."));
+    }
     CalcomOAuthServiceConfig.assertValidConfig(config);
     return config;
 }
@@ -121,7 +129,7 @@ function _array_with_holes(arr) {
 function _array_without_holes$3(arr) {
     if (Array.isArray(arr)) return _array_like_to_array$3(arr);
 }
-function asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, key, arg) {
+function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
         var value = info.value;
@@ -135,16 +143,16 @@ function asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, key, arg) {
         Promise.resolve(value).then(_next, _throw);
     }
 }
-function _async_to_generator$2(fn) {
+function _async_to_generator$3(fn) {
     return function() {
         var self = this, args = arguments;
         return new Promise(function(resolve, reject) {
             var gen = fn.apply(self, args);
             function _next(value) {
-                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "next", value);
+                asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, "next", value);
             }
             function _throw(err) {
-                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "throw", err);
+                asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, "throw", err);
             }
             _next(undefined);
         });
@@ -261,7 +269,7 @@ function _unsupported_iterable_to_array$3(o, minLen) {
     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$3(o, minLen);
 }
-function _ts_generator$2(thisArg, body) {
+function _ts_generator$3(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
         sent: function() {
@@ -365,7 +373,8 @@ function _ts_generator$2(thisArg, body) {
  *
  * Implementations store and retrieve OAuth access tokens (and the rotated refresh tokens
  * embedded in them). The service supports both a server-level cache and per-user caches
- * keyed by the user's initial refresh token.
+ * keyed either by a caller-owned key ({@link cacheForKey}) or by the user's refresh token
+ * ({@link cacheForRefreshToken}).
  */ var CalcomOAuthAccessTokenCacheService = function CalcomOAuthAccessTokenCacheService() {
     _class_call_check$7(this, CalcomOAuthAccessTokenCacheService);
 };
@@ -382,13 +391,29 @@ CalcomOAuthAccessTokenCacheService = __decorate([
  */ function calcomRefreshTokenCacheKey(refreshToken) {
     return createHash('sha256').update(refreshToken).digest('hex').substring(0, 16);
 }
+/**
+ * Matches any character that is unsafe in a filesystem path segment.
+ */ var UNSAFE_CALCOM_CACHE_FILE_KEY_CHARACTERS_REGEX = /[^a-zA-Z0-9_-]/g;
+/**
+ * Converts a cache key into a filesystem-safe path segment.
+ *
+ * A key that is already safe (such as the hex output of {@link calcomRefreshTokenCacheKey}) is
+ * returned unchanged. Otherwise the unsafe characters are replaced and a hash of the original key
+ * is appended, so two different keys can never collapse onto the same file.
+ *
+ * @param key - The cache key to convert.
+ * @returns A filesystem-safe path segment for the key.
+ */ function calcomAccessTokenCacheFileKey(key) {
+    var safeKey = key.replaceAll(UNSAFE_CALCOM_CACHE_FILE_KEY_CHARACTERS_REGEX, '_');
+    return safeKey === key ? key : "".concat(safeKey, "-").concat(createHash('sha256').update(key).digest('hex').substring(0, 8));
+}
 // MARK: Merge
 function buildCalcomReadAdapter(cache) {
     return {
         load: function load() {
-            return _async_to_generator$2(function() {
+            return _async_to_generator$3(function() {
                 var value;
-                return _ts_generator$2(this, function(_state) {
+                return _ts_generator$3(this, function(_state) {
                     switch(_state.label){
                         case 0:
                             return [
@@ -411,8 +436,8 @@ function buildCalcomReadAdapter(cache) {
             return cache.updateCachedToken(token);
         },
         clear: function clear() {
-            return _async_to_generator$2(function() {
-                return _ts_generator$2(this, function(_state) {
+            return _async_to_generator$3(function() {
+                return _ts_generator$3(this, function(_state) {
                     return [
                         2
                     ];
@@ -473,9 +498,9 @@ function updateCalcomCacheCapturingError(cache, accessToken) {
                 return merged.load();
             },
             updateCachedToken: function updateCachedToken(accessToken) {
-                return _async_to_generator$2(function() {
+                return _async_to_generator$3(function() {
                     var settled, failedUpdates;
-                    return _ts_generator$2(this, function(_state) {
+                    return _ts_generator$3(this, function(_state) {
                         switch(_state.label){
                             case 0:
                                 return [
@@ -509,16 +534,26 @@ function updateCalcomCacheCapturingError(cache, accessToken) {
     var allServicesWithCacheForRefreshToken = allServices.filter(function(x) {
         return x.cacheForRefreshToken != null;
     });
+    var allServicesWithCacheForKey = allServices.filter(function(x) {
+        return x.cacheForKey != null;
+    });
     var cacheForRefreshToken = allServicesWithCacheForRefreshToken.length > 0 ? function(refreshToken) {
         var allCaches = allServicesWithCacheForRefreshToken.map(function(x) {
             return x.cacheForRefreshToken(refreshToken);
         });
         return mergeCachesForService(allCaches);
     } : undefined;
+    var cacheForKey = allServicesWithCacheForKey.length > 0 ? function(key) {
+        var allCaches = allServicesWithCacheForKey.map(function(x) {
+            return x.cacheForKey(key);
+        });
+        return mergeCachesForService(allCaches);
+    } : undefined;
     var service = {
         loadCalcomAccessTokenCache: function loadCalcomAccessTokenCache() {
             return mergeCachesForService(allServiceAccessTokenCaches);
         },
+        cacheForKey: cacheForKey,
         cacheForRefreshToken: cacheForRefreshToken
     };
     return service;
@@ -533,9 +568,9 @@ function updateCalcomCacheCapturingError(cache, accessToken) {
  */ function calcomAccessTokenCacheFromAsyncValueCache(cache, logAccessToConsole) {
     return {
         loadCachedToken: function loadCachedToken() {
-            return _async_to_generator$2(function() {
+            return _async_to_generator$3(function() {
                 var token;
-                return _ts_generator$2(this, function(_state) {
+                return _ts_generator$3(this, function(_state) {
                     switch(_state.label){
                         case 0:
                             return [
@@ -559,8 +594,8 @@ function updateCalcomCacheCapturingError(cache, accessToken) {
             })();
         },
         updateCachedToken: function updateCachedToken(accessToken) {
-            return _async_to_generator$2(function() {
-                return _ts_generator$2(this, function(_state) {
+            return _async_to_generator$3(function() {
+                return _ts_generator$3(this, function(_state) {
                     switch(_state.label){
                         case 0:
                             return [
@@ -609,13 +644,16 @@ function updateCalcomCacheCapturingError(cache, accessToken) {
             }
         };
     }
+    function cacheForKey(key) {
+        return calcomAccessTokenCacheFromAsyncValueCache(userCacheView(key), logAccessToConsole);
+    }
     return {
         loadCalcomAccessTokenCache: function loadCalcomAccessTokenCache() {
             return calcomAccessTokenCacheFromAsyncValueCache(serverCache, logAccessToConsole);
         },
+        cacheForKey: cacheForKey,
         cacheForRefreshToken: function cacheForRefreshToken(refreshToken) {
-            var key = calcomRefreshTokenCacheKey(refreshToken);
-            return calcomAccessTokenCacheFromAsyncValueCache(userCacheView(key), logAccessToConsole);
+            return cacheForKey(calcomRefreshTokenCacheKey(refreshToken));
         }
     };
 }
@@ -689,9 +727,9 @@ var CALCOM_SERVER_TOKEN_FILE_KEY = 'server';
                 return cache.load();
             },
             updateCachedToken: function updateCachedToken(accessToken) {
-                return _async_to_generator$2(function() {
+                return _async_to_generator$3(function() {
                     var e;
-                    return _ts_generator$2(this, function(_state) {
+                    return _ts_generator$3(this, function(_state) {
                         switch(_state.label){
                             case 0:
                                 _state.trys.push([
@@ -724,17 +762,50 @@ var CALCOM_SERVER_TOKEN_FILE_KEY = 'server';
             }
         };
     }
+    function cacheForCallerKey(key) {
+        return makeCacheForKey("user-".concat(calcomAccessTokenCacheFileKey(key)));
+    }
     return {
         cacheDir: cacheDir,
         loadCalcomAccessTokenCache: function loadCalcomAccessTokenCache() {
             return makeCacheForKey(CALCOM_SERVER_TOKEN_FILE_KEY);
         },
+        cacheForKey: cacheForCallerKey,
         cacheForRefreshToken: function cacheForRefreshToken(refreshToken) {
-            return makeCacheForKey("user-".concat(calcomRefreshTokenCacheKey(refreshToken)));
+            return cacheForCallerKey(calcomRefreshTokenCacheKey(refreshToken));
         }
     };
 }
 
+function asyncGeneratorStep$2(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$2(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
 function _class_call_check$6(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
@@ -766,6 +837,105 @@ function _define_property$6(obj, key, value) {
     }
     return obj;
 }
+function _ts_generator$2(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
+        };
+    }
+}
 var CalcomOAuthApi = /*#__PURE__*/ function() {
     function CalcomOAuthApi(config, cacheService) {
         _class_call_check$6(this, CalcomOAuthApi);
@@ -777,12 +947,20 @@ var CalcomOAuthApi = /*#__PURE__*/ function() {
         this.cacheService = cacheService;
         var accessTokenCache = cacheService.loadCalcomAccessTokenCache();
         var _config_calcomOAuth = config.calcomOAuth, clientId = _config_calcomOAuth.clientId, clientSecret = _config_calcomOAuth.clientSecret, refreshToken = _config_calcomOAuth.refreshToken, apiKey = _config_calcomOAuth.apiKey;
+        // the environment-facing config stays flat, mirroring the CALCOM_* variables it is read from.
+        // `client` is the app's OAuth registration, sent on every exchange; `defaultAuth` is the one
+        // credential the ambient loadAccessToken() resolves. The client is taken as a pair or not at all,
+        // which replaces the empty-string sentinels this used to pass for a config with no OAuth client
         this.calcomOAuth = calcomOAuthFactory((_config_factoryConfig = config.factoryConfig) !== null && _config_factoryConfig !== void 0 ? _config_factoryConfig : {})({
-            accessTokenCache: accessTokenCache,
-            clientId: clientId !== null && clientId !== void 0 ? clientId : '',
-            clientSecret: clientSecret !== null && clientSecret !== void 0 ? clientSecret : '',
-            refreshToken: refreshToken,
-            apiKey: apiKey
+            client: clientId && clientSecret ? {
+                clientId: clientId,
+                clientSecret: clientSecret
+            } : undefined,
+            defaultAuth: calcomAuthCredentialFromValues({
+                apiKey: apiKey,
+                refreshToken: refreshToken,
+                accessTokenCache: accessTokenCache
+            })
         });
     }
     _create_class$5(CalcomOAuthApi, [
@@ -803,23 +981,80 @@ var CalcomOAuthApi = /*#__PURE__*/ function() {
                 return exchangeAuthorizationCode(this.oauthContext);
             }
         },
+        {
+            key: "exchangeAuthorizationCodeToAccessToken",
+            value: /**
+     * Exchanges an OAuth authorization code and maps the response to a {@link CalcomAccessToken}.
+     *
+     * The returned `refreshToken` is the one to persist: Cal.com rotates refresh tokens on every use.
+     *
+     * @param input - The authorization code and the exact redirect URI it was issued for.
+     * @returns The exchanged access token.
+     */ function exchangeAuthorizationCodeToAccessToken(input) {
+                return _async_to_generator$2(function() {
+                    var response;
+                    return _ts_generator$2(this, function(_state) {
+                        switch(_state.label){
+                            case 0:
+                                return [
+                                    4,
+                                    this.exchangeAuthorizationCode(input)
+                                ];
+                            case 1:
+                                response = _state.sent();
+                                return [
+                                    2,
+                                    calcomAccessTokenFromTokenResponse(response)
+                                ];
+                        }
+                    });
+                }).call(this);
+            }
+        },
         {
             /**
      * Retrieves an access token for a specific user using their refresh token.
      *
-     * @param input - Contains the user's refresh token and optional access token cache.
-     * @param input.refreshToken - The user's OAuth refresh token.
-     * @param input.userAccessTokenCache - Optional cache to store/retrieve the user's access token.
+     * @param credential - The user's refresh token credential, with the cache scoped to that grant.
      * @returns Promise resolving to the user's CalcomAccessToken.
      */ key: "userAccessToken",
-            value: function userAccessToken(input) {
-                var factory = this.oauthContext.makeUserAccessTokenFactory(input);
-                return factory();
+            value: function userAccessToken(credential) {
+                return this.userAccessTokenFactory(credential)();
+            }
+        },
+        {
+            /**
+     * Returns the CalcomAccessTokenFactory for a user's credential.
+     *
+     * A fresh factory on every call: its in-memory tier lives only as long as the returned factory, so
+     * one caller's tokens are never visible to the next. Durable sharing is the access token cache's
+     * job — see {@link cacheForKey}.
+     *
+     * @param credential - The user's refresh token credential.
+     * @returns The CalcomAccessTokenFactory for that credential.
+     */ key: "userAccessTokenFactory",
+            value: function userAccessTokenFactory(credential) {
+                return this.oauthContext.makeAccessTokenFactory(credential);
             }
         },
         {
             /**
-     * Returns a per-user CalcomAccessTokenCache derived from the refresh token (md5 hashed as the file key).
+     * Returns a per-user CalcomAccessTokenCache for a stable, caller-owned key.
+     * Returns undefined if the cache service does not support keyed caching.
+     *
+     * Preferred over {@link cacheForRefreshToken}, whose key changes as Cal.com rotates the token.
+     *
+     * @param key - A stable key identifying the user, such as their user or profile id.
+     * @returns A per-user access token cache, or undefined if not supported.
+     */ key: "cacheForKey",
+            value: function cacheForKey(key) {
+                var _this_cacheService_cacheForKey, _this_cacheService;
+                return (_this_cacheService_cacheForKey = (_this_cacheService = this.cacheService).cacheForKey) === null || _this_cacheService_cacheForKey === void 0 ? void 0 : _this_cacheService_cacheForKey.call(_this_cacheService, key);
+            }
+        },
+        {
+            /**
+     * Returns a per-user CalcomAccessTokenCache derived from a hash of the refresh token.
      * Returns undefined if the cache service does not support per-user caching.
      *
      * @param refreshToken - The user's OAuth refresh token used to derive the cache key.
@@ -1088,7 +1323,7 @@ function _object_spread_props$1(target, source) {
      * resolved from the cache service using an md5 hash of the refresh token as the key.
      * This ensures tokens persist across requests and server restarts without collisions.
      *
-     * @param input - The user context factory input containing the refresh token and optional cache.
+     * @param credential - The user's refresh token credential, with an optional cache scoped to that grant.
      * @returns A new CalcomApiContextInstance scoped to the user.
      *
      * @example
@@ -1105,16 +1340,13 @@ function _object_spread_props$1(target, source) {
      * });
      * ```
      */ key: "makeUserContextInstance",
-            value: function makeUserContextInstance(input) {
-                var contextInput = _object_spread$1({}, input);
-                // Auto-resolve per-user cache from the refresh token if no explicit cache was given
-                if (!contextInput.accessTokenCache && contextInput.refreshToken) {
-                    var userCache = this.calcomOAuthApi.cacheForRefreshToken(contextInput.refreshToken);
-                    if (userCache) {
-                        contextInput.accessTokenCache = userCache;
-                    }
-                }
-                var userContext = this.calcom.calcomServerContext.makeUserContext(contextInput);
+            value: function makeUserContextInstance(credential) {
+                var _credential_accessTokenCache;
+                // auto-resolve a per-user cache from the refresh token when none was given
+                var accessTokenCache = (_credential_accessTokenCache = credential.accessTokenCache) !== null && _credential_accessTokenCache !== void 0 ? _credential_accessTokenCache : this.calcomOAuthApi.cacheForRefreshToken(credential.refreshToken);
+                var userContext = this.calcom.calcomServerContext.makeUserContext(_object_spread_props$1(_object_spread$1({}, credential), {
+                    accessTokenCache: accessTokenCache
+                }));
                 return this.makeContextInstance(userContext);
             }
         },
@@ -1134,11 +1366,11 @@ function _object_spread_props$1(target, source) {
      * Creates a raw {@link CalcomUserContext} from a refresh token, without wrapping in a {@link CalcomApiContextInstance}.
      * Prefer {@link makeUserContextInstance} unless you need direct context access.
      *
-     * @param input - The user context factory input containing the refresh token and optional cache.
+     * @param credential - The user's refresh token credential, with the cache scoped to that grant.
      * @returns A CalcomUserContext for the given user.
      */ key: "makeUserContext",
-            value: function makeUserContext(input) {
-                return this.calcom.calcomServerContext.makeUserContext(input);
+            value: function makeUserContext(credential) {
+                return this.calcom.calcomServerContext.makeUserContext(credential);
             }
         }
     ]);
@@ -2137,4 +2369,4 @@ CalcomWebhookModule = __decorate([
     };
 }
 
-export { CALCOM_API_KEY_CONFIG_KEY, CALCOM_CLIENT_ID_CONFIG_KEY, CALCOM_CLIENT_SECRET_CONFIG_KEY, CALCOM_REFRESH_TOKEN_CONFIG_KEY, CALCOM_SERVER_TOKEN_FILE_KEY, CALCOM_SERVICE_NAME, CALCOM_WEBHOOK_BOOKING_CANCELLED, CALCOM_WEBHOOK_BOOKING_CONFIRMED, CALCOM_WEBHOOK_BOOKING_CREATED, CALCOM_WEBHOOK_BOOKING_RESCHEDULED, CALCOM_WEBHOOK_SECRET_CONFIG_KEY, CalcomApi, CalcomApiContextInstance, CalcomOAuthAccessTokenCacheService, CalcomOAuthApi, CalcomOAuthServiceConfig, CalcomServiceConfig, CalcomWebhookController, CalcomWebhookModule, CalcomWebhookService, CalcomWebhookServiceConfig, DEFAULT_FILE_CALCOM_ACCESS_TOKEN_CACHE_DIR, appCalcomModuleMetadata, appCalcomOAuthModuleMetadata, appCalcomWebhookModuleMetadata, calcomEventHandlerConfigurerFactory, calcomEventHandlerFactory, calcomOAuthServiceConfigFactory, calcomRefreshTokenCacheKey, calcomServiceConfigFactory, calcomWebhookEvent, calcomWebhookEventVerifier, calcomWebhookServiceConfigFactory, fileCalcomOAuthAccessTokenCacheService, logMergeCalcomOAuthAccessTokenCacheServiceErrorFunction, memoryCalcomOAuthAccessTokenCacheService, mergeCalcomOAuthAccessTokenCacheServices };
+export { CALCOM_API_KEY_CONFIG_KEY, CALCOM_CLIENT_ID_CONFIG_KEY, CALCOM_CLIENT_SECRET_CONFIG_KEY, CALCOM_REFRESH_TOKEN_CONFIG_KEY, CALCOM_SERVER_TOKEN_FILE_KEY, CALCOM_SERVICE_NAME, CALCOM_WEBHOOK_BOOKING_CANCELLED, CALCOM_WEBHOOK_BOOKING_CONFIRMED, CALCOM_WEBHOOK_BOOKING_CREATED, CALCOM_WEBHOOK_BOOKING_RESCHEDULED, CALCOM_WEBHOOK_SECRET_CONFIG_KEY, CalcomApi, CalcomApiContextInstance, CalcomOAuthAccessTokenCacheService, CalcomOAuthApi, CalcomOAuthServiceConfig, CalcomServiceConfig, CalcomWebhookController, CalcomWebhookModule, CalcomWebhookService, CalcomWebhookServiceConfig, DEFAULT_FILE_CALCOM_ACCESS_TOKEN_CACHE_DIR, appCalcomModuleMetadata, appCalcomOAuthModuleMetadata, appCalcomWebhookModuleMetadata, calcomAccessTokenCacheFileKey, calcomEventHandlerConfigurerFactory, calcomEventHandlerFactory, calcomOAuthServiceConfigFactory, calcomRefreshTokenCacheKey, calcomServiceConfigFactory, calcomWebhookEvent, calcomWebhookEventVerifier, calcomWebhookServiceConfigFactory, fileCalcomOAuthAccessTokenCacheService, logMergeCalcomOAuthAccessTokenCacheServiceErrorFunction, memoryCalcomOAuthAccessTokenCacheService, mergeCalcomOAuthAccessTokenCacheServices };

package/nestjs/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/calcom/nestjs",
-  "version": "13.32.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/nestjs": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/util": "13.32.0",
-    "@dereekb/calcom": "13.32.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0",
+    "@dereekb/calcom": "13.34.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1"

package/nestjs/src/lib/calcom/calcom.api.d.ts

@@ -1,5 +1,5 @@
 import { CalcomServiceConfig } from './calcom.config';
-import { type Calcom, type CalcomContext, type CalcomServerContext, type CalcomUserContext, type CalcomUserContextFactoryInput } from '@dereekb/calcom';
+import { type Calcom, type CalcomContext, type CalcomServerContext, type CalcomUserContext, type CalcomRefreshTokenCredential } from '@dereekb/calcom';
 import { CalcomOAuthApi } from '../oauth';
 /**
  * Injectable NestJS service that provides access to the Cal.com API.
@@ -50,7 +50,7 @@ export declare class CalcomApi {
      * resolved from the cache service using an md5 hash of the refresh token as the key.
      * This ensures tokens persist across requests and server restarts without collisions.
      *
-     * @param input - The user context factory input containing the refresh token and optional cache.
+     * @param credential - The user's refresh token credential, with an optional cache scoped to that grant.
      * @returns A new CalcomApiContextInstance scoped to the user.
      *
      * @example
@@ -67,7 +67,7 @@ export declare class CalcomApi {
      * });
      * ```
      */
-    makeUserContextInstance(input: CalcomUserContextFactoryInput): CalcomApiContextInstance;
+    makeUserContextInstance(credential: CalcomRefreshTokenCredential): CalcomApiContextInstance;
     /**
      * Creates a {@link CalcomApiContextInstance} from any {@link CalcomContext}.
      *
@@ -79,10 +79,10 @@ export declare class CalcomApi {
      * Creates a raw {@link CalcomUserContext} from a refresh token, without wrapping in a {@link CalcomApiContextInstance}.
      * Prefer {@link makeUserContextInstance} unless you need direct context access.
      *
-     * @param input - The user context factory input containing the refresh token and optional cache.
+     * @param credential - The user's refresh token credential, with the cache scoped to that grant.
      * @returns A CalcomUserContext for the given user.
      */
-    makeUserContext(input: CalcomUserContextFactoryInput): CalcomUserContext;
+    makeUserContext(credential: CalcomRefreshTokenCredential): CalcomUserContext;
 }
 /**
  * Wraps a {@link CalcomContext} (server or user) and exposes all authenticated Cal.com API

package/nestjs/src/lib/oauth/oauth.api.d.ts

@@ -1,4 +1,4 @@
-import { type CalcomAccessTokenCache, type CalcomOAuth, type CalcomOAuthContext, type CalcomRefreshToken } from '@dereekb/calcom';
+import { type CalcomAccessToken, type CalcomAccessTokenCache, type CalcomAccessTokenCacheKey, type CalcomAccessTokenFactory, type CalcomOAuth, type CalcomOAuthContext, type CalcomOAuthExchangeAuthorizationCodeInput, type CalcomRefreshToken, type CalcomRefreshTokenCredential } from '@dereekb/calcom';
 import { type Maybe } from '@dereekb/util';
 import { CalcomOAuthServiceConfig } from './oauth.config';
 import { CalcomOAuthAccessTokenCacheService } from './oauth.service';
@@ -13,21 +13,46 @@ export declare class CalcomOAuthApi {
      *
      * @returns Function to exchange an OAuth authorization code for tokens.
      */
-    get exchangeAuthorizationCode(): (input: import("@dereekb/calcom").CalcomOAuthExchangeAuthorizationCodeInput) => Promise<import("@dereekb/calcom").CalcomOAuthTokenResponse>;
+    get exchangeAuthorizationCode(): (input: CalcomOAuthExchangeAuthorizationCodeInput) => Promise<import("@dereekb/calcom").CalcomOAuthTokenResponse>;
+    /**
+     * Exchanges an OAuth authorization code and maps the response to a {@link CalcomAccessToken}.
+     *
+     * The returned `refreshToken` is the one to persist: Cal.com rotates refresh tokens on every use.
+     *
+     * @param input - The authorization code and the exact redirect URI it was issued for.
+     * @returns The exchanged access token.
+     */
+    exchangeAuthorizationCodeToAccessToken(input: CalcomOAuthExchangeAuthorizationCodeInput): Promise<CalcomAccessToken>;
     /**
      * Retrieves an access token for a specific user using their refresh token.
      *
-     * @param input - Contains the user's refresh token and optional access token cache.
-     * @param input.refreshToken - The user's OAuth refresh token.
-     * @param input.userAccessTokenCache - Optional cache to store/retrieve the user's access token.
+     * @param credential - The user's refresh token credential, with the cache scoped to that grant.
      * @returns Promise resolving to the user's CalcomAccessToken.
      */
-    userAccessToken(input: {
-        refreshToken: string;
-        userAccessTokenCache?: Maybe<CalcomAccessTokenCache>;
-    }): Promise<import("@dereekb/calcom").CalcomAccessToken>;
+    userAccessToken(credential: CalcomRefreshTokenCredential): Promise<CalcomAccessToken>;
+    /**
+     * Returns the CalcomAccessTokenFactory for a user's credential.
+     *
+     * A fresh factory on every call: its in-memory tier lives only as long as the returned factory, so
+     * one caller's tokens are never visible to the next. Durable sharing is the access token cache's
+     * job — see {@link cacheForKey}.
+     *
+     * @param credential - The user's refresh token credential.
+     * @returns The CalcomAccessTokenFactory for that credential.
+     */
+    userAccessTokenFactory(credential: CalcomRefreshTokenCredential): CalcomAccessTokenFactory;
+    /**
+     * Returns a per-user CalcomAccessTokenCache for a stable, caller-owned key.
+     * Returns undefined if the cache service does not support keyed caching.
+     *
+     * Preferred over {@link cacheForRefreshToken}, whose key changes as Cal.com rotates the token.
+     *
+     * @param key - A stable key identifying the user, such as their user or profile id.
+     * @returns A per-user access token cache, or undefined if not supported.
+     */
+    cacheForKey(key: CalcomAccessTokenCacheKey): Maybe<CalcomAccessTokenCache>;
     /**
-     * Returns a per-user CalcomAccessTokenCache derived from the refresh token (md5 hashed as the file key).
+     * Returns a per-user CalcomAccessTokenCache derived from a hash of the refresh token.
      * Returns undefined if the cache service does not support per-user caching.
      *
      * @param refreshToken - The user's OAuth refresh token used to derive the cache key.