@dereekb/firebase 13.31.0 → 13.33.0

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

@@ -0,0 +1,21 @@
+import { type AsyncFirebaseFunctionUpdateAction, type FirebaseFunctionUpdateAction } from '../../common';
+import { type UserExternalConnectionDocument } from './userexternalconnection';
+/**
+ * @module userexternalconnection.action
+ *
+ * Type aliases for UserExternalConnection server action functions.
+ *
+ * NOTE: there are no create/delete action aliases here on purpose. The document pair is only ever
+ * mutated through the paired per-provider connect/update/disconnect operations in
+ * `@dereekb/firebase-server/model`, which create and remove the documents themselves.
+ *
+ * @template P - the API parameter type for the action
+ */
+/**
+ * Synchronous update action targeting a {@link UserExternalConnectionDocument}.
+ */
+export type UserExternalConnectionUpdateAction<P extends object> = FirebaseFunctionUpdateAction<P, UserExternalConnectionDocument>;
+/**
+ * Async update action targeting a {@link UserExternalConnectionDocument}.
+ */
+export type AsyncUserExternalConnectionUpdateAction<P extends object> = AsyncFirebaseFunctionUpdateAction<P, UserExternalConnectionDocument>;

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

@@ -0,0 +1,120 @@
+import { type Type } from 'arktype';
+import { type InferredTargetModelParams } from '../../common/model/model/model.param';
+import { type FirebaseFunctionTypeConfigMap, type ModelFirebaseCreateFunction, type ModelFirebaseCrudFunction, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap } from '../../client';
+import { type UserExternalConnectionTypes } from './userexternalconnection';
+import { type UserExternalConnectionProviderType } from './userexternalconnection.id';
+/**
+ * Parameters for creating the calling user's connection document.
+ *
+ * Deliberately empty: the document is keyed by uid, so there is nothing to target and nothing to
+ * seed it with — providers arrive one at a time through the OAuth flow, never at creation.
+ *
+ * @dbxModelApiParams
+ */
+export interface CreateUserExternalConnectionParams {
+}
+export declare const createUserExternalConnectionParamsType: Type<CreateUserExternalConnectionParams>;
+/**
+ * Parameters for disconnecting the current user from a third-party provider.
+ *
+ * This is the ONLY write path a client has to the connection pair. There is deliberately no connect
+ * or update params type here: connecting requires credentials, which only the server ever sees.
+ *
+ * If no target model is provided, the current user's connection document is assumed.
+ *
+ * @dbxModelApiParams
+ */
+export interface DisconnectUserExternalConnectionParams extends InferredTargetModelParams {
+    /**
+     * The provider type to disconnect from.
+     */
+    readonly providerType: UserExternalConnectionProviderType;
+}
+export declare const disconnectUserExternalConnectionParamsType: Type<DisconnectUserExternalConnectionParams>;
+/**
+ * Parameters for beginning an OAuth connect handoff for a provider.
+ *
+ * @dbxModelApiParams
+ */
+export interface ReadUserExternalConnectionAuthorizeStateParams extends InferredTargetModelParams {
+    /**
+     * The provider type to begin connecting to.
+     */
+    readonly providerType: UserExternalConnectionProviderType;
+}
+export declare const readUserExternalConnectionAuthorizeStateParamsType: Type<ReadUserExternalConnectionAuthorizeStateParams>;
+/**
+ * The opaque, short-lived `state` to carry through a provider's OAuth handoff.
+ *
+ * Minting it requires an authenticated call, because a top-level navigation to the provider's
+ * authorize endpoint carries no credentials and the server must already know who is connecting. The
+ * client's only job is to pass this through — it must never append its ID token to the redirect.
+ */
+export interface UserExternalConnectionAuthorizeStateResult {
+    /**
+     * The state to send on the authorize request.
+     */
+    readonly state: string;
+}
+/**
+ * Custom (non-CRUD) function type map for UserExternalConnection. There are none.
+ */
+export type UserExternalConnectionFunctionTypeMap = {};
+export declare const USER_EXTERNAL_CONNECTION_FUNCTION_TYPE_CONFIG_MAP: FirebaseFunctionTypeConfigMap<UserExternalConnectionFunctionTypeMap>;
+/**
+ * CRUD function configuration map for the UserExternalConnection model.
+ */
+export type UserExternalConnectionModelCrudFunctionsConfig = {
+    readonly userExternalConnection: {
+        /**
+         * Creates the calling user's connection document.
+         *
+         * Every other client-reachable operation asserts a role against this document, so it must exist
+         * before a user can begin a connect. Creating it is its own call — rather than a side effect of
+         * the first connect — so that "may this user have external connections at all?" is decided in
+         * one place instead of being folded into the OAuth handoff.
+         *
+         * Throws when the document already exists.
+         */
+        create: CreateUserExternalConnectionParams;
+        read: {
+            /**
+             * Mints the short-lived `state` that begins an OAuth connect handoff for a provider.
+             *
+             * A read rather than an update: it changes nothing, it just proves who is asking. The app
+             * decides how the state is signed and how long it lives.
+             */
+            authorizeState: [ReadUserExternalConnectionAuthorizeStateParams, UserExternalConnectionAuthorizeStateResult];
+        };
+        update: {
+            /**
+             * Disconnects the current user from the given provider.
+             *
+             * Removes the provider's credentials and its entry in one transaction, and recomputes the
+             * connected-provider array from the result.
+             */
+            disconnect: DisconnectUserExternalConnectionParams;
+        };
+    };
+};
+export declare const USER_EXTERNAL_CONNECTION_MODEL_CRUD_FUNCTIONS_CONFIG: ModelFirebaseCrudFunctionConfigMap<UserExternalConnectionModelCrudFunctionsConfig, UserExternalConnectionTypes>;
+/**
+ * Abstract class defining all callable UserExternalConnection cloud functions.
+ *
+ * Implement this in your app module to wire up the function endpoints.
+ */
+export declare abstract class UserExternalConnectionFunctions implements ModelFirebaseFunctionMap<UserExternalConnectionFunctionTypeMap, UserExternalConnectionModelCrudFunctionsConfig> {
+    abstract userExternalConnection: {
+        createUserExternalConnection: ModelFirebaseCreateFunction<CreateUserExternalConnectionParams>;
+        readUserExternalConnection: {
+            authorizeState: ModelFirebaseCrudFunction<ReadUserExternalConnectionAuthorizeStateParams, UserExternalConnectionAuthorizeStateResult>;
+        };
+        updateUserExternalConnection: {
+            disconnect: ModelFirebaseCrudFunction<DisconnectUserExternalConnectionParams>;
+        };
+    };
+}
+/**
+ * Used to generate the UserExternalConnectionFunctions map for a Functions instance.
+ */
+export declare const userExternalConnectionFunctionMap: import("../..").ModelFirebaseFunctionMapFactory<UserExternalConnectionFunctionTypeMap, UserExternalConnectionModelCrudFunctionsConfig>;

