@kelpie/server 0.1.0

package/src/modules/activities/repository.ts

@@ -0,0 +1,196 @@
+import { and, eq, inArray, or, sql } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { dealPeople, deals } from '../deals/schema.ts'
+import { opportunities } from '../opportunities/schema.ts'
+import { partnershipPeople, partnerships } from '../partnerships/schema.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import { activities } from './schema.ts'
+
+export type ActivityRecord = typeof activities.$inferSelect
+
+/** The writable column shape. The recorder builds one of these; nothing else knows the column names. */
+export type ActivityColumns = typeof activities.$inferInsert
+
+/**
+ * Only `created_at`. An activity carries no other non-nullable value worth
+ * ordering by, and a keyset cannot seek past a null.
+ */
+export const ACTIVITY_SORTS: SortableFields<ActivityRecord> = {
+  created_at: timestampSort(activities.createdAt, (activity) => activity.createdAt),
+}
+
+export const DEFAULT_ACTIVITY_SORT = '-created_at'
+
+/** One `(target_type, target_id)` pair a timeline reads from. */
+export interface ActivityTarget {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+}
+
+export async function insertActivity(
+  db: Queryable,
+  values: ActivityColumns,
+): Promise<ActivityRecord> {
+  const [created] = await db.insert(activities).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting activity ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+/**
+ * The related records whose activity rolls up onto a person or company timeline.
+ *
+ * A deal moving to Proposal is the most useful thing on that company's timeline
+ * and it is not stored against the company. Which relations roll up was settled
+ * by the mockup (`activitiesFor` in `mockups/src/data/seed.ts`): deals,
+ * opportunities and partnerships for a company, and for a person only the two
+ * they can be attached to.
+ *
+ * Reads the pipeline tables directly rather than composing their repositories,
+ * which is the rule already set for a query spanning a relation
+ * (`architecture.md`).
+ *
+ * @returns The roll-up targets only. The caller adds the record's own.
+ */
+export async function listRolledUpTargets(
+  db: Queryable,
+  workspaceId: string,
+  targetType: RecordTargetType,
+  targetId: string,
+): Promise<ActivityTarget[]> {
+  if (targetType === 'company') {
+    const [dealRows, opportunityRows, partnershipRows] = await Promise.all([
+      db
+        .select({ id: deals.id })
+        .from(deals)
+        .where(and(eq(deals.workspaceId, workspaceId), eq(deals.companyId, targetId))),
+      db
+        .select({ id: opportunities.id })
+        .from(opportunities)
+        .where(
+          and(eq(opportunities.workspaceId, workspaceId), eq(opportunities.companyId, targetId)),
+        ),
+      db
+        .select({ id: partnerships.id })
+        .from(partnerships)
+        .where(and(eq(partnerships.workspaceId, workspaceId), eq(partnerships.companyId, targetId))),
+    ])
+
+    return [
+      ...dealRows.map((row) => ({ targetType: 'deal' as const, targetId: row.id })),
+      ...opportunityRows.map((row) => ({ targetType: 'opportunity' as const, targetId: row.id })),
+      ...partnershipRows.map((row) => ({ targetType: 'partnership' as const, targetId: row.id })),
+    ]
+  }
+
+  if (targetType === 'person') {
+    // An opportunity has no people, so a person rolls up two relations, not three.
+    const [dealRows, partnershipRows] = await Promise.all([
+      db
+        .select({ id: deals.id })
+        .from(deals)
+        .innerJoin(dealPeople, eq(dealPeople.dealId, deals.id))
+        .where(and(eq(deals.workspaceId, workspaceId), eq(dealPeople.personId, targetId))),
+      db
+        .select({ id: partnerships.id })
+        .from(partnerships)
+        .innerJoin(partnershipPeople, eq(partnershipPeople.partnershipId, partnerships.id))
+        .where(
+          and(eq(partnerships.workspaceId, workspaceId), eq(partnershipPeople.personId, targetId)),
+        ),
+    ])
+
+    return [
+      ...dealRows.map((row) => ({ targetType: 'deal' as const, targetId: row.id })),
+      ...partnershipRows.map((row) => ({ targetType: 'partnership' as const, targetId: row.id })),
+    ]
+  }
+
+  return []
+}
+
+/**
+ * Grouped by target type, so the index on `(workspace_id, target_type,
+ * target_id)` stays usable for each group instead of degrading into a long list
+ * of independent pair comparisons.
+ */
+function matchesAnyTarget(targets: readonly ActivityTarget[]): SQL | undefined {
+  const idsByType = new Map<RecordTargetType, string[]>()
+
+  for (const target of targets) {
+    const ids = idsByType.get(target.targetType)
+
+    if (ids === undefined) {
+      idsByType.set(target.targetType, [target.targetId])
+    } else {
+      ids.push(target.targetId)
+    }
+  }
+
+  return or(
+    ...[...idsByType].map(([targetType, ids]) =>
+      and(eq(activities.targetType, targetType), inArray(activities.targetId, ids)),
+    ),
+  )
+}
+
+/**
+ * @param targets The record's own target plus its roll-up set. An empty list
+ *   answers no rows rather than every row in the workspace, which is what an
+ *   omitted condition would have meant.
+ * @returns Up to `window.fetchLimit` rows: one more than the page, so the caller
+ *   can tell there is a next one.
+ */
+export function listActivities(
+  db: Queryable,
+  workspaceId: string,
+  targets: readonly ActivityTarget[],
+  window: ListWindow<ActivityRecord>,
+): Promise<ActivityRecord[]> {
+  return db
+    .select()
+    .from(activities)
+    .where(
+      and(
+        eq(activities.workspaceId, workspaceId),
+        targets.length === 0 ? sql`false` : matchesAnyTarget(targets),
+        keysetCondition(window, activities.id),
+      ),
+    )
+    .orderBy(...orderByWindow(window, activities.id))
+    .limit(window.fetchLimit)
+}
+
+/**
+ * Removes every activity attached to a target.
+ *
+ * The target is polymorphic and carries no foreign key, so nothing in the
+ * database deletes these. The service that deletes the target calls this inside
+ * the same transaction (`schema.md`).
+ */
+export async function deleteForTarget(
+  db: Queryable,
+  workspaceId: string,
+  targetType: string,
+  targetId: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(activities)
+    .where(
+      and(
+        eq(activities.workspaceId, workspaceId),
+        eq(activities.targetType, targetType),
+        eq(activities.targetId, targetId),
+      ),
+    )
+    .returning({ id: activities.id })
+
+  return deleted.length
+}

package/src/modules/activities/routes.ts

@@ -0,0 +1,78 @@
+import type { Context, Hono } from 'hono'
+
+import { AppError } from '../../lib/errors.ts'
+import { pageBody, readListParameters } from '../../lib/http.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import { isRecordTargetType } from '../recordTargets.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import type { ActivitiesService, ActivityView } from './service.ts'
+
+/**
+ * `/v1/activities`, read-only.
+ *
+ * One list endpoint, and it always names a record. A workspace-wide feed is a
+ * different question with a different shape, and answering it accidentally
+ * through an omitted filter is how a client ends up paging the entire history of
+ * a workspace to render one sidebar.
+ */
+
+export interface ActivitiesRoutesDependencies extends CredentialDependencies {
+  readonly service: ActivitiesService
+}
+
+export function activityResponse(activity: ActivityView): Record<string, unknown> {
+  return {
+    id: activity.id,
+    target_type: activity.targetType,
+    target_id: activity.targetId,
+    kind: activity.kind,
+    actor_member_id: activity.actorMemberId,
+    actor_label: activity.actorLabel,
+    action: activity.action,
+    detail: activity.detail,
+    created_at: activity.createdAt.toISOString(),
+  }
+}
+
+/**
+ * @throws AppError 422 when either half of the target is missing or the type is
+ *   not one a record can be attached to.
+ */
+function readTarget(context: Context): { targetType: RecordTargetType; targetId: string } {
+  const targetType = context.req.query('target_type')
+  const targetId = context.req.query('target_id')
+
+  if (targetType === undefined || targetId === undefined || targetId.length === 0) {
+    throw AppError.validationFailed('A timeline is always a timeline of something', [
+      { field: 'target_type', message: 'Required' },
+      { field: 'target_id', message: 'Required' },
+    ])
+  }
+
+  if (!isRecordTargetType(targetType)) {
+    throw AppError.validationFailed('That is not a record type activity attaches to', [
+      { field: 'target_type', message: `Unknown target type "${targetType}"` },
+    ])
+  }
+
+  return { targetType, targetId }
+}
+
+export function mountActivitiesRoutes(
+  router: Hono,
+  dependencies: ActivitiesRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/activities', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      readTarget(context),
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, activityResponse))
+  })
+}

