@rdlabo/ionic-angular-kit 0.0.15 → 0.0.16

package/types/rdlabo-ionic-angular-kit-auth-firebase-social.d.ts

@@ -0,0 +1,104 @@
+import { Auth } from 'firebase/auth';
+
+/** How a social-credential failure is classified for the app's error hook. */
+type KitOAuthErrorCategory = 'already-in-use' | 'cancelled' | 'other';
+/** The mode a social login runs in. */
+type KitOAuthModeName = 'new' | 'link' | 'credential';
+/**
+ * The mode discriminator. `'credential'` links an email/password to the (re-authenticated) social
+ * account, so it requires the new email/password; `'new'` / `'link'` do not.
+ */
+type KitOAuthMode = {
+    mode: 'new';
+} | {
+    mode: 'link';
+} | {
+    mode: 'credential';
+    emailLogin: {
+        email: string;
+        password: string;
+    };
+};
+/**
+ * The apple identity payload handed to the `success` hook for the backend call. Populated from the
+ * native plugin on device, or synthesized from the popup result on the web.
+ */
+interface KitAppleResponse {
+    user: string | null;
+    email: string | null;
+    givenName: string | null;
+    familyName: string | null;
+    identityToken: string | null;
+    authorizationCode: string | null;
+}
+/**
+ * The uniform lifecycle hooks for a social flow — the same `before / success / error / finally`
+ * shape as {@link KitFirebaseAuthService}'s hooks, so a call site reads the same everywhere. All are
+ * optional; the kit renders nothing itself.
+ *
+ * @typeParam Info - the identity payload handed to {@link success} (Facebook access token / Apple
+ * response), so an app can notify its backend and give feedback in one place.
+ *
+ * @remarks
+ * `before` runs before the plugin login starts, `success` after the mode's Firebase op succeeds
+ * (carrying the identity payload — do the backend call and the toast here), `error` on a classified
+ * failure (`'cancelled'` is passed through so the app can stay silent on a user cancel), and
+ * `finally` always. The kit swallows none of these errors.
+ */
+interface KitSocialHooks<Info> {
+    before?: () => void | Promise<unknown>;
+    success?: (info: Info) => void | Promise<unknown>;
+    error?: (category: KitOAuthErrorCategory, error: unknown) => void | Promise<unknown>;
+    finally?: () => void | Promise<unknown>;
+}
+/** Options for {@link kitFacebookLogin}. */
+type KitFacebookLoginOptions = KitOAuthMode & KitSocialHooks<{
+    accessToken: string;
+    mode: KitOAuthModeName;
+}> & {
+    /** Facebook permissions to request. */
+    permissions: string[];
+};
+/** Options for {@link kitAppleLogin}. */
+type KitAppleLoginOptions = KitOAuthMode & KitSocialHooks<{
+    response: KitAppleResponse;
+    mode: KitOAuthModeName;
+}>;
+/**
+ * Facebook login / link, bundled: native plugin → credential → the shared 3-mode state machine.
+ *
+ * @remarks
+ * On iOS the credential is built from the OIDC token with a nonce (`OAuthProvider('facebook.com')`);
+ * elsewhere from the access token (`FacebookAuthProvider`). Returns `{ status: false }` on a
+ * cancelled/failed plugin login or a handled Firebase error (the app was already notified via the
+ * hooks).
+ */
+declare const kitFacebookLogin: (auth: Auth, options: KitFacebookLoginOptions) => Promise<{
+    status: boolean;
+}>;
+/**
+ * Log out of the Facebook SDK (best-effort; errors are ignored).
+ *
+ * @remarks
+ * Apps that offer Facebook login typically call this alongside the Firebase sign-out, so it lives
+ * here to keep the `@capacitor-community/facebook-login` import out of the app.
+ */
+declare const kitFacebookLogout: () => Promise<void>;
+/**
+ * Sign in with Apple / link, bundled. Native uses the plugin; the web uses the Firebase popup.
+ *
+ * @remarks
+ * - **Native**: `SignInWithApple.authorize()` → `OAuthProvider('apple.com')` credential → the shared
+ *   3-mode state machine.
+ * - **Web**: `signInWithPopup` / `linkWithPopup` (with `email`/`name` scopes), or, for `credential`,
+ *   `reauthenticateWithPopup` then link the email/password. The identity payload for the backend is
+ *   synthesized from the popup result.
+ *
+ * Every failure path (including popup errors) is routed through `onError`.
+ */
+declare const kitAppleLogin: (auth: Auth, options: KitAppleLoginOptions) => Promise<{
+    status: boolean;
+}>;
+
+export { kitAppleLogin, kitFacebookLogin, kitFacebookLogout };
+export type { KitAppleLoginOptions, KitAppleResponse, KitFacebookLoginOptions, KitOAuthErrorCategory, KitOAuthMode, KitOAuthModeName };

