@kelpie/schemas 0.7.0 → 0.9.0

package/src/personConsent.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod'
+
+import { CONSENT_PURPOSE_STATUSES } from './values.ts'
+import type { ConsentPurposeStatus, ConsentStatus } from './values.ts'
+import { definedFields, nullableTimestampSchema } from './wire.ts'
+
+/**
+ * The effective consent status for a (person, purpose) pair.
+ *
+ * `inherited: true` means the person has no explicit `person_consents` row for
+ * the purpose and the reader is looking at the purpose's `default_status`. In
+ * that case `source` and `notedAt` are null. `inherited: false` means the row
+ * exists and carries its own `granted | withdrawn`, `source`, and `notedAt`.
+ */
+export interface PersonConsent {
+  /** The purpose's slug — the identity that survives a rename of its label. */
+  readonly purposeSlug: string
+  readonly purposeLabel: string
+  readonly status: ConsentPurposeStatus
+  readonly source: string | null
+  readonly notedAt: Date | null
+  readonly inherited: boolean
+}
+
+export const personConsentSchema: z.ZodType<PersonConsent, unknown> = z
+  .object({
+    purpose_slug: z.string(),
+    purpose_label: z.string(),
+    status: z.enum(CONSENT_PURPOSE_STATUSES),
+    source: z.string().nullable(),
+    noted_at: nullableTimestampSchema,
+    inherited: z.boolean(),
+  })
+  .transform(
+    (wire): PersonConsent => ({
+      purposeSlug: wire.purpose_slug,
+      purposeLabel: wire.purpose_label,
+      status: wire.status,
+      source: wire.source,
+      notedAt: wire.noted_at,
+      inherited: wire.inherited,
+    }),
+  )
+
+/**
+ * What a manual override writes for one (person, purpose) pair. A `status` of
+ * `granted` or `withdrawn` upserts the row (`source: manual`); a `null` status
+ * clears the row and falls the pair back to the purpose's default.
+ */
+export interface PersonConsentInput {
+  readonly purposeSlug: string
+  readonly status: ConsentStatus | null
+}
+
+export function personConsentWriteBody(input: PersonConsentInput): Record<string, unknown> {
+  return definedFields({
+    purpose_slug: input.purposeSlug,
+    status: input.status,
+  })
+}

package/src/raise.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { customFieldValuesBody, customFieldValuesSchema } from './customField.ts'
+import type { CustomFieldValue, CustomFieldValues } from './customField.ts'
 import { definedFields, idSchema, recordTimestamps } from './wire.ts'
 import type { RecordTimestamps } from './wire.ts'
 
@@ -22,6 +24,8 @@ export interface Raise extends RecordTimestamps {
   readonly personIds: readonly string[]
   readonly summary: string
   readonly tags: readonly string[]
+  /** Workspace-defined fields, keyed by definition key. Always present (default `{}`). */
+  readonly customFields: CustomFieldValues
 }
 
 export const raiseSchema: z.ZodType<Raise, unknown> = z
@@ -39,6 +43,7 @@ export const raiseSchema: z.ZodType<Raise, unknown> = z
     person_ids: z.array(idSchema),
     summary: z.string(),
     tags: z.array(z.string()),
+    custom_fields: customFieldValuesSchema,
     ...recordTimestamps,
   })
   .transform(
@@ -56,6 +61,7 @@ export const raiseSchema: z.ZodType<Raise, unknown> = z
       personIds: wire.person_ids,
       summary: wire.summary,
       tags: wire.tags,
+      customFields: wire.custom_fields,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,
     }),
@@ -74,6 +80,11 @@ export interface RaiseInput {
   readonly personIds?: readonly string[]
   readonly summary?: string
   readonly tags?: readonly string[]
+  /**
+   * Partial merge patch: sent keys change, `null` clears a key, absent keys are
+   * left alone. Unknown keys are rejected at `422`.
+   */
+  readonly customFields?: Readonly<Record<string, CustomFieldValue | null>>
 }
 
 export function raiseBody(input: RaiseInput): Record<string, unknown> {
@@ -90,5 +101,7 @@ export function raiseBody(input: RaiseInput): Record<string, unknown> {
     person_ids: input.personIds,
     summary: input.summary,
     tags: input.tags,
+    custom_fields:
+      input.customFields === undefined ? undefined : customFieldValuesBody(input.customFields),
   })
 }