package/src/modules/activities/schema.ts

@@ -0,0 +1,41 @@
+import { ACTIVITY_KINDS, RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { index, pgTable, text } from 'drizzle-orm/pg-core'
+
+import { checkOneOf, createdAt, primaryId } from '../../lib/columns.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
+
+/** Re-exported for the routes and service that constrain themselves to this table. */
+export { ACTIVITY_KINDS } from '@kelpie/schemas'
+export type { ActivityKind } from '@kelpie/schemas'
+
+/**
+ * System history, rolled up onto person and company timelines. Append-only: there
+ * is no update route and no `updated_at`.
+ *
+ * `actor_label` carries the display name when there is no member behind the
+ * action, e.g. "Form" or "Gmail".
+ */
+export const activities = pgTable(
+  'activities',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    targetType: text('target_type').notNull(),
+    targetId: text('target_id').notNull(),
+    kind: text('kind').notNull(),
+    actorMemberId: text('actor_member_id').references(() => workspaceMembers.id, {
+      onDelete: 'set null',
+    }),
+    actorLabel: text('actor_label'),
+    action: text('action').notNull(),
+    detail: text('detail'),
+    createdAt: createdAt(),
+  },
+  (table) => [
+    index('activities_target_idx').on(table.workspaceId, table.targetType, table.targetId),
+    checkOneOf('activities_target_type_check', table.targetType, RECORD_TARGET_TYPES),
+    checkOneOf('activities_kind_check', table.kind, ACTIVITY_KINDS),
+  ],
+)

