@heyama/pay-react-native 0.0.0-stage → 1.0.1

package/dist/checkout-core/models/checkout.interface.d.ts

@@ -0,0 +1,417 @@
+import type { CardFieldsMessageEnum, CheckoutPaymentStatusEnum, CheckoutScreenEnum, CheckoutTabEnum, CheckoutThemeEnum, MethodBrandEnum, MethodFlowEnum, MethodKindEnum, MethodStateEnum, PayRefusalEnum, PhoneErrorEnum, SimulatorOutcomeEnum, SupportChannelEnum } from './checkout.enum.js';
+import type { AttemptStatusEnum, CountryEnum, CurrencyEnum, FailureReasonEnum, LangEnum, ProviderLogoEnum } from './domain.enum.js';
+export interface CheckoutApp {
+    name: string;
+    color: string;
+    logoUrl: string | null;
+    termsUrl: string | null;
+    privacyUrl: string | null;
+    supportEmail: string | null;
+    /** E.164. */
+    supportWhatsapp: string | null;
+}
+export interface CheckoutItem {
+    name: string;
+    quantity: number;
+    /** Minor units. */
+    unitAmount: number;
+}
+/** A payment method this payment can be paid with, in the admin's order. */
+export interface CheckoutMethod {
+    id: string;
+    name: string;
+    kind: MethodKindEnum;
+    country: CountryEnum;
+    /** The network that runs it ("Orange Cameroun"). */
+    network: string;
+    flow: MethodFlowEnum;
+    /** The code a payer dials to see payments waiting for approval. */
+    pendingCode: string | null;
+    /** OTP methods: what the payer dials to get a payment code for this amount. */
+    otpCode: string | null;
+    /** Card methods: the provider's page hosting its card fields, shown in an iframe. */
+    cardFieldsPath: string | null;
+    logos: Array<ProviderLogoEnum>;
+    state: MethodStateEnum;
+    /** Why it is in maintenance, for the payer. */
+    note: string | null;
+}
+/**
+ * A paid card as its provider reported it: never more than the last 4
+ * digits. The brand is the provider's own word, whatever the network.
+ */
+export interface CardSummary {
+    brand: string;
+    last4: string;
+}
+export interface CheckoutAttempt {
+    reference: string;
+    method: string;
+    /** As the payer read it when paying. */
+    methodName: string;
+    logos: Array<ProviderLogoEnum>;
+    flow: MethodFlowEnum;
+    pendingCode: string | null;
+    status: AttemptStatusEnum;
+    failureReason: FailureReasonEnum | null;
+    /** E.164; a card has none. */
+    phone: string | null;
+    /** A paid card: its brand and last 4 digits. */
+    card: CardSummary | null;
+    startedAt: number;
+    /** A test attempt the Simulator took: the tester picks its outcome. */
+    simulated: boolean;
+}
+export interface CheckoutPayer {
+    name: string | null;
+    phone: string | null;
+    email: string | null;
+}
+/** One payment as the checkout shows it (`checkout.queries.get`). */
+export interface CheckoutView {
+    id: string;
+    status: CheckoutPaymentStatusEnum;
+    test: boolean;
+    /** Minor units. */
+    amount: number;
+    currency: CurrencyEnum;
+    orderRef: string | null;
+    items: Array<CheckoutItem>;
+    returnUrl: string;
+    expiresAt: number;
+    paidAt: number | null;
+    payer: CheckoutPayer;
+    /** The app's hint for the payer's country. */
+    country: CountryEnum | null;
+    language: LangEnum | null;
+    theme: CheckoutThemeEnum | null;
+    preferredMethod: string | null;
+    preferredTab: CheckoutTabEnum | null;
+    app: CheckoutApp;
+    methods: Array<CheckoutMethod>;
+    /** Payer-caused failures it still takes before it locks, out of `maxAttempts`. */
+    attemptsLeft: number;
+    maxAttempts: number;
+    attempt: CheckoutAttempt | null;
+    /**
+     * Where the checkout is served, without a trailing slash: the payment
+     * sheet loads card fields pages (`cardFieldsPath`) from it.
+     */
+    siteUrl: string;
+}
+/** Where the request came from, for picking the payer's country. */
+export interface CountryClues {
+    /** From the proxy's country header, when it sends one. */
+    ipCountry: string | null;
+    /** Browser languages in preference order (`fr-CM`). */
+    languages: Array<string>;
+}
+/** A greyed row on the Card tab for a wallet no provider offers yet. */
+export interface ComingSoonWallet {
+    /** Catalog key under `wallets` and logo name. */
+    id: ProviderLogoEnum;
+}
+export interface OperatorDetection {
+    /** The operator the number belongs to, once enough digits say so. */
+    operator: MethodBrandEnum | null;
+    /** Enough digits were typed and no known operator matches. */
+    unrecognized: boolean;
+}
+export interface PhoneInputs {
+    country: CountryEnum;
+    /** Digits of the national number, no dial code and no spaces. */
+    digits: string;
+    /** A full international number of a country the payment is not offered in. */
+    foreign: boolean;
+    touched: boolean;
+    focused: boolean;
+    submitTried: boolean;
+}
+export interface PhoneStatus {
+    error: PhoneErrorEnum | null;
+    valid: boolean;
+    operator: MethodBrandEnum | null;
+}
+/** What the payer typed, read: its country and national digits. */
+export interface TypedNumber {
+    country: CountryEnum;
+    digits: string;
+    /** A `+…` number kept as typed while its country is unknown or not offered. */
+    pending: string | null;
+}
+export interface PhoneNumberOptions {
+    country: CountryEnum;
+    /** Countries of this payment's Mobile Money methods. */
+    countries: Array<CountryEnum>;
+    /** The payer typed or pasted a full number of another offered country. */
+    onCountryChange: (country: CountryEnum) => void;
+}
+/** The Mobile Money number without its field: each platform draws and wires its own input. */
+export interface PhoneNumber {
+    /** What the field shows: the number grouped the country's way. */
+    value: string;
+    /**
+     * The field's new text and where its caret was; answers where the caret
+     * goes in the grouped number, or null to leave it (an international number).
+     */
+    type: (text: string, caret: number) => number | null;
+    /** E.164, empty until the number is complete. */
+    e164: string;
+    dial: string;
+    placeholder: string;
+    status: PhoneStatus;
+    focused: boolean;
+    onFocus: () => void;
+    onBlur: () => void;
+    /** Marks the field as submitted, so its error shows. */
+    reject: () => void;
+    /** The app's number for the payer, when it is of the page's country. */
+    fill: (e164: string) => void;
+}
+/** What the payer did on this page; the payment itself comes from the gateway. */
+export interface CheckoutUi {
+    tab: CheckoutTabEnum;
+    country: CountryEnum;
+    /** The Mobile Money method picked, if any. */
+    method: string | null;
+    /** The payment code typed for an OTP method; cleared when the method changes. */
+    code: string;
+    /** A card method's fields say the card is complete. */
+    cardComplete: boolean;
+    /** Pay went to the card fields page: the form stays until it says how it went. */
+    cardPaying: boolean;
+    pickerOpen: boolean;
+    summaryOpen: boolean;
+    submitting: boolean;
+    /** An attempt the payer walked away from: the form shows again. */
+    dismissed: string | null;
+    redirecting: boolean;
+}
+/** Everything the screens show that follows from the payment and the page, worked out once. */
+export interface CheckoutDerived {
+    screen: CheckoutScreenEnum;
+    /** Countries with Mobile Money methods, in the admin's order. */
+    countries: Array<CountryEnum>;
+    wallets: Array<CheckoutMethod>;
+    cards: Array<CheckoutMethod>;
+    /** The picked method, while it can still be used. */
+    selected: CheckoutMethod | null;
+    canPay: boolean;
+    /** The number belongs to another method of the country than the one picked. */
+    mismatch: CheckoutMethod | null;
+    /** After a failure: another method of the same country the payer can use now. */
+    suggestion: CheckoutMethod | null;
+}
+export interface CheckoutCoreActions {
+    toggleSummary: () => void;
+    setTab: (tab: CheckoutTabEnum) => void;
+    setCountry: (country: CountryEnum) => void;
+    selectMethod: (method: CheckoutMethod) => void;
+    /** A greyed wallet no provider offers yet was tapped. */
+    comingSoon: (name: string) => void;
+    openPicker: () => void;
+    switchToDetected: () => void;
+    pay: () => void;
+    /** The failed attempt again: same method, same number. An OTP method asks for a new code first. */
+    retry: () => void;
+    setCode: (code: string) => void;
+    /** The phone could not open its dialler on the OTP method's code: dial it by hand. */
+    cannotDial: () => void;
+    /** Leaves the failure screen for the suggested method, or the list. */
+    useAnother: () => void;
+    /** "Didn't get it?": the prompt again. */
+    resend: () => void;
+    cancel: () => void;
+    returnNow: () => void;
+    stayHere: () => void;
+    openHelp: () => void;
+    closeHelp: () => void;
+    copyReference: () => void;
+    downloadReceipt: () => void;
+    simulate: (outcome: SimulatorOutcomeEnum) => void;
+}
+/** The checkout's state and actions, the same on the web page and in the payment sheet. */
+export interface CheckoutCore {
+    /** Null for a link that matches no payment. */
+    view: CheckoutView | null;
+    ui: CheckoutUi;
+    derived: CheckoutDerived;
+    phone: PhoneNumber;
+    /** Seconds left on the waiting screen's clock. */
+    waitLeft: number;
+    /** Seconds before the success screen sends the payer back, null once stopped. */
+    returnLeft: number | null;
+    helpOpen: boolean;
+    toastMessage: string | null;
+    copied: boolean;
+    /** The Branding tab's preview: nothing can be paid. */
+    preview: boolean;
+    /** The card fields' content height, as their page last said; null until it loaded. */
+    cardHeight: number | null;
+    actions: CheckoutCoreActions;
+}
+/**
+ * What only the platform can do, handed to the controller. Pass one stable
+ * object: a new one each render subscribes again.
+ */
+export interface CheckoutPlatform {
+    /** Calls `listener` each time the payer comes back to the page or the app; answers how to stop. */
+    onReturn: (listener: () => void) => () => void;
+    copyText: (text: string) => void;
+    /** Leaves for the app's return URL. */
+    openUrl: (url: string) => void;
+    /** Calls `listener` with each message the card fields page sends; answers how to stop. */
+    onCardMessage: (listener: (message: CardFieldsMessage) => void) => () => void;
+    /** Tells the card fields page that Pay was pressed. */
+    submitCard: () => void;
+    /** Hands the receipt to the payer as a text file. */
+    saveReceipt: (fileName: string, text: string) => void;
+    /** Pay found the number wrong: draw the payer's eye to the field. */
+    onPhoneRejected: () => void;
+}
+export interface CheckoutControllerOptions {
+    clues: CountryClues;
+    /** Null on the Branding tab's preview: nothing is paid there. */
+    mutations: CheckoutMutations | null;
+    platform: CheckoutPlatform;
+}
+/** What Pay answers: refused with a reason, or an attempt started. */
+export interface PayResult {
+    ok: boolean;
+    reason?: PayRefusalEnum;
+}
+/** The gateway calls the page makes; none on the Branding tab's preview. */
+export interface CheckoutMutations {
+    pay: (args: {
+        paymentId: string;
+        method: string;
+        phone: string;
+    }) => Promise<PayResult>;
+    /** OTP methods: Pay with the payment code, which the server never stores. */
+    payWithCode: (args: {
+        paymentId: string;
+        method: string;
+        phone: string;
+        otp: string;
+    }) => Promise<PayResult>;
+    checkNow: (args: {
+        paymentId: string;
+    }) => Promise<null>;
+    /** The payer opened the link; the funnel counts the first time only. */
+    open: (args: {
+        paymentId: string;
+    }) => Promise<null>;
+    cancel: (args: {
+        paymentId: string;
+    }) => Promise<null>;
+    resend: (args: {
+        paymentId: string;
+    }) => Promise<{
+        ok: boolean;
+    }>;
+    simulate: (args: {
+        paymentId: string;
+        outcome: SimulatorOutcomeEnum;
+    }) => Promise<null>;
+}
+/** What the payer typed in the Simulator's stand-in card fields; it never leaves that page. */
+export interface CardEntry {
+    number: string;
+    expiry: string;
+    cvc: string;
+}
+/** A card fields page's address: the payment, its method, and the look of the checkout that shows it. */
+export interface CardFieldsSearch {
+    payment?: string;
+    method?: string;
+    /** The app colour, a hex code. */
+    color?: string;
+    theme?: CheckoutThemeEnum.DARK;
+}
+/** The Simulator's stand-in card fields page, from its address. */
+export interface SimulatorCardFieldsProps {
+    /** Null when the page is opened on its own: nothing can be paid. */
+    paymentId: string | null;
+    method: string | null;
+    /** The app colour, a hex code. */
+    color: string | null;
+    dark: boolean;
+}
+/** What a card fields page and the checkout send each other (`CardFieldsMessageEnum`). */
+export interface CardFieldsMessage {
+    type: CardFieldsMessageEnum;
+    complete?: boolean;
+    height?: number;
+    reason?: PayRefusalEnum;
+}
+/** How a Pay goes: the number, and the payment code of an OTP method. */
+export interface PayVia {
+    phone: string;
+    otp?: string;
+}
+/** The Convex calls of the stand-in card fields page. */
+export interface SimulatorCardFieldsCalls {
+    startCard: (args: {
+        paymentId: string;
+        method: string;
+    }) => Promise<{
+        ok: true;
+        reference: string;
+        providerReference: string | null;
+    } | {
+        ok: false;
+        reason: PayRefusalEnum;
+    }>;
+    receiveCard: (args: {
+        reference: string;
+        brand: string;
+        last4: string;
+    }) => Promise<null>;
+    checkNow: (args: {
+        paymentId: string;
+    }) => Promise<null>;
+}
+/** What each way of approving changes on the screens. */
+export interface FlowTraits {
+    /** The tab its methods are on. */
+    tab: CheckoutTabEnum;
+    /** A prompt on the phone: the waiting screen's steps and "send it again". */
+    prompt: boolean;
+    /** What the Simulator offers that this flow's payer cannot do. */
+    hiddenOutcomes: Array<SimulatorOutcomeEnum>;
+}
+/** The checkout's themed colours (`--ck-*` in `checkout.css`), for a platform without the stylesheet. */
+export interface CheckoutColors {
+    page: string;
+    surface: string;
+    tabOn: string;
+    fill: string;
+    fill2: string;
+    fill3: string;
+    ink: string;
+    inkStrong: string;
+    ink2: string;
+    muted: string;
+    faint: string;
+    line: string;
+    line2: string;
+    line3: string;
+    line4: string;
+    danger: string;
+    dangerSoft: string;
+    warnSoft: string;
+    warnLine: string;
+    warnInk: string;
+    warnInk2: string;
+    successInk: string;
+}
+export interface CheckoutPreviewApp {
+    name: string;
+    color: string;
+    logoUrl: string | null;
+}
+export interface SupportContact {
+    channel: SupportChannelEnum;
+    value: string;
+    href: string;
+}

