@kelpie/server 0.1.0

package/src/modules/deals/repository.ts

@@ -0,0 +1,251 @@
+import { and, asc, eq, ilike, inArray, or, sql } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, textSort, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import { arrayContainsPattern, containsPattern } from '../../lib/search.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { companies } from '../companies/schema.ts'
+import { people } from '../people/schema.ts'
+import { workspaceMembers } from '../workspace/schema.ts'
+import { dealPeople, deals } from './schema.ts'
+
+export type DealRecord = typeof deals.$inferSelect
+
+/** The writable column shape. Services build one of these; nothing else knows the column names. */
+export type DealColumns = typeof deals.$inferInsert
+
+/** The sort fields `?sort=` documents for deals. Nullable columns (value, close date) stay out: a keyset cannot seek past a null. */
+export const DEAL_SORTS: SortableFields<DealRecord> = {
+  name: textSort(deals.name, (deal) => deal.name),
+  created_at: timestampSort(deals.createdAt, (deal) => deal.createdAt),
+  updated_at: timestampSort(deals.updatedAt, (deal) => deal.updatedAt),
+}
+
+export const DEFAULT_DEAL_SORT = '-created_at'
+
+export interface DealFilters {
+  /** `?q=`: deal name, summary, tags, competitors, or the company's name. */
+  readonly term?: string | undefined
+  /** `?company_id=`, repeatable. */
+  readonly companyIds?: readonly string[] | undefined
+  /** `?stage_id=`, repeatable: the board fetches one column with one of these. */
+  readonly stageIds?: readonly string[] | undefined
+  /** `?person_id=`, repeatable: deals any of these people are on. */
+  readonly personIds?: readonly string[] | undefined
+}
+
+/**
+ * The company half of `?q=`. Reads the `companies` *table*, never its
+ * repository, the rule set for a filter spanning a relation (`architecture.md`).
+ */
+function companyNameMatches(pattern: string): SQL {
+  return sql`exists (
+    select 1
+    from ${companies}
+    where ${companies.id} = ${deals.companyId}
+      and ${companies.name} ilike ${pattern}
+  )`
+}
+
+function hasAnyOfPeople(personIds: readonly string[]): SQL {
+  return sql`exists (
+    select 1
+    from ${dealPeople}
+    where ${dealPeople.dealId} = ${deals.id}
+      and ${inArray(dealPeople.personId, personIds)}
+  )`
+}
+
+function matchesTerm(term: string): SQL | undefined {
+  const pattern = containsPattern(term)
+
+  return or(
+    ilike(deals.name, pattern),
+    ilike(deals.summary, pattern),
+    arrayContainsPattern(deals.tags, pattern),
+    arrayContainsPattern(deals.competitors, pattern),
+    companyNameMatches(pattern),
+  )
+}
+
+function conditionsFor(workspaceId: string, filters: DealFilters): (SQL | undefined)[] {
+  return [
+    eq(deals.workspaceId, workspaceId),
+    filters.term === undefined ? undefined : matchesTerm(filters.term),
+    filters.companyIds === undefined ? undefined : inArray(deals.companyId, filters.companyIds),
+    filters.stageIds === undefined ? undefined : inArray(deals.stageId, filters.stageIds),
+    filters.personIds === undefined ? undefined : hasAnyOfPeople(filters.personIds),
+  ]
+}
+
+/** @returns Up to `window.fetchLimit` rows: one more than the page, so the caller can tell there is a next one. */
+export function listDeals(
+  db: Queryable,
+  workspaceId: string,
+  filters: DealFilters,
+  window: ListWindow<DealRecord>,
+): Promise<DealRecord[]> {
+  return db
+    .select()
+    .from(deals)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, deals.id)))
+    .orderBy(...orderByWindow(window, deals.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findDeal(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<DealRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(deals)
+    .where(and(eq(deals.workspaceId, workspaceId), eq(deals.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertDeal(db: Queryable, values: DealColumns): Promise<DealRecord> {
+  const [created] = await db.insert(deals).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting deal ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateDeal(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<DealColumns>,
+): Promise<DealRecord | undefined> {
+  const [updated] = await db
+    .update(deals)
+    .set(changes)
+    .where(and(eq(deals.workspaceId, workspaceId), eq(deals.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteDeal(db: Queryable, workspaceId: string, id: string): Promise<number> {
+  const deleted = await db
+    .delete(deals)
+    .where(and(eq(deals.workspaceId, workspaceId), eq(deals.id, id)))
+    .returning({ id: deals.id })
+
+  return deleted.length
+}
+
+/** The people on one deal. Ordered by id so a response is stable across reads. */
+export async function listPersonIds(db: Queryable, dealId: string): Promise<string[]> {
+  const rows = await db
+    .select({ personId: dealPeople.personId })
+    .from(dealPeople)
+    .where(eq(dealPeople.dealId, dealId))
+    .orderBy(asc(dealPeople.personId))
+
+  return rows.map((row) => row.personId)
+}
+
+/**
+ * The people on each of a page of deals, in one query rather than one per row.
+ *
+ * @returns Ids missing from the map have no people.
+ */
+export async function listPersonIdsFor(
+  db: Queryable,
+  dealIds: readonly string[],
+): Promise<ReadonlyMap<string, readonly string[]>> {
+  if (dealIds.length === 0) {
+    return new Map()
+  }
+
+  const rows = await db
+    .select({ dealId: dealPeople.dealId, personId: dealPeople.personId })
+    .from(dealPeople)
+    .where(inArray(dealPeople.dealId, dealIds))
+    .orderBy(asc(dealPeople.personId))
+
+  const byDeal = new Map<string, string[]>()
+
+  for (const row of rows) {
+    const existing = byDeal.get(row.dealId)
+
+    if (existing === undefined) {
+      byDeal.set(row.dealId, [row.personId])
+    } else {
+      existing.push(row.personId)
+    }
+  }
+
+  return byDeal
+}
+
+export async function insertDealPeople(
+  db: Queryable,
+  dealId: string,
+  personIds: readonly string[],
+): Promise<void> {
+  if (personIds.length === 0) {
+    return
+  }
+
+  await db.insert(dealPeople).values(personIds.map((personId) => ({ dealId, personId })))
+}
+
+export async function deleteDealPeople(
+  db: Queryable,
+  dealId: string,
+  personIds: readonly string[],
+): Promise<void> {
+  if (personIds.length === 0) {
+    return
+  }
+
+  await db
+    .delete(dealPeople)
+    .where(and(eq(dealPeople.dealId, dealId), inArray(dealPeople.personId, personIds)))
+}
+
+/**
+ * The names of these people in this workspace, keyed by id. An id missing from
+ * the map does not exist here, which is how `person_ids` is validated. Reads the
+ * `people` *table*, per the cross-relation rule in `architecture.md`.
+ */
+export async function findPeopleNamed(
+  db: Queryable,
+  workspaceId: string,
+  personIds: readonly string[],
+): Promise<ReadonlyMap<string, string>> {
+  if (personIds.length === 0) {
+    return new Map()
+  }
+
+  const rows = await db
+    .select({ id: people.id, name: people.name })
+    .from(people)
+    .where(and(eq(people.workspaceId, workspaceId), inArray(people.id, personIds)))
+
+  return new Map(rows.map((row) => [row.id, row.name]))
+}
+
+/** Whether a member belongs to this workspace, for validating `owner_id`. */
+export async function memberExists(
+  db: Queryable,
+  workspaceId: string,
+  memberId: string,
+): Promise<boolean> {
+  const [found] = await db
+    .select({ id: workspaceMembers.id })
+    .from(workspaceMembers)
+    .where(and(eq(workspaceMembers.workspaceId, workspaceId), eq(workspaceMembers.id, memberId)))
+    .limit(1)
+
+  return found !== undefined
+}

package/src/modules/deals/routes.ts

@@ -0,0 +1,166 @@
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { isoDateSchema } from '../../lib/dates.ts'
+import { pageBody, readIdFilter, readJsonBody, 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 type { CreateDealInput, DealView, DealsService, UpdateDealInput } from './service.ts'
+
+/** Wire shapes for `/v1/deals`. Bodies are strict; an unknown field is a 422, per `api.md`. */
+
+/** The full field set, without defaults. `createBody` adds those; `updateBody` makes it partial. */
+const dealShape = {
+  name: z.string().min(1),
+  company_id: z.string().min(1),
+  stage_id: z.string().min(1),
+  value_cents: z.number().int().min(0).nullable(),
+  currency: z.string().regex(/^[A-Z]{3}$/u, 'Use a three-letter ISO 4217 code').nullable(),
+  owner_id: z.string().min(1).nullable(),
+  expected_close: isoDateSchema.nullable(),
+  person_ids: z.array(z.string().min(1)),
+  competitors: z.array(z.string().min(1)),
+  risks: z.string(),
+  why_win: z.string(),
+  summary: z.string(),
+  tags: z.array(z.string().min(1)),
+  external_id: z.string().min(1).nullable(),
+}
+
+/**
+ * Only `name` and `company_id` are required. An absent `stage_id` lands in the
+ * pipeline's first open stage and an absent `owner_id` goes to the caller, both
+ * resolved in the service; the value defaults here say "unknown", not zero, so
+ * that a board of new deals does not read as a board of worthless ones.
+ */
+export const createBody = z.strictObject({
+  ...dealShape,
+  stage_id: dealShape.stage_id.optional(),
+  value_cents: dealShape.value_cents.default(null),
+  currency: dealShape.currency.default('USD'),
+  owner_id: dealShape.owner_id.optional(),
+  expected_close: dealShape.expected_close.default(null),
+  person_ids: dealShape.person_ids.default([]),
+  competitors: dealShape.competitors.default([]),
+  risks: dealShape.risks.default(''),
+  why_win: dealShape.why_win.default(''),
+  summary: dealShape.summary.default(''),
+  tags: dealShape.tags.default([]),
+  external_id: dealShape.external_id.default(null),
+})
+
+export const updateBody = z.strictObject(dealShape).partial()
+
+export interface DealsRoutesDependencies extends CredentialDependencies {
+  readonly service: DealsService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateDealInput {
+  return {
+    name: body.name,
+    companyId: body.company_id,
+    stageId: body.stage_id,
+    valueCents: body.value_cents,
+    currency: body.currency,
+    ownerId: body.owner_id,
+    expectedClose: body.expected_close,
+    personIds: body.person_ids,
+    competitors: body.competitors,
+    risks: body.risks,
+    whyWin: body.why_win,
+    summary: body.summary,
+    tags: body.tags,
+    externalId: body.external_id,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateDealInput {
+  return {
+    ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.company_id === undefined ? {} : { companyId: body.company_id }),
+    ...(body.stage_id === undefined ? {} : { stageId: body.stage_id }),
+    ...(body.value_cents === undefined ? {} : { valueCents: body.value_cents }),
+    ...(body.currency === undefined ? {} : { currency: body.currency }),
+    ...(body.owner_id === undefined ? {} : { ownerId: body.owner_id }),
+    ...(body.expected_close === undefined ? {} : { expectedClose: body.expected_close }),
+    ...(body.person_ids === undefined ? {} : { personIds: body.person_ids }),
+    ...(body.competitors === undefined ? {} : { competitors: body.competitors }),
+    ...(body.risks === undefined ? {} : { risks: body.risks }),
+    ...(body.why_win === undefined ? {} : { whyWin: body.why_win }),
+    ...(body.summary === undefined ? {} : { summary: body.summary }),
+    ...(body.tags === undefined ? {} : { tags: body.tags }),
+    ...(body.external_id === undefined ? {} : { externalId: body.external_id }),
+  }
+}
+
+export function dealResponse(deal: DealView): Record<string, unknown> {
+  return {
+    id: deal.id,
+    name: deal.name,
+    company_id: deal.companyId,
+    stage_id: deal.stageId,
+    value_cents: deal.valueCents,
+    currency: deal.currency,
+    owner_id: deal.ownerId,
+    expected_close: deal.expectedClose,
+    person_ids: deal.personIds,
+    competitors: deal.competitors,
+    risks: deal.risks,
+    why_win: deal.whyWin,
+    summary: deal.summary,
+    tags: deal.tags,
+    external_id: deal.externalId,
+    created_at: deal.createdAt.toISOString(),
+    updated_at: deal.updatedAt.toISOString(),
+  }
+}
+
+export function mountDealsRoutes(router: Hono, dependencies: DealsRoutesDependencies): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/deals', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        companyIds: readIdFilter(context, 'company_id'),
+        stageIds: readIdFilter(context, 'stage_id'),
+        personIds: readIdFilter(context, 'person_id'),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, dealResponse))
+  })
+
+  router.post('/deals', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const deal = await dependencies.service.create(await requireActor(context), toCreateInput(body))
+
+    return context.json(dealResponse(deal), 201)
+  })
+
+  router.get('/deals/:id', async (context) => {
+    const deal = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(dealResponse(deal))
+  })
+
+  router.patch('/deals/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const deal = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(dealResponse(deal))
+  })
+
+  router.delete('/deals/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/deals/schema.ts

@@ -0,0 +1,72 @@
+import { bigint, date, index, pgTable, primaryKey, text } from 'drizzle-orm/pg-core'
+
+import { createdAt, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
+import type { SearchVectorPart } from '../../lib/columns.ts'
+import { companies } from '../companies/schema.ts'
+import { people } from '../people/schema.ts'
+import { pipelineStages } from '../pipelines/schema.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
+
+/**
+ * The sales pipeline. Money is integer cents plus a currency code, never a float
+ * (`api.md`).
+ *
+ * Company, stage, and owner are all restrict: deleting any of them while a deal
+ * points at it returns 409 rather than quietly destroying the deal.
+ */
+export const deals = pgTable(
+  'deals',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    companyId: text('company_id')
+      .notNull()
+      .references(() => companies.id, { onDelete: 'restrict' }),
+    stageId: text('stage_id')
+      .notNull()
+      .references(() => pipelineStages.id, { onDelete: 'restrict' }),
+    valueCents: bigint('value_cents', { mode: 'number' }),
+    currency: text('currency'),
+    ownerId: text('owner_id').references(() => workspaceMembers.id, { onDelete: 'restrict' }),
+    expectedClose: date('expected_close'),
+    competitors: text('competitors').array().notNull().default([]),
+    risks: text('risks').notNull().default(''),
+    whyWin: text('why_win').notNull().default(''),
+    summary: text('summary').notNull().default(''),
+    tags: text('tags').array().notNull().default([]),
+    externalId: text('external_id'),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    searchVector: searchVector((): readonly SearchVectorPart[] => [
+      { column: deals.name, weight: 'A' },
+      { column: deals.risks, weight: 'B' },
+      { column: deals.whyWin, weight: 'B' },
+      { column: deals.summary, weight: 'B' },
+      { column: deals.tags, weight: 'C', array: true },
+      { column: deals.competitors, weight: 'C', array: true },
+    ]),
+  },
+  (table) => [
+    index('deals_workspace_idx').on(table.workspaceId),
+    index('deals_company_idx').on(table.companyId),
+    index('deals_stage_idx').on(table.stageId),
+    index('deals_search_idx').using('gin', table.searchVector),
+  ],
+)
+
+/** People attached to a deal. Restrict on person: a deal contact cannot vanish. */
+export const dealPeople = pgTable(
+  'deal_people',
+  {
+    dealId: text('deal_id')
+      .notNull()
+      .references(() => deals.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+      .notNull()
+      .references(() => people.id, { onDelete: 'restrict' }),
+  },
+  (table) => [primaryKey({ columns: [table.dealId, table.personId] })],
+)