@sixb/core 0.1.21 → 0.1.22

package/src/artifacts/workbook.ts

@@ -1,9 +1,14 @@
+import { FormulaSyntaxError, parseFormula } from "./formula/parser"
 import { ARTIFACT_LIMITS } from "./limits"
+import { isArtifactQueryName } from "./queries"
+import { ARTIFACT_TONES, type ArtifactTone, isArtifactTone } from "./tones"
 
 /**
  * A sheet artifact is `workbook.json` and one CSV per sheet under `sheets/`. The CSV holds the
  * values; the workbook holds what CSV can't: sheet order, column types and formats, frozen rows
- * and columns, widths, and charts drawn from the sheets. Formulas belong in an `.xlsx` file.
+ * and columns, widths, descriptions and totals, computed columns' formulas, and charts drawn from
+ * the sheets. A live sheet has no CSV: its rows are one of the version's queries', as each reader
+ * reads them.
  */
 export const WORKBOOK_FILE = "workbook.json"
 
@@ -15,21 +20,48 @@ export const SHEET_COLUMN_TYPES = [
   "date",
   "link",
   "image",
+  "boolean",
+  "tag",
 ] as const
 export type SheetColumnType = (typeof SHEET_COLUMN_TYPES)[number]
 
 /** Column types whose cells are numbers, so a chart can plot them and a range can sum them. */
 export const NUMERIC_COLUMN_TYPES: readonly SheetColumnType[] = ["number", "currency", "percent"]
 
-export const SHEET_CHART_TYPES = ["bar", "line", "area", "pie"] as const
+/**
+ * How a numeric column's cells are shaded by value, across the column: a bar in the cell, a
+ * shade from light to dark, or two colors either side of zero.
+ */
+export const SHEET_HIGHLIGHTS = ["bars", "scale", "diverging"] as const
+export type SheetHighlight = (typeof SHEET_HIGHLIGHTS)[number]
+
+/** What a sheet's totals row shows under a column, over the rows the reader sees. */
+export const SHEET_TOTALS = ["sum", "average", "min", "max", "count"] as const
+export type SheetTotal = (typeof SHEET_TOTALS)[number]
+
+export const SHEET_CHART_TYPES = ["bar", "line", "area", "pie", "scatter"] as const
 export type SheetChartType = (typeof SHEET_CHART_TYPES)[number]
 
