@egen-civitas/esm-platform 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @egen-civitas/esm-platform
+
+## 1.1.0
+
+### Minor Changes
+
+- d1d2d7d: Contrat d'app multiplateforme (F2) : `EgenAppRoutes.platforms` et `requiredCapabilities`. `registerApp` écarte (sans rien enregistrer) une app non éligible à la plateforme ou dont une capacité requise manque. `esm-globals` : `setCapabilityResolver` / `hasCapability`. `esm-platform` : `registerPlatformCapabilities()`. Shell : capacités rendues consultables avant l'enregistrement des apps. Sans champs dans `routes.json`, comportement inchangé.
+
+### Patch Changes
+
+- Updated dependencies [d1d2d7d]
+- Updated dependencies [669cbd6]
+- Updated dependencies [5958a56]
+  - @egen-civitas/esm-globals@2.1.0

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @egen-civitas/esm-platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Capacités de plateforme EGEN pour **Web, Android et iOS** : contrats TypeScript, détection de la cible, erreurs typées et (à venir) client du protocole Host.
+
+> Document de référence : `docs/EGEN-FRAMEWORK-DEV.md` à la racine du dépôt (chantier C).
+
+## Règles
+- **Aucun code natif** et aucun import `@capacitor/*` ici (règles R2/N2).
+- La cible est lue **uniquement** via `window.egenTarget` (posé au build). Pas de User-Agent (N4).
+- Les capacités rejettent toujours avec `PlatformError` (`UNAVAILABLE`, `DENIED`, `CANCELLED`, `INVALID_ARGS`, `TIMEOUT`, `INCOMPATIBLE`, `HOST_ERROR`).
+- Une capacité absente existe comme objet ; ses méthodes rejettent `UNAVAILABLE`. Utiliser `platform.has('…')`.
+
+## Utilisation
+
+Les apps importent **uniquement** via `@egen-civitas/esm-framework` (jamais `esm-platform` directement) :
+
+```ts
+import { getPlatform, PlatformError } from '@egen-civitas/esm-framework';
+
+const platform = getPlatform();
+if (platform.has('secureStorage')) {
+  const value = await platform.secureStorage.get('clé');
+}
+```
+
+**Web** : l'adaptateur du navigateur fournit `session` (vide : le cookie reste le mécanisme), `openExternal` (`https:`, `mailto:`, `tel:`),
+`lifecycle` (`visibilitychange`), `files.select`, `camera.capture` et, si l'API existe, `permissions`. `secureStorage`, `push` et `biometric` ne sont **jamais
+simulés** : `has()` est faux et les méthodes rejettent `PlatformError('UNAVAILABLE')`.
+**Natif** : tant que le client de pont (C5) n'est pas branché, **aucune capacité n'est fournie** (même comportement). Les abonnements `onResume`, `onPause`,
+`onMessage`, dont la signature n'est pas une `Promise`, lèvent la même erreur au lieu de rejeter.
+`platform.ready` se résout immédiatement en Web ; en natif il rejette `INCOMPATIBLE` (« Host manquant ») si `window.egenHostBridge` n'a pas été injecté.
+
+## Tests d'une app
+
+```ts
+import { createMockPlatform } from '@egen-civitas/esm-framework/mock';
+
+getPlatform.mockReturnValue(createMockPlatform({ capabilities: { openExternal: { open: vi.fn() } } }));
+```
+
+`createMockPlatform` utilise le même assembleur que `getPlatform()` (`src/capabilities.ts`) : seules les capacités listées sont disponibles,
+le reste reste `UNAVAILABLE`. Le mock et l'implémentation passent les **mêmes** tests de contrat (`src/platform.test.ts`).
+`createMockHost()` (simulation de `window.egenHostBridge`) viendra avec le client de pont (C5/C9).
+
+## État d'avancement
+| Élément | Tâche | État |
+|---|---|---|
+| Création du package et câblage (`esm-framework` index/internal/mocks, shell, typedoc) | C1 | fait |
+| Contrats TypeScript des capacités | C2 | fait |
+| Erreurs typées | C2 | fait |
+| Détection de la cible, cohérence du Host (`hasHostBridge`, `ready`) | C3 | fait |
+| `getPlatform()` sûr par défaut (aucune capacité simulée) | C1 | fait |
+| `createMockPlatform` | C9 | partiel (`createMockHost` à faire avec C5) |
+| Adaptateur Web | C4 | fait |
+| Client de pont / protocole v1 | C5 | à faire |
+| Registre et procédure d'ajout d'une capacité | C6 | à faire |

