@kelpie/schemas 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kelpie/schemas",
+  "version": "0.1.0",
+  "description": "Wire contract for the Kelpie API, as Zod schemas. Shared by the service, the UI, and any agent decoding /v1 responses.",
+  "keywords": [
+    "kelpie",
+    "crm",
+    "zod",
+    "schema",
+    "api"
+  ],
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velvet-tiger/kelpie.git",
+    "directory": "packages/schemas"
+  },
+  "homepage": "https://github.com/velvet-tiger/kelpie/tree/main/packages/schemas#readme",
+  "bugs": "https://github.com/velvet-tiger/kelpie/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "kelpie-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  }
+}

package/src/account.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod'
+
+import { THEME_PREFERENCES } from './values.ts'
+import type { ThemePreference } from './values.ts'
+import { definedFields, idSchema, timestampSchema } from './wire.ts'
+
+/**
+ * Wire shapes for `/v1/account`: the signed-in human, rather than the workspace
+ * they are looking at or the session they arrived on.
+ *
+ * An account is global. Changing a name here changes it in every workspace the
+ * person belongs to, which is why this is not part of the member resource.
+ */
+
+export interface Account {
+  readonly id: string
+  readonly email: string
+  readonly name: string
+}
+
+export const accountSchema: z.ZodType<Account, unknown> = z.object({
+  id: idSchema,
+  email: z.string(),
+  name: z.string(),
+})
+
+export interface UpdateAccountInput {
+  readonly name?: string
+  readonly email?: string
+  /** Required by the service whenever `email` is present. */
+  readonly currentPassword?: string
+}
+
+export function updateAccountBody(input: UpdateAccountInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    email: input.email,
+    current_password: input.currentPassword,
+  })
+}
+
+/**
+ * One of the caller's sessions, as the Security page lists them.
+ *
+ * Distinct from `Session` in `session.ts`, which is the single identity behind
+ * `GET /v1/auth/me`. This is a row in "where am I signed in", and `current`
+ * marks the one asking.
+ *
+ * `device` and `location` are nullable because the service records what the
+ * request actually carried. A `User-Agent` is usually present; nothing derives
+ * a location today, so it is always `null`.
+ */
+export interface AccountSession {
+  readonly id: string
+  readonly device: string | null
+  readonly location: string | null
+  readonly lastActiveAt: Date
+  readonly current: boolean
+}
+
+export const accountSessionSchema: z.ZodType<AccountSession, unknown> = z
+  .object({
+    id: idSchema,
+    device: z.string().nullable(),
+    location: z.string().nullable(),
+    last_active_at: timestampSchema,
+    current: z.boolean(),
+  })
+  .transform(
+    (wire): AccountSession => ({
+      id: wire.id,
+      device: wire.device,
+      location: wire.location,
+      lastActiveAt: wire.last_active_at,
+      current: wire.current,
+    }),
+  )
+
+/**
+ * The shortest password the service will hash.
+ *
+ * Part of the contract rather than a server detail: signup, reset, and the
+ * change-password form all have to state the rule before a caller submits, and
+ * a second copy in the browser is a copy that can drift below the real one.
+ */
+export const MINIMUM_PASSWORD_LENGTH = 12
+
+export interface ChangePasswordInput {
+  readonly currentPassword: string
+  readonly newPassword: string
+}
+
+export function changePasswordBody(input: ChangePasswordInput): Record<string, unknown> {
+  return { current_password: input.currentPassword, new_password: input.newPassword }
+}
+
+/**
+ * Per-account settings that follow the person between browsers.
+ *
+ * The three notification fields are stored choices, not switches over a running
+ * mailer: Kelpie sends no digest, mention, or product email yet. They record
+ * what to do when it does, and the Preferences page says so on screen rather
+ * than leaving a reader to infer a capability from a toggle.
+ */
+export interface AccountPreferences {
+  readonly timezone: string
+  readonly theme: ThemePreference
+  readonly emailDigest: boolean
+  readonly mentionEmails: boolean
+  readonly productUpdates: boolean
+}
+
+export const accountPreferencesSchema: z.ZodType<AccountPreferences, unknown> = z
+  .object({
+    timezone: z.string(),
+    theme: z.enum(THEME_PREFERENCES),
+    email_digest: z.boolean(),
+    mention_emails: z.boolean(),
+    product_updates: z.boolean(),
+  })
+  .transform(
+    (wire): AccountPreferences => ({
+      timezone: wire.timezone,
+      theme: wire.theme,
+      emailDigest: wire.email_digest,
+      mentionEmails: wire.mention_emails,
+      productUpdates: wire.product_updates,
+    }),
+  )
+
+export interface UpdateAccountPreferencesInput {
+  readonly timezone?: string
+  readonly theme?: ThemePreference
+  readonly emailDigest?: boolean
+  readonly mentionEmails?: boolean
+  readonly productUpdates?: boolean
+}
+
+export function updateAccountPreferencesBody(
+  input: UpdateAccountPreferencesInput,
+): Record<string, unknown> {
+  return definedFields({
+    timezone: input.timezone,
+    theme: input.theme,
+    email_digest: input.emailDigest,
+    mention_emails: input.mentionEmails,
+    product_updates: input.productUpdates,
+  })
+}