package/src/lib/model/userexternalconnection/userexternalconnection.d.ts

@@ -0,0 +1,191 @@
+import { type Maybe } from '@dereekb/util';
+import { type GrantedReadRole, type GrantedUpdateRole } from '@dereekb/model';
+import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext } from '../../common';
+import { type UserRelated, type UserRelatedById } from '../user';
+import { type UserExternalConnectionCapability, type UserExternalConnectionExternalAccountId, type UserExternalConnectionProviderType } from './userexternalconnection.id';
+/**
+ * Provides access to the {@link UserExternalConnection} collection.
+ *
+ * NOTE: the private half of this model pair (`UserExternalConnectionPrivate`) is deliberately NOT
+ * declared here. It exists only in `@dereekb/firebase-server/model`, so client-shared code cannot
+ * name it.
+ *
+ * @dbxModelGroup UserExternalConnection
+ */
+export interface UserExternalConnectionFirestoreCollections {
+    readonly userExternalConnectionCollection: UserExternalConnectionFirestoreCollection;
+}
+/**
+ * Union of all UserExternalConnection model identity types.
+ */
+export type UserExternalConnectionTypes = typeof userExternalConnectionIdentity;
+export declare const userExternalConnectionIdentity: import("../..").RootFirestoreModelIdentity<"userExternalConnection", "uec">;
+/**
+ * Status of a single third-party connection.
+ *
+ * - `connected` — credentials are present and believed usable
+ * - `disconnected` — the user (or the server) revoked the connection. Retained only for history.
+ * - `error` — the connection exists but the credentials stopped working and need attention
+ */
+export type UserExternalConnectionEntryStatus = 'connected' | 'disconnected' | 'error';
+export declare const USER_EXTERNAL_CONNECTION_ENTRY_STATUSES: UserExternalConnectionEntryStatus[];
+/**
+ * Short code describing why an entry is in the `error` status.
+ *
+ * Deliberately a code and not a message: the UI decides the wording, and a stored message would
+ * leak provider internals into a client-readable document.
+ */
+export type UserExternalConnectionErrorCode = 'unauthorized' | 'expired' | 'revoked' | 'insufficient_scope' | 'provider_error' | 'unknown';
+/**
+ * Per-provider connection state stored inside a {@link UserExternalConnection}.
+ *
+ * Every field here is DERIVED by the server from the credentials that were stored alongside it —
+ * see `userExternalConnectionEntryForOutcome()`. Nothing on this interface may be supplied directly
+ * by a caller, otherwise the summary could contradict the credentials it summarizes.
+ *
+ * @dbxModelSubObject
+ */
+export interface UserExternalConnectionEntry {
+    /**
+     * Current status of this connection.
+     *
+     * @dbxModelVariable status
+     */
+    st: UserExternalConnectionEntryStatus;
+    /**
+     * Capabilities/scopes granted by the provider.
+     *
+     * @dbxModelVariable capabilities
+     */
+    ca?: Maybe<UserExternalConnectionCapability[]>;
+    /**
+     * Identifier of the connected account within the provider.
+     *
+     * @dbxModelVariable externalAccountId
+     */
+    ea?: Maybe<UserExternalConnectionExternalAccountId>;
+    /**
+     * Human-readable label for the connected account (e.g. the provider-side email or username).
+     *
+     * @dbxModelVariable label
+     */
+    l?: Maybe<string>;
+    /**
+     * Date the connection was first established.
+     *
+     * @dbxModelVariable connectedAt
+     */
+    coa?: Maybe<Date>;
+    /**
+     * Date the current access credentials expire at, when known.
+     *
+     * @dbxModelVariable expiresAt
+     */
+    exa?: Maybe<Date>;
+    /**
+     * Date this entry was last updated at.
+     *
+     * @dbxModelVariable updatedAt
+     */
+    uat: Date;
+    /**
+     * Reason the entry is in the `error` status. Cleared on any non-error outcome.
+     *
+     * @dbxModelVariable errorCode
+     */
+    er?: Maybe<UserExternalConnectionErrorCode>;
+}
+/**
+ * Map of provider type to the user's connection state for that provider.
+ */
+export type UserExternalConnectionEntryMap = Record<UserExternalConnectionProviderType, UserExternalConnectionEntry>;
+/**
+ * The client-readable half of a user's third-party OAuth connection state.
+ *
+ * There is exactly ONE of these per user, keyed by uid — per-provider details live inside `e`
+ * rather than in separate documents. The server-only half holding the actual access/refresh
+ * tokens is `UserExternalConnectionPrivate` in `@dereekb/firebase-server/model`, which shares this
+ * document's id.
+ *
+ * The two documents are NEVER written independently. Every mutation goes through the paired
+ * transaction accessor in `@dereekb/firebase-server/model`, which derives everything on this
+ * document from the same input that produces the credentials. There is deliberately no sync,
+ * reconciliation, or drift-detection process — divergence is unrepresentable rather than detectable.
+ *
+ * @dbxModel
+ * @dbxModelRead owner
+ */
+export interface UserExternalConnection extends UserRelated, UserRelatedById {
+    /**
+     * Per-provider connection state, keyed by provider type.
+     *
+     * @dbxModelVariable entries
+     */
+    e: UserExternalConnectionEntryMap;
+    /**
+     * DERIVED from `e`: every provider type whose entry status is `connected`.
+     *
+     * This exists solely so "which users are connected to X?" stays queryable after collapsing to a
+     * single document per user — Firestore cannot query across map keys, but it can `array-contains`
+     * this field. It is recomputed from `e` on every write and is never passed in by a caller.
+     *
+     * Entries in the `disconnected` or `error` status are excluded: a "usable connections" query that
+     * returned users whose credentials stopped working would be worse than useless, and
+     * `array-contains` cannot filter by status to compensate.
+     *
+     * @dbxModelVariable connectedProviderTypes
+     */
+    c: UserExternalConnectionProviderType[];
+    /**
+     * Date this document was last updated at.
+     *
+     * @dbxModelVariable updatedAt
+     */
+    uat: Date;
+}
+/**
+ * Roles for a UserExternalConnection. Users can read their own connection state; all writes go
+ * through the server.
+ *
+ * `connect` and `disconnect` are called out separately from `update` because they are the only
+ * operations a client can reach, so an app can withhold either one (a user allowed to drop a
+ * connection but not to add another, or the reverse) without also withholding the server-driven
+ * writes that share `update`.
+ */
+export type UserExternalConnectionRoles = GrantedReadRole | GrantedUpdateRole | 'connect' | 'disconnect';
+export declare class UserExternalConnectionDocument extends AbstractFirestoreDocument<UserExternalConnection, UserExternalConnectionDocument, typeof userExternalConnectionIdentity> {
+    get modelIdentity(): import("../..").RootFirestoreModelIdentity<"userExternalConnection", "uec">;
+}
+/**
+ * Field conversions for a {@link UserExternalConnectionEntry}.
+ */
+export declare const userExternalConnectionEntryFields: {
+    st: import("../..").FirestoreModelFieldMapFunctionsConfig<UserExternalConnectionEntryStatus, UserExternalConnectionEntryStatus>;
+    ca: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<string[]>, Maybe<string[]>>;
+    ea: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<string>, Maybe<string>>;
+    l: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<string>, Maybe<string>>;
+    coa: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<Date>, Maybe<string>>;
+    exa: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<Date>, Maybe<string>>;
+    uat: import("../..").FirestoreModelFieldMapFunctionsConfig<Date, string>;
+    er: import("../..").FirestoreModelFieldMapFunctionsConfig<Maybe<UserExternalConnectionErrorCode>, Maybe<UserExternalConnectionErrorCode>>;
+};
+export declare const userExternalConnectionConverter: import("../..").SnapshotConverterFunctions<UserExternalConnection, Partial<import("@dereekb/util").ReplaceType<UserExternalConnection, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Copies the document id into `uid` on write, so the stored uid can never drift from the document id.
+ */
+export declare const userExternalConnectionAccessorFactory: import("../..").InterceptAccessorFactoryFunction<UserExternalConnection, import("../..").DocumentData>;
+/**
+ * Returns the root Firestore collection reference for UserExternalConnection documents.
+ *
+ * @param context - The FirestoreContext used to resolve the collection.
+ * @returns A typed CollectionReference for the userExternalConnection collection.
+ */
+export declare function userExternalConnectionCollectionReference(context: FirestoreContext): CollectionReference<UserExternalConnection>;
+export type UserExternalConnectionFirestoreCollection = FirestoreCollection<UserExternalConnection, UserExternalConnectionDocument>;
+/**
+ * Creates the Firestore collection accessor for UserExternalConnection documents.
+ *
+ * @param firestoreContext - The FirestoreContext used to build the collection.
+ * @returns A UserExternalConnectionFirestoreCollection.
+ */
+export declare function userExternalConnectionFirestoreCollection(firestoreContext: FirestoreContext): UserExternalConnectionFirestoreCollection;