package/dist/checkout-core/models/checkout.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/checkout-core/models/checkout.money.utils.d.ts

@@ -0,0 +1,7 @@
+import type { CurrencyEnum } from './domain.enum.js';
+/** 15000 XAF → "15 000", 1250 EUR → "12.50": grouped with a narrow no-break space, so it never wraps. */
+export declare function formatAmount(minor: number, currency: CurrencyEnum): string;
+/** "15 000 FCFA". */
+export declare function formatMoney(minor: number, currency: CurrencyEnum): string;
+/** "02:05" style clock for the approval countdown. */
+export declare function formatClock(totalSeconds: number): string;

package/dist/checkout-core/models/checkout.money.utils.js

@@ -0,0 +1,21 @@
+import { CURRENCY_DECIMALS, CURRENCY_LABEL } from "./checkout.constants.js";
+const THIN_SPACE = ' ';
+/** 15000 XAF → "15 000", 1250 EUR → "12.50": grouped with a narrow no-break space, so it never wraps. */
+export function formatAmount(minor, currency) {
+    const decimals = CURRENCY_DECIMALS[currency];
+    const [whole, fraction] = (minor / 10 ** decimals)
+        .toFixed(decimals)
+        .split('.');
+    const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, THIN_SPACE);
+    return fraction ? `${grouped}.${fraction}` : grouped;
+}
+/** "15 000 FCFA". */
+export function formatMoney(minor, currency) {
+    return `${formatAmount(minor, currency)} ${CURRENCY_LABEL[currency]}`;
+}
+/** "02:05" style clock for the approval countdown. */
+export function formatClock(totalSeconds) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = String(totalSeconds % 60).padStart(2, '0');
+    return `${minutes}:${seconds}`;
+}