package/src/sampleData.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod'
+
+/**
+ * Wire shape for `POST /v1/workspaces/:id/sample-data`.
+ *
+ * The endpoint takes no body. The response is a count per object type, so a
+ * caller can tell the reader what the button just did without a second query.
+ */
+
+export interface SampleDataCounts {
+  readonly companies: number
+  readonly people: number
+  readonly positions: number
+  readonly deals: number
+  readonly planItems: number
+  readonly notes: number
+  readonly opportunities: number
+  readonly raises: number
+  readonly partnerships: number
+  readonly enquiries: number
+  readonly roles: number
+  readonly candidates: number
+}
+
+export const sampleDataCountsSchema: z.ZodType<SampleDataCounts, unknown> = z
+  .object({
+    companies: z.number().int().nonnegative(),
+    people: z.number().int().nonnegative(),
+    positions: z.number().int().nonnegative(),
+    deals: z.number().int().nonnegative(),
+    plan_items: z.number().int().nonnegative(),
+    notes: z.number().int().nonnegative(),
+    opportunities: z.number().int().nonnegative(),
+    raises: z.number().int().nonnegative(),
+    partnerships: z.number().int().nonnegative(),
+    enquiries: z.number().int().nonnegative(),
+    roles: z.number().int().nonnegative(),
+    candidates: z.number().int().nonnegative(),
+  })
+  .transform(
+    (wire): SampleDataCounts => ({
+      companies: wire.companies,
+      people: wire.people,
+      positions: wire.positions,
+      deals: wire.deals,
+      planItems: wire.plan_items,
+      notes: wire.notes,
+      opportunities: wire.opportunities,
+      raises: wire.raises,
+      partnerships: wire.partnerships,
+      enquiries: wire.enquiries,
+      roles: wire.roles,
+      candidates: wire.candidates,
+    }),
+  )

package/src/values.ts

@@ -90,6 +90,7 @@ export const EXTENSIBLE_RECORD_TYPES = [
   'opportunity',
   'partnership',
   'raise',
+  'enquiry',
   'role',
   'candidate',
 ] as const
@@ -110,11 +111,24 @@ export const RECORD_TARGET_TYPES = [
   'opportunity',
   'partnership',
   'raise',
+  'enquiry',
   'candidate',
 ] as const
 
 export type RecordTargetType = (typeof RECORD_TARGET_TYPES)[number]
 
+/** Human labels for `RECORD_TARGET_TYPES`. Used by any picker that names a type. */
+export const RECORD_TARGET_TYPE_LABELS: Readonly<Record<RecordTargetType, string>> = {
+  person: 'Person',
+  company: 'Company',
+  deal: 'Deal',
+  opportunity: 'Opportunity',
+  partnership: 'Partnership',
+  raise: 'Raise',
+  enquiry: 'Enquiry',
+  candidate: 'Candidate',
+}
+
 /**
  * What `GET /v1/search` looks through, and the order its groups come back in.
  *
@@ -131,6 +145,7 @@ export const SEARCH_COLLECTIONS = [
   'person',
   'role',
   'company',
+  'enquiry',
   'deal',
   'opportunity',
   'raise',
@@ -196,16 +211,23 @@ export const INTERVIEW_STAGE_LABELS: Readonly<Record<InterviewStage, string>> =
 export const FIRST_INTERVIEW_STAGE: InterviewStage = INTERVIEW_STAGES[0]
 
 /**
- * The four pipelines whose board columns live in `pipeline_stages`. A Deal moves
+ * The five pipelines whose board columns live in `pipeline_stages`. A Deal moves
  * through `deal` stages and so on; the kinds are fixed even though the stages
  * within each are workspace-configurable.
  */