package/src/lib/model/userexternalconnection/userexternalconnection.id.d.ts

@@ -0,0 +1,51 @@
+import { type FirestoreModelId, type FirestoreModelKey } from '../../common';
+/**
+ * Document id for a {@link UserExternalConnection}.
+ *
+ * The document id IS the user's Firebase Auth uid. There is exactly one document per user.
+ */
+export type UserExternalConnectionId = FirestoreModelId;
+/**
+ * Full Firestore model key path for a {@link UserExternalConnection} document.
+ */
+export type UserExternalConnectionKey = FirestoreModelKey;
+/**
+ * String identifier for a third-party service a user can connect their account to.
+ *
+ * Used as the key of the per-provider entry map on a UserExternalConnection, so it must be a
+ * valid Firestore map key (no dots or slashes) and must be identical on the server paths that
+ * write the connection and the client paths that render it.
+ */
+export type UserExternalConnectionProviderType = string;
+/**
+ * Known third-party services the workspace ships provider support for.
+ */
+export type KnownUserExternalConnectionProviderType = 'calcom' | 'zoom' | 'discord' | 'zoho';
+/**
+ * Provider type for Cal.com.
+ *
+ * Declared here rather than in a server package because the string is the map key on BOTH halves of
+ * the connection pair: the server's OAuth controller writes it and the client renders from it, so
+ * they must be the same literal.
+ */
+export declare const CALCOM_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE: KnownUserExternalConnectionProviderType;
+/**
+ * Provider type for Zoom.
+ */
+export declare const ZOOM_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE: KnownUserExternalConnectionProviderType;
+/**
+ * Provider type for Discord.
+ */
+export declare const DISCORD_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE: KnownUserExternalConnectionProviderType;
+/**
+ * Provider type for Zoho.
+ */
+export declare const ZOHO_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE: KnownUserExternalConnectionProviderType;
+/**
+ * A capability/scope string granted by a third-party provider (e.g. an OAuth scope).
+ */
+export type UserExternalConnectionCapability = string;
+/**
+ * Identifier for the connected account within the third-party provider.
+ */
+export type UserExternalConnectionExternalAccountId = string;