package/dist/checkout-core/models/checkout.phone.utils.d.ts

@@ -0,0 +1,33 @@
+import { CountryEnum } from './domain.enum.js';
+import type { OperatorDetection, PhoneInputs, PhoneStatus, TypedNumber } from './checkout.interface.js';
+/** Which operator a number belongs to, from its first digits. */
+export declare function detectOperator(country: CountryEnum, digits: string): OperatorDetection;
+/**
+ * What the field should say about the number typed so far, by the country's
+ * own mobile rules. Errors that typing more can never fix (a wrong first
+ * digit) show at once; the rest wait until the field is left or Pay pressed.
+ */
+export declare function getPhoneStatus({ country, digits, foreign, touched, focused, submitTried, }: PhoneInputs): PhoneStatus;
+/** "691234567" → "6 91 23 45 67", grouped the way the country writes it. */
+export declare function formatNational(digits: string, country: CountryEnum): string;
+/** "+33612345678" → "+33 6 12 34 56 78": a full number, grouped its country's way. */
+export declare function formatInternational(number: string): string;
+/** A real-looking mobile number of the country, for the empty field. */
+export declare function placeholderOf(country: CountryEnum): string;
+/** The number as providers want it: `+237691234567`. Empty while incomplete. */
+export declare function toE164(digits: string, country: CountryEnum): string;
+/**
+ * Reads what the payer typed or pasted. A national number stays in the
+ * country; a full international one (`+225…`, `00225…`) moves to its country
+ * when the payment can be paid there, and is kept as typed until its country
+ * is known.
+ */
+export declare function readTypedNumber(raw: string, country: CountryEnum, countries: Array<CountryEnum>): TypedNumber;
+/** "6 91 23 45 67" → "6 91 •• •• 67": keeps the first 3 and last 2 digits. */
+export declare function maskNumber(formatted: string): string;
+/** Where the caret goes in `formatted` to sit after its `count`-th digit. */
+export declare function caretAfterDigits(formatted: string, count: number): number;
+/** A USSD code as a link that dials it: `#` must be escaped in a `tel:` URL. */
+export declare function telHref(code: string): string;
+/** `+237691234567` → `+237 6 91 •• •• 67`: the dial code, then the number masked. */
+export declare function maskE164(phone: string): string;

