@dereekb/firebase 13.32.0 → 13.34.0

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;