@egen-civitas/esm-platform 1.1.0 → 1.2.0

package/dist/testing/mock-host.d.ts

@@ -0,0 +1,49 @@
+import type { CapabilityName } from '@egen-civitas/esm-globals';
+import type { HostBridge } from '../bridge/protocol.js';
+import type { PlatformEnvironment } from '../types.js';
+export interface MockHostOptions {
+    /** Version de protocole annoncée par le Host dans le `hello`. @default 1 */
+    protocol?: number;
+    /** Valeur du champ `v` des réponses (permet de simuler un Host qui répond dans une version inconnue). @default protocol */
+    replyVersion?: number;
+    /** Version de l'application hôte. @default '1.0.0-test' */
+    host?: string;
+    /** Plateforme annoncée. @default 'android' */
+    platform?: PlatformEnvironment;
+    /** Capacités annoncées dans le `hello`. @default {} */
+    capabilities?: Partial<Record<CapabilityName, {
+        v: number;
+    }>>;
+    /** Remplace entièrement le résultat du `hello` (cas limites : réponse invalide…). */
+    helloResult?: unknown;
+    /** Méthodes servies, clé `namespace.méthode`. Retourner une valeur, ou lever (`code` de l'erreur repris). */
+    handlers?: Record<string, (args: unknown) => unknown>;
+    /** `false` : le Host ne répond jamais (tests de timeout). @default true */
+    respond?: boolean;
+    /** Latence de réponse en ms (0 = prochaine micro-tâche). @default 0 */
+    latencyMs?: number;
+}
+export interface MockHost {
+    /** Le pont à injecter : `window.egenHostBridge`. */
+    readonly bridge: HostBridge;
+    /** Requêtes décodées reçues par le Host, dans l'ordre. */
+    readonly sent: Array<Record<string, unknown>>;
+    /** Nombre d'appels à `subscribe`. */
+    readonly subscribeCount: number;
+    /** Pose `window.egenHostBridge`. */
+    install(): void;
+    /** Retire `window.egenHostBridge`. */
+    uninstall(): void;
+    /** host → web : émet un événement du protocole. */
+    emit(event: string, data?: unknown): void;
+    /** host → web : pousse une chaîne arbitraire (messages malformés, orphelins…). */
+    inject(raw: string): void;
+}
+/**
+ * Simule un Host natif (`window.egenHostBridge`) pour les tests : handshake automatique, méthodes programmables,
+ * latence, silence, version de protocole incompatible. Aucun code natif : c'est le CONTRAT du protocole v1 (annexe 1
+ * du document de développement) rejoué côté test.
+ *
+ * @category Platform
+ */
+export declare function createMockHost(options?: MockHostOptions): MockHost;

package/dist/testing/mock-host.js

@@ -0,0 +1,86 @@
+/**
+ * Simule un Host natif (`window.egenHostBridge`) pour les tests : handshake automatique, méthodes programmables,
+ * latence, silence, version de protocole incompatible. Aucun code natif : c'est le CONTRAT du protocole v1 (annexe 1
+ * du document de développement) rejoué côté test.
+ *
+ * @category Platform
+ */
+export function createMockHost(options = {}) {
+    const { protocol = 1, replyVersion = protocol, host = '1.0.0-test', platform = 'android', capabilities = {}, handlers = {}, respond = true, latencyMs = 0, } = options;
+    let callback = null;
+    let subscribeCount = 0;
+    const sent = [];
+    const deliver = (message) => {
+        const json = JSON.stringify({ p: 'egen-host', v: replyVersion, ...message });
+        const push = () => callback?.(json);
+        if (latencyMs > 0) {
+            setTimeout(push, latencyMs);
+        }
+        else {
+            void Promise.resolve().then(push);
+        }
+    };
+    const reply = async (request) => {
+        const id = request.id;
+        try {
+            if (request.ns === 'host' && request.m === 'hello') {
+                deliver({
+                    id,
+                    ok: true,
+                    r: 'helloResult' in options ? options.helloResult : { protocol, host, platform, capabilities },
+                });
+                return;
+            }
+            const handler = handlers[`${String(request.ns)}.${String(request.m)}`];
+            if (!handler) {
+                deliver({
+                    id,
+                    ok: false,
+                    e: { code: 'UNAVAILABLE', message: `Pas de handler pour ${String(request.ns)}.${String(request.m)}` },
+                });
+                return;
+            }
+            deliver({ id, ok: true, r: await handler(request.a) });
+        }
+        catch (error) {
+            const code = error?.code;
+            deliver({
+                id,
+                ok: false,
+                e: { code: code ?? 'HOST_ERROR', message: error instanceof Error ? error.message : String(error) },
+            });
+        }
+    };
+    const bridge = {
+        send(json) {
+            const request = JSON.parse(json);
+            sent.push(request);
+            if (respond) {
+                void reply(request);
+            }
+        },
+        subscribe(cb) {
+            callback = cb;
+            subscribeCount++;
+        },
+    };
+    return {
+        bridge,
+        sent,
+        get subscribeCount() {
+            return subscribeCount;
+        },
+        install() {
+            window.egenHostBridge = bridge;
+        },
+        uninstall() {
+            delete window.egenHostBridge;
+        },
+        emit(event, data) {
+            callback?.(JSON.stringify({ p: 'egen-host', v: replyVersion, ev: event, ...(data === undefined ? {} : { d: data }) }));
+        },
+        inject(raw) {
+            callback?.(raw);
+        },
+    };
+}

