@kelpie/schemas 0.1.0

package/src/invite.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+
+import { INVITABLE_ROLES, INVITE_STATUSES } from './values.ts'
+import type { InvitableRole } from './values.ts'
+import { idSchema, timestampSchema } from './wire.ts'
+
+/**
+ * Wire shapes for `/v1/workspaces/:id/invites`.
+ *
+ * `status` is derived from `expires_at` rather than stored, so a workspace that
+ * nobody has looked at still reports its stale invitations correctly. Nothing
+ * sweeps the table.
+ *
+ * Both write bodies carry `invite_url_template`: the service sends the email and
+ * has no idea what URL the caller's browser or agent is reachable at, so the
+ * caller supplies the address the token goes into.
+ */
+
+export interface Invite {
+  readonly id: string
+  readonly email: string
+  readonly role: InvitableRole
+  readonly status: (typeof INVITE_STATUSES)[number]
+  readonly expiresAt: Date
+  readonly createdAt: Date
+}
+
+export const inviteSchema: z.ZodType<Invite, unknown> = z
+  .object({
+    id: idSchema,
+    email: z.string(),
+    role: z.enum(INVITABLE_ROLES),
+    status: z.enum(INVITE_STATUSES),
+    expires_at: timestampSchema,
+    created_at: timestampSchema,
+  })
+  .transform(
+    (wire): Invite => ({
+      id: wire.id,
+      email: wire.email,
+      role: wire.role,
+      status: wire.status,
+      expiresAt: wire.expires_at,
+      createdAt: wire.created_at,
+    }),
+  )
+
+export interface CreateInviteInput {
+  readonly email: string
+  readonly role: InvitableRole
+  /** An absolute URL containing the literal `{token}`, which the email replaces. */
+  readonly inviteUrlTemplate: string
+}
+
+export function createInviteBody(input: CreateInviteInput): Record<string, unknown> {
+  return {
+    email: input.email,
+    role: input.role,
+    invite_url_template: input.inviteUrlTemplate,
+  }
+}
+
+export interface ResendInviteInput {
+  readonly inviteUrlTemplate: string
+}
+
+export function resendInviteBody(input: ResendInviteInput): Record<string, unknown> {
+  return { invite_url_template: input.inviteUrlTemplate }
+}

package/src/mcpTool.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+/**
+ * Wire shape for `GET /v1/mcp/tools`: what this deployment exposes over MCP.
+ *
+ * The same listing an MCP client gets from `tools/list`, read with ordinary
+ * credentials. A browser cannot call `/mcp` — it takes bearer keys only — so
+ * this is how the admin page shows what is actually registered rather than a
+ * hand-written copy that drifts.
+ */
+
+export interface McpTool {
+  /** `people_list`, `handbook_pages_get`, `import_commit`. Resource, then verb. */
+  readonly name: string
+  readonly description: string
+  /** JSON Schema for the tool's arguments, as the MCP client sees it. */
+  readonly inputSchema: Record<string, unknown>
+}
+
+export const mcpToolSchema = z
+  .strictObject({
+    name: z.string().min(1),
+    description: z.string(),
+    input_schema: z.record(z.string(), z.unknown()),
+  })
+  .transform(
+    (wire): McpTool => ({
+      name: wire.name,
+      description: wire.description,
+      inputSchema: wire.input_schema,
+    }),
+  )

package/src/member.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod'
+
+import { MEMBER_ROLES } from './values.ts'
+import type { MemberRole } from './values.ts'
+import { idSchema, timestampSchema } from './wire.ts'
+
+/**
+ * Wire shape for `GET /v1/workspaces/:id/members`.
+ *
+ * `id` is the membership, not the user. Notes and activities attribute to this
+ * id, so it is what a panel keys its name lookup on.
+ */
+
+export interface Member {
+  readonly id: string
+  readonly userId: string
+  readonly name: string
+  readonly email: string
+  readonly role: MemberRole
+  readonly joinedAt: Date
+}
+
+export const memberSchema: z.ZodType<Member, unknown> = z
+  .object({
+    id: idSchema,
+    user_id: idSchema,
+    name: z.string(),
+    email: z.string(),
+    role: z.enum(MEMBER_ROLES),
+    joined_at: timestampSchema,
+  })
+  .transform(
+    (wire): Member => ({
+      id: wire.id,
+      userId: wire.user_id,
+      name: wire.name,
+      email: wire.email,
+      role: wire.role,
+      joinedAt: wire.joined_at,
+    }),
+  )
+
+export interface UpdateMemberRoleInput {
+  /**
+   * `owner` transfers ownership: the workspace holds exactly one, so the caller
+   * giving it away becomes an admin in the same write.
+   */
+  readonly role: MemberRole
+}
+
+export function updateMemberRoleBody(input: UpdateMemberRoleInput): Record<string, unknown> {
+  return { role: input.role }
+}