package/dist/adapters/web/camera.d.ts

@@ -0,0 +1,10 @@
+import type { CameraCapability } from '../../types.js';
+/**
+ * `camera.capture` en Web : `<input type="file" accept="image/*" capture>`.
+ *
+ * CHOIX documenté (la doc C4 demande d'en retenir UN) : l'attribut `capture` plutôt que `getUserMedia`. Raisons :
+ * pas de flux vidéo à gérer ni de permission préalable à orchestrer, et l'application de caméra du système est
+ * employée sur mobile. Contrepartie : sur ordinateur, `capture` est ignoré et l'utilisateur obtient un sélecteur de
+ * fichiers image (pas de prévisualisation intégrée).
+ */
+export declare function createWebCamera(): CameraCapability;

package/dist/adapters/web/camera.js

@@ -0,0 +1,31 @@
+import { PlatformError } from '../../errors.js';
+import { pickFiles } from './pick-files.js';
+import { registerWebFile } from './file-registry.js';
+/**
+ * `camera.capture` en Web : `<input type="file" accept="image/*" capture>`.
+ *
+ * CHOIX documenté (la doc C4 demande d'en retenir UN) : l'attribut `capture` plutôt que `getUserMedia`. Raisons :
+ * pas de flux vidéo à gérer ni de permission préalable à orchestrer, et l'application de caméra du système est
+ * employée sur mobile. Contrepartie : sur ordinateur, `capture` est ignoré et l'utilisateur obtient un sélecteur de
+ * fichiers image (pas de prévisualisation intégrée).
+ */
+export function createWebCamera() {
+    return {
+        async capture(options) {
+            const facing = options?.facing;
+            if (facing !== undefined && facing !== 'front' && facing !== 'back') {
+                throw new PlatformError('INVALID_ARGS', '`facing` doit valoir "front" ou "back".', {
+                    capability: 'camera',
+                    method: 'capture',
+                });
+            }
+            const [file] = await pickFiles({
+                accept: ['image/*'],
+                capture: facing === 'front' ? 'user' : 'environment',
+                capability: 'camera',
+                method: 'capture',
+            });
+            return registerWebFile(file);
+        },
+    };
+}

package/dist/adapters/web/file-registry.d.ts

@@ -0,0 +1,7 @@
+import type { FileHandle } from '../../types.js';
+/** Enregistre un fichier et retourne son handle (sans binaire). */
+export declare function registerWebFile(file: File): FileHandle;
+/** @internal */
+export declare function getWebFile(id: string): File | undefined;
+/** @internal Libère le fichier : à appeler dès qu'il a été lu ou téléversé. */
+export declare function releaseWebFile(id: string): boolean;

package/dist/adapters/web/file-registry.js

@@ -0,0 +1,26 @@
+/**
+ * Registre interne des fichiers choisis par l'utilisateur en Web. Un `FileHandle` ne porte jamais le binaire (contrat
+ * v1) : le `File` du navigateur est conservé ici, sous un identifiant opaque, jusqu'à ce que le consommateur
+ * (capacités fichiers, tâche C7) le récupère puis le libère. Non exporté par le point d'entrée du package.
+ */
+const files = new Map();
+let counter = 0;
+function newId() {
+    const random = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function' ? crypto.randomUUID() : null;
+    counter += 1;
+    return random ?? `web-file-${Date.now().toString(36)}-${counter}-${Math.random().toString(36).slice(2)}`;
+}
+/** Enregistre un fichier et retourne son handle (sans binaire). */
+export function registerWebFile(file) {
+    const id = newId();
+    files.set(id, file);
+    return { id, name: file.name, size: file.size, mime: file.type || 'application/octet-stream' };
+}
+/** @internal */
+export function getWebFile(id) {
+    return files.get(id);
+}
+/** @internal Libère le fichier : à appeler dès qu'il a été lu ou téléversé. */
+export function releaseWebFile(id) {
+    return files.delete(id);
+}

