@pi-spi/app 0.0.0-stage → 1.2.0

package/src/modules/compte/presentation/pages/solde_widget_with_qr.tsx

@@ -0,0 +1,299 @@
+import { MaterialIcons } from '@expo/vector-icons';
+import { useState } from 'react';
+import { ActivityIndicator, Platform, Pressable, Share, StyleSheet, Text, View } from 'react-native';
+
+import { useBloc, useBlocBuilder, useBlocListener, useCreateBloc } from '../../../../core/bloc_react';
+import { Di } from '../../../../core/di';
+import { AppRouter, useAppRouter } from '../../../../core/router';
+import { Themer, useTheme } from '../../../../core/theme';
+import { useAppLocalizations } from '../../../../l10n/localizations';
+import { Card } from '../../../../shared/material/card';
+import { maskCompte } from '../../../../shared/utils/compte_mask';
+import { AmountWidget } from '../../../../shared/widgets/amount_widget';
+import { ClipboardWidget } from '../../../../shared/widgets/clipboard_widget';
+import { CustomSnackBar } from '../../../../shared/widgets/custom_snack_bar';
+import { QrImageWidget } from '../../../../shared/widgets/qr_image/qr_image_widget';
+import type { Alias } from '../../../alias/domain/models/alias';
+import { AliasBloc } from '../../../alias/presentation/bloc/alias_bloc';
+import type { AliasExistState } from '../../../alias/presentation/bloc/alias_state';
+import { ConfigBloc } from '../../../config/adapters/ui/bloc/config_bloc';
+import { ConfigChangeEvent } from '../../../config/adapters/ui/bloc/config_event';
+import { ConfigKey } from '../../../config/domain/models/config_keys';
+import { QrcodeAliasBloc } from '../../../qrcode/presentation/bloc/qrcode_alias/qrcode_alias_bloc';
+import { QrcodeAliasEncodeEvent } from '../../../qrcode/presentation/bloc/qrcode_alias/qrcode_alias_event';
+import {
+  QrcodeAliasEncodeErrorState,
+  QrcodeAliasEncodeSuccessState,
+} from '../../../qrcode/presentation/bloc/qrcode_alias/qrcode_alias_state';
+import { CompteSoldeBloc } from '../bloc/solde/solde_bloc';
+import { GetSoldeCompteEvent } from '../bloc/solde/solde_event';
+import { CompteSoldeDisplayState, CompteSoldeStateInitial, type CompteSoldeState } from '../bloc/solde/solde_state';
+import { SkeletonWidget } from '../../../../shared/widgets/skeleton_widget';
+import { TransactionSendBloc } from '../../../transactions/presentation/bloc/transaction_send/transaction_send_bloc';
+import { TransactionSendUpdateStateEvent } from '../../../transactions/presentation/bloc/transaction_send/transaction_send_event';
+
+/**
+ * Carte du compte actif sur l'accueil : libellé et numéro masqué, solde
+ * (masquable), QR code de l'alias (tap = scanner) et alias à copier ou
+ * partager.
+ */
+export function SoldeWidgetWithQr() {
+  const aliasBloc = useBloc(AliasBloc);
+  const configBloc = useBloc(ConfigBloc);
+  const [alias] = useState(() => (aliasBloc.state as AliasExistState).alias);
+  const compteSoldeBloc = useCreateBloc(() => {
+    const bloc = new CompteSoldeBloc(Di.getCompteInputPort(), Di.activeCompte);
+    bloc.add(new GetSoldeCompteEvent());
+    return bloc;
+  });
+  const soldeState = useBlocBuilder(compteSoldeBloc);
+  useBlocBuilder(configBloc);
+
+  // Le solde sert à vérifier le montant des transferts
+  const transactionSendBloc = useBloc(TransactionSendBloc);
+  useBlocListener(compteSoldeBloc, (state) => {
+    if (state instanceof CompteSoldeDisplayState) {
+      transactionSendBloc.add(new TransactionSendUpdateStateEvent({ solde: state.solde ?? 0 }));
+    }
+  });
+
+  return <CardCompte alias={alias} soldeState={soldeState} compteSoldeBloc={compteSoldeBloc} />;
+}
+
+// ── Card principale ──────────────────────────────────────────────────────────
+
+function CardCompte({
+  alias,
+  soldeState,
+  compteSoldeBloc,
+}: {
+  alias: Alias;
+  soldeState: CompteSoldeState;
+  compteSoldeBloc: CompteSoldeBloc;
+}) {
+  const theme = useTheme();
+  return (
+    <Card style={[styles.card, { backgroundColor: theme.colorScheme.surface }]}>
+      <View style={styles.cardContent}>
+        {/* Ligne 1 : infos compte + QR */}
+        <View style={styles.row}>
+          <View style={styles.expanded}>
+            {/* Libellé + numéro masqué du compte */}
+            <CompteLabelRow compte={Di.activeCompte} />
+            <View style={styles.gap10} />
+            {/* Solde */}
+            <SoldeRow soldeState={soldeState} compteSoldeBloc={compteSoldeBloc} />
+          </View>
+          {/* QR code */}
+          <QrCodeCard />
+        </View>
+        <AliasRow alias={alias} />
+      </View>
+    </Card>
+  );
+}
+
+// ── Libellé + numéro masqué du compte ───────────────────────────────────────
+
+function CompteLabelRow({ compte }: { compte: string }) {
+  const theme = useTheme();
+  const comptes = Di.config.user.comptes;
+  const libelle = (comptes.find((c) => c.numero === compte) ?? comptes[0]).libelle;
+  return (
+    <View>
+      <Text style={[theme.textTheme.displaySmall, styles.libelle]}>{libelle.toUpperCase()}</Text>
+      <View style={styles.gap2} />
+      <View style={styles.inlineRow}>
+        <Text style={[theme.textTheme.bodyMedium, styles.bold]}>{maskCompte(compte)}</Text>
+        <Pressable
+          accessibilityRole="button"
+          hitSlop={10}
+          style={styles.copyCompte}
+          onPress={() => void ClipboardWidget.setData(compte)}
+        >
+          <MaterialIcons name="content-copy" size={13} color={Themer.neural04Color} />
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+// ── Alias + bouton copier ────────────────────────────────────────────────────
+
+function AliasRow({ alias }: { alias: Alias }) {
+  const theme = useTheme();
+  const traductions = useAppLocalizations();
+
+  // Comme share_plus : feuille de partage système avec le texte de l'alias.
+  const share = async () => {
+    await Share.share({ message: alias.getCle() });
+  };
+
+  return (
+    <View style={styles.inlineRow}>
+      <Text numberOfLines={1} style={[theme.textTheme.displayLarge, { color: theme.primaryColor }]}>
+        {traductions.qrcodePageBtnMonAlias}
+      </Text>
+      <View style={styles.gap20w} />
+      <Pressable
+        accessibilityRole="button"
+        hitSlop={6}
+        style={styles.iconBtn}
+        onPress={() => void ClipboardWidget.setData(alias.getShid())}
+      >
+        <MaterialIcons name="content-copy" size={16} color={theme.primaryColor} />
+      </Pressable>
+      <Pressable accessibilityRole="button" hitSlop={6} style={styles.iconBtn} onPress={() => void share()}>
+        <MaterialIcons name={Platform.OS === 'ios' ? 'ios-share' : 'share'} size={16} color={theme.primaryColor} />
+      </Pressable>
+    </View>
+  );
+}
+
+// ── Solde + œil ─────────────────────────────────────────────────────────────
+
+function SoldeRow({ soldeState, compteSoldeBloc }: { soldeState: CompteSoldeState; compteSoldeBloc: CompteSoldeBloc }) {
+  const theme = useTheme();
+  const traductions = useAppLocalizations();
+  const configBloc = useBloc(ConfigBloc);
+  const displayEye = configBloc.state.configParams.params[ConfigKey.hideEye] !== '1';
+  const solde = soldeState.solde ?? 0;
+  const fontSize = solde < 100000000 ? 24 : solde < 1000000000 ? 20 : 18;
+
+  return (
+    <View>
+      <Text style={theme.textTheme.displaySmall}>{traductions.homeSolde}</Text>
+      <View style={styles.inlineRow}>
+        {soldeState instanceof CompteSoldeStateInitial && <SkeletonWidget height={25} width={150} />}
+        {soldeState instanceof CompteSoldeDisplayState && (
+          <>
+            <AmountWidget montant={soldeState.solde} numberOfLines={1} style={{ ...theme.textTheme.headlineLarge, fontSize }} />
+            {displayEye && <EyeButton compteSoldeBloc={compteSoldeBloc} />}
+          </>
+        )}
+      </View>
+    </View>
+  );
+}
+
+// ── Bouton œil ───────────────────────────────────────────────────────────────
+
+function EyeButton({ compteSoldeBloc }: { compteSoldeBloc: CompteSoldeBloc }) {
+  const configBloc = useBloc(ConfigBloc);
+  return (
+    <Pressable
+      accessibilityRole="button"
+      style={styles.eye}
+      onPress={() => {
+        const displayAmount = configBloc.state.configParams.params[ConfigKey.displayAmount] === '1';
+        configBloc.add(new ConfigChangeEvent(ConfigKey.displayAmount, displayAmount ? '0' : '1'));
+        if (!displayAmount) {
+          compteSoldeBloc.add(new GetSoldeCompteEvent());
+        }
+      }}
+    >
+      <MaterialIcons name="visibility" size={18} color={Themer.neural04Color} />
+    </Pressable>
+  );
+}
+
+// ── QR code miniature ────────────────────────────────────────────────────────
+
+function QrCodeCard() {
+  const theme = useTheme();
+  const router = useAppRouter();
+  const traductions = useAppLocalizations();
+  return (
+    <View style={styles.qrColumn}>
+      <Pressable
+        accessibilityRole="button"
+        style={styles.qrBox}
+        onPress={() => void AppRouter.push(router, AppRouter.qrcodeScan, { params: 'send_now' })}
+      >
+        <QrCodeAliasWidget />
+      </Pressable>
+      <View style={styles.gap8} />
+      <View style={styles.inlineRow}>
+        <MaterialIcons name="photo-camera" size={14} color={Themer.neural04Color} />
+        <View style={styles.gap5w} />
+        <Text style={[theme.textTheme.displaySmall, { color: Themer.neural04Color }]}>{traductions.qrcodePageBtnScan}</Text>
+      </View>
+    </View>
+  );
+}
+
+// ── Widget QR code (gère son propre bloc) ───────────────────────────────────
+
+export function QrCodeAliasWidget() {
+  const traductions = useAppLocalizations();
+  const theme = useTheme();
+  const aliasBloc = useBloc(AliasBloc);
+  const [qrCode, setQrCode] = useState<string | null>(null);
+  const qrcodeAliasBloc = useCreateBloc(() => {
+    const bloc = new QrcodeAliasBloc(Di.getQrcodeInputPort());
+    bloc.add(new QrcodeAliasEncodeEvent((aliasBloc.state as AliasExistState).alias));
+    return bloc;
+  });
+
+  // L'encodage est synchrone côté service : le résultat peut arriver avant
+  // l'abonnement du listener, d'où la lecture de l'état courant.
+  const state = useBlocBuilder(qrcodeAliasBloc);
+  const current = qrCode ?? (state instanceof QrcodeAliasEncodeSuccessState ? state.qrCode : null);
+
+  useBlocListener(
+    qrcodeAliasBloc,
+    (s) => {
+      if (s instanceof QrcodeAliasEncodeSuccessState) {
+        setQrCode(s.qrCode);
+      } else if (s instanceof QrcodeAliasEncodeErrorState) {
+        console.warn('QrcodeAliasEncodeErrorState', s.error);
+        CustomSnackBar.show(traductions.qrcodeEncodeErrorMsg, { durationMs: 5000, bgColor: Themer.systemErrorColor });
+      }
+    },
+    (_previous, s) => s instanceof QrcodeAliasEncodeSuccessState || s instanceof QrcodeAliasEncodeErrorState,
+  );
+
+  if (current == null) {
+    return (
+      <View style={styles.qrLoading}>
+        <ActivityIndicator size="small" color={theme.colorScheme.primary} />
+      </View>
+    );
+  }
+  const dark = theme.brightness === 'dark';
+  return (
+    <Card style={styles.qrCard}>
+      <QrImageWidget
+        payload={current}
+        qrImageOptions={{
+          margin: 0,
+          icon: { size: 20 },
+          data: dark ? { color: Themer.whiteColor } : undefined,
+          eye: dark ? { color: Themer.whiteColor } : undefined,
+        }}
+      />
+    </Card>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: { borderRadius: 16 },
+  cardContent: { paddingLeft: 10, paddingRight: 10, paddingTop: 16, paddingBottom: 10 },
+  row: { flexDirection: 'row', alignItems: 'flex-start' },
+  inlineRow: { flexDirection: 'row', alignItems: 'center' },
+  expanded: { flex: 1 },
+  libelle: { color: Themer.neural04Color, letterSpacing: 0.4 },
+  bold: { fontWeight: '600' },
+  copyCompte: { width: 22, height: 22, alignItems: 'center', justifyContent: 'center', marginLeft: 2 },
+  iconBtn: { width: 30, height: 30, alignItems: 'center', justifyContent: 'center' },
+  eye: { width: 40, height: 40, alignItems: 'center', justifyContent: 'center' },
+  qrColumn: { alignItems: 'center' },
+  qrBox: { width: 90, height: 90 },
+  qrCard: { margin: 0, borderRadius: 10, flex: 1 },
+  qrLoading: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+  gap2: { height: 2 },
+  gap8: { height: 8 },
+  gap10: { height: 10 },
+  gap5w: { width: 5 },
+  gap20w: { width: 20 },
+});

package/src/modules/config/adapters/infra/config_output_prefs.ts

@@ -0,0 +1,22 @@
+import type { SharedPreferences } from '../../../../core/storage';
+import { ConfigParams } from '../../domain/models/config_params';
+import type { ConfigOutputPort } from '../../ports/output/config_output_port';
+
+export class ConfigOutputPrefs implements ConfigOutputPort {
+  /**
+   * [sharedPreferences] est utilisé pour stocker et
+   * recuperer les paramètres de configuration
+   */
+  constructor(readonly sharedPreferences: SharedPreferences) {}
+
+  recuperer(keys: string[]): ConfigParams {
+    // récupérer les configurations et les mettre dans un map
+    const params: Record<string, string | null> = {};
+    for (const paramkey of keys) params[paramkey] = this.sharedPreferences.getString(paramkey);
+    return new ConfigParams(params);
+  }
+
+  async modifier(key: string, value: string): Promise<void> {
+    await this.sharedPreferences.setString(key, value);
+  }
+}

package/src/modules/config/adapters/ui/bloc/config_bloc.ts

@@ -0,0 +1,44 @@
+import { Bloc, type Emitter } from '../../../../../core/bloc';
+import { Logger } from '../../../../../core/logger';
+import type { ConfigKey } from '../../../domain/models/config_keys';
+import { ConfigParams } from '../../../domain/models/config_params';
+import type { ConfigInputPort } from '../../../ports/input/config_input_port';
+import { ConfigChangeEvent, ConfigLoadedEvent, type ConfigEvent } from './config_event';
+import { ConfigLoadedState, type ConfigState } from './config_state';
+
+export class ConfigBloc extends Bloc<ConfigEvent, ConfigState> {
+  readonly logger = new Logger();
+
+  /** ConfigLoadedState est l'état initial, déjà chargé (lecture synchrone des préférences) */
+  constructor(readonly configInputPort: ConfigInputPort) {
+    super(new ConfigLoadedState(configInputPort.recuperer(), null));
+    // Après modification d'une configuration
+    this.on(ConfigChangeEvent, (event, emit) => this.onConfigChangeEvent(event, emit));
+    // Charger la liste des config
+    this.on(ConfigLoadedEvent, (_event, emit) => this.onConfigLoadedEvent(emit));
+  }
+
+  private onConfigLoadedEvent(emit: Emitter<ConfigState>): void {
+    const configParams = this.configInputPort.recuperer();
+    emit(new ConfigLoadedState(configParams, null));
+  }
+
+  private async onConfigChangeEvent(event: ConfigChangeEvent, emit: Emitter<ConfigState>): Promise<void> {
+    // Appeler le service pour charger la configuration
+    await this.configInputPort.modifier(event.configKey, event.configValue);
+    this.logger.i(`Change config ${event.configKey} to ${event.configValue}`);
+
+    // Mettre à jour les paramètres avec la nouvelle valeur (nouvel objet,
+    // pour que les composants abonnés voient le changement)
+    const configParams = new ConfigParams({
+      ...this.state.configParams.params,
+      [event.configKey]: event.configValue,
+    });
+    emit(new ConfigLoadedState(configParams, event.configKey));
+  }
+
+  /** Permet d'obtenir la valeur d'un paramètre après chargement de la config */
+  getParamValue(key: ConfigKey): string | null {
+    return this.state.configParams.params[key] ?? null;
+  }
+}

package/src/modules/config/adapters/ui/bloc/config_event.ts

@@ -0,0 +1,31 @@
+import type { ConfigKey } from '../../../domain/models/config_keys';
+
+export abstract class ConfigEvent {}
+
+/** Au chargement de la configuration / chargement de l'application */
+export class ConfigAskedEvent extends ConfigEvent {}
+
+/** Pour demander le changement de configuration d'un parametre */
+export class ConfigChangeEvent extends ConfigEvent {
+  constructor(
+    /** Clé du Parametre de configuration à changer */
+    readonly configKey: ConfigKey,
+    /** Valeur du Parametre de configuration à changer */
+    readonly configValue: string,
+  ) {
+    super();
+  }
+}
+
+/** Apres chargement de la configuration */
+export class ConfigLoadedEvent extends ConfigEvent {}
+
+/** Lorsqu'une erreur survient lors du chargement des configurations */
+export class ConfigErrorEvent extends ConfigEvent {
+  constructor(
+    /** Erreur survenue */
+    readonly error: Error,
+  ) {
+    super();
+  }
+}

package/src/modules/config/adapters/ui/bloc/config_state.ts

@@ -0,0 +1,22 @@
+import type { ConfigKey } from '../../../domain/models/config_keys';
+import type { ConfigParams } from '../../../domain/models/config_params';
+
+export abstract class ConfigState {
+  constructor(
+    /** paramètre de configuration */
+    public configParams: ConfigParams,
+  ) {}
+}
+
+/**
+ * La configuration a chargé.
+ * L'état de l'application après chargement de la configuration
+ */
+export class ConfigLoadedState extends ConfigState {
+  constructor(
+    configParams: ConfigParams,
+    readonly updatedKey: ConfigKey | null,
+  ) {
+    super(configParams);
+  }
+}

package/src/modules/config/domain/models/config_keys.ts

@@ -0,0 +1,42 @@
+/** Définit les paramètres de configurations de l'application. La valeur de chaque membre est sa codification. */
+export enum ConfigKey {
+  /** keyword to say all config params */
+  all = 'ALL',
+
+  /** l'utilisateur a passé l'introduction */
+  introductionPassed = 'INTRODUCTION_PASSED',
+
+  /** theme de l'utilisateur */
+  preferedTheme = 'PREFERED_THEME',
+
+  /** Permission notification */
+  permissionNotification = 'PERMISSION_NOTIFICATION',
+  /** Permission contact autorisée ou pas */
+  permissionContact = 'PERMISSION_CONTACT',
+  /** Permission biométrie déjà demandée ou pas */
+  permissionBiometryAsked = 'PERMISSION_BIOMETRY_ASKED',
+
+  /** Permet de controller l'affichage du montant */
+  displayAmount = 'DISPLAY_AMOUNT',
+  /** Permet d'afficher l'oeil et d'ecouter sur le basculement du telephone */
+  hideEye = 'HIDE_EYE',
+
+  /** Permet d'afficher le qr code par défaut */
+  showQRcode = 'SHOW_QRCODE',
+
+  /** Notifications dans l'application */
+  notificationStatus = 'NOTIFICATION_STATUS',
+  notificationStyle = 'NOTIFICATION_STYLE',
+  notificationAlertSound = 'NOTIFICATION_ALERT_SOUND',
+  notificationAlertVibration = 'NOTIFICATION_ALERT_VIBRATION',
+  notificationAlertTransfer = 'NOTIFICATION_ALERT_TRANSFER',
+
+  /** Nombre d'élements affichés sur la liste des dernières transactions */
+  transactionsRecentNbItems = 'TRANSACTIONS_RECENTS_NB',
+
+  /** L'utilisateur a passé l'introduction du module économie */
+  economieIntroductionPassed = 'ECONOMIE_INTRODUCTION_PASSED',
+}
+
+/** Toutes les clés, dans l'ordre de déclaration (≈ `ConfigKey.values`). */
+export const configKeyValues: readonly ConfigKey[] = Object.values(ConfigKey);

package/src/modules/config/domain/models/config_params.ts

@@ -0,0 +1,4 @@
+/** Paramètres de configuration de l'application */
+export class ConfigParams {
+  constructor(public params: Record<string, string | null>) {}
+}

package/src/modules/config/domain/services/config_service.ts

@@ -0,0 +1,22 @@
+import type { ConfigInputPort } from '../../ports/input/config_input_port';
+import type { ConfigOutputPort } from '../../ports/output/config_output_port';
+import { configKeyValues } from '../models/config_keys';
+import type { ConfigParams } from '../models/config_params';
+
+/** Service contenant la logique de gestion des configurations */
+export class ConfigService implements ConfigInputPort {
+  /**
+   * Le service a besoin de [configOutputPort] pour stocker
+   * et recuperer les paramètres de configuration
+   */
+  constructor(readonly configOutputPort: ConfigOutputPort) {}
+
+  recuperer(): ConfigParams {
+    // Récuperer toute la config et Appeler le systeme de stockage
+    return this.configOutputPort.recuperer([...configKeyValues]);
+  }
+
+  async modifier(key: string, value: string): Promise<void> {
+    await this.configOutputPort.modifier(key, value);
+  }
+}

package/src/modules/config/ports/input/config_input_port.ts

@@ -0,0 +1,12 @@
+import type { ConfigParams } from '../../domain/models/config_params';
+
+/**
+ * Porte d'entrée pour pouvoir gerer la configuration de l'app
+ */
+export interface ConfigInputPort {
+  /** Récupère la configuration de l'application */
+  recuperer(): ConfigParams;
+
+  /** Mets à jour la configuration de [key] avec la valeur [value] */
+  modifier(key: string, value: string): Promise<void>;
+}

package/src/modules/config/ports/output/config_output_port.ts

@@ -0,0 +1,12 @@
+import type { ConfigParams } from '../../domain/models/config_params';
+
+/**
+ * Porte de sortie pour pouvoir stocker la configuration de l'app
+ */
+export interface ConfigOutputPort {
+  /** Récupère la configuration générale de l'application */
+  recuperer(keys: string[]): ConfigParams;
+
+  /** Mets à jour la configuration de [key] avec la valeur [value] */
+  modifier(key: string, value: string): Promise<void>;
+}

package/src/modules/contacts/domain/contact_create_error.ts

@@ -0,0 +1,4 @@
+export enum ContactCreateError {
+  unknow = 'unknow',
+  notFound = 'notFound',
+}

package/src/modules/contacts/domain/contact_list.ts

@@ -0,0 +1,9 @@
+import type { PhoneContact } from './phone_contact';
+
+/** Groupe de contacts sous une même lettre (en-tête de section). */
+export class ContactList {
+  constructor(
+    readonly header: string,
+    readonly contacts: PhoneContact[],
+  ) {}
+}

package/src/modules/contacts/domain/contact_pi.ts

@@ -0,0 +1,32 @@
+import { Logger } from '../../../core/logger';
+import { getAliasValue, type PhoneContact } from './phone_contact';
+
+export class ContactPI {
+  static readonly logger = new Logger();
+
+  name: string;
+  phoneNumber: string;
+  alias?: string | null;
+
+  constructor(params: { name: string; alias?: string | null; phoneNumber?: string }) {
+    this.name = params.name;
+    this.alias = params.alias;
+    this.phoneNumber = params.phoneNumber ?? '';
+  }
+
+  /** Récupère un contactPI à partir d'un contact */
+  static fromContact(contact: PhoneContact): ContactPI {
+    return new ContactPI({
+      name: contact.displayName,
+      phoneNumber: contact.phones[0]?.number ?? '',
+      alias: ContactPI.getAlias(contact),
+    });
+  }
+
+  /** Récupère la valeur de l'alias */
+  static getAlias(contact: PhoneContact): string | null {
+    const alias = getAliasValue(contact);
+    if (alias == null) ContactPI.logger.i(`No alias found for contact ${contact.displayName}`);
+    return alias;
+  }
+}

package/src/modules/contacts/domain/phone_contact.ts

@@ -0,0 +1,58 @@
+import { AliasPI } from '../../../shared/models/alias_pi';
+
+/**
+ * Numéro d'un contact du téléphone (≈ `Phone` de flutter_contacts). Les
+ * alias PI-SPI sont enregistrés comme des numéros à l'étiquette
+ * personnalisée `@PI` ({@link AliasPI.label}).
+ */
+export type PhoneContactPhone = {
+  /** Identifiant du numéro dans le carnet (absent pour un numéro pas encore enregistré). */
+  id?: string;
+  number: string;
+  label: string;
+};
+
+/**
+ * Contact du carnet d'adresses du téléphone (≈ `Contact` de
+ * flutter_contacts), indépendant de la bibliothèque native.
+ */
+export type PhoneContact = {
+  id: string;
+  /**
+   * Identifiant du contact dans le carnet, quand [id] a été rendu unique
+   * pour l'affichage (une entrée par numéro, voir `groupContactPhones`).
+   */
+  sourceId?: string;
+  displayName: string;
+  firstName: string;
+  lastName: string;
+  /** URI locale de la photo (miniature) du contact. */
+  photo?: string | null;
+  phones: PhoneContactPhone[];
+};
+
+/** Le numéro est-il un alias PI-SPI (étiquette personnalisée `@PI`) ? */
+export function isAliasPhone(phone: PhoneContactPhone): boolean {
+  return phone.label === AliasPI.label;
+}
+
+/** Numéro sans espaces ni tirets (≈ `Phone.normalizedNumber`). */
+export function normalizedNumber(phone: PhoneContactPhone): string {
+  return phone.number.trim().replace(/[\s-]/g, '');
+}
+
+/**
+ * Valeur de l'alias PI-SPI du contact, s'il en a un. Boucle simple : appelée
+ * pour chaque contact du téléphone (index, recherche, affichage).
+ */
+export function getAliasValue(contact: PhoneContact): string | null {
+  for (const phone of contact.phones) {
+    if (isAliasPhone(phone) && phone.number.length > 0) return phone.number;
+  }
+  return null;
+}
+
+/** Identifiant du contact dans le carnet d'adresses du téléphone. */
+export function contactIdOf(contact: PhoneContact): string {
+  return contact.sourceId ?? contact.id;
+}