package/src/lib/model/userexternalconnection/userexternalconnection.query.d.ts

@@ -0,0 +1,19 @@
+import { type FirestoreQueryConstraint } from '../../common';
+import { type UserExternalConnectionProviderType } from './userexternalconnection.id';
+/**
+ * Query for the UserExternalConnection documents that are currently connected to the given provider.
+ *
+ * This is the single reason the derived `c` array exists: with one document per user, provider ids
+ * are map keys, and Firestore cannot query across map keys.
+ *
+ * Only `connected` entries are members of `c`, so this never returns a user whose credentials are in
+ * the `error` or `disconnected` state.
+ *
+ * @param providerType - The provider type to search for.
+ * @returns Firestore query constraints matching users connected to that provider.
+ *
+ * @dbxModelFirebaseIndex
+ * @dbxModelFirebaseIndexModel UserExternalConnection
+ * @dbxModelFirebaseIndexScope COLLECTION
+ */
+export declare function userExternalConnectionsWithConnectedProviderQuery(providerType: UserExternalConnectionProviderType): FirestoreQueryConstraint[];

package/src/lib/model/userexternalconnection/userexternalconnection.util.d.ts

@@ -0,0 +1,149 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId } from '../../common';
+import { type UserExternalConnection, type UserExternalConnectionEntry, type UserExternalConnectionEntryMap, type UserExternalConnectionEntryStatus, type UserExternalConnectionErrorCode } from './userexternalconnection';
+import { type UserExternalConnectionCapability, type UserExternalConnectionExternalAccountId, type UserExternalConnectionProviderType } from './userexternalconnection.id';
+/**
+ * The facts about a granted third-party authorization that a {@link UserExternalConnectionEntry} is
+ * allowed to summarize.
+ *
+ * This is projected from the stored credentials by the server (see
+ * `userExternalConnectionGrantSummaryFromCredentials` in `@dereekb/firebase-server/model`), never
+ * assembled by a caller. That is what makes it impossible for the client-readable summary to claim
+ * scopes, an account, or an expiration the credentials do not actually have.
+ */
+export interface UserExternalConnectionGrantSummary {
+    readonly scopes?: Maybe<UserExternalConnectionCapability[]>;
+    readonly externalAccountId?: Maybe<UserExternalConnectionExternalAccountId>;
+    readonly label?: Maybe<string>;
+    readonly connectedAt?: Maybe<Date>;
+    readonly expiresAt?: Maybe<Date>;
+}
+/**
+ * The SOLE producer of a {@link UserExternalConnection}'s `c` array.
+ *
+ * Membership is exactly the provider types whose entry status is `connected`. `disconnected` and
+ * `error` entries are excluded — the array backs a "which users can I actually call X for?" query,
+ * and `array-contains` has no way to filter by status afterwards.
+ *
+ * @param entries - The per-provider entry map to derive from.
+ * @returns The connected provider types, sorted for a stable stored value.
+ */
+export declare function userExternalConnectionConnectedProviderTypes(entries: Maybe<UserExternalConnectionEntryMap>): UserExternalConnectionProviderType[];
+/**
+ * Input for {@link userExternalConnectionEntryForOutcome}.
+ *
+ * NOTE the shape: there is no parameter for any entry field. `ca`/`ea`/`l`/`exa` are copied off the
+ * `grant` (which is itself projected from the credentials), and `st`/`coa`/`uat` are computed. A
+ * caller has no way to describe a connection the credentials do not support.
+ */
+export interface UserExternalConnectionEntryForOutcomeInput {
+    /**
+     * The outcome of the operation that produced (or removed) the credentials.
+     */
+    readonly outcome: UserExternalConnectionEntryStatus;
+    /**
+     * Summary of the grant the credentials carry. Required in practice for a `connected` outcome.
+     */
+    readonly grant?: Maybe<UserExternalConnectionGrantSummary>;
+    /**
+     * Reason for an `error` outcome. Defaults to `unknown`.
+     */
+    readonly error?: Maybe<UserExternalConnectionErrorCode>;
+    /**
+     * The entry currently stored for this provider, when there is one.
+     */
+    readonly previous?: Maybe<UserExternalConnectionEntry>;
+    /**
+     * Whether a `disconnected` outcome should retain a history entry rather than removing the key.
+     *
+     * Defaults to false.
+     */
+    readonly retainEntry?: Maybe<boolean>;
+    /**
+     * The instant the operation is being applied at.
+     */
+    readonly now: Date;
+}
+/**
+ * Derives the {@link UserExternalConnectionEntry} for an operation's outcome.
+ *
+ * @param input - The outcome plus the grant it derives from.
+ * @returns The next entry, or null when the provider's entry should be REMOVED from the map.
+ */
+export declare function userExternalConnectionEntryForOutcome(input: UserExternalConnectionEntryForOutcomeInput): Maybe<UserExternalConnectionEntry>;
+/**
+ * Input for {@link applyUserExternalConnectionEntry}.
+ */
+export interface ApplyUserExternalConnectionEntryInput {
+    /**
+     * The currently stored document, when one exists.
+     */
+    readonly current?: Maybe<UserExternalConnection>;
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The next entry for this provider, or null to remove the provider's key entirely.
+     */
+    readonly entry: Maybe<UserExternalConnectionEntry>;
+    readonly now: Date;
+}
+/**
+ * Applies a single provider's entry and returns the COMPLETE next document.
+ *
+ * Returning the whole value (rather than a patch) is what keeps `c` honest: this is the only
+ * exported way to change `e`, and it always recomputes `c` from the resulting map. There is no
+ * exported path that touches one without the other.
+ *
+ * @param input - The current document plus the provider entry to apply.
+ * @returns The next UserExternalConnection value to write.
+ */
+export declare function applyUserExternalConnectionEntry(input: ApplyUserExternalConnectionEntryInput): UserExternalConnection;
+/**
+ * Input for {@link emptyUserExternalConnection}.
+ */
+export interface EmptyUserExternalConnectionInput {
+    readonly uid: FirebaseAuthUserId;
+    readonly now: Date;
+}
+/**
+ * Returns the value of a connection document that has no providers on it yet.
+ *
+ * Creating the document is its own operation, so the "no connections" value lives here beside
+ * {@link applyUserExternalConnectionEntry} rather than as a literal at the call site — both write
+ * the complete document, and `c` is empty here for the same reason it is derived there.
+ *
+ * @param input - The user the document belongs to and the instant to stamp it with.
+ * @returns The UserExternalConnection value for a user with no provider entries.
+ */
+export declare function emptyUserExternalConnection(input: EmptyUserExternalConnectionInput): UserExternalConnection;
+/**
+ * Returns the entry for the given provider, if any.
+ *
+ * @param connection - The loaded connection document.
+ * @param providerType - The provider to read.
+ * @returns The provider's entry, or null when the user has no entry for it.
+ */
+export declare function userExternalConnectionEntryForProvider(connection: Maybe<UserExternalConnection>, providerType: UserExternalConnectionProviderType): Maybe<UserExternalConnectionEntry>;
+/**
+ * Returns true if the entry is in the `connected` status.
+ *
+ * @param entry - The entry to check.
+ * @returns True when the entry is connected.
+ */
+export declare function userExternalConnectionEntryIsConnected(entry: Maybe<UserExternalConnectionEntry>): boolean;
+/**
+ * Returns true if the entry declares an expiration that has already passed.
+ *
+ * @param entry - The entry to check.
+ * @param now - The instant to compare against. Defaults to the current time.
+ * @returns True when the entry's credentials are known to have expired.
+ */
+export declare function userExternalConnectionEntryIsExpired(entry: Maybe<UserExternalConnectionEntry>, now?: Date): boolean;
+/**
+ * Returns true if the user is currently connected to the given provider.
+ *
+ * @param connection - The loaded connection document.
+ * @param providerType - The provider to check.
+ * @returns True when the provider's entry is connected.
+ */
+export declare function userExternalConnectionIsConnectedToProvider(connection: Maybe<UserExternalConnection>, providerType: UserExternalConnectionProviderType): boolean;