package/src/modules/activities/service.ts

@@ -0,0 +1,93 @@
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+import type { Actor } from '../auth/actor.ts'
+import { requireWorkspaceId } from '../auth/actor.ts'
+import { targetExists } from '../recordTargets.ts'
+import type { RecordTargetType } from '../recordTargets.ts'
+import * as repository from './repository.ts'
+import { DEFAULT_ACTIVITY_SORT, ACTIVITY_SORTS } from './repository.ts'
+import type { ActivityRecord } from './repository.ts'
+
+/**
+ * Activity: what happened, and who did it.
+ *
+ * Read-only. Rows are written by the services that make the change, through the
+ * recorder, inside the same transaction (`recorder.ts`). There is deliberately
+ * no create, update or delete route: a history a client can edit is not a
+ * history, and `schema.md` gives the table no `updated_at` to support one.
+ *
+ * A timeline is not only the rows filed against the record. A person's timeline
+ * includes the deals and partnerships they are on; a company's includes its
+ * deals, opportunities and partnerships. The roll-up is resolved here rather
+ * than in the browser, which is the point of moving `activitiesFor` server-side.
+ */
+
+export interface ActivitiesDependencies {
+  readonly db: Database
+}
+
+/** An activity as the API returns one: the stored row minus the tenancy column. */
+export type ActivityView = Omit<ActivityRecord, 'workspaceId'>
+
+export interface ActivityTimelineQuery {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+}
+
+export interface ActivitiesService {
+  list(
+    actor: Actor,
+    timeline: ActivityTimelineQuery,
+    query: ListQueryParameters,
+  ): Promise<Page<ActivityView>>
+}
+
+function toView(record: ActivityRecord): ActivityView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+export function createActivitiesService(
+  dependencies: ActivitiesDependencies,
+): ActivitiesService {
+  return {
+    async list(actor, timeline, query) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      // Without this an unknown id answers an empty timeline, which reads as
+      // "nothing has happened" rather than "there is no such record".
+      const exists = await targetExists(
+        dependencies.db,
+        workspaceId,
+        timeline.targetType,
+        timeline.targetId,
+      )
+
+      if (!exists) {
+        throw AppError.notFound('Record not found')
+      }
+
+      const rolledUp = await repository.listRolledUpTargets(
+        dependencies.db,
+        workspaceId,
+        timeline.targetType,
+        timeline.targetId,
+      )
+      const window = readListWindow(query, ACTIVITY_SORTS, DEFAULT_ACTIVITY_SORT)
+      const rows = await repository.listActivities(
+        dependencies.db,
+        workspaceId,
+        [{ targetType: timeline.targetType, targetId: timeline.targetId }, ...rolledUp],
+        window,
+      )
+
+      return mapPage(
+        toPage(rows, window, (activity) => activity.id),
+        toView,
+      )
+    },
+  }
+}