package/dist/adapters/web/files.d.ts

@@ -0,0 +1,7 @@
+import type { FilesCapability } from '../../types.js';
+/**
+ * `files` en Web : `select` utilise un `<input type="file">` éphémère. `download` n'est PAS fourni en Web en v1 :
+ * l'attribut `download` d'un lien est ignoré hors même origine, et la capacité ne doit pas promettre ce qu'elle ne
+ * garantit pas (`UNAVAILABLE`, comme les autres méthodes non fournies).
+ */
+export declare function createWebFiles(): Partial<FilesCapability>;

package/dist/adapters/web/files.js

@@ -0,0 +1,22 @@
+import { unavailable } from '../../errors.js';
+import { pickFiles } from './pick-files.js';
+import { registerWebFile } from './file-registry.js';
+/**
+ * `files` en Web : `select` utilise un `<input type="file">` éphémère. `download` n'est PAS fourni en Web en v1 :
+ * l'attribut `download` d'un lien est ignoré hors même origine, et la capacité ne doit pas promettre ce qu'elle ne
+ * garantit pas (`UNAVAILABLE`, comme les autres méthodes non fournies).
+ */
+export function createWebFiles() {
+    return {
+        async select(options) {
+            const selected = await pickFiles({
+                multiple: options?.multiple,
+                accept: options?.accept,
+                capability: 'files',
+                method: 'select',
+            });
+            return selected.map(registerWebFile);
+        },
+        download: () => Promise.reject(unavailable('files', 'download')),
+    };
+}

package/dist/adapters/web/index.d.ts

@@ -0,0 +1,7 @@
+import type { CapabilityOverrides } from '../../capabilities.js';
+/**
+ * Capacités fournies par le navigateur. PRINCIPE (doc C4) : ne jamais simuler de la sécurité. Sont donc ABSENTES
+ * (`has()` faux, méthodes `UNAVAILABLE`) : `secureStorage` (pas de faux coffre dans `localStorage`), `push` et
+ * `biometric` (v1), ainsi que `permissions` quand l'API Permissions n'existe pas.
+ */
+export declare function createWebCapabilities(): CapabilityOverrides;

package/dist/adapters/web/index.js

@@ -0,0 +1,24 @@
+import { createWebCamera } from './camera.js';
+import { createWebFiles } from './files.js';
+import { createWebLifecycle } from './lifecycle.js';
+import { createWebOpenExternal } from './open-external.js';
+import { createWebPermissions, isWebPermissionsAvailable } from './permissions.js';
+import { createWebSession } from './session.js';
+/**
+ * Capacités fournies par le navigateur. PRINCIPE (doc C4) : ne jamais simuler de la sécurité. Sont donc ABSENTES
+ * (`has()` faux, méthodes `UNAVAILABLE`) : `secureStorage` (pas de faux coffre dans `localStorage`), `push` et
+ * `biometric` (v1), ainsi que `permissions` quand l'API Permissions n'existe pas.
+ */
+export function createWebCapabilities() {
+    const capabilities = {
+        session: createWebSession(),
+        openExternal: createWebOpenExternal(),
+        lifecycle: createWebLifecycle(),
+        files: createWebFiles(),
+        camera: createWebCamera(),
+    };
+    if (isWebPermissionsAvailable()) {
+        capabilities.permissions = createWebPermissions();
+    }
+    return capabilities;
+}

package/dist/adapters/web/lifecycle.d.ts

@@ -0,0 +1,3 @@
+import type { LifecycleCapability } from '../../types.js';
+/** `lifecycle` en Web : `visibilitychange` → `onResume` (page visible) / `onPause` (page masquée). */
+export declare function createWebLifecycle(): LifecycleCapability;

