@kelpie/server 0.1.0

package/src/modules/opportunities/routes.ts

@@ -0,0 +1,152 @@
+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 {
+  CreateOpportunityInput,
+  OpportunitiesService,
+  OpportunityView,
+  UpdateOpportunityInput,
+} from './service.ts'
+
+/** Wire shapes for `/v1/opportunities`. 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 opportunityShape = {
+  name: z.string().min(1),
+  kind: z.string(),
+  stage_id: z.string().min(1),
+  company_id: z.string().min(1).nullable(),
+  owner_id: z.string().min(1).nullable(),
+  expected_close: isoDateSchema.nullable(),
+  summary: z.string(),
+  tags: z.array(z.string().min(1)),
+}
+
+/**
+ * Only `name` is required: an opportunity 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. `kind` defaults
+ * to empty rather than to the mockup's invented "Other"; an unclassified
+ * opportunity should read as unclassified.
+ */
+export const createBody = z.strictObject({
+  ...opportunityShape,
+  kind: opportunityShape.kind.default(''),
+  stage_id: opportunityShape.stage_id.optional(),
+  company_id: opportunityShape.company_id.default(null),
+  owner_id: opportunityShape.owner_id.optional(),
+  expected_close: opportunityShape.expected_close.default(null),
+  summary: opportunityShape.summary.default(''),
+  tags: opportunityShape.tags.default([]),
+})
+
+export const updateBody = z.strictObject(opportunityShape).partial()
+
+export interface OpportunitiesRoutesDependencies extends CredentialDependencies {
+  readonly service: OpportunitiesService
+}
+
+export function toCreateInput(body: z.infer<typeof createBody>): CreateOpportunityInput {
+  return {
+    name: body.name,
+    kind: body.kind,
+    stageId: body.stage_id,
+    companyId: body.company_id,
+    ownerId: body.owner_id,
+    expectedClose: body.expected_close,
+    summary: body.summary,
+    tags: body.tags,
+  }
+}
+
+export function toUpdateInput(body: z.infer<typeof updateBody>): UpdateOpportunityInput {
+  return {
+    ...(body.name === undefined ? {} : { name: body.name }),
+    ...(body.kind === undefined ? {} : { kind: body.kind }),
+    ...(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.expected_close === undefined ? {} : { expectedClose: body.expected_close }),
+    ...(body.summary === undefined ? {} : { summary: body.summary }),
+    ...(body.tags === undefined ? {} : { tags: body.tags }),
+  }
+}
+
+export function opportunityResponse(opportunity: OpportunityView): Record<string, unknown> {
+  return {
+    id: opportunity.id,
+    name: opportunity.name,
+    kind: opportunity.kind,
+    stage_id: opportunity.stageId,
+    company_id: opportunity.companyId,
+    owner_id: opportunity.ownerId,
+    expected_close: opportunity.expectedClose,
+    summary: opportunity.summary,
+    tags: opportunity.tags,
+    created_at: opportunity.createdAt.toISOString(),
+    updated_at: opportunity.updatedAt.toISOString(),
+  }
+}
+
+export function mountOpportunitiesRoutes(
+  router: Hono,
+  dependencies: OpportunitiesRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  router.get('/opportunities', async (context) => {
+    const page = await dependencies.service.list(
+      await requireActor(context),
+      {
+        term: context.req.query('q'),
+        kinds: readIdFilter(context, 'kind'),
+        companyIds: readIdFilter(context, 'company_id'),
+        stageIds: readIdFilter(context, 'stage_id'),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, opportunityResponse))
+  })
+
+  router.post('/opportunities', async (context) => {
+    const body = await readJsonBody(context, createBody)
+    const opportunity = await dependencies.service.create(
+      await requireActor(context),
+      toCreateInput(body),
+    )
+
+    return context.json(opportunityResponse(opportunity), 201)
+  })
+
+  router.get('/opportunities/:id', async (context) => {
+    const opportunity = await dependencies.service.get(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(opportunityResponse(opportunity))
+  })
+
+  router.patch('/opportunities/:id', async (context) => {
+    const body = await readJsonBody(context, updateBody)
+    const opportunity = await dependencies.service.update(
+      await requireActor(context),
+      context.req.param('id'),
+      toUpdateInput(body),
+    )
+
+    return context.json(opportunityResponse(opportunity))
+  })
+
+  router.delete('/opportunities/:id', async (context) => {
+    await dependencies.service.remove(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

package/src/modules/opportunities/schema.ts

@@ -0,0 +1,47 @@
+import { date, index, 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 { pipelineStages } from '../pipelines/schema.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
+
+/**
+ * Non-sales chances: grants, accelerators, tenders, press, speaking. Not an alias
+ * for Deal.
+ *
+ * `company_id` is nullable because a speaking slot or a grant need not belong to
+ * a company on file.
+ */
+export const opportunities = pgTable(
+  'opportunities',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    kind: text('kind').notNull(),
+    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' }),
+    expectedClose: date('expected_close'),
+    summary: text('summary').notNull().default(''),
+    tags: text('tags').array().notNull().default([]),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+    searchVector: searchVector((): readonly SearchVectorPart[] => [
+      { column: opportunities.name, weight: 'A' },
+      { column: opportunities.kind, weight: 'B' },
+      { column: opportunities.summary, weight: 'B' },
+      { column: opportunities.tags, weight: 'C', array: true },
+    ]),
+  },
+  (table) => [
+    index('opportunities_workspace_idx').on(table.workspaceId),
+    index('opportunities_stage_idx').on(table.stageId),
+    index('opportunities_search_idx').using('gin', table.searchVector),
+  ],
+)

package/src/modules/opportunities/service.ts

@@ -0,0 +1,342 @@
+import { changedKeys } from '../../lib/changes.ts'
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import { readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { ActivityRecorder } from '../activities/recorder.ts'
+import { describeCreation, describeStageChange, describeUpdate } from '../activities/wording.ts'
+import type { FieldLabels } from '../activities/wording.ts'
+import type { Actor } from '../auth/actor.ts'
+import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
+import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import * as companyRepository from '../companies/repository.ts'
+import * as pipelineRepository from '../pipelines/repository.ts'
+import type { PipelineStageRecord } from '../pipelines/repository.ts'
+import * as repository from './repository.ts'
+import { DEFAULT_OPPORTUNITY_SORT, OPPORTUNITY_SORTS } from './repository.ts'
+import type { OpportunityFilters, OpportunityRecord } from './repository.ts'
+
+/**
+ * Opportunities: the non-sales pipeline. Grants, accelerators, tenders, press,
+ * speaking — same stage mechanics as Deals, different lens, and no people links.
+ *
+ * A stage move is an ordinary PATCH of `stage_id`, and it is the one change that
+ * files a `stage_changed` activity and a `stage.changed` event instead of the
+ * generic update pair.
+ */
+
+export interface OpportunitiesDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly recordActivity: ActivityRecorder
+}
+
+/** What a changed column is called on a timeline. The mockup says "Target date", not "Expected close". */
+const OPPORTUNITY_FIELD_LABELS: FieldLabels = {
+  name: 'Name',
+  kind: 'Kind',
+  companyId: 'Company',
+  ownerId: 'Owner',
+  expectedClose: 'Target date',
+  summary: 'Summary',
+  tags: 'Tags',
+}
+
+/** An opportunity as the API returns one: the stored row minus tenancy. */
+export type OpportunityView = Omit<OpportunityRecord, 'workspaceId'>
+
+export interface CreateOpportunityInput {
+  readonly name: string
+  /**
+   * Free text. Empty means unclassified: the mockup's Add button invents
+   * "Other", and a fabricated kind is worse than an absent one for agents.
+   */
+  readonly kind: string
+  /** Absent means the pipeline's default stage: the first open one. */
+  readonly stageId: string | undefined
+  readonly companyId: string | null
+  /** Absent means the caller: the member creating an opportunity starts as its owner. */
+  readonly ownerId: string | null | undefined
+  readonly expectedClose: string | null
+  readonly summary: string
+  readonly tags: readonly string[]
+}
+
+/** PATCH semantics: an absent field is left alone, and null clears a nullable one. */
+export interface UpdateOpportunityInput {
+  readonly name?: string | undefined
+  readonly kind?: string | undefined
+  readonly stageId?: string | undefined
+  readonly companyId?: string | null | undefined
+  readonly ownerId?: string | null | undefined
+  readonly expectedClose?: string | null | undefined
+  readonly summary?: string | undefined
+  readonly tags?: readonly string[] | undefined
+}
+
+export interface OpportunitiesService {
+  list(
+    actor: Actor,
+    filters: OpportunityFilters,
+    query: ListQueryParameters,
+  ): Promise<Page<OpportunityView>>
+  get(actor: Actor, id: string): Promise<OpportunityView>
+  create(actor: Actor, input: CreateOpportunityInput): Promise<OpportunityView>
+  update(actor: Actor, id: string, changes: UpdateOpportunityInput): Promise<OpportunityView>
+  remove(actor: Actor, id: string): Promise<void>
+}
+
+function toView(record: OpportunityRecord): OpportunityView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+function toStoredColumns(input: UpdateOpportunityInput): Partial<repository.OpportunityColumns> {
+  return {
+    ...(input.name === undefined ? {} : { name: input.name }),
+    ...(input.kind === undefined ? {} : { kind: input.kind }),
+    ...(input.stageId === undefined ? {} : { stageId: input.stageId }),
+    ...(input.companyId === undefined ? {} : { companyId: input.companyId }),
+    ...(input.ownerId === undefined ? {} : { ownerId: input.ownerId }),
+    ...(input.expectedClose === undefined ? {} : { expectedClose: input.expectedClose }),
+    ...(input.summary === undefined ? {} : { summary: input.summary }),
+    ...(input.tags === undefined ? {} : { tags: [...input.tags] }),
+  }
+}
+
+export function createOpportunitiesService(
+  dependencies: OpportunitiesDependencies,
+): OpportunitiesService {
+  async function require(workspaceId: string, id: string): Promise<OpportunityRecord> {
+    const opportunity = await repository.findOpportunity(dependencies.db, workspaceId, id)
+
+    if (opportunity === undefined) {
+      throw AppError.notFound('Opportunity not found')
+    }
+
+    return opportunity
+  }
+
+  async function requireCompany(workspaceId: string, companyId: string): Promise<void> {
+    const company = await companyRepository.findCompany(dependencies.db, workspaceId, companyId)
+
+    if (company === undefined) {
+      throw AppError.notFound('Company not found')
+    }
+  }
+
+  /**
+   * A stage an opportunity may sit in: exists in this workspace and belongs to
+   * the opportunity pipeline. The wrong-workspace case reads as missing, per
+   * `api.md`; the wrong-pipeline case is a request naming a real stage that can
+   * never hold an opportunity, which is a validation error rather than a missing
+   * record.
+   */
+  async function requireOpportunityStage(
+    workspaceId: string,
+    stageId: string,
+  ): Promise<PipelineStageRecord> {
+    const stage = await pipelineRepository.findStage(dependencies.db, workspaceId, stageId)
+
+    if (stage === undefined) {
+      throw AppError.notFound('Pipeline stage not found')
+    }
+
+    if (stage.kind !== 'opportunity') {
+      throw AppError.validationFailed('That stage is not part of the opportunity pipeline', [
+        { field: 'stage_id', message: `It belongs to the ${stage.kind} pipeline` },
+      ])
+    }
+
+    return stage
+  }
+
+  /** The default stage for a new opportunity: the first open one, or the first if none are open. */
+  async function defaultOpportunityStage(workspaceId: string): Promise<PipelineStageRecord> {
+    const rows = await pipelineRepository.listStagesOfKind(
+      dependencies.db,
+      workspaceId,
+      'opportunity',
+    )
+    const first = rows.find((row) => row.open) ?? rows[0]
+
+    if (first === undefined) {
+      // Unreachable through the API: workspaces seed stages and the last stage
+      // of a pipeline cannot be removed.
+      throw AppError.conflict('This workspace has no opportunity stages')
+    }
+
+    return first
+  }
+
+  async function requireOwner(workspaceId: string, ownerId: string): Promise<void> {
+    if (!(await repository.memberExists(dependencies.db, workspaceId, ownerId))) {
+      throw AppError.notFound('Team member not found')
+    }
+  }
+
+  return {
+    async list(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, OPPORTUNITY_SORTS, DEFAULT_OPPORTUNITY_SORT)
+      const rows = await repository.listOpportunities(dependencies.db, workspaceId, filters, window)
+      const page = toPage(rows, window, (opportunity) => opportunity.id)
+
+      return { items: page.items.map(toView), nextCursor: page.nextCursor }
+    },
+
+    async get(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      return toView(await require(workspaceId, id))
+    },
+
+    async create(actor, input) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      if (input.companyId !== null) {
+        await requireCompany(workspaceId, input.companyId)
+      }
+
+      const stage =
+        input.stageId === undefined
+          ? await defaultOpportunityStage(workspaceId)
+          : await requireOpportunityStage(workspaceId, input.stageId)
+      const ownerId = input.ownerId === undefined ? actorMemberId(actor) : input.ownerId
+
+      if (ownerId !== null) {
+        await requireOwner(workspaceId, ownerId)
+      }
+
+      const id = dependencies.createId('opportunity')
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const created = await repository.insertOpportunity(tx, {
+          id,
+          workspaceId,
+          name: input.name,
+          kind: input.kind,
+          stageId: stage.id,
+          companyId: input.companyId,
+          ownerId,
+          expectedClose: input.expectedClose,
+          summary: input.summary,
+          tags: [...input.tags],
+        })
+
+        await dependencies.recordActivity(tx, workspaceId, actor, {
+          targetType: 'opportunity',
+          targetId: id,
+          kind: 'created',
+          ...describeCreation('Opportunity'),
+        })
+
+        events.emit('record.created', { workspaceId, objectType: 'opportunity', recordId: id })
+
+        return toView(created)
+      })
+    },
+
+    async update(actor, id, changes) {
+      const workspaceId = requireWorkspaceId(actor)
+      const existing = await require(workspaceId, id)
+
+      if (
+        typeof changes.companyId === 'string' &&
+        changes.companyId !== existing.companyId
+      ) {
+        await requireCompany(workspaceId, changes.companyId)
+      }
+
+      const stageMove =
+        changes.stageId === undefined || changes.stageId === existing.stageId
+          ? undefined
+          : {
+              from: await requireOpportunityStage(workspaceId, existing.stageId),
+              to: await requireOpportunityStage(workspaceId, changes.stageId),
+            }
+
+      if (typeof changes.ownerId === 'string' && changes.ownerId !== existing.ownerId) {
+        await requireOwner(workspaceId, changes.ownerId)
+      }
+
+      const columns = toStoredColumns(changes)
+      const changed = changedKeys(existing, columns)
+
+      if (changed.length === 0) {
+        return toView(existing)
+      }
+
+      return dependencies.transaction(async ({ tx, events }) => {
+        const updated = await repository.updateOpportunity(tx, workspaceId, id, {
+          ...columns,
+          updatedAt: dependencies.now(),
+        })
+
+        if (updated === undefined) {
+          throw AppError.notFound('Opportunity not found')
+        }
+
+        if (stageMove !== undefined) {
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'opportunity',
+            targetId: id,
+            kind: 'stage_changed',
+            ...describeStageChange(stageMove.from.label, stageMove.to.label),
+          })
+        }
+
+        const otherChanged = changed.filter((field) => field !== 'stageId')
+
+        if (otherChanged.length > 0) {
+          await dependencies.recordActivity(tx, workspaceId, actor, {
+            targetType: 'opportunity',
+            targetId: id,
+            kind: 'updated',
+            ...describeUpdate(otherChanged, OPPORTUNITY_FIELD_LABELS, existing, columns),
+          })
+        }
+
+        events.emit('record.updated', {
+          workspaceId,
+          objectType: 'opportunity',
+          recordId: id,
+          changedFields: changed,
+        })
+
+        if (stageMove !== undefined) {
+          events.emit('stage.changed', {
+            workspaceId,
+            objectType: 'opportunity',
+            recordId: id,
+            fromStageId: stageMove.from.id,
+            toStageId: stageMove.to.id,
+          })
+        }
+
+        return toView(updated)
+      })
+    },
+
+    async remove(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+
+      await dependencies.transaction(async ({ tx, events }) => {
+        await require(workspaceId, id)
+
+        // Notes, activities, decisions and plan items have no foreign key to
+        // their target, so the deleting service removes them here, in the same
+        // transaction. Nothing else references an opportunity.
+        await deleteRecordsAttachedTo(tx, workspaceId, 'opportunity', id)
+        await repository.deleteOpportunity(tx, workspaceId, id)
+
+        events.emit('record.deleted', { workspaceId, objectType: 'opportunity', recordId: id })
+      })
+    },
+  }
+}

