@sfinges/sf-conversation 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,226 @@
1
- # Temporary Holding Version
1
+ # @sfinges/sf-conversation
2
2
 
3
- 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.
3
+ Conversación interna por entidad: un hilo de mensajes en cada crédito, solicitud (y más adelante
4
+ garantía o lote), con menciones `@usuario`, no leídos y mensajes en vivo. TFB es el primer front que
5
+ la usa; está hecha para TFA, forms-ui y cualquier front de la plataforma en Angular 19.
6
+
7
+ El backend es la v2 de la API `notifications` del APIM `tfnbx-platform` (TFNBXNotifications): el
8
+ tenant sale del token, no va `idKatios` en la ruta, y el APIM revisa las opciones
9
+ `CONVERSATION_VIEW` y `CONVERSATION_POST` del perfil. Los mensajes en vivo llegan por Azure SignalR
10
+ Service en modo serverless, negociado por la misma API.
11
+
12
+ ## Reglas
13
+
14
+ 1. **No conoce al front.** El contexto entra por inputs, los datos por `CONVERSATION_SERVICE`, lo
15
+ nuevo en vivo por `CONVERSATION_REALTIME` (opcional) y los nombres por `CONVERSATION_DIRECTORY`.
16
+ No conoce `OptionsService` ni la burbuja de agentes.
17
+ 2. **Los permisos los decide el front** con `canView` y `canPost`. Ocultar es comodidad: quien hace
18
+ cumplir el permiso es el APIM.
19
+ 3. **Sin estética propia.** Usa componentes de PrimeNG y sus tokens (`--p-*`), así toma el tema del
20
+ front, en claro y en oscuro.
21
+ 4. **Texto con interpolación, nunca `[innerHTML]`.** Las menciones se resaltan con los datos de
22
+ `mentions`, partiendo el texto en trozos; no se interpreta HTML.
23
+ 5. **Carga perezosa.** El botón pide solo los no leídos de su entidad; el panel pide los mensajes al
24
+ abrirse, de 30 en 30 hacia atrás. En un listado, el front llama a `unreadSummary` una vez por
25
+ página, nunca una por fila.
26
+
27
+ ## Qué trae
28
+
29
+ | Pieza | Qué hace |
30
+ |---|---|
31
+ | `<lib-conversation-button>` | Botón "Conversación" con el número de no leídos. Abre el panel. Si `canView` es `false`, no se muestra. |
32
+ | `<lib-conversation-panel>` | `p-drawer` a la derecha: ~420 px en escritorio sin bloquear la pantalla; pantalla completa con "Volver" en el celular (menos de 768 px; el corte es de la librería, no el `isMobile()` de 992 px de TFB, porque sirve a varios fronts). |
33
+ | `CONVERSATION_SERVICE` | Puerto con las seis operaciones de la API. |
34
+ | `ConversationHttpService` | Implementación lista del puerto contra la v2, con la URL de `CONVERSATION_API_URL`. |
35
+ | `CONVERSATION_REALTIME` | Puerto opcional de mensajes en vivo. |
36
+ | `provideConversationRealtime()` | Implementación lista del canal en vivo (`ConversationSignalRService`) sobre Azure SignalR, con la misma URL. |
37
+ | `CONVERSATION_ACCESS_TOKEN` | Función que devuelve el token del front, para lo que no pasa por `HttpClient` (la negociación y el WebSocket). |
38
+ | `CONVERSATION_DIRECTORY` | Puerto para nombres de usuarios y búsqueda de menciones. |
39
+
40
+ Entradas de los dos componentes: `entityType`, `entityId`, `canView`, `canPost` (las cuatro
41
+ obligatorias). Salida: `openChange: boolean`. El panel además acepta `[(visible)]` si el front quiere
42
+ abrirlo con su propio botón.
43
+
44
+ ## Cómo se usa
45
+
46
+ ### 1. Proveer los puertos
47
+
48
+ El front pone tres cosas: la URL de la API, una función que devuelva su token y el directorio de
49
+ usuarios. Lo demás (el servicio HTTP y el canal en vivo) lo trae la librería. En el `app.config.ts`:
50
+
51
+ ```ts
52
+ import { provideHttpClient, withInterceptors } from '@angular/common/http';
53
+ import { ApplicationConfig, inject } from '@angular/core';
54
+ import {
55
+ CONVERSATION_ACCESS_TOKEN,
56
+ CONVERSATION_DIRECTORY,
57
+ provideConversationHttp,
58
+ provideConversationRealtime,
59
+ } from '@sfinges/sf-conversation';
60
+
61
+ export const appConfig: ApplicationConfig = {
62
+ providers: [
63
+ provideHttpClient(withInterceptors([authInterceptor])), // el interceptor pone el token
64
+ provideConversationHttp(environment.conversationApiUrl), // p. ej. https://<apim>/notifications/v2/
65
+ provideConversationRealtime(), // opcional: mensajes en vivo
66
+ {
67
+ provide: CONVERSATION_ACCESS_TOKEN,
68
+ useFactory: () => {
69
+ const jwt = inject(JwtTokenService);
70
+ return () => jwt.getToken(); // el token vigente, en cada llamada
71
+ },
72
+ },
73
+ { provide: CONVERSATION_DIRECTORY, useExisting: ConversationDirectoryAdapter },
74
+ ],
75
+ };
76
+ ```
77
+
78
+ `provideConversationHttp(url)` equivale a:
79
+
80
+ ```ts
81
+ { provide: CONVERSATION_API_URL, useValue: url },
82
+ { provide: CONVERSATION_SERVICE, useExisting: ConversationHttpService },
83
+ ```
84
+
85
+ `ConversationHttpService` **no pone el token ni la llave de suscripción**: los pone el interceptor
86
+ del front, como en las demás rutas v2. Un front que no llame al API directo (un mock, una fachada)
87
+ implementa `ConversationGateway` y lo provee en `CONVERSATION_SERVICE`.
88
+
89
+ `CONVERSATION_ACCESS_TOKEN` solo lo usa el canal en vivo, y se pide en cada conexión y reconexión.
90
+ Debe devolver el token vigente (sin `Bearer`), no uno guardado al arrancar. El interceptor de TFB
91
+ renueva el token antes de que venza, pero la negociación de SignalR no pasa por él: si el token
92
+ está por vencer, la función debe renovarlo antes de devolverlo (puede devolver una promesa).
93
+
94
+ ### 2. Montar el botón
95
+
96
+ ```html
97
+ <lib-conversation-button
98
+ entityType="LOAN"
99
+ [entityId]="loan.id"
100
+ [canView]="canViewConversation()"
101
+ [canPost]="canPostConversation()"
102
+ (openChange)="conversationOpen.set($event)" />
103
+ ```
104
+
105
+ `canView` y `canPost` salen de las opciones de botón del front (en TFB, `BUTTONS/CONVERSATION` y
106
+ `BUTTONS/CONVERSATION_POST`). Sin `canPost` el panel abre en solo lectura y lo dice.
107
+
108
+ `openChange` sirve para ocultar lo que estorbe mientras el panel está abierto. En TFB, la burbuja de
109
+ agentes de `sf-aiembedded` se oculta con `[hidden]` (no con `@if`, para no perder la conversación
110
+ abierta con el agente) y vuelve al cerrar el panel. Un front sin burbuja no hace nada. Si el front
111
+ destruye el panel abierto (navegó a otra pantalla), el panel emite `false` antes de irse.
112
+
113
+ ### 3. El canal en vivo (opcional)
114
+
115
+ `provideConversationRealtime()` registra `ConversationSignalRService` en `CONVERSATION_REALTIME`.
116
+ El front no adapta ningún hub:
117
+
118
+ - **Conexión.** Conecta al hub `conversations` de la misma API (`<URL>conversations`). El cliente de
119
+ SignalR llama solo a `POST conversations/negotiate`, con el token de `CONVERSATION_ACCESS_TOKEN` y
120
+ sin cookies (`withCredentials: false`), y sigue a la URL de Azure SignalR que devuelve. Conecta
121
+ cuando se abre el primer panel y se desconecta un minuto después de cerrarse el último. La
122
+ conexión y sus temporizadores corren fuera de la zona de Angular. Si falta el token o la URL, el
123
+ panel funciona sin canal.
124
+ - **Grupos.** Al abrirse, el panel se une a su conversación con
125
+ `POST conversations/{entityType}/{entityId}/join` y `{ connectionId }`, y sale con `.../leave` al
126
+ cerrarse o al cambiar de entidad. Estas dos sí van por `HttpClient`, con el interceptor del front.
127
+ Las de una misma conversación salen en orden (cerrar y reabrir rápido no las cruza), y dos
128
+ paneles sobre la misma entidad comparten la unión.
129
+ - **Eventos.** Reenvía el evento de cliente `CONVERSATION_MESSAGE`
130
+ (`{ idKatios, entityType, entityId, change, message }`). El panel filtra los de su entidad.
131
+ - **Reconexión.** Reintenta sin rendirse (0 s, 2 s, 10 s, 30 s y luego cada minuto) mientras haya un
132
+ panel abierto. Al reconectar cambia el `connectionId`: vuelve a unirse a los grupos abiertos y
133
+ después emite `reconnected$`, y el panel pide lo posterior al último mensaje que tiene
134
+ (`afterId`). Si llega una página completa, recarga la primera en vez de dejar un hueco.
135
+ - Si una de esas uniones falla (p. ej. un 503 del servicio), la reintenta con las mismas pausas
136
+ mientras el panel siga abierto, y vuelve a emitir `reconnected$` cuando entra.
137
+ - Una unión pedida mientras reconecta espera hasta 15 s; después falla y ese panel sigue sin canal.
138
+ - Si el servidor cierra la conexión sin dejar reconectar, conecta desde cero. Si la conexión
139
+ no alcanzó a durar un minuto, cada intento espera más, para no caer en un bucle.
140
+ - **Al volver a la pestaña** el panel siempre pide lo nuevo (`afterId`), con canal o sin él: así se
141
+ pone al día si el canal se cayó sin que se notara. **Sin canal**, o si la conexión o la unión
142
+ fallan, también lo pide al abrirse. No consulta cada pocos segundos: el límite de peticiones del
143
+ APIM es uno por usuario para todas las APIs.
144
+
145
+ Un front con otro transporte puede implementar `ConversationRealtime` (`events$`, `join`, `leave` y,
146
+ opcional, `reconnected$`) y proveerlo en `CONVERSATION_REALTIME` en lugar de
147
+ `provideConversationRealtime()`.
148
+
149
+ ### 4. Implementar el directorio
150
+
151
+ ```ts
152
+ @Injectable({ providedIn: 'root' })
153
+ export class ConversationDirectoryAdapter implements ConversationDirectory {
154
+ private readonly users = inject(BusinessUsersService); // la lista que el front ya carga
155
+ resolveUsers(refs: ConversationUserRef[]) { /* filtra la lista por tdoc/ndoc */ }
156
+ searchUsers(query: string) { /* filtra por nombre; query puede venir vacío */ }
157
+ }
158
+ ```
159
+
160
+ El token solo trae el documento y el servicio no guarda nombres. El panel pide cada usuario una sola
161
+ vez mientras está abierto, y muestra los primeros ocho resultados de la búsqueda. Sin directorio, el
162
+ panel muestra `tdoc ndoc` en vez del nombre y no ofrece menciones.
163
+
164
+ ## Comportamiento
165
+
166
+ - **Envío optimista.** El mensaje aparece de inmediato como "Enviando…" con un `clientMessageId`
167
+ (uuid). Si falla queda con el motivo, "Reintentar" (reenvía **el mismo id**, así el servicio no lo
168
+ duplica) y "Descartar". El envío no se corta al cerrar el panel ni al destruirlo.
169
+ - **No leídos del botón.** Se piden al montar el botón, al cambiar de entidad y, con el panel
170
+ cerrado, al volver a la pestaña o al reconectarse el canal en vivo. No cambian en vivo mientras el
171
+ panel está cerrado: el canal solo se une al grupo de la conversación con el panel abierto.
172
+ - **Leído.** Llama a `markRead` con el id más nuevo al abrir y al llegar un mensaje de otro con el
173
+ panel abierto. Si la pestaña está oculta, espera a que vuelva a estar visible. La marca "Mensajes
174
+ nuevos" queda antes del primer mensaje de otro posterior a `lastReadMessageId`.
175
+ - **Editar y borrar** solo lo propio (`mine`), con `canPost`. Borrar pide confirmación en el mismo
176
+ mensaje; el borrado es lógico y los demás ven "Mensaje eliminado". Editar cambia solo el texto: las
177
+ menciones del mensaje quedan como estaban en el servicio (si se borra un `@nombre`, deja de
178
+ resaltarse, pero la mención sigue).
179
+ - **Errores.** Se clasifican sin mostrar el texto técnico del backend: sin conexión (0), sesión
180
+ vencida (401), `NOT_AUTHOR` (403 del servicio), falta de permiso (otro 403, que puede ser una opción
181
+ recién asignada), mensaje inexistente (404), texto inválido (400), demasiadas solicitudes (429).
182
+ - **Teclado y foco.** Al abrir, el foco entra al panel: al campo de texto en escritorio, y al
183
+ título en el celular o en solo lectura. Escape cierra el panel (o primero la lista de menciones, la
184
+ edición o la confirmación de borrado). Enter envía y Shift+Enter agrega una línea (en pantallas
185
+ táctiles Enter es salto de línea y se envía con el botón). En la lista de menciones: flechas,
186
+ Enter o Tab para elegir. Al cerrar el panel el foco vuelve a donde estaba al abrirlo.
187
+
188
+ ### Qué asume del backend
189
+
190
+ - Fechas (`createdAt`, `editedAt`) en ISO 8601 **con zona** (`...Z`): el panel las muestra en la hora
191
+ local con `yyyy-MM-dd HH:mm`.
192
+ - `id` numérico y creciente: ordena y pagina por él.
193
+ - Cuerpos: `PUT conversations/messages/{id}` con `{ body }`; `PUT .../read` con
194
+ `{ lastReadMessageId }`; `POST conversations/unread` con `{ entityType, entityIds }`.
195
+ - En vivo: `POST conversations/negotiate` devuelve `{ url, accessToken }` del hub `conversations`
196
+ de Azure SignalR; `POST conversations/{entityType}/{entityId}/join` y `.../leave` con
197
+ `{ connectionId }`; el evento `CONVERSATION_MESSAGE` llega sin `mine`.
198
+ - El mensaje que llega por el canal en vivo no sabe quién lo mira, así que el panel **ignora su
199
+ `mine`**: un mensaje nuevo por el canal es de otro, salvo el eco de uno propio, que se reconoce por
200
+ `clientMessageId`. Un mensaje propio escrito desde otra pestaña llega sin el menú de editar hasta
201
+ la siguiente carga. Un evento `edited` o `deleted` de un mensaje que no está en pantalla se ignora.
202
+
203
+ ## Qué pone el front
204
+
205
+ - Angular `^19.2`, PrimeNG `^19.1.4` con su tema, `primeicons`, `@microsoft/signalr` y el provider de
206
+ animaciones (`provideAnimationsAsync()`, que `p-drawer` necesita). `@microsoft/signalr` hace
207
+ falta aunque el front no use el canal en vivo, porque la librería lo importa. Se probó con la 10;
208
+ el rango acepta 8 y 9, que tienen la misma API.
209
+ - `provideHttpClient` con el interceptor que pone el token, si usa `ConversationHttpService` o el
210
+ canal en vivo.
211
+ - `CONVERSATION_ACCESS_TOKEN`, si usa el canal en vivo.
212
+
213
+ ## Compilar y probar
214
+
215
+ No depende de las demás librerías del repo:
216
+
217
+ ```sh
218
+ npx ng build sf-conversation --configuration production
219
+ npx ng test sf-conversation --watch=false --browsers=ChromeHeadless
220
+ ```
221
+
222
+ Las pruebas cubren las utilidades (menciones, errores), el store con un puerto falso (primera
223
+ página, paginación, `afterId`, envío optimista y reintento con el mismo id, eventos en vivo) y el
224
+ canal en vivo con una conexión de SignalR falsa (token, unirse y salir en orden, eventos,
225
+ reconectar y volver a unirse, reintento de una reunión fallida, unión en curso durante la
226
+ reconexión, espera máxima, cierre del servidor, desconexión por inactividad, falta del token).