@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 +225 -2
- package/fesm2022/sfinges-sf-conversation.mjs +1807 -0
- package/fesm2022/sfinges-sf-conversation.mjs.map +1 -0
- package/index.d.ts +5 -0
- package/lib/components/conversation-button/conversation-button.component.d.ts +36 -0
- package/lib/components/conversation-composer/conversation-composer.component.d.ts +48 -0
- package/lib/components/conversation-panel/conversation-panel.component.d.ts +88 -0
- package/lib/gateways/conversation-access-token.port.d.ts +13 -0
- package/lib/gateways/conversation-directory.port.d.ts +24 -0
- package/lib/gateways/conversation-http.service.d.ts +31 -0
- package/lib/gateways/conversation-realtime.port.d.ts +29 -0
- package/lib/gateways/conversation-signalr.service.d.ts +110 -0
- package/lib/gateways/conversation.port.d.ts +38 -0
- package/lib/models/conversation.model.d.ts +73 -0
- package/lib/state/conversation-user-names.service.d.ts +22 -0
- package/lib/state/conversation.store.d.ts +86 -0
- package/lib/utils/conversation-error.util.d.ts +8 -0
- package/lib/utils/mention.util.d.ts +21 -0
- package/lib/utils/uuid.util.d.ts +5 -0
- package/package.json +27 -3
- package/public-api.d.ts +16 -0
package/README.md
CHANGED
|
@@ -1,3 +1,226 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @sfinges/sf-conversation
|
|
2
2
|
|
|
3
|
-
|
|
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).
|