@kelpie/schemas 0.1.0

package/src/planItem.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod'
+
+import { PIPELINE_KINDS, PLAN_ITEM_STATUSES } from './values.ts'
+import type { PipelineKind, PlanItemStatus } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/plan_items`.
+ *
+ * A plan item is a dated action on one of the four pipelines. It replaces any
+ * next-step text field (`brief.md`): the date, the owner, and the status are
+ * columns, so "what is overdue" is a query rather than a read of prose.
+ *
+ * `ownerId` is a workspace member id and is null when nobody has taken it. The
+ * status is never null: the table defaults it to `todo`, so a plan item always
+ * says where it stands.
+ */
+
+export interface PlanItem extends RecordTimestamps {
+  readonly id: string
+  readonly targetType: PipelineKind
+  readonly targetId: string
+  /** `YYYY-MM-DD`, per `api.md` date-only fields. */
+  readonly date: string
+  readonly title: string
+  readonly ownerId: string | null
+  readonly status: PlanItemStatus
+}
+
+export const planItemSchema: z.ZodType<PlanItem, unknown> = z
+  .object({
+    id: idSchema,
+    target_type: z.enum(PIPELINE_KINDS),
+    target_id: idSchema,
+    date: z.string(),
+    title: z.string(),
+    owner_id: idSchema.nullable(),
+    status: z.enum(PLAN_ITEM_STATUSES),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): PlanItem => ({
+      id: wire.id,
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+      date: wire.date,
+      title: wire.title,
+      ownerId: wire.owner_id,
+      status: wire.status,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreatePlanItemInput {
+  readonly targetType: PipelineKind
+  readonly targetId: string
+  readonly date: string
+  readonly title: string
+  readonly ownerId?: string | null
+  readonly status?: PlanItemStatus
+}
+
+export function createPlanItemBody(input: CreatePlanItemInput): Record<string, unknown> {
+  return definedFields({
+    target_type: input.targetType,
+    target_id: input.targetId,
+    date: input.date,
+    title: input.title,
+    owner_id: input.ownerId,
+    status: input.status,
+  })
+}
+
+/** The target never moves: re-filing a plan item under another record is a delete and a create. */
+export interface PlanItemInput {
+  readonly date?: string
+  readonly title?: string
+  readonly ownerId?: string | null
+  readonly status?: PlanItemStatus
+}
+
+export function planItemBody(input: PlanItemInput): Record<string, unknown> {
+  return definedFields({
+    date: input.date,
+    title: input.title,
+    owner_id: input.ownerId,
+    status: input.status,
+  })
+}

package/src/position.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod'
+
+import { idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/positions`, the Person↔Company link that holds
+ * the job title. Moving a link to a different person or company is a delete and
+ * a create, which is why only the title is updatable.
+ */
+
+export interface Position extends RecordTimestamps {
+  readonly id: string
+  readonly personId: string
+  readonly companyId: string
+  readonly title: string
+}
+
+export const positionSchema: z.ZodType<Position, unknown> = z
+  .object({
+    id: idSchema,
+    person_id: idSchema,
+    company_id: idSchema,
+    title: z.string(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Position => ({
+      id: wire.id,
+      personId: wire.person_id,
+      companyId: wire.company_id,
+      title: wire.title,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreatePositionInput {
+  readonly personId: string
+  readonly companyId: string
+  readonly title: string
+}
+
+export function createPositionBody(input: CreatePositionInput): Record<string, unknown> {
+  return { person_id: input.personId, company_id: input.companyId, title: input.title }
+}
+
+export function updatePositionBody(title: string): Record<string, unknown> {
+  return { title }
+}

package/src/raise.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/** Wire and write shapes for `/v1/raises`. */
+
+export interface Raise extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  /** Required: the firm. The ongoing investor relationship stays a Partnership. */
+  readonly companyId: string
+  readonly stageId: string
+  readonly checkSizeCents: number | null
+  readonly currency: string | null
+  readonly thesisFit: string
+  /** Why they said no. Meaningful whenever set, not only in the passed stage. */
+  readonly passReason: string | null
+  readonly ownerId: string | null
+  /** `YYYY-MM-DD`, per `api.md` date-only fields. */
+  readonly expectedClose: string | null
+  readonly personIds: readonly string[]
+  readonly summary: string
+  readonly tags: readonly string[]
+}
+
+export const raiseSchema: z.ZodType<Raise, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    company_id: idSchema,
+    stage_id: idSchema,
+    check_size_cents: z.number().int().nullable(),
+    currency: z.string().nullable(),
+    thesis_fit: z.string(),
+    pass_reason: z.string().nullable(),
+    owner_id: idSchema.nullable(),
+    expected_close: z.string().nullable(),
+    person_ids: z.array(idSchema),
+    summary: z.string(),
+    tags: z.array(z.string()),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Raise => ({
+      id: wire.id,
+      name: wire.name,
+      companyId: wire.company_id,
+      stageId: wire.stage_id,
+      checkSizeCents: wire.check_size_cents,
+      currency: wire.currency,
+      thesisFit: wire.thesis_fit,
+      passReason: wire.pass_reason,
+      ownerId: wire.owner_id,
+      expectedClose: wire.expected_close,
+      personIds: wire.person_ids,
+      summary: wire.summary,
+      tags: wire.tags,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface RaiseInput {
+  readonly name?: string
+  readonly companyId?: string
+  readonly stageId?: string
+  readonly checkSizeCents?: number | null
+  readonly currency?: string | null
+  readonly thesisFit?: string
+  readonly passReason?: string | null
+  readonly ownerId?: string | null
+  readonly expectedClose?: string | null
+  readonly personIds?: readonly string[]
+  readonly summary?: string
+  readonly tags?: readonly string[]
+}
+
+export function raiseBody(input: RaiseInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    company_id: input.companyId,
+    stage_id: input.stageId,
+    check_size_cents: input.checkSizeCents,
+    currency: input.currency,
+    thesis_fit: input.thesisFit,
+    pass_reason: input.passReason,
+    owner_id: input.ownerId,
+    expected_close: input.expectedClose,
+    person_ids: input.personIds,
+    summary: input.summary,
+    tags: input.tags,
+  })
+}

package/src/role.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+
+import { ROLE_STATUSES } from './values.ts'
+import type { RoleStatus } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/roles`, an opening the workspace is hiring for.
+ *
+ * A Role holds no people. Candidates attach through `/v1/candidates`, which is
+ * the Person↔Role link and the only place hiring pipeline state lives.
+ */
+
+export interface Role extends RecordTimestamps {
+  readonly id: string
+  readonly title: string
+  readonly status: RoleStatus
+}
+
+export const roleSchema: z.ZodType<Role, unknown> = z
+  .object({
+    id: idSchema,
+    title: z.string(),
+    status: z.enum(ROLE_STATUSES),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Role => ({
+      id: wire.id,
+      title: wire.title,
+      status: wire.status,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface RoleInput {
+  readonly title?: string
+  readonly status?: RoleStatus
+}
+
+export function roleBody(input: RoleInput): Record<string, unknown> {
+  return definedFields({ title: input.title, status: input.status })
+}

package/src/search.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+
+import { SEARCH_COLLECTIONS } from './values.ts'
+import type { SearchCollection } from './values.ts'
+import { idSchema } from './wire.ts'
+
+/**
+ * Wire shape for `GET /v1/search`. Read-only, so there is no body builder.
+ *
+ * One object rather than a list envelope, and no cursor. Nine collections are
+ * ranked separately, because a `ts_rank` over a handbook page and one over a
+ * three-word Role title are not comparable numbers, and "which Deal" and "which
+ * handbook page" are different questions anyway.
+ *
+ * Every group carries `total`, the count of every match, beside `items`, which
+ * holds however many the request's `?limit=` allowed.
+ */
+
+export interface SearchResult {
+  readonly id: string
+  readonly title: string
+  /**
+   * The record's one line of context, already resolved. What it holds depends on
+   * the collection: an email for a Person, a domain for a Company, the stage
+   * label for a Deal or Raise, the kind for an Opportunity or Partnership, the
+   * status for a Role, the slug for a handbook page, and the date decided for a
+   * Decision as `YYYY-MM-DD`.
+   */
+  readonly subtitle: string | null
+  /** A fragment of the record's prose centred on the match. Empty when it has none. */
+  readonly snippet: string
+}
+
+export interface SearchResultGroup {
+  readonly collection: SearchCollection
+  readonly total: number
+  readonly items: readonly SearchResult[]
+}
+
+export interface SearchResults {
+  readonly query: string
+  readonly limit: number
+  /** Across every group, which is what a "12 results" heading is built from. */
+  readonly total: number
+  readonly groups: readonly SearchResultGroup[]
+}
+
+const resultSchema: z.ZodType<SearchResult, unknown> = z
+  .object({
+    id: idSchema,
+    title: z.string(),
+    subtitle: z.string().nullable(),
+    snippet: z.string(),
+  })
+  .transform((wire) => ({
+    id: wire.id,
+    title: wire.title,
+    subtitle: wire.subtitle,
+    snippet: wire.snippet,
+  }))
+
+const groupSchema: z.ZodType<SearchResultGroup, unknown> = z
+  .object({
+    type: z.enum(SEARCH_COLLECTIONS),
+    total: z.number().int(),
+    items: z.array(resultSchema),
+  })
+  .transform((wire) => ({
+    collection: wire.type,
+    total: wire.total,
+    items: wire.items,
+  }))
+
+export const searchResultsSchema: z.ZodType<SearchResults, unknown> = z
+  .object({
+    query: z.string(),
+    limit: z.number().int(),
+    total: z.number().int(),
+    groups: z.array(groupSchema),
+  })
+  .transform((wire) => ({
+    query: wire.query,
+    limit: wire.limit,
+    total: wire.total,
+    groups: wire.groups,
+  }))

package/src/session.ts

@@ -0,0 +1,177 @@
+import { z } from 'zod'
+
+import type { Account } from './account.ts'
+import { MEMBER_ROLES } from './values.ts'
+import type { MemberRole } from './values.ts'
+import { definedFields, idSchema } from './wire.ts'
+
+/**
+ * Wire shapes for `/v1/auth/*` and `/v1/workspaces`: how a browser gets a
+ * session, and which workspace that session is in.
+ *
+ * `workspaceId` is nullable because signup creates an account and nothing else.
+ * Every CRM endpoint answers `403` until a workspace exists, so the shell has to
+ * be able to tell "signed out" from "signed in, no workspace yet".
+ *
+ * The password-reset pair belongs here rather than in `account.ts` for the same
+ * reason sign-in does: a caller running them has no account context yet. What
+ * `account.ts` holds is the signed-in person.
+ */
+
+export interface Session {
+  readonly userId: string
+  readonly sessionId: string
+  readonly workspaceId: string | null
+  readonly role: MemberRole | null
+}
+
+export const sessionSchema: z.ZodType<Session, unknown> = z
+  .object({
+    user_id: idSchema,
+    session_id: idSchema,
+    workspace_id: idSchema.nullable(),
+    role: z.enum(MEMBER_ROLES).nullable(),
+  })
+  .transform(
+    (wire): Session => ({
+      userId: wire.user_id,
+      sessionId: wire.session_id,
+      workspaceId: wire.workspace_id,
+      role: wire.role,
+    }),
+  )
+
+/** What `POST /v1/auth/login` and `/v1/auth/signup` answer with. */
+export interface SignedInAccount {
+  readonly account: Account
+  readonly activeWorkspaceId: string | null
+}
+
+export const signedInAccountSchema: z.ZodType<SignedInAccount, unknown> = z
+  .object({
+    account: z.object({ id: idSchema, email: z.string(), name: z.string() }),
+    active_workspace_id: idSchema.nullable(),
+  })
+  .transform(
+    (wire): SignedInAccount => ({
+      account: wire.account,
+      activeWorkspaceId: wire.active_workspace_id,
+    }),
+  )
+
+export interface Workspace {
+  readonly id: string
+  readonly name: string
+  readonly slug: string
+  readonly timezone: string
+  readonly tagline: string | null
+  readonly oneLiner: string | null
+}
+
+export const workspaceSchema: z.ZodType<Workspace, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    slug: z.string(),
+    timezone: z.string(),
+    tagline: z.string().nullable(),
+    one_liner: z.string().nullable(),
+  })
+  .transform(
+    (wire): Workspace => ({
+      id: wire.id,
+      name: wire.name,
+      slug: wire.slug,
+      timezone: wire.timezone,
+      tagline: wire.tagline,
+      oneLiner: wire.one_liner,
+    }),
+  )
+
+export interface CreateWorkspaceInput {
+  readonly name: string
+  readonly slug: string
+  readonly timezone: string
+}
+
+export function createWorkspaceBody(input: CreateWorkspaceInput): Record<string, unknown> {
+  return { name: input.name, slug: input.slug, timezone: input.timezone }
+}
+
+/**
+ * Settings a workspace admin can change.
+ *
+ * `tagline` and `oneLiner` are the two strings an agent reads to say who this
+ * company is, so `null` clears them and `undefined` leaves them alone, per
+ * `api.md`. `definedFields` is what keeps those two apart on the wire.
+ */
+export interface UpdateWorkspaceInput {
+  readonly name?: string
+  readonly slug?: string
+  readonly timezone?: string
+  readonly tagline?: string | null
+  readonly oneLiner?: string | null
+}
+
+export function updateWorkspaceBody(input: UpdateWorkspaceInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    slug: input.slug,
+    timezone: input.timezone,
+    tagline: input.tagline,
+    one_liner: input.oneLiner,
+  })
+}
+
+export interface LogInInput {
+  readonly email: string
+  readonly password: string
+}
+
+export function logInBody(input: LogInInput): Record<string, unknown> {
+  return { email: input.email, password: input.password }
+}
+
+/**
+ * Creating an account. It answers the same shape sign-in does, with
+ * `activeWorkspaceId` null: signup makes the user and stops there.
+ */
+export interface SignUpInput {
+  readonly name: string
+  readonly email: string
+  readonly password: string
+}
+
+export function signUpBody(input: SignUpInput): Record<string, unknown> {
+  return { name: input.name, email: input.email, password: input.password }
+}
+
+/**
+ * Asking for a reset link.
+ *
+ * `resetUrlTemplate` carries the literal `{token}`, which the email replaces.
+ * The caller supplies it for the same reason an invitation does: the service
+ * sends the mail and has no idea what address the browser reached it at.
+ */
+export interface RequestPasswordResetInput {
+  readonly email: string
+  readonly resetUrlTemplate: string
+}
+
+export function requestPasswordResetBody(
+  input: RequestPasswordResetInput,
+): Record<string, unknown> {
+  return { email: input.email, reset_url_template: input.resetUrlTemplate }
+}
+
+/** Spending the token from that email. Answers `204`; it does not sign anyone in. */
+export interface ConfirmPasswordResetInput {
+  readonly token: string
+  readonly password: string
+}
+
+export function confirmPasswordResetBody(
+  input: ConfirmPasswordResetInput,
+): Record<string, unknown> {
+  return { token: input.token, password: input.password }
+}