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;