---
title: "Référence d'API — nodefony/client — realtime-RealtimeEventMap"
source: docs/api/core/client-realtime-RealtimeEventMap.md
url: https://nodefony.net/docs/api/core/client-realtime-RealtimeEventMap/
---


[Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › client-realtime-RealtimeEventMap

> Générée depuis les déclarations de types publiées de `nodefony` **10.0.0-beta.7** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

## `nodefony/client`

`import { … } from "nodefony/client"` — 31 symboles.

### Constantes (1)

#### `REALTIME_PRESENCE_METHOD`

```ts
const REALTIME_PRESENCE_METHOD = "realtime:presence"
```

Nom de la notification du protocole qui porte la présence d'un canal (ADR-0025 P2 bis) — une source pour le serveur qui l'émet et le navigateur qui la lit.

### Interfaces (13)

#### `IContractRoute`

```ts
interface IContractRoute
```

Une route servie par le pont, vue par le contrat : le schéma de son corps et de sa query — la VALEUR que la route valide, référencée par `typeof`, jamais recopiée —, et ce qu'elle rend.

- `body?: IStandardSchemaV1` — Schéma du corps (`schema: { body }` de la route).
- `query?: IStandardSchemaV1` — Schéma de la query (`schema: { query }` de la route).
- `params?: IStandardSchemaV1` — Schéma des paramètres de chemin (`schema: { params }` de la route) ; absent, leurs noms sont lus dans le gabarit de la clé (`{id}`).
- `result: unknown` — Ce que l'action rend.

#### `IPresenceEntry`

```ts
interface IPresenceEntry<TState = unknown>
```

Ce que porte une identité présente sur un canal (ADR-0025 P4) — l'entrée de la VUE (`ReadonlyMap` du hook, `hub.presence()`). Sur le fil, entre pods comme vers le navigateur, elle voyage à plat (`PresencePairs`, `PresenceStates`).

- `tabs: number` — Connexions (onglets) de cette identité sur le canal, tous pods confondus — entier ≥ 1.
- `states?: Readonly<Record<string, TState>>` — États par onglet ; clé = référence d'onglet OPAQUE (elle ne dit rien de la topologie des pods), présente seulement avec un état (RFC 3863 §4.1.2, `id` de chaque tuple).

#### `IRealtimeClosed`

```ts
interface IRealtimeClosed
```

Payload de la notification système `realtime:closed` — poussée par le serveur quand il met fin, de lui-même, à un abonnement en cours (ADR-0021 S4, ADR-0022 §6 décision 3).

- `channel: string` — Canal dont l'abonnement vient de prendre fin.
- `reason: RealtimeClosedReason` — Pourquoi (cf `RealtimeClosedReason`) — jamais le détail de la décision.

#### `IRealtimeContract`

```ts
interface IRealtimeContract
```

Le moule du contrat temps réel d'une application — déclaré UNE fois, dans un fichier partagé par ses deux côtés, et lu par chacun dans SA direction.

- `serverToClient?: EventsMap` — Événements poussés par le serveur (socket, flux SSE, webhook).
- `clientToServer?: EventsMap` — Événements envoyés par le client.
- `serverMethods?: ActionsMap` — Méthodes du serveur : le client appelle, le serveur répond.
- `clientMethods?: ActionsMap` — Méthodes du client : le serveur appelle, le client répond.
- `serverRoutes?: RoutesMap` — Routes servies par le pont `api.request` : `"<VERBE> <chemin>"` → schéma du corps et de la query (`typeof` du schéma que la route VALIDE — une seule source) et résultat.

#### `IRealtimeDenied`

```ts
interface IRealtimeDenied
```

Payload de la notification système `realtime:denied` — poussée par le serveur quand une frame `subscribe`/inbound est REFUSÉE par le verrou d'autorisation (P6). Rend le refus OBSERVABLE côté client (une notification, contrairement à une requête, serait sinon droppée en silence → le client resterait aveugle).

- `channel: string` — Canal (ou méthode inbound) refusé(e).
- `reason: RealtimeDeniedReason` — Motif générique (cf `RealtimeDeniedReason`) — jamais le détail de la policy.
- `detail?: string` — Ce qui s'est passé, en clair — **hors production UNIQUEMENT**.
- `retryAfterMs?: number` — Délai minimal, en millisecondes, avant de réessayer — posé seulement avec `reason: "unavailable"`, quand le serveur sait combien de temps il restera indisponible (coupe-circuit ouvert).

#### `IRealtimePresenceChanges`

```ts
interface IRealtimePresenceChanges<TState = unknown>
```

Changements appliqués à la vue (trame `IRealtimePresenceDelta`).

- `set?: PresencePairs` — Identités arrivées ou modifiées, avec leur nombre d'onglets (remplace l'ancien).
- `states?: PresenceStates<TState>` — États des identités de `set` qui en portent un.
- `gone?: readonly string[]` — Identités parties.

