@basaltkit/comments adiciona comentários em thread a qualquer recurso — uma nota, um projeto, uma tarefa — com @mentions e resolve/reopen, delimitados por tenant. Emite eventos que fazem ponte de forma limpa com o realtime (discussão ao vivo) e as notificações (alertar os mencionados).
Regista commentsPlugin e monta as rotas REST já prontas através do teu adaptador. Em dev o store é em memória; em produção passa um store suportado por @basaltkit/comments-prisma ou -sqlite:
add extrai as mentions com DEFAULT_MENTION_PATTERN — @id ([\w-]+) não precedido de um carácter de palavra, ., + ou -, por isso ana@example.comnão é uma mention de example. Passa mentionPattern (uma regex g cujo primeiro grupo de captura é o user id) ao commentsPlugin para corresponder ao teu próprio esquema de ids; DELIMITED_MENTION_PATTERN lê @{qualquer-id} para ids com pontos ou @.
add extrai as @mentions do corpo (padrão configurável), armazena-as no comentário, e emite comment:created mais um comment:mentioned por cada utilizador mencionado. Também: edit, remove, resolve(id, by), reopen(id) — e, opt-in, âncoras, soft delete, janela de edição e revisões.
Corpos e mentions limitados
Um corpo maior que maxBodyLength (predefinição 10 000 caracteres) lança CommentTooLongError (400 COMMENT_TOO_LONG), e um com mais de maxMentions mentions distintas (predefinição 50) lança CommentMentionLimitError (400 COMMENT_TOO_MANY_MENTIONS) — em add e em edit, antes de guardar ou emitir o que quer que seja. De resto cada @id é aceite tal como vem, por isso quando comment:mentioned chega a um canal de notificação real, passa resolveMentions(ids, tenantId) para manter só os utilizadores que podem ser mencionados — tipicamente os membros do tenant:
Dentro de um contexto de tenant, um argumento tenantId explícito tem de nomear esse tenant; qualquer outro valor lança CommentTenantMismatchError (403 COMMENT_TENANT_MISMATCH). Só escolhe um tenant fora de um (jobs, CLI).
Numa app single-tenant — sem tenancyPlugin — as chamadas não precisam de tenantId, e os comentários ficam numa única chave interna, SINGLE_TENANT_SCOPE ('@single' — fora da gramática de ids de tenant, logo nenhum tenant pode receber esses comentários). Um id de tenant igual a ela é recusado com CommentTenantReservedError (400 COMMENT_TENANT_RESERVED).
Atualizar dados single-tenant
Antes do @basaltkit/comments 4.0 a chave single-tenant era 'default' — um id de tenant válido, logo um tenant chamado default lia, editava e apagava os comentários single-tenant. Uma app single-tenant com comentários persistidos muda-lhes a chave uma vez: UPDATE comments SET "tenantId" = '@single' WHERE "tenantId" = 'default' (@basaltkit/comments-prisma; no @basaltkit/comments-sqlite a coluna é tenant_id). Salta este passo se default alguma vez foi um tenant real nessa base de dados.
Cada mutação emite um hook (comment:created, comment:mentioned, comment:updated, comment:deleted, comment:resolved, comment:reopened), por isso atualizações ao vivo e notificações ligam-se sem acoplamento. Cada payload leva actorId — quem o fez: o autor em created/mentioned, quem resolveu em resolved, senão o ator explícito (edit(id, body, { actorId }), remove(id, { by })) ou ctx().user.id; só falta quando uma chamada corre fora de um pedido sem ator indicado. Subscreve em app.hooks:
ts
import { REALTIME } from '@basaltkit/realtime'import { NOTIFIER, defineNotification } from '@basaltkit/notifications'import { z } from 'zod'import { app } from './app.js'const realtime = app.container.get(REALTIME)const notifier = app.container.get(NOTIFIER)const CommentMention = defineNotification({ name: 'comment.mention', schema: z.object({ by: z.string() }), channels: ['inApp'], via: { inApp: ({ by }) => ({ title: 'You were mentioned', data: { by } }) },})// push new comments to everyone viewing the resourceapp.hooks.on('comment:created', ({ comment }) => realtime .to(comment.tenantId) .channel(`${comment.resourceType}:${comment.resourceId}`) .emit('comment', comment))// notify the mentioned — one hook fires per mentioned userapp.hooks.on('comment:mentioned', ({ comment, userId }) => notifier.notify({ id: userId }, CommentMention, { by: comment.authorId }))
Os hooks são em processo. Para pôr a atividade dos comentários no bus durável @basaltkit/events (outbox, listeners em fila), faz a ponte dos que precisares:
Âncoras, soft delete, janela de edição e revisões
Tudo opt-in; sem estas opções os comentários comportam-se exatamente como antes.
ts
commentsPlugin({ deletion: 'soft', // remove() guarda uma lápide em vez de apagar a linha editWindowMs: 15 * 60_000, // edit() recusado com 409 passados 15 minutos revisions: true, // edit() guarda cada corpo anterior})// anchor: onde no recurso o comentário aponta (objeto JSON, ≤ 4 KB)await comments.on('contract', 'c-12').add({ authorId: 'u1', body: 'Vê esta cláusula', anchor: { page: 3, rect: [72, 540, 300, 560] } })await comments.remove(id, { by: 'moderator-1', reason: 'fora do tema' })await comments.revisions(id) // [{ body, at, by }, …] do mais antigo para o mais recente
Opção
Predefinição
Comportamento
deletion
'hard'
'soft' define deletedAt/deletedBy/deleteReason; list()/tree() devolvem o comentário como lápide (body vazio, sem mentions) para as respostas manterem o seu lugar. get() continua a devolver o registo guardado (moderação). Um comentário soft-deleted responde 404 a edit/resolve/reopen; removê-lo de novo não faz nada. comment:deleted leva soft: true
editWindowMs
nenhuma
edit() fora da janela lança CommentEditWindowClosedError (409 COMMENT_EDIT_WINDOW_CLOSED)
revisions
false
edit() regista o corpo anterior (CommentRevision) antes de o substituir. Requer uma store com addRevision/revisions (memória, SQLite, Prisma); caso contrário a app falha no arranque com CommentRevisionsUnsupportedError
anchor tem de ser um objeto JSON simples de no máximo 4 KB (400 COMMENT_ANCHOR_INVALID); POST /comments aceita-o no corpo. O schema Prisma ganhou as colunas opcionais anchor, deletedAt, deletedBy, deleteReason e um modelo CommentRevision — só são escritas quando usas a funcionalidade, por isso adiciona-as antes de a ligar. O SQLite migra-se sozinho.
resolveMentions filtra em silêncio. Para recusar um comentário que menciona alguém que não pode ser mencionado, lança a partir dele — o erro propaga-se para fora de add/edit (e pelas rotas, com o seu próprio status) antes de qualquer coisa ser guardada:
ts
commentsPlugin({ resolveMentions: async (ids, tenantId) => { const known = new Set((await members.of(tenantId, ids)).map((m) => m.userId)) const unknown = ids.filter((id) => !known.has(id)) if (unknown.length) throw new HttpError(422, 'UNKNOWN_MENTION', `Utilizadores desconhecidos: ${unknown.join(', ')}`) return ids },})
commentRoutes() (exigem um utilizador autenticado; o autor é tirado de ctx().user): GET /comments?resourceType=&resourceId=, POST /comments, PATCH /comments/:id, DELETE /comments/:id, POST /comments/:id/resolve e /reopen. Por predefinição qualquer utilizador do tenant pode ler uma thread e publicar nela, e editar, apagar, resolver e reabrir estão restritos ao autor do comentário (403 COMMENT_FORBIDDEN). Tudo é delimitado por tenant.
Passa authorize para ligar uma thread às regras de acesso do recurso que discute. Substitui a política predefinida; compõe com defaultCommentPolicy para a manter:
Para responder 404 em vez de 403 a um recurso cuja existência quem chama nem deve conhecer, lança CommentNotFoundError a partir do authorize — o status do erro chega ao cliente em todos os adaptadores:
ts
import { CommentNotFoundError, commentRoutes } from '@basaltkit/comments'commentRoutes({ authorize: async (action, target, user) => { if (!(await canSeeMatter(user.id, target.resourceId))) throw new CommentNotFoundError() // 404 COMMENT_NOT_FOUND return defaultCommentPolicy(action, target, user) }, meta: { can: 'comments:write' }, // meta de rota extra, fundido em todas as rotas (auth: true mantém-se sempre)})
Aqui não é preciso UI já pronta — os comentários renderizam inline na tua app — mas o mesmo padrão autocontido alimenta o visualizador de auditoria.
Comentários
@basaltkit/commentsadiciona comentários em thread a qualquer recurso — uma nota, um projeto, uma tarefa — com @mentions e resolve/reopen, delimitados por tenant. Emite eventos que fazem ponte de forma limpa com o realtime (discussão ao vivo) e as notificações (alertar os mencionados).Setup
Regista
commentsPlugine monta as rotas REST já prontas através do teu adaptador. Em dev o store é em memória; em produção passa umstoresuportado por@basaltkit/comments-prismaou-sqlite:Dica
addextrai as mentions comDEFAULT_MENTION_PATTERN—@id([\w-]+) não precedido de um carácter de palavra,.,+ou-, por issoana@example.comnão é uma mention deexample. PassamentionPattern(uma regexgcujo primeiro grupo de captura é o user id) aocommentsPluginpara corresponder ao teu próprio esquema de ids;DELIMITED_MENTION_PATTERNlê@{qualquer-id}para ids com pontos ou@.Adicionar e ler
addextrai as @mentions do corpo (padrão configurável), armazena-as no comentário, e emitecomment:createdmais umcomment:mentionedpor cada utilizador mencionado. Também:edit,remove,resolve(id, by),reopen(id)— e, opt-in, âncoras, soft delete, janela de edição e revisões.Corpos e mentions limitados
Um corpo maior que
maxBodyLength(predefinição 10 000 caracteres) lançaCommentTooLongError(400 COMMENT_TOO_LONG), e um com mais demaxMentionsmentions distintas (predefinição 50) lançaCommentMentionLimitError(400 COMMENT_TOO_MANY_MENTIONS) — emadde emedit, antes de guardar ou emitir o que quer que seja. De resto cada@idé aceite tal como vem, por isso quandocomment:mentionedchega a um canal de notificação real, passaresolveMentions(ids, tenantId)para manter só os utilizadores que podem ser mencionados — tipicamente os membros do tenant:Dentro de um contexto de tenant, um argumento
tenantIdexplícito tem de nomear esse tenant; qualquer outro valor lançaCommentTenantMismatchError(403 COMMENT_TENANT_MISMATCH). Só escolhe um tenant fora de um (jobs, CLI).Numa app single-tenant — sem
tenancyPlugin— as chamadas não precisam detenantId, e os comentários ficam numa única chave interna,SINGLE_TENANT_SCOPE('@single'— fora da gramática de ids de tenant, logo nenhum tenant pode receber esses comentários). Um id de tenant igual a ela é recusado comCommentTenantReservedError(400 COMMENT_TENANT_RESERVED).Atualizar dados single-tenant
Antes do
@basaltkit/comments4.0 a chave single-tenant era'default'— um id de tenant válido, logo um tenant chamadodefaultlia, editava e apagava os comentários single-tenant. Uma app single-tenant com comentários persistidos muda-lhes a chave uma vez:UPDATE comments SET "tenantId" = '@single' WHERE "tenantId" = 'default'(@basaltkit/comments-prisma; no@basaltkit/comments-sqlitea coluna étenant_id). Salta este passo sedefaultalguma vez foi um tenant real nessa base de dados.Discussão ao vivo + notificações de mention
Cada mutação emite um hook (
comment:created,comment:mentioned,comment:updated,comment:deleted,comment:resolved,comment:reopened), por isso atualizações ao vivo e notificações ligam-se sem acoplamento. Cada payload levaactorId— quem o fez: o autor emcreated/mentioned, quem resolveu emresolved, senão o ator explícito (edit(id, body, { actorId }),remove(id, { by })) ouctx().user.id; só falta quando uma chamada corre fora de um pedido sem ator indicado. Subscreve emapp.hooks:Os hooks são em processo. Para pôr a atividade dos comentários no bus durável
@basaltkit/events(outbox, listeners em fila), faz a ponte dos que precisares:Âncoras, soft delete, janela de edição e revisões
Tudo opt-in; sem estas opções os comentários comportam-se exatamente como antes.
deletion'hard''soft'definedeletedAt/deletedBy/deleteReason;list()/tree()devolvem o comentário como lápide (bodyvazio, semmentions) para as respostas manterem o seu lugar.get()continua a devolver o registo guardado (moderação). Um comentário soft-deleted responde 404 a edit/resolve/reopen; removê-lo de novo não faz nada.comment:deletedlevasoft: trueeditWindowMsedit()fora da janela lançaCommentEditWindowClosedError(409 COMMENT_EDIT_WINDOW_CLOSED)revisionsfalseedit()regista o corpo anterior (CommentRevision) antes de o substituir. Requer uma store comaddRevision/revisions(memória, SQLite, Prisma); caso contrário a app falha no arranque comCommentRevisionsUnsupportedErroranchortem de ser um objeto JSON simples de no máximo 4 KB (400 COMMENT_ANCHOR_INVALID);POST /commentsaceita-o no corpo. O schema Prisma ganhou as colunas opcionaisanchor,deletedAt,deletedBy,deleteReasone um modeloCommentRevision— só são escritas quando usas a funcionalidade, por isso adiciona-as antes de a ligar. O SQLite migra-se sozinho.Recusar mentions desconhecidas
resolveMentionsfiltra em silêncio. Para recusar um comentário que menciona alguém que não pode ser mencionado, lança a partir dele — o erro propaga-se para fora deadd/edit(e pelas rotas, com o seu próprio status) antes de qualquer coisa ser guardada:Rotas
commentRoutes()(exigem um utilizador autenticado; o autor é tirado dectx().user):GET /comments?resourceType=&resourceId=,POST /comments,PATCH /comments/:id,DELETE /comments/:id,POST /comments/:id/resolvee/reopen. Por predefinição qualquer utilizador do tenant pode ler uma thread e publicar nela, e editar, apagar, resolver e reabrir estão restritos ao autor do comentário (403 COMMENT_FORBIDDEN). Tudo é delimitado por tenant.Passa
authorizepara ligar uma thread às regras de acesso do recurso que discute. Substitui a política predefinida; compõe comdefaultCommentPolicypara a manter:Para responder 404 em vez de 403 a um recurso cuja existência quem chama nem deve conhecer, lança
CommentNotFoundErrora partir doauthorize— o status do erro chega ao cliente em todos os adaptadores:Aqui não é preciso UI já pronta — os comentários renderizam inline na tua app — mas o mesmo padrão autocontido alimenta o visualizador de auditoria.