@dereekb/firebase 13.32.0 → 13.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.32.0",
+  "version": "13.34.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.32.0",
-    "@dereekb/model": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/util": "13.32.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "@marcbachmann/cel-js": "^7.6.1",
     "@typescript-eslint/parser": "8.59.3",

package/src/lib/common/firestore/snapshot/snapshot.field.d.ts

@@ -23,7 +23,7 @@
  * - **Primitives**: `firestoreString`, `firestoreNumber`, `firestoreBoolean`, `firestoreEnum`
  * - **Dates**: `firestoreDate` (ISO8601), `firestoreDateNumber` (unix seconds)
  * - **Arrays**: `firestoreArray`, `firestoreUniqueArray`, `firestoreEnumArray`, `firestoreEncodedArray`
- * - **Maps**: `firestoreMap`, `firestoreEncodedObjectMap`, `firestoreArrayMap`
+ * - **Maps**: `firestoreMap`, `firestoreEncodedObjectMap`, `firestoreObjectMap`, `firestoreArrayMap`
  * - **Objects**: `firestoreSubObject`, `firestoreObjectArray`
  * - **Specialized**: `firestoreUID`, `firestoreLatLngString`, `firestoreWebsiteLink`,
  *   `firestoreDateCellRange`, `firestoreBitwiseSet`, `firestoreUnitedStatesAddress`
@@ -1361,9 +1361,11 @@ export type FirestoreSubObjectFieldMapFunctionsConfig<T extends object, O extend
  * // Nested address object with its own converters
  * const addressField = firestoreSubObject<Address>({
  *   objectField: {
- *     street: firestoreString(),
- *     city: firestoreString(),
- *     zip: firestoreString()
+ *     fields: {
+ *       street: firestoreString(),
+ *       city: firestoreString(),
+ *       zip: firestoreString()
+ *     }
  *   }
  * });
  * ```
@@ -1371,6 +1373,59 @@ export type FirestoreSubObjectFieldMapFunctionsConfig<T extends object, O extend
  * @__NO_SIDE_EFFECTS__
  */
 export declare function firestoreSubObject<T extends object, O extends object = FirestoreModelData<T>>(config: FirestoreSubObjectFieldConfig<T, O>): FirestoreSubObjectFieldMapFunctionsConfig<T, O>;
+/**
+ * A Firestore map type where each value is an object that is converted using its own set of field converters.
+ */
+export type FirestoreObjectMapFieldValueType<T extends object, S extends string = string> = Record<S, T>;
+/**
+ * firestoreObjectMap configuration
+ */
+export type FirestoreObjectMapFieldConfig<T extends object, O extends object = FirestoreModelData<T>, S extends string = string> = DefaultMapConfiguredFirestoreFieldConfig<FirestoreObjectMapFieldValueType<T, S>, FirestoreMapFieldType<O, S>> & (FirestoreObjectArrayFieldConfigObjectFieldInput<T, O> | FirestoreObjectArrayFieldConfigFirestoreFieldInput<T, O>) & {
+    /**
+     * Optional filter to apply when saving to data.
+     *
+     * By default filters all empty values from the map. Objects with no keys are considered empty.
+     */
+    readonly mapFilter?: FilterKeyValueTuplesInput<FirestoreMapFieldType<O, S>>;
+};
+/**
+ * Creates a field mapping configuration for a Firestore map whose values are complex objects.
+ *
+ * This is the map-keyed counterpart to {@link firestoreObjectArray}: each value in the map is
+ * converted using its own set of field converters (via `objectField` or `firestoreField`), so
+ * nested `Date`/enum/array fields round-trip properly.
+ *
+ * On write, null/undefined values are filtered from each object to match Firestore semantics, and
+ * empty values (including objects with no keys) are removed from the map entirely.
+ *
+ * NOTE: this exists instead of passing a sub-object's `mapFunctions.to`/`.from` directly to
+ * {@link firestoreEncodedObjectMap}. That encoder is invoked as `mapFn(value, key)` by
+ * `mapObjectMap()`, while a `ModelMapFunctions`' second parameter is the accumulator *target* — so
+ * the map key string would be used as the write target and the conversion would throw at runtime.
+ * The arity is wrapped here, once, rather than at each call site.
+ *
+ * @param config - Configuration including the per-value conversions and optional map filtering.
+ * @returns A field mapping configuration for object map values.
+ *
+ * @dbxModelSnapshotField
+ * @dbxModelSnapshotFieldCategory map
+ * @dbxModelSnapshotFieldTags map, record, dictionary, object, nested, embedded, structured, factory
+ * @dbxModelSnapshotFieldRelated firestore-sub-object, firestore-object-array
+ * @template T - The value model type
+ * @template O - The value Firestore data type (defaults to FirestoreModelData<T>)
+ * @template S - Key type (string, defaults to string)
+ *
+ * @example
+ * ```ts
+ * // Map of provider id -> connection entry
+ * const entriesField = firestoreObjectMap<UserExternalConnectionEntry, FirestoreModelData<UserExternalConnectionEntry>, UserExternalConnectionProviderType>({
+ *   objectField: { fields: userExternalConnectionEntryFields }
+ * });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firestoreObjectMap<T extends object, O extends object = FirestoreModelData<T>, S extends string = string>(config: FirestoreObjectMapFieldConfig<T, O, S>): FirestoreModelFieldMapFunctionsConfig<FirestoreEncodedObjectMapFieldValueType<T, S>, FirestoreMapFieldType<O, S>>;
 export interface FirestoreLatLngStringConfig extends DefaultMapConfiguredFirestoreFieldConfig<LatLngString, LatLngString> {
     readonly precision?: LatLngPrecision;
 }

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