package/dist/adapters/web/lifecycle.js

@@ -0,0 +1,20 @@
+import { PlatformError } from '../../errors.js';
+function subscribe(state, method, callback) {
+    if (typeof callback !== 'function') {
+        throw new PlatformError('INVALID_ARGS', 'Le callback doit être une fonction.', { capability: 'lifecycle', method });
+    }
+    const listener = () => {
+        if (document.visibilityState === state) {
+            callback();
+        }
+    };
+    document.addEventListener('visibilitychange', listener);
+    return () => document.removeEventListener('visibilitychange', listener);
+}
+/** `lifecycle` en Web : `visibilitychange` → `onResume` (page visible) / `onPause` (page masquée). */
+export function createWebLifecycle() {
+    return {
+        onResume: (callback) => subscribe('visible', 'onResume', callback),
+        onPause: (callback) => subscribe('hidden', 'onPause', callback),
+    };
+}

package/dist/adapters/web/open-external.d.ts

@@ -0,0 +1,8 @@
+import type { OpenExternalCapability } from '../../types.js';
+/**
+ * Valide une URL à ouvrir hors de l'app : schémas `https:`, `mailto:`, `tel:` UNIQUEMENT (ni `http:`, ni
+ * `javascript:`, ni `data:`, ni `file:`…). Le message d'erreur ne reprend jamais l'URL (elle peut contenir un secret).
+ */
+export declare function assertExternalUrl(url: unknown): string;
+/** `openExternal` en Web : `window.open(url, '_blank', 'noopener,noreferrer')` après validation. */
+export declare function createWebOpenExternal(): OpenExternalCapability;

package/dist/adapters/web/open-external.js

@@ -0,0 +1,32 @@
+import { PlatformError } from '../../errors.js';
+const ALLOWED_PROTOCOLS = new Set(['https:', 'mailto:', 'tel:']);
+/**
+ * Valide une URL à ouvrir hors de l'app : schémas `https:`, `mailto:`, `tel:` UNIQUEMENT (ni `http:`, ni
+ * `javascript:`, ni `data:`, ni `file:`…). Le message d'erreur ne reprend jamais l'URL (elle peut contenir un secret).
+ */
+export function assertExternalUrl(url) {
+    let parsed = null;
+    try {
+        parsed = typeof url === 'string' ? new URL(url) : null;
+    }
+    catch {
+        parsed = null;
+    }
+    if (!parsed || !ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new PlatformError('INVALID_ARGS', 'URL refusée : seuls les schémas https:, mailto: et tel: sont autorisés.', {
+            capability: 'openExternal',
+            method: 'open',
+        });
+    }
+    return parsed.href;
+}
+/** `openExternal` en Web : `window.open(url, '_blank', 'noopener,noreferrer')` après validation. */
+export function createWebOpenExternal() {
+    return {
+        async open(url) {
+            const href = assertExternalUrl(url);
+            // `noopener` : la page ouverte n'a pas accès à `window.opener` ; le retour de `open` est alors toujours `null`.
+            window.open(href, '_blank', 'noopener,noreferrer');
+        },
+    };
+}

package/dist/adapters/web/permissions.d.ts

@@ -0,0 +1,12 @@
+import type { PermissionsCapability } from '../../types.js';
+/** L'API Permissions du navigateur est-elle disponible ? Sinon la capacité n'est pas fournie (`has()` faux). */
+export declare function isWebPermissionsAvailable(): boolean;
+/**
+ * `permissions` en Web, via l'API Permissions du navigateur.
+ *
+ * - `check` : `navigator.permissions.query`. `files` n'a pas d'équivalent Web, et un navigateur qui ne connaît pas un
+ *   nom (ex. `camera` sous Firefox) lève : dans les deux cas `UNAVAILABLE`, jamais une valeur inventée.
+ * - `request` : seule `notifications` a une demande explicite en Web (`Notification.requestPermission`). Pour
+ *   `camera` et `microphone`, le navigateur demande l'accès au moment de l'usage : `UNAVAILABLE` (rien n'est simulé).
+ */
+export declare function createWebPermissions(): Partial<PermissionsCapability>;

