@dereekb/firebase 14.0.1 → 14.2.0

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

@@ -1,7 +1,7 @@
-import { type Maybe } from '@dereekb/util';
+import { type EmailAddress, 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';
+import { type UserExternalConnection, type UserExternalConnectionEntry, type UserExternalConnectionEntryMap, type UserExternalConnectionEntryStatus, type UserExternalConnectionErrorCode, type UserExternalConnectionLogin, type UserExternalConnectionLoginMap } from './userexternalconnection';
+import { type UserExternalConnectionCapability, type UserExternalConnectionExternalAccountId, type UserExternalConnectionExternalAccountKey, type UserExternalConnectionProviderType } from './userexternalconnection.id';
 /**
  * The facts about a granted third-party authorization that a {@link UserExternalConnectionEntry} is
  * allowed to summarize.
@@ -29,6 +29,36 @@ export interface UserExternalConnectionGrantSummary {
  * @returns The connected provider types, sorted for a stable stored value.
  */
 export declare function userExternalConnectionConnectedProviderTypes(entries: Maybe<UserExternalConnectionEntryMap>): UserExternalConnectionProviderType[];
+/**
+ * Input for {@link userExternalConnectionExternalAccountKeys}.
+ *
+ * BOTH maps, always. Taking them as one object rather than as a positional entry map is deliberate:
+ * `ec` is the union of the two, and a signature that made either one omittable would make it possible
+ * to recompute the array from half its sources — which silently drops the other half's keys out of the
+ * lookup a sign-in performs.
+ */
+export interface UserExternalConnectionExternalAccountKeysInput {
+    readonly entries?: Maybe<UserExternalConnectionEntryMap>;
+    readonly logins?: Maybe<UserExternalConnectionLoginMap>;
+}
+/**
+ * The SOLE producer of a {@link UserExternalConnection}'s `ec` array.
+ *
+ * Membership is every ENTRY carrying an `ea`, at ANY status, UNION every LOGIN LINK's `ea` —
+ * deliberately unlike {@link userExternalConnectionConnectedProviderTypes}, which is `connected`-only.
+ * `c` answers "whose credentials can I use?", a question about the credentials; `ec` answers "who IS
+ * this account?", a question about identity, which survives an expired token. Filtering it by status
+ * would make a returning user with `error` credentials look like a stranger, and a sign-in would
+ * mint them a second Firebase user.
+ *
+ * The union is what makes the two lifecycles independent. Disconnecting a data connection removes its
+ * entry, and if `ec` came from `e` alone that would take the sign-in binding with it — the next
+ * sign-in would find no match and mint a second Firebase user for the same person.
+ *
+ * @param input - The entry map and the login map to derive from.
+ * @returns The external account keys, deduped and sorted for a stable stored value.
+ */
+export declare function userExternalConnectionExternalAccountKeys(input: UserExternalConnectionExternalAccountKeysInput): UserExternalConnectionExternalAccountKey[];
 /**
  * Input for {@link userExternalConnectionEntryForOutcome}.
  *
@@ -87,6 +117,29 @@ export interface ApplyUserExternalConnectionEntryInput {
     readonly entry: Maybe<UserExternalConnectionEntry>;
     readonly now: Date;
 }
+/**
+ * Input for {@link userExternalConnectionValue}.
+ */
+export interface UserExternalConnectionValueInput {
+    readonly uid: FirebaseAuthUserId;
+    readonly entries: UserExternalConnectionEntryMap;
+    readonly logins: UserExternalConnectionLoginMap;
+    readonly now: Date;
+}
+/**
+ * Assembles the COMPLETE document value from both maps.
+ *
+ * Extracted so the two appliers cannot diverge on how the derived arrays are produced: `ec` is the
+ * union of `e` and `li`, and either applier computing it from only the map it happened to change
+ * would drop the other map's keys out of the sign-in lookup.
+ *
+ * Exported for the one caller that legitimately replaces a whole map rather than one provider's key —
+ * the login backfill. Ordinary writes go through the two appliers.
+ *
+ * @param input - The uid, both maps, and the instant to stamp.
+ * @returns The next UserExternalConnection value to write.
+ */
+export declare function userExternalConnectionValue(input: UserExternalConnectionValueInput): UserExternalConnection;
 /**
  * Applies a single provider's entry and returns the COMPLETE next document.
  *
@@ -94,10 +147,77 @@ export interface ApplyUserExternalConnectionEntryInput {
  * 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.
  *
+ * The login map is carried through UNCHANGED. A data connection's lifecycle says nothing about
+ * whether the provider is still a way to sign in, so a disconnect must not remove the link.
+ *
  * @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 applyUserExternalConnectionLogin}.
+ */
+export interface ApplyUserExternalConnectionLoginInput {
+    /**
+     * The currently stored document, when one exists.
+     */
+    readonly current?: Maybe<UserExternalConnection>;
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The next login link for this provider, or null to remove the provider's key entirely.
+     */
+    readonly login: Maybe<UserExternalConnectionLogin>;
+    readonly now: Date;
+}
+/**
+ * Applies a single provider's LOGIN LINK and returns the COMPLETE next document.
+ *
+ * The mirror of {@link applyUserExternalConnectionEntry}, and the only exported way to change `li`.
+ * The entry map is carried through unchanged: linking a provider as a login method grants nothing
+ * about its data connection, because the identity scopes and the data scopes are not guaranteed to
+ * be the same set.
+ *
+ * @param input - The current document plus the login link to apply.
+ * @returns The next UserExternalConnection value to write.
+ */
+export declare function applyUserExternalConnectionLogin(input: ApplyUserExternalConnectionLoginInput): UserExternalConnection;
+/**
+ * The identity facts a {@link UserExternalConnectionLogin} is derived from.
+ *
+ * Structurally the subset of `UserExternalConnectionSignInIdentity` (in
+ * `@dereekb/firebase-server/model`) that a link records. Declared here rather than imported because
+ * this package is shared with the browser and cannot name a server type — and because the derivation
+ * genuinely needs nothing more than these four values.
+ */
+export interface UserExternalConnectionLoginIdentity {
+    readonly externalAccountId: UserExternalConnectionExternalAccountId;
+    readonly email?: Maybe<EmailAddress>;
+    readonly emailVerified?: Maybe<boolean>;
+    readonly label?: Maybe<string>;
+}
+/**
+ * Input for {@link userExternalConnectionLoginForIdentity}.
+ */
+export interface UserExternalConnectionLoginForIdentityInput {
+    readonly identity: UserExternalConnectionLoginIdentity;
+    /**
+     * The link currently stored for this provider, when there is one.
+     */
+    readonly previous?: Maybe<UserExternalConnectionLogin>;
+    readonly now: Date;
+}
+/**
+ * Derives the {@link UserExternalConnectionLogin} for an identity a link round trip resolved.
+ *
+ * `lat` survives a relink, the mirror of how {@link userExternalConnectionEntryForOutcome} preserves
+ * `coa`: relinking the same provider is a re-consent, not a new relationship, so the date the account
+ * first became a login method stays what it was.
+ *
+ * @param input - The resolved identity, the stored link, and the instant to stamp.
+ * @returns The next login link.
+ */
+export declare function userExternalConnectionLoginForIdentity(input: UserExternalConnectionLoginForIdentityInput): UserExternalConnectionLogin;
 /**
  * Input for {@link emptyUserExternalConnection}.
  */
@@ -147,3 +267,18 @@ export declare function userExternalConnectionEntryIsExpired(entry: Maybe<UserEx
  * @returns True when the provider's entry is connected.
  */
 export declare function userExternalConnectionIsConnectedToProvider(connection: Maybe<UserExternalConnection>, providerType: UserExternalConnectionProviderType): boolean;
+/**
+ * Returns the login link for the given provider, if any.
+ *
+ * @param connection - The loaded connection document.
+ * @param providerType - The provider to read.
+ * @returns The provider's login link, or null when the provider is not a login method for this user.
+ */
+export declare function userExternalConnectionLoginForProvider(connection: Maybe<UserExternalConnection>, providerType: UserExternalConnectionProviderType): Maybe<UserExternalConnectionLogin>;
+/**
+ * Returns every provider type that is a login method for this user.
+ *
+ * @param connection - The loaded connection document.
+ * @returns The linked provider types, sorted for a stable render order.
+ */
+export declare function userExternalConnectionLinkedLoginProviderTypes(connection: Maybe<UserExternalConnection>): UserExternalConnectionProviderType[];

package/test/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "14.0.1",
+  "version": "14.2.0",
+  "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.0.1",
-    "@dereekb/firebase": "14.0.1",
-    "@dereekb/model": "14.0.1",
-    "@dereekb/rxjs": "14.0.1",
-    "@dereekb/util": "14.0.1",
+    "@dereekb/date": "14.2.0",
+    "@dereekb/firebase": "14.2.0",
+    "@dereekb/model": "14.2.0",
+    "@dereekb/rxjs": "14.2.0",
+    "@dereekb/util": "14.2.0",
     "@firebase/rules-unit-testing": "5.0.2",
     "date-fns": "^4.1.0",
     "firebase": "^12.18.0",