package/dist/types.d.ts

@@ -66,21 +66,43 @@ export interface BiometricCapability {
     authenticate(reason: string): Promise<boolean>;
 }
 /**
- * Point d'accès unique des apps aux capacités de plateforme.
- * Une capacité indisponible (`has()` faux) existe toujours comme objet : ses méthodes rejettent `UNAVAILABLE`.
+ * Forme (interface TypeScript) de chaque capacité, indexée par son nom. Les 9 capacités de la v1 y sont déclarées ;
+ * une nouvelle capacité s'y ajoute par FUSION DE DÉCLARATION depuis son propre fichier (procédure « ajouter une
+ * capacité » du README), sans modifier celui-ci :
+ *
+ * ```ts
+ * declare module './types.js' {
+ *   interface CapabilityInterfaces {
+ *     maCapacite: MaCapaciteCapability;
+ *   }
+ * }
+ * ```
+ *
+ * Le nom doit aussi être déclaré dans `EgenCapabilityExtensions` (`@egen-civitas/esm-globals`) pour être un
+ * `CapabilityName` valide.
  */
-export interface Platform {
+export interface CapabilityInterfaces {
+    session: SessionCapability;
+    secureStorage: SecureStorageCapability;
+    openExternal: OpenExternalCapability;
+    lifecycle: LifecycleCapability;
+    permissions: PermissionsCapability;
+    files: FilesCapability;
+    camera: CameraCapability;
+    push: PushCapability;
+    biometric: BiometricCapability;
+}
+/** Ce qui est commun à toute plateforme, indépendamment des capacités. */
+export interface PlatformCore {
     readonly environment: PlatformEnvironment;
     /** Résolue quand le handshake avec le Host est terminé (immédiatement en Web). */
     readonly ready: Promise<void>;
     has(capability: CapabilityName): boolean;
-    readonly session: SessionCapability;
-    readonly secureStorage: SecureStorageCapability;
-    readonly openExternal: OpenExternalCapability;
-    readonly lifecycle: LifecycleCapability;
-    readonly permissions: PermissionsCapability;
-    readonly files: FilesCapability;
-    readonly camera: CameraCapability;
-    readonly push: PushCapability;
-    readonly biometric: BiometricCapability;
 }
+/**
+ * Point d'accès unique des apps aux capacités de plateforme.
+ * Une capacité indisponible (`has()` faux) existe toujours comme objet : ses méthodes rejettent `UNAVAILABLE`.
+ */
+export type Platform = PlatformCore & {
+    readonly [K in keyof CapabilityInterfaces]: CapabilityInterfaces[K];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@egen-civitas/esm-platform",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "MPL-2.0",
   "description": "Capacités de plateforme EGEN (web, Android, iOS) : contrats TypeScript, détection de la cible, erreurs typées et client du protocole Host. Aucun code natif ici.",
   "main": "dist/index.js",
@@ -32,10 +32,10 @@
     "lint": "eslint src --ext ts,tsx"
   },
   "dependencies": {
-    "@egen-civitas/esm-globals": "^2.1.0"
+    "@egen-civitas/esm-globals": "^2.2.0"
   },
   "peerDependencies": {
-    "@egen-civitas/esm-globals": "^2.1.0"
+    "@egen-civitas/esm-globals": "^2.2.0"
   },
   "devDependencies": {
     "@swc/cli": "0.8.1",