@basaltkit/comments 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @basaltkit/comments
+
+Per-resource comments for Basalt: **threads** (nested replies), **@mentions**, and **resolve/reopen**, isolated by tenant, emitting **events** that connect to [`@basaltkit/realtime`](https://www.npmjs.com/package/@basaltkit/realtime) (live discussion) and [`@basaltkit/notifications`](https://www.npmjs.com/package/@basaltkit/notifications) (notify who was mentioned). You need this module when you want collaboration — commenting on a note, a project, a task.
+
+## What this module solves
+
+A comment system involves more than storing text: threads with replies, extracting @mentions to notify, marking a discussion as resolved, and restricting edits to the author. This module gives you all of that — attached to **any resource** (`resourceType`:`resourceId`) and isolated by tenant — and emits events for the rest of the ecosystem to react to.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/comments
+```
+
+Depends on `@basaltkit/core` and `@basaltkit/fastify` (routes). No database required: the default store is in-memory (`CommentStore` contract for production).
+
+## Get started in 5 minutes
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { commentsPlugin, COMMENTS, commentRoutes } from '@basaltkit/comments'
+import { fastifyPlugin } from '@basaltkit/fastify'
+
+const app = await createApp({
+  plugins: [commentsPlugin(), fastifyPlugin({ routes: [...commentRoutes()] })],
+}).boot()
+
+const comments = app.container.get(COMMENTS)
+
+// add a comment to a resource
+const root = await comments.on('note', 'note-1', 'acme').add({ authorId: 'u1', body: 'Great work @u2!' })
+
+// reply (thread)
+await comments.on('note', 'note-1', 'acme').add({ authorId: 'u2', body: 'Thanks!', parentId: root.id })
+
+// get the comment tree
+const tree = await comments.on('note', 'note-1', 'acme').tree()
+```
+
+`add` extracts @mentions from the body (default `@id`), stores them on the comment, and emits `comment:mentioned` for each mentioned user.
+
+## Connecting to realtime and notifications
+
+The power is in the events. Push comments live and notify mentioned users without coupling anything:
+
+```ts
+// live discussion (realtime)
+hooks.on('comment:created', ({ comment }) =>
+  realtime.to(comment.tenantId).channel(`${comment.resourceType}:${comment.resourceId}`).emit('comment', comment))
+
+// notify whoever was mentioned
+hooks.on('comment:mentioned', ({ comment, userId }) =>
+  notifications.to(userId).send('comment.mention', { by: comment.authorId, resource: comment.resourceId }))
+```
+
+## Routes
+
+`commentRoutes()` (all require login; author comes from `ctx().user`):
+
+| Route | Description |
+|---|---|
+| `GET /comments?resourceType=&resourceId=` | Comment tree for the resource. |
+| `POST /comments` `{ resourceType, resourceId, body, parentId? }` | Create (or reply). |
+| `PATCH /comments/:id` `{ body }` | Edit — **author only**. |
+| `DELETE /comments/:id` | Delete — **author only**. |
+| `POST /comments/:id/resolve` · `/reopen` | Resolve / reopen the discussion. |
+
+## API reference
+
+### `commentsPlugin({ store?, mentionPattern? })`
+
+Registers the `COMMENTS` token. `mentionPattern` is a regex whose first group is the mentioned id (default `@([\w-]+)`).
+
+### `class Comments`
+
+| Method | Description |
+|---|---|
+| `on(resourceType, resourceId, tenantId?)` | `{ add, list, tree }` for a resource. |
+| `get(id, tenantId?)` | A single comment. |
+| `edit(id, body, tenantId?)` | Edits and re-extracts mentions; emits `comment:updated`. |
+| `remove(id, tenantId?)` | Deletes; emits `comment:deleted`. |
+| `resolve(id, by, tenantId?)` · `reopen(id, tenantId?)` | Emits `comment:resolved` / `comment:reopened`. |
+
+Without `tenantId`, uses `ctx().tenant.id` (otherwise `CommentTenantRequiredError`).
+
+### Events
+
+`comment:created` · `comment:updated` · `comment:deleted` · `comment:resolved` · `comment:reopened` · `comment:mentioned` (one per mentioned user).
+
+## How it connects to other modules
+
+- **`@basaltkit/realtime`** — pushes `comment:created` to the resource's channel (live discussion).
+- **`@basaltkit/notifications`** — reacts to `comment:mentioned` to notify mentioned users.
+- **`@basaltkit/auth` / `@basaltkit/tenancy`** — provide the user (author) and tenant from context.

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import * as _basaltkit_core from '@basaltkit/core';
+import { HookBus, BasaltError } from '@basaltkit/core';
+import { BasaltRoute } from '@basaltkit/fastify';
+
+/** A comment attached to a resource (`resourceType`:`resourceId`) within a tenant. */
+interface Comment {
+    id: string;
+    tenantId: string;
+    resourceType: string;
+    resourceId: string;
+    /** Set when this comment is a reply to another. */
+    parentId?: string;
+    authorId: string;
+    body: string;
+    /** User ids extracted from @mentions in the body. */
+    mentions: string[];
+    resolvedAt?: number;
+    resolvedBy?: string;
+    editedAt?: number;
+    createdAt: number;
+}
+interface CommentPatch {
+    body?: string;
+    mentions?: string[];
+    editedAt?: number;
+    /** `undefined` clears it (reopen). */
+    resolvedAt?: number | undefined;
+    resolvedBy?: string | undefined;
+}
+interface CommentStore {
+    create(comment: Comment): Promise<void>;
+    find(tenantId: string, id: string): Promise<Comment | null>;
+    /** Every comment on a resource (the whole thread), oldest first. */
+    list(tenantId: string, resourceType: string, resourceId: string): Promise<Comment[]>;
+    update(tenantId: string, id: string, patch: CommentPatch): Promise<Comment | null>;
+    delete(tenantId: string, id: string): Promise<void>;
+}
+declare class MemoryCommentStore implements CommentStore {
+    private readonly records;
+    private key;
+    create(comment: Comment): Promise<void>;
+    find(tenantId: string, id: string): Promise<Comment | null>;
+    list(tenantId: string, resourceType: string, resourceId: string): Promise<Comment[]>;
+    update(tenantId: string, id: string, patch: CommentPatch): Promise<Comment | null>;
+    delete(tenantId: string, id: string): Promise<void>;
+}
+
+declare class CommentNotFoundError extends BasaltError {
+    readonly status = 404;
+    constructor();
+}
+declare class CommentTenantRequiredError extends BasaltError {
+    readonly status = 400;
+    constructor();
+}
+/** A comment plus its nested replies. */
+interface CommentNode extends Comment {
+    replies: CommentNode[];
+}
+interface CommentsOptions {
+    store?: CommentStore;
+    hooks?: HookBus;
+    /** Regex whose first capture group is a mentioned user id. Default `@([\w-]+)`. */
+    mentionPattern?: RegExp;
+    now?: () => number;
+}
+interface AddCommentInput {
+    authorId: string;
+    body: string;
+    parentId?: string;
+}
+/** Everything scoped to one resource (`resourceType`:`resourceId`) of a tenant. */
+interface ResourceComments {
+    add(input: AddCommentInput): Promise<Comment>;
+    list(): Promise<Comment[]>;
+    tree(): Promise<CommentNode[]>;
+}
+/**
+ * Per-resource comment threads with @mentions and resolve/reopen, scoped by
+ * tenant. Emits hooks (`comment:created`, `comment:mentioned`, …) so live
+ * updates (@basaltkit/realtime) and notifications wire up without coupling.
+ */
+declare class Comments {
+    private readonly store;
+    private readonly hooks;
+    private readonly mentionPattern;
+    private readonly now;
+    constructor(options?: CommentsOptions);
+    on(resourceType: string, resourceId: string, tenantId?: string): ResourceComments;
+    get(id: string, tenantId?: string): Promise<Comment | null>;
+    edit(id: string, body: string, tenantId?: string): Promise<Comment>;
+    remove(id: string, tenantId?: string): Promise<void>;
+    resolve(id: string, resolvedBy: string, tenantId?: string): Promise<Comment>;
+    reopen(id: string, tenantId?: string): Promise<Comment>;
+    private add;
+    private mutate;
+    private mentions;
+    private tenant;
+}
+
+declare module '@basaltkit/core' {
+    interface BasaltHooks {
+        'comment:created': {
+            comment: Comment;
+        };
+        'comment:updated': {
+            comment: Comment;
+        };
+        'comment:deleted': {
+            tenantId: string;
+            id: string;
+            resourceType: string;
+            resourceId: string;
+        };
+        'comment:resolved': {
+            comment: Comment;
+        };
+        'comment:reopened': {
+            comment: Comment;
+        };
+        /** One per mentioned user — wire to notifications. */
+        'comment:mentioned': {
+            comment: Comment;
+            userId: string;
+        };
+    }
+}
+declare const COMMENTS: _basaltkit_core.Token<Comments>;
+type CommentsPluginOptions = Omit<CommentsOptions, 'hooks'>;
+declare function commentsPlugin(options?: CommentsPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+/**
+ * REST routes for the current tenant's comments, all requiring a logged-in
+ * user. The author is taken from `ctx().user`; editing and deleting are
+ * restricted to the comment's author.
+ */
+declare function commentRoutes(): BasaltRoute[];
+
+export { type AddCommentInput, COMMENTS, type Comment, type CommentNode, CommentNotFoundError, type CommentPatch, type CommentStore, CommentTenantRequiredError, Comments, type CommentsOptions, type CommentsPluginOptions, MemoryCommentStore, type ResourceComments, commentRoutes, commentsPlugin };

package/dist/index.js

@@ -0,0 +1,251 @@
+// src/comments.ts
+import { randomUUID } from "crypto";
+import { BasaltError, tryCtx } from "@basaltkit/core";
+
+// src/store.ts
+var MemoryCommentStore = class {
+  records = /* @__PURE__ */ new Map();
+  key(tenantId, id) {
+    return `${tenantId} ${id}`;
+  }
+  async create(comment) {
+    this.records.set(this.key(comment.tenantId, comment.id), comment);
+  }
+  async find(tenantId, id) {
+    return this.records.get(this.key(tenantId, id)) ?? null;
+  }
+  async list(tenantId, resourceType, resourceId) {
+    const out = [];
+    for (const c of this.records.values()) {
+      if (c.tenantId === tenantId && c.resourceType === resourceType && c.resourceId === resourceId) out.push(c);
+    }
+    return out.sort((a, b) => a.createdAt - b.createdAt);
+  }
+  async update(tenantId, id, patch) {
+    const record = this.records.get(this.key(tenantId, id));
+    if (!record) return null;
+    Object.assign(record, patch);
+    return record;
+  }
+  async delete(tenantId, id) {
+    this.records.delete(this.key(tenantId, id));
+  }
+};
+
+// src/comments.ts
+var CommentNotFoundError = class extends BasaltError {
+  status = 404;
+  constructor() {
+    super("COMMENT_NOT_FOUND", "Comment not found.");
+  }
+};
+var CommentTenantRequiredError = class extends BasaltError {
+  status = 400;
+  constructor() {
+    super("COMMENT_TENANT_REQUIRED", "A tenant is required \u2014 pass tenantId or run inside a tenant context.");
+  }
+};
+var buildTree = (comments2) => {
+  const nodes = new Map(comments2.map((c) => [c.id, { ...c, replies: [] }]));
+  const roots = [];
+  for (const node of nodes.values()) {
+    const parent = node.parentId ? nodes.get(node.parentId) : void 0;
+    if (parent) parent.replies.push(node);
+    else roots.push(node);
+  }
+  return roots;
+};
+var Comments = class {
+  store;
+  hooks;
+  mentionPattern;
+  now;
+  constructor(options = {}) {
+    this.store = options.store ?? new MemoryCommentStore();
+    this.hooks = options.hooks;
+    this.mentionPattern = options.mentionPattern ?? /@([\w-]+)/g;
+    this.now = options.now ?? Date.now;
+  }
+  on(resourceType, resourceId, tenantId) {
+    const tenant = this.tenant(tenantId);
+    return {
+      add: (input) => this.add(tenant, resourceType, resourceId, input),
+      list: () => this.store.list(tenant, resourceType, resourceId),
+      tree: async () => buildTree(await this.store.list(tenant, resourceType, resourceId))
+    };
+  }
+  get(id, tenantId) {
+    return this.store.find(this.tenant(tenantId), id);
+  }
+  async edit(id, body, tenantId) {
+    const tenant = this.tenant(tenantId);
+    if (!await this.store.find(tenant, id)) throw new CommentNotFoundError();
+    const updated = await this.store.update(tenant, id, { body, mentions: this.mentions(body), editedAt: this.now() });
+    await this.hooks?.emit("comment:updated", { comment: updated });
+    return updated;
+  }
+  async remove(id, tenantId) {
+    const tenant = this.tenant(tenantId);
+    const comment = await this.store.find(tenant, id);
+    if (!comment) return;
+    await this.store.delete(tenant, id);
+    await this.hooks?.emit("comment:deleted", {
+      tenantId: tenant,
+      id,
+      resourceType: comment.resourceType,
+      resourceId: comment.resourceId
+    });
+  }
+  async resolve(id, resolvedBy, tenantId) {
+    const comment = await this.mutate(id, { resolvedAt: this.now(), resolvedBy }, tenantId);
+    await this.hooks?.emit("comment:resolved", { comment });
+    return comment;
+  }
+  async reopen(id, tenantId) {
+    const comment = await this.mutate(id, { resolvedAt: void 0, resolvedBy: void 0 }, tenantId);
+    await this.hooks?.emit("comment:reopened", { comment });
+    return comment;
+  }
+  async add(tenantId, resourceType, resourceId, input) {
+    const mentions = this.mentions(input.body);
+    const comment = {
+      id: randomUUID(),
+      tenantId,
+      resourceType,
+      resourceId,
+      authorId: input.authorId,
+      body: input.body,
+      mentions,
+      createdAt: this.now(),
+      ...input.parentId !== void 0 ? { parentId: input.parentId } : {}
+    };
+    await this.store.create(comment);
+    await this.hooks?.emit("comment:created", { comment });
+    for (const userId of mentions) await this.hooks?.emit("comment:mentioned", { comment, userId });
+    return comment;
+  }
+  async mutate(id, patch, tenantId) {
+    const tenant = this.tenant(tenantId);
+    if (!await this.store.find(tenant, id)) throw new CommentNotFoundError();
+    return await this.store.update(tenant, id, patch);
+  }
+  mentions(body) {
+    const ids = /* @__PURE__ */ new Set();
+    for (const match of body.matchAll(this.mentionPattern)) if (match[1]) ids.add(match[1]);
+    return [...ids];
+  }
+  tenant(explicit) {
+    const id = explicit ?? tryCtx()?.["tenant"]?.id;
+    if (!id) throw new CommentTenantRequiredError();
+    return id;
+  }
+};
+
+// src/plugin.ts
+import { createToken, ctx, definePlugin, BasaltError as BasaltError2 } from "@basaltkit/core";
+import { route } from "@basaltkit/fastify";
+import { z } from "zod";
+var COMMENTS = createToken("comments");
+function commentsPlugin(options = {}) {
+  return definePlugin({
+    name: "basalt:comments",
+    register({ container, hooks }) {
+      container.singleton(COMMENTS, () => new Comments({ ...options, hooks }));
+    }
+  });
+}
+var CommentForbiddenError = class extends BasaltError2 {
+  status = 403;
+  constructor() {
+    super("COMMENT_FORBIDDEN", "You can only modify your own comments.");
+  }
+};
+var UserRequiredError = class extends BasaltError2 {
+  status = 401;
+  constructor() {
+    super("AUTH_REQUIRED", "Authentication required.");
+  }
+};
+var comments = () => ctx().container.get(COMMENTS);
+var currentUser = () => {
+  const id = ctx().user?.id;
+  if (!id) throw new UserRequiredError();
+  return id;
+};
+var assertAuthor = async (id) => {
+  const comment = await comments().get(id);
+  if (!comment || comment.authorId !== currentUser()) throw new CommentForbiddenError();
+};
+function commentRoutes() {
+  const resource = z.object({ resourceType: z.string().min(1), resourceId: z.string().min(1) });
+  return [
+    route({
+      method: "GET",
+      url: "/comments",
+      meta: { auth: true },
+      query: resource,
+      async handler({ query }) {
+        return comments().on(query.resourceType, query.resourceId).tree();
+      }
+    }),
+    route({
+      method: "POST",
+      url: "/comments",
+      meta: { auth: true },
+      body: resource.extend({ body: z.string().min(1), parentId: z.string().optional() }),
+      async handler({ body, reply }) {
+        const created = await comments().on(body.resourceType, body.resourceId).add({ authorId: currentUser(), body: body.body, ...body.parentId ? { parentId: body.parentId } : {} });
+        return reply.code(201).send(created);
+      }
+    }),
+    route({
+      method: "PATCH",
+      url: "/comments/:id",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      body: z.object({ body: z.string().min(1) }),
+      async handler({ params, body }) {
+        await assertAuthor(params.id);
+        return comments().edit(params.id, body.body);
+      }
+    }),
+    route({
+      method: "DELETE",
+      url: "/comments/:id",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      async handler({ params, reply }) {
+        await assertAuthor(params.id);
+        await comments().remove(params.id);
+        return reply.code(204).send();
+      }
+    }),
+    route({
+      method: "POST",
+      url: "/comments/:id/resolve",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      async handler({ params }) {
+        return comments().resolve(params.id, currentUser());
+      }
+    }),
+    route({
+      method: "POST",
+      url: "/comments/:id/reopen",
+      meta: { auth: true },
+      params: z.object({ id: z.string() }),
+      async handler({ params }) {
+        return comments().reopen(params.id);
+      }
+    })
+  ];
+}
+export {
+  COMMENTS,
+  CommentNotFoundError,
+  CommentTenantRequiredError,
+  Comments,
+  MemoryCommentStore,
+  commentRoutes,
+  commentsPlugin
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@basaltkit/comments",
+  "version": "1.0.0",
+  "description": "Comments for Basalt: per-resource threads with @mentions and resolve/reopen, tenant-scoped, emitting events that bridge to realtime and notifications.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/fastify": "^1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.24.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "zod": "^3.24.0",
+    "@basaltkit/auth": "^1.0.0",
+    "@basaltkit/tenancy": "^1.0.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/comments"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/comments#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "saas",
+    "comments",
+    "threads",
+    "mentions"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}