package/src/activity.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod'
+
+import { ACTIVITY_KINDS, RECORD_TARGET_TYPES } from './values.ts'
+import type { ActivityKind, RecordTargetType } from './values.ts'
+import { idSchema, timestampSchema } from './wire.ts'
+
+/**
+ * Wire shape for `/v1/activities`. Read-only, so there is no body builder here.
+ *
+ * No `updatedAt`: the table is append-only and carries no such column.
+ *
+ * `actorLabel` is the display name to use when `actorMemberId` is null, e.g.
+ * "Form", "Gmail", "API key". Exactly one of the two is set.
+ */
+
+export interface Activity {
+  readonly id: string
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly kind: ActivityKind
+  readonly actorMemberId: string | null
+  readonly actorLabel: string | null
+  readonly action: string
+  readonly detail: string | null
+  readonly createdAt: Date
+}
+
+export const activitySchema: z.ZodType<Activity, unknown> = z
+  .object({
+    id: idSchema,
+    target_type: z.enum(RECORD_TARGET_TYPES),
+    target_id: idSchema,
+    kind: z.enum(ACTIVITY_KINDS),
+    actor_member_id: idSchema.nullable(),
+    actor_label: z.string().nullable(),
+    action: z.string(),
+    detail: z.string().nullable(),
+    created_at: timestampSchema,
+  })
+  .transform(
+    (wire): Activity => ({
+      id: wire.id,
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+      kind: wire.kind,
+      actorMemberId: wire.actor_member_id,
+      actorLabel: wire.actor_label,
+      action: wire.action,
+      detail: wire.detail,
+      createdAt: wire.created_at,
+    }),
+  )

package/src/agentTask.ts