#### `IRealtimePresenceCount`

```ts
interface IRealtimePresenceCount extends IRealtimePresenceHead
```

Nombres seuls : au-delà du seuil de membres nommés (défaut 1 000 ; seuil 0 = jamais nommés), aucune identité ne voyage. Complète comme une liste — elle porte la version courante, remplace la vue (vide d'identités) et réinitialise la référence.

- `members?: never`
- `changes?: never`
- `states?: never`

#### `IRealtimePresenceDelta`

```ts
interface IRealtimePresenceDelta<TState = unknown> extends IRealtimePresenceHead
```

Changements numérotés : s'appliquent à la vue seulement si la règle `classifyNumberedChange(référence, version)` rend `applied` ; `gap` → le client réémet `subscribe`, `stale` → jetée.

- `changes: IRealtimePresenceChanges<TState>`
- `members?: never`
- `states?: never`

#### `IRealtimePresenceHead`

```ts
interface IRealtimePresenceHead
```

En-tête commun des trames `realtime:presence` (ADR-0025 P2 bis) — champs figés.

- `channel: string` — Nom EXACT du canal décrit (un canal cadencé `base:<ms>` en est un autre).
- `version: number` — Version de la vue, entière, propre au canal SUR le pod qui sert la connexion.
- `count: number` — Identités NOMMÉES distinctes présentes (comptes seulement).
- `unnamed: number` — Connexions comptées sans être nommées (anonymes, appelants machine sans compte).
- `partial?: true` — Présent seulement à `true` : la vue est connue incomplète ou figée (liste locale avant la réponse des pairs, bus perdu, trou en cours sur un pod).

#### `IRealtimePresenceList`

```ts
interface IRealtimePresenceList<TState = unknown> extends IRealtimePresenceHead
```

Liste complète : REMPLACE la vue et RÉINITIALISE sa référence de version. Servie à chaque (re-)`subscribe`, et à tout moment quand elle pèse moins que les changements (RFC 5262 §4) — le client l'accepte sans l'avoir demandée.

- `members: PresencePairs` — Tous les présents NOMMÉS, à plat (cf `PresencePairs`).
- `states?: PresenceStates<TState>` — États des présents qui en portent un.
- `changes?: never`

#### `IRealtimeSubscribed`

```ts
interface IRealtimeSubscribed
```

Payload de la notification système `realtime:subscribed` — poussée par le serveur quand un `subscribe` est ACCEPTÉ, y compris pour un canal que la connexion suivait déjà (sans quoi un `subscribe` réémis attendrait un acquittement qui ne vient jamais).

- `channel: string` — Canal dont l'abonnement est désormais effectif sur cette connexion.
- `imposed?: true` — `true` quand c'est le SERVEUR qui a abonné la connexion (abonnement imposé, ADR-0022 §6 décision 2) — absent pour la réponse à un `subscribe` du client.

#### `IRealtimeWelcome`

```ts
interface IRealtimeWelcome
```

Payload de la notification système `realtime:welcome` — **1ʳᵉ frame** poussée par le serveur juste après le handshake. Annonce le protocole, les canaux/actions **découvrables** de l'endpoint et l'`RealtimeIdentity` résolue de la connexion. Cold path (1×/connexion).

- `ts: number` — Timestamp serveur (ms epoch).
- `protocol: string` — Étiquette de protocole (`"jsonrpc-2.0"`).
- `channels: string[]` — Canaux pub/sub annoncés par l'endpoint (découverte).
- `methods: string[]` — Actions RPC exposées par l'endpoint (découverte).
- `identity: RealtimeIdentity` — Identité résolue de CETTE connexion (cf `RealtimeIdentity`).
- `env?: string` — Mode d'exécution du serveur — **posé UNIQUEMENT hors production**.
- `subscriptionAcks?: boolean` — Le serveur ACQUITTE chaque abonnement accepté (`realtime:subscribed`, cf `IRealtimeSubscribed`).
- `codec?: string` — Sous-protocole du codec retenu pour les frames qui SUIVENT cet accueil — l'un de ceux que le client a offerts au handshake (ADR-0022 §2, cf `IFrameCodec`).
- `bytes?: string` — Marqueur de la convention d'octets (`$bytes`) que le serveur émet sur cette connexion TEXTE — posé quand il a activé un codec binaire que le client n'a pas pris (ADR-0022 §2).

#### `RealtimeIdentity`

```ts
interface RealtimeIdentity
```

Identité d'une connexion temps réel, telle que **résolue par le serveur au handshake** (token neutre `IRealtimeToken` côté back) et **annoncée au client** dans la notification système `realtime:welcome`.

- `type: string` — Type de token résolu (`"anonymous"`, `"session"`, `"jwt"`, …) — discriminator.
- `authenticated: boolean` — `false` pour un visiteur anonyme (Zero Trust : toujours présent, jamais `null`).
- `id: string | null` — Identifiant STABLE et OPAQUE du compte — la clé des canaux personnels (`user:${id}`) ; `null` pour l'anonyme, et pour un authentificateur qui ne produit pas d'identité d'admission (`IRealtimeToken.get …
- `userIdentifier: string` — Identifiant logique du porteur (`"anonymous"`, `"user-42"`, …) — affichage et audit, jamais une clé de canal.
- `roles: readonly string[]` — Rôles **plats** (RBAC, sans hiérarchie résolue) — `["ROLE_ANONYMOUS"]` si anonyme.
- `scopes: readonly string[]` — Scopes accordés (clés API / OAuth) — `[]` en session BFF web.

### Types (17)

#### `BridgeVerb`

```ts
type BridgeVerb = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
```

Verbe HTTP d'une action servie par le pont `api.request` — le pont n'en sert pas d'autre.

#### `ContractClientActions`

```ts
type ContractClientActions<C extends IRealtimeContract> = MethodsSeenBy<ContractSide<C, "serverMethods", ActionsMap>, "out"> & MethodsSeenBy<ContractSide<C, "clientMethods", ActionsMap>, "in">
```

Les méthodes du client vues par `NodefonySocket` : `serverMethods` qu'il appelle (`request`, résultat lu par `Jsonify`) et `clientMethods` qu'il implémente (`register`, paramètres lus par `Jsonify`). La socket range les deux sous un seul générique `Actions` : une méthode déclarée des deux côtés sous le même nom n'a pas de sens, le contrat ne la sépare pas.

#### `ContractClientEmit`

```ts
type ContractClientEmit<C extends IRealtimeContract> = ContractSide<C, "clientToServer", EventsMap>
```

Ce que le client ÉMET : `clientToServer`, tel que déclaré.

#### `ContractClientListen`

```ts
type ContractClientListen<C extends IRealtimeContract> = ReceivedEvents<ContractSide<C, "serverToClient", EventsMap>>
```

Ce que le client REÇOIT : `serverToClient`, lu par `Jsonify`.

#### `ContractClientRoutes`

```ts
type ContractClientRoutes<C extends IRealtimeContract> = ContractSide<C, "serverRoutes", RoutesMap>
```

Les routes du pont qu'un client appelle — `serverRoutes` du contrat, ou la carte permissive si le contrat n'en déclare pas.

#### `ContractRouteBody`

```ts
type ContractRouteBody<R extends RoutesMap, K extends string> = K extends DeclaredRouteKeys<R> ? RoutePart<R, K, "body"> : unknown
```

Le corps qu'accepte une route du pont : l'entrée de son schéma quand la clé `K` (`"<VERBE> <chemin>"`) appartient au contrat, `undefined` si la route déclarée n'a pas de corps, libre (`unknown`) hors contrat.

#### `ContractRouteParams`

```ts
type ContractRouteParams<R extends RoutesMap, K extends string, P extends string> = K extends DeclaredRouteKeys<R> ? "params" extends keyof R[K & keyof R] ? RoutePart<R, K & keyof R, "params"> : TemplateParams<P> : TemplateParams<P>
```

Les paramètres de chemin qu'accepte une route du pont : l'entrée de son schéma `params` quand la route déclarée en a un, sinon une valeur par `{nom}` du gabarit `P` — sous contrat comme hors contrat.

#### `ContractRouteQuery`

```ts
type ContractRouteQuery<R extends RoutesMap, K extends string> = K extends DeclaredRouteKeys<R> ? RoutePart<R, K, "query"> : unknown
```

La query qu'accepte une route du pont — pendant de `ContractRouteBody`.

#### `ContractRouteResult`

```ts
type ContractRouteResult<R extends RoutesMap, K extends string, T> = K extends DeclaredRouteKeys<R> ? R[K & keyof R] extends { result: infer X; } ? Jsonify<X> : unknown : T
```

Ce que rend une route du pont, lu par `Jsonify` (il a traversé le fil) quand `K` appartient au contrat ; sinon le `T` que l'appelant demande.

#### `Jsonify`

```ts
type Jsonify<T, D extends number = 10> = unknown extends T ? T : [ D ] extends [ never ] ? unknown : T extends Uint8Array ? T : T extends { toJSON(...args: never[]): infer R; } ? Jsonify<R, JsonifyDepth[D]> : T extends JsonPrimitive | void ? T : T extends bigint | symbol | (...args: never[]) => unknown ? never : T extends readonly unknown[] ? { [I in keyof T]: JsonifyItem<T[I], JsonifyDepth[D]>; } …
```

Le type qu'un pair REÇOIT quand l'autre a envoyé un `T` : ce que JSON en fait.

#### `PresencePairs`

```ts
type PresencePairs = readonly (string | number)[]
```

Identités et nombre d'onglets À PLAT : `[identité, onglets, identité, onglets, …]` — la forme sur le fil de `IPresenceEntry` (sans ses états).

#### `PresenceStates`

```ts
type PresenceStates<TState = unknown> = Readonly<Record<string, Readonly<Record<string, TState>>>>
```

États par identité puis par onglet (référence opaque → état) — champ FACULTATIF voisin des paires, présent seulement pour les identités qui ont un état. Un lecteur qui ne le connaît pas l'ignore ; jamais posé en 10.0 (ADR-0025 P4).

#### `RealtimeClosedReason`

```ts
type RealtimeClosedReason = "ended" | "evicted"
```

Motif d'un `realtime:closed`. Fermé exprès, comme `RealtimeDeniedReason` : le client doit pouvoir traiter tous les cas.

#### `RealtimeDeniedReason`

```ts
type RealtimeDeniedReason = "forbidden" | "limit" | "unknown" | "unavailable"
```

Motif d'un `realtime:denied`. Fermé exprès : le client doit pouvoir traiter TOUS les cas (le compilateur le lui rappelle), et un motif inventé côté serveur ne doit pas atteindre un écran qui ne sait pas le dire.

#### `RealtimePresenceFrame`

```ts
type RealtimePresenceFrame<TState = unknown> = IRealtimePresenceList<TState> | IRealtimePresenceDelta<TState> | IRealtimePresenceCount
```

Payload de la notification du protocole `realtime:presence` (ADR-0025 P2 bis) : qui est présent sur un canal à présence. Exactement une des trois formes — la discriminer par `changes !== undefined`, puis `members !== undefined`, sinon nombres seuls.

#### `RoutePathParamNames`

```ts
type RoutePathParamNames<P extends string> = P extends `${string}{${infer Name}}${infer Rest}` ? Name | RoutePathParamNames<Rest> : never
```

Noms des variables d'un gabarit de chemin — `"/a/{id}/b/{slug}"` → `"id" | "slug"` ; `never` sans variable. Même lecture que `routePathParams` (`runtime/routePath.ts`).

#### `RoutesMap`

```ts
type RoutesMap = Record<`${BridgeVerb} /${string}`, IContractRoute>
```

Carte des routes du pont : `"<VERBE> <chemin>"` → `IContractRoute`. Le chemin est celui de la route montée, préfixe du contrôleur compris.

---

[← Toutes les références d'API](../../)