+/** How a chart summarizes rows that share an x value: one point or slice for each value. */
+export const SHEET_CHART_AGGREGATES = ["sum", "average", "count"] as const
+export type SheetChartAggregate = (typeof SHEET_CHART_AGGREGATES)[number]
+
 export interface SheetColumnFormat {
   readonly type: SheetColumnType
   /** An ISO 4217 code, for a currency column. */
   readonly currency?: string
   /** Digits after the decimal point, for numbers, currencies, and percents. */
   readonly decimals?: number
+  /** `1.2M` for `1,204,330`, for numbers and currencies. */
+  readonly compact?: boolean
+  /** A sign on positive values too, `+3.2%`, for numbers, currencies, and percents. */
+  readonly signed?: boolean
+  /** A tag column's colors by value; a value not named is neutral. */
+  readonly tones?: Readonly<Record<string, ArtifactTone>>
+  /** How a numeric column's cells are shaded by value. */
+  readonly highlight?: SheetHighlight
+  /** The formula that computes the column's every value, as an Excel table's column does. */
+  readonly formula?: string
 }
 
 export interface WorkbookSheet {
@@ -42,6 +74,35 @@ export interface WorkbookSheet {
   readonly columns: Readonly<Record<string, SheetColumnFormat>>
   /** Widths in pixels by column name. */
   readonly widths: Readonly<Record<string, number>>
+  /** What a column means, shown on its header, by column name. */
+  readonly descriptions: Readonly<Record<string, string>>
+  /** A totals row pinned under the rows: what each named column totals to. */
+  readonly totals: Readonly<Record<string, SheetTotal>>
+  /** Where a live sheet's rows and columns come from; a sheet without it holds its CSV's. */
+  readonly live?: LiveSheetSource
+}
+
+/**
+ * A live sheet's query and columns. Its columns are exactly those its workbook lists, in order,
+ * each showing a property of the rows or computed by a formula. A column whose type is its
+ * property's has no format in `columns` until the property's type is known: `liveSheetColumns`
+ * reads it then.
+ */
+export interface LiveSheetSource {
+  /** The query whose rows the sheet shows: `queries/<name>.json` in the version. */
+  readonly query: string
+  readonly columns: readonly LiveSheetColumnSource[]
+}
+
+export interface LiveSheetColumnSource {
+  readonly name: string
+  /**
+   * The property the column shows: a property id of the rows, or `<linkId>.<propertyId>` of a
+   * link the query expands. A computed column has none.
+   */
+  readonly from?: string
+  /** The column's format as written, when it gives no type: its property's type is its type. */
+  readonly untyped?: Readonly<Record<string, unknown>>
 }
 
 export interface WorkbookChart {
@@ -51,8 +112,15 @@ export interface WorkbookChart {
   readonly sheet: string
   /** The column along the x axis, or a pie's slice labels. */
   readonly x: string
-  /** The plotted columns: one series each, or a pie's one value column. */
+  /**
+   * The plotted columns: one series each, or a pie's one value column. Empty for a chart that
+   * counts rows.
+   */
   readonly y: readonly string[]
+  /** A bar chart's columns drawn as lines over its bars. */
+  readonly line: readonly string[]
+  /** Rows summarized by their x value, in the order the values first appear. */
+  readonly aggregate?: SheetChartAggregate
   readonly title?: string
   /** Stack a bar or area chart's series. */
   readonly stacked: boolean
@@ -71,7 +139,8 @@ export function sheetFilePath(sheetName: string): string {
 /**
  * Reads `workbook.json` into its full form: `"Revenue": "currency"` becomes
  * `{ type: "currency" }`, a single `y` becomes a list, and defaults are filled. Returns what is
- * wrong in words the author can act on. Whether the columns exist is checked against the CSVs.
+ * wrong in words the author can act on. Whether the columns exist is checked against the CSVs, and
+ * a live sheet's against its query.
  */
 export function parseWorkbook(
   text: string
@@ -111,6 +180,11 @@ export function parseSheetDate(value: string): Date | undefined {
 class WorkbookError extends Error {}
 
 const SHEET_NAME_MAX = 60
+const DESCRIPTION_MAX = 300
+const TONES_MAX = 20
+const TAG_MAX = 60
+const FORMULA_MAX = 500
+const COMPUTED_MAX = 20
 const CHART_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/
 const CONTROL = /[\u0000-\u001f\u007f]/
 
@@ -150,7 +224,16 @@ function readWorkbook(value: unknown): Workbook {
 
 function readSheet(value: unknown, index: number): WorkbookSheet {
   const at = `sheet ${index + 1}`
-  const input = record(value, at, ["name", "frozenRows", "frozenColumns", "columns", "widths"])
+  const input = record(value, at, [
+    "name",
+    "frozenRows",
+    "frozenColumns",
+    "columns",
+    "widths",
+    "descriptions",
+    "totals",
+    "query",
+  ])
   const name = typeof input.name === "string" ? input.name.trim() : ""
   if (
     !name ||
@@ -165,11 +248,28 @@ function readSheet(value: unknown, index: number): WorkbookSheet {
     )
   }
   const sheetAt = `sheet '${name}'`
+  const live = input.query === undefined ? undefined : readLiveSheet(input, sheetAt)
   const columns: Record<string, SheetColumnFormat> = {}
   for (const [column, format] of Object.entries(
     record(input.columns ?? {}, `${sheetAt} "columns"`, null)
   )) {
-    columns[column] = readColumnFormat(format, `${sheetAt} column '${column}'`)
+    const at = `${sheetAt} column '${column}'`
+    if (!live) {
+      columns[column] = readColumnFormat(format, at)
+      continue
+    }
+
+    // A live column's `from` is its source, not its format; without a type, its property's is.
+    const { from: _from, ...written } = format as Record<string, unknown>
+    if (written.type !== undefined || written.formula !== undefined) {
+      columns[column] = readColumnFormat(written, at)
+    }
+  }
+  const computed = Object.values(columns).filter((format) => format.formula).length
+  if (computed > COMPUTED_MAX) {
+    throw new WorkbookError(
+      `${sheetAt} computes ${computed} columns; a sheet computes at most ${COMPUTED_MAX}.`
+    )
   }
   const widths: Record<string, number> = {}
   for (const [column, width] of Object.entries(
@@ -182,18 +282,168 @@ function readSheet(value: unknown, index: number): WorkbookSheet {
     }
     widths[column] = width
   }
+  const descriptions: Record<string, string> = {}
+  for (const [column, description] of Object.entries(
+    record(input.descriptions ?? {}, `${sheetAt} "descriptions"`, null)
+  )) {
+    if (
+      typeof description !== "string" ||
+      !description.trim() ||
+      description.length > DESCRIPTION_MAX
+    ) {
+      throw new WorkbookError(
+        `${sheetAt} describes column '${column}' with ${JSON.stringify(description)}; a description is text of at most ${DESCRIPTION_MAX} characters.`
+      )
+    }
+    descriptions[column] = description.trim()
+  }
+  const totals: Record<string, SheetTotal> = {}
+  for (const [column, total] of Object.entries(
+    record(input.totals ?? {}, `${sheetAt} "totals"`, null)
+  )) {
+    if (!(SHEET_TOTALS as readonly unknown[]).includes(total)) {
+      throw new WorkbookError(
+        `${sheetAt} totals column '${column}' with ${JSON.stringify(total)}; use one of ${SHEET_TOTALS.join(", ")}.`
+      )
+    }
+    // A live column typed by its property is checked once its property's type is known, and one
+    // the sheet does not list once its columns are.
+    const deferred = live !== undefined && columns[column] === undefined
+    const problem = deferred
+      ? null
+      : sheetTotalProblem(sheetAt, column, total as SheetTotal, columns[column]?.type ?? "text")
+    if (problem) throw new WorkbookError(problem)
+    totals[column] = total as SheetTotal
+  }
   return {
     name,
     frozenRows: integer(input.frozenRows, 1, 0, 10, `${sheetAt} "frozenRows"`),
     frozenColumns: integer(input.frozenColumns, 0, 0, 5, `${sheetAt} "frozenColumns"`),
     columns,
     widths,
+    descriptions,
+    totals,
+    ...(live ? { live } : {}),
+  }
+}
+
+/** Why a column can't have its total, or null: only a numeric column has more than a count. */
+export function sheetTotalProblem(
+  sheetAt: string,
+  column: string,
+  total: SheetTotal,
+  type: SheetColumnType
+): string | null {
+  if (total === "count" || NUMERIC_COLUMN_TYPES.includes(type)) return null
+  return `${sheetAt} totals column '${column}' with "${total}", but it is ${type}; only a number, currency, or percent column has a ${total}. Use "count", or give it a numeric type in "columns".`
+}
+
+/** A JSON object puts a name such as `2024` before the others, whatever order it was written in. */
+const INDEX_NAME = /^(0|[1-9]\d{0,8})$/
+
+/**
+ * A live sheet's query and columns. Each column shows a property, `from`, or is computed, in the
+ * order `columns` lists them, so a name JSON would move is refused.
+ */
+function readLiveSheet(input: Record<string, unknown>, sheetAt: string): LiveSheetSource {
+  if (typeof input.query !== "string" || !isArtifactQueryName(input.query)) {
+    throw new WorkbookError(
+      `${sheetAt} "query" must name one of the version's queries, as queries/<name>.json names it: lowercase letters, digits and hyphens.`
+    )
+  }
+
+  const entries = Object.entries(record(input.columns ?? {}, `${sheetAt} "columns"`, null))
+  if (entries.length === 0) {
+    throw new WorkbookError(
+      `${sheetAt} reads query '${input.query}': list its columns in "columns", each with the property it shows in "from".`
+    )
+  }
+
+  const columns = entries.map(([name, value]): LiveSheetColumnSource => {
+    const at = `${sheetAt} column '${name}'`
+    if (INDEX_NAME.test(name)) {
+      throw new WorkbookError(
+        `${at}: a live sheet's columns come in the order "columns" lists them, and JSON puts a name of digits first. Name it with a letter, such as "FY${name}".`
+      )
+    }
+
+    if (typeof value === "string") {
+      throw new WorkbookError(
+        `${at} is ${JSON.stringify(value)}; a live sheet's column is an object, such as { "from": "amount", "type": "${value}" }.`
+      )
+    }
+    const column = record(value, at, [
+      "from",
+      "type",
+      "currency",
+      "decimals",
+      "compact",
+      "signed",
+      "tones",
+      "highlight",
+      "formula",
+    ])
+    if (column.from === undefined && column.formula === undefined) {
+      throw new WorkbookError(
+        `${at} shows nothing: give it "from", the property it shows, or a "formula".`
+      )
+    }
+    if (column.from !== undefined && column.formula !== undefined) {
+      throw new WorkbookError(
+        `${at} has both "from" and "formula": a column shows a property or computes, not both.`
+      )
+    }
+    if (column.from === undefined) return { name }
+
+    const from = column.from
+    const segments = typeof from === "string" ? from.split(".") : []
+    if (segments.length === 0 || segments.some((segment) => !segment)) {
+      throw new WorkbookError(
+        `${at} "from" must name a property of the rows, such as "amount", or of a link the query expands, such as "customer.name".`
+      )
+    }
+    if (segments.length > 2) {
+      throw new WorkbookError(
+        `${at} "from" is ${JSON.stringify(from)}; a column reads a property of the rows or of one link the query expands, such as "customer.name".`
+      )
+    }
+
+    const { from: _from, ...untyped } = column
+    return { name, from: from as string, ...(column.type === undefined ? { untyped } : {}) }
+  })
+
+  return { query: input.query, columns }
+}
+
+/**
+ * A column's format as `columns` writes it, for a column whose type `type` gives when the format
+ * names none: a live column's property's. Returns what is wrong in the words parsing uses.
+ */
+export function readSheetColumnFormat(
+  value: Readonly<Record<string, unknown>>,
+  at: string,
+  type: SheetColumnType
+): { readonly format: SheetColumnFormat } | { readonly error: string } {
+  try {
+    return { format: readColumnFormat({ type, ...value }, at) }
+  } catch (error) {
+    if (error instanceof WorkbookError) return { error: `${WORKBOOK_FILE}: ${error.message}` }
+    throw error
   }
 }
 
 function readColumnFormat(value: unknown, at: string): SheetColumnFormat {
   if (typeof value === "string") return { type: columnType(value, at) }
-  const input = record(value, at, ["type", "currency", "decimals"])
+  const input = record(value, at, [
+    "type",
+    "currency",
+    "decimals",
+    "compact",
+    "signed",
+    "tones",
+    "highlight",
+    "formula",
+  ])
   const type = columnType(input.type, at)
   if (input.currency !== undefined) {
     if (type !== "currency")
@@ -207,9 +457,85 @@ function readColumnFormat(value: unknown, at: string): SheetColumnFormat {
       `${at} sets "decimals" but is not a number, currency, or percent column.`
     )
   }
+  for (const [key, types, named] of [
+    ["compact", ["number", "currency"], "number or currency"],
+    ["signed", ["number", "currency", "percent"], "number, currency, or percent"],
+  ] as const) {
+    if (input[key] === undefined) continue
+    if (typeof input[key] !== "boolean") {
+      throw new WorkbookError(`${at} "${key}" must be true or false.`)
+    }
+    if (!(types as readonly string[]).includes(type)) {
+      throw new WorkbookError(`${at} sets "${key}" but is not a ${named} column.`)
+    }
+  }
+  let tones: Record<string, ArtifactTone> | undefined
+  if (input.tones !== undefined) {
+    if (type !== "tag") throw new WorkbookError(`${at} sets "tones" but is not a tag column.`)
+    tones = {}
+    const entries = Object.entries(record(input.tones, `${at} "tones"`, null))
+    if (entries.length > TONES_MAX) {
+      throw new WorkbookError(
+        `${at} "tones" names ${entries.length} values; it takes at most ${TONES_MAX}.`
+      )
+    }
+    for (const [tag, tone] of entries) {
+      if (!tag.trim() || tag.length > TAG_MAX) {
+        throw new WorkbookError(
+          `${at} "tones" names a value of ${tag.length} characters; a tag is 1 to ${TAG_MAX}.`
+        )
+      }
+      if (!isArtifactTone(tone)) {
+        throw new WorkbookError(
+          `${at} gives '${tag}' the tone ${JSON.stringify(tone)}; use one of ${ARTIFACT_TONES.join(", ")}.`
+        )
+      }
+      tones[tag] = tone as ArtifactTone
+    }
+  }
+  if (input.highlight !== undefined) {
+    if (!(SHEET_HIGHLIGHTS as readonly unknown[]).includes(input.highlight)) {
+      throw new WorkbookError(
+        `${at} "highlight" is ${JSON.stringify(input.highlight)}; use one of ${SHEET_HIGHLIGHTS.join(", ")}.`
+      )
+    }
+    if (!NUMERIC_COLUMN_TYPES.includes(type)) {
+      throw new WorkbookError(
+        `${at} sets "highlight" but is not a number, currency, or percent column.`
+      )
+    }
+  }
+  let formula: string | undefined
+  if (input.formula !== undefined) {
+    if (typeof input.formula !== "string" || !input.formula.trim()) {
+      throw new WorkbookError(`${at} "formula" must be text, such as "[@Revenue]-[@Cost]".`)
+    }
+    if (input.formula.length > FORMULA_MAX) {
+      throw new WorkbookError(
+        `${at} "formula" is ${input.formula.length} characters; a formula is at most ${FORMULA_MAX}.`
+      )
+    }
+    if (type === "link" || type === "image") {
+      throw new WorkbookError(`${at} is a ${type} column, which a formula can't compute.`)
+    }
+    formula = input.formula.trim().replace(/^=/, "")
+    try {
+      parseFormula(formula)
+    } catch (error) {
+      if (error instanceof FormulaSyntaxError) {
+        throw new WorkbookError(`${at} "formula" does not read: ${error.message}`)
+      }
+      throw error
+    }
+  }
   return {
     type,
     ...(typeof input.currency === "string" ? { currency: input.currency } : {}),
+    ...(formula ? { formula } : {}),
+    ...(input.compact === true ? { compact: true } : {}),
+    ...(input.signed === true ? { signed: true } : {}),
+    ...(tones ? { tones } : {}),
+    ...(input.highlight === undefined ? {} : { highlight: input.highlight as SheetHighlight }),
     ...(input.decimals === undefined
       ? {}
       : { decimals: integer(input.decimals, 0, 0, 6, `${at} "decimals"`) }),
@@ -232,6 +558,8 @@ function readChart(value: unknown, index: number, sheets: readonly WorkbookSheet
     "sheet",
     "x",
     "y",
+    "line",
+    "aggregate",
     "title",
     "stacked",
   ])
@@ -253,20 +581,49 @@ function readChart(value: unknown, index: number, sheets: readonly WorkbookSheet
     )
   }
   if (typeof input.x !== "string" || !input.x) throw new WorkbookError(`${at} needs an "x" column.`)
-  const y = typeof input.y === "string" ? [input.y] : input.y
   if (
-    !Array.isArray(y) ||
-    y.length === 0 ||
-    !y.every((column) => typeof column === "string" && column)
+    input.aggregate !== undefined &&
+    !(SHEET_CHART_AGGREGATES as readonly unknown[]).includes(input.aggregate)
   ) {
+    throw new WorkbookError(
+      `${at} "aggregate" is ${JSON.stringify(input.aggregate)}; use one of ${SHEET_CHART_AGGREGATES.join(", ")}.`
+    )
+  }
+  const aggregate = input.aggregate as SheetChartAggregate | undefined
+  if (aggregate && type === "scatter") {
+    throw new WorkbookError(
+      `${at} is a scatter chart, which plots every row; leave out "aggregate".`
+    )
+  }
+  const columns = (key: "y" | "line") => {
+    const value = input[key]
+    const list = typeof value === "string" ? [value] : (value ?? [])
+    if (!Array.isArray(list) || !list.every((column) => typeof column === "string" && column)) {
+      throw new WorkbookError(`${at} "${key}" must be a column, or a list of them.`)
+    }
+    return list as string[]
+  }
+  const y = columns("y")
+  const line = columns("line")
+  // Counting rows plots how many there are for each x value: there is no column to plot.
+  if (aggregate === "count") {
+    if (y.length > 0 || line.length > 0) {
+      throw new WorkbookError(`${at} counts rows, which needs no "y"; leave it out.`)
+    }
+  } else if (y.length === 0) {
     throw new WorkbookError(`${at} needs a "y" column, or a list of them.`)
   }
-  if (y.length > ARTIFACT_LIMITS.maxChartSeries) {
+  if (line.length > 0 && type !== "bar") {
+    throw new WorkbookError(
+      `${at} is a ${type} chart; only a bar chart draws "line" columns over its bars.`
+    )
+  }
+  if (y.length + line.length > ARTIFACT_LIMITS.maxChartSeries) {
     throw new WorkbookError(
-      `${at} plots ${y.length} columns; a chart reads well with at most ${ARTIFACT_LIMITS.maxChartSeries}. Split it, or chart the ones that matter.`
+      `${at} plots ${y.length + line.length} columns; a chart reads well with at most ${ARTIFACT_LIMITS.maxChartSeries}. Split it, or chart the ones that matter.`
     )
   }
-  if (type === "pie" && y.length !== 1)
+  if (type === "pie" && aggregate !== "count" && y.length !== 1)
     throw new WorkbookError(`${at} is a pie: give it one "y" column.`)
   if (input.stacked !== undefined && typeof input.stacked !== "boolean") {
     throw new WorkbookError(`${at} "stacked" must be true or false.`)
@@ -282,7 +639,9 @@ function readChart(value: unknown, index: number, sheets: readonly WorkbookSheet
     type,
     sheet: input.sheet,
     x: input.x,
-    y: y as string[],
+    y,
+    line,
+    ...(aggregate ? { aggregate } : {}),
     ...(typeof input.title === "string" && input.title.trim() ? { title: input.title.trim() } : {}),
     stacked: input.stacked === true,
   }

package/src/auth/index.ts

@@ -118,7 +118,9 @@ export type {
   OidcCallbackResult,
   OidcStartSignInInput,
   OidcStartSignInResult,
+  OwnProfile,
   Principal,
+  ProfileField,
   ReactivateMemberInput,
   ReactivateMemberResult,
   ResolvedAuthConfig,
@@ -136,6 +138,8 @@ export type {
   UnauthenticatedAuthSession,
   UpdateMemberGroupsInput,
   UpdateMemberGroupsResult,
+  UpdateOwnProfileInput,
+  UserPrincipal,
 } from "./types"
 export { principalsEqual, SYSTEM_PRINCIPAL } from "./types"
 export {

package/src/auth/member-events.ts

@@ -0,0 +1,114 @@
+import type { EventDraft, PropertyChange, UserProfileUpdatedEvent } from "../events/types"
+import type { CompleteSignInResult, InvitationRecord, UserRecord } from "../storage/auth"
+import { toUserProfile } from "../users/execution"
+import type { AuthenticatedUserRequestSession } from "./types"
+
+type ProfileChanges = UserProfileUpdatedEvent["payload"]["changes"]
+
+/**
+ * What a completed sign-in tells the project: a new member, or the profile their identity provider
+ * changed. A sign-in that changed nothing tells nothing.
+ */
+export function signInEvents(result: CompleteSignInResult): readonly EventDraft[] {
+  const user = toUserProfile(result.user)
+
+  if (result.previousUser === null) {
+    return [
+      {
+        type: "user.joined",
+        payload: {
+          user,
+          ...(result.invitation ? { invitationId: result.invitation.id } : {}),
+        },
+        idempotencyKey: `user.joined:${user.id}`,
+      },
+    ]
+  }
+
+  const changes = profileChanges(result.previousUser, result.user)
+  if (!hasChanges(changes)) return []
+
+  return [{ type: "user.profile.updated", payload: { user, changes } }]
+}
+
+/** A member edited their own profile. Saving the values it already had tells nothing. */
+export function profileUpdatedEvents(
+  caller: AuthenticatedUserRequestSession,
+  previousUser: UserRecord,
+  user: UserRecord
+): readonly EventDraft[] {
+  const changes = profileChanges(previousUser, user)
+  if (!hasChanges(changes)) return []
+
+  return [
+    {
+      type: "user.profile.updated",
+      payload: { user: toUserProfile(user), changes, requestedBy: requester(caller) },
+    },
+  ]
+}
+
+export function statusChangedEvents(
+  caller: AuthenticatedUserRequestSession,
+  previousUser: UserRecord,
+  user: UserRecord
+): readonly EventDraft[] {
+  if (previousUser.status === user.status) return []
+
+  return [
+    {
+      type: user.status === "suspended" ? "user.suspended" : "user.reactivated",
+      payload: { user: toUserProfile(user), requestedBy: requester(caller) },
+    },
+  ]
+}
+
+export function invitedEvents(
+  caller: AuthenticatedUserRequestSession,
+  invitation: InvitationRecord
+): readonly EventDraft[] {
+  return [
+    {
+      type: "user.invited",
+      payload: {
+        invitationId: invitation.id,
+        email: invitation.email,
+        expiresAt: invitation.expiresAt.toISOString(),
+        requestedBy: requester(caller),
+      },
+    },
+  ]
+}
+
+function profileChanges(before: UserRecord, after: UserRecord): ProfileChanges {
+  const displayName = fieldChange(before.displayName, after.displayName)
+  const avatarUrl = fieldChange(before.avatarUrl, after.avatarUrl)
+
+  return {
+    ...(displayName ? { displayName } : {}),
+    ...(avatarUrl ? { avatarUrl } : {}),
+  }
+}
+
+function fieldChange(
+  before: string | undefined,
+  after: string | undefined
+): PropertyChange<string> | undefined {
+  if (after === undefined) {
+    return before === undefined ? undefined : { operation: "cleared", before, after: null }
+  }
+
+  if (before === undefined) return { operation: "created", after }
+  if (before === after) return undefined
+
+  return { operation: "updated", before, after }
+}
+
+function hasChanges(changes: ProfileChanges): boolean {
+  return changes.displayName !== undefined || changes.avatarUrl !== undefined
+}
+
+// Only the principal: the session behind it is not part of the event.
+function requester(caller: AuthenticatedUserRequestSession) {
+  return { type: caller.principal.type, id: caller.principal.id }
+}