package/dist/checkout-core/models/checkout.phone.utils.js

@@ -0,0 +1,159 @@
+import { AsYouType, getExampleNumber, isValidPhoneNumber, parsePhoneNumberFromString, validatePhoneNumberLength, } from 'libphonenumber-js/mobile';
+import examples from 'libphonenumber-js/mobile/examples';
+import { DIAL_CODES } from "./checkout.constants.js";
+import { CountryEnum } from "./domain.enum.js";
+import { MethodBrandEnum, PhoneErrorEnum } from "./checkout.enum.js";
+/** Cameroon mobile numbers are 9 digits and always start with 6. */
+const CAMEROON_LENGTH = 9;
+const MTN_CAMEROON = /^6(7\d|5[0-4]|8[0-4])$/;
+const ORANGE_CAMEROON = /^6(9\d|5[5-9]|8[5-9]|4\d)$/;
+const CI_OPERATOR_BY_PREFIX = {
+    '07': MethodBrandEnum.ORANGE,
+    '05': MethodBrandEnum.MTN,
+    '01': MethodBrandEnum.MOOV,
+};
+/** `cm` → `CM`, the library's country code. */
+function codeOf(country) {
+    return country.toUpperCase();
+}
+/** Which operator a number belongs to, from its first digits. */
+export function detectOperator(country, digits) {
+    if (country === CountryEnum.CAMEROON) {
+        if (digits.length < 3)
+            return { operator: null, unrecognized: false };
+        const prefix = digits.slice(0, 3);
+        if (MTN_CAMEROON.test(prefix))
+            return { operator: MethodBrandEnum.MTN, unrecognized: false };
+        if (ORANGE_CAMEROON.test(prefix))
+            return { operator: MethodBrandEnum.ORANGE, unrecognized: false };
+        return { operator: null, unrecognized: true };
+    }
+    if (country === CountryEnum.COTE_D_IVOIRE && digits.length >= 2) {
+        return {
+            operator: CI_OPERATOR_BY_PREFIX[digits.slice(0, 2)] ?? null,
+            unrecognized: false,
+        };
+    }
+    return { operator: null, unrecognized: false };
+}
+/**
+ * What the field should say about the number typed so far, by the country's
+ * own mobile rules. Errors that typing more can never fix (a wrong first
+ * digit) show at once; the rest wait until the field is left or Pay pressed.
+ */
+export function getPhoneStatus({ country, digits, foreign, touched, focused, submitTried, }) {
+    const isCameroon = country === CountryEnum.CAMEROON;
+    const { operator, unrecognized } = detectOperator(country, digits);
+    const valid = isValidPhoneNumber(digits, codeOf(country));
+    let error = null;
+    if (isCameroon && digits.length > 0 && !digits.startsWith('6')) {
+        error = PhoneErrorEnum.START;
+    }
+    else if (isCameroon && digits.length === CAMEROON_LENGTH && unrecognized) {
+        error = PhoneErrorEnum.OPERATOR;
+    }
+    else if ((touched && !focused) || submitTried) {
+        if (foreign) {
+            error = PhoneErrorEnum.COUNTRY;
+        }
+        else if (digits.length === 0) {
+            if (submitTried)
+                error = PhoneErrorEnum.EMPTY;
+        }
+        else if (validatePhoneNumberLength(digits, codeOf(country)) === 'TOO_SHORT') {
+            error = PhoneErrorEnum.SHORT;
+        }
+        else if (!valid) {
+            error = PhoneErrorEnum.INVALID;
+        }
+    }
+    return { error, valid: error === null && valid, operator };
+}
+/** "691234567" → "6 91 23 45 67", grouped the way the country writes it. */
+export function formatNational(digits, country) {
+    return new AsYouType(codeOf(country)).input(digits);
+}
+/** "+33612345678" → "+33 6 12 34 56 78": a full number, grouped its country's way. */
+export function formatInternational(number) {
+    return new AsYouType().input(number);
+}
+/** A real-looking mobile number of the country, for the empty field. */
+export function placeholderOf(country) {
+    return getExampleNumber(codeOf(country), examples).formatNational();
+}
+/** The number as providers want it: `+237691234567`. Empty while incomplete. */
+export function toE164(digits, country) {
+    return parsePhoneNumberFromString(digits, codeOf(country))?.number ?? '';
+}
+/** Drops the digits past the longest number the country has. */
+function fit(digits, country) {
+    let kept = digits;
+    while (validatePhoneNumberLength(kept, codeOf(country)) === 'TOO_LONG') {
+        kept = kept.slice(0, -1);
+    }
+    return kept;
+}
+/**
+ * Reads what the payer typed or pasted. A national number stays in the
+ * country; a full international one (`+225…`, `00225…`) moves to its country
+ * when the payment can be paid there, and is kept as typed until its country
+ * is known.
+ */
+export function readTypedNumber(raw, country, countries) {
+    const text = raw.trim();
+    if (text.startsWith('+') || text.startsWith('00')) {
+        const international = `+${text.replace(/^(\+|00)/, '').replace(/\D/g, '')}`;
+        const typer = new AsYouType();
+        typer.input(international);
+        const found = typer.getCountry()?.toLowerCase();
+        if (found && countries.includes(found)) {
+            return {
+                country: found,
+                // A known country comes with its digits.
+                digits: fit(typer.getNumber().nationalNumber, found),
+                pending: null,
+            };
+        }
+        return { country, digits: '', pending: international };
+    }
+    const typed = text.replace(/\D/g, '');
+    // "237691234567": the dial code typed without its plus.
+    const parsed = typed.startsWith(DIAL_CODES[country])
+        ? parsePhoneNumberFromString(typed, codeOf(country))
+        : undefined;
+    const digits = parsed?.isValid() ? parsed.nationalNumber : typed;
+    return { country, digits: fit(digits, country), pending: null };
+}
+/** "6 91 23 45 67" → "6 91 •• •• 67": keeps the first 3 and last 2 digits. */
+export function maskNumber(formatted) {
+    const total = (formatted.match(/\d/g) ?? []).length;
+    let seen = 0;
+    return formatted.replace(/\d/g, (digit) => {
+        seen += 1;
+        return seen <= 3 || seen > total - 2 ? digit : '•';
+    });
+}
+/** Where the caret goes in `formatted` to sit after its `count`-th digit. */
+export function caretAfterDigits(formatted, count) {
+    if (count === 0)
+        return 0;
+    let seen = 0;
+    for (let index = 0; index < formatted.length; index++) {
+        if (/\d/.test(formatted[index]))
+            seen += 1;
+        if (seen === count)
+            return index + 1;
+    }
+    return formatted.length;
+}
+/** A USSD code as a link that dials it: `#` must be escaped in a `tel:` URL. */
+export function telHref(code) {
+    return `tel:${code.replace(/#/g, '%23')}`;
+}
+/** `+237691234567` → `+237 6 91 •• •• 67`: the dial code, then the number masked. */
+export function maskE164(phone) {
+    const parsed = parsePhoneNumberFromString(phone);
+    if (!parsed)
+        return maskNumber(phone);
+    return `+${parsed.countryCallingCode} ${maskNumber(parsed.formatNational())}`;
+}