@@ -0,0 +1,254 @@
+import { z } from 'zod'
+
+import {
+  AGENT_RUN_STATUSES,
+  AGENT_TASK_PLACEMENTS,
+  AGENT_TASK_TARGET_TYPES,
+} from './values.ts'
+import type { AgentRunStatus, AgentTaskPlacement, AgentTaskTargetType } from './values.ts'
+import {
+  definedFields,
+  idSchema,
+  nullableTimestampSchema,
+  recordTimestamps,
+} from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Agent tasks (`agent-tasks.md`): prompt recipes over the workspace's own data.
+ *
+ * The task catalog ships in code, so a TaskDefinition has no timestamps and no
+ * body builder — it is read-only on the wire. A ResolvedTask is the one payload
+ * both triggers share: Copy puts `prompt` on the clipboard, Run POSTs the whole
+ * thing to a registered agent.
+ */
+
+/** A catalog entry. `id` is a stable string like `company.enrich`, not a ULID. */
+export interface AgentTaskDefinition {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly targetTypes: readonly AgentTaskTargetType[]
+  readonly placement: AgentTaskPlacement
+  readonly handbookSlugs: readonly string[]
+  readonly instructions: string
+  readonly writePolicy: string
+}
+
+export const agentTaskDefinitionSchema: z.ZodType<AgentTaskDefinition, unknown> = z
+  .object({
+    id: idSchema,
+    label: z.string(),
+    description: z.string(),
+    target_types: z.array(z.enum(AGENT_TASK_TARGET_TYPES)),
+    placement: z.enum(AGENT_TASK_PLACEMENTS),
+    handbook_slugs: z.array(z.string()),
+    instructions: z.string(),
+    write_policy: z.string(),
+  })
+  .transform(
+    (wire): AgentTaskDefinition => ({
+      id: wire.id,
+      label: wire.label,
+      description: wire.description,
+      targetTypes: wire.target_types,
+      placement: wire.placement,
+      handbookSlugs: wire.handbook_slugs,
+      instructions: wire.instructions,
+      writePolicy: wire.write_policy,
+    }),
+  )
+
+/**
+ * The structured snapshot resolve assembled. `related` keys are id-list names
+ * such as `person_ids`; which keys appear depends on the target type.
+ */
+export interface AgentTaskContextPack {
+  readonly targetLabel: string
+  readonly deepLink: string
+  readonly handbookSlugs: readonly string[]
+  readonly pinnedNoteIds: readonly string[]
+  readonly openPlanIds: readonly string[]
+  readonly openDecisionIds: readonly string[]
+  readonly related: Readonly<Record<string, readonly string[]>>
+}
+
+const contextPackSchema: z.ZodType<AgentTaskContextPack, unknown> = z
+  .object({
+    target_label: z.string(),
+    deep_link: z.string(),
+    handbook_slugs: z.array(z.string()),
+    pinned_note_ids: z.array(idSchema),
+    open_plan_ids: z.array(idSchema),
+    open_decision_ids: z.array(idSchema),
+    related: z.record(z.string(), z.array(idSchema)),
+  })
+  .transform(
+    (wire): AgentTaskContextPack => ({
+      targetLabel: wire.target_label,
+      deepLink: wire.deep_link,
+      handbookSlugs: wire.handbook_slugs,
+      pinnedNoteIds: wire.pinned_note_ids,
+      openPlanIds: wire.open_plan_ids,
+      openDecisionIds: wire.open_decision_ids,
+      related: wire.related,
+    }),
+  )
+
+/** What resolve answers, and what a run dispatches. Identical for copy and run. */
+export interface ResolvedAgentTask {
+  readonly taskId: string
+  readonly targetType: AgentTaskTargetType
+  readonly targetId: string
+  readonly prompt: string
+  readonly context: AgentTaskContextPack
+}
+
+export const resolvedAgentTaskSchema: z.ZodType<ResolvedAgentTask, unknown> = z
+  .object({
+    task_id: idSchema,
+    target_type: z.enum(AGENT_TASK_TARGET_TYPES),
+    target_id: idSchema,
+    prompt: z.string(),
+    context: contextPackSchema,
+  })
+  .transform(
+    (wire): ResolvedAgentTask => ({
+      taskId: wire.task_id,
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+      prompt: wire.prompt,
+      context: wire.context,
+    }),
+  )
+
+export interface ResolveAgentTaskInput {
+  readonly targetType: AgentTaskTargetType
+  readonly targetId: string
+}
+
+export function resolveAgentTaskBody(input: ResolveAgentTaskInput): Record<string, unknown> {
+  return {
+    target_type: input.targetType,
+    target_id: input.targetId,
+  }
+}
+
+export interface RunAgentTaskInput extends ResolveAgentTaskInput {
+  readonly agentId: string
+}
+
+export function runAgentTaskBody(input: RunAgentTaskInput): Record<string, unknown> {
+  return {
+    ...resolveAgentTaskBody(input),
+    agent_id: input.agentId,
+  }
+}
+
+/**
+ * A bring-your-own agent endpoint. The auth header is sealed server-side and
+ * never returned; `hasAuthHeader` is all a reader learns about it.
+ */
+export interface RegisteredAgent extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  readonly endpoint: string
+  readonly hasAuthHeader: boolean
+  readonly lastRunAt: Date | null
+}
+
+export const registeredAgentSchema: z.ZodType<RegisteredAgent, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    endpoint: z.string(),
+    has_auth_header: z.boolean(),
+    last_run_at: nullableTimestampSchema,
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): RegisteredAgent => ({
+      id: wire.id,
+      name: wire.name,
+      endpoint: wire.endpoint,
+      hasAuthHeader: wire.has_auth_header,
+      lastRunAt: wire.last_run_at,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreateRegisteredAgentInput {
+  readonly name: string
+  readonly endpoint: string
+  /** Sent as the `Authorization` header on every dispatch to this agent. */
+  readonly authHeader?: string
+}
+
+export function createRegisteredAgentBody(
+  input: CreateRegisteredAgentInput,
+): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    endpoint: input.endpoint,
+    auth_header: input.authHeader,
+  })
+}
+
+export interface RegisteredAgentInput {
+  readonly name?: string
+  readonly endpoint?: string
+  /** A string replaces the stored header; `null` clears it. */
+  readonly authHeader?: string | null
+}
+
+export function registeredAgentBody(input: RegisteredAgentInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    endpoint: input.endpoint,
+    auth_header: input.authHeader,
+  })
+}
+
+/**
+ * One dispatch of a ResolvedTask to a registered agent. `failureReason` is set
+ * only on `failed`, and says what the dispatch hit — a status, a timeout, a
+ * refused connection.
+ */
+export interface AgentRun extends RecordTimestamps {
+  readonly id: string
+  readonly agentId: string
+  readonly taskId: string
+  readonly targetType: AgentTaskTargetType
+  readonly targetId: string
+  readonly status: AgentRunStatus
+  readonly prompt: string
+  readonly failureReason: string | null
+}
+
+export const agentRunSchema: z.ZodType<AgentRun, unknown> = z
+  .object({
+    id: idSchema,
+    agent_id: idSchema,
+    task_id: idSchema,
+    target_type: z.enum(AGENT_TASK_TARGET_TYPES),
+    target_id: idSchema,
+    status: z.enum(AGENT_RUN_STATUSES),
+    prompt: z.string(),
+    failure_reason: z.string().nullable(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): AgentRun => ({
+      id: wire.id,
+      agentId: wire.agent_id,
+      taskId: wire.task_id,
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+      status: wire.status,
+      prompt: wire.prompt,
+      failureReason: wire.failure_reason,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )

package/src/candidate.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod'
+
+import { CANDIDATE_STATUSES, INTERVIEW_STAGES } from './values.ts'
+import type { CandidateStatus, InterviewStage } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/candidates`, the Person↔Role link.
+ *
+ * Hiring pipeline state sits here rather than on Person, so the same person can
+ * be interviewing for one role and in the nurture pile for another. Interview
+ * notes attach to the candidate, not to the person or the role.
+ *
+ * Neither end is updatable: moving a candidacy to a different role or person is
+ * a delete and a create, the rule Position already follows.
+ */
+
+export interface Candidate extends RecordTimestamps {
+  readonly id: string
+  readonly roleId: string
+  readonly personId: string
+  readonly status: CandidateStatus
+  /** Null unless the candidate is in process. The API keeps that true. */
+  readonly interviewStage: InterviewStage | null
+  readonly referrerPersonId: string | null
+}
+
+export const candidateSchema: z.ZodType<Candidate, unknown> = z
+  .object({
+    id: idSchema,
+    role_id: idSchema,
+    person_id: idSchema,
+    status: z.enum(CANDIDATE_STATUSES),
+    interview_stage: z.enum(INTERVIEW_STAGES).nullable(),
+    referrer_person_id: idSchema.nullable(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Candidate => ({
+      id: wire.id,
+      roleId: wire.role_id,
+      personId: wire.person_id,
+      status: wire.status,
+      interviewStage: wire.interview_stage,
+      referrerPersonId: wire.referrer_person_id,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreateCandidateInput {
+  readonly roleId: string
+  readonly personId: string
+  /** Absent means in process, where the mockup's "Add candidate" starts one. */
+  readonly status?: CandidateStatus
+  readonly interviewStage?: InterviewStage | null
+  readonly referrerPersonId?: string | null
+}
+
+export function createCandidateBody(input: CreateCandidateInput): Record<string, unknown> {
+  return definedFields({
+    role_id: input.roleId,
+    person_id: input.personId,
+    status: input.status,
+    interview_stage: input.interviewStage,
+    referrer_person_id: input.referrerPersonId,
+  })
+}
+
+export interface CandidateInput {
+  readonly status?: CandidateStatus
+  readonly interviewStage?: InterviewStage | null
+  readonly referrerPersonId?: string | null
+}
+
+export function candidateBody(input: CandidateInput): Record<string, unknown> {
+  return definedFields({
+    status: input.status,
+    interview_stage: input.interviewStage,
+    referrer_person_id: input.referrerPersonId,
+  })
+}

package/src/company.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod'
+
+import { ACCOUNT_TYPES, COMPANY_STAGES, ICP_FITS, SIZE_BANDS } from './values.ts'
+import type { AccountType, CompanyStage, IcpFit, SizeBand } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/** Wire and write shapes for `/v1/companies`. */
+
+export interface Company extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  readonly domain: string | null
+  readonly industry: string | null
+  readonly description: string
+  readonly stage: CompanyStage
+  readonly sizeBand: SizeBand
+  readonly hq: string | null
+  readonly website: string | null
+  readonly accountType: AccountType
+  readonly icpFit: IcpFit
+  readonly techStack: readonly string[]
+  readonly summary: string
+  readonly tags: readonly string[]
+}
+
+export const companySchema: z.ZodType<Company, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    domain: z.string().nullable(),
+    industry: z.string().nullable(),
+    description: z.string(),
+    stage: z.enum(COMPANY_STAGES),
+    size_band: z.enum(SIZE_BANDS),
+    hq: z.string().nullable(),
+    website: z.string().nullable(),
+    account_type: z.enum(ACCOUNT_TYPES),
+    icp_fit: z.enum(ICP_FITS),
+    tech_stack: z.array(z.string()),
+    summary: z.string(),
+    tags: z.array(z.string()),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Company => ({
+      id: wire.id,
+      name: wire.name,
+      domain: wire.domain,
+      industry: wire.industry,
+      description: wire.description,
+      stage: wire.stage,
+      sizeBand: wire.size_band,
+      hq: wire.hq,
+      website: wire.website,
+      accountType: wire.account_type,
+      icpFit: wire.icp_fit,
+      techStack: wire.tech_stack,
+      summary: wire.summary,
+      tags: wire.tags,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CompanyInput {
+  readonly name?: string
+  readonly domain?: string | null
+  readonly industry?: string | null
+  readonly description?: string
+  readonly stage?: CompanyStage
+  readonly sizeBand?: SizeBand
+  readonly hq?: string | null
+  readonly website?: string | null
+  readonly accountType?: AccountType
+  readonly icpFit?: IcpFit
+  readonly techStack?: readonly string[]
+  readonly summary?: string
+  readonly tags?: readonly string[]
+}
+
+export function companyBody(input: CompanyInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    domain: input.domain,
+    industry: input.industry,
+    description: input.description,
+    stage: input.stage,
+    size_band: input.sizeBand,
+    hq: input.hq,
+    website: input.website,
+    account_type: input.accountType,
+    icp_fit: input.icpFit,
+    tech_stack: input.techStack,
+    summary: input.summary,
+    tags: input.tags,
+  })
+}