@acropole/skills 1.5.0 → 1.6.1

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.
@@ -1,6 +1,6 @@
1
1
  # Catálogo de API — @trismegisto/spine
2
2
 
3
- > **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills.
3
+ > **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 3.0.1, a cada `npm run sync` do @acropole/skills.
4
4
  > Gerado do código-fonte do `@trismegisto/spine`. Confira a versão instalada no `package.json` do pacote em `node_modules`.
5
5
 
6
6
  Uma seção por ponto de entrada (o `import` exato). Dentro dela: componentes (seletor, inputs/outputs),
@@ -40,7 +40,7 @@ Wrapper fino sobre `HermesThemeService.density`/`setDensity` (já persistido em
40
40
 
41
41
  #### `SpinePreferencesService` · `providedIn: root`
42
42
 
43
- Preferências do usuário que não são de tema (tema/família/densidade continuam no `HermesThemeService`; modo do menu lateral no `HermesSidebarService`): fuso horário, idioma e o interruptor dos atalhos de tecla única (WCAG 2.1.4) do `HermesShortcutService`.
43
+ Preferências do usuário que não são de tema (tema/família/densidade continuam no `HermesThemeService`; modo do menu lateral no `HermesSidebarService`): fuso horário, idioma, relógio de 12/24 h e primeiro dia da semana (`HermesI18nService.setRegionalFormat`), tamanho do texto (`HermesZoomService.setTextScale`), movimento (`HermesMotionService.setPreference`) e o interruptor dos atalhos de tecla única (WCAG 2.1.4) do `HermesShortcutService`.
44
44
 
45
45
  - `readonly appLanguage` — Idioma com que o app subiu (`provideHermesI18n`) — vale quando a pessoa não escolheu nenhum.
46
46
  - `readonly timeZone: signal(…)` — Fuso escolhido (IANA, ex.: "America/Sao_Paulo"). Vazio = o do navegador.
@@ -48,8 +48,25 @@ Preferências do usuário que não são de tema (tema/família/densidade continu
48
48
  - `readonly effectiveTimeZone: computed(…)` — O fuso que vale de fato: o escolhido ou, sem escolha, o do navegador.
49
49
  - `readonly language: signal(…)` — Idioma escolhido (BCP 47: `pt-BR`, `en`, `es`). Vazio = o padrão do app.
50
50
  - `readonly characterKeys: signal(…)` — Atalhos de tecla única (`?`, `G H`) ligados — WCAG 2.1.4. Guardado por app (`'on'`/`'off'`); sem escolha salva, vale o padrão do `HermesShortcutService` (`provideHermesShortcuts`).
51
+ - `readonly textScale: signal(…)` — Tamanho do texto (1 = 100%; os oferecidos em `HERMES_TEXT_SCALES`).
52
+ - `readonly motion: signal<HermesMotionPreference>(…)` — Movimento: `system` segue o `prefers-reduced-motion`; `reduce` sempre reduz; `full` nunca.
53
+ - `readonly hourCycle: signal<SpineHourCyclePreference>(…)` — Relógio: `h23` (24 horas), `h12` (12 horas) ou vazio (o do idioma).
54
+ - `readonly weekStart: signal<SpineWeekStartPreference>(…)` — Primeiro dia da semana (0 = domingo, 1 = segunda) ou `null` (o do idioma).
55
+ - `readonly idleMinutes: signal(…)` — Encerrar a sessão depois de tantos minutos sem uso (0 = nunca). Os limites do app (`SpineFeatures.idleTimeout`) são aplicados por quem usa o valor (`SpineIdleService`), não aqui.
56
+ - `readonly startPage: signal<SpineStartPagePreference>(…)` — Tela que abre depois do login.
57
+ - `readonly noticeTypes: signal<Readonly<Record<string, boolean>>>(…)` — Tipos de aviso que a pessoa ligou/desligou (`id` → ligado); tipo ausente segue o `defaultEnabled` dele.
58
+ - `readonly browserNotices: signal(…)` — Aviso do navegador (Notification API) quando a aba está em segundo plano.
51
59
  - `setCharacterKeys(enabled: boolean): void` — Liga/desliga os atalhos de tecla única na hora, guarda e avisa as outras abas.
52
60
  - `setLanguage(value: string): void` — Troca o idioma da lib e do spine na hora, guarda e avisa as outras abas. Vazio = padrão do app.
61
+ - `setTextScale(value: number): void` — Tamanho do texto na hora (1 = 100%), guarda e avisa as outras abas.
62
+ - `setMotion(value: HermesMotionPreference): void` — Movimento na hora (`system`/`reduce`/`full`), guarda e avisa as outras abas.
63
+ - `setHourCycle(value: SpineHourCyclePreference): void` — Relógio na hora (`h23`/`h12`; vazio = o do idioma), guarda e avisa as outras abas.
64
+ - `setWeekStart(value: SpineWeekStartPreference): void` — Primeiro dia da semana na hora (0 = domingo, 1 = segunda; `null` = o do idioma), guarda e avisa.
65
+ - `setIdleMinutes(value: number): void` — Minutos sem uso até encerrar a sessão (0 = nunca), guarda e avisa as outras abas.
66
+ - `setStartPage(value: SpineStartPagePreference): void` — Tela inicial depois do login, guarda e avisa as outras abas.
67
+ - `setNoticeType(id: string, enabled: boolean): void` — Liga/desliga um tipo de aviso, guarda e avisa as outras abas.
68
+ - `setNoticeTypes(value: Readonly<Record<string, boolean>>): void` — Troca o mapa inteiro de tipos de aviso (restaurar, sincronização com a conta).
69
+ - `setBrowserNotices(enabled: boolean): void` — Liga/desliga o aviso do navegador, guarda e avisa as outras abas (a permissão é pedida por quem chama).
53
70
  - `setTimeZone(value: string): void`
54
71
  - `supportedTimeZones(): string[]` — Todos os fusos IANA que o navegador conhece (vazio em navegador antigo).
55
72
 
@@ -61,6 +78,7 @@ Favorites and recently visited pages, shared by every consumer in the app (page
61
78
  - `readonly recents: Signal (somente leitura)`
62
79
  - `isFavorite(id: string | null | undefined): boolean`
63
80
  - `toggleFavorite(item: QuickAccessItem): void`
81
+ - `setFavorites(items: readonly unknown[]): void` — Troca a lista de favoritos inteira (sincronização com a conta). Itens inválidos ou repetidos são descartados.
64
82
  - `recordVisit(item: QuickAccessItem): void`
65
83
  - `forgetRecent(id: string): void`
66
84
 
@@ -71,6 +89,8 @@ Chaves de `localStorage` do shell por usuário: `<clientId>_<lista>_<sub>`, com
71
89
  - `userId(): string` — `sub` do token da sessão (só leitura do payload); vazio sem sessão.
72
90
  - `key(list: SpineUserStorageKey): string` — Chave de `localStorage` da lista para o usuário atual.
73
91
  - `clearHistory(): void` — Apaga buscas recentes e páginas recentes do usuário (o atual ou o último visto). Favoritos ficam.
92
+ - `clear(list: SpineUserStorageKey): void` — Apaga uma lista do usuário atual (Configurações › Dados do navegador): a chave dele, e também a antiga sem usuário. Quem guarda a lista em memória relê (`onChange`).
93
+ - `count(list: SpineUserStorageKey): number` — Quantos itens a lista do usuário atual tem guardados (0 sem nada ou com valor ilegível).
74
94
 
75
95
  ### Funções
76
96
 
@@ -91,6 +111,7 @@ Chaves de `localStorage` do shell por usuário: `<clientId>_<lista>_<sub>`, com
91
111
  - `SPINE_CONFIG`: `InjectionToken<SpineConfig>`
92
112
  - `SPINE_DEFAULT_LOGO`: `'assets/images/logo.svg'` — Convenção quando o app não configura `logo`: `src/assets/images/logo.svg` servido em `assets/images/`.
93
113
  - `APP_PACKAGE_INFO`: `InjectionToken<PackageInfo>`
114
+ - `SPINE_IDLE_OPTIONS`: `readonly number[]` — Minutos de inatividade oferecidos em "Encerrar por inatividade" (0 = nunca).
94
115
  - `SPINE_ADMIN_API`: `InjectionToken<string>` — Base da API do argos-admin-server (ex.: `https://exemplo.com.br/argos/admin/api`) — recursos do próprio usuário (`/me/*`, hoje os tokens de aplicação) que o painel de configurações usa. Quem chama `provideAutoService({ adminApi })` já fornece este token (é a…
95
116
  - `SPINE_USER_STORAGE_KEYS` — Listas do shell guardadas no navegador, por usuário.
96
117
  - `SPINE_NEWS`: `InjectionToken<readonly (readonly SpineNewsItem[])[]>` — Multi: cada chamada de `provideSpineNews` contribui com uma lista.
@@ -185,6 +206,70 @@ interface SpineConfig {
185
206
  * Padrão: `isDevMode()`. Apps com build de produção em homologação passam
186
207
  * `!environment.production` (ou equivalente) para mostrá-la fora de produção. */
187
208
  technicalDocs?: boolean;
209
+ /**
210
+ * Recursos opcionais do painel de configurações (todos desligados sem configuração). Ver `SpineFeatures`.
211
+ */
212
+ features?: SpineFeatures;
213
+ }
214
+ ```
215
+
216
+ #### `SpineMcpServer` (interface)
217
+
218
+ Um servidor MCP do app, oferecido em Sessões › "Conectar um agente de IA".
219
+
220
+ ```ts
221
+ interface SpineMcpServer {
222
+ /** Nome da entrada no `.mcp.json` (ex.: `app`). Letras, números, `-` e `_`. */
223
+ name: string;
224
+ /** URL do MCP. Relativa (`/app/mcp`) é resolvida contra a origem da página. */
225
+ url: string;
226
+ /** Rótulo exibido (padrão: `name`). */
227
+ label?: string;
228
+ /** Valor de `x-mcp-scopes` no modo só leitura. Omitido: o header não vai (o MCP já é só leitura sem ele). */
229
+ readScopes?: string;
230
+ /** Valor de `x-mcp-scopes` no modo leitura e escrita (ex.: `deploy.*`). Omitido: o servidor só é oferecido para leitura. */
231
+ writeScopes?: string;
232
+ }
233
+ ```
234
+
235
+ #### `SpineNoticeType` (interface)
236
+
237
+ Tipo de aviso que o app emite (`SpineNoticesService.notify`), ligável/desligável em Configurações › Notificações.
238
+
239
+ ```ts
240
+ interface SpineNoticeType {
241
+ /** Identificador estável (ex.: `deploy-concluido`): é a chave da preferência salva. */
242
+ id: string;
243
+ label: string;
244
+ description?: string;
245
+ /** Ligado enquanto a pessoa não escolher. Padrão: `true`. */
246
+ defaultEnabled?: boolean;
247
+ }
248
+ ```
249
+
250
+ #### `SpineFeatures` (interface)
251
+
252
+ Recursos opcionais do painel de configurações. Cada um só aparece quando ligado aqui (e, quando depende do Argos, com a API da conta disponível — `AUTH_CONFIG` com `authority`/`realmId`).
253
+
254
+ ```ts
255
+ interface SpineFeatures {
256
+ /** Sessões › "Conectar um agente de IA": gera um token de aplicação e a configuração MCP pronta para colar.
257
+ * Precisa de `SPINE_ADMIN_API` (tokens de aplicação). */
258
+ aiAgent?: { servers: readonly SpineMcpServer[] };
259
+ /** MFA › "Atividade da conta": entradas e tentativas que falharam desta conta (últimos 90 dias, API da conta). */
260
+ accountActivity?: boolean;
261
+ /** Conta › "Encerrar por inatividade". `true` = opções padrão; `{ min, max }` limita os minutos (com `max` a
262
+ * opção "Nunca" some e a escolha é limitada a ele). */
263
+ idleTimeout?: boolean | { min?: number; max?: number };
264
+ /** Conta › "Tela inicial": início, um favorito ou a última tela visitada, aplicada depois do login. */
265
+ startPage?: boolean;
266
+ /** Conta › "Crachá padrão": o nível de acesso com que o login entra (guardado no Argos, vale nos outros navegadores). */
267
+ defaultBadge?: boolean;
268
+ /** Configurações › Notificações: os tipos de aviso que o app emite e o aviso do navegador com a aba em segundo plano. */
269
+ notices?: { types: readonly SpineNoticeType[] };
270
+ /** Preferências (aparência, região, acessibilidade, favoritos, tela inicial…) guardadas também na conta do Argos,
271
+ * para acompanharem a pessoa em qualquer navegador. Sem a API da conta, ficam só no navegador. */
272
+ accountPreferences?: boolean;
188
273
  }
189
274
  ```
190
275
 
@@ -230,6 +315,30 @@ interface PackageInfo {
230
315
  }
231
316
  ```
232
317
 
318
+ #### `SpineStartPagePreference` (type)
319
+
320
+ Tela inicial depois do login: `home` (a padrão do app), `last` (a última visitada) ou `fav:<id>` (um favorito, pelo `id` do `SpineQuickAccessService`).
321
+
322
+ ```ts
323
+ type SpineStartPagePreference = 'home' | 'last' | `fav:${string}`;
324
+ ```
325
+
326
+ #### `SpineHourCyclePreference` (type)
327
+
328
+ Relógio escolhido em Região: vazio = o do idioma.
329
+
330
+ ```ts
331
+ type SpineHourCyclePreference = '' | TimeHourCycle;
332
+ ```
333
+
334
+ #### `SpineWeekStartPreference` (type)
335
+
336
+ Primeiro dia da semana escolhido em Região: `null` = o do idioma.
337
+
338
+ ```ts
339
+ type SpineWeekStartPreference = Weekday | null;
340
+ ```
341
+
233
342
  #### `QuickAccessItem` (interface)
234
343
 
235
344
  A page remembered by the shell, either as a favorite or as a recent visit.
@@ -345,7 +454,7 @@ interface SpineI18nConfig {
345
454
 
346
455
  ## `@trismegisto/spine/audit`
347
456
 
348
- @trismegisto/spine/audit — a tela de Auditoria (leitura de `audit.events` do argos admin-server), a mesma para o painel central (`scope="admin"`) e para o auto-serviço (`scope="client"` + `clientId`).
457
+ @trismegisto/spine/audit — as telas de auditoria do argos admin-server, as mesmas para o painel central (`scope="admin"`) e para o auto-serviço (`scope="client"` + `clientId`): Ações (`SpineAuditComponent`, leitura de `audit.events`) e Tentativas de login (`SpineLoginAttemptsComponent`, leitura de `auth.auth_attempts`).
349
458
 
350
459
  ### Componentes e diretivas
351
460
 
@@ -376,6 +485,17 @@ Card de ranking da Auditoria ("Operações", "Usuários", "Por aplicação") com
376
485
  | `picked` | output | `AuditTopRow` | | |
377
486
  | `offsetChange` | output | `number` | | Novo `offset` pedido (anterior/próxima). |
378
487
 
488
+ #### `spine-login-attempts` — `SpineLoginAttemptsComponent`
489
+
490
+ A tela de Tentativas de login (`auth.auth_attempts` do argos): quando, quem (usuário ou o que foi digitado), de qual IP e navegador, por qual método, com que resultado e, nas falhas, o motivo. Só leitura, com filtros e paginação no servidor. A mesma no painel central e no auto-serviço; só muda o escopo: - `scope="client"` + `clientId`: `{adminApi}/auto-service/:clientId/attempts`, só as tentativas na aplicação do client (recorte feito no servidor) -- sem as colunas Realm e Client; - `scope="adm…
491
+
492
+ | Nome | Tipo | Tipo TS | Padrão | Descrição |
493
+ |---|---|---|---|---|
494
+ | `scope` | input (obrigatório) | `SpineAuditScope` | | `admin` = painel central (todos os realms); `client` = só as tentativas na aplicação do `clientId`. |
495
+ | `clientId` | input | `string \| null` | `null` | Obrigatório com `scope="client"`. |
496
+ | `realmId` | input | `string \| null` | `null` | Só no escopo `admin`: filtra por realm (vazio = todos). |
497
+ | `adminApi` | input | `string \| null` | `null` | Base do argos admin-server; sem ele, vale o `SPINE_ADMIN_API`. |
498
+
379
499
  ### Serviços e classes
380
500
 
381
501
  #### `SpineAuditService` · `providedIn: root`
@@ -388,6 +508,7 @@ HTTP da auditoria (só leitura), igual nos dois escopos: cada método recebe a `
388
508
  - `trace(base: string, traceId: string, occurredAt?: string | null): Promise<AuditTrace>` — `occurredAt` (opcional) = o do evento de origem: o servidor limita a busca da cadeia a ±1 dia dele.
389
509
  - `stats(base: string, query: AuditQuery, opts: { tops?: boolean } = {}): Promise<AuditStats>` — Resumo (KPIs + linha do tempo). `tops: false` pula os rankings — a tela os pagina por `tops()`.
390
510
  - `tops(base: string, kind: AuditTopKind, query: AuditQuery, page: { offset: number; limit: number }): Promise<AuditTopPage>` — Um ranking paginado (`apps` \| `operations` \| `users`) com os mesmos filtros/janela do resumo.
511
+ - `loginAttempts(url: string, query: LoginAttemptQuery): Promise<LoginAttemptList>` — Uma página das tentativas de login (`url` = `loginAttemptsUrl`), mais recentes primeiro, com o total do filtro.
391
512
 
392
513
  #### `AuditCursorPager`
393
514
 
@@ -407,6 +528,11 @@ Paginação numerada ("página N de M") sobre a lista por cursor (keyset) do ser
407
528
  - `function worstOutcome(outcomes: readonly (string | null | undefined)[]): AuditOutcome` — Pior resultado (denied > failure > success) — o `outcome` de uma ação.
408
529
  - `function buildSpanTimeline(items: readonly AuditEvent[]): AuditSpanTimeline` — Spans de um trace → linha do tempo: ordem em árvore (pai antes dos filhos, irmãos por início), com profundidade pela cadeia parent_span_id → span_id. Span cujo pai não está na lista (de fora do escopo, fora da janela) vira raiz. Fim do span = início + duratio…
409
530
  - `function auditErrorCode(err: unknown): { status: number; code: string; detail: string }` — Código de erro do envelope do admin-server (`{ error, detail }`), quando houver.
531
+ - `function loginAttemptsUrl(adminApi: string | null | undefined, scope: SpineAuditScope, clientId?: string | null): string | null` — Endpoint das tentativas no escopo: `{adminApi}/admin/attempts` (todos os realms, operação `admin:attempts:list`) ou `{adminApi}/auto-service/:clientId/attempts` (só as do client, recorte feito no servidor).
532
+ - `function loginAttemptParams(query: LoginAttemptQuery): HttpParams` — Query string da listagem: só os campos com valor.
533
+ - `function isoDay(d: Date): string` — Dia local AAAA-MM-DD (o valor do `hm-date-range-picker`).
534
+ - `function defaultAttemptsPeriod(today = new Date()): DateRange` — Período padrão: os últimos 7 dias, hoje incluído.
535
+ - `function attemptsPeriodToWindow(range: DateRange | null): { from?: string; to?: string }` — Dias locais do período -> janela ISO [início do primeiro dia, início do dia seguinte ao último).
410
536
 
411
537
  ### Constantes e tokens
412
538
 
@@ -418,9 +544,14 @@ Paginação numerada ("página N de M") sobre a lista por cursor (keyset) do ser
418
544
  - `AUDIT_PERIOD_MS`: `Readonly<Record<AuditPeriod, number>>`
419
545
  - `AUDIT_MAX_WINDOW_MS` — Janela máxima aceita pelo servidor (acima: 400 `range_too_large`).
420
546
  - `AUDIT_MAX_PAGE_SIZE`: `200` — Maior `limit` aceito por `GET .../audit/events`.
547
+ - `LOGIN_ATTEMPT_METHODS` — Métodos gravados pelo argos auth-server em `auth.auth_attempts.method`.
548
+ - `LOGIN_ATTEMPT_RESULTS`
549
+ - `LOGIN_ATTEMPT_REASONS` — Códigos de `auth.auth_attempts.reason` que a tela traduz; código desconhecido aparece como veio.
421
550
  - `AUDIT_PAGE_SIZE`: `10` — Eventos por página da tabela, de saída (o servidor aceita até 200 — `AUDIT_MAX_PAGE_SIZE`).
422
551
  - `AUDIT_PAGE_SIZES`: `readonly number[]` — Opções do seletor de eventos por página (todas dentro do `limit` máximo do servidor).
423
552
  - `AUDIT_AUTO_REFRESH_MS`: `30_000` — Intervalo da atualização automática (opcional, desligada por padrão).
553
+ - `LOGIN_ATTEMPTS_PAGE_SIZE`: `50` — Tentativas por página, de saída (o servidor aceita até 200).
554
+ - `LOGIN_ATTEMPTS_PAGE_SIZES`: `readonly number[]`
424
555
 
425
556
  ### Tipos
426
557
 
@@ -732,6 +863,75 @@ interface AuditSpanTimeline {
732
863
  }
733
864
  ```
734
865
 
866
+ #### `LoginAttemptMethod` (type)
867
+
868
+ ```ts
869
+ type LoginAttemptMethod = typeof LOGIN_ATTEMPT_METHODS[number];
870
+ ```
871
+
872
+ #### `LoginAttemptResult` (type)
873
+
874
+ ```ts
875
+ type LoginAttemptResult = typeof LOGIN_ATTEMPT_RESULTS[number];
876
+ ```
877
+
878
+ #### `LoginAttemptReason` (type)
879
+
880
+ ```ts
881
+ type LoginAttemptReason = typeof LOGIN_ATTEMPT_REASONS[number];
882
+ ```
883
+
884
+ #### `LoginAttempt` (interface)
885
+
886
+ Uma tentativa de login (`GET /admin/attempts` ou `/auto-service/:clientId/attempts`). Datas em ISO UTC.
887
+
888
+ ```ts
889
+ interface LoginAttempt {
890
+ id: string;
891
+ created_at: string;
892
+ realm_id: string;
893
+ realm_name: string | null;
894
+ client_id: string | null;
895
+ client_name: string | null;
896
+ user_id: string | null;
897
+ user_username: string | null;
898
+ user_name: string | null;
899
+ user_email: string | null;
900
+ /** Identificador digitado no login local (pode não ser de usuário nenhum). */
901
+ username: string | null;
902
+ method: LoginAttemptMethod;
903
+ result: LoginAttemptResult;
904
+ reason: string | null;
905
+ ip: string | null;
906
+ user_agent: string | null;
907
+ }
908
+ ```
909
+
910
+ #### `LoginAttemptList` (interface)
911
+
912
+ ```ts
913
+ interface LoginAttemptList { items: LoginAttempt[]; total: number; page: number; limit: number; }
914
+ ```
915
+
916
+ #### `LoginAttemptQuery` (interface)
917
+
918
+ ```ts
919
+ interface LoginAttemptQuery {
920
+ page: number;
921
+ limit: number;
922
+ /** ISO-8601. */
923
+ from?: string;
924
+ to?: string;
925
+ /** Só no escopo `admin` (no `client` o servidor usa o realm do client). */
926
+ realm?: string;
927
+ user?: string;
928
+ ip?: string;
929
+ method?: LoginAttemptMethod;
930
+ result?: LoginAttemptResult;
931
+ reason?: string;
932
+ }
933
+ ```
934
+
735
935
  #### `AuditTopRow` (interface)
736
936
 
737
937
  Uma linha de ranking já pronta para mostrar (o card não sabe de que tipo é).
@@ -770,6 +970,10 @@ interface AuditTopRow {
770
970
  - `getRouterTree(clientId: string)` — Árvore do menu (header → … → página) com os router_ids de cada nó, já na ordem gravada.
771
971
  - `reorderRouters(clientId: string, groups: RouterOrderGroup[])` — Grava a ordem de UM nível (irmãos): o índice do grupo é a ordem; cada grupo escreve `${type}_order` em todos os seus routers. Vale também para routers de template (ordem é do client).
772
972
  - `getGroups(clientId: string)`
973
+ - `getGroupTypes(clientId: string)` — Tipos (crachás) do realm; `assignable: false` no Administrador, que é só do grupo de administração (painel central).
974
+ - `createGroup(clientId: string, body: AutoServiceGroupCreate)`
975
+ - `updateGroup(clientId: string, groupId: string, body: AutoServiceGroupUpdate)`
976
+ - `deleteGroup(clientId: string, groupId: string)`
773
977
  - `getGroupMembers(clientId: string, groupId: string)`
774
978
  - `addGroupMember(clientId: string, groupId: string, userId: string, role: string | null)`
775
979
  - `updateGroupMemberRole(clientId: string, groupId: string, userId: string, role: string | null)`
@@ -784,8 +988,12 @@ interface AuditTopRow {
784
988
  - `getApps(clientId: string)`
785
989
  - `createApp(clientId: string, body: { name: string; allowed_grants?: string[] })`
786
990
  - `updateApp(clientId: string, appId: string, body: any)`
991
+ - `rotateAppSecret(clientId: string, appId: string)` — Gera um segredo novo para a aplicação (o anterior para de valer na hora). A resposta traz o segredo uma única vez.
787
992
  - `deleteApp(clientId: string, appId: string)`
788
993
  - `getAppOperations(clientId: string, appId: string)`
994
+ - `getAppTokens(clientId: string, appId: string)`
995
+ - `createAppToken(clientId: string, appId: string, body: AutoServiceAppTokenCreate)` — Cria o token (e o consumer dele, com as permissões escolhidas). A resposta traz o valor uma única vez.
996
+ - `revokeAppToken(clientId: string, appId: string, tokenId: string)` — Revoga: o token para de valer na hora e continua na lista como revogado.
789
997
  - `getAppConsumers(clientId: string, appId: string)`
790
998
  - `createAppConsumer(clientId: string, appId: string, groupId: string)`
791
999
  - `deleteAppConsumer(clientId: string, consumerId: string)`
@@ -804,9 +1012,10 @@ interface AuditTopRow {
804
1012
  - `AUTO_SERVICE_APPS_TEMPLATE_ROUTER_ID`: `'ad100002-0000-4000-8000-000000000001'`
805
1013
  - `AUTO_SERVICE_CLIENT_TEMPLATE_ROUTER_ID`: `'ad100003-0000-4000-8000-000000000001'`
806
1014
  - `AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID`: `'ad100004-0000-4000-8000-000000000001'`
1015
+ - `AUTO_SERVICE_LOGIN_ATTEMPTS_TEMPLATE_ROUTER_ID`: `'ad100005-0000-4000-8000-000000000001'`
807
1016
  - `AUTO_SERVICE_HOME_TEMPLATE_ROUTER_ID`: `'6a9a13db-f31b-494e-b51c-79af0ac28b60'`
808
- - `AUTO_SERVICE_SCREENS`: `Readonly<Record<'home' | 'groups' | 'apps' | 'client' | 'audit', () => Promise<Type<unknown>>>>` — As 5 telas do auto-serviço, carregadas sob demanda. Cada `import()` relativo vira um chunk próprio no FESM publicado (`trismegisto-spine-auto-service-<tela>-<hash>.mjs`), que o bundler do app mantém fora do carregamento inicial. Não exporte as telas no `publi…
809
- - `AUTO_SERVICE_DOCUMENTS`: `Readonly<Record<keyof typeof AUTO_SERVICE_SCREENS, RouteDocument>>` — Documentação das 5 telas (botão de documentação da barra da página e índice "Documentação do sistema"): o manual de uso (`load`) e a especificação técnica (`loadTechnical`, só com `SpineConfig.technicalDocs`). O Markdown fica em módulos `.ts` próprios em `./d…
1017
+ - `AUTO_SERVICE_SCREENS`: `Readonly<Record<'home' | 'groups' | 'apps' | 'client' | 'audit' | 'loginAttempts', () => Promise<Type<unknown>>>>` — As 6 telas do auto-serviço, carregadas sob demanda. Cada `import()` relativo vira um chunk próprio no FESM publicado (`trismegisto-spine-auto-service-<tela>-<hash>.mjs`), que o bundler do app mantém fora do carregamento inicial. Não exporte as telas no `publi…
1018
+ - `AUTO_SERVICE_DOCUMENTS`: `Readonly<Record<keyof typeof AUTO_SERVICE_SCREENS, RouteDocument>>` — Documentação das 6 telas (botão de documentação da barra da página e índice "Documentação do sistema"): o manual de uso (`load`) e a especificação técnica (`loadTechnical`, só com `SpineConfig.technicalDocs`). O Markdown fica em módulos `.ts` próprios em `./d…
810
1019
 
811
1020
  ### Tipos
812
1021
 
@@ -854,6 +1063,93 @@ Um item da ordem nova de um nível (`PATCH /routers/reorder`).
854
1063
  interface RouterOrderGroup { type: RouterOrderType; router_ids: string[] }
855
1064
  ```
856
1065
 
1066
+ #### `AutoServiceGroup` (interface)
1067
+
1068
+ Grupo do projeto do client (`GET /groups`). O grupo de administração do projeto (`is_admin`) é gerido só no painel central e o servidor não o devolve aqui; servidor antigo ainda devolve com `is_admin: true` e as telas descartam.
1069
+
1070
+ ```ts
1071
+ interface AutoServiceGroup {
1072
+ id: string;
1073
+ name: string;
1074
+ description: string | null;
1075
+ enabled: boolean;
1076
+ is_admin?: boolean;
1077
+ type: { id: string; name: string; level: number } | null;
1078
+ }
1079
+ ```
1080
+
1081
+ #### `AutoServiceGroupType` (interface)
1082
+
1083
+ Tipo de grupo (crachá) do realm (`GET /group-types`).
1084
+
1085
+ ```ts
1086
+ interface AutoServiceGroupType { id: string; name: string; level: number; assignable: boolean }
1087
+ ```
1088
+
1089
+ #### `AutoServiceGroupCreate` (interface)
1090
+
1091
+ Corpo de `POST /groups` (o projeto é sempre o do client).
1092
+
1093
+ ```ts
1094
+ interface AutoServiceGroupCreate { name: string; type_id: string; description?: string }
1095
+ ```
1096
+
1097
+ #### `AutoServiceGroupUpdate` (interface)
1098
+
1099
+ Corpo de `PUT /groups/:groupId`; do grupo de administração só `description`. `null` apaga a descrição.
1100
+
1101
+ ```ts
1102
+ interface AutoServiceGroupUpdate { name?: string; type_id?: string; description?: string | null; enabled?: boolean }
1103
+ ```
1104
+
1105
+ #### `AutoServiceApp` (interface)
1106
+
1107
+ Aplicação (client_credentials) do projeto do client (`GET /apps`).
1108
+
1109
+ ```ts
1110
+ interface AutoServiceApp {
1111
+ id: string;
1112
+ name: string;
1113
+ enabled: boolean;
1114
+ allowed_grants?: string[] | null;
1115
+ [key: string]: unknown;
1116
+ }
1117
+ ```
1118
+
1119
+ #### `AutoServiceAppToken` (interface)
1120
+
1121
+ Token de API (`x-api-token`) de uma aplicação (`GET /apps/:appId/tokens`). O valor só vem na criação; aqui fica o começo dele (`token_prefix`) para reconhecer. Cada token é também um consumer (`consumer_id`) com as permissões dele.
1122
+
1123
+ ```ts
1124
+ interface AutoServiceAppToken {
1125
+ id: string;
1126
+ consumer_id: string;
1127
+ name: string;
1128
+ description: string | null;
1129
+ token_prefix: string;
1130
+ expires_at: string;
1131
+ revoked_at: string | null;
1132
+ created_at: string;
1133
+ last_used_at: string | null;
1134
+ }
1135
+ ```
1136
+
1137
+ #### `AutoServiceAppTokenCreate` (interface)
1138
+
1139
+ Corpo de `POST /apps/:appId/tokens`: validade ISO (até 365 dias) e as operações protected liberadas ao token.
1140
+
1141
+ ```ts
1142
+ interface AutoServiceAppTokenCreate { name: string; description?: string; expires_at: string; operation_ids?: string[] }
1143
+ ```
1144
+
1145
+ #### `AutoServiceAppTokenCreated` (interface)
1146
+
1147
+ Resposta de `POST /apps/:appId/tokens`: `token` é o valor cru, devolvido uma única vez.
1148
+
1149
+ ```ts
1150
+ interface AutoServiceAppTokenCreated { id: string; consumer_id: string; name: string; token: string }
1151
+ ```
1152
+
857
1153
  #### `AutoServiceClient` (interface)
858
1154
 
859
1155
  ```ts
@@ -1001,7 +1297,19 @@ _Sem inputs/outputs._
1001
1297
 
1002
1298
  #### `spine-settings-panel` — `SettingsPanelComponent`
1003
1299
 
1004
- Painel de configurações do shell (substitui as telas do antigo módulo "Sistema"): Aparência, Região, Atalhos, Conta, Conta e segurança (MFA, códigos de recuperação e sessões do Argos) e Sobre, mais as seções que o app registrar com `provideSettingsSection`. Tudo vale na hora — cada controle chama o serviço que já persiste aquela preferência (tema, densidade, menu lateral, fuso).
1300
+ Painel de configurações do shell (substitui as telas do antigo módulo "Sistema"): Conta (perfil, nível, sessão, sair), MFA (verificação em duas etapas e códigos de recuperação do Argos), Sessões (token de acesso, tokens de aplicação e sessões e dispositivos do Argos), Aparência, Acessibilidade (tamanho do texto, animações), Região (idioma, fuso, formato de hora, primeiro dia da semana), Atalhos, Dados do navegador (limpar listas, restaurar preferências), Ajuda (novidades, tour) e Sobre, mais as…
1301
+
1302
+ _Sem inputs/outputs._
1303
+
1304
+ #### `spine-ai-agent` — `AiAgentComponent`
1305
+
1306
+ Sessões › "Conectar um agente de IA" (`SpineFeatures.aiAgent`): em um passo, cria um token de aplicação pessoal (`x-app-token`, a mesma API de "Tokens de aplicação") e monta a configuração MCP pronta para o Claude Code, com os servidores que o app declarou e os escopos do acesso escolhido (só leitura ou leitura e escrita). O token aparece uma única vez, dentro da configuração; nunca vai para o console nem para o armazenamento do navegador, e some ao concluir ou fechar o painel.
1307
+
1308
+ _Sem inputs/outputs._
1309
+
1310
+ #### `spine-idle-warning` — `SpineIdleWarningComponent`
1311
+
1312
+ Aviso de "Encerrar por inatividade" (`SpineIdleService`): contagem regressiva, "Continuar conectado" (padrão, e o que fechar pelo X/Esc faz) e "Sair agora". Montado uma vez no `spine-layout`.
1005
1313
 
1006
1314
  _Sem inputs/outputs._
1007
1315
 
@@ -1027,6 +1335,13 @@ Renderiza Markdown (GFM) como HTML com a tipografia do design system. O texto é
1027
1335
 
1028
1336
  ### Serviços e classes
1029
1337
 
1338
+ #### `SpineLogoutService` · `providedIn: root`
1339
+
1340
+ Saída da sessão pelo shell: todo botão/atalho de sair do spine passa por aqui (menu do perfil, painel de configurações, `Mod+Shift+L`, tela `/blocked`).
1341
+
1342
+ - `readonly pending: signal(…)` — Saída em andamento (o botão mostra "saindo…" / fica desabilitado).
1343
+ - `logout(): Promise<boolean>` — Sai da sessão. Resolve `true` quando saiu (o `@orfeu/angular` já navega para o `/logoff`) e `false` quando o Argos não confirmou: a sessão continua e o aviso de erro aparece. Nunca rejeita. Cliques repetidos durante a s…
1344
+
1030
1345
  #### `OnboardingService` · `providedIn: root`
1031
1346
 
1032
1347
  Onboarding interativo próprio (sem dependência externa). O overlay/holofote e o balão são renderizados pelo OnboardingOverlayComponent, que escuta este serviço. Aparece uma vez por máquina (flag em localStorage), namespaced por cliente.
@@ -1059,7 +1374,7 @@ Abre/fecha o painel de configurações de qualquer lugar (menu do perfil, atalho
1059
1374
 
1060
1375
  - `readonly isOpen: signal(…)`
1061
1376
  - `readonly section: signal(…)` — Seção pedida na abertura (vazio = a primeira).
1062
- - `open(section = ''): void`
1377
+ - `open(section = ''): void` — `section` aceita também as chaves antigas (`seguranca` abre "MFA").
1063
1378
  - `close(): void`
1064
1379
  - `toggle(): void`
1065
1380
 
@@ -1068,6 +1383,7 @@ Abre/fecha o painel de configurações de qualquer lugar (menu do perfil, atalho
1068
1383
  Tokens de aplicação pessoais (`x-app-token`) do usuário logado — `argos-admin /me/app-tokens`. Sempre da aplicação LOGADA: o servidor tira o client do próprio access-token da sessão, então aqui não existe escolha de aplicação. Autentica com o access-token da sessão (o servidor recusa um app-token aqui: token não cria token). `available` é falso quando o app não tem a URL do argos-admin (`SPINE_ADMIN_API`).
1069
1384
 
1070
1385
  - `readonly available`
1386
+ - `readonly changes: signal(…)` — Sobe a cada token criado por aqui (o "Conectar um agente de IA" cria um; a lista de tokens relê).
1071
1387
  - `list(): Promise<AppTokenList>`
1072
1388
  - `options(): Promise<AppTokenOptions>`
1073
1389
  - `create(body: { badge_id: string; name: string; validity_days: number }): Promise<CreatedAppToken>`
@@ -1084,6 +1400,60 @@ Conta do usuário no Argos (verificação em duas etapas, códigos de recuperaç
1084
1400
  - `remove(methodId: string): Promise<AccountOverview>`
1085
1401
  - `sessions(): Promise<{ sessions: AccountSession[] }>`
1086
1402
  - `endOtherSessions(): Promise<{ ended: number }>`
1403
+ - `activity(params: { limit?: number; offset?: number; result?: 'success' | 'failure' } = {}): Promise<AccountActivityPage>` — Entradas e tentativas desta conta nos últimos 90 dias, da mais recente. `result` filtra só sucessos ou falhas.
1404
+ - `badges(): Promise<AccountBadges>`
1405
+ - `setDefaultBadge(badgeId: string | null): Promise<{ default_badge_id: string | null }>` — Crachá com que o login entra nesta aplicação (`null` volta ao padrão: o de menor nível).
1406
+ - `preferences(): Promise<AccountPreferences>`
1407
+ - `savePreferences(preferences: Record<string, unknown>): Promise<AccountPreferences>` — Substitui o documento de preferências desta aplicação na conta (até 16 KB).
1408
+
1409
+ #### `SpineIdleService` · `providedIn: root`
1410
+
1411
+ Encerrar por inatividade (`SpineFeatures.idleTimeout`): conta o tempo sem uso (ponteiro, teclado, rolagem) em TODAS as abas do app — a última atividade vai para o `localStorage` (`hermes_<clientId>_last_activity`) e cada aba confere a mais recente —, abre o aviso com contagem regressiva `SPINE_IDLE_WARNING_SECONDS` antes do fim e, se ninguém responder, sai pelo `SpineLogoutService` (o mesmo "Sair" do menu). Com o aviso aberto, só "Continuar conectado" (ou atividade em outra aba) mantém a sessão…
1412
+
1413
+ - `readonly limits`
1414
+ - `readonly minutes: computed(…)` — Minutos que valem agora (0 = não encerra).
1415
+ - `readonly warning: signal(…)` — Aviso aberto.
1416
+ - `readonly secondsLeft: signal(…)` — Segundos que faltam, enquanto o aviso está aberto.
1417
+ - `start(): void` — Liga a contagem (idempotente). Para sozinha quando a escolha vira "Nunca".
1418
+ - `stay(): void` — "Continuar conectado": fecha o aviso e recomeça a contagem.
1419
+ - `logoutNow(): void` — "Sair agora".
1420
+ - `touch(force = false): void` — Conta uma atividade agora (e a grava para as outras abas no máximo a cada 5 s, ou já, com `force`).
1421
+
1422
+ #### `SpineStartPageService` · `providedIn: root`
1423
+
1424
+ Tela inicial (`SpineFeatures.startPage`): para onde o app vai depois do login quando a pessoa não pediu uma URL (`/callback` sem URL de retorno, ou com `/` ou `/home`) — o início do app, um favorito ou a última tela visitada.
1425
+
1426
+ - `readonly enabled`
1427
+ - `track(): void` — Grava a URL de cada navegação enquanto a escolha for "Última tela visitada" (idempotente).
1428
+ - `remember(url: string): void` — Guarda `url` como última tela (só com a escolha "Última tela visitada").
1429
+ - `target(): string | null` — Destino da tela inicial escolhida, ou `null` (início do app, recurso desligado ou favorito que sumiu).
1430
+
1431
+ #### `SpineNoticesService` · `providedIn: root`
1432
+
1433
+ Avisos do app (`SpineFeatures.notices`): o app declara os tipos que emite (`{ id, label }`) e chama `notify(tipo, aviso)` de onde já sabe do acontecimento (subscription, polling). Cada tipo pode ser desligado em Configurações › Notificações; tipo desligado não aparece. O aviso ligado: - aparece na tela (`HermesToastService`, com "Abrir" quando tem `url`); - com a aba em segundo plano, o aviso do navegador ligado e a permissão concedida, vira também um aviso do sistema (Notification API); clicar…
1434
+
1435
+ - `readonly enabled` — Recurso ligado pelo app.
1436
+ - `readonly types: readonly SpineNoticeType[]` — Tipos declarados pelo app.
1437
+ - `readonly permission: signal<SpineNoticePermission>(…)` — Permissão atual do navegador.
1438
+ - `readonly browserActive: computed(…)` — Aviso do navegador valendo de fato: ligado nas configurações e permitido pelo navegador.
1439
+ - `isEnabled(typeId: string): boolean` — O tipo está ligado (escolha da pessoa ou, sem escolha, o `defaultEnabled` dele).
1440
+ - `setEnabled(typeId: string, enabled: boolean): void`
1441
+ - `enableBrowser(): Promise<boolean>` — Liga o aviso do navegador: pede a permissão quando ainda não foi pedida. Devolve se ficou ligado (permissão negada ou navegador sem suporte: continua desligado).
1442
+ - `disableBrowser(): void`
1443
+ - `refreshPermission(): void` — Relê a permissão (a pessoa pode ter mudado nas configurações do navegador).
1444
+ - `notify(typeId: string, notice: SpineNotice): boolean` — Mostra o aviso, se o tipo estiver ligado. Devolve se mostrou.
1445
+
1446
+ #### `SpineAccountPreferencesService` · `providedIn: root`
1447
+
1448
+ Preferências na conta (`SpineFeatures.accountPreferences`): espelha no Argos (`GET/PUT {api}/preferences`, por usuário e aplicação) o que o painel de configurações guarda no navegador — tema, cor, densidade, fonte, menu lateral, idioma, fuso, relógio, primeiro dia da semana, tamanho do texto, animações, atalhos de tecla única, inatividade, tela inicial, tipos de aviso e favoritos. As telas Aparência, Região etc. não mudam: o armazenamento local continua sendo a fonte de cada tela, e este serviç…
1449
+
1450
+ - `readonly enabled` — Recurso ligado e API da conta disponível.
1451
+ - `readonly status: signal<SpineAccountPreferencesStatus>(…)`
1452
+ - `readonly syncedAt: signal<Date | null>(…)` — Hora da última leitura/gravação bem-sucedida.
1453
+ - `readonly snapshot: computed<SpineAccountPreferencesDoc>(…)` — O documento que o navegador tem agora.
1454
+ - `start(): Promise<void>` — Lê a conta e aplica (uma vez por sessão do app; chamadas seguintes devolvem a mesma promessa). Nunca rejeita.
1455
+ - `ready(timeoutMs = READY_TIMEOUT_MS): Promise<void>` — Como `start()`, mas sem esperar mais que `timeoutMs` (o login não fica parado se o Argos demorar).
1456
+ - `syncNow(): Promise<void>` — Grava agora o que estiver pendente ("Sincronizar agora"); relê a conta se ela ainda não respondeu.
1087
1457
 
1088
1458
  #### `SpineDocsService` · `providedIn: root`
1089
1459
 
@@ -1120,16 +1490,25 @@ Painel de novidades do app (ver `provideSpineNews`). Decide o que está devido
1120
1490
  ### Funções
1121
1491
 
1122
1492
  - `function findTourTarget(selector: string): HTMLElement | null` — Primeiro elemento do seletor que está de fato na tela (tem tamanho e conteúdo). Não usa `offsetParent`: ele é `null` pra `position: fixed` (a sidebar) e pra `display: contents`, e o passo sumia do tour mesmo com o alvo visível. Com as abas vivas do workspace…
1493
+ - `function resolveSettingsSection(section: string): string` — Chave de seção que vale hoje: troca uma chave antiga pela nova; as demais passam iguais.
1123
1494
  - `function provideSettingsSection(section: SpineSettingsSection): Provider` — Registra uma seção do app no painel de configurações (aparece depois das do spine, antes de "Sobre"). Pode ser chamado várias vezes, uma por seção.
1124
1495
  - `function argosAccountApi(authority: string | null | undefined, realm: string | null | undefined): string | null` — Base da API da conta no Argos: `{authority}/api/realms/{realm}/account` — o mesmo `{authority}/api` que o `@orfeu/angular` usa para o OIDC (a `authority` já traz o contexto do serviço, ex.: `https://host/argos`). Sem `authority`/`realm` (ou com o `CHANGE_ME`…
1125
1496
  - `function accountErrorCode(err: unknown): string` — Código de erro que o Argos devolveu (`{ error: 'invalid_code' }`), ou `''`.
1497
+ - `function buildMcpConfig(servers: readonly SpineMcpServer[], token: string, write: boolean, origin: string): string` — Monta o `.mcp.json` do Claude Code: uma entrada por servidor, todas com o mesmo token. Com `write`, cada servidor que tem `writeScopes` pede esses escopos; os demais (e todos sem `write`) vão com `readScopes`, ou sem o header (o MCP já é só leitura sem ele).…
1498
+ - `function idleLimits(features: SpineFeatures | undefined): SpineIdleLimits` — Opções e limites de inatividade do app. Sem o recurso, `enabled` é falso e não há opções.
1499
+ - `function effectiveIdleMinutes(chosen: number, limits: SpineIdleLimits): number` — Minutos que valem de fato: a escolha da pessoa dentro dos limites do app (0 = não encerra).
1500
+ - `function isInternalPath(url: unknown): url is string` — Caminho interno seguro (`/x`, nunca `//host` nem `http:`).
1501
+ - `function stable(value: unknown): string` — JSON com as chaves dos objetos em ordem (a conta pode devolver outra ordem).
1126
1502
  - `function sanitizeSpineMarkdownHtml(html: string): string | null` — HTML limpo pelo perfil do spine, ou `null` quando não há DOM (SSR: melhor não renderizar).
1127
1503
 
1128
1504
  ### Constantes e tokens
1129
1505
 
1130
1506
  - `SPINE_BRAND`: `InjectionToken<Type<unknown> | null>` — Componente de marca que o header do shell desenha no lugar da imagem de `SpineConfig.logo` (tem prioridade sobre ela). Injeção em vez de projeção de conteúdo porque o `LayoutComponent` é montado pelo `Router`, não pelo template do app — não existe `<ng-conten…
1131
1507
  - `SPINE_SETTINGS_KEYS` — Seções que o próprio spine já traz. `key` é também o valor de `?settings=` na URL.
1508
+ - `SPINE_SETTINGS_ALIASES`: `Readonly<Record<string, string>>` — Chaves antigas de `?settings=` que continuam abrindo a seção que as substituiu (links já publicados).
1132
1509
  - `SPINE_SETTINGS_SECTIONS`: `InjectionToken<SpineSettingsSection[]>`
1510
+ - `SPINE_IDLE_WARNING_SECONDS`: `60` — Segundos de aviso antes de encerrar.
1511
+ - `SPINE_PREFERENCES_SAVE_DELAY_MS`: `1500` — Espera depois da última mudança antes de gravar.
1133
1512
  - `SPINE_MARKDOWN_PURIFY_CONFIG`: `Config` — Perfil do DOMPurify para o Markdown do spine (documentação de tela, novidades). Mais restrito que o padrão: o HTML entra no DOM do shell (sem shadow DOM), então - `<style>` e o atributo `style` ficam de fora (CSS valeria para a página inteira: esconder/redese…
1134
1513
 
1135
1514
  ### Tipos
@@ -1327,12 +1706,145 @@ interface AccountSession {
1327
1706
  }
1328
1707
  ```
1329
1708
 
1709
+ #### `AccountActivityEntry` (interface)
1710
+
1711
+ Uma tentativa de entrar na conta (`GET {api}/activity`): sucesso, falha ou cancelamento.
1712
+
1713
+ ```ts
1714
+ interface AccountActivityEntry {
1715
+ id: string;
1716
+ /** Data e hora (ISO). */
1717
+ at: string;
1718
+ result: 'success' | 'failure' | 'cancelled';
1719
+ /** `local`, `mfa`, `github`, `google`, `keycloak`, `entraid`. */
1720
+ method: string;
1721
+ /** Motivo da falha (`bad_password`, `mfa_failed`, `locked`…); `null` no sucesso. */
1722
+ reason: string | null;
1723
+ ip: string | null;
1724
+ device: { browser?: string | null; os?: string | null; mobile: boolean; label: string };
1725
+ /** Aplicativo em que a pessoa tentou entrar. */
1726
+ client: { client_id: string; name: string | null } | null;
1727
+ }
1728
+ ```
1729
+
1730
+ #### `AccountActivityPage` (interface)
1731
+
1732
+ ```ts
1733
+ interface AccountActivityPage {
1734
+ attempts: AccountActivityEntry[];
1735
+ total: number;
1736
+ limit: number;
1737
+ offset: number;
1738
+ /** Começo da janela (90 dias). */
1739
+ since: string;
1740
+ }
1741
+ ```
1742
+
1743
+ #### `AccountBadges` (interface)
1744
+
1745
+ Crachás da pessoa nesta aplicação e o padrão guardado no Argos (`GET {api}/badges`).
1746
+
1747
+ ```ts
1748
+ interface AccountBadges {
1749
+ client: { id: string; name: string | null };
1750
+ badges: { id: string; name: string }[];
1751
+ default_badge_id: string | null;
1752
+ active_badge_id: string | null;
1753
+ }
1754
+ ```
1755
+
1756
+ #### `AccountPreferences` (interface)
1757
+
1758
+ Preferências guardadas na conta para esta aplicação (`GET/PUT {api}/preferences`).
1759
+
1760
+ ```ts
1761
+ interface AccountPreferences {
1762
+ preferences: Record<string, unknown>;
1763
+ updated_at: string | null;
1764
+ }
1765
+ ```
1766
+
1330
1767
  #### `AccountReauth` (type)
1331
1768
 
1332
1769
  ```ts
1333
1770
  type AccountReauth = { password: string } | { method_id: string; code: string };
1334
1771
  ```
1335
1772
 
1773
+ #### `SpineIdleLimits` (interface)
1774
+
1775
+ Limites de "Encerrar por inatividade" já resolvidos a partir de `SpineFeatures.idleTimeout`.
1776
+
1777
+ ```ts
1778
+ interface SpineIdleLimits {
1779
+ enabled: boolean;
1780
+ /** Minutos mínimos (0 = sem mínimo). */
1781
+ min: number;
1782
+ /** Minutos máximos (0 = sem máximo; com máximo a opção "Nunca" some). */
1783
+ max: number;
1784
+ /** Opções oferecidas (0 = nunca), já filtradas pelos limites. */
1785
+ options: readonly number[];
1786
+ }
1787
+ ```
1788
+
1789
+ #### `SpineNotice` (interface)
1790
+
1791
+ Um aviso do app (`SpineNoticesService.notify`).
1792
+
1793
+ ```ts
1794
+ interface SpineNotice {
1795
+ title: string;
1796
+ /** Detalhe (segunda linha do aviso do navegador; no aviso da tela vai depois do título). */
1797
+ body?: string;
1798
+ /** Caminho interno (`/solicitacoes/42`) aberto pelo "Abrir" do aviso e pelo clique no aviso do navegador. */
1799
+ url?: string;
1800
+ /** Cor do aviso na tela. Padrão: `info`. */
1801
+ intent?: AlertVariant;
1802
+ }
1803
+ ```
1804
+
1805
+ #### `SpineNoticePermission` (type)
1806
+
1807
+ Permissão do navegador para avisos, ou `unsupported` (sem Notification API, ou fora do navegador).
1808
+
1809
+ ```ts
1810
+ type SpineNoticePermission = NotificationPermission | 'unsupported';
1811
+ ```
1812
+
1813
+ #### `SpineAccountPreferencesDoc` (interface)
1814
+
1815
+ Documento de preferências guardado no Argos (`PUT {api}/preferences`): chaves planas, todas opcionais.
1816
+
1817
+ ```ts
1818
+ interface SpineAccountPreferencesDoc {
1819
+ v: number;
1820
+ themeMode?: HermesThemeMode;
1821
+ family?: string;
1822
+ density?: HermesDensity;
1823
+ font?: string;
1824
+ sidebar?: 'auto' | 'fixed' | 'compact';
1825
+ language?: string;
1826
+ timeZone?: string;
1827
+ textScale?: number;
1828
+ motion?: HermesMotionPreference;
1829
+ hourCycle?: SpineHourCyclePreference;
1830
+ weekStart?: Weekday | null;
1831
+ characterKeys?: boolean;
1832
+ idleMinutes?: number;
1833
+ startPage?: SpineStartPagePreference;
1834
+ notices?: Record<string, boolean>;
1835
+ browserNotices?: boolean;
1836
+ favorites?: unknown[];
1837
+ }
1838
+ ```
1839
+
1840
+ #### `SpineAccountPreferencesStatus` (type)
1841
+
1842
+ `local`: só no navegador (recurso desligado, sem API da conta, ou Argos sem o endpoint).
1843
+
1844
+ ```ts
1845
+ type SpineAccountPreferencesStatus = 'idle' | 'local' | 'loading' | 'saving' | 'synced' | 'error';
1846
+ ```
1847
+
1336
1848
  #### `DocsEntry` (interface)
1337
1849
 
1338
1850
  Documento de uma tela que a pessoa logada pode abrir.