Référence de l’API

Propriétés de window.mairies

Propriété	Type	Description
mairies.version	number	Version du protocole (1).
mairies.platform	'ios' | 'android'	Plateforme de l’application.
mairies.commands	string[]	Fonctions autorisées sur ce lien, par exemple ['torch', 'camera', 'auth'].
mairies.torch	objet	Méthodes de la torche.
mairies.auth	objet ou absent	Connexion dans le navigateur. Présent seulement si la case « Connexion dans le navigateur » est cochée.
mairies.call(command, params)	fonction	Appel générique.

L’objet et ses sous-objets sont figés : ils ne peuvent être ni modifiés ni remplacés.

Méthodes de la torche

Méthode	Résultat
mairies.torch.isAvailable()	{ available: boolean } : la torche peut-elle être utilisée maintenant ?
mairies.torch.getState()	{ on: boolean }
mairies.torch.on()	{ on: true }
mairies.torch.off()	{ on: false }
mairies.torch.toggle()	{ on: boolean } : le nouvel état

Connexion

Propriété ou méthode	Résultat
mairies.auth.callbackUrl	string : URL de rappel de l’application, de la forme <identifiant>.webauth://callback.
mairies.auth.open(url)	{ url: string } : l’URL de rappel complète, avec les paramètres ajoutés par votre page de connexion.

La caméra n’a pas de méthode : elle passe par navigator.mediaDevices.getUserMedia. Voir Caméra.

Événement mairies:ready

L’événement mairies:ready est émis sur window juste après l’installation de window.mairies. Il ne porte aucune donnée.

Le script de l’application est injecté au début du chargement de chaque page, avant vos scripts : dans la plupart des cas, window.mairies existe déjà quand votre code s’exécute, et l’événement a déjà eu lieu. Testez donc toujours la présence de l’objet avant d’écouter l’événement :

if (window.mairies) init(window.mairies);
else window.addEventListener('mairies:ready', () => init(window.mairies), { once: true });

Hors de l’application, l’événement n’est jamais émis.

Appel générique

await mairies.call('torch.on', {});

Équivalent à mairies.torch.on(). Les méthodes nommées ne sont que des raccourcis vers call.

Commande	Paramètres	Équivalent
torch.isAvailable	aucun	mairies.torch.isAvailable()
torch.getState	aucun	mairies.torch.getState()
torch.on	aucun	mairies.torch.on()
torch.off	aucun	mairies.torch.off()
torch.toggle	aucun	mairies.torch.toggle()
auth.open	{ url: string }	mairies.auth.open(url)

Règles sur les paramètres :

• un objet (pas un tableau), ou rien ;
• sérialisable en JSON ;
• 16 Ko au maximum une fois sérialisé.

Sinon, la promesse est rejetée avec INVALID_PARAMS. Une commande inconnue de cette version de l’application est rejetée avec UNKNOWN_COMMAND.

Codes d’erreur

En cas d’échec, la promesse est rejetée avec une Error dont name vaut 'MairiesError' et qui porte une propriété code. Le message est purement informatif : sa langue et son texte varient selon la plateforme et la version. Basez votre logique uniquement sur code.

Code	Cause
NOT_ALLOWED	Fonction non cochée, origine différente de celle du lien, appel depuis une iframe, ou adresse refusée par auth.open.
UNKNOWN_COMMAND	Commande inexistante dans cette version de l’application.
INVALID_PARAMS	Paramètres invalides ou trop volumineux (16 Ko maximum).
UNAVAILABLE	Fonction indisponible sur l’appareil : pas de torche, caméra occupée, navigateur impossible à ouvrir…
RATE_LIMITED	Changements d’état trop rapprochés (500 ms minimum pour la torche).
CANCELLED	L’utilisateur a fermé la feuille de connexion, ou quitté l’écran du lien pendant la connexion (auth.open).
BUSY	Une connexion est déjà en cours (auth.open).
INTERNAL	Erreur inattendue de l’application.

try {
  await window.mairies.torch.on();
} catch (error) {
  switch (error.code) {
    case 'RATE_LIMITED':
      break; // réessayer plus tard
    case 'UNAVAILABLE':
      showMessage('La lampe n’est pas disponible pour le moment.');
      break;
    default:
      console.warn(error.code, error.message);
  }
}

Déclaration TypeScript

À copier dans votre projet, par exemple dans un fichier mairies.d.ts :

type MairiesErrorCode =
  | 'CANCELLED'
  | 'BUSY'
  | 'NOT_ALLOWED'
  | 'UNKNOWN_COMMAND'
  | 'INVALID_PARAMS'
  | 'UNAVAILABLE'
  | 'RATE_LIMITED'
  | 'INTERNAL';

interface MairiesError extends Error {
  name: 'MairiesError';
  code: MairiesErrorCode;
}

interface MairiesTorch {
  isAvailable(): Promise<{ available: boolean }>;
  on(): Promise<{ on: boolean }>;
  off(): Promise<{ on: boolean }>;
  toggle(): Promise<{ on: boolean }>;
  getState(): Promise<{ on: boolean }>;
}

interface MairiesAuth {
  readonly callbackUrl: string;
  open(url: string): Promise<{ url: string }>;
}

interface Mairies {
  readonly version: 1;
  readonly platform: 'ios' | 'android';
  readonly commands: ReadonlyArray<'torch' | 'camera' | 'auth' | string>;
  call<T = unknown>(command: string, params?: Record<string, unknown>): Promise<T>;
  readonly torch: MairiesTorch;
  readonly auth?: MairiesAuth; // présent seulement si « Connexion dans le navigateur » est cochée
}

interface Window {
  readonly mairies?: Mairies;
}

interface WindowEventMap {
  'mairies:ready': Event;
}

Dans un module (fichier qui contient un import ou un export), placez les deux dernières interfaces dans un bloc declare global { … }.

Pour typer une erreur interceptée :

function isMairiesError(error: unknown): error is MairiesError {
  return error instanceof Error && error.name === 'MairiesError';
}

Versions du protocole

Version	Contenu
1	Version actuelle : torche, caméra, connexion dans le navigateur.

mairies.version donne la version du protocole prise en charge par l’application installée. Les nouvelles fonctions s’ajoutent au fil des mises à jour de l’application ; un utilisateur qui n’a pas mis à jour son application peut donc ne pas les avoir. Pour savoir si une fonction est utilisable, fiez-vous à mairies.commands plutôt qu’à la version, et traitez UNKNOWN_COMMAND comme une fonction absente.