@kelpie/server 0.12.0 → 0.14.0

package/src/lib/jobs.ts

@@ -0,0 +1,126 @@
+import type { ZodType } from 'zod'
+
+import type { Logger } from './logger.ts'
+
+/**
+ * The port core runs background work through.
+ *
+ * A module declares a handle at register time with `context.jobs.define(...)`
+ * and enqueues against it from a service. The insert lives inside the same
+ * Drizzle transaction as the write it belongs to, so a rolled-back write
+ * never leaves an orphan job behind. Handlers run out of process — on the
+ * worker entry point, or inline when the API runs its own worker — and see
+ * the same payload the caller passed, validated against the module's Zod
+ * schema before it reaches user code.
+ *
+ * The port itself knows nothing about pg-boss. `runtime/jobs.ts` binds it to
+ * a real provider at boot; tests bind it to a stub. Nothing outside the
+ * runtime imports the provider directly.
+ *
+ * Why a handle rather than a global name map: consumers of `@kelpie/server`
+ * installed from npm lost the `KelpieEventMap` augmentation until every
+ * catalog was pulled in from the entry point (see
+ * `modules/eventCatalogs.ts`). A handle keeps the payload type on the value
+ * the module exports, so `enqueue(handle, data)` typechecks without
+ * declaration merging across the package boundary.
+ */
+
+/**
+ * Marker property carrying the handle's payload type. Never assigned at
+ * runtime; the `?` on the property makes an untagged plain object satisfy the
+ * shape at read time, so a stub handle in a test can be built without
+ * `unsafeCast`.
+ */
+declare const JobHandleDataMarker: unique symbol
+
+/** A typed reference a module exports after `define()`. */
+export interface JobHandle<Data> {
+  readonly name: string
+  readonly [JobHandleDataMarker]?: Data
+}
+
+/**
+ * Defaults every enqueue on this queue inherits, unless the caller overrides
+ * on a per-`enqueue` basis. `localConcurrency` sizes the work loop on the
+ * worker; the rest match pg-boss's `QueueOptions` names.
+ *
+ * `retryDelay` is in seconds. pg-boss's default is 0 (immediate retry).
+ * `retryLimit` counts the retries pg-boss does after the first run; a job
+ * with `retryLimit: 2` runs at most three times.
+ */
+export interface JobDefaults {
+  readonly retryLimit?: number
+  readonly retryDelay?: number
+  readonly retryBackoff?: boolean
+  readonly retryDelayMax?: number
+  readonly expireInSeconds?: number
+  readonly localConcurrency?: number
+}
+
+/** Passed to a job handler when a worker picks the job up. */
+export interface JobContext<Data> {
+  readonly id: string
+  readonly data: Data
+  readonly log: Logger
+  /** Fires when pg-boss decides the job has expired. Long-running handlers should honour it. */
+  readonly signal: AbortSignal
+}
+
+export type JobHandler<Data> = (context: JobContext<Data>) => Promise<void>
+
+export interface JobDefinition<Data> {
+  /**
+   * The queue name pg-boss stores against. Must be unique across the
+   * assembly; a second `define()` with the same name fails boot.
+   *
+   * Prefix with the module id — `webhooks.deliver`, `agent-tasks.dispatch` —
+   * so operators reading `pgboss.job` see who owns it.
+   */
+  readonly name: string
+  /**
+   * Parses the payload at handle time before it reaches user code. A job
+   * whose payload no longer matches fails, retries, and eventually
+   * dead-letters like any other failure.
+   */
+  readonly schema: ZodType<Data>
+  readonly handler: JobHandler<Data>
+  readonly defaults?: JobDefaults
+}
+
+/**
+ * The registration surface exposed to a module through `context.jobs`. Modules
+ * hand a definition in and receive a typed handle to enqueue against.
+ */
+export interface JobRegistry {
+  define<Data>(definition: JobDefinition<Data>): JobHandle<Data>
+}
+
+/**
+ * Options a caller may override per `enqueue`. Deliberately narrow: features
+ * beyond retries, a singleton key, and a deferred start are out of scope until
+ * a consumer needs them (`crm-brief.md` cost/maintainability trade-offs).
+ */
+export interface EnqueueOptions {
+  readonly retryLimit?: number
+  readonly retryBackoff?: boolean
+  readonly singletonKey?: string
+  readonly startAfter?: number | string | Date
+}
+
+/**
+ * Exposed on the transaction context next to `events`. `enqueue` runs its
+ * insert inside the caller's transaction via pg-boss's `fromDrizzle` adapter,
+ * so a rollback discards the job with the write.
+ */
+export interface TransactionJobs {
+  enqueue<Data>(
+    handle: JobHandle<Data>,
+    data: Data,
+    options?: EnqueueOptions,
+  ): Promise<string | null>
+}
+
+/** The name pg-boss stores the dead-letter queue under, given a handle name. */
+export function deadLetterQueueName(jobName: string): string {
+  return `${jobName}.dead`
+}