package/src/modules/opportunities/tools.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import { createBody, opportunityResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { OpportunitiesService } from './service.ts'
+
+/** `opportunities_*`. Same schemas and mappers as `/v1/opportunities`. */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  q: termArg,
+  kind: idSetArg.optional().describe('Kinds are free text, so a match here is exact.'),
+  company_id: idSetArg.optional().describe('Only opportunities with these companies.'),
+  stage_id: idSetArg.optional().describe('Only opportunities in these pipeline stages.'),
+})
+
+export function registerOpportunitiesTools(mcp: McpToolRegistry, service: OpportunitiesService): void {
+  registerCrudTools(mcp, {
+    resource: 'opportunities',
+    subject: 'opportunity',
+    about:
+      'A non-sales chance: a grant, accelerator, tender, press or speaking slot. ' +
+      'Not another word for a deal.',
+    service,
+    render: opportunityResponse,
+    listArgs,
+    toFilters: (args) => ({
+      term: args.q,
+      kinds: toSet(args.kind),
+      companyIds: toSet(args.company_id),
+      stageIds: toSet(args.stage_id),
+    }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/partnerships/index.ts

@@ -0,0 +1,44 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { mountPartnershipsRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createPartnershipsService } from './service.ts'
+import { registerPartnershipsTools } from './tools.ts'
+
+/**
+ * Partnerships: ongoing two-way relationships.
+ *
+ * Requires its relations because creating one checks that the company, stage,
+ * owner, and key people are all in the caller's workspace before linking them,
+ * and `activities` because every write leaves its timeline entry in the same
+ * transaction.
+ */
+export function createPartnershipsModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'partnerships',
+    requires: ['companies', 'people', 'pipelines', 'activities'],
+
+    register(context) {
+      const service = createPartnershipsService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        recordActivity: createActivityRecorder({
+          createId: context.createId,
+          now: context.now,
+        }),
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountPartnershipsRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      registerPartnershipsTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}