package/dist/checkout-core/models/checkout.view.utils.d.ts

@@ -0,0 +1,34 @@
+import { CheckoutScreenEnum } from './checkout.enum.js';
+import { CountryEnum } from './domain.enum.js';
+import type { ProviderLogoEnum } from './domain.enum.js';
+import type { CheckoutApp, CheckoutDerived, CheckoutMethod, CheckoutPreviewApp, CheckoutUi, CheckoutView, CountryClues, PhoneStatus, SupportContact } from './checkout.interface.js';
+/** Countries with Mobile Money methods, in the order their first method comes. */
+export declare function countriesOf(methods: Array<CheckoutMethod>): Array<CountryEnum>;
+/** The country whose dial code starts this E.164 number. */
+export declare function countryOfPhone(phone: string): CountryEnum | null;
+/**
+ * The payer's country (docs/v1-plan.md, Checkout): the app's hint, then the
+ * phone's dial code, then the request's IP, then the browser's language
+ * (`fr-CM`). Only countries this payment can be paid in count; with none, the
+ * first country the gateway serves, for a page that has nothing to offer.
+ */
+export declare function pickCountry(view: CheckoutView, clues: CountryClues, countries: Array<CountryEnum>): CountryEnum;
+/**
+ * How the page opens: on the app's preferred method when it can be paid with,
+ * else on its preferred tab, with the list open.
+ */
+export declare function initialUi(view: CheckoutView, clues: CountryClues): CheckoutUi;
+/** Which screen shows: the payment's status first, then what the payer is doing. */
+export declare function screenOf(view: CheckoutView | null | undefined, ui: CheckoutUi): CheckoutScreenEnum;
+/** The brand of a Mobile Money method, which a number's first digits can reveal. */
+export declare function brandOf(method: CheckoutMethod): string;
+/** The tile of a method or an attempt: the generic card for cards, whatever networks they take. */
+export declare function logoOf(of: Pick<CheckoutMethod, 'flow' | 'logos'>): ProviderLogoEnum;
+/** Works out what the screens show from the payment, the page and the number typed. */
+export declare function deriveCheckout(view: CheckoutView, ui: CheckoutUi, phone: PhoneStatus): CheckoutDerived;
+/** Seconds left to approve an attempt started at `startedAt`. */
+export declare function waitLeftOf(startedAt: number, now: number): number;
+/** How payers reach the app's support, when it set any. */
+export declare function supportContactsOf(app: CheckoutApp): Array<SupportContact>;
+/** A pending test payment for the Branding tab's preview, branded as typed. */
+export declare function previewView(app: CheckoutPreviewApp, methods: Array<CheckoutMethod>): CheckoutView;