package/src/modules/activities/tools.ts

@@ -0,0 +1,40 @@
+import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, listWindowShape, pageResult, toListQuery } from '../crudTools.ts'
+import { activityResponse } from './routes.ts'
+import type { ActivitiesService } from './service.ts'
+
+/**
+ * `activities_list`, and nothing else.
+ *
+ * Activity is written by the services that cause it, inside their own
+ * transaction. There is no REST endpoint that writes one, so there is no tool
+ * that does either.
+ */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  target_type: z.enum(RECORD_TARGET_TYPES).describe('The kind of record whose timeline to read.'),
+  target_id: idArg.describe('The record whose timeline to read.'),
+})
+
+export function registerActivitiesTools(mcp: McpToolRegistry, service: ActivitiesService): void {
+  mcp.tool({
+    name: 'activities_list',
+    description:
+      'Read one record\'s timeline: what changed, who changed it, and when. Always names ' +
+      'a record; there is no workspace-wide feed. Cursor paged. Mirrors GET /v1/activities.',
+    inputSchema: listArgs,
+    invoke: async (args, actor) =>
+      pageResult(
+        await service.list(
+          actor,
+          { targetType: args.target_type, targetId: args.target_id },
+          toListQuery(args),
+        ),
+        activityResponse,
+      ),
+  })
+}

package/src/modules/activities/wording.ts