package/types/rdlabo-ionic-angular-kit-auth-firebase.d.ts

@@ -0,0 +1,266 @@
+import { InjectionToken, EnvironmentProviders } from '@angular/core';
+import { FirebaseOptions } from '@angular/fire/app';
+import { Auth, User, UserCredential } from 'firebase/auth';
+import { Observable } from 'rxjs';
+
+/**
+ * DI token for the Firebase `Auth` instance.
+ *
+ * @remarks
+ * Inject this (`inject(KIT_FIREBASE_AUTH)`) instead of `@angular/fire`'s `Auth`, so the
+ * `@angular/fire` dependency stays isolated inside the kit. This is the seam that makes the planned
+ * `@angular/fire` → `firebase/auth` migration a kit-internal change: only {@link provideKitFirebase}
+ * (which binds this token) has to change; every consumer keeps injecting `KIT_FIREBASE_AUTH`.
+ *
+ * The value is a `firebase/auth` `Auth` (the SDK type is exposed directly, not re-abstracted —
+ * Firebase Auth itself is not being dropped, only the `@angular/fire` wrapper).
+ */
+declare const KIT_FIREBASE_AUTH: InjectionToken<Auth>;
+/** Configuration for {@link provideKitFirebase}. */
+interface KitFirebaseConfig {
+    /** The Firebase project options (`apiKey`, `authDomain`, `projectId`, …). */
+    readonly firebaseConfig: FirebaseOptions;
+}
+/**
+ * Wire Firebase App + Auth into the application and bind {@link KIT_FIREBASE_AUTH}.
+ *
+ * @remarks
+ * Replaces each app's hand-rolled `provideFirebaseApp(...)` + `provideAuth(...)` (with its
+ * native/web persistence branch) with one call, and — crucially — keeps `@angular/fire` out of the
+ * application: apps inject {@link KIT_FIREBASE_AUTH} and import auth operations/types straight from
+ * `firebase/auth`. On a native platform the persistence uses `indexedDBLocalPersistence`; on the web
+ * it uses the default (`getAuth`).
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideKitFirebase({ firebaseConfig: environment.firebase })],
+ * });
+ * ```
+ */
+declare const provideKitFirebase: (config: KitFirebaseConfig) => EnvironmentProviders;
+/**
+ * Wire Firebase Analytics into the application (optional; only the apps that use it call this).
+ */
+declare const provideKitFirebaseAnalytics: () => EnvironmentProviders;
+
+/** A user-facing message (alert header + body). */
+interface KitAuthMessage {
+    readonly header: string;
+    readonly message: string;
+}
+/**
+ * The fleet's canonical Firebase auth error dictionary: error `code` → message, plus a fallback for
+ * unmapped codes.
+ *
+ * @remarks
+ * The kit does *not* present errors itself (that's an app side effect). This is offered as an
+ * importable constant so an app can render its error alert from a shared, canonical source instead of
+ * re-declaring the same five messages. Apps that need `$localize` (i18n) keep their own dictionary;
+ * JA-only apps can import {@link KIT_DEFAULT_AUTH_TEXT} and spread it, overriding the odd code.
+ *
+ * @example
+ * ```ts
+ * import { KIT_DEFAULT_AUTH_TEXT } from '@rdlabo/ionic-angular-kit/auth-firebase';
+ *
+ * const AUTH_ERRORS = { ...KIT_DEFAULT_AUTH_TEXT.errors, 'auth/wrong-password': { header: '…', message: '…' } };
+ * presentError(code: string) {
+ *   const msg = AUTH_ERRORS[code] ?? KIT_DEFAULT_AUTH_TEXT.fallbackError;
+ *   return this.overlay.alertClose(msg);
+ * }
+ * ```
+ */
+interface KitAuthText {
+    /** Firebase error `code` → message. */
+    readonly errors: Readonly<Record<string, KitAuthMessage>>;
+    /** Shown when an error has no matching `code`. */
+    readonly fallbackError: KitAuthMessage;
+}
+/** The fleet's canonical Japanese error dictionary (see {@link KitAuthText}). */
+declare const KIT_DEFAULT_AUTH_TEXT: KitAuthText;
+
+/**
+ * Uniform lifecycle hooks for the bundled email/password auth flows — where the app hangs its own
+ * side effects on a flow.
+ *
+ * @remarks
+ * The kit performs the Firebase operation and renders nothing itself. `before` runs before the op,
+ * `success` on success, `error` on failure (with the raw error — the app presents it, from its own
+ * dictionary), and `finally` always. Failures are *not* thrown: value flows resolve to `null` and
+ * boolean flows to `false`. Return values are awaited and ignored.
+ *
+ * @example
+ * ```ts
+ * kitSignIn(auth, email, password, {
+ *   error: (e) => this.presentAuthError(e),   // app's own error dictionary
+ *   success: () => this.nav.navigateRoot('/'),
+ * });
+ * ```
+ */
+interface KitAuthHooks {
+    before?: () => void | Promise<unknown>;
+    success?: () => void | Promise<unknown>;
+    error?: (error: unknown) => void | Promise<unknown>;
+    finally?: () => void | Promise<unknown>;
+}
+/**
+ * Sign in with email and password.
+ *
+ * @remarks
+ * Bundles the Firebase op so the app never imports `signInWithEmailAndPassword` directly (the SDK
+ * stays isolated in the kit). Resolves the credential, or `null` on failure (handed to the `error`
+ * hook).
+ */
+declare const kitSignIn: (auth: Auth, email: string, password: string, hooks?: KitAuthHooks) => Promise<UserCredential | null>;
+/**
+ * Create an account and send the verification email.
+ *
+ * @remarks
+ * Bundles the two-step "create → send verification" sequence. Resolves the credential, or `null` on
+ * failure. Any success toast is the caller's, via the `success` hook.
+ */
+declare const kitSignUp: (auth: Auth, email: string, password: string, hooks?: KitAuthHooks) => Promise<UserCredential | null>;
+/**
+ * Sign out.
+ *
+ * @remarks
+ * App-specific cleanup (clearing stores, toasts, navigation, third-party logout) is the caller's,
+ * done via the hooks — the kit only owns the Firebase op. `true` on success, `false` on failure.
+ */
+declare const kitSignOut: (auth: Auth, hooks?: KitAuthHooks) => Promise<boolean>;
+/** Send a password-reset email. `true` on success, `false` on failure. */
+declare const kitSendPasswordReset: (auth: Auth, email: string, hooks?: KitAuthHooks) => Promise<boolean>;
+/**
+ * Unlink a linked auth provider (e.g. `'facebook.com'`, `'apple.com'`) from the current user.
+ *
+ * @remarks
+ * Exposed from the core (not `/social`) so an app can unlink without importing `unlink` from
+ * `firebase/auth` directly — keeping the invariant that the SDK is only imported inside the kit. Any
+ * app-specific step around it (e.g. a backend DELETE before unlinking) goes in the `before` hook.
+ * Resolves the updated `User`, or `null` on failure (including when there is no signed-in user).
+ */
+declare const kitUnlinkProvider: (auth: Auth, providerId: string, hooks?: KitAuthHooks) => Promise<User | null>;
+/**
+ * (Re-)send the verification email to the signed-in user (a no-op when signed out).
+ *
+ * @remarks
+ * `true` on success (including the signed-out no-op), `false` on failure.
+ */
+declare const kitSendEmailVerification: (auth: Auth, hooks?: KitAuthHooks) => Promise<boolean>;
+/**
+ * The current Firebase user as an Observable (emits on every auth-state change; `null` when signed out).
+ *
+ * @remarks
+ * Wraps `onAuthStateChanged` so consumers get an rxjs stream without pulling in `@angular/fire`'s
+ * `authState` (or `rxfire`). Emits the current value on subscribe and completes its listener on
+ * teardown.
+ *
+ * @param auth - the Firebase `Auth` instance (inject `KIT_FIREBASE_AUTH`)
+ */
+declare const kitAuthState: (auth: Auth) => Observable<User | null>;
+/**
+ * The current user's ID token, or `null` when signed out.
+ *
+ * @remarks
+ * For building `Authorization` / bearer headers in interceptors and services. Failure to fetch a
+ * token is **thrown, not swallowed** — the caller decides the fallback (e.g. an empty header) as its
+ * own side effect, so the kit never silently hides an auth failure.
+ *
+ * @param auth - the Firebase `Auth` instance (inject `KIT_FIREBASE_AUTH`)
+ * @param forceRefresh - force a token refresh (default `false`)
+ * @returns the ID token, or `null` if there is no signed-in user
+ * @throws if the token fetch fails for a signed-in user
+ */
+declare const kitGetIdToken: (auth: Auth, forceRefresh?: boolean) => Promise<string | null>;
+/**
+ * The app-supplied side effects for {@link kitReauthWithRetry}.
+ *
+ * @remarks
+ * The kit owns the *control flow* but generates no UI; every user-facing effect (the prompt, the
+ * loading overlay) is a callback the app implements, rendering from its own dictionary.
+ */
+interface KitReauthWithRetryOptions {
+    /**
+     * Present the current-password prompt.
+     *
+     * @remarks
+     * A side effect — the app presents whatever it likes (e.g. an `ion-alert` with a masked input and
+     * dictionary text). Receives `true` when re-prompting after a wrong password.
+     *
+     * @returns the entered password, or `null` if the user cancels/dismisses
+     */
+    prompt: (wrongPasswordRetry: boolean) => Promise<string | null>;
+    /**
+     * The sensitive change to run once re-authenticated.
+     *
+     * @remarks
+     * Keep this pure — just the Firebase op(s) (e.g. `updatePassword(user, next)`). Loading and other
+     * UI are side effects handled by {@link withLoading}, not here.
+     */
+    mutate: (user: User) => Promise<void>;
+    /**
+     * Wrap the re-authentication + mutation with a loading indicator (a side effect).
+     *
+     * @remarks
+     * Optional. Runs only after a password is entered, around each attempt — so no loading flashes on a
+     * cancelled prompt, and it re-shows on a wrong-password retry. The app implements it (e.g.
+     * present/dismiss an `ion-loading`).
+     */
+    withLoading?: (run: () => Promise<void>) => Promise<void>;
+}
+/**
+ * Run the fleet's canonical "confirm current password → change" flow, re-prompting in place on a
+ * wrong password.
+ *
+ * @remarks
+ * Owns the drift-prone *control flow* (the retry loop, the wrong-password classification every app
+ * once got wrong, and when to show loading) while generating **no UI** — the prompt and the loading
+ * overlay are {@link KitReauthWithRetryOptions | side-effect callbacks} the app supplies. On a wrong
+ * password the loop re-prompts instead of dropping the user out of the flow. Any non-wrong-password
+ * re-auth failure (lockout, offline, expired session) and any error from `mutate` are re-thrown —
+ * re-auth failures unwrapped to the underlying Firebase error so the caller's error dictionary can
+ * read its `code`.
+ *
+ * @param auth - the Firebase `Auth` instance
+ * @param currentEmail - the current email (for the re-auth credential)
+ * @param options - the pure mutation plus the app's prompt / loading side effects
+ * @returns `true` if the mutation completed, `false` if the user cancelled
+ * @throws the underlying Firebase error on a non-wrong-password failure, or `mutate`'s own error
+ */
+declare const kitReauthWithRetry: (auth: Auth, currentEmail: string, options: KitReauthWithRetryOptions) => Promise<boolean>;
+/** The fleet's 3-state auth status derived from the Firebase user. */
+type KitAuthStatus = 'user' | 'confirm' | 'required';
+/** Options for {@link kitResolveAuthStatus}. */
+interface KitResolveAuthStatusOptions {
+    /**
+     * Provider IDs that count as verified even without `emailVerified` — a social login (e.g.
+     * `'facebook.com'`, `'apple.com'`) has no email-verification step but is a real, trusted account.
+     */
+    readonly verifiedProviders?: readonly string[];
+    /**
+     * Extra predicate to treat a signed-in user as fully authed regardless of verification — for an
+     * e2e bypass or an anonymous-allowed app. Receives the current user.
+     */
+    readonly allowWhen?: (user: User) => boolean;
+}
+/**
+ * Classify a Firebase user into the fleet's 3-state auth status.
+ *
+ * @remarks
+ * `null` (signed out) → `'required'`. A signed-in user is `'user'` when their email is verified, OR
+ * they signed in with one of `verifiedProviders`, OR `allowWhen` returns true; otherwise `'confirm'`
+ * (signed in but unverified). This is only the shared classification — app-specific side effects
+ * around it (reloading the user to refresh `emailVerified`, caching a token) stay in the app.
+ *
+ * @example
+ * ```ts
+ * kitResolveAuthStatus(user, {
+ *   verifiedProviders: ['facebook.com', 'apple.com'],
+ *   allowWhen: () => environment.e2e,
+ * });
+ * ```
+ */
+declare const kitResolveAuthStatus: (user: User | null, options?: KitResolveAuthStatusOptions) => KitAuthStatus;
+
+export { KIT_DEFAULT_AUTH_TEXT, KIT_FIREBASE_AUTH, kitAuthState, kitGetIdToken, kitReauthWithRetry, kitResolveAuthStatus, kitSendEmailVerification, kitSendPasswordReset, kitSignIn, kitSignOut, kitSignUp, kitUnlinkProvider, provideKitFirebase, provideKitFirebaseAnalytics };
+export type { KitAuthHooks, KitAuthMessage, KitAuthStatus, KitAuthText, KitFirebaseConfig, KitReauthWithRetryOptions, KitResolveAuthStatusOptions };