package/dist/adapters/web/permissions.js

@@ -0,0 +1,48 @@
+import { PlatformError, unavailable } from '../../errors.js';
+const NAMES = ['camera', 'microphone', 'notifications', 'files'];
+function assertName(name, method) {
+    if (!NAMES.includes(name)) {
+        throw new PlatformError('INVALID_ARGS', `Permission inconnue. Valeurs acceptées : ${NAMES.join(', ')}.`, {
+            capability: 'permissions',
+            method,
+        });
+    }
+    return name;
+}
+/** L'API Permissions du navigateur est-elle disponible ? Sinon la capacité n'est pas fournie (`has()` faux). */
+export function isWebPermissionsAvailable() {
+    return typeof navigator !== 'undefined' && typeof navigator.permissions?.query === 'function';
+}
+/**
+ * `permissions` en Web, via l'API Permissions du navigateur.
+ *
+ * - `check` : `navigator.permissions.query`. `files` n'a pas d'équivalent Web, et un navigateur qui ne connaît pas un
+ *   nom (ex. `camera` sous Firefox) lève : dans les deux cas `UNAVAILABLE`, jamais une valeur inventée.
+ * - `request` : seule `notifications` a une demande explicite en Web (`Notification.requestPermission`). Pour
+ *   `camera` et `microphone`, le navigateur demande l'accès au moment de l'usage : `UNAVAILABLE` (rien n'est simulé).
+ */
+export function createWebPermissions() {
+    return {
+        async check(name) {
+            const permission = assertName(name, 'check');
+            if (permission === 'files') {
+                throw unavailable('permissions', 'check');
+            }
+            try {
+                const status = await navigator.permissions.query({ name: permission });
+                return status.state;
+            }
+            catch {
+                throw unavailable('permissions', 'check');
+            }
+        },
+        async request(name) {
+            const permission = assertName(name, 'request');
+            if (permission !== 'notifications' || typeof Notification === 'undefined') {
+                throw unavailable('permissions', 'request');
+            }
+            // « default » (fenêtre fermée sans choix) n'est pas un octroi.
+            return (await Notification.requestPermission()) === 'granted' ? 'granted' : 'denied';
+        },
+    };
+}

package/dist/adapters/web/pick-files.d.ts

@@ -0,0 +1,17 @@
+export interface PickFilesOptions {
+    multiple?: boolean;
+    accept?: string[];
+    /** Valeur de l'attribut `capture` (`user` = caméra frontale, `environment` = caméra arrière). */
+    capture?: 'user' | 'environment';
+    capability: string;
+    method: string;
+}
+/**
+ * Ouvre le sélecteur de fichiers du navigateur via un `<input type="file">` ÉPHÉMÈRE (créé, utilisé, retiré).
+ * Doit être appelé depuis un geste utilisateur, sans quoi le navigateur ignore `click()`.
+ *
+ * Annulation : l'événement `cancel` (navigateurs récents) rejette `CANCELLED`. Sur un navigateur qui ne l'émet pas,
+ * la promesse reste en attente tant que l'utilisateur ne choisit rien : c'est une limite connue, non contournable
+ * proprement sans deviner (pas d'heuristique sur le focus).
+ */
+export declare function pickFiles({ multiple, accept, capture, capability, method, }: PickFilesOptions): Promise<File[]>;

package/dist/adapters/web/pick-files.js

