@rdlabo/ionic-angular-kit 0.0.14 → 0.0.16

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@rdlabo/ionic-angular-kit",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
     "@angular/router": "^21.0.0",
     "@ionic/angular": "^8.0.0",
     "@ionic/storage-angular": "^4.0.0",
+    "@angular/fire": ">=21.0.0-rc.0",
+    "firebase": "^11.0.0",
     "@capacitor/core": ">=6.0.0 <9.0.0",
     "@capacitor/haptics": ">=6.0.0 <9.0.0",
     "@capacitor/keyboard": ">=6.0.0 <9.0.0",
@@ -14,11 +16,19 @@
     "@capacitor/preferences": ">=6.0.0 <9.0.0",
     "@capacitor/status-bar": ">=6.0.0 <9.0.0",
     "@capacitor-community/in-app-review": ">=6.0.0 <9.0.0",
+    "@capacitor-community/facebook-login": ">=8.0.0 <9.0.0",
+    "@capacitor-community/apple-sign-in": "*",
     "@rdlabo/capacitor-brotherprint": ">=6.0.0 <9.0.0",
     "dom-to-image-more": "^3.0.0",
     "rxjs": "^7.8.0"
   },
   "peerDependenciesMeta": {
+    "@angular/fire": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    },
     "@capacitor/preferences": {
       "optional": true
     },
@@ -28,6 +38,12 @@
     "@capacitor-community/in-app-review": {
       "optional": true
     },
+    "@capacitor-community/facebook-login": {
+      "optional": true
+    },
+    "@capacitor-community/apple-sign-in": {
+      "optional": true
+    },
     "@rdlabo/capacitor-brotherprint": {
       "optional": true
     },
@@ -48,6 +64,26 @@
     ".": {
       "types": "./types/rdlabo-ionic-angular-kit.d.ts",
       "default": "./fesm2022/rdlabo-ionic-angular-kit.mjs"
+    },
+    "./auth-firebase": {
+      "types": "./types/rdlabo-ionic-angular-kit-auth-firebase.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-auth-firebase.mjs"
+    },
+    "./auth-firebase/social": {
+      "types": "./types/rdlabo-ionic-angular-kit-auth-firebase-social.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-auth-firebase-social.mjs"
+    },
+    "./printer": {
+      "types": "./types/rdlabo-ionic-angular-kit-printer.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-printer.mjs"
+    },
+    "./review": {
+      "types": "./types/rdlabo-ionic-angular-kit-review.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-review.mjs"
+    },
+    "./theme": {
+      "types": "./types/rdlabo-ionic-angular-kit-theme.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-theme.mjs"
     }
   },
   "type": "module"

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 };

package/types/rdlabo-ionic-angular-kit-printer.d.ts

