@kelpie/server 0.7.0 → 0.9.0

package/src/modules/enquiries/repository.ts

@@ -0,0 +1,164 @@
+import { and, 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 { anyPersonLinked } from '../personLinks.ts'
+import { workspaceMembers } from '../workspace/schema.ts'
+import { enquiries } from './schema.ts'
+
+export type EnquiryRecord = typeof enquiries.$inferSelect
+
+/** The writable column shape. Services build one of these; nothing else knows the column names. */
+export type EnquiryColumns = typeof enquiries.$inferInsert
+
+/** The sort fields `?sort=` documents. */
+export const ENQUIRY_SORTS: SortableFields<EnquiryRecord> = {
+  name: textSort(enquiries.name, (enquiry) => enquiry.name),
+  created_at: timestampSort(enquiries.createdAt, (enquiry) => enquiry.createdAt),
+  updated_at: timestampSort(enquiries.updatedAt, (enquiry) => enquiry.updatedAt),
+}
+
+export const DEFAULT_ENQUIRY_SORT = '-created_at'
+
+export interface EnquiryFilters {
+  /** `?q=`: name, source, summary, tags, or the company's name. */
+  readonly term?: string | undefined
+  /** `?source=`, repeatable: sources are free text, so a match is exact, not fuzzy. */
+  readonly sources?: readonly 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: enquiries 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} = ${enquiries.companyId}
+      and ${companies.workspaceId} = ${enquiries.workspaceId}
+      and ${companies.name} ilike ${pattern}
+  )`
+}
+
+function matchesTerm(term: string): SQL | undefined {
+  const pattern = containsPattern(term)
+
+  return or(
+    ilike(enquiries.name, pattern),
+    ilike(enquiries.source, pattern),
+    ilike(enquiries.summary, pattern),
+    arrayContainsPattern(enquiries.tags, pattern),
+    companyNameMatches(pattern),
+  )
+}
+
+function conditionsFor(workspaceId: string, filters: EnquiryFilters): (SQL | undefined)[] {
+  return [
+    eq(enquiries.workspaceId, workspaceId),
+    filters.term === undefined ? undefined : matchesTerm(filters.term),
+    filters.sources === undefined ? undefined : inArray(enquiries.source, filters.sources),
+    filters.companyIds === undefined
+      ? undefined
+      : inArray(enquiries.companyId, filters.companyIds),
+    filters.stageIds === undefined ? undefined : inArray(enquiries.stageId, filters.stageIds),
+    filters.personIds === undefined
+      ? undefined
+      : anyPersonLinked('enquiry', enquiries.id, enquiries.workspaceId, 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 listEnquiries(
+  db: Queryable,
+  workspaceId: string,
+  filters: EnquiryFilters,
+  window: ListWindow<EnquiryRecord>,
+): Promise<EnquiryRecord[]> {
+  return db
+    .select()
+    .from(enquiries)
+    .where(and(...conditionsFor(workspaceId, filters), keysetCondition(window, enquiries.id)))
+    .orderBy(...orderByWindow(window, enquiries.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findEnquiry(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<EnquiryRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(enquiries)
+    .where(and(eq(enquiries.workspaceId, workspaceId), eq(enquiries.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertEnquiry(
+  db: Queryable,
+  values: EnquiryColumns,
+): Promise<EnquiryRecord> {
+  const [created] = await db.insert(enquiries).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting enquiry ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateEnquiry(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<EnquiryColumns>,
+): Promise<EnquiryRecord | undefined> {
+  const [updated] = await db
+    .update(enquiries)
+    .set(changes)
+    .where(and(eq(enquiries.workspaceId, workspaceId), eq(enquiries.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteEnquiry(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(enquiries)
+    .where(and(eq(enquiries.workspaceId, workspaceId), eq(enquiries.id, id)))
+    .returning({ id: enquiries.id })
+
+  return deleted.length
+}
+
+/** 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/enquiries/routes.ts

@@ -0,0 +1,172 @@
+import { customFieldsPatchShape } from '@kelpie/schemas'
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+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 { renderCustomFieldsForWire } from '../custom-fields/wire.ts'
+import { dealResponse } from '../deals/routes.ts'
+import type { CreateEnquiryInput, EnquiriesService, EnquiryView, UpdateEnquiryInput } from './service.ts'
+
+/** Wire shapes for `/v1/enquiries`. 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. `converted_deal_id` is read-only: it is set only by
+ * `POST /v1/enquiries/:id/convert`, so it is not in this shape and any
+ * `PATCH` that carries it is `422`.
+ */
+const enquiryShape = {
+  name: z.string().min(1),
+  source: z.string(),
+  stage_id: z.string().min(1),
+  company_id: z.string().min(1).nullable(),
+  owner_id: z.string().min(1).nullable(),
+  person_ids: z.array(z.string().min(1)),
+  summary: z.string(),
+  tags: z.array(z.string().min(1)),
+  custom_fields: customFieldsPatchShape,
+}
+
+/**
+ * Only `name` is required: an enquiry need not belong to a company. 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. `source`
+ * defaults to empty; an unclassified enquiry should read as unclassified.
+ */
+export const createBody = z.strictObject({
+  ...enquiryShape,
+  source: enquiryShape.source.default(''),
+  stage_id: enquiryShape.stage_id.optional(),
+  company_id: enquiryShape.company_id.default(null),
+  owner_id: enquiryShape.owner_id.optional(),
+  person_ids: enquiryShape.person_ids.default([]),
+  summary: enquiryShape.summary.default(''),
+  tags: enquiryShape.tags.default([]),
+  custom_fields: enquiryShape.custom_fields.default({}),
+})
+
+export const updateBody = z.strictObject(enquiryShape).partial()
+
+export interface EnquiriesRoutesDependencies extends CredentialDependencies {
+  readonly service: EnquiriesService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateEnquiryInput {
+  return {
+    name: body.name,
+    source: body.source,
+    stageId: body.stage_id,
+    companyId: body.company_id,
+    ownerId: body.owner_id,
+    personIds: body.person_ids,
+    summary: body.summary,
+    tags: body.tags,
+    customFields: body.custom_fields,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateEnquiryInput {
+  return {
+    ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.source === undefined ? {} : { source: body.source }),
+    ...(body.stage_id === undefined ? {} : { stageId: body.stage_id }),
+    ...(body.company_id === undefined ? {} : { companyId: body.company_id }),
+    ...(body.owner_id === undefined ? {} : { ownerId: body.owner_id }),
+    ...(body.person_ids === undefined ? {} : { personIds: body.person_ids }),
+    ...(body.summary === undefined ? {} : { summary: body.summary }),
+    ...(body.tags === undefined ? {} : { tags: body.tags }),
+    ...(body.custom_fields === undefined ? {} : { customFields: body.custom_fields }),
+  }
+}
+
+export function enquiryResponse(enquiry: EnquiryView): Record<string, unknown> {
+  return {
+    id: enquiry.id,
+    name: enquiry.name,
+    source: enquiry.source,
+    stage_id: enquiry.stageId,
+    company_id: enquiry.companyId,
+    owner_id: enquiry.ownerId,
+    converted_deal_id: enquiry.convertedDealId,
+    person_ids: enquiry.personIds,
+    summary: enquiry.summary,
+    tags: enquiry.tags,
+    custom_fields: renderCustomFieldsForWire(enquiry.customFields),
+    created_at: enquiry.createdAt.toISOString(),
+    updated_at: enquiry.updatedAt.toISOString(),
+  }
+}
+
+export function mountEnquiriesRoutes(
+  router: Hono,
+  dependencies: EnquiriesRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/enquiries', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        sources: readIdFilter(context, 'source'),
+        companyIds: readIdFilter(context, 'company_id'),
+        stageIds: readIdFilter(context, 'stage_id'),
+        personIds: readIdFilter(context, 'person_id'),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, enquiryResponse))
+  })
+
+  router.post('/enquiries', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const enquiry = await dependencies.service.create(
+      await requireActor(context),
+      toCreateInput(body),
+    )
+
+    return context.json(enquiryResponse(enquiry), 201)
+  })
+
+  router.get('/enquiries/:id', async (context) => {
+    const enquiry = await dependencies.service.get(await requireActor(context), context.req.param('id'))
+
+    return context.json(enquiryResponse(enquiry))
+  })
+
+  router.patch('/enquiries/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const enquiry = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(enquiryResponse(enquiry))
+  })
+
+  router.delete('/enquiries/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+
+  /**
+   * Convert an enquiry to a deal. Idempotent-ish: a second call 409s and
+   * carries the existing deal id in `details`. Returns the freshly created
+   * deal, wire-shaped, so the caller can navigate straight to it.
+   */
+  router.post('/enquiries/:id/convert', async (context) => {
+    const { deal, personIds } = await dependencies.service.convertToDeal(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+    const { workspaceId: _workspaceId, ...dealView } = deal
+
+    return context.json(dealResponse({ ...dealView, personIds }), 201)
+  })
+}

package/src/modules/enquiries/schema.ts

@@ -0,0 +1,59 @@
+import type { CustomFieldValue } from '@kelpie/schemas'
+import { index, jsonb, pgTable, 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 { deals } from '../deals/schema.ts'
+import { pipelineStages } from '../pipelines/schema.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
+
+/**
+ * Enquiries: the top-of-funnel pipeline. An inbound request — website form,
+ * email, referral — that may become a Deal once qualified.
+ *
+ * `source` is free text like Opportunity's `kind`; a form is a source, and the
+ * kinds a workspace uses vary. `company_id` is nullable because an early
+ * enquiry may arrive before a company is on file. `converted_deal_id` becomes
+ * non-null when the enquiry is converted via
+ * `POST /v1/enquiries/:id/convert`; deleting the deal nulls it back so a
+ * fresh conversion is possible.
+ */
+export const enquiries = pgTable(
+  'enquiries',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    source: text('source').notNull().default(''),
+    stageId: text('stage_id')
+      .notNull()
+      .references(() => pipelineStages.id, { onDelete: 'restrict' }),
+    companyId: text('company_id').references(() => companies.id, { onDelete: 'restrict' }),
+    ownerId: text('owner_id').references(() => workspaceMembers.id, { onDelete: 'restrict' }),
+    convertedDealId: text('converted_deal_id').references(() => deals.id, { onDelete: 'set null' }),
+    summary: text('summary').notNull().default(''),
+    tags: text('tags').array().notNull().default([]),
+    // Workspace-defined fields, keyed by definition key. See people/schema.ts.
+    customFields: jsonb('custom_fields')
+      .$type<Readonly<Record<string, CustomFieldValue>>>()
+      .notNull()
+      .default({}),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    searchVector: searchVector((): readonly SearchVectorPart[] => [
+      { column: enquiries.name, weight: 'A' },
+      { column: enquiries.source, weight: 'B' },
+      { column: enquiries.summary, weight: 'B' },
+      { column: enquiries.tags, weight: 'C', array: true },
+    ]),
+  },
+  (table) => [
+    index('enquiries_workspace_idx').on(table.workspaceId),
+    index('enquiries_stage_idx').on(table.stageId),
+    index('enquiries_converted_deal_idx').on(table.convertedDealId),
+    index('enquiries_search_idx').using('gin', table.searchVector),
+  ],
+)