@ephia/sdk

SDK TypeScript officiel pour la dictée médicale Ephia (speech-to-text radiologique).

Version 2 : architecture target + adapter. Le SDK applique des commandes canoniques sur votre éditeur ; l’éditeur reste la source de vérité du document.

Installation

npm install @ephia/sdk
# ou
pnpm add @ephia/sdk

Dépendances peer

| Contexte | Packages requis | |---|---| | React | react, react-dom (^18 ou ^19) | | TipTap | @tiptap/core, @tiptap/pm (>= 2) — optionnels si vous n’utilisez pas TipTap |

Feuille de styles (obligatoire pour l’UI)

Importez une fois dans votre point d’entrée (layout, main.tsx, etc.) :

import "@ephia/sdk/style.css";

Sans cet import, le bouton flottant, l’overlay textarea et le preview TipTap (décorations) ne s’affichent pas correctement. Détail : docs/apparence.md.

Points d’entrée

| Import | Usage | |---|---| | @ephia/sdk | Réexport principal (React + UI + headless + utilitaires) | | @ephia/sdk/react | Provider, hooks, targets, composants React | | @ephia/sdk/ui | EphiaFloatingButton et primitives UI | | @ephia/sdk/headless | Client sans React (vanilla, Electron, scripts) | | @ephia/sdk/speechmike | Philips SpeechMike (WebHID) | | @ephia/sdk/testing | Helpers de test | | @ephia/sdk/style.css | Styles SDK (bouton, overlay textarea, décorations preview TipTap) |

Configuration minimale

Trois éléments suffisent pour une première dictée :

1. Authentification — bearerToken (production) ou apiKey (dev local uniquement)
2. EphiaProvider — une instance par application
3. Une target — zone de texte enregistrée via EphiaEditorTarget

"use client";

import { EphiaProvider, EphiaEditorTarget, createTextareaAdapter, useEphiaEditorTargetSync } from "@ephia/sdk/react";
import { EphiaFloatingButton } from "@ephia/sdk/ui";
import { resolveEphiaSdkApiUrl } from "@ephia/sdk";
import { useMemo, useState } from "react";
import "@ephia/sdk/style.css";

const TARGET_ID = "report";

export function App({ bearerToken }: { bearerToken: string }) {
  return (
    <EphiaProvider
      bearerToken={bearerToken}
      apiUrl={resolveEphiaSdkApiUrl()}
      clientType="my-app"
      options={{ language: "fr" }}
    >
      <ReportField />
      <EphiaFloatingButton dictationTargetId={TARGET_ID} />
    </EphiaProvider>
  );
}

function ReportField() {
  const [element, setElement] = useState<HTMLTextAreaElement | null>(null);
  const adapter = useMemo(() => createTextareaAdapter(element), [element]);
  const { handleFocus } = useEphiaEditorTargetSync({ targetId: TARGET_ID });

  return (
    <EphiaEditorTarget targetId={TARGET_ID} adapter={adapter} label="Compte rendu">
      <textarea ref={setElement} onFocus={handleFocus} rows={8} placeholder="Dictez ici…" />
    </EphiaEditorTarget>
  );
}

Production : ne jamais exposer apiKey dans le frontend. Générez un bearerToken court-vivant côté serveur. Voir docs/configuration.md.

Intégration classique (TipTap)

Modèle recommandé pour un compte rendu structuré :

EphiaProvider (1× par app)
  └─ EphiaEditorTarget + createTiptapAdapter(editor)
  └─ getTiptapEphiaExtensions() dans useEditor
  └─ EphiaFloatingButton  OU  useEphiaDictation() pour un bouton custom

Exemple complet : docs/integration-react.md.

Rôles des briques

| Brique | Rôle | Obligatoire ? | |---|---|---| | EphiaProvider | Connexion backend, runtime dictée, raccourcis clavier | Oui (1× par app avec éditeur) | | EphiaEditorTarget | Enregistre une zone d’édition (target) + adapter | Oui pour chaque champ | | createTiptapAdapter / createTextareaAdapter | Pont entre votre éditeur et le SDK | Oui | | getTiptapEphiaExtensions() | Extensions TipTap requises (schéma marks) ; le preview live est en décorations | Oui avec TipTap | | EphiaFloatingButton | Bouton de dictée prêt à l’emploi | Optionnel | | useEphiaDictation() | Contrôle programmatique start/stop | Optionnel (remplace le bouton) |

useEphiaDictation() ne remplace pas le Provider : il consomme le contexte créé par EphiaProvider.

Deux chemins d’intégration

A. App avec éditeur (recommandé)

Un seul EphiaProvider englobe l’éditeur et le bouton. Le bouton réutilise le Provider existant :

<EphiaProvider bearerToken={token}>
  <MyEditor />
  <EphiaFloatingButton dictationTargetId="report" />
</EphiaProvider>

B. Bouton seul (sans éditeur React)

EphiaFloatingButton peut créer son propre Provider si aucun ancêtre n’en fournit un :

<EphiaFloatingButton
  bearerToken={token}
  apiUrl="https://api.ephia.app"
  clientType="my-widget"
/>

Utile pour un widget minimal ou une preuve de concept. Dès qu’un éditeur est présent, préférez le chemin A.

Contrôle programmatique

import { useEphiaDictation } from "@ephia/sdk/react";

function CustomRecordButton() {
  const { status, start, stop } = useEphiaDictation();
  const recording = status === "recording";

  return (
    <button type="button" onClick={() => (recording ? stop() : start("report"))}>
      {recording ? "Arrêter" : "Dicter"}
    </button>
  );
}

stop({ awaitFinalization: true }) n’est nécessaire que si vous devez lire le transcript final ou effectuer une action destructive juste après l’arrêt.

Mise en forme du bouton

EphiaFloatingButton accepte des props d’apparence sans CSS custom :

| Prop | Valeurs | Défaut | |---|---|---| | theme | "light" | "dark" | "light" | | size | "S" | "M" | "L" | "M" | | variant | "standard" | "minimal" | "standard" | | borderRadius | "sm" | "md" | "lg" | "full" | "md" | | position | bottom-center, bottom-right, … | "bottom-center" | | interactionMode | "toggle" | "push-to-talk" | "toggle" | | colors | { primary, secondary } | thème Ephia | | shortcutHint | true | false | "⌥ + Space" | true en variant standard |

Guide détaillé : docs/apparence.md.

Hooks utiles

| Hook | Usage | |---|---| | useEphiaDictation() | start, stop, status | | useEphiaSession() | sessionId, erreurs session | | useEphiaConnection() | État connexion transport | | useEphiaTargetActions() | Target active, contexte éditeur | | useEphiaEditorTargetSync() | Focus → target active (textarea / TipTap) |

Headless (sans React)

import { createEphiaClient } from "@ephia/sdk/headless";

const client = createEphiaClient({
  bearerToken: token,
  apiUrl: "https://api.ephia.app",
  clientType: "my-script",
});

Voir docs/headless.md.

Documentation

| Fichier | Contenu | |---|---| | docs/integration-react.md | Intégration React / TipTap pas à pas | | docs/configuration.md | EphiaProvider, auth, options session | | docs/apparence.md | Bouton flottant, CSS, theming | | docs/headless.md | Client sans UI React |

Documentation en ligne (guides complets, FAQ, dépannage) : docs.ephia.app.

Licence

Propriétaire — usage soumis aux conditions Ephia.