@@ -4,3 +4,4 @@ export * from './notification';
 export * from './oidcmodel';
 export * from './storagefile';
 export * from './system';
+export * from './userexternalconnection';

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

@@ -1,9 +1,10 @@
 import { type GrantedSysAdminRole } from '@dereekb/model';
-import { AbstractFirestoreDocument } from '../../common/firestore/accessor/document';
+import { AbstractFirestoreDocument, type FirestoreDocument } from '../../common/firestore/accessor/document';
+import { type InterceptFirestoreDataConverterFactory } from '../../common/firestore/accessor/converter';
 import { type FirestoreCollection } from '../../common/firestore/collection/collection';
 import { type FirestoreContext } from '../../common/firestore/context';
 import { type CollectionReference } from '../../common/firestore/types';
-import { type ModelFieldMapFunctionsConfig } from '@dereekb/util';
+import { type Maybe, type ModelFieldMapFunctionsConfig } from '@dereekb/util';
 /**
  * @module system
  *
@@ -31,7 +32,12 @@ export declare abstract class SystemStateFirestoreCollections {
  */
 export type SystemStateTypes = typeof systemStateIdentity;
 /**
- * Model identity for the SystemState collection (collection name: `systemState`, prefix: `sys`).
+ * Model identity for the SystemState collection.
+ *
+ * NOTE: the second argument of `firestoreModelIdentity()` is the COLLECTION NAME, so this is model
+ * type `systemState` stored at the Firestore path `sys/<docId>` — not the other way around.
+ * `systemStateCollectionReference()` resolves `identity.collectionName`, and `firestore.rules` match
+ * blocks are written against `/sys`.
  */
 export declare const systemStateIdentity: import("../..").RootFirestoreModelIdentity<"systemState", "sys">;
 /**
@@ -106,6 +112,14 @@ export declare const systemStateConverter: import("../..").SnapshotConverterFunc
  */
 export declare function systemStateCollectionReference(context: FirestoreContext): CollectionReference<SystemState>;
 export type SystemStateFirestoreCollection<T extends SystemStateStoredData = SystemStateStoredData> = FirestoreCollection<SystemState<T>, SystemStateDocument<T>>;
+/**
+ * A {@link SystemState} collection with any document type.
+ *
+ * Use this where a consumer only needs to read/write SystemState documents and should accept either
+ * the client-shared {@link SystemStateFirestoreCollection} or a server-only variant that uses its own
+ * document class (e.g. `SystemStatePrivateFirestoreCollection` in `@dereekb/firebase-server/model`).
+ */
+export type SystemStateFirestoreCollectionLike<T extends SystemStateStoredData = SystemStateStoredData, D extends FirestoreDocument<SystemState<T>> = FirestoreDocument<SystemState<T>>> = FirestoreCollection<SystemState<T>, D>;
 /**
  * Field conversion config for a specific SystemState data type.
  *
@@ -122,6 +136,50 @@ export type SystemStateStoredDataFieldConverterConfig<T extends SystemStateStore
 export type SystemStateStoredDataConverterMap = {
     [key: string]: SystemStateStoredDataFieldConverterConfig<any>;
 };
+/**
+ * What a SystemState collection does when a document's type has no registered converter.
+ *
+ * - `passthrough`: fall back to the default pass-through converter. Historical behavior, and what
+ *   {@link systemStateFirestoreCollection} uses.
+ * - `error`: throw. Appropriate for a collection whose types are all known up front — notably a
+ *   server-only collection, where silently reading a secret-bearing document through a pass-through
+ *   converter would skip its field mapping (dates come back as raw `Timestamp`s, encrypted fields as
+ *   raw ciphertext) with nothing to signal it.
+ */
+export type SystemStateUnknownTypeBehavior = 'passthrough' | 'error';
+/**
+ * Configuration for {@link systemStateStoredDataConverterFactory}.
+ */
+export interface SystemStateStoredDataConverterFactoryConfig {
+    /**
+     * Map of type identifiers to their data field converters.
+     */
+    readonly converters: SystemStateStoredDataConverterMap;
+    /**
+     * Behavior when a document's type has no registered converter. Defaults to `passthrough`.
+     */
+    readonly unknownTypeBehavior?: Maybe<SystemStateUnknownTypeBehavior>;
+    /**
+     * Collection name used only to make the `error` message actionable.
+     */
+    readonly collectionName?: Maybe<string>;
+}
+/**
+ * Creates the `converterFactory` for a SystemState collection, selecting a converter by document id
+ * (which is the {@link SystemStateTypeIdentifier}).
+ *
+ * Returning `undefined` is what produces the pass-through fallback — the accessor resolves
+ * `converterFactory(ref) ?? defaultConverter`.
+ *
+ * NOTE for `error`: the factory runs in `loadDocument` / `documentRefForKey`, so an unregistered type
+ * throws at document *load*, including while hydrating query results. That is intended for a
+ * server-only collection, but it does mean you cannot generically iterate such a collection unless
+ * every type it contains is registered.
+ *
+ * @param config - The converter map and unknown-type behavior.
+ * @returns A converter factory suitable for a Firestore collection's `converterFactory`.
+ */
+export declare function systemStateStoredDataConverterFactory(config: SystemStateStoredDataConverterFactoryConfig): InterceptFirestoreDataConverterFactory<SystemState>;
 /**
  * Creates a {@link SystemStateFirestoreCollection} with per-type data converters.
  *

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

@@ -0,0 +1,6 @@
+export * from './userexternalconnection';
+export * from './userexternalconnection.id';
+export * from './userexternalconnection.util';
+export * from './userexternalconnection.query';
+export * from './userexternalconnection.api';
+export * from './userexternalconnection.action';

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[];