@kelpie/server 0.1.0

package/src/modules/workspace/repository.ts

@@ -0,0 +1,420 @@
+import { and, asc, count, eq, gt } from 'drizzle-orm'
+
+import type { Database } from '../../lib/database.ts'
+import type { Transaction } from '../../runtime/transaction.ts'
+import { users } from '../auth/schema.ts'
+import { deals } from '../deals/schema.ts'
+import { decisions } from '../decisions/schema.ts'
+import { handbookPages } from '../handbook/schema.ts'
+import { notes } from '../notes/schema.ts'
+import { opportunities } from '../opportunities/schema.ts'
+import { partnerships } from '../partnerships/schema.ts'
+import { pipelineStages } from '../pipelines/schema.ts'
+import { planItems } from '../plans/schema.ts'
+import { raises } from '../raises/schema.ts'
+import { invites, workspaceMembers, workspaceModuleSettings, workspaces } from './schema.ts'
+
+/** Queries for workspaces, membership, and invites. The service decides; these read and write. */
+
+export type Queryable = Database | Transaction
+
+export type WorkspaceRecord = typeof workspaces.$inferSelect
+export type MemberRecord = typeof workspaceMembers.$inferSelect
+export type InviteRecord = typeof invites.$inferSelect
+
+export async function insertWorkspace(
+  db: Queryable,
+  values: typeof workspaces.$inferInsert,
+): Promise<WorkspaceRecord> {
+  const [created] = await db.insert(workspaces).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting workspace ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function findWorkspace(db: Queryable, id: string): Promise<WorkspaceRecord | undefined> {
+  const [found] = await db.select().from(workspaces).where(eq(workspaces.id, id)).limit(1)
+
+  return found
+}
+
+export async function updateWorkspace(
+  db: Queryable,
+  id: string,
+  changes: Partial<typeof workspaces.$inferInsert>,
+): Promise<WorkspaceRecord | undefined> {
+  const [updated] = await db.update(workspaces).set(changes).where(eq(workspaces.id, id)).returning()
+
+  return updated
+}
+
+/**
+ * Removes the workspace and, through `workspace_id` cascades, everything it
+ * owned. No table outside this one holds a workspace's data.
+ */
+export async function deleteWorkspace(db: Queryable, id: string): Promise<void> {
+  await db.delete(workspaces).where(eq(workspaces.id, id))
+}
+
+export async function insertMember(
+  db: Queryable,
+  values: typeof workspaceMembers.$inferInsert,
+): Promise<MemberRecord> {
+  const [created] = await db.insert(workspaceMembers).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting member ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function findMember(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<MemberRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(workspaceMembers)
+    .where(and(eq(workspaceMembers.workspaceId, workspaceId), eq(workspaceMembers.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function updateMemberRole(
+  db: Queryable,
+  id: string,
+  role: string,
+  updatedAt: Date,
+): Promise<MemberRecord | undefined> {
+  const [updated] = await db
+    .update(workspaceMembers)
+    .set({ role, updatedAt })
+    .where(eq(workspaceMembers.id, id))
+    .returning()
+
+  return updated
+}
+
+export async function deleteMember(db: Queryable, id: string): Promise<void> {
+  await db.delete(workspaceMembers).where(eq(workspaceMembers.id, id))
+}
+
+/**
+ * What a member is named on, counted per table.
+ *
+ * The `owner_id` and `author_id` columns are `ON DELETE RESTRICT`, so the
+ * database would refuse the delete on its own. It would only name one table
+ * while doing it, and `api.md` wants every referencing type in the `409`
+ * details, so the counts are read first and the refusal is the service's.
+ *
+ * This is the one place the workspace module reads other modules' tables. The
+ * alternative is each of them registering a "does this member matter to you"
+ * hook, which is more machinery than one query list is worth today.
+ *
+ * @returns Only the types with at least one reference, in a fixed order.
+ */
+export async function countMemberReferences(
+  db: Queryable,
+  memberId: string,
+): Promise<readonly { readonly type: string; readonly count: number }[]> {
+  const sources = [
+    { type: 'deal', table: deals, column: deals.ownerId },
+    { type: 'opportunity', table: opportunities, column: opportunities.ownerId },
+    { type: 'partnership', table: partnerships, column: partnerships.ownerId },
+    { type: 'raise', table: raises, column: raises.ownerId },
+    { type: 'plan_item', table: planItems, column: planItems.ownerId },
+    { type: 'decision', table: decisions, column: decisions.ownerId },
+    { type: 'note', table: notes, column: notes.authorId },
+  ] as const
+
+  const counted = await Promise.all(
+    sources.map(async (source) => {
+      const [row] = await db.select({ total: count() }).from(source.table).where(eq(source.column, memberId))
+
+      return { type: source.type, count: row?.total ?? 0 }
+    }),
+  )
+
+  return counted.filter((entry) => entry.count > 0)
+}
+
+/** A membership plus the identity behind it, which is what a member is to a reader. */
+export interface MemberWithUser {
+  readonly id: string
+  readonly userId: string
+  readonly role: string
+  readonly joinedAt: Date
+  readonly name: string
+  readonly email: string
+}
+
+/**
+ * Members with their user's name and email.
+ *
+ * Joined here rather than left to the caller: every list of members is read to
+ * be shown to a human, and a membership row on its own carries nothing a human
+ * recognises. Notes and activities attribute to a member id and resolve the name
+ * through this list.
+ */
+export async function listMembers(db: Queryable, workspaceId: string): Promise<MemberWithUser[]> {
+  return db
+    .select({
+      id: workspaceMembers.id,
+      userId: workspaceMembers.userId,
+      role: workspaceMembers.role,
+      joinedAt: workspaceMembers.joinedAt,
+      name: users.name,
+      email: users.email,
+    })
+    .from(workspaceMembers)
+    .innerJoin(users, eq(users.id, workspaceMembers.userId))
+    .where(eq(workspaceMembers.workspaceId, workspaceId))
+    .orderBy(workspaceMembers.joinedAt)
+}
+
+/** One member in the same shape `listMembers` produces, for a write to answer with. */
+export async function findMemberWithUser(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<MemberWithUser | undefined> {
+  const [found] = await db
+    .select({
+      id: workspaceMembers.id,
+      userId: workspaceMembers.userId,
+      role: workspaceMembers.role,
+      joinedAt: workspaceMembers.joinedAt,
+      name: users.name,
+      email: users.email,
+    })
+    .from(workspaceMembers)
+    .innerJoin(users, eq(users.id, workspaceMembers.userId))
+    .where(and(eq(workspaceMembers.workspaceId, workspaceId), eq(workspaceMembers.id, id)))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * The workspace's owner. Earliest-joined breaks a tie, so the answer does not
+ * move if a second owner ever exists; the service is what keeps there being one.
+ */
+export async function findOwner(
+  db: Queryable,
+  workspaceId: string,
+): Promise<MemberRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(workspaceMembers)
+    .where(and(eq(workspaceMembers.workspaceId, workspaceId), eq(workspaceMembers.role, 'owner')))
+    .orderBy(asc(workspaceMembers.joinedAt), asc(workspaceMembers.id))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * The member a record is assigned to when nobody chose one.
+ *
+ * A public form submit has no actor, so a Deal it creates has no natural owner
+ * and `forms.md` gives it the workspace's default member. That is the owner: the
+ * account that created the workspace, and the one person guaranteed to be able
+ * to reassign it.
+ *
+ * @returns undefined only for a workspace with no members, which membership
+ *   creation makes unreachable through the API.
+ */
+export function findDefaultMember(
+  db: Queryable,
+  workspaceId: string,
+): Promise<MemberRecord | undefined> {
+  return findOwner(db, workspaceId)
+}
+
+/**
+ * Seats already spoken for: members plus invitations still open.
+ *
+ * An open invite counts, otherwise a workspace on its last seat could send ten
+ * invitations and let whoever accepts first through while the others fail. One
+ * that has expired does not, because nobody can accept it.
+ */
+export async function countSeatsInUse(
+  db: Queryable,
+  workspaceId: string,
+  now: Date,
+): Promise<number> {
+  const [members, pending] = await Promise.all([
+    db.select({ id: workspaceMembers.id }).from(workspaceMembers).where(eq(workspaceMembers.workspaceId, workspaceId)),
+    db
+      .select({ id: invites.id })
+      .from(invites)
+      .where(
+        and(
+          eq(invites.workspaceId, workspaceId),
+          eq(invites.status, 'pending'),
+          gt(invites.expiresAt, now),
+        ),
+      ),
+  ])
+
+  return members.length + pending.length
+}
+
+export async function insertInvite(
+  db: Queryable,
+  values: typeof invites.$inferInsert,
+): Promise<InviteRecord> {
+  const [created] = await db.insert(invites).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting invite ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function listInvites(db: Queryable, workspaceId: string): Promise<InviteRecord[]> {
+  return db.select().from(invites).where(eq(invites.workspaceId, workspaceId)).orderBy(invites.createdAt)
+}
+
+export async function findInvite(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<InviteRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(invites)
+    .where(and(eq(invites.workspaceId, workspaceId), eq(invites.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function updateInvite(
+  db: Queryable,
+  id: string,
+  changes: Partial<typeof invites.$inferInsert>,
+): Promise<InviteRecord | undefined> {
+  const [updated] = await db.update(invites).set(changes).where(eq(invites.id, id)).returning()
+
+  return updated
+}
+
+/**
+ * Every invitation to this address in this workspace, expired ones included.
+ *
+ * The column is `citext`, so an address invited as `Grace@Example.com` is found
+ * by `grace@example.com` and the caller does not have to case-fold twice.
+ */
+export async function listInvitesForEmail(
+  db: Queryable,
+  workspaceId: string,
+  email: string,
+): Promise<InviteRecord[]> {
+  return db
+    .select()
+    .from(invites)
+    .where(and(eq(invites.workspaceId, workspaceId), eq(invites.email, email)))
+    .orderBy(invites.createdAt)
+}
+
+/** The same set, removed. Expiry is not a filter: a dead invitation is still noise. */
+export async function deleteInvitesForEmail(
+  db: Queryable,
+  workspaceId: string,
+  email: string,
+): Promise<void> {
+  await db.delete(invites).where(and(eq(invites.workspaceId, workspaceId), eq(invites.email, email)))
+}
+
+export async function findInviteByTokenHash(
+  db: Queryable,
+  tokenHash: string,
+): Promise<InviteRecord | undefined> {
+  const [found] = await db.select().from(invites).where(eq(invites.tokenHash, tokenHash)).limit(1)
+
+  return found
+}
+
+export async function deleteInvite(db: Queryable, id: string): Promise<void> {
+  await db.delete(invites).where(eq(invites.id, id))
+}
+
+export async function insertHandbookPages(
+  db: Queryable,
+  values: readonly (typeof handbookPages.$inferInsert)[],
+): Promise<void> {
+  if (values.length === 0) {
+    return
+  }
+
+  await db.insert(handbookPages).values([...values])
+}
+
+export async function insertPipelineStages(
+  db: Queryable,
+  values: readonly (typeof pipelineStages.$inferInsert)[],
+): Promise<void> {
+  if (values.length === 0) {
+    return
+  }
+
+  await db.insert(pipelineStages).values([...values])
+}
+
+export type ModuleSettingRecord = typeof workspaceModuleSettings.$inferSelect
+
+export async function listModuleSettings(db: Queryable, workspaceId: string): Promise<ModuleSettingRecord[]> {
+  return db
+    .select()
+    .from(workspaceModuleSettings)
+    .where(eq(workspaceModuleSettings.workspaceId, workspaceId))
+}
+
+/** Undefined means the workspace has never toggled this module, not that it is disabled. */
+export async function findModuleSetting(
+  db: Queryable,
+  workspaceId: string,
+  moduleId: string,
+): Promise<ModuleSettingRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(workspaceModuleSettings)
+    .where(and(eq(workspaceModuleSettings.workspaceId, workspaceId), eq(workspaceModuleSettings.moduleId, moduleId)))
+    .limit(1)
+
+  return found
+}
+
+/**
+ * Sets a workspace's choice for one module, inserting the row on its first
+ * toggle and overwriting `enabled` on every one after.
+ */
+export async function upsertModuleSetting(
+  db: Queryable,
+  values: typeof workspaceModuleSettings.$inferInsert,
+): Promise<ModuleSettingRecord> {
+  const [row] = await db
+    .insert(workspaceModuleSettings)
+    .values(values)
+    .onConflictDoUpdate({
+      target: [workspaceModuleSettings.workspaceId, workspaceModuleSettings.moduleId],
+      set: { enabled: values.enabled, updatedAt: values.updatedAt },
+    })
+    .returning()
+
+  if (row === undefined) {
+    throw new Error(
+      `Upserting the "${values.moduleId}" module setting for workspace ${values.workspaceId} returned no row`,
+    )
+  }
+
+  return row
+}

package/src/modules/workspace/roles.ts

@@ -0,0 +1,38 @@
+import { INVITABLE_ROLES, INVITE_STATUSES, MEMBER_ROLES } from '@kelpie/schemas'
+import type { InvitableRole, InviteStatus, MemberRole } from '@kelpie/schemas'
+
+/**
+ * Workspace roles, ordered by authority. `owner` is a single seat per workspace,
+ * enforced in the service layer because it is a per-workspace invariant rather
+ * than a per-row one.
+ *
+ * The lists themselves live in `@kelpie/schemas`: `GET /v1/auth/me` returns a
+ * role and the team page offers one, so the browser decodes against the same
+ * values this file gates on.
+ */
+
+export { INVITABLE_ROLES, INVITE_STATUSES, MEMBER_ROLES }
+export type { InvitableRole, InviteStatus, MemberRole }
+
+const authority: Readonly<Record<MemberRole, number>> = {
+  owner: 3,
+  admin: 2,
+  member: 1,
+}
+
+/** True when `role` is at least as authoritative as `required`. */
+export function roleAllows(role: MemberRole, required: MemberRole): boolean {
+  return authority[role] >= authority[required]
+}
+
+/**
+ * Narrows a stored role string. Returns undefined for anything else, which can
+ * only happen if a row is violating its own check constraint.
+ */
+export function parseMemberRole(value: string): MemberRole | undefined {
+  return MEMBER_ROLES.find((role) => role === value)
+}
+
+export function parseInvitableRole(value: string): InvitableRole | undefined {
+  return INVITABLE_ROLES.find((role) => role === value)
+}

package/src/modules/workspace/routes.ts

@@ -0,0 +1,255 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError, toErrorDetails } from '../../lib/errors.ts'
+import { timezoneSchema } from '../../lib/timezones.ts'
+import { requireSessionActor } from '../auth/actor.ts'
+import type { Actor, SessionActor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import { INVITABLE_ROLES, MEMBER_ROLES } from './roles.ts'
+import type { InviteView, MemberView, ModuleSettingView, WorkspaceService, WorkspaceView } from './service.ts'
+
+/** Wire shapes for `/v1/workspaces`, per `onboarding.md`'s API sketch. */
+
+/** Lowercase letters, digits, and hyphens: it appears in URLs. */
+const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u
+
+const createBody = z.object({
+  name: z.string().min(1),
+  slug: z.string().min(1).max(63).regex(slugPattern, 'Use lowercase letters, digits, and hyphens'),
+  timezone: timezoneSchema,
+})
+
+export const updateBody = z
+  .object({
+    name: z.string().min(1),
+    slug: z.string().min(1).max(63).regex(slugPattern, 'Use lowercase letters, digits, and hyphens'),
+    timezone: timezoneSchema,
+    tagline: z.string().nullable(),
+    one_liner: z.string().nullable(),
+  })
+  .partial()
+
+export const inviteBody = z.object({
+  email: z.string().min(1),
+  role: z.enum(INVITABLE_ROLES),
+  invite_url_template: z.string().min(1).includes('{token}'),
+})
+
+export const resendBody = z.object({
+  invite_url_template: z.string().min(1).includes('{token}'),
+})
+
+export const memberRoleBody = z.object({ role: z.enum(MEMBER_ROLES) })
+
+export const moduleSettingBody = z.object({ enabled: z.boolean() })
+
+const acceptBody = z.object({ token: z.string().min(1) })
+
+export interface WorkspaceRoutesDependencies extends CredentialDependencies {
+  readonly service: WorkspaceService
+}
+
+async function readBody<T>(context: Context, schema: z.ZodType<T>): Promise<T> {
+  const raw: unknown = await context.req.json().catch(() => {
+    throw new AppError('bad_request', 'Body must be valid JSON')
+  })
+  const parsed = schema.safeParse(raw)
+
+  if (!parsed.success) {
+    throw AppError.validationFailed('Request body is invalid', toErrorDetails(parsed.error.issues))
+  }
+
+  return parsed.data
+}
+
+export function workspaceResponse(workspace: WorkspaceView): Record<string, unknown> {
+  return {
+    id: workspace.id,
+    name: workspace.name,
+    slug: workspace.slug,
+    timezone: workspace.timezone,
+    tagline: workspace.tagline,
+    one_liner: workspace.oneLiner,
+  }
+}
+
+export function memberResponse(member: MemberView): Record<string, unknown> {
+  return {
+    id: member.id,
+    user_id: member.userId,
+    name: member.name,
+    email: member.email,
+    role: member.role,
+    joined_at: member.joinedAt.toISOString(),
+  }
+}
+
+export function inviteResponse(invite: InviteView): Record<string, unknown> {
+  return {
+    id: invite.id,
+    email: invite.email,
+    role: invite.role,
+    status: invite.status,
+    expires_at: invite.expiresAt.toISOString(),
+    created_at: invite.createdAt.toISOString(),
+  }
+}
+
+export function moduleSettingResponse(setting: ModuleSettingView): Record<string, unknown> {
+  return { module_id: setting.moduleId, enabled: setting.enabled, locked: setting.locked }
+}
+
+export function mountWorkspaceRoutes(router: Hono, dependencies: WorkspaceRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  /** Onboarding and joining are things a person does; a key has no session to move. */
+  const requireUser = async (context: Context): Promise<SessionActor> =>
+    requireSessionActor(await resolveActorFrom(dependencies, context))
+
+  router.post('/workspaces', async (context) => {
+    const body = await readBody(context, createBody)
+    const workspace = await dependencies.service.create(await requireUser(context), body)
+
+    return context.json(workspaceResponse(workspace), 201)
+  })
+
+  router.get('/workspaces/:id', async (context) => {
+    const workspace = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(workspaceResponse(workspace))
+  })
+
+  router.patch('/workspaces/:id', async (context) => {
+    const body = await readBody(context, updateBody)
+    const workspace = await dependencies.service.update(await requireActor(context), context.req.param('id'), {
+      ...(body.name === undefined ? {} : { name: body.name }),
+      ...(body.slug === undefined ? {} : { slug: body.slug }),
+      ...(body.timezone === undefined ? {} : { timezone: body.timezone }),
+      ...(body.tagline === undefined ? {} : { tagline: body.tagline }),
+      ...(body.one_liner === undefined ? {} : { oneLiner: body.one_liner }),
+    })
+
+    return context.json(workspaceResponse(workspace))
+  })
+
+  /**
+   * The confirmation rides in the query string rather than a body: a `DELETE`
+   * body is optional in HTTP and dropped by some clients, and this one decides
+   * whether the request is honoured.
+   */
+  router.delete('/workspaces/:id', async (context) => {
+    await dependencies.service.remove(
+      await requireActor(context),
+      context.req.param('id'),
+      context.req.query('slug') ?? '',
+    )
+
+    return context.body(null, 204)
+  })
+
+  router.get('/workspaces/:id/members', async (context) => {
+    const members = await dependencies.service.listMembers(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json({ data: members.map(memberResponse), next_cursor: null })
+  })
+
+  router.patch('/workspaces/:id/members/:memberId', async (context) => {
+    const body = await readBody(context, memberRoleBody)
+    const member = await dependencies.service.setMemberRole(
+      await requireActor(context),
+      context.req.param('id'),
+      context.req.param('memberId'),
+      body.role,
+    )
+
+    return context.json(memberResponse(member))
+  })
+
+  router.delete('/workspaces/:id/members/:memberId', async (context) => {
+    await dependencies.service.removeMember(
+      await requireActor(context),
+      context.req.param('id'),
+      context.req.param('memberId'),
+    )
+
+    return context.body(null, 204)
+  })
+
+  router.post('/workspaces/:id/invites', async (context) => {
+    const body = await readBody(context, inviteBody)
+    const invite = await dependencies.service.invite(
+      await requireActor(context),
+      context.req.param('id'),
+      body.email,
+      body.role,
+      body.invite_url_template,
+    )
+
+    return context.json(inviteResponse(invite), 201)
+  })
+
+  router.get('/workspaces/:id/invites', async (context) => {
+    const invites = await dependencies.service.listInvites(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json({ data: invites.map(inviteResponse), next_cursor: null })
+  })
+
+  router.post('/workspaces/:id/invites/:inviteId/resend', async (context) => {
+    const body = await readBody(context, resendBody)
+    const invite = await dependencies.service.resendInvite(
+      await requireActor(context),
+      context.req.param('id'),
+      context.req.param('inviteId'),
+      body.invite_url_template,
+    )
+
+    return context.json(inviteResponse(invite))
+  })
+
+  router.delete('/workspaces/:id/invites/:inviteId', async (context) => {
+    await dependencies.service.revokeInvite(
+      await requireActor(context),
+      context.req.param('id'),
+      context.req.param('inviteId'),
+    )
+
+    return context.body(null, 204)
+  })
+
+  router.get('/workspaces/:id/modules', async (context) => {
+    const settings = await dependencies.service.listModuleSettings(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json({ data: settings.map(moduleSettingResponse), next_cursor: null })
+  })
+
+  router.patch('/workspaces/:id/modules/:moduleId', async (context) => {
+    const body = await readBody(context, moduleSettingBody)
+    const setting = await dependencies.service.setModuleEnabled(
+      await requireActor(context),
+      context.req.param('id'),
+      context.req.param('moduleId'),
+      body.enabled,
+    )
+
+    return context.json(moduleSettingResponse(setting))
+  })
+
+  /** Not nested under a workspace: the caller does not know which one until it resolves. */
+  router.post('/invites/accept', async (context) => {
+    const body = await readBody(context, acceptBody)
+    const workspace = await dependencies.service.acceptInvite(await requireUser(context), body.token)
+
+    return context.json(workspaceResponse(workspace))
+  })
+}