@egen-civitas/esm-platform 1.1.0 → 1.2.0

package/dist/bridge/index.d.ts

@@ -0,0 +1,4 @@
+export { createBridgeClient } from './client.js';
+export type { BridgeClient, BridgeClientOptions, CallOptions, HostInfo } from './client.js';
+export { DEFAULT_TIMEOUT_MS, HOST_PROTOCOL_NAME, MAX_MESSAGE_LENGTH, SUPPORTED_PROTOCOL, isSupportedProtocolVersion, parseHostMessage, } from './protocol.js';
+export type { HostBridge, HostEvent, HostFailure, HostMessage, HostRequest, HostSuccess } from './protocol.js';

package/dist/bridge/index.js

@@ -0,0 +1,2 @@
+export { createBridgeClient } from './client.js';
+export { DEFAULT_TIMEOUT_MS, HOST_PROTOCOL_NAME, MAX_MESSAGE_LENGTH, SUPPORTED_PROTOCOL, isSupportedProtocolVersion, parseHostMessage, } from './protocol.js';

package/dist/bridge/protocol.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Protocole Host ↔ Shell, version 1 — voir docs/EGEN-FRAMEWORK-DEV.md, annexe 1.
+ * Transport : chaînes JSON UTF-8 via `window.egenHostBridge`.
+ */
+/** Valeur du champ `p` de chaque message : tout message sans elle est ignoré. */
+export declare const HOST_PROTOCOL_NAME = "egen-host";
+/** Versions du protocole que CE client sait parler. Un Host hors de cette plage est `INCOMPATIBLE`. */
+export declare const SUPPORTED_PROTOCOL: {
+    readonly min: 1;
+    readonly max: 1;
+};
+/**
+ * Taille maximale d'un message JSON, en caractères (proposition de la doc, à valider sur appareil). Au-delà, le Host
+ * doit fournir une référence de fichier (`FileHandle`) plutôt qu'un binaire inline.
+ */
+export declare const MAX_MESSAGE_LENGTH: number;
+/** Délai par défaut d'un appel avant `TIMEOUT`. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Contrat de pont que le Host injecte AVANT tout script de la page : `window.egenHostBridge`.
+ * Le framework ne connaît rien d'autre du natif (règles R2 / N2).
+ */
+export interface HostBridge {
+    /** web → host : un message JSON. */
+    send(json: string): void;
+    /** host → web : le Host appelle `callback` avec un message JSON. Appelé UNE fois par le client. */
+    subscribe(callback: (json: string) => void): void;
+}
+export interface HostRequest {
+    p: typeof HOST_PROTOCOL_NAME;
+    v: number;
+    id: string;
+    ns: string;
+    m: string;
+    a?: unknown;
+}
+export interface HostSuccess {
+    p: typeof HOST_PROTOCOL_NAME;
+    v: number;
+    id: string;
+    ok: true;
+    r?: unknown;
+}
+export interface HostFailure {
+    p: typeof HOST_PROTOCOL_NAME;
+    v: number;
+    id: string;
+    ok: false;
+    /** Contenu NON fiable : validé par le client avant d'être converti en `PlatformError`. */
+    e: {
+        code?: unknown;
+        message?: unknown;
+        retryable?: unknown;
+    };
+}
+export interface HostEvent {
+    p: typeof HOST_PROTOCOL_NAME;
+    v: number;
+    ev: string;
+    d?: unknown;
+}
+export type HostMessage = HostSuccess | HostFailure | HostEvent;
+export declare const KNOWN_ERROR_CODES: ReadonlySet<string>;
+export declare function isSupportedProtocolVersion(version: unknown): version is number;
+/**
+ * Décode un message du Host. Retourne `null` pour tout ce qui n'est pas un message du protocole : entrée non
+ * textuelle, trop longue, JSON invalide, autre valeur de `p`, forme inconnue. Ne lève JAMAIS et n'évalue rien.
+ *
+ * Le champ `v` n'est PAS filtré ici : le client doit pouvoir répondre « incompatible » à un appel en attente plutôt
+ * que de le laisser expirer.
+ */
+export declare function parseHostMessage(raw: unknown): HostMessage | null;

package/dist/bridge/protocol.js

