@kernhq/module-quire 0.3.0 → 0.4.0

package/src/contract/events.ts

@@ -22,6 +22,10 @@ export const quireEvents = {
     'quire.page.restored_version',
     z.object({ pageId: Id, workspaceId: WorkspaceId, versionId: Id }),
   ),
+  commentCreated: defineEvent(
+    'quire.comment.created',
+    z.object({ commentId: Id, pageId: Id, workspaceId: WorkspaceId }),
+  ),
   /** The page and its descendants are gone; anything holding a reference should drop it. */
   pageDeleted: defineEvent('quire.page.deleted', page.extend({ pageIds: z.array(Id) })),
 } as const

package/src/contract/index.ts

@@ -1,5 +1,6 @@
 export * from './capabilities.js'
 export * from './events.js'
 export * from './models.js'
+export * from './notifications.js'
 export * from './permissions.js'
 export * from './router.js'

package/src/contract/models.ts

@@ -113,4 +113,52 @@ export const PageVersion = z.object({
 })
 export type PageVersion = z.infer<typeof PageVersion>
 
+/**
+ * Where a comment is attached, as **Yjs relative positions**.
+ *
+ * Not character offsets: an offset names a place that only exists while nobody else is typing, and
+ * two words inserted above would move a comment onto text it was never about. A relative position
+ * points at the content rather than the index, so it survives concurrent editing — which is the
+ * whole reason a comment on a collaborative document is harder than a comment on a row.
+ */
+export const CommentAnchor = z.object({
+  /** base64 `Y.encodeRelativePosition` */
+  from: z.base64(),
+  to: z.base64(),
+})
+export type CommentAnchor = z.infer<typeof CommentAnchor>
+
+/** A Tiptap/ProseMirror document. Kept opaque here; the renderer is what knows its shape. */
+export const RichDoc = z.record(z.string(), z.unknown())
+
+export const Comment = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  pageId: Id,
+  parentId: Id.nullable(),
+  threadId: Id,
+  authorId: UserId.nullable(),
+  body: RichDoc,
+  bodyText: z.string(),
+  mentionIds: z.array(UserId),
+  /** null for a comment about the page rather than a piece of it */
+  anchor: CommentAnchor.nullable(),
+  /** what the anchor pointed at when it was written, so a thread whose text is gone still reads */
+  quotedText: z.string(),
+  resolvedAt: Timestamp.nullable(),
+  resolvedBy: UserId.nullable(),
+  editedAt: Timestamp.nullable(),
+  createdAt: Timestamp,
+})
+export type Comment = z.infer<typeof Comment>
+
+/** A root comment and its replies, which is how a page's margin is actually read. */
+export const CommentThread = z.object({
+  id: Id,
+  root: Comment,
+  replies: z.array(Comment),
+  resolved: z.boolean(),
+})
+export type CommentThread = z.infer<typeof CommentThread>
+
 export const Ok = z.object({ ok: z.literal(true) })

package/src/contract/notifications.ts

@@ -0,0 +1,17 @@
+import type { core } from '@kernhq/contracts'
+
+/**
+ * What Quire can put in somebody's inbox.
+ *
+ * Declared rather than invented at the call site: the inbox renders a notification from its type,
+ * and one that was never declared arrives as a blank row.
+ */
+export const quireNotificationTypes: core.NotificationTypeDef[] = [
+  {
+    type: 'quire.mention',
+    label: 'Mentioned in a page comment',
+    description: 'Somebody named you in a remark on a page',
+    defaults: { inapp: true, push: true, email: false },
+    urgent: false,
+  },
+]

package/src/contract/permissions.ts

@@ -48,6 +48,14 @@ export const quirePermissions = definePermissions([
     defaultRoles: ['owner', 'admin', 'member'],
     dangerous: false,
   },
+  {
+    key: 'quire.page.comment',
+    label: 'Comment on pages',
+    description: 'Leave a remark in the margin without being able to change the page',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member', 'guest'],
+    dangerous: false,
+  },
   {
     key: 'quire.page.publish',
     label: 'Publish pages',

package/src/contract/router.ts

@@ -1,6 +1,17 @@
 import { baseContract, Id, PageInput, page, WorkspaceId } from '@kernhq/contracts'
 import { z } from 'zod'
-import { Ok, Page, PageKind, PageNode, PageVersion, Space, SpaceVisibility } from './models.js'
+import {
+  CommentAnchor,
+  CommentThread,
+  Ok,
+  Page,
+  PageKind,
+  PageNode,
+  PageVersion,
+  RichDoc,
+  Space,
+  SpaceVisibility,
+} from './models.js'
 
 const ws = z.object({ workspaceId: WorkspaceId })
 const t = (...tags: string[]) => ({ tags })
@@ -141,6 +152,41 @@ export const quireContract = {
       .output(PageVersion),
   },
 
+  comments: {
+    /** Every open thread on a page, and optionally the resolved ones too. */
+    list: baseContract
+      .route({ method: 'GET', path: '/pages/{pageId}/comments', ...t('comments') })
+      .input(ws.extend({ pageId: Id, includeResolved: z.boolean().default(false) }))
+      .output(z.array(CommentThread)),
+    create: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/comments', ...t('comments') })
+      .input(
+        ws.extend({
+          pageId: Id,
+          body: RichDoc,
+          /** omit for a comment about the page rather than a piece of it */
+          anchor: CommentAnchor.nullable().default(null),
+          quotedText: z.string().max(2000).default(''),
+          /** reply to this comment; the thread is inferred from it */
+          parentId: Id.nullable().default(null),
+        }),
+      )
+      .output(CommentThread.shape.root),
+    update: baseContract
+      .route({ method: 'PATCH', path: '/comments/{commentId}', ...t('comments') })
+      .input(ws.extend({ commentId: Id, body: RichDoc }))
+      .output(CommentThread.shape.root),
+    remove: baseContract
+      .route({ method: 'DELETE', path: '/comments/{commentId}', ...t('comments') })
+      .input(ws.extend({ commentId: Id }))
+      .output(Ok),
+    /** Settle a thread. Resolving the root resolves the thread; it is not a per-reply state. */
+    resolve: baseContract
+      .route({ method: 'POST', path: '/comments/{commentId}/resolve', ...t('comments') })
+      .input(ws.extend({ commentId: Id, resolved: z.boolean().default(true) }))
+      .output(CommentThread),
+  },
+
   publishing: {
     /** Make what is written now the version readers are served. Only meaningful for a `page`. */
     publish: baseContract