@@ -0,0 +1,49 @@
+import { PlatformError } from '../../errors.js';
+/** Types MIME ou extensions : `image/*`, `application/pdf`, `.csv`. Rien d'autre n'est écrit dans l'attribut `accept`. */
+const ACCEPT_ENTRY = /^(\.[A-Za-z0-9]+|[A-Za-z0-9!#$&^_.+-]+\/(\*|[A-Za-z0-9!#$&^_.+-]+))$/;
+/**
+ * Ouvre le sélecteur de fichiers du navigateur via un `<input type="file">` ÉPHÉMÈRE (créé, utilisé, retiré).
+ * Doit être appelé depuis un geste utilisateur, sans quoi le navigateur ignore `click()`.
+ *
+ * Annulation : l'événement `cancel` (navigateurs récents) rejette `CANCELLED`. Sur un navigateur qui ne l'émet pas,
+ * la promesse reste en attente tant que l'utilisateur ne choisit rien : c'est une limite connue, non contournable
+ * proprement sans deviner (pas d'heuristique sur le focus).
+ */
+export function pickFiles({ multiple = false, accept, capture, capability, method, }) {
+    if (accept !== undefined && (!Array.isArray(accept) || !accept.every((entry) => ACCEPT_ENTRY.test(String(entry))))) {
+        return Promise.reject(new PlatformError('INVALID_ARGS', '`accept` doit être une liste de types MIME ou d’extensions (ex. "image/*", ".csv").', {
+            capability,
+            method,
+        }));
+    }
+    return new Promise((resolve, reject) => {
+        const input = document.createElement('input');
+        input.type = 'file';
+        input.multiple = multiple;
+        if (accept && accept.length > 0) {
+            input.accept = accept.join(',');
+        }
+        if (capture) {
+            input.setAttribute('capture', capture);
+        }
+        // Certains navigateurs mobiles exigent l'élément dans le document pour déclencher le sélecteur.
+        input.style.display = 'none';
+        document.body.appendChild(input);
+        const cleanup = () => input.remove();
+        input.addEventListener('change', () => {
+            const selected = Array.from(input.files ?? []);
+            cleanup();
+            if (selected.length === 0) {
+                reject(new PlatformError('CANCELLED', 'Aucun fichier sélectionné.', { capability, method }));
+            }
+            else {
+                resolve(selected);
+            }
+        }, { once: true });
+        input.addEventListener('cancel', () => {
+            cleanup();
+            reject(new PlatformError('CANCELLED', 'Sélection annulée.', { capability, method }));
+        }, { once: true });
+        input.click();
+    });
+}

package/dist/adapters/web/session.d.ts

@@ -0,0 +1,12 @@
+import type { SessionCapability } from '../../types.js';
+/**
+ * `session` en Web : fournisseur d'autorisation VIDE. Le cookie de session reste le mécanisme d'authentification
+ * (`egenFetch` n'ajoute aucun en-tête `Authorization`, cf. D1) : il n'y a donc pas de jeton à fournir, et on n'en
+ * fabrique pas.
+ *
+ * - `getAuthorization` → `null` (« pas de jeton géré par le client ») ;
+ * - `refresh` → `false` (aucun nouveau jeton) ;
+ * - `clear` → no-op (rien n'est stocké côté client ; la déconnexion Web passe par le serveur) ;
+ * - `setTokens` → `UNAVAILABLE` : stocker un jeton dans le navigateur serait un faux coffre (jamais simuler de sécurité).
+ */
+export declare function createWebSession(): SessionCapability;

package/dist/adapters/web/session.js

@@ -0,0 +1,19 @@
+import { unavailable } from '../../errors.js';
+/**
+ * `session` en Web : fournisseur d'autorisation VIDE. Le cookie de session reste le mécanisme d'authentification
+ * (`egenFetch` n'ajoute aucun en-tête `Authorization`, cf. D1) : il n'y a donc pas de jeton à fournir, et on n'en
+ * fabrique pas.
+ *
+ * - `getAuthorization` → `null` (« pas de jeton géré par le client ») ;
+ * - `refresh` → `false` (aucun nouveau jeton) ;
+ * - `clear` → no-op (rien n'est stocké côté client ; la déconnexion Web passe par le serveur) ;
+ * - `setTokens` → `UNAVAILABLE` : stocker un jeton dans le navigateur serait un faux coffre (jamais simuler de sécurité).
+ */
+export function createWebSession() {
+    return {
+        getAuthorization: () => Promise.resolve(null),
+        refresh: () => Promise.resolve(false),
+        clear: () => Promise.resolve(),
+        setTokens: () => Promise.reject(unavailable('session', 'setTokens')),
+    };
+}