package/src/lib/kelpieConfigFile.ts

@@ -1,6 +1,17 @@
+import type { PublicRegion } from '@kelpie/schemas'
+import { publicRegionSchema } from '@kelpie/schemas'
+
 import type { KelpieModule } from '../runtime/module.ts'
-import { ConfigurationError, type Environment, type KelpieConfig, type LogLevel, type RuntimeMode } from './config.ts'
+import {
+  ConfigurationError,
+  type Environment,
+  type KelpieConfig,
+  type LogLevel,
+  type RuntimeMode,
+  type SignupsMode,
+} from './config.ts'
 import type { EmailConfig } from './email.ts'
+import { describeValidationIssue } from './errors.ts'
 import { type ConfigValue, resolveMarkers } from './fromEnv.ts'
 import type { LoggingDestination } from './logger.ts'
 import type { RateLimitConfig } from './rateLimit.ts'
@@ -35,6 +46,19 @@ export interface KelpieConfigInput {
   readonly siteName?: ConfigValue<string | undefined>
   /** Optional; defaults to 0 (no proxy in front). */
   readonly trustedProxyHopCount?: ConfigValue<number>
+  /**
+   * Whether the instance accepts a brand-new account. Optional; defaults to
+   * `'open'`, matching `loadConfig`'s default, so an assembly that never sets
+   * this sees no change in behaviour.
+   */
+  readonly signups?: ConfigValue<SignupsMode>
+  /**
+   * Origins a multi-region assembly advertises on signed-out pages. Optional;
+   * omitted or empty hides the switcher, matching a self-hosted install.
+   * Two or more draws it. Each `id` and `origin` must be unique, and each
+   * `origin` must be an absolute `http:` or `https:` origin.
+   */
+  readonly regions?: ConfigValue<readonly PublicRegion[]>
   /**
    * The deployment's base URL. Every emailed link (password reset, email
    * verification, invite) is built from it. Required by the workspace and auth
@@ -164,6 +188,9 @@ export function resolveKelpieConfig(input: KelpieConfigInput, environment: Envir
   const rateLimit = buildRateLimitConfig(resolved.rateLimit)
   const env = mergeEnv(environment, resolved.env)
   const secretEncryption = buildSecretEncryptionConfig(resolved.secretEncryption)
+  const regions = resolved.regions ?? []
+
+  problems.push(...describeRegionProblems(regions))
 
   if (problems.length > 0) {
     throw new ConfigurationError(problems)
@@ -186,6 +213,8 @@ export function resolveKelpieConfig(input: KelpieConfigInput, environment: Envir
     env,
     appBaseUrl: resolved.appBaseUrl,
     secretEncryption,
+    signups: resolved.signups ?? 'open',
+    regions,
   }
 }
 
@@ -217,6 +246,8 @@ interface ResolvedInput {
   readonly moduleConfigPath?: string | undefined
   readonly siteName?: string | undefined
   readonly trustedProxyHopCount?: number
+  readonly signups?: SignupsMode
+  readonly regions?: readonly PublicRegion[]
   readonly appBaseUrl?: string
   readonly secretEncryption?: ResolvedSecretEncryption
   readonly email: ResolvedEmail
@@ -242,6 +273,43 @@ interface ResolvedRateLimit {
   readonly api?: { readonly limit?: number; readonly windowSeconds?: number }
 }
 
+function describeRegionProblems(regions: readonly unknown[]): string[] {
+  const problems: string[] = []
+  const ids = new Set<string>()
+  const origins = new Set<string>()
+
+  for (const [index, region] of regions.entries()) {
+    const parsed = publicRegionSchema.safeParse(region)
+
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        problems.push(
+          describeValidationIssue({
+            path: ['regions', index, ...issue.path],
+            message: issue.message,
+          }),
+        )
+      }
+
+      continue
+    }
+
+    if (ids.has(parsed.data.id)) {
+      problems.push(`regions.${String(index)}.id: duplicate id '${parsed.data.id}'`)
+    }
+
+    ids.add(parsed.data.id)
+
+    if (origins.has(parsed.data.origin)) {
+      problems.push(`regions.${String(index)}.origin: duplicate origin '${parsed.data.origin}'`)
+    }
+
+    origins.add(parsed.data.origin)
+  }
+
+  return problems
+}
+
 function buildEmailConfig(resolved: ResolvedEmail | undefined): EmailConfig {
   // Missing `email.provider` or `email.from` is already recorded by the
   // walker; return a placeholder so `resolveKelpieConfig` reaches its throw

package/src/modules/agent-tasks/catalog.ts

@@ -128,7 +128,7 @@ Append a Note, update summary only when clearly supported, propose Plan items on
     targetTypes: ['company'],
     placement: 'primary',
     handbookSlugs: ['ideal-customer-profile', 'agent-faq'],
-    instructions: `Research this Company. Update description, stage, sizeBand, techStack, website/linkedin when evidenced, tags, and summary.
+    instructions: `Research this Company. Update description, stage, sizeBand, techStack, domain when evidenced, tags, and summary.
 Append a Note listing sources. Prefer notes over guesses for uncertain facts.`,
   }),
   task({
@@ -623,6 +623,28 @@ Ask before setting stage to passed.`,
     instructions: `The human will paste notes after this prompt. Append a Note; propose Plan items; extract Decisions.`,
   }),
 
+  // Event
+  task({
+    id: 'event.brief',
+    label: 'Event brief',
+    description: 'Agenda, who is registered, linked records, open Plans.',
+    targetTypes: ['event'],
+    placement: 'primary',
+    handbookSlugs: ['agent-faq'],
+    instructions: `Prepare a brief for this Event: agenda from details, who is registered, linked records, and open Plan items.
+Do not invent attendees. Prefer pinned notes and Decisions.`,
+  }),
+  task({
+    id: 'event.follow_up',
+    label: 'Follow up',
+    description: 'Draft follow-up from attended vs no-show Attendances.',
+    targetTypes: ['event'],
+    placement: 'primary',
+    handbookSlugs: ['voice-and-tone', 'agent-faq'],
+    instructions: `Draft follow-up from this Event's Attendances. Separate attended from no-show.
+Save drafts as Notes. Do not send email.`,
+  }),
+
   // Candidate
   task({
     id: 'candidate.score',
@@ -753,6 +775,16 @@ Suggest Draft outreach or Plan items. Do not spam everyone.`,
     handbookSlugs: ['how-we-sell', 'agent-faq'],
     instructions: `Propose a week of Plan items across open Deals, Opportunities, Raises, and Partnerships.
 Create Plan items only when clearly useful; otherwise list proposals for confirmation.`,
+  }),
+  task({
+    id: 'workspace.upcoming_events',
+    label: 'Upcoming events',
+    description: 'Scheduled Events in the next week and their attendee counts.',
+    targetTypes: ['workspace'],
+    placement: 'primary',
+    handbookSlugs: ['agent-faq'],
+    instructions: `List scheduled Events in the next week with attendee counts.
+Use GET /v1/dashboard upcoming_events. Suggest follow-up or brief tasks where useful.`,
   }),
   task({
     id: 'workspace.empty_field_sweep',

package/src/modules/agent-tasks/index.ts

@@ -38,6 +38,7 @@ export function createAgentTasksModule(
       'partnerships',
       'raises',
       'hiring',
+      'events',
       'plans',
       'decisions',
       'notes',

package/src/modules/agent-tasks/resolve.ts

@@ -9,6 +9,7 @@ import { companies } from '../companies/schema.ts'
 import { deals } from '../deals/schema.ts'
 import { decisions } from '../decisions/schema.ts'
 import { enquiries } from '../enquiries/schema.ts'
+import { attendances } from '../events/schema.ts'
 import { handbookPages } from '../handbook/schema.ts'
 import { candidates, roles } from '../hiring/schema.ts'
 import { notes } from '../notes/schema.ts'
@@ -443,6 +444,16 @@ async function collectRelated(
         ),
       }
 
+    case 'event':
+      return {
+        person_ids: await relatedFrom(
+          db,
+          attendances,
+          attendances.personId,
+          and(eq(attendances.workspaceId, workspaceId), eq(attendances.eventId, targetId)) as SQL,
+        ),
+      }
+
     case 'handbook':
     case 'workspace':
       return {}

package/src/modules/attachedRecords.ts

@@ -1,10 +1,16 @@
-import { PIPELINE_KINDS } from '@kelpie/schemas'
+import {
+  EVENT_ASSOCIATION_TARGET_TYPES,
+  FORM_ATTACH_TARGET_TYPES,
+  PIPELINE_KINDS,
+  PLAN_ITEM_TARGET_TYPES,
+} from '@kelpie/schemas'
 import type { PipelineKind } from '@kelpie/schemas'
 import { and, eq } from 'drizzle-orm'
 
 import type { Queryable } from '../runtime/transaction.ts'
 import * as activityRepository from './activities/repository.ts'
 import * as decisionRepository from './decisions/repository.ts'
+import { attendances, eventAssociations } from './events/schema.ts'
 import { formAttachTargets } from './forms/schema.ts'
 import { candidates } from './hiring/schema.ts'
 import * as listRepository from './lists/repository.ts'
@@ -20,19 +26,26 @@ import * as planRepository from './plans/repository.ts'
  * the target deletes these, in the same transaction, or the rows outlive the
  * record they described and reappear the day an id is reused.
  *
- * `plan_items` attach the same way but their check constraint allows only the
- * four pipeline types, so they are removed only for those targets. `person_links`
- * follows the same rule: it holds a person's involvement in a pipeline record
- * and its check constraint allows only the four pipeline types, so a deleted
- * deal/opportunity/raise/partnership sheds its people here. `form_attach_targets`
- * is the same shape: forms pinning submitters into a pre-existing pipeline
- * record shed the mapping when the target goes.
+ * `plan_items` attach the same way but their check constraint allows the
+ * pipeline types plus Event, so they are removed only for those targets.
+ * `person_links` stays pipeline-only. `form_attach_targets` follows the plan
+ * set (pipelines plus Event). `event_associations` is Event-only: deleting the
+ * other record strips rows that pointed at it.
  */
 
 /** Target types that can own attached records here. */
-export type AttachableTargetType = 'person' | 'company' | 'candidate' | PipelineKind
+export type AttachableTargetType =
+  | 'person'
+  | 'company'
+  | 'candidate'
+  | 'event'
+  | 'attendance'
+  | PipelineKind
 
-const PLAN_TARGET_TYPES: ReadonlySet<string> = new Set(PIPELINE_KINDS)
+const PLAN_TARGET_TYPES: ReadonlySet<string> = new Set(PLAN_ITEM_TARGET_TYPES)
+const LINK_TARGET_TYPES: ReadonlySet<string> = new Set(PIPELINE_KINDS)
+const FORM_ATTACH_TYPES: ReadonlySet<string> = new Set(FORM_ATTACH_TARGET_TYPES)
+const ASSOCIATION_TARGET_TYPES: ReadonlySet<string> = new Set(EVENT_ASSOCIATION_TARGET_TYPES)
 
 /**
  * @param db Must be the caller's transaction. Called on its own, this deletes the
@@ -53,13 +66,13 @@ export async function deleteRecordsAttachedTo(
   const plans = PLAN_TARGET_TYPES.has(targetType)
     ? await planRepository.deleteForTarget(db, workspaceId, targetType, targetId)
     : 0
-  const links = PLAN_TARGET_TYPES.has(targetType)
+  const links = LINK_TARGET_TYPES.has(targetType)
     ? await personLinks.deleteLinksForTarget(db, workspaceId, {
         targetType: targetType as PipelineKind,
         targetId,
       })
     : 0
-  const attachTargets = PLAN_TARGET_TYPES.has(targetType)
+  const attachTargets = FORM_ATTACH_TYPES.has(targetType)
     ? (
         await db
           .delete(formAttachTargets)
@@ -79,8 +92,36 @@ export async function deleteRecordsAttachedTo(
     targetType,
     targetId,
   )
+  const associations = ASSOCIATION_TARGET_TYPES.has(targetType)
+    ? await deleteEventAssociationsForTarget(db, workspaceId, targetType, targetId)
+    : 0
+
+  return notes + activities + decisions + plans + links + attachTargets + memberships + associations
+}
+
+/**
+ * Event↔record rows have no FK to the target, so the target's delete must strip
+ * them. Event delete itself cascades `event_id`. Role is not an attachable
+ * notes target, so its service calls this helper directly.
+ */
+export async function deleteEventAssociationsForTarget(
+  db: Queryable,
+  workspaceId: string,
+  targetType: string,
+  targetId: string,
+): Promise<number> {
+  const deleted = await db
+    .delete(eventAssociations)
+    .where(
+      and(
+        eq(eventAssociations.workspaceId, workspaceId),
+        eq(eventAssociations.targetType, targetType),
+        eq(eventAssociations.targetId, targetId),
+      ),
+    )
+    .returning({ id: eventAssociations.id })
 
-  return notes + activities + decisions + plans + links + attachTargets + memberships
+  return deleted.length
 }
 
 /**
@@ -117,3 +158,34 @@ export async function deleteRecordsAttachedToCandidaciesOf(
 
   return removed
 }
+
+/**
+ * The same cleanup for Attendances a person's (or Event's) delete takes with
+ * them. `attendances.person_id` / `event_id` cascade, so notes on those rows
+ * would otherwise outlive the Attendance.
+ */
+export async function deleteRecordsAttachedToAttendancesOf(
+  db: Queryable,
+  workspaceId: string,
+  filter: { readonly personId: string } | { readonly eventId: string },
+): Promise<number> {
+  const held = await db
+    .select({ id: attendances.id })
+    .from(attendances)
+    .where(
+      and(
+        eq(attendances.workspaceId, workspaceId),
+        'personId' in filter
+          ? eq(attendances.personId, filter.personId)
+          : eq(attendances.eventId, filter.eventId),
+      ),
+    )
+
+  let removed = 0
+
+  for (const attendance of held) {
+    removed += await deleteRecordsAttachedTo(db, workspaceId, 'attendance', attendance.id)
+  }
+
+  return removed
+}

package/src/modules/auth/index.ts

@@ -37,6 +37,7 @@ export function createAuthModule(migrationsDirectory: string): KelpieModule {
         createId: context.createId,
         now: context.now,
         appBaseUrl,
+        signupsEnabled: context.signupsEnabled ?? true,
       })
 
       // `Secure` everywhere except development. A test host reaches the API

