@kelpie/server 0.8.0 → 0.9.0

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),
+  ],
+)