@@ -0,0 +1,81 @@
+import { BRLMPrinterModelName, BRLMPrinterLabelName, BRLMPrintOptions } from '@rdlabo/capacitor-brotherprint';
+
+/**
+ * Rotate a base64 image 90°, returning a new base64 data URL of the same MIME type.
+ *
+ * @remarks
+ * Pure DOM/canvas work — no DI. Used before sending a label to the printer when the artwork must be
+ * turned to match the tape orientation. Extracted verbatim from the fleet's printer services so the
+ * canvas handling lives in one place.
+ *
+ * @param imageData - a base64 data URL (e.g. `data:image/png;base64,...`)
+ * @returns a Promise resolving to the rotated image as a base64 data URL
+ */
+declare const kitRotationImage: (imageData: string) => Promise<string>;
+/** Options for {@link kitDomToPng}. */
+interface KitDomToPngOptions {
+    /** When `true`, the rendered PNG is rotated 90° via {@link kitRotationImage}. Defaults to `false`. */
+    readonly rotate?: boolean;
+    /** Rendering scale passed to `dom-to-image-more`. Defaults to `3` (the fleet's print resolution). */
+    readonly scale?: number;
+}
+/**
+ * Render a DOM element to a base64 PNG for label printing, with the fleet's device-specific fixes.
+ *
+ * @remarks
+ * Pure function — no DI (reads the platform from `Capacitor`, uses the global `document`), so the
+ * caller presents its own loading UI around it. Centralizes the hard-won device quirks: on iOS it
+ * pads width/height by 2px (otherwise the bottom is clipped), on Android it does not (the padding
+ * introduces a black line). Retries the `dom-to-image-more` render up to 10 times because the first
+ * pass can occasionally return empty. This is exactly the kind of plumbing where a future fix should
+ * land in every app at once.
+ *
+ * @param element - the element to rasterize (e.g. the label preview host)
+ * @param options - rendering options; see {@link KitDomToPngOptions}
+ * @returns a Promise resolving to the PNG as a base64 data URL (empty string if every attempt failed)
+ * @example
+ * ```ts
+ * const loading = await this.#loadingCtrl.create({ message: this.text.generating });
+ * await loading.present();
+ * const png = await kitDomToPng(this.preview().nativeElement, { rotate: true });
+ * await loading.dismiss();
+ * ```
+ */
+declare const kitDomToPng: (element: HTMLElement, options?: KitDomToPngOptions) => Promise<string>;
+/** Parameters for {@link kitBuildBrotherPrintSettings}. */
+interface KitBrotherPrintSettingsParams {
+    /** The target printer model. */
+    readonly modelName: BRLMPrinterModelName;
+    /** The label artwork as a base64 data URL (the `data:...,` prefix is stripped internally). */
+    readonly printBase64: string;
+    /** The selected label/paper (its `W<width>H<height>` code drives the tape dimensions). */
+    readonly label: BRLMPrinterLabelName;
+    /** Number of copies to print. Passed by the caller (apps differ: some use the print option, some fix 1). */
+    readonly numberOfCopies: number;
+    /** Halftone threshold for the print. */
+    readonly halftoneThreshold: number;
+}
+/**
+ * Assemble the Brother `BRLMPrintOptions` for a die-cut label print, minus the transport fields.
+ *
+ * @remarks
+ * Pure function — no DI. Centralizes the fleet's canonical print settings (fit-page scale, centered,
+ * best quality, threshold halftone, 2mm/1mm margins, `gapLength` 2.0) and the tape sizing derived
+ * from the label's `W<width>H<height>` code. The caller merges the printer's `port` / `channelInfo`
+ * onto the result before calling `BrotherPrint.printImage()`, so channel selection and loading UI stay
+ * in the app.
+ *
+ * @param params - model, artwork, label, copies, and halftone threshold; see {@link KitBrotherPrintSettingsParams}
+ * @returns the `BRLMPrintOptions` ready to be spread with `{ port, channelInfo }`
+ * @example
+ * ```ts
+ * const settings = kitBuildBrotherPrintSettings({
+ *   modelName, printBase64, label, numberOfCopies: printOptions.printNum, halftoneThreshold: printOptions.halftoneThreshold,
+ * });
+ * await BrotherPrint.printImage({ ...settings, port: channel.port, channelInfo: channel.channelInfo });
+ * ```
+ */
+declare const kitBuildBrotherPrintSettings: (params: KitBrotherPrintSettingsParams) => BRLMPrintOptions;
+
+export { kitBuildBrotherPrintSettings, kitDomToPng, kitRotationImage };
+export type { KitBrotherPrintSettingsParams, KitDomToPngOptions };

package/types/rdlabo-ionic-angular-kit-review.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Options for {@link kitRequestReview}.
+ */
+interface KitRequestReviewOptions {
+    /**
+     * Key under which the timestamp of the last review request is stored (via `@capacitor/preferences`).
+     *
+     * @remarks
+     * Supplied by the caller so the kit ships no storage keys of its own; each app passes its own enum
+     * value.
+     */
+    readonly storageKey: string;
+    /**
+     * Minimum number of months between review prompts.
+     *
+     * @remarks
+     * A prompt is only shown when this much time has elapsed since the last one (or when there is no
+     * record yet), so the OS review dialog is never nagged repeatedly.
+     */
+    readonly throttleMonths: number;
+}
+/**
+ * Request the native in-app review dialog, throttled so the user is prompted at most once per window.
+ *
+ * @remarks
+ * A plain function — no DI needed (`@capacitor/preferences`, `@capacitor-community/in-app-review` and
+ * `Capacitor` are all static), so the caller invokes it directly and passes its own config rather
+ * than injecting a controller. A no-op on non-native platforms. When enough time has elapsed since
+ * the last prompt (per {@link KitRequestReviewOptions.throttleMonths}, tracked under
+ * {@link KitRequestReviewOptions.storageKey}), it briefly waits for the app to settle, calls
+ * `InAppReview.requestReview()`, and records the new timestamp. The wait/throttle/record sequence
+ * was previously copy-pasted verbatim across the fleet; centralizing it means a single place to tune
+ * the prompt cadence.
+ *
+ * @param options - the storage key and throttle window; see {@link KitRequestReviewOptions}
+ * @returns a Promise that resolves once the request has been made (or immediately if throttled / on web)
+ * @example
+ * ```ts
+ * await kitRequestReview({ storageKey: StorageEnum.lastRequestRate, throttleMonths: 3 });
+ * ```
+ */
+declare const kitRequestReview: (options: KitRequestReviewOptions) => Promise<void>;
+
+export { kitRequestReview };
+export type { KitRequestReviewOptions };