@kernhq/module-quire 0.2.0 → 0.3.0

package/migrations/meta/0002_snapshot.json

@@ -0,0 +1,491 @@
+{
+  "id": "09606cee-18e2-41eb-b1a6-44a2bf9856cb",
+  "prevId": "73e5ffbb-8a14-4b41-bdfd-776e51bec7d7",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "mod_quire.page_versions": {
+      "name": "page_versions",
+      "schema": "mod_quire",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page_id": {
+          "name": "page_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "label": {
+          "name": "label",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "state": {
+          "name": "state",
+          "type": "bytea",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "snapshot": {
+          "name": "snapshot",
+          "type": "bytea",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "size": {
+          "name": "size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "author_id": {
+          "name": "author_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "page_versions_ws_page_idx": {
+          "name": "page_versions_ws_page_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "page_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "page_versions_ws_created_idx": {
+          "name": "page_versions_ws_created_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "mod_quire.pages": {
+      "name": "pages",
+      "schema": "mod_quire",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "space_id": {
+          "name": "space_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parent_id": {
+          "name": "parent_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "position": {
+          "name": "position",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'page'"
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_url": {
+          "name": "cover_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_version_id": {
+          "name": "published_version_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "has_unpublished_changes": {
+          "name": "has_unpublished_changes",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_by": {
+          "name": "updated_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "pages_ws_space_idx": {
+          "name": "pages_ws_space_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "space_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "pages_ws_parent_idx": {
+          "name": "pages_ws_parent_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "pages_ws_updated_idx": {
+          "name": "pages_ws_updated_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "mod_quire.spaces": {
+      "name": "spaces",
+      "schema": "mod_quire",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "visibility": {
+          "name": "visibility",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'open'"
+        },
+        "homepage_id": {
+          "name": "homepage_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "spaces_ws_key_uq": {
+          "name": "spaces_ws_key_uq",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "spaces_ws_idx": {
+          "name": "spaces_ws_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {
+    "mod_quire": "mod_quire"
+  },
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/migrations/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1787566824449,
       "tag": "0001_rls",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1787572772745,
+      "tag": "0002_page_versions",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-quire",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Kern Quire: collaborative documents, spaces and page trees",
   "homepage": "https://kernaio.com",
   "license": "AGPL-3.0-only",

package/src/client/index.ts

@@ -1,6 +1,7 @@
+import { formatCollabDocument } from '@kernhq/contracts'
 import { createModuleClient, type KernClientOptions } from '@kernhq/sdk'
 import type { ContractRouterClient } from '@orpc/contract'
-import type { PageNode, QuireContract } from '../contract/index.js'
+import { MODULE_ID, type Page, type PageNode, type QuireContract } from '../contract/index.js'
 
 /**
  * The client half.
@@ -33,6 +34,22 @@ export {
 } from '../contract/index.js'
 export * from './rank.js'
 
+/**
+ * The name this page's prose is synchronised under, on the collab service.
+ *
+ * Exported here rather than left to the caller because the gateway parses it with the matching
+ * function from `@kernhq/contracts`, and a name it cannot parse is a rejected connection with no
+ * useful error. The module owns the naming of its own objects.
+ */
+export function pageDocumentName(page: { workspaceId: Page['workspaceId']; id: string }): string {
+  return formatCollabDocument({
+    workspaceId: page.workspaceId,
+    module: MODULE_ID,
+    type: 'page',
+    objectId: page.id,
+  })
+}
+
 /** The permission keys, so the app gates on a constant rather than a string it retyped. */
 export const QUIRE_PERMISSIONS = {
   spaceView: 'quire.space.view',

package/src/contract/events.ts

@@ -17,6 +17,11 @@ export const quireEvents = {
   pageArchived: defineEvent('quire.page.archived', page.extend({ archived: z.boolean() })),
   pageTrashed: defineEvent('quire.page.trashed', page.extend({ count: z.number().int().nonnegative() })),
   pageRestored: defineEvent('quire.page.restored', page),
+  pagePublished: defineEvent('quire.page.published', page.extend({ versionId: Id })),
+  pageRestoredVersion: defineEvent(
+    'quire.page.restored_version',
+    z.object({ pageId: Id, workspaceId: WorkspaceId, versionId: Id }),
+  ),
   /** 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/models.ts

@@ -90,4 +90,27 @@ export const PageNode = z.object({
 })
 export type PageNode = z.infer<typeof PageNode>
 
+/**
+ * How a version came to exist. `restore` matters: putting an older version back writes a new
+ * version rather than rewinding, so restoring is never itself the thing that loses work.
+ */
+export const VersionKind = z.enum(['auto', 'publish', 'restore', 'import'])
+export type VersionKind = z.infer<typeof VersionKind>
+
+export const PageVersion = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  pageId: Id,
+  kind: VersionKind,
+  label: z.string().max(120).nullable(),
+  /** the first line or so of the prose, so a list reads without loading a document */
+  preview: z.string(),
+  size: z.number().int().nonnegative(),
+  authorId: UserId.nullable(),
+  createdAt: Timestamp,
+  /** whether this is the version a reader is currently served */
+  published: z.boolean(),
+})
+export type PageVersion = z.infer<typeof PageVersion>
+
 export const Ok = z.object({ ok: z.literal(true) })

package/src/contract/permissions.ts

@@ -48,6 +48,14 @@ export const quirePermissions = definePermissions([
     defaultRoles: ['owner', 'admin', 'member'],
     dangerous: false,
   },
+  {
+    key: 'quire.page.publish',
+    label: 'Publish pages',
+    description: 'Decide which version readers and any public site are served',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
   {
     key: 'quire.page.delete',
     label: 'Delete pages permanently',

package/src/contract/router.ts

@@ -1,6 +1,6 @@
 import { baseContract, Id, PageInput, page, WorkspaceId } from '@kernhq/contracts'
 import { z } from 'zod'
-import { Ok, Page, PageKind, PageNode, Space, SpaceVisibility } from './models.js'
+import { Ok, Page, PageKind, PageNode, PageVersion, Space, SpaceVisibility } from './models.js'
 
 const ws = z.object({ workspaceId: WorkspaceId })
 const t = (...tags: string[]) => ({ tags })
@@ -115,6 +115,44 @@ export const quireContract = {
       .input(ws.extend({ pageId: Id }))
       .output(z.object({ ok: z.literal(true), count: z.number().int().nonnegative() })),
   },
+
+  versions: {
+    list: baseContract
+      .route({ method: 'GET', path: '/pages/{pageId}/versions', ...t('versions') })
+      .input(ws.extend({ pageId: Id }).extend(PageInput.shape))
+      .output(page(PageVersion)),
+    /** The prose of one version, rendered as text — enough to read it and to diff it. */
+    get: baseContract
+      .route({ method: 'GET', path: '/versions/{versionId}', ...t('versions') })
+      .input(ws.extend({ versionId: Id }))
+      .output(PageVersion.extend({ text: z.string() })),
+    /** Take one now, and give it a name. */
+    create: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/versions', ...t('versions') })
+      .input(ws.extend({ pageId: Id, label: z.string().min(1).max(120).nullable().default(null) }))
+      .output(PageVersion),
+    /**
+     * Put an older version back. It is applied to the live document rather than written behind the
+     * people editing it, and the state it replaced is kept as a version of its own first.
+     */
+    restore: baseContract
+      .route({ method: 'POST', path: '/versions/{versionId}/restore', ...t('versions') })
+      .input(ws.extend({ versionId: Id }))
+      .output(PageVersion),
+  },
+
+  publishing: {
+    /** Make what is written now the version readers are served. Only meaningful for a `page`. */
+    publish: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/publish', ...t('publishing') })
+      .input(ws.extend({ pageId: Id, label: z.string().min(1).max(120).nullable().default(null) }))
+      .output(Page),
+    /** Throw the draft away and go back to what readers can already see. */
+    revert: baseContract
+      .route({ method: 'POST', path: '/pages/{pageId}/revert', ...t('publishing') })
+      .input(ws.extend({ pageId: Id }))
+      .output(Page),
+  },
 } as const
 export type QuireContract = typeof quireContract