@@ -0,0 +1,66 @@
+/**
+ * Protocole Host ↔ Shell, version 1 — voir docs/EGEN-FRAMEWORK-DEV.md, annexe 1.
+ * Transport : chaînes JSON UTF-8 via `window.egenHostBridge`.
+ */
+/** Valeur du champ `p` de chaque message : tout message sans elle est ignoré. */
+export const HOST_PROTOCOL_NAME = 'egen-host';
+/** Versions du protocole que CE client sait parler. Un Host hors de cette plage est `INCOMPATIBLE`. */
+export const SUPPORTED_PROTOCOL = { min: 1, max: 1 };
+/**
+ * Taille maximale d'un message JSON, en caractères (proposition de la doc, à valider sur appareil). Au-delà, le Host
+ * doit fournir une référence de fichier (`FileHandle`) plutôt qu'un binaire inline.
+ */
+export const MAX_MESSAGE_LENGTH = 256 * 1024;
+/** Délai par défaut d'un appel avant `TIMEOUT`. */
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const KNOWN_ERROR_CODES = new Set([
+    'UNAVAILABLE',
+    'DENIED',
+    'CANCELLED',
+    'INVALID_ARGS',
+    'TIMEOUT',
+    'INCOMPATIBLE',
+    'HOST_ERROR',
+]);
+export function isSupportedProtocolVersion(version) {
+    return (Number.isInteger(version) &&
+        version >= SUPPORTED_PROTOCOL.min &&
+        version <= SUPPORTED_PROTOCOL.max);
+}
+/**
+ * Décode un message du Host. Retourne `null` pour tout ce qui n'est pas un message du protocole : entrée non
+ * textuelle, trop longue, JSON invalide, autre valeur de `p`, forme inconnue. Ne lève JAMAIS et n'évalue rien.
+ *
+ * Le champ `v` n'est PAS filtré ici : le client doit pouvoir répondre « incompatible » à un appel en attente plutôt
+ * que de le laisser expirer.
+ */
+export function parseHostMessage(raw) {
+    if (typeof raw !== 'string' || raw.length === 0 || raw.length > MAX_MESSAGE_LENGTH) {
+        return null;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const message = value;
+    if (message.p !== HOST_PROTOCOL_NAME || typeof message.v !== 'number') {
+        return null;
+    }
+    if (typeof message.id === 'string' && typeof message.ok === 'boolean') {
+        if (message.ok) {
+            return { p: HOST_PROTOCOL_NAME, v: message.v, id: message.id, ok: true, r: message.r };
+        }
+        const e = typeof message.e === 'object' && message.e !== null && !Array.isArray(message.e) ? message.e : {};
+        return { p: HOST_PROTOCOL_NAME, v: message.v, id: message.id, ok: false, e };
+    }
+    if (typeof message.ev === 'string') {
+        return { p: HOST_PROTOCOL_NAME, v: message.v, ev: message.ev, d: message.d };
+    }
+    return null;
+}

package/dist/bridge/protocol.test.js

@@ -0,0 +1,215 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+import { describe, expect, it } from 'vitest';
+import { MAX_MESSAGE_LENGTH, isSupportedProtocolVersion, parseHostMessage } from './protocol';
+var msg = function msg(extra) {
+    return JSON.stringify(_object_spread({
+        p: 'egen-host',
+        v: 1
+    }, extra));
+};
+describe('isSupportedProtocolVersion', function() {
+    it('accepte la v1 uniquement', function() {
+        expect(isSupportedProtocolVersion(1)).toBe(true);
+        expect(isSupportedProtocolVersion(0)).toBe(false);
+        expect(isSupportedProtocolVersion(2)).toBe(false);
+        expect(isSupportedProtocolVersion(1.5)).toBe(false);
+        expect(isSupportedProtocolVersion('1')).toBe(false);
+    });
+});
+describe('parseHostMessage', function() {
+    it('décode une réponse de succès', function() {
+        expect(parseHostMessage(msg({
+            id: 'a',
+            ok: true,
+            r: 42
+        }))).toEqual({
+            p: 'egen-host',
+            v: 1,
+            id: 'a',
+            ok: true,
+            r: 42
+        });
+    });
+    it("décode une réponse d'échec et normalise un `e` absent en objet vide", function() {
+        expect(parseHostMessage(msg({
+            id: 'a',
+            ok: false,
+            e: {
+                code: 'DENIED'
+            }
+        }))).toMatchObject({
+            ok: false,
+            e: {
+                code: 'DENIED'
+            }
+        });
+        expect(parseHostMessage(msg({
+            id: 'a',
+            ok: false
+        }))).toMatchObject({
+            ok: false,
+            e: {}
+        });
+        expect(parseHostMessage(msg({
+            id: 'a',
+            ok: false,
+            e: 'x'
+        }))).toMatchObject({
+            ok: false,
+            e: {}
+        });
+    });
+    it('décode un événement', function() {
+        expect(parseHostMessage(msg({
+            ev: 'lifecycle.resume',
+            d: {
+                a: 1
+            }
+        }))).toEqual({
+            p: 'egen-host',
+            v: 1,
+            ev: 'lifecycle.resume',
+            d: {
+                a: 1
+            }
+        });
+    });
+    it('ne filtre pas la version (le client répond « incompatible » plutôt que de laisser expirer)', function() {
+        expect(parseHostMessage(JSON.stringify({
+            p: 'egen-host',
+            v: 9,
+            id: 'a',
+            ok: true
+        }))).toMatchObject({
+            v: 9
+        });
+    });
+    it.each([
+        [
+            'non textuel',
+            42
+        ],
+        [
+            'objet',
+            {}
+        ],
+        [
+            'null',
+            null
+        ],
+        [
+            'chaîne vide',
+            ''
+        ],
+        [
+            'JSON invalide',
+            '{pas du json'
+        ],
+        [
+            'tableau',
+            '[]'
+        ],
+        [
+            'nombre JSON',
+            '12'
+        ],
+        [
+            'sans p',
+            JSON.stringify({
+                v: 1,
+                id: 'a',
+                ok: true
+            })
+        ],
+        [
+            'mauvais p',
+            JSON.stringify({
+                p: 'autre',
+                v: 1,
+                id: 'a',
+                ok: true
+            })
+        ],
+        [
+            'v non numérique',
+            JSON.stringify({
+                p: 'egen-host',
+                v: '1',
+                id: 'a',
+                ok: true
+            })
+        ],
+        [
+            'ni réponse ni événement',
+            msg({
+                foo: 1
+            })
+        ],
+        [
+            'id non textuel',
+            msg({
+                id: 5,
+                ok: true
+            })
+        ],
+        [
+            'ok non booléen',
+            msg({
+                id: 'a',
+                ok: 'oui'
+            })
+        ],
+        [
+            'ev non textuel',
+            msg({
+                ev: 5
+            })
+        ]
+    ])('ignore : %s', function(_label, raw) {
+        expect(parseHostMessage(raw)).toBeNull();
+    });
+    it('ignore un message trop long', function() {
+        expect(parseHostMessage(msg({
+            id: 'a',
+            ok: true,
+            r: 'x'.repeat(MAX_MESSAGE_LENGTH)
+        }))).toBeNull();
+    });
+    it("n'évalue rien : un contenu qui ressemble à du code reste une donnée", function() {
+        var parsed = parseHostMessage(msg({
+            id: 'a',
+            ok: true,
+            r: 'alert(1)//</script>'
+        }));
+        expect(parsed).toMatchObject({
+            r: 'alert(1)//</script>'
+        });
+    });
+});

package/dist/capabilities.d.ts

@@ -1,14 +1,17 @@
 import type { CapabilityName } from '@egen-civitas/esm-globals';
-import type { Platform, PlatformEnvironment } from './types.js';
-/** Les capacités d'une plateforme, indexées par leur nom (`CapabilityName` = clés de `Platform`). */
-export type CapabilityMap = Pick<Platform, CapabilityName>;
+import type { CapabilityInterfaces, Platform, PlatformEnvironment } from './types.js';
+/** Les capacités d'une plateforme, indexées par leur nom (clés de `CapabilityInterfaces`). */
+export type CapabilityMap = {
+    [K in keyof CapabilityInterfaces]: CapabilityInterfaces[K];
+};
 /** Implémentations (éventuellement partielles) fournies par un adaptateur ; ce qui manque reste `UNAVAILABLE`. */
 export type CapabilityOverrides = {
-    [K in CapabilityName]?: Partial<CapabilityMap[K]>;
+    [K in keyof CapabilityInterfaces]?: Partial<CapabilityInterfaces[K]>;
 };
 /**
- * Toutes les capacités, sous forme d'objets dont chaque méthode échoue en `UNAVAILABLE`. Une capacité absente EXISTE
- * donc toujours comme objet (règle C2) ; c'est `has()` qui dit si elle est réellement fournie.
+ * Toutes les capacités DU REGISTRE, sous forme d'objets dont chaque méthode échoue en `UNAVAILABLE`. Une capacité
+ * absente EXISTE donc toujours comme objet (règle C2) ; c'est `has()` qui dit si elle est réellement fournie.
+ * Dérivé de `registry.ts` : ajouter une capacité au registre l'ajoute ici sans rien modifier.
  */
 export declare function createUnavailableCapabilities(): CapabilityMap;
 export interface AssemblePlatformOptions {
@@ -17,10 +20,15 @@ export interface AssemblePlatformOptions {
     capabilities?: CapabilityOverrides;
     /** Appelée à CHAQUE lecture de `platform.ready` (évite un rejet non observé si personne ne l'attend). */
     ready: () => Promise<void>;
+    /**
+     * Filtre dynamique en plus de la présence d'un adaptateur : une capacité n'est disponible que si elle est fournie
+     * ET que ce prédicat l'accepte (natif : le Host l'a annoncée au handshake). Défaut : toujours vrai.
+     */
+    available?: (capability: CapabilityName) => boolean;
 }
 /**
  * Assemble un objet `Platform` : les capacités fournies remplacent celles indisponibles, et `has()` n'est vrai que pour
  * elles. Point unique de construction, partagé par `getPlatform()`, les adaptateurs (C4, C5) et les mocks (C9) : ils
  * ne peuvent donc pas diverger du contrat.
  */
-export declare function assemblePlatform({ environment, capabilities, ready }: AssemblePlatformOptions): Platform;
+export declare function assemblePlatform({ environment, capabilities, ready, available, }: AssemblePlatformOptions): Platform;

package/dist/capabilities.js

@@ -1,4 +1,5 @@
 import { unavailable } from './errors.js';
+import { getCapabilityDefinition, listCapabilityNames } from './registry.js';
 /** Méthode asynchrone d'une capacité absente : REJETTE `UNAVAILABLE` (jamais de `null` ambigu). */
 const rejecting = (capability, method) => () => Promise.reject(unavailable(capability, method));
 /**
@@ -9,52 +10,27 @@ const throwing = (capability, method) => () => {
     throw unavailable(capability, method);
 };
 /**
- * Toutes les capacités, sous forme d'objets dont chaque méthode échoue en `UNAVAILABLE`. Une capacité absente EXISTE
- * donc toujours comme objet (règle C2) ; c'est `has()` qui dit si elle est réellement fournie.
+ * Toutes les capacités DU REGISTRE, sous forme d'objets dont chaque méthode échoue en `UNAVAILABLE`. Une capacité
+ * absente EXISTE donc toujours comme objet (règle C2) ; c'est `has()` qui dit si elle est réellement fournie.
+ * Dérivé de `registry.ts` : ajouter une capacité au registre l'ajoute ici sans rien modifier.
  */
 export function createUnavailableCapabilities() {
-    return {
-        session: {
-            getAuthorization: rejecting('session', 'getAuthorization'),
-            setTokens: rejecting('session', 'setTokens'),
-            refresh: rejecting('session', 'refresh'),
-            clear: rejecting('session', 'clear'),
-        },
-        secureStorage: {
-            get: rejecting('secureStorage', 'get'),
-            set: rejecting('secureStorage', 'set'),
-            remove: rejecting('secureStorage', 'remove'),
-        },
-        openExternal: { open: rejecting('openExternal', 'open') },
-        lifecycle: {
-            onResume: throwing('lifecycle', 'onResume'),
-            onPause: throwing('lifecycle', 'onPause'),
-        },
-        permissions: {
-            check: rejecting('permissions', 'check'),
-            request: rejecting('permissions', 'request'),
-        },
-        files: {
-            select: rejecting('files', 'select'),
-            download: rejecting('files', 'download'),
-        },
-        camera: { capture: rejecting('camera', 'capture') },
-        push: {
-            register: rejecting('push', 'register'),
-            onMessage: throwing('push', 'onMessage'),
-        },
-        biometric: {
-            isAvailable: rejecting('biometric', 'isAvailable'),
-            authenticate: rejecting('biometric', 'authenticate'),
-        },
-    };
+    const capabilities = {};
+    for (const name of listCapabilityNames()) {
+        const methods = getCapabilityDefinition(name)?.methods ?? {};
+        capabilities[name] = Object.fromEntries(Object.entries(methods).map(([method, kind]) => [
+            method,
+            kind === 'subscribe' ? throwing(name, method) : rejecting(name, method),
+        ]));
+    }
+    return capabilities;
 }
 /**
  * Assemble un objet `Platform` : les capacités fournies remplacent celles indisponibles, et `has()` n'est vrai que pour
  * elles. Point unique de construction, partagé par `getPlatform()`, les adaptateurs (C4, C5) et les mocks (C9) : ils
  * ne peuvent donc pas diverger du contrat.
  */
-export function assemblePlatform({ environment, capabilities = {}, ready }) {
+export function assemblePlatform({ environment, capabilities = {}, ready, available, }) {
     const base = createUnavailableCapabilities();
     const provided = new Set(Object.keys(capabilities));
     const merged = {};
@@ -66,7 +42,7 @@ export function assemblePlatform({ environment, capabilities = {}, ready }) {
         get ready() {
             return ready();
         },
-        has: (capability) => provided.has(capability),
+        has: (capability) => provided.has(capability) && (available?.(capability) ?? true),
         ...merged,
     };
 }

package/dist/detect.d.ts

@@ -1,3 +1,4 @@
+import type { HostBridge } from './bridge/protocol.js';
 import type { PlatformEnvironment } from './types.js';
 /**
  * Environnement d'exécution courant. Source UNIQUE : `window.egenTarget`, posé au build.
@@ -9,10 +10,16 @@ export declare function getPlatformEnvironment(): PlatformEnvironment;
 /** `true` en Android/iOS. */
 export declare function isNativePlatform(): boolean;
 /**
- * `true` si le Host a injecté un pont conforme au contrat (`window.egenHostBridge = { send, subscribe }`, tâche C5).
- * Ne vérifie que la FORME du pont : le handshake (version, capacités) est fait par le client de pont (C5).
+ * Le pont injecté par le Host (`window.egenHostBridge = { send, subscribe }`), ou `null` s'il est absent ou non
+ * conforme. Ne vérifie que la FORME du pont : le handshake (version, capacités) est fait par le client de pont.
  * Jamais de détection par User-Agent ni par bibliothèque d'enveloppe (N4).
  *
  * @category Platform
  */
+export declare function getHostBridge(): HostBridge | null;
+/**
+ * `true` si le Host a injecté un pont conforme au contrat.
+ *
+ * @category Platform
+ */
 export declare function hasHostBridge(): boolean;

package/dist/detect.js

@@ -13,16 +13,26 @@ export function isNativePlatform() {
     return isNativeTarget();
 }
 /**
- * `true` si le Host a injecté un pont conforme au contrat (`window.egenHostBridge = { send, subscribe }`, tâche C5).
- * Ne vérifie que la FORME du pont : le handshake (version, capacités) est fait par le client de pont (C5).
+ * Le pont injecté par le Host (`window.egenHostBridge = { send, subscribe }`), ou `null` s'il est absent ou non
+ * conforme. Ne vérifie que la FORME du pont : le handshake (version, capacités) est fait par le client de pont.
  * Jamais de détection par User-Agent ni par bibliothèque d'enveloppe (N4).
  *
  * @category Platform
  */
-export function hasHostBridge() {
+export function getHostBridge() {
     if (typeof window === 'undefined') {
-        return false;
+        return null;
     }
     const bridge = window.egenHostBridge;
-    return !!bridge && typeof bridge.send === 'function' && typeof bridge.subscribe === 'function';
+    return bridge && typeof bridge.send === 'function' && typeof bridge.subscribe === 'function'
+        ? bridge
+        : null;
+}
+/**
+ * `true` si le Host a injecté un pont conforme au contrat.
+ *
+ * @category Platform
+ */
+export function hasHostBridge() {
+    return getHostBridge() !== null;
 }

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export * from './types.js';
 export * from './errors.js';
 export * from './detect.js';
 export { getPlatform, registerPlatformCapabilities } from './platform.js';
+export { getHostInfo } from './native.js';
+export * from './bridge/index.js';

package/dist/index.js

@@ -10,3 +10,5 @@ export * from './types.js';
 export * from './errors.js';
 export * from './detect.js';
 export { getPlatform, registerPlatformCapabilities } from './platform.js';
+export { getHostInfo } from './native.js';
+export * from './bridge/index.js';