package/src/modules/auth/repository.ts

@@ -1,8 +1,8 @@
-import { and, desc, eq, gt, isNull, ne } from 'drizzle-orm'
+import { and, asc, desc, eq, gt, isNull, ne } from 'drizzle-orm'
 
 import type { Database } from '../../lib/database.ts'
 import type { Transaction } from '../../runtime/transaction.ts'
-import { workspaceMembers } from '../workspace/schema.ts'
+import { workspaceMembers, workspaces } from '../workspace/schema.ts'
 import {
   emailVerificationTokens,
   passwordResetTokens,
@@ -64,11 +64,15 @@ export async function updateUserPassword(
 /**
  * Writes name and email. Not the password: that one has its own function because
  * it also ends sessions, and the two must not be reachable through one call.
+ *
+ * `emailVerifiedAt` rides along with an email change: the service resets it to
+ * null in the same call rather than a second write, so there is no window where
+ * the row holds a new address and the old address's verification.
  */
 export async function updateUserProfile(
   db: Queryable,
   userId: string,
-  changes: { readonly name?: string; readonly email?: string },
+  changes: { readonly name?: string; readonly email?: string; readonly emailVerifiedAt?: Date | null },
   now: Date,
 ): Promise<UserRecord | undefined> {
   const [updated] = await db
@@ -294,3 +298,30 @@ export async function findFirstMembership(
 
   return found
 }
+
+/** Every workspace this account belongs to, oldest membership first. */
+export interface AccountWorkspaceRecord {
+  readonly id: string
+  readonly name: string
+  readonly slug: string
+  readonly timezone: string
+  readonly role: string
+}
+
+export async function listWorkspacesForUser(
+  db: Queryable,
+  userId: string,
+): Promise<AccountWorkspaceRecord[]> {
+  return db
+    .select({
+      id: workspaces.id,
+      name: workspaces.name,
+      slug: workspaces.slug,
+      timezone: workspaces.timezone,
+      role: workspaceMembers.role,
+    })
+    .from(workspaceMembers)
+    .innerJoin(workspaces, eq(workspaces.id, workspaceMembers.workspaceId))
+    .where(eq(workspaceMembers.userId, userId))
+    .orderBy(asc(workspaceMembers.joinedAt))
+}

package/src/modules/auth/routes.ts

@@ -10,7 +10,7 @@ import type { SessionActor } from './actor.ts'
 import { resolveActorFrom } from './credentials.ts'
 import type { CredentialDependencies } from './credentials.ts'
 import type { PreferenceValues } from './preferences.ts'
-import type { AccountView, AuthService, IssuedSession, SessionView } from './service.ts'
+import type { AccountView, AuthService, IssuedSession, MeView, SessionView } from './service.ts'
 import { clearSessionCookie, describeClient, writeSessionCookie } from './session.ts'
 import type { SessionCookieOptions } from './session.ts'
 
@@ -44,6 +44,10 @@ const changePasswordBody = z.object({
   new_password: z.string().min(1),
 })
 
+const switchWorkspaceBodySchema = z.object({
+  workspace_id: z.string().min(1),
+})
+
 const verifyEmailConfirmBody = z.object({
   token: z.string().min(1),
 })
@@ -135,6 +139,32 @@ function preferencesResponse(preferences: PreferenceValues): Record<string, unkn
   }
 }
 
+function sessionMeResponse(session: MeView): Record<string, unknown> {
+  return {
+    user_id: session.userId,
+    session_id: session.sessionId,
+    workspace_id: session.workspaceId,
+    role: session.role,
+    email_verified: session.emailVerified,
+  }
+}
+
+function accountWorkspaceResponse(workspace: {
+  readonly id: string
+  readonly name: string
+  readonly slug: string
+  readonly timezone: string
+  readonly role: string
+}): Record<string, unknown> {
+  return {
+    id: workspace.id,
+    name: workspace.name,
+    slug: workspace.slug,
+    timezone: workspace.timezone,
+    role: workspace.role,
+  }
+}
+
 function sessionResponse(session: SessionView): Record<string, unknown> {
   return {
     id: session.id,
@@ -194,6 +224,19 @@ export function mountAuthRoutes(router: Hono, dependencies: AuthRoutesDependenci
     })
   })
 
+  router.get('/auth/workspaces', async (context) => {
+    const workspaces = await dependencies.service.listWorkspaces(await requireActor(context))
+
+    return context.json({ data: workspaces.map(accountWorkspaceResponse), next_cursor: null })
+  })
+
+  router.post('/auth/workspace', async (context) => {
+    const body = await readBody(context, switchWorkspaceBodySchema)
+    const session = await dependencies.service.switchWorkspace(await requireActor(context), body.workspace_id)
+
+    return context.json(sessionMeResponse(session))
+  })
+
   /**
    * `/account` rather than `/auth/account`: `/auth/*` is how a browser gets a
    * session, and this is the person that session belongs to. The auth module