-export const PIPELINE_KINDS = ['deal', 'opportunity', 'raise', 'partnership'] as const
+export const PIPELINE_KINDS = [
+  'enquiry',
+  'deal',
+  'opportunity',
+  'raise',
+  'partnership',
+] as const
 
 export type PipelineKind = (typeof PIPELINE_KINDS)[number]
 
 /** Display names for `PIPELINE_KINDS`. "Fundraising" is what the nav calls a Raise. */
 export const PIPELINE_KIND_LABELS: Readonly<Record<PipelineKind, string>> = {
+  enquiry: 'Enquiry',
   deal: 'Deal',
   opportunity: 'Opportunity',
   raise: 'Fundraising',
@@ -302,24 +324,46 @@ export type FormStatus = (typeof FORM_STATUSES)[number]
  * uploads, multi-page forms and branching out of scope, and every type here is
  * one `<input>`, `<textarea>` or `<select>`.
  */
-export const FORM_FIELD_TYPES = ['text', 'email', 'textarea', 'select'] as const
+export const FORM_FIELD_TYPES = ['text', 'email', 'textarea', 'select', 'consent', 'notice'] as const
 
 export type FormFieldType = (typeof FORM_FIELD_TYPES)[number]
 
+/**
+ * The field types whose answer is stored as a boolean, not a string. A
+ * `consent` field renders as a checkbox whose label carries the consent
+ * statement; the answer records whether the visitor ticked it.
+ */
+export const FORM_BOOLEAN_FIELD_TYPES = ['consent'] as const
+
+export type FormBooleanFieldType = (typeof FORM_BOOLEAN_FIELD_TYPES)[number]
+
 /**
  * Where a field's answer lands on submit.
  *
  * `position.title` rather than a person field, because a job title belongs to the
  * Person↔Company link and nowhere else. `submission` stores the answer without
  * writing any CRM record, which is what a free-text "How can we help?" wants.
+ *
+ * A form asks for a name the way its author wants it asked: one `person.name`
+ * box, or the `person.first_name` / `person.last_name` pair most sign-up forms
+ * use. Mapping the pair and no `person.name` composes the display name from the
+ * two, so neither arrangement makes a nameless person. `salutation` and `suffix`
+ * are storable on a Person but are not offered here — a public form asking for
+ * them is rare enough that the choice is not worth the room in this list.
  */
 export const FORM_FIELD_MAP_TARGETS = [
   'person.name',
+  'person.first_name',
+  'person.last_name',
   'person.email',
+  'person.consent',
   'company.name',
   'company.domain',
   'position.title',
+  'enquiry.name',
   'deal.name',
+  'opportunity.name',
+  'partnership.name',
   'submission',
 ] as const
 
@@ -327,14 +371,23 @@ export type FormFieldMapTarget = (typeof FORM_FIELD_MAP_TARGETS)[number]
 
 export const FORM_FIELD_MAP_TARGET_LABELS: Readonly<Record<FormFieldMapTarget, string>> = {
   'person.name': 'Person · name',
+  'person.first_name': 'Person · first name',
+  'person.last_name': 'Person · last name',
   'person.email': 'Person · email',
+  'person.consent': 'Person · consent',
   'company.name': 'Company · name',
   'company.domain': 'Company · domain',
   'position.title': 'Position · title',
+  'enquiry.name': 'Enquiry · name',
   'deal.name': 'Deal · name',
+  'opportunity.name': 'Opportunity · name',
+  'partnership.name': 'Partnership · name',
   submission: 'Submission only',
 }
 
+/** The map target for a consent field. Repeats per purpose, unlike `person.email`. */
+export const PERSON_CONSENT_TARGET: FormFieldMapTarget = 'person.consent'
+
 /** The one mapping a form cannot process without, and may carry at most once. */
 export const PERSON_EMAIL_TARGET: FormFieldMapTarget = 'person.email'
 
@@ -348,6 +401,16 @@ export const FORM_OPTION_VALUE_TYPES = ['string', 'number', 'boolean'] as const
 
 export type FormOptionValueType = (typeof FORM_OPTION_VALUE_TYPES)[number]
 
+/**
+ * Each post-submit action lands one of these on the submission's `action_log`.
+ * `ok` = the action ran; `skipped` = its precondition was absent (a company
+ * list on a submit that never resolved one); `error` = the savepoint rolled
+ * back so the rest of the submit could continue.
+ */
+export const FORM_ACTION_STATUSES = ['ok', 'skipped', 'error'] as const
+
+export type FormActionStatus = (typeof FORM_ACTION_STATUSES)[number]
+
 /**
  * The domain events a webhook can subscribe to.
  *
@@ -404,6 +467,7 @@ export const AGENT_TASK_TARGET_TYPES = [
   'opportunity',
   'partnership',
   'raise',
+  'enquiry',
   'candidate',
   'role',
   'handbook',
@@ -433,3 +497,116 @@ export const AGENT_RUN_STATUS_LABELS: Readonly<Record<AgentRunStatus, string>> =
   succeeded: 'Succeeded',
   failed: 'Failed',
 }
+
+/**
+ * The seven record types a workspace may attach custom field definitions to.
+ *
+ * The ones that already carry `tags` and agent-oriented fields on the record
+ * itself. Role and Candidate are absent on purpose: hiring state hangs off the
+ * Candidate link and a Role is a header rather than a rich record, so the demand
+ * signal for custom fields on either has not landed. Kept separate from
+ * `RECORD_TARGET_TYPES` and `EXTENSIBLE_RECORD_TYPES` so a later addition here
+ * cannot silently widen either of those.
+ */
+export const CUSTOM_FIELD_OBJECT_TYPES = [
+  'person',
+  'company',
+  'deal',
+  'opportunity',
+  'partnership',
+  'raise',
+  'enquiry',
+] as const
+
+export type CustomFieldObjectType = (typeof CUSTOM_FIELD_OBJECT_TYPES)[number]
+
+export const CUSTOM_FIELD_OBJECT_TYPE_LABELS: Readonly<Record<CustomFieldObjectType, string>> = {
+  person: 'Person',
+  company: 'Company',
+  deal: 'Deal',
+  opportunity: 'Opportunity',
+  partnership: 'Partnership',
+  raise: 'Raise',
+  enquiry: 'Enquiry',
+}
+
+/**
+ * The nine editor types a custom field can carry.
+ *
+ * Deliberately distinct from `FORM_FIELD_TYPES`: a form asks a stranger for four
+ * kinds of text over one submit; a custom field is a first-class attribute on a
+ * record with numeric, date, boolean and currency answers. Sharing one list
+ * would drag either surface toward the other's shape.
+ *
+ * `record_reference` is intentionally absent from v1 — it needs the polymorphic
+ * existence check and delete-transaction cleanup that Phase 2 owns.
+ */
+export const CUSTOM_FIELD_TYPES = [
+  'text',
+  'long_text',
+  'number',
+  'currency',
+  'date',
+  'checkbox',
+  'select',
+  'multi_select',
+  'url',
+] as const
+
+export type CustomFieldType = (typeof CUSTOM_FIELD_TYPES)[number]
+
+export const CUSTOM_FIELD_TYPE_LABELS: Readonly<Record<CustomFieldType, string>> = {
+  text: 'Text',
+  long_text: 'Long text',
+  number: 'Number',
+  currency: 'Currency',
+  date: 'Date',
+  checkbox: 'Checkbox',
+  select: 'Select',
+  multi_select: 'Multi-select',
+  url: 'URL',
+}
+
+/**
+ * The custom-field types whose definition carries an `options` list. Every
+ * other type stores its `options` as `[]` and any non-empty write is `422`.
+ */
+export const CUSTOM_FIELD_TYPES_WITH_OPTIONS = ['select', 'multi_select'] as const
+
+export type CustomFieldTypeWithOptions = (typeof CUSTOM_FIELD_TYPES_WITH_OPTIONS)[number]
+
+/**
+ * The default a consent purpose starts with, and what a person without an
+ * explicit `person_consents` row inherits for that purpose. `unknown` is the
+ * safest default — silence about a person's wishes is not a grant.
+ */
+export const CONSENT_PURPOSE_STATUSES = ['unknown', 'granted', 'withdrawn'] as const
+
+export type ConsentPurposeStatus = (typeof CONSENT_PURPOSE_STATUSES)[number]
+
+export const CONSENT_PURPOSE_STATUS_LABELS: Readonly<Record<ConsentPurposeStatus, string>> = {
+  unknown: 'Unknown',
+  granted: 'Granted',
+  withdrawn: 'Withdrawn',
+}
+
+/**
+ * The explicit status on a `person_consents` row. `unknown` is deliberately
+ * absent: no row is the unknown, so a stored row always carries a decision.
+ */
+export const CONSENT_STATUSES = ['granted', 'withdrawn'] as const
+
+export type ConsentStatus = (typeof CONSENT_STATUSES)[number]
+
+export const CONSENT_STATUS_LABELS: Readonly<Record<ConsentStatus, string>> = {
+  granted: 'Granted',
+  withdrawn: 'Withdrawn',
+}
+
+/**
+ * Where a `person_consents` row came from. `form:<form_id>` and `list:<list_id>`
+ * are prefixed so the origin is inspectable; `import` and `manual` need no id.
+ */
+export const CONSENT_SOURCE_KINDS = ['form', 'list', 'import', 'manual'] as const
+
+export type ConsentSourceKind = (typeof CONSENT_SOURCE_KINDS)[number]