@@ -0,0 +1,168 @@
+/**
+ * The sentence an activity row carries.
+ *
+ * The timeline renders `<actor> <action>` with `detail` beneath it, so the
+ * phrasing is data, not presentation, and it is decided here rather than in
+ * five services. Pure functions with no database and no clock: what a person
+ * sees on a timeline is worth a unit test, and this is the shape that gets one.
+ *
+ * The phrasings match the ones the mockup's seeded activity carries
+ * (`mockups/src/data/seed.ts`), because that seed is what the panel was designed
+ * against.
+ */
+
+/** What an activity says happened, ready to store. */
+export interface ActivityWording {
+  readonly action: string
+  readonly detail: string | null
+}
+
+/** Human labels for the fields of one resource, keyed by their `camelCase` column name. */
+export type FieldLabels = Readonly<Record<string, string>>
+
+/**
+ * A value fit to print inside `old → new`.
+ *
+ * Arrays and objects are excluded on purpose. A tags array rendered as JSON is
+ * noise on a timeline, and there is no short honest rendering of "these five
+ * social profiles became those four", so the change is reported without a
+ * before-and-after rather than with an unreadable one.
+ */
+function printable(value: unknown): string | undefined {
+  if (value === null) {
+    return 'none'
+  }
+
+  if (typeof value === 'string') {
+    return value.length === 0 ? 'none' : value
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value)
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+
+  return undefined
+}
+
+function labelFor(labels: FieldLabels, field: string): string {
+  return labels[field] ?? field
+}
+
+/** `created Person`, `created Company`. */
+export function describeCreation(objectLabel: string): ActivityWording {
+  return { action: `created ${objectLabel}`, detail: null }
+}
+
+/**
+ * `Submitted via Website contact`, with the first answers beneath it.
+ *
+ * Reads as the submitter's own action rather than as "created Person", because
+ * the row lands on a person's timeline and the person is usually not new: a
+ * returning lead filling the form in again is the same sentence either way.
+ */
+export function describeFormSubmission(formName: string, answers: string | null): ActivityWording {
+  return { action: `Submitted via ${formName}`, detail: answers }
+}
+
+/**
+ * `created Deal via Website contact`, `created Company via acme-companies.csv`.
+ *
+ * @param sourceName What brought the record in: a form's name, an import's file
+ *   name. Named on the row because a record nobody typed in needs to say where
+ *   it came from, and the actor column only says who pressed the button.
+ */
+export function describeCreationVia(objectLabel: string, sourceName: string): ActivityWording {
+  return { action: `created ${objectLabel} via ${sourceName}`, detail: null }
+}
+
+/**
+ * `updated Company via acme-companies.csv`.
+ *
+ * A bulk update names no fields, unlike `describeUpdate`. One import row can
+ * move a dozen columns at once, and a timeline listing them says less than the
+ * file that carried them: the job's own row-by-row account is where that detail
+ * belongs.
+ */
+export function describeUpdateVia(objectLabel: string, sourceName: string): ActivityWording {
+  return { action: `updated ${objectLabel} via ${sourceName}`, detail: null }
+}
+
+/**
+ * One changed field reads as itself; several read as a count.
+ *
+ * `changed Influence` with `influencer → decision_maker` says more than
+ * `changed 1 attribute`, and past one field the before-and-after stops fitting
+ * on a line, so the detail becomes the list of what moved.
+ *
+ * @param changed The field names `changedKeys` returned, in `camelCase`.
+ * @param before The stored record, for the single-field before-and-after.
+ * @param after The values being written.
+ */
+export function describeUpdate(
+  changed: readonly string[],
+  labels: FieldLabels,
+  before: Readonly<Record<string, unknown>>,
+  after: Readonly<Record<string, unknown>>,
+): ActivityWording {
+  const first = changed[0]
+
+  if (changed.length === 1 && first !== undefined) {
+    const from = printable(before[first])
+    const to = printable(after[first])
+
+    return {
+      action: `changed ${labelFor(labels, first)}`,
+      detail: from === undefined || to === undefined ? null : `${from} → ${to}`,
+    }
+  }
+
+  return {
+    action: `changed ${String(changed.length)} attributes`,
+    detail: changed.map((field) => labelFor(labels, field)).join(', '),
+  }
+}
+
+/** `linked to company` with the far side's name beneath it. */
+export function describeLink(relatedLabel: string, relatedName: string): ActivityWording {
+  return { action: `linked to ${relatedLabel}`, detail: relatedName }
+}
+
+/**
+ * `unlinked from company`, the mirror of `describeLink`.
+ *
+ * The far side is named for the same reason it is named on the link: the row
+ * lands on each end's timeline, and `unlinked from company` alone leaves the
+ * reader asking which one.
+ */
+export function describeUnlink(relatedLabel: string, relatedName: string): ActivityWording {
+  return { action: `unlinked from ${relatedLabel}`, detail: relatedName }
+}
+
+/** `moved to Proposal`, with where it came from beneath. */
+export function describeStageChange(fromStage: string, toStage: string): ActivityWording {
+  return { action: `moved to ${toStage}`, detail: `${fromStage} → ${toStage}` }
+}
+
+/** How much of a note's body the timeline repeats before trailing off. */
+const NOTE_EXCERPT_LENGTH = 120
+
+/**
+ * `added a note`, with the opening of the note beneath it.
+ *
+ * The excerpt is what makes the row worth reading without leaving the timeline.
+ * It is truncated on a character count rather than a word boundary because a
+ * note has no guaranteed whitespace.
+ */
+export function describeNote(body: string): ActivityWording {
+  const trimmed = body.trim()
+  const excerpt =
+    trimmed.length > NOTE_EXCERPT_LENGTH
+      ? `${trimmed.slice(0, NOTE_EXCERPT_LENGTH).trimEnd()}…`
+      : trimmed
+
+  return { action: 'added a note', detail: excerpt.length === 0 ? null : excerpt }
+}