@kernhq/module-quire 0.13.1 → 0.15.0

package/src/contract/router.ts

@@ -3,7 +3,12 @@ import { z } from 'zod'
 import {
   CommentAnchor,
   CommentThread,
+  ExportFormat,
+  ExportJob,
+  ExportScope,
   Favorite,
+  ImportJob,
+  ImportSource,
   Label,
   LabelColour,
   Ok,
@@ -17,6 +22,10 @@ import {
   RichDoc,
   Space,
   SpaceVisibility,
+  Template,
+  TemplateKind,
+  TemplateStarterKey,
+  TemplateVariable,
 } from './models.js'
 import {
   Database,
@@ -184,6 +193,34 @@ export type PublicSearchHit = z.infer<typeof PublicSearchHit>
 
 export const PublicSitemapEntry = z.object({ path: z.string(), lastModified: Timestamp })
 
+/**
+ * An export job, plus the one thing that cannot be stored on it: a link to the artefact.
+ *
+ * `downloadUrl` is minted per request and is null in every state but `done`. It is composed here
+ * rather than written into `export_jobs` because a signed storage URL is the object's key, so a
+ * stored one is both an address that leaks the workspace and file uuids and an address that stops
+ * working an hour later — and, worse, a fence applied once at the moment the job finished rather
+ * than every time somebody asks. A subtree export flattens pages of different readerships into one
+ * file, so the moment of the fetch is the moment that has to be checked.
+ */
+export const ExportJobDetail = ExportJob.extend({ downloadUrl: z.string().nullable() })
+export type ExportJobDetail = z.infer<typeof ExportJobDetail>
+
+/**
+ * An import job **without its report**, which is the only shape a list can afford to carry.
+ *
+ * The report is one row per file, and a Notion export is thousands of files — so twenty jobs in a
+ * list is a response of megabytes to draw a table of dates and states. `get` carries the whole thing
+ * because that screen is somebody looking at one import and asking what happened to their files,
+ * which is the question the report exists to answer.
+ *
+ * Omitted rather than truncated on purpose. A report cut off at fifty rows is one that has quietly
+ * stopped being the complete account of the archive, and a person reading "23 skipped" beside a list
+ * of twelve would have no way to know which. Absent is a state a client can render; incomplete is not.
+ */
+export const ImportJobSummary = ImportJob.omit({ report: true })
+export type ImportJobSummary = z.infer<typeof ImportJobSummary>
+
 /**
  * One picture from a published page, **as bytes rather than as an address**.
  *
@@ -254,6 +291,77 @@ export const PublicBasePath = z
  */
 export const PUBLIC_ASSET_SEGMENT = '__media'
 
+/**
+ * One row of the picker: a shipped starter, or a template somebody saved.
+ *
+ * The two are one list on purpose. A person choosing what to write does not care which of them came
+ * with Kern, so a screen that draws "Templates" and "Your templates" as separate sections is asking
+ * them to know something about our packaging — and it makes the override rule invisible, because a
+ * starter a workspace has edited would appear in the second list while its shipped twin sat in the
+ * first.
+ *
+ * **`id` is null for a shipped starter, and that is the whole shape of the compromise.** A starter is
+ * a constant in the module rather than a row in the customer's database — `migrations/0011` argues
+ * why at length — so there is no row for it to have an id, and `key` is what addresses it instead.
+ * `instantiate` therefore takes one of the two and refuses both.
+ *
+ * `name` and `description` arrive **already in the reader's language**. A starter's strings are a
+ * table in the module resolved against `principal.locale`, so a client renders whatever it is given
+ * and never has to know which entries are ours.
+ */
+export const TemplateChoice = z.object({
+  /** null for a shipped starter — a constant has no row, so it has no id */
+  id: Id.nullable(),
+  /**
+   * The starter this entry is, or replaces; null for somebody's own template.
+   *
+   * A row carrying a key **stands in for** that starter rather than appearing beside it, so this
+   * list never contains two entries with the same key.
+   */
+  key: z.string().nullable(),
+  builtIn: z.boolean(),
+  kind: TemplateKind,
+  spaceId: Id.nullable(),
+  name: z.string(),
+  description: z.string(),
+  icon: z.string().nullable(),
+  variables: z.array(TemplateVariable),
+  /** null for a shipped starter nobody has edited — it has no row and therefore no history */
+  updatedAt: Timestamp.nullable(),
+})
+export type TemplateChoice = z.infer<typeof TemplateChoice>
+
+/**
+ * What somebody typed into the form a template asked for.
+ *
+ * Strings whatever the variable's type, because substitution is textual: a `date` variable puts
+ * characters into a paragraph exactly as a `text` one does, and the type only ever decided which
+ * control the person was shown. Storing a number here would mean the server deciding how to format
+ * it, in a locale it would have to guess.
+ *
+ * A key naming no declared variable is ignored rather than refused — a client one release ahead is
+ * a normal thing during a rolling deploy, and refusing the whole page over a spare field is not.
+ */
+export const TemplateValues = z.record(z.string().max(40), z.string().max(2000))
+
+/**
+ * What making something from a template produced.
+ *
+ * One shape for both kinds, rather than `Page` for one and `Space` for the other. The caller's next
+ * move is the same either way — open what was just made — and a union output would make every
+ * client branch on `kind` to find out where to navigate. `pageCount` is what the screen reports:
+ * a space template that made eleven pages should say so, because that is a lot of pages to have
+ * appeared in a sidebar without warning.
+ */
+export const TemplateResult = z.object({
+  /** the new space, for a space template; the space the new page landed in otherwise */
+  spaceId: Id,
+  /** what to open: the new page, or the first page of the new space's tree. Null for an empty tree. */
+  pageId: Id.nullable(),
+  pageCount: z.number().int().nonnegative(),
+})
+export type TemplateResult = z.infer<typeof TemplateResult>
+
 export const quireContract = {
   spaces: {
     list: baseContract
@@ -694,6 +802,159 @@ export const quireContract = {
       .output(Ok),
   },
 
+  /**
+   * What somebody writes with: a page, or a whole space, saved so it can be made again.
+   *
+   * **The five starters Kern ships are constants in this module, not rows in a customer's
+   * database.** `migrations/0011_templates.sql` argues that at length; the consequences visible from
+   * here are three. `list` answers starters and rows in one list, with a row carrying a starter's
+   * `key` standing *in place of* that starter rather than beside it. A starter has no id, so
+   * `instantiate` takes `templateId` **or** `starterKey` and refuses both. And `get`, `update` and
+   * `remove` take an id, which means they are about rows only — a starter has nothing to fetch or
+   * delete, and "reset this one" is deleting the row that replaced it.
+   *
+   * Reading is `quire.space.view` and writing is `quire.space.manage`, exactly as `labels.*` next
+   * door, and for the same reason: a template is part of a space's furniture rather than one page's
+   * content. Changing it changes what everybody in the space is offered when they make a page, which
+   * is not a thing somebody who may edit one page should be able to do to everybody else's.
+   *
+   * `instantiate` is the exception and asks `quire.page.create`, because what it does is make a
+   * page. Somebody who may write in a space may use its templates; only somebody who configures the
+   * space may change them.
+   */
+  templates: {
+    /**
+     * What may be made here: the starters, plus this workspace's own, with overrides applied.
+     *
+     * `spaceId` is the space being written into, and null asks the workspace-wide question — which
+     * is what the "New space" picker needs, because there is no space yet. With a space named, the
+     * answer is that space's templates *and* the workspace-wide ones: a template scoped to a space
+     * is an addition to what is offered there, never a replacement for what is offered everywhere.
+     *
+     * No body comes back. Thirty page documents to draw thirty names is thirty documents nobody
+     * reads — see `TemplateSummary`. `instantiate` is what reads one.
+     */
+    list: baseContract
+      .route({ method: 'GET', path: '/templates', ...t('templates') })
+      .input(
+        ws.extend({
+          kind: TemplateKind.default('page'),
+          /** the space a page would be made in; null asks only what is offered everywhere */
+          spaceId: Id.nullable().default(null),
+        }),
+      )
+      .output(z.array(TemplateChoice)),
+    /**
+     * One saved template, body and all — what the edit screen loads.
+     *
+     * Rows only. A starter has no row, and inventing an id for it would make every other procedure
+     * here have to tell the two kinds of id apart.
+     */
+    get: baseContract
+      .route({ method: 'GET', path: '/templates/{templateId}', ...t('templates') })
+      .input(ws.extend({ templateId: Id }))
+      .output(Template),
+    /**
+     * Save what is written now as a template.
+     *
+     * `sourceId` names the page for `kind: 'page'` and the **space** for `kind: 'space'`, the same
+     * shape as `exports.start`'s `targetId` and for the same reason: the two kinds have nothing in
+     * common to point at, and two nullable id fields would let a caller send both. The procedure is
+     * named for the common case; a space template reads the space's whole tree.
+     *
+     * `key` is what makes a starter editable at all. Passing one writes a row that **replaces** that
+     * starter in this workspace's picker; deleting the row brings the shipped one back, current and
+     * translated. One row per starter per workspace — the second is a conflict, not a second entry.
+     */
+    createFromPage: baseContract
+      .route({ method: 'POST', path: '/templates', ...t('templates') })
+      .input(
+        ws.extend({
+          kind: TemplateKind.default('page'),
+          /** the page for `page`; the space for `space` — `kind` says which */
+          sourceId: Id,
+          /** null offers it everywhere in the workspace; a space id scopes it to that space */
+          spaceId: Id.nullable().default(null),
+          name: z.string().min(1).max(120),
+          description: z.string().max(2000).default(''),
+          icon: z.string().max(64).nullable().default(null),
+          variables: z.array(TemplateVariable).max(25).default([]),
+          /** replace this shipped starter rather than sitting beside it */
+          key: TemplateStarterKey.nullable().default(null),
+        }),
+      )
+      .output(Template),
+    /**
+     * Rename it, re-scope it, change what it asks for — or replace its body with a page's.
+     *
+     * `sourceId` is three-valued like `publications.update`'s password: a page (or space) id takes
+     * the body from there again, and leaving the key out changes nothing. Without that, updating a
+     * template's name would be a separate act from updating its prose, and the second one would have
+     * no procedure at all.
+     */
+    update: baseContract
+      .route({ method: 'PATCH', path: '/templates/{templateId}', ...t('templates') })
+      .input(
+        ws.extend({
+          templateId: Id,
+          name: z.string().min(1).max(120).optional(),
+          description: z.string().max(2000).optional(),
+          icon: z.string().max(64).nullable().optional(),
+          spaceId: Id.nullable().optional(),
+          variables: z.array(TemplateVariable).max(25).optional(),
+          /** take the body from this page (or space) again; omit to leave the body alone */
+          sourceId: Id.optional(),
+        }),
+      )
+      .output(Template),
+    /**
+     * Delete it. For a row that replaced a starter this is "reset": the shipped one comes back.
+     *
+     * Nothing made from a template is touched — a page is a page once it exists, and a template that
+     * took its pages with it would be a delete nobody could afford to press.
+     */
+    remove: baseContract
+      .route({ method: 'DELETE', path: '/templates/{templateId}', ...t('templates') })
+      .input(ws.extend({ templateId: Id }))
+      .output(Ok),
+    /**
+     * Make the thing: a page, or a whole space and its tree.
+     *
+     * Exactly one of `templateId` and `starterKey` — a starter is a constant with no id, and a
+     * union input would be a shape oRPC has to route. Both, or neither, is a bad request.
+     *
+     * `values` fills what the template declared. `{{date}}`, `{{time}}`, `{{author}}` and
+     * `{{space}}` are filled by the server from the request and are declared by nobody; a name the
+     * template never declared is left in the page as it was written, because deleting text somebody
+     * typed is worse than showing them a placeholder they can see and fix.
+     *
+     * Substitution happens **in text, never in JSON**. A value containing a quote, a brace or a
+     * newline is characters in a paragraph and cannot be anything else — see `services/templates.ts`.
+     */
+    instantiate: baseContract
+      .route({ method: 'POST', path: '/templates/instantiate', ...t('templates') })
+      .input(
+        ws.extend({
+          /** a saved template; null when `starterKey` names a shipped one */
+          templateId: Id.nullable().default(null),
+          /** a shipped starter; null when `templateId` names a saved one */
+          starterKey: TemplateStarterKey.nullable().default(null),
+          /** the space to write into, for a page template. Ignored for a space template. */
+          spaceId: Id.nullable().default(null),
+          /** where the new page hangs, for a page template */
+          parentId: Id.nullable().default(null),
+          afterId: Id.nullable().default(null),
+          /** what the new page is called; empty takes the template's own name */
+          title: z.string().max(300).default(''),
+          /** the new space's key and name, for a space template */
+          key: Space.shape.key.nullable().default(null),
+          name: z.string().max(120).default(''),
+          values: TemplateValues.default({}),
+        }),
+      )
+      .output(TemplateResult),
+  },
+
   publishing: {
     /** Make what is written now the version readers are served. Only meaningful for a `page`. */
     publish: baseContract
@@ -781,6 +1042,120 @@ export const quireContract = {
       .output(z.object({ pageId: Id, excluded: z.boolean() })),
   },
 
+  /**
+   * Taking work out: a page, a page and everything under it, or a whole space, as a file.
+   *
+   * Three procedures and no fourth, which is the shape worth explaining. There is no `download`:
+   * `get` carries a `downloadUrl` it mints as it answers, so the permission is checked on the
+   * request that fetches the file rather than baked into a link that outlives the check. And there
+   * is no `cancel`: a job either finishes or fails, both terminal, and a cancel that races a worker
+   * writing an artefact is a way to end up with an object nothing points at.
+   *
+   * **What the artefact contains is decided by the job, not by the caller.** `start` names a scope
+   * and a format; every page under that scope is then checked against the requester's own
+   * `quire.page.view`, and a page they may not read is left out and counted in `skipped`. So a
+   * subtree export by somebody with a page-scoped DENY is a smaller file, not a refusal — and
+   * `counts.skipped` is how they find out, which is the difference between an export that is quietly
+   * missing pages and one that says how many.
+   *
+   * `format: 'docx'` is declared in `ExportFormat` and refused by `start` today: see the note in
+   * `services/export.ts` for what makes a *correct* Word file more than a matter of effort, and why
+   * a refusal is better than a document that may not open.
+   */
+  exports: {
+    /** Queue one. The answer is a row to watch, never the file — see the note above. */
+    start: baseContract
+      .route({ method: 'POST', path: '/exports', ...t('exports') })
+      .input(
+        ws.extend({
+          scope: ExportScope,
+          /** the page for `page` and `subtree`, the space for `space`; `scope` says which */
+          targetId: Id,
+          format: ExportFormat,
+        }),
+      )
+      .output(ExportJobDetail),
+    /** Where it has got to, and — once it is `done` — a link that is good for a few minutes. */
+    get: baseContract
+      .route({ method: 'GET', path: '/exports/{jobId}', ...t('exports') })
+      .input(ws.extend({ jobId: Id }))
+      .output(ExportJobDetail),
+    /**
+     * This person's own exports, newest first.
+     *
+     * Deliberately not the workspace's. Row-level security fences the tenant, which is not a privacy
+     * boundary, so the `requested_by` filter in the query is the only thing that keeps one person's
+     * export of the salary handbook out of everybody else's list — the same rule `favorites.list`
+     * and `recents.list` follow.
+     */
+    list: baseContract
+      .route({ method: 'GET', path: '/exports', ...t('exports') })
+      .input(ws.extend({ limit: z.number().int().min(1).max(50).default(20) }))
+      .output(z.array(ExportJob)),
+  },
+
+  /**
+   * Getting work in: a Notion export, a Confluence export or a folder of Markdown, into one space.
+   *
+   * **The failure list is the feature.** A real export has files that will not map — an attachment,
+   * a `.csv` with no header, a page whose link points outside what was exported — and an import that
+   * silently drops forty pages is worse than one that refuses. So every file in the archive gets a
+   * row in `report` saying whether it became a page, was deliberately left out, or could not be read,
+   * and `counts.total` is exactly the number of rows: nothing in the archive goes unaccounted for.
+   *
+   * Three things follow from the archive being read whole before anything is written, and each is
+   * worth knowing before reading the handlers:
+   *
+   *   - **an import is all or nothing.** A zip that fails half way leaves the space exactly as it
+   *     was, because the plan is built in memory and written in one transaction;
+   *   - **links between imported pages are rewritten to Quire page ids**, which needs every id to
+   *     exist before any body is resolved — a link to a page further down the archive is the normal
+   *     case, not the exception. A link that resolves to nothing becomes plain text rather than a
+   *     dead link, and the report names the target it could not find;
+   *   - **a `.csv` becomes a database with typed columns**, guessed from the values and reported.
+   *
+   * `quire.page.import` is `dangerous`, as the tracker marks its own imports: this is the one thing
+   * in the module that writes hundreds of pages into a space in one act, and it is not undone by
+   * pressing something.
+   */
+  imports: {
+    /**
+     * Queue one. The answer is a row to watch; nothing has been written to the space yet.
+     *
+     * `fileId` is an upload — a core file the browser has already put in place — and not the archive
+     * itself. A zip is up to a few hundred megabytes, which is a file to be uploaded and then named,
+     * never a request body.
+     */
+    start: baseContract
+      .route({ method: 'POST', path: '/imports', ...t('imports') })
+      .input(
+        ws.extend({
+          /** the space being written into; an import always targets exactly one */
+          spaceId: Id,
+          source: ImportSource,
+          /** the uploaded archive, and not something this job produces — see `ImportJob` */
+          fileId: Id,
+        }),
+      )
+      .output(ImportJob),
+    /** Where it has got to, and — once it has finished — what happened to every file in it. */
+    get: baseContract
+      .route({ method: 'GET', path: '/imports/{jobId}', ...t('imports') })
+      .input(ws.extend({ jobId: Id }))
+      .output(ImportJob),
+    /**
+     * This person's own imports, newest first, without their reports — see `ImportJobSummary`.
+     *
+     * Deliberately not the workspace's, for the same reason `exports.list` is not: row-level security
+     * fences the tenant, which is not a privacy boundary, so the `requested_by` filter in the query
+     * is the only thing that keeps one person's import out of everybody else's list.
+     */
+    list: baseContract
+      .route({ method: 'GET', path: '/imports', ...t('imports') })
+      .input(ws.extend({ limit: z.number().int().min(1).max(50).default(20) }))
+      .output(z.array(ImportJobSummary)),
+  },
+
   /**
    * The signed-out surface. **This is the only part of Kern with no principal behind it.**
    *