@dereekb/firebase-server 13.31.0 → 13.33.0

package/calcom/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dereekb/firebase-server/calcom",
+  "version": "13.33.0",
+  "peerDependencies": {
+    "@dereekb/analytics": "13.33.0",
+    "@dereekb/calcom": "13.33.0",
+    "@dereekb/date": "13.33.0",
+    "@dereekb/firebase": "13.33.0",
+    "@dereekb/firebase-server": "13.33.0",
+    "@dereekb/model": "13.33.0",
+    "@dereekb/nestjs": "13.33.0",
+    "@dereekb/rxjs": "13.33.0",
+    "@dereekb/util": "13.33.0",
+    "@nestjs/common": "^11.1.19",
+    "express": "^5.2.1"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/calcom/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/calcom/src/lib/calcom.oauth.connection.cache.d.ts

@@ -0,0 +1,49 @@
+import { type CalcomAccessToken, type CalcomAccessTokenCache } from '@dereekb/calcom';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type UserExternalConnectionAccessor, type UserExternalConnectionCredentials, type UserExternalConnectionCredentialsWriter } from '@dereekb/firebase-server/model';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Maps stored connection credentials to a {@link CalcomAccessToken}.
+ *
+ * @param credentials - The credentials stored for the `calcom` provider.
+ * @returns The equivalent Cal.com access token, or null when the credentials cannot form one.
+ */
+export declare function calcomAccessTokenFromUserExternalConnectionCredentials(credentials: Maybe<UserExternalConnectionCredentials>): Maybe<CalcomAccessToken>;
+/**
+ * Configuration for {@link userExternalConnectionCalcomAccessTokenCache}.
+ */
+export interface UserExternalConnectionCalcomAccessTokenCacheConfig {
+    /**
+     * Used to read the user's currently stored Cal.com credentials.
+     *
+     * The accessor rather than `UserExternalConnectionReader`: the contract below is explicitly that an
+     * EXPIRED token may be returned, so a surface that could refresh would be the wrong tool — see
+     * `loadCachedToken`.
+     */
+    readonly accessor: UserExternalConnectionAccessor;
+    /**
+     * Used to persist a rotated token back onto the connection pair.
+     */
+    readonly actions: UserExternalConnectionCredentialsWriter;
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * Creates a {@link CalcomAccessTokenCache} backed by a user's UserExternalConnection pair.
+ *
+ * This is what keeps a Cal.com connection working past its first refresh. Cal.com invalidates a
+ * refresh token on every use and returns a rotated one, but it hands that rotated token to its
+ * `CalcomAccessTokenCache` — not back to us. With the default in-memory or file cache, the token
+ * stored on `uecp` is spent the first time it is used: nothing looks wrong, the entry stays
+ * `connected`, and the next process that starts with a cold cache replays a dead token.
+ *
+ * Pointing the cache at the connection pair makes the pair the single store of record, so a rotation
+ * is durable the moment it happens.
+ *
+ * Deliberately NOT registered as a `CalcomOAuthAccessTokenCacheService`: that service's `cacheForKey`
+ * is keyed by an opaque string, whereas this cache is per-user and needs a uid. Build one per user at
+ * the call site and pass it in explicitly.
+ *
+ * @param config - The accessor, the actions, and the user the cache is for.
+ * @returns A CalcomAccessTokenCache reading and writing the user's connection pair.
+ */
+export declare function userExternalConnectionCalcomAccessTokenCache(config: UserExternalConnectionCalcomAccessTokenCacheConfig): CalcomAccessTokenCache;

package/calcom/src/lib/calcom.oauth.connection.config.d.ts

@@ -0,0 +1,75 @@
+import { type CalcomOAuthScope } from '@dereekb/calcom';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { UserExternalConnectionOAuthServiceConfig } from '@dereekb/firebase-server/model';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Controller path the Cal.com external-connection OAuth endpoints are mounted at.
+ *
+ * Derived from the framework's path factory, the same expression the redirect URI and the
+ * global-prefix exclusion are built from, so the three cannot drift apart.
+ */
+export declare const CALCOM_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH: string;
+/**
+ * Routes to exclude from an app's global API route prefix so the Cal.com callback controller stays
+ * mounted at `/oauth/calcom/*`.
+ *
+ * Spread this into the `exclude` list of the app's `globalApiRoutePrefix` config, alongside
+ * `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`.
+ */
+export declare const CALCOM_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE: string[];
+/**
+ * The scopes requested when an app does not declare its own.
+ *
+ * Declared in code, deliberately NOT read from the environment: the set to request follows from what
+ * the integration actually does, so it is a property of the code rather than of a deployment.
+ * Requesting less than the code uses does not make it work — it moves the failure from the consent
+ * screen to the first API call.
+ *
+ * Least privilege for a per-user calendar connect: read which meeting types exist, read the user's
+ * availability, and read/write bookings. Excludes `EVENT_TYPE_WRITE` and `SCHEDULE_WRITE` —
+ * connecting a calendar does not involve editing the user's meeting types or availability — and
+ * `PROFILE_READ`, which is only needed to label the connection with the Cal.com account it belongs
+ * to.
+ *
+ * Cal.com refuses the authorize request outright when the requested set exceeds what the OAuth
+ * client is registered for ("Requested scope exceeds the client's registered scopes"). That is a
+ * registration problem: register the scopes the code needs, rather than narrowing the request to fit.
+ * An app whose integration genuinely does less can declare its own set on the module metadata, in
+ * code where it is reviewable.
+ */
+export declare const DEFAULT_CALCOM_OAUTH_SCOPES: readonly CalcomOAuthScope[];
+/**
+ * Configuration for the {@link CalcomUserExternalConnectionOAuthService}.
+ *
+ * Extends the framework config with the one thing that is Cal.com's own — which scopes to request.
+ */
+export declare abstract class CalcomUserExternalConnectionOAuthServiceConfig extends UserExternalConnectionOAuthServiceConfig {
+    readonly scopes: readonly CalcomOAuthScope[];
+}
+export interface CalcomUserExternalConnectionOAuthServiceConfigFactoryConfig {
+    readonly envService: FirebaseServerEnvService;
+    /**
+     * Path on the app URL the user is returned to after connecting, e.g. `/app/settings`.
+     */
+    readonly successPath: string;
+    /**
+     * Path on the app URL the user is returned to after a failed connect. Defaults to `successPath`.
+     */
+    readonly failurePath?: Maybe<string>;
+    /**
+     * The scopes to request. Defaults to {@link DEFAULT_CALCOM_OAUTH_SCOPES}.
+     */
+    readonly scopes?: Maybe<readonly CalcomOAuthScope[]>;
+}
+/**
+ * Builds the Cal.com connect flow's configuration from the app's configured origins.
+ *
+ * Nothing here is read from the environment as a value: the redirect URI is derived from the app's
+ * OAuth origin plus the mounted controller path, and the return URLs from the app URL plus
+ * code-declared paths. Registering Cal.com therefore adds no deployment configuration beyond the
+ * client credentials themselves.
+ *
+ * @param config - The env service, the return paths, and the optional scope override.
+ * @returns The validated service configuration.
+ */
+export declare function calcomUserExternalConnectionOAuthServiceConfigFactory(config: CalcomUserExternalConnectionOAuthServiceConfigFactoryConfig): CalcomUserExternalConnectionOAuthServiceConfig;

package/calcom/src/lib/calcom.oauth.connection.context.d.ts

@@ -0,0 +1,84 @@
+import { type CalcomApi, type CalcomApiContextInstance } from '@dereekb/calcom/nestjs';
+import { type FirebaseAuthUserIdRef, type UserExternalConnectionErrorCode } from '@dereekb/firebase';
+import { type UserExternalConnectionAccessor, type UserExternalConnectionCredentialsAndFailureWriter } from '@dereekb/firebase-server/model';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Maps an error thrown while calling Cal.com as a user to the code to record on their connection.
+ *
+ * Returns null for anything that is not the grant being refused — a rate limit, a validation error, a
+ * network failure, or a 403 all leave the connection itself intact, and marking it `error` for those
+ * would send the user to a reconnect that fixes nothing.
+ *
+ * @param error - The error thrown by a Cal.com call.
+ * @returns The error code to record, or null when the connection is not at fault.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionErrorCodeFromCalcomError(error: unknown): Maybe<UserExternalConnectionErrorCode>;
+/**
+ * Turns a uid into a Cal.com API instance that acts as that user.
+ *
+ * The provider-specific sibling of `UserExternalConnectionReader.readerForUser`, and the only correct
+ * way to make per-user Cal.com calls in an app that stores connections on the pair:
+ *
+ * ```ts
+ * const calcom = await calcomUserContextService.calcomUserContextForUser({ uid });
+ * const me = await calcom.getMe();
+ * ```
+ *
+ * Do NOT assemble this by hand from `readUsableUserExternalConnectionCredentials()`. Cal.com runs its
+ * own refresh loop through the access token cache, so a reader refresh followed by a library refresh
+ * spends a rotated refresh token twice and destroys one of two valid grants.
+ */
+export declare abstract class UserExternalConnectionCalcomUserContextService {
+    /**
+     * Builds a Cal.com API instance scoped to the given user.
+     *
+     * Token rotations land durably on the user's connection pair, and a refused grant is recorded on
+     * the connection entry before the error reaches the caller.
+     *
+     * @param input - The user to act as.
+     * @returns The Cal.com API instance for that user.
+     * @throws When the user is not connected to Cal.com, or their stored credentials carry no refresh
+     *   token and so cannot produce an access token.
+     */
+    abstract calcomUserContextForUser(input: FirebaseAuthUserIdRef): Promise<CalcomApiContextInstance>;
+}
+/**
+ * Reference to a {@link UserExternalConnectionCalcomUserContextService} instance.
+ */
+export interface UserExternalConnectionCalcomUserContextServiceRef {
+    readonly userExternalConnectionCalcomUserContextService: UserExternalConnectionCalcomUserContextService;
+}
+/**
+ * Configuration for {@link userExternalConnectionCalcomUserContextService}.
+ *
+ * Deliberately holds no surface that can refresh credentials itself. `UserExternalConnectionReader`
+ * is absent for that reason: its `readUsableUserExternalConnectionCredentials` is the one call this
+ * path must never make, and taking the accessor instead makes that mistake unrepresentable here.
+ */
+export interface UserExternalConnectionCalcomUserContextServiceConfig {
+    /**
+     * Builds the user context and wraps it into an API instance.
+     */
+    readonly calcomApi: CalcomApi;
+    /**
+     * Reads the stored refresh token, and backs the per-user token cache.
+     */
+    readonly accessor: UserExternalConnectionAccessor;
+    /**
+     * Persists a rotated token, and records a refused grant.
+     */
+    readonly actions: UserExternalConnectionCredentialsAndFailureWriter;
+}
+/**
+ * Creates a {@link UserExternalConnectionCalcomUserContextService}.
+ *
+ * Instances are NOT cached per user. Each call builds a fresh token factory, so the in-memory token
+ * tier lives only as long as the returned instance and one request's tokens are never visible to the
+ * next. The pair-backed cache means the cost of that is a document read, not a token refresh.
+ *
+ * @param config - The Cal.com API, the accessor, and the write surface.
+ * @returns A concrete UserExternalConnectionCalcomUserContextService implementation.
+ */
+export declare function userExternalConnectionCalcomUserContextService(config: UserExternalConnectionCalcomUserContextServiceConfig): UserExternalConnectionCalcomUserContextService;

package/calcom/src/lib/calcom.oauth.connection.controller.d.ts

@@ -0,0 +1,18 @@
+import { AbstractUserExternalConnectionOAuthController } from '@dereekb/firebase-server/model';
+import { CalcomUserExternalConnectionOAuthService } from './calcom.oauth.connection.service';
+/**
+ * Endpoints for the Cal.com external-connection authorization-code handoff.
+ *
+ * Mounted at `/oauth/calcom`, matching the Angular registry's default authorize path of
+ * `/oauth/<providerType>/authorize`. Hosting rewrites do not strip the path, so this prefix is the
+ * public path — but an app with a global API route prefix must ALSO exclude these routes from it via
+ * {@link CALCOM_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE}, or they land under
+ * that prefix instead and no longer match the redirect URI registered with Cal.com.
+ *
+ * The `authorize` and `callback` routes come from the base class, so this declares only where they
+ * mount and which service serves them.
+ */
+export declare class CalcomUserExternalConnectionOAuthController extends AbstractUserExternalConnectionOAuthController {
+    readonly oauthService: CalcomUserExternalConnectionOAuthService;
+    constructor(oauthService: CalcomUserExternalConnectionOAuthService);
+}

package/calcom/src/lib/calcom.oauth.connection.module.d.ts

@@ -0,0 +1,55 @@
+import { type ModuleMetadata, type Provider } from '@nestjs/common';
+import { type CalcomOAuthScope } from '@dereekb/calcom';
+import { type Maybe } from '@dereekb/util';
+export interface ProvideAppCalcomUserExternalConnectionOAuthMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * This module requires the following dependencies in order to initialize properly:
+     * - CalcomOAuthApi
+     *
+     * This module declaration makes it easier to import a module that exports that dependency.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+    /**
+     * Path on the app URL the user is returned to after connecting, e.g. `/app/settings`.
+     */
+    readonly successPath: string;
+    /**
+     * Path on the app URL the user is returned to after a failed connect. Defaults to `successPath`.
+     */
+    readonly failurePath?: Maybe<string>;
+    /**
+     * The scopes to request. Defaults to `DEFAULT_CALCOM_OAUTH_SCOPES`.
+     */
+    readonly scopes?: Maybe<readonly CalcomOAuthScope[]>;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's Cal.com external-connection
+ * OAuth module.
+ *
+ * Opt-in, like the webhook module: importing the Cal.com OAuth module alone never mounts HTTP
+ * routes, so an app that only makes outbound Cal.com calls exposes no endpoints.
+ *
+ * The importing module must also supply `UserExternalConnectionServerActions` and
+ * `UserExternalConnectionStateCoder` — both exported by `appUserExternalConnectionModuleMetadata`,
+ * so pass that module in `imports`.
+ *
+ * @param config - The module metadata configuration.
+ * @returns NestJS ModuleMetadata mounting the Cal.com connect endpoints.
+ */
+export declare function appCalcomUserExternalConnectionOAuthModuleMetadata(config: ProvideAppCalcomUserExternalConnectionOAuthMetadataConfig): ModuleMetadata;
+/**
+ * Creates the NestJS provider for the {@link UserExternalConnectionCalcomUserContextService}.
+ *
+ * A provider rather than a module, because the three tokens it needs are never declared together:
+ * `CalcomApi` comes from the app's Cal.com module and the accessor and actions from its
+ * UserExternalConnection module. Declare this in a module that imports both.
+ *
+ * Separate from {@link appCalcomUserExternalConnectionOAuthModuleMetadata} on purpose — that module
+ * needs only `CalcomOAuthApi`, and folding this in would force every app running the connect flow to
+ * also provide `CalcomApi` whether it makes outbound Cal.com calls or not.
+ *
+ * @returns The NestJS provider.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionCalcomUserContextServiceProvider(): Provider;

package/calcom/src/lib/calcom.oauth.connection.service.d.ts

@@ -0,0 +1,33 @@
+import { type CalcomAccessToken, type CalcomOAuthAuthorizeUrlFactory } from '@dereekb/calcom';
+import { CalcomOAuthApi } from '@dereekb/calcom/nestjs';
+import { AbstractUserExternalConnectionOAuthService, UserExternalConnectionAccessor, UserExternalConnectionServerActions, UserExternalConnectionStateCoder, type UserExternalConnectionCredentials, type UserExternalConnectionOAuthExchangeInput, type UserExternalConnectionOAuthRefreshCredentialsInput, type UserExternalConnectionOAuthState } from '@dereekb/firebase-server/model';
+import { type WebsiteUrl } from '@dereekb/util';
+import { CalcomUserExternalConnectionOAuthServiceConfig } from './calcom.oauth.connection.config';
+/**
+ * Maps an exchanged Cal.com token to the credentials stored on the private connection document.
+ *
+ * The `refreshToken` written here is the rotated one from the exchange — Cal.com invalidates the
+ * token each use, so persisting the one we sent would break the next refresh.
+ *
+ * @param accessToken - The exchanged Cal.com access token.
+ * @returns The credentials to store.
+ */
+export declare function calcomUserExternalConnectionCredentials(accessToken: CalcomAccessToken): UserExternalConnectionCredentials;
+/**
+ * Cal.com's half of the external-connection authorization-code handoff.
+ *
+ * Everything else — resolving who is connecting, surfacing a refusal, persisting the credentials,
+ * choosing the redirect — is the framework's.
+ */
+export declare class CalcomUserExternalConnectionOAuthService extends AbstractUserExternalConnectionOAuthService {
+    readonly config: CalcomUserExternalConnectionOAuthServiceConfig;
+    readonly stateCoder: UserExternalConnectionStateCoder;
+    readonly userExternalConnectionActions: UserExternalConnectionServerActions;
+    readonly userExternalConnectionAccessor: UserExternalConnectionAccessor;
+    readonly oauthApi: CalcomOAuthApi;
+    readonly authorizeUrlFactory: CalcomOAuthAuthorizeUrlFactory;
+    constructor(config: CalcomUserExternalConnectionOAuthServiceConfig, stateCoder: UserExternalConnectionStateCoder, userExternalConnectionActions: UserExternalConnectionServerActions, userExternalConnectionAccessor: UserExternalConnectionAccessor, oauthApi: CalcomOAuthApi);
+    protected authorizeUrlForState(state: UserExternalConnectionOAuthState): WebsiteUrl;
+    protected credentialsForAuthorizationCode(input: UserExternalConnectionOAuthExchangeInput): Promise<UserExternalConnectionCredentials>;
+    refreshCredentials(input: UserExternalConnectionOAuthRefreshCredentialsInput): Promise<UserExternalConnectionCredentials>;
+}

package/calcom/src/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from './calcom.oauth.connection.cache';
+export * from './calcom.oauth.connection.config';
+export * from './calcom.oauth.connection.context';
+export * from './calcom.oauth.connection.controller';
+export * from './calcom.oauth.connection.module';
+export * from './calcom.oauth.connection.service';

package/discord/index.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./index.cjs.js').default;