package/src/moduleSetting.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+
+/**
+ * Wire shapes for `/v1/workspaces/:id/modules`.
+ *
+ * No `id` or timestamps: a setting is identified by `module_id`, and a reader
+ * only ever needs the current value, not its history.
+ */
+
+export interface ModuleSetting {
+  readonly moduleId: string
+  readonly enabled: boolean
+  /** True when a deploy-time config file holds this value, not the workspace's own choice. */
+  readonly locked: boolean
+}
+
+export const moduleSettingSchema: z.ZodType<ModuleSetting, unknown> = z
+  .object({
+    module_id: z.string(),
+    enabled: z.boolean(),
+    locked: z.boolean(),
+  })
+  .transform(
+    (wire): ModuleSetting => ({
+      moduleId: wire.module_id,
+      enabled: wire.enabled,
+      locked: wire.locked,
+    }),
+  )
+
+export interface UpdateModuleSettingInput {
+  readonly enabled: boolean
+}
+
+export function updateModuleSettingBody(input: UpdateModuleSettingInput): Record<string, unknown> {
+  return { enabled: input.enabled }
+}

package/src/note.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+
+import { RECORD_TARGET_TYPES } from './values.ts'
+import type { RecordTargetType } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/notes`.
+ *
+ * `authorId` is a workspace member id, not a user id. It is null when no member
+ * was behind the write, which today means a workspace API key. Resolving it to a
+ * name is the caller's job: `api.md` has no include-expansion, so a panel joins
+ * against the workspace member list it already holds.
+ */
+
+export interface Note extends RecordTimestamps {
+  readonly id: string
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly body: string
+  readonly authorId: string | null
+  readonly pinned: boolean
+}
+
+export const noteSchema: z.ZodType<Note, unknown> = z
+  .object({
+    id: idSchema,
+    target_type: z.enum(RECORD_TARGET_TYPES),
+    target_id: idSchema,
+    body: z.string(),
+    author_id: idSchema.nullable(),
+    pinned: z.boolean(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Note => ({
+      id: wire.id,
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+      body: wire.body,
+      authorId: wire.author_id,
+      pinned: wire.pinned,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreateNoteInput {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly body: string
+  readonly pinned?: boolean
+}
+
+export function createNoteBody(input: CreateNoteInput): Record<string, unknown> {
+  return definedFields({
+    target_type: input.targetType,
+    target_id: input.targetId,
+    body: input.body,
+    pinned: input.pinned,
+  })
+}
+
+/** The target never moves: re-filing a note under another record is a delete and a create. */
+export interface NoteInput {
+  readonly body?: string
+  readonly pinned?: boolean
+}
+
+export function noteBody(input: NoteInput): Record<string, unknown> {
+  return definedFields({ body: input.body, pinned: input.pinned })
+}

package/src/opportunity.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod'
+
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/** Wire and write shapes for `/v1/opportunities`. */
+
+export interface Opportunity extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  /** Free text ("Grant", "Accelerator", …), not an enum: the seed's own kinds vary by workspace. */
+  readonly kind: string
+  readonly stageId: string
+  /** Nullable: a speaking slot or a grant need not belong to a company on file. */
+  readonly companyId: string | null
+  readonly ownerId: string | null
+  /** `YYYY-MM-DD`, per `api.md` date-only fields. */
+  readonly expectedClose: string | null
+  readonly summary: string
+  readonly tags: readonly string[]
+}
+
+export const opportunitySchema: z.ZodType<Opportunity, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    kind: z.string(),
+    stage_id: idSchema,
+    company_id: idSchema.nullable(),
+    owner_id: idSchema.nullable(),
+    expected_close: z.string().nullable(),
+    summary: z.string(),
+    tags: z.array(z.string()),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Opportunity => ({
+      id: wire.id,
+      name: wire.name,
+      kind: wire.kind,
+      stageId: wire.stage_id,
+      companyId: wire.company_id,
+      ownerId: wire.owner_id,
+      expectedClose: wire.expected_close,
+      summary: wire.summary,
+      tags: wire.tags,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface OpportunityInput {
+  readonly name?: string
+  readonly kind?: string
+  readonly stageId?: string
+  readonly companyId?: string | null
+  readonly ownerId?: string | null
+  readonly expectedClose?: string | null
+  readonly summary?: string
+  readonly tags?: readonly string[]
+}
+
+export function opportunityBody(input: OpportunityInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    kind: input.kind,
+    stage_id: input.stageId,
+    company_id: input.companyId,
+    owner_id: input.ownerId,
+    expected_close: input.expectedClose,
+    summary: input.summary,
+    tags: input.tags,
+  })
+}

package/src/partnership.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod'
+
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/** Wire and write shapes for `/v1/partnerships`. */
+
+export interface Partnership extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  /** Required: a partnership is with an organisation, unlike an opportunity. */
+  readonly companyId: string
+  readonly stageId: string
+  /** Free text ("Integration", "Co-marketing", …), not an enum: the seed's own kinds vary by workspace. */
+  readonly kind: string
+  /** `YYYY-MM-DD`, per `api.md` date-only fields. */
+  readonly nextTouchpoint: string | null
+  readonly ownerId: string | null
+  readonly goals: string
+  readonly successLooksLike: string
+  readonly personIds: readonly string[]
+  readonly summary: string
+  readonly tags: readonly string[]
+}
+
+export const partnershipSchema: z.ZodType<Partnership, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    company_id: idSchema,
+    stage_id: idSchema,
+    kind: z.string(),
+    next_touchpoint: z.string().nullable(),
+    owner_id: idSchema.nullable(),
+    goals: z.string(),
+    success_looks_like: z.string(),
+    person_ids: z.array(idSchema),
+    summary: z.string(),
+    tags: z.array(z.string()),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Partnership => ({
+      id: wire.id,
+      name: wire.name,
+      companyId: wire.company_id,
+      stageId: wire.stage_id,
+      kind: wire.kind,
+      nextTouchpoint: wire.next_touchpoint,
+      ownerId: wire.owner_id,
+      goals: wire.goals,
+      successLooksLike: wire.success_looks_like,
+      personIds: wire.person_ids,
+      summary: wire.summary,
+      tags: wire.tags,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface PartnershipInput {
+  readonly name?: string
+  readonly companyId?: string
+  readonly stageId?: string
+  readonly kind?: string
+  readonly nextTouchpoint?: string | null
+  readonly ownerId?: string | null
+  readonly goals?: string
+  readonly successLooksLike?: string
+  readonly personIds?: readonly string[]
+  readonly summary?: string
+  readonly tags?: readonly string[]
+}
+
+export function partnershipBody(input: PartnershipInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    company_id: input.companyId,
+    stage_id: input.stageId,
+    kind: input.kind,
+    next_touchpoint: input.nextTouchpoint,
+    owner_id: input.ownerId,
+    goals: input.goals,
+    success_looks_like: input.successLooksLike,
+    person_ids: input.personIds,
+    summary: input.summary,
+    tags: input.tags,
+  })
+}

package/src/person.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod'
+
+import {
+  INFLUENCE_LEVELS,
+  PREFERRED_CHANNELS,
+  RELATIONSHIP_LEVELS,
+  SOCIAL_NETWORK_IDS,
+} from './values.ts'
+import type { Influence, PreferredChannel, Relationship, SocialNetworkId } from './values.ts'
+import { definedFields, idSchema, nullableTimestampSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/** Wire and write shapes for `/v1/people`. Job title is not here: it lives on Position. */
+
+export interface SocialProfile {
+  readonly network: SocialNetworkId
+  readonly url: string
+}
+
+export interface Person extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  readonly email: string | null
+  readonly phones: readonly string[]
+  readonly socialProfiles: readonly SocialProfile[]
+  readonly timezone: string | null
+  readonly location: string | null
+  readonly preferredChannel: PreferredChannel
+  readonly influence: Influence
+  readonly relationship: Relationship
+  readonly summary: string
+  readonly tags: readonly string[]
+  readonly lastContactedAt: Date | null
+}
+
+const socialProfileSchema = z.object({
+  network: z.enum(SOCIAL_NETWORK_IDS),
+  url: z.string(),
+})
+
+export const personSchema: z.ZodType<Person, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    email: z.string().nullable(),
+    phones: z.array(z.string()),
+    social_profiles: z.array(socialProfileSchema),
+    timezone: z.string().nullable(),
+    location: z.string().nullable(),
+    preferred_channel: z.enum(PREFERRED_CHANNELS),
+    influence: z.enum(INFLUENCE_LEVELS),
+    relationship: z.enum(RELATIONSHIP_LEVELS),
+    summary: z.string(),
+    tags: z.array(z.string()),
+    last_contacted_at: nullableTimestampSchema,
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Person => ({
+      id: wire.id,
+      name: wire.name,
+      email: wire.email,
+      phones: wire.phones,
+      socialProfiles: wire.social_profiles,
+      timezone: wire.timezone,
+      location: wire.location,
+      preferredChannel: wire.preferred_channel,
+      influence: wire.influence,
+      relationship: wire.relationship,
+      summary: wire.summary,
+      tags: wire.tags,
+      lastContactedAt: wire.last_contacted_at,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+/**
+ * A create or update body. Every field is optional because `POST` defaults all
+ * but `name` server-side and `PATCH` sends only what changed; `name` is required
+ * on create by the route, not by this type.
+ */
+export interface PersonInput {
+  readonly name?: string
+  readonly email?: string | null
+  readonly phones?: readonly string[]
+  readonly socialProfiles?: readonly SocialProfile[]
+  readonly timezone?: string | null
+  readonly location?: string | null
+  readonly preferredChannel?: PreferredChannel
+  readonly influence?: Influence
+  readonly relationship?: Relationship
+  readonly summary?: string
+  readonly tags?: readonly string[]
+  readonly lastContactedAt?: Date | null
+}
+
+export function personBody(input: PersonInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    email: input.email,
+    phones: input.phones,
+    social_profiles: input.socialProfiles,
+    timezone: input.timezone,
+    location: input.location,
+    preferred_channel: input.preferredChannel,
+    influence: input.influence,
+    relationship: input.relationship,
+    summary: input.summary,
+    tags: input.tags,
+    last_contacted_at:
+      input.lastContactedAt === undefined || input.lastContactedAt === null
+        ? input.lastContactedAt
+        : input.lastContactedAt.toISOString(),
+  })
+}

package/src/pipelineStage.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod'
+
+import { PIPELINE_KINDS } from './values.ts'
+import type { PipelineKind } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/** Wire and write shapes for `/v1/pipeline_stages`. */
+
+export interface PipelineStage extends RecordTimestamps {
+  readonly id: string
+  readonly kind: PipelineKind
+  /** The stable import-alias id. Renaming the label never moves it. */
+  readonly slug: string
+  readonly label: string
+  /** When false, hidden from the board's Open scope. */
+  readonly open: boolean
+  readonly sortOrder: number
+}
+
+export const pipelineStageSchema: z.ZodType<PipelineStage, unknown> = z
+  .object({
+    id: idSchema,
+    kind: z.enum(PIPELINE_KINDS),
+    slug: z.string(),
+    label: z.string(),
+    open: z.boolean(),
+    sort_order: z.number().int(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): PipelineStage => ({
+      id: wire.id,
+      kind: wire.kind,
+      slug: wire.slug,
+      label: wire.label,
+      open: wire.open,
+      sortOrder: wire.sort_order,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreatePipelineStageInput {
+  readonly kind: PipelineKind
+  readonly label: string
+  readonly open?: boolean
+}
+
+export function createPipelineStageBody(input: CreatePipelineStageInput): Record<string, unknown> {
+  return definedFields({
+    kind: input.kind,
+    label: input.label,
+    open: input.open,
+  })
+}
+
+export interface UpdatePipelineStageInput {
+  readonly label?: string
+  readonly open?: boolean
+  /** The stage's new 0-based position on its board. */
+  readonly sortOrder?: number
+}
+
+export function updatePipelineStageBody(input: UpdatePipelineStageInput): Record<string, unknown> {
+  return definedFields({
+    label: input.label,
+    open: input.open,
+    sort_order: input.sortOrder,
+  })
+}