@kelpie/schemas 0.1.0

package/src/form.ts

@@ -0,0 +1,217 @@
+import { z } from 'zod'
+
+import {
+  FORM_FIELD_MAP_TARGETS,
+  FORM_FIELD_TYPES,
+  FORM_OPTION_VALUE_TYPES,
+  FORM_STATUSES,
+} from './values.ts'
+import type { FormFieldMapTarget, FormFieldType, FormOptionValueType, FormStatus } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/forms`, the embeddable inbound capture from
+ * [`forms.md`](../../../forms.md).
+ *
+ * Fields come back nested inside their form rather than as their own resource.
+ * A form without its fields cannot be rendered or validated, so every caller
+ * that wants one wants both, and the ordering is the form's rather than a
+ * property of any single field.
+ */
+
+/**
+ * A select choice. `key` is the identifier: it is what a stored answer holds and
+ * what a submit is checked against, so the display `value` is free to change.
+ */
+export interface FormFieldOption {
+  readonly key: string
+  /** What the embed shows in the dropdown. */
+  readonly value: string
+  readonly valueType: FormOptionValueType
+}
+
+export interface FormField {
+  readonly id: string
+  readonly label: string
+  readonly type: FormFieldType
+  readonly required: boolean
+  readonly mapTo: FormFieldMapTarget
+  /** Empty for every type but `select`. */
+  readonly options: readonly FormFieldOption[]
+  readonly placeholder: string | null
+  /** Position in the form, contiguous from 0. The server renumbers on every write. */
+  readonly sortOrder: number
+}
+
+export interface Form extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  readonly description: string | null
+  readonly status: FormStatus
+  readonly fields: readonly FormField[]
+  readonly thankYouMessage: string
+  readonly createDeal: boolean
+  /** Null means the deal pipeline's default stage is used at submit time. */
+  readonly dealStageId: string | null
+  /** Expands `{{company.name}}` and `{{person.name}}`. Null when `createDeal` is off. */
+  readonly dealNameTemplate: string | null
+  /**
+   * The handle the public submit and embed endpoints resolve a workspace from.
+   * Globally unique, and the only credential those endpoints take.
+   */
+  readonly publicKey: string
+}
+
+const formFieldOptionSchema = z
+  .object({
+    key: z.string(),
+    value: z.string(),
+    value_type: z.enum(FORM_OPTION_VALUE_TYPES),
+  })
+  .transform(
+    (wire): FormFieldOption => ({
+      key: wire.key,
+      value: wire.value,
+      valueType: wire.value_type,
+    }),
+  )
+
+const formFieldSchema = z
+  .object({
+    id: idSchema,
+    label: z.string(),
+    type: z.enum(FORM_FIELD_TYPES),
+    required: z.boolean(),
+    map_to: z.enum(FORM_FIELD_MAP_TARGETS),
+    options: z.array(formFieldOptionSchema),
+    placeholder: z.string().nullable(),
+    sort_order: z.number().int(),
+  })
+  .transform(
+    (wire): FormField => ({
+      id: wire.id,
+      label: wire.label,
+      type: wire.type,
+      required: wire.required,
+      mapTo: wire.map_to,
+      options: wire.options,
+      placeholder: wire.placeholder,
+      sortOrder: wire.sort_order,
+    }),
+  )
+
+export const formSchema: z.ZodType<Form, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    description: z.string().nullable(),
+    status: z.enum(FORM_STATUSES),
+    fields: z.array(formFieldSchema),
+    thank_you_message: z.string(),
+    create_deal: z.boolean(),
+    deal_stage_id: idSchema.nullable(),
+    deal_name_template: z.string().nullable(),
+    public_key: z.string(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Form => ({
+      id: wire.id,
+      name: wire.name,
+      description: wire.description,
+      status: wire.status,
+      fields: wire.fields,
+      thankYouMessage: wire.thank_you_message,
+      createDeal: wire.create_deal,
+      dealStageId: wire.deal_stage_id,
+      dealNameTemplate: wire.deal_name_template,
+      publicKey: wire.public_key,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface FormFieldOptionInput {
+  readonly key: string
+  readonly value: string
+  readonly valueType?: FormOptionValueType
+}
+
+/**
+ * A field as it is written.
+ *
+ * There is no id: a write replaces the whole field list, so the server assigns
+ * ids and positions from the array's order. Editing one field means sending the
+ * list back with that field changed, which is also what a drag-reorder sends.
+ */
+export interface FormFieldInput {
+  readonly label: string
+  readonly type: FormFieldType
+  readonly required?: boolean
+  readonly mapTo: FormFieldMapTarget
+  readonly options?: readonly FormFieldOptionInput[]
+  readonly placeholder?: string | null
+}
+
+export interface CreateFormInput {
+  readonly name: string
+  readonly description?: string | null
+  readonly status?: FormStatus
+  readonly fields: readonly FormFieldInput[]
+  readonly thankYouMessage?: string
+  readonly createDeal?: boolean
+  readonly dealStageId?: string | null
+  readonly dealNameTemplate?: string | null
+}
+
+/** `fields` is absent or the whole list; there is no per-field patch. */
+export interface FormInput {
+  readonly name?: string
+  readonly description?: string | null
+  readonly status?: FormStatus
+  readonly fields?: readonly FormFieldInput[]
+  readonly thankYouMessage?: string
+  readonly createDeal?: boolean
+  readonly dealStageId?: string | null
+  readonly dealNameTemplate?: string | null
+}
+
+function fieldBody(field: FormFieldInput): Record<string, unknown> {
+  return definedFields({
+    label: field.label,
+    type: field.type,
+    required: field.required,
+    map_to: field.mapTo,
+    options: field.options?.map((option) =>
+      definedFields({ key: option.key, value: option.value, value_type: option.valueType }),
+    ),
+    placeholder: field.placeholder,
+  })
+}
+
+export function createFormBody(input: CreateFormInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    description: input.description,
+    status: input.status,
+    fields: input.fields.map(fieldBody),
+    thank_you_message: input.thankYouMessage,
+    create_deal: input.createDeal,
+    deal_stage_id: input.dealStageId,
+    deal_name_template: input.dealNameTemplate,
+  })
+}
+
+export function formBody(input: FormInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    description: input.description,
+    status: input.status,
+    fields: input.fields?.map(fieldBody),
+    thank_you_message: input.thankYouMessage,
+    create_deal: input.createDeal,
+    deal_stage_id: input.dealStageId,
+    deal_name_template: input.dealNameTemplate,
+  })
+}

package/src/formSubmission.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+
+import { idSchema, timestampSchema } from './wire.ts'
+
+/**
+ * Wire shape for `/v1/forms/:id/submissions`, and for what the public submit
+ * endpoint answers with.
+ *
+ * Read-only over the API: a submission is evidence of what arrived, so there is
+ * no create body here (the public endpoint takes an answer map, not a
+ * submission) and no update at all.
+ */
+
+export interface FormSubmission {
+  readonly id: string
+  readonly formId: string
+  readonly submittedAt: Date
+  /** Field id to the answer given: a select option's `key`, or free text. */
+  readonly answers: Readonly<Record<string, string>>
+  /**
+   * What the submit created or matched. Each is null when the rule did not
+   * apply, and each becomes null again if that record is later deleted: the
+   * submission outlives what it produced.
+   */
+  readonly personId: string | null
+  readonly companyId: string | null
+  readonly positionId: string | null
+  readonly dealId: string | null
+  readonly createdAt: Date
+}
+
+export const formSubmissionSchema: z.ZodType<FormSubmission, unknown> = z
+  .object({
+    id: idSchema,
+    form_id: idSchema,
+    submitted_at: timestampSchema,
+    answers: z.record(z.string(), z.string()),
+    person_id: idSchema.nullable(),
+    company_id: idSchema.nullable(),
+    position_id: idSchema.nullable(),
+    deal_id: idSchema.nullable(),
+    created_at: timestampSchema,
+  })
+  .transform(
+    (wire): FormSubmission => ({
+      id: wire.id,
+      formId: wire.form_id,
+      submittedAt: wire.submitted_at,
+      answers: wire.answers,
+      personId: wire.person_id,
+      companyId: wire.company_id,
+      positionId: wire.position_id,
+      dealId: wire.deal_id,
+      createdAt: wire.created_at,
+    }),
+  )
+
+/**
+ * What the public submit endpoint answers with.
+ *
+ * Smaller than the stored submission, as `forms.md` specifies: the ids it
+ * produced, and nothing else. The caller is a stranger's browser, and echoing
+ * back the answers it just sent would tell it nothing it does not have.
+ */
+export interface FormSubmitResult {
+  readonly id: string
+  readonly formId: string
+  readonly submittedAt: Date
+  readonly personId: string
+  readonly companyId: string | null
+  readonly positionId: string | null
+  readonly dealId: string | null
+  /** The form's configured confirmation, so an embed can render it without a second request. */
+  readonly thankYouMessage: string
+}
+
+export const formSubmitResultSchema: z.ZodType<FormSubmitResult, unknown> = z
+  .object({
+    id: idSchema,
+    form_id: idSchema,
+    submitted_at: timestampSchema,
+    person_id: idSchema,
+    company_id: idSchema.nullable(),
+    position_id: idSchema.nullable(),
+    deal_id: idSchema.nullable(),
+    thank_you_message: z.string(),
+  })
+  .transform(
+    (wire): FormSubmitResult => ({
+      id: wire.id,
+      formId: wire.form_id,
+      submittedAt: wire.submitted_at,
+      personId: wire.person_id,
+      companyId: wire.company_id,
+      positionId: wire.position_id,
+      dealId: wire.deal_id,
+      thankYouMessage: wire.thank_you_message,
+    }),
+  )

package/src/handbookPage.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/handbook_pages`, the workspace's nested
+ * markdown handbook.
+ *
+ * The response is flat: `parentId` and `sortOrder` are the tree, and the caller
+ * rebuilds it. `sortOrder` positions a page among its siblings only, so it is
+ * meaningless across the whole set and the list is not sorted by it.
+ *
+ * `updatedBy` is a workspace member id, not a user id, and is null when no
+ * member was behind the write (a workspace API key). Resolving it to a name is
+ * the caller's job, as with a note's author.
+ */
+
+/** Top-level pages are 0, so `MAX_DEPTH` of 4 allows five levels. Mirrors the server's cap. */
+export const MAX_HANDBOOK_DEPTH = 4
+
+export interface HandbookPage extends RecordTimestamps {
+  readonly id: string
+  readonly title: string
+  /** The stable handle agent tasks name pages by. It does not follow the title. */
+  readonly slug: string
+  readonly parentId: string | null
+  readonly sortOrder: number
+  readonly body: string
+  readonly updatedBy: string | null
+}
+
+export const handbookPageSchema: z.ZodType<HandbookPage, unknown> = z
+  .object({
+    id: idSchema,
+    title: z.string(),
+    slug: z.string(),
+    parent_id: idSchema.nullable(),
+    sort_order: z.number().int(),
+    body: z.string(),
+    updated_by: idSchema.nullable(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): HandbookPage => ({
+      id: wire.id,
+      title: wire.title,
+      slug: wire.slug,
+      parentId: wire.parent_id,
+      sortOrder: wire.sort_order,
+      body: wire.body,
+      updatedBy: wire.updated_by,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreateHandbookPageInput {
+  readonly title: string
+  /** Absent means empty: a page is created before it is written. */
+  readonly body?: string
+  /** Absent means derived from the title, with a numeric suffix if that is taken. */
+  readonly slug?: string
+  /** Absent or null puts the page at the top level. */
+  readonly parentId?: string | null
+}
+
+export function createHandbookPageBody(input: CreateHandbookPageInput): Record<string, unknown> {
+  return definedFields({
+    title: input.title,
+    body: input.body,
+    slug: input.slug,
+    parent_id: input.parentId,
+  })
+}
+
+/**
+ * `parentId` and `sortOrder` are the move; the rest is the edit. A drag sends
+ * both halves of the move together, because landing somewhere new is a parent
+ * and a position at once.
+ */
+export interface HandbookPageInput {
+  readonly title?: string
+  readonly body?: string
+  readonly slug?: string
+  /** Null lifts the page to the top level. */
+  readonly parentId?: string | null
+  readonly sortOrder?: number
+}
+
+export function handbookPageBody(input: HandbookPageInput): Record<string, unknown> {
+  return definedFields({
+    title: input.title,
+    body: input.body,
+    slug: input.slug,
+    parent_id: input.parentId,
+    sort_order: input.sortOrder,
+  })
+}