sea-dev 1.0.0

package/libs/dal/src/form.ts

@@ -0,0 +1,1165 @@
+import { db, schema } from "@sea/db";
+import type { InsertFormDerived, InsertFormField, InsertFormGroup, Member } from "@sea/db/types";
+import { nanoid } from "@sea/util/id";
+import { invariant, InvariantError } from "@sea/util/invariant";
+import { and, asc, desc, eq, gte, inArray, isNull, sql } from "drizzle-orm";
+
+/**
+ * Retrieves all non-deleted forms for a member's organization
+ * @param member - The member whose organization's forms to retrieve
+ * @returns Array of forms with their associated workflows
+ */
+export async function getForms({ member }: { member: Member }) {
+  const forms = await db.query.form.findMany({
+    with: { workflow: true },
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+    ),
+  });
+  return forms;
+}
+
+/**
+ * Retrieves a specific form with its groups, fields, and derived fields
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form to retrieve
+ * @returns Form with nested groups, fields, and derived fields, ordered by their order field
+ * @throws Error if form is not found
+ */
+export async function getForm({ member, formId }: { member: Member; formId: string }) {
+  const form = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+    with: {
+      groups: {
+        with: {
+          fields: {
+            orderBy: asc(schema.formField.order),
+          },
+          derived: true,
+        },
+        orderBy: asc(schema.formGroup.order),
+      },
+    },
+  });
+  invariant(form, `no form found for ${formId}`);
+  return form;
+}
+
+/**
+ * Creates a new form with an associated conversation
+ * @param member - The member creating the form
+ * @param workflowId - The workflow the form belongs to
+ * @param name - The name of the form
+ * @param hint - Optional hint text for the form
+ * @returns The newly created form
+ */
+export async function createForm({
+  member,
+  workflowId,
+  name,
+  hint = "",
+}: {
+  member: Member;
+  workflowId: string;
+  name: string;
+  hint?: string;
+}) {
+  return await db.transaction(async (tx) => {
+    // Create conversation for the form
+    const [conversation] = await tx
+      .insert(schema.conversation)
+      .values({ organizationId: member.organizationId })
+      .returning();
+    invariant(conversation);
+
+    // Create the form
+    const [newForm] = await tx
+      .insert(schema.form)
+      .values({
+        workflowId,
+        organizationId: member.organizationId,
+        conversationId: conversation.id,
+        name,
+        hint,
+      })
+      .returning();
+    invariant(newForm);
+
+    return newForm;
+  });
+}
+
+/**
+ * Creates a new form with groups and fields in a single transaction
+ * @param member - The member creating the form
+ * @param workflowId - The workflow the form belongs to
+ * @param name - The name of the form
+ * @param hint - Optional hint text for the form
+ * @param groups - Array of groups with their fields to create
+ * @returns The complete form with all nested groups and fields
+ */
+export async function createFormWithGroups({
+  member,
+  workflowId,
+  name,
+  hint = "",
+  groups,
+}: {
+  member: Member;
+  workflowId: string;
+  name: string;
+  hint?: string;
+  groups: Array<{
+    name: string;
+    multi?: boolean;
+    hint?: string;
+    fields: Array<{
+      name: string;
+      type?:
+        | "string"
+        | "string-long"
+        | "number"
+        | "boolean"
+        | "date"
+        | "email"
+        | "money"
+        | "url"
+        | "enum";
+      hint?: string;
+    }>;
+  }>;
+}) {
+  const { organizationId } = member;
+
+  return await db.transaction(async (tx) => {
+    // Create conversation for the form
+    const [conversation] = await tx
+      .insert(schema.conversation)
+      .values({ organizationId })
+      .returning();
+    invariant(conversation);
+
+    // Create the form
+    const [newForm] = await tx
+      .insert(schema.form)
+      .values({
+        workflowId,
+        organizationId,
+        conversationId: conversation.id,
+        name,
+        hint,
+      })
+      .returning();
+    invariant(newForm);
+
+    // Create groups and fields
+    const formGroups: InsertFormGroup[] = [];
+    const formFields: InsertFormField[] = [];
+
+    groups.forEach((group, groupIndex) => {
+      const groupId = nanoid();
+      formGroups.push({
+        id: groupId,
+        formId: newForm.id,
+        name: group.name,
+        multi: group.multi ?? false,
+        hint: group.hint ?? "",
+        order: groupIndex,
+      });
+
+      group.fields.forEach((field, fieldIndex) => {
+        formFields.push({
+          formGroupId: groupId,
+          name: field.name,
+          type: field.type ?? "string",
+          hint: field.hint ?? "",
+          order: fieldIndex,
+        });
+      });
+    });
+
+    // Insert groups and fields
+    if (formGroups.length > 0) {
+      await tx.insert(schema.formGroup).values(formGroups);
+    }
+    if (formFields.length > 0) {
+      await tx.insert(schema.formField).values(formFields);
+    }
+
+    // Return the complete form with groups and fields
+    const completeForm = await tx.query.form.findFirst({
+      where: eq(schema.form.id, newForm.id),
+      with: {
+        groups: {
+          with: {
+            fields: {
+              orderBy: asc(schema.formField.order),
+            },
+          },
+          orderBy: asc(schema.formGroup.order),
+        },
+      },
+    });
+
+    invariant(completeForm, "Failed to retrieve created form");
+    return completeForm;
+  });
+}
+
+/**
+ * Updates a form's name and/or hint
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form to update
+ * @param name - Optional new name for the form
+ * @param hint - Optional new hint text for the form
+ * @returns The updated form
+ * @throws Error if form is not found
+ */
+export async function updateForm({
+  member,
+  formId,
+  name,
+  hint,
+}: {
+  member: Member;
+  formId: string;
+  name?: string;
+  hint?: string;
+}) {
+  // First verify the form exists and belongs to the organization
+  const existingForm = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+  });
+  invariant(existingForm, `no form found for ${formId}`);
+
+  // Build update object with only provided fields
+  const updateData: { name?: string; hint?: string } = {};
+  if (name !== undefined) updateData.name = name;
+  if (hint !== undefined) updateData.hint = hint;
+
+  const [updatedForm] = await db
+    .update(schema.form)
+    .set(updateData)
+    .where(eq(schema.form.id, formId))
+    .returning();
+
+  return updatedForm;
+}
+
+/**
+ * Soft deletes a form by setting its deletedAt timestamp
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form to delete
+ */
+export async function deleteForm({ member, formId }: { member: Member; formId: string }) {
+  await db
+    .update(schema.form)
+    .set({ deletedAt: new Date() })
+    .where(and(eq(schema.form.organizationId, member.organizationId), eq(schema.form.id, formId)));
+}
+
+/**
+ * Moves a form to a different workflow
+ * @param member - The member whose organization the form and workflow belong to
+ * @param formId - The ID of the form to move
+ * @param workflowId - The ID of the target workflow
+ * @returns The updated form with its groups and fields
+ * @throws Error if form or workflow is not found
+ */
+export async function moveFormToWorkflow({
+  member,
+  formId,
+  workflowId,
+}: {
+  member: Member;
+  formId: string;
+  workflowId: string;
+}) {
+  const { organizationId } = member;
+
+  // First verify the form exists and belongs to the organization
+  const existingForm = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+  });
+  invariant(existingForm, `no form found for ${formId}`);
+
+  // Verify the target workflow exists and belongs to the organization
+  const targetWorkflow = await db.query.workflow.findFirst({
+    where: and(
+      eq(schema.workflow.organizationId, organizationId),
+      isNull(schema.workflow.deletedAt),
+      eq(schema.workflow.id, workflowId),
+    ),
+  });
+  invariant(targetWorkflow, `no workflow found for ${workflowId}`);
+
+  // Update the form's workflow
+  await db.update(schema.form).set({ workflowId }).where(eq(schema.form.id, formId));
+
+  // Return the updated form
+  return await getForm({ member, formId });
+}
+
+/**
+ * Creates a copy of an existing form with all its groups, fields, and derived fields
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form to clone
+ * @param targetWorkflowId - Optional workflow ID to place the cloned form in (defaults to source form's workflow)
+ * @returns Object containing the newly created form
+ * @throws Error if form or target workflow is not found
+ */
+export async function cloneForm({
+  member,
+  formId,
+  targetWorkflowId,
+}: {
+  member: Member;
+  formId: string;
+  targetWorkflowId?: string;
+}) {
+  const existingForm = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+    with: {
+      groups: {
+        with: { fields: true, derived: true },
+        orderBy: asc(schema.formGroup.order),
+      },
+    },
+  });
+  invariant(existingForm, `no existing form found for ${formId}`);
+
+  // If targetWorkflowId is provided, verify access to it
+  if (targetWorkflowId) {
+    const targetWorkflow = await db.query.workflow.findFirst({
+      where: and(
+        eq(schema.workflow.organizationId, member.organizationId),
+        isNull(schema.workflow.deletedAt),
+        eq(schema.workflow.id, targetWorkflowId),
+      ),
+    });
+    invariant(targetWorkflow, `no workflow found for ${targetWorkflowId}`);
+  }
+
+  const newForm = await db.transaction(async (tx) => {
+    const [conversation] = await tx
+      .insert(schema.conversation)
+      .values({ organizationId: member.organizationId })
+      .returning();
+    invariant(conversation);
+    const { id: conversationId } = conversation;
+    const [newForm] = await tx
+      .insert(schema.form)
+      .values({
+        ...existingForm,
+        id: undefined,
+        workflowId: targetWorkflowId || existingForm.workflowId,
+        name: `${existingForm.name} (copy)`,
+        organizationId: member.organizationId,
+        conversationId,
+      })
+      .returning();
+    invariant(newForm);
+
+    const groups: InsertFormGroup[] = [];
+    const fields: InsertFormField[] = [];
+    const derived: InsertFormDerived[] = [];
+
+    existingForm.groups.forEach((group) => {
+      const formGroupId = nanoid();
+      groups.push({ ...group, id: formGroupId, formId: newForm.id });
+
+      group.fields.forEach((field) => {
+        fields.push({ ...field, id: undefined, formGroupId });
+      });
+
+      // Copy derived fields if any
+      group.derived?.forEach((derivedField) => {
+        derived.push({ ...derivedField, id: undefined, formGroupId });
+      });
+    });
+    if (groups.length > 0) {
+      await tx.insert(schema.formGroup).values(groups);
+    }
+    if (fields.length > 0) {
+      await tx.insert(schema.formField).values(fields);
+    }
+    if (derived.length > 0) {
+      await tx.insert(schema.formDerived).values(derived);
+    }
+    return newForm;
+  });
+  return { newForm };
+}
+
+/**
+ * Retrieves a specific form group within a form
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the group
+ * @param formGroupId - The ID of the group to retrieve
+ * @returns The form group
+ * @throws Error if form or group is not found
+ */
+export async function getFormGroup({
+  member,
+  formId,
+  formGroupId,
+}: {
+  member: Member;
+  formId: string;
+  formGroupId: string;
+}) {
+  const form = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+    with: {
+      groups: {
+        where: eq(schema.formGroup.id, formGroupId),
+        orderBy: asc(schema.formGroup.order),
+      },
+    },
+  });
+  invariant(form, `No form found for ${formId}`);
+  const [group] = form.groups;
+  invariant(group);
+
+  return group;
+}
+
+/**
+ * Creates a new group within a form
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form to add the group to
+ * @param name - The name of the group
+ * @param multi - Whether this group can have multiple instances (default: false)
+ * @param hint - Optional hint text for the group
+ * @param order - Optional position in the form (defaults to end)
+ * @returns The newly created group
+ * @throws Error if form is not found
+ */
+export async function createFormGroup({
+  member,
+  formId,
+  name,
+  multi = false,
+  hint = "",
+  order,
+}: {
+  member: Member;
+  formId: string;
+  name: string;
+  multi?: boolean;
+  hint?: string;
+  order?: number;
+}) {
+  const form = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+    with: {
+      groups: {
+        orderBy: asc(schema.formGroup.order),
+      },
+    },
+  });
+  invariant(form, `no form found for ${formId}`);
+
+  const group = await db.transaction(async (tx) => {
+    // If order not provided, append to the end
+    const maxOrder = form.groups.length ? Math.max(...form.groups.map((g) => g.order)) + 1 : 0;
+    const groupOrder = order !== undefined ? order : maxOrder;
+
+    // If order provided, make sure to shift all subsequent groups forward
+    if (order !== undefined) {
+      await tx
+        .update(schema.formGroup)
+        .set({ order: sql`${schema.formGroup.order} + 1` })
+        .where(and(eq(schema.formGroup.formId, formId), gte(schema.formGroup.order, order)));
+    }
+    const [group] = await tx
+      .insert(schema.formGroup)
+      .values({
+        formId,
+        name,
+        multi,
+        hint,
+        order: groupOrder,
+      })
+      .returning();
+    return group;
+  });
+  invariant(group);
+
+  return group;
+}
+
+/**
+ * Updates a form group's properties
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the group
+ * @param groupId - The ID of the group to update
+ * @param name - Optional new name for the group
+ * @param multi - Optional new multi value
+ * @param hint - Optional new hint text
+ * @param order - Optional new position (will shift other groups if needed)
+ * @returns The updated group
+ * @throws Error if group is not found or member lacks access
+ */
+export async function updateFormGroup({
+  member,
+  formGroupId,
+  formId,
+  name,
+  type,
+  multi,
+  hint,
+  order,
+}: {
+  member: Member;
+  formId: string;
+  formGroupId: string;
+  name?: string;
+  type?: "custom" | "bank_statement";
+  multi?: boolean;
+  hint?: string;
+  order?: number;
+}) {
+  // Validate access
+  const group = await getFormGroup({ member, formId, formGroupId });
+
+  const updateData: Partial<InsertFormGroup> = {};
+  if (name !== undefined) updateData.name = name;
+  if (type !== undefined) updateData.type = type;
+  if (multi !== undefined) updateData.multi = multi;
+  if (hint !== undefined) updateData.hint = hint;
+  if (order !== undefined) updateData.order = order;
+
+  if (Object.keys(updateData).length === 0) return group;
+  return await db.transaction(async (tx) => {
+    if (order !== undefined) {
+      await tx
+        .update(schema.formGroup)
+        .set({ order: sql`${schema.formGroup.order} + 1` })
+        .where(and(eq(schema.formGroup.formId, formId), gte(schema.formGroup.order, order)));
+    }
+    const [updatedGroup] = await tx
+      .update(schema.formGroup)
+      .set(updateData)
+      .where(eq(schema.formGroup.id, group.id))
+      .returning();
+    invariant(updatedGroup);
+    return updatedGroup;
+  });
+}
+
+/**
+ * Deletes a form group and all its fields (via cascade)
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the group
+ * @param groupId - The ID of the group to delete
+ * @throws Error if form or group is not found
+ */
+export async function deleteFormGroup({
+  member,
+  formId,
+  formGroupId,
+}: {
+  member: Member;
+  formId: string;
+  formGroupId: string;
+}) {
+  // Validate access
+  const group = await getFormGroup({ member, formId, formGroupId });
+  await db.delete(schema.formGroup).where(eq(schema.formGroup.id, group.id));
+}
+
+/**
+ * Retrieves a specific form field and validates access
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the field
+ * @param formFieldId - The ID of the field to retrieve
+ * @returns The form field
+ * @throws InvariantError if field is not found or doesn't belong to the specified form
+ */
+export async function getFormField({
+  member,
+  formId,
+  formFieldId,
+}: {
+  member: Member;
+  formId: string;
+  formFieldId: string;
+}) {
+  const fieldWithGroup = await db.query.formField.findFirst({
+    with: {
+      group: {
+        with: { form: true },
+      },
+    },
+    where: eq(schema.formField.id, formFieldId),
+  });
+  invariant(fieldWithGroup, `no formField found for ${formFieldId}`);
+
+  const { group, ...field } = fieldWithGroup;
+  if (group.form.organizationId !== member.organizationId || group.form.id !== formId) {
+    throw new InvariantError(`no formField found for ${formFieldId} in form ${formId}`);
+  }
+
+  return field;
+}
+
+/**
+ * Creates a new field within a form group
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the group
+ * @param groupId - The ID of the group to add the field to
+ * @param name - The name of the field
+ * @param type - The field type (default: "string")
+ * @param hint - Optional hint text for the field
+ * @param order - Optional position in the group (defaults to end)
+ * @returns The newly created field
+ * @throws Error if form or group is not found
+ */
+export async function createFormField({
+  member,
+  formId,
+  groupId,
+  name,
+  type = "string",
+  hint = "",
+  order,
+}: {
+  member: Member;
+  formId: string;
+  groupId: string;
+  name: string;
+  type?:
+    | "string"
+    | "string-long"
+    | "number"
+    | "boolean"
+    | "date"
+    | "email"
+    | "money"
+    | "url"
+    | "enum";
+  hint?: string;
+  order?: number;
+}) {
+  // Verify the form and group belong to the organization
+  const form = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+    with: {
+      groups: {
+        where: eq(schema.formGroup.id, groupId),
+        with: {
+          fields: {
+            orderBy: asc(schema.formField.order),
+          },
+        },
+      },
+    },
+  });
+  invariant(form, `no form found for ${formId}`);
+  const [group] = form.groups;
+  invariant(group, `group ${groupId} not found in form ${formId}`);
+
+  const maxOrder = group.fields.length ? Math.max(...group.fields.map((f) => f.order)) + 1 : 0;
+  const fieldOrder = order !== undefined ? order : maxOrder;
+  const [field] = await db
+    .insert(schema.formField)
+    .values({
+      formGroupId: groupId,
+      name,
+      type,
+      hint,
+      order: fieldOrder,
+    })
+    .returning();
+  invariant(field);
+
+  return field;
+}
+
+/**
+ * Updates a form field's properties
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form to which the field belongs to
+ * @param formFieldId - The ID of the field to update
+ * @param name - Optional new name for the field
+ * @param hint - Optional new hint text
+ * @param type - Optional new field type
+ * @param order - Optional new position (will shift other fields if needed)
+ * @returns The updated field
+ * @throws Error if field is not found or member lacks access
+ */
+export async function updateFormField({
+  member,
+  formId,
+  formFieldId,
+  name,
+  hint,
+  type,
+  order,
+}: {
+  member: Member;
+  formId: string;
+  formFieldId: string;
+  name?: string;
+  hint?: string;
+  type?:
+    | "string"
+    | "string-long"
+    | "number"
+    | "boolean"
+    | "date"
+    | "email"
+    | "money"
+    | "url"
+    | "enum";
+  order?: number;
+}) {
+  const field = await getFormField({ member, formId, formFieldId });
+  const updateData: Partial<InsertFormField> = {};
+  if (name !== undefined) updateData.name = name;
+  if (hint !== undefined) updateData.hint = hint;
+  if (type !== undefined) updateData.type = type;
+  if (order !== undefined) updateData.order = order;
+  if (Object.keys(updateData).length === 0) return field;
+
+  return await db.transaction(async (tx) => {
+    if (order !== undefined) {
+      await tx
+        .update(schema.formField)
+        .set({ order: sql`${schema.formField.order} + 1` })
+        .where(
+          and(
+            eq(schema.formField.formGroupId, field.formGroupId),
+            gte(schema.formField.order, order),
+          ),
+        );
+    }
+    const [formField] = await tx
+      .update(schema.formField)
+      .set(updateData)
+      .where(eq(schema.formField.id, formFieldId))
+      .returning();
+    invariant(formField);
+    return formField;
+  });
+}
+
+/**
+ * Updates only a form field's hint text
+ * @param member - The member whose organization the form belongs to
+ * @param formFieldId - The ID of the field to update
+ * @param hint - The new hint text
+ * @throws Error if field is not found or member lacks access
+ */
+export async function updateFormFieldHint({
+  member,
+  formFieldId,
+  hint,
+}: {
+  member: Member;
+  formFieldId: string;
+  hint: string;
+}) {
+  const field = await db.query.formField.findFirst({
+    where: eq(schema.formField.id, formFieldId),
+    with: { group: { with: { form: true } } },
+  });
+  if (field?.group.form.organizationId !== member.organizationId) {
+    throw new InvariantError(`formField not found for ${formFieldId}`);
+  }
+
+  // Get the field to validate access
+  await db.update(schema.formField).set({ hint }).where(eq(schema.formField.id, field.id));
+}
+
+/**
+ * Deletes a form field
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the field
+ * @param fieldId - The ID of the field to delete
+ * @throws Error if form or field is not found
+ */
+export async function deleteFormField({
+  member,
+  formId,
+  formFieldId,
+}: {
+  member: Member;
+  formId: string;
+  formFieldId: string;
+}) {
+  // Get the field to validate access
+  const field = await getFormField({ member, formId, formFieldId });
+  await db.delete(schema.formField).where(eq(schema.formField.id, field.id));
+}
+
+/**
+ * Creates a derived field within a form group (computed/AI-generated field)
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the group
+ * @param groupId - The ID of the group to add the derived field to
+ * @param name - The name of the derived field
+ * @param prompt - Optional prompt text for generating the derived value
+ * @returns The newly created derived field
+ * @throws Error if form or group is not found
+ */
+export async function createFormDerived({
+  member,
+  formId,
+  groupId,
+  name,
+  prompt = "",
+}: {
+  member: Member;
+  formId: string;
+  groupId: string;
+  name: string;
+  prompt?: string;
+}) {
+  // Verify the form and group belong to the organization
+  const form = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+    with: {
+      groups: {
+        where: eq(schema.formGroup.id, groupId),
+      },
+    },
+  });
+  invariant(form, `no form found for ${formId}`);
+  invariant(form.groups.length > 0, `group ${groupId} not found in form ${formId}`);
+
+  const [derived] = await db
+    .insert(schema.formDerived)
+    .values({
+      formGroupId: groupId,
+      name,
+      prompt,
+    })
+    .returning();
+  invariant(derived);
+
+  return derived;
+}
+
+/**
+ * Updates a derived field's properties
+ * @param member - The member whose organization the form belongs to
+ * @param derivedId - The ID of the derived field to update
+ * @param name - Optional new name for the derived field
+ * @param prompt - Optional new prompt text
+ * @returns The updated derived field
+ * @throws Error if derived field is not found or member lacks access
+ */
+export async function updateFormDerived({
+  member,
+  formId,
+  derivedId,
+  name,
+  prompt,
+}: {
+  member: Member;
+  formId: string;
+  derivedId: string;
+  name?: string;
+  prompt?: string;
+}) {
+  // Verify the form and derived field belong to the organization
+  const formDerived = await db.query.formDerived.findFirst({
+    with: {
+      group: {
+        with: {
+          form: true,
+        },
+      },
+    },
+    where: eq(schema.formDerived.id, derivedId),
+  });
+  invariant(formDerived, `no formDerived found for ${derivedId}`);
+  const { group, ...currentDerived } = formDerived;
+
+  if (group.form.organizationId !== member.organizationId) {
+    throw new InvariantError(`no form found for ${formId}`);
+  }
+
+  const updateData: Partial<InsertFormDerived> = {};
+  if (name !== undefined) updateData.name = name;
+  if (prompt !== undefined) updateData.prompt = prompt;
+
+  if (Object.keys(updateData).length === 0) return currentDerived;
+  const [updatedFormDerived] = await db
+    .update(schema.formDerived)
+    .set(updateData)
+    .where(eq(schema.formDerived.id, derivedId))
+    .returning();
+
+  return updatedFormDerived;
+}
+
+/**
+ * Deletes a derived field
+ * @param member - The member whose organization the form belongs to
+ * @param formId - The ID of the form containing the derived field
+ * @param derivedId - The ID of the derived field to delete
+ * @throws Error if form or derived field is not found
+ */
+export async function deleteFormDerived({
+  member,
+  formId,
+  derivedId,
+}: {
+  member: Member;
+  formId: string;
+  derivedId: string;
+}) {
+  // Verify the form and derived field belong to the organization
+  const form = await db.query.form.findFirst({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+      eq(schema.form.id, formId),
+    ),
+    with: {
+      groups: {
+        with: {
+          derived: {
+            where: eq(schema.formDerived.id, derivedId),
+          },
+        },
+      },
+    },
+  });
+  invariant(form, `no form found for ${formId}`);
+
+  const derivedBelongsToForm = form.groups.some((group) =>
+    group.derived.some((d) => d.id === derivedId),
+  );
+  invariant(derivedBelongsToForm, `derived field ${derivedId} not found in form ${formId}`);
+
+  await db.delete(schema.formDerived).where(eq(schema.formDerived.id, derivedId));
+}
+
+/**
+ * Creates or updates a merged form for a template based on its workflow
+ * Combines all groups from all forms in the workflow into a single form
+ * @param member - The member whose organization the template belongs to
+ * @param templateId - The ID of the template
+ * @param workflowId - The ID of the workflow to merge forms from
+ * @param existingMergedFormId - Optional ID of existing merged form to update
+ * @returns The merged form ID and a hash of the workflow's forms for staleness checking
+ */
+export async function getOrCreateMergedFormForTemplate({
+  member,
+  templateId,
+  workflowId,
+  existingMergedFormId,
+}: {
+  member: Member;
+  templateId: string;
+  workflowId: string;
+  existingMergedFormId?: string | null;
+}): Promise<{ formId: string; formHash: string }> {
+  // Get all forms in the workflow with their groups and fields
+  const workflowForms = await db.query.form.findMany({
+    where: and(
+      eq(schema.form.workflowId, workflowId),
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+    ),
+    with: {
+      groups: {
+        with: {
+          fields: {
+            orderBy: asc(schema.formField.order),
+          },
+          derived: true,
+        },
+        orderBy: asc(schema.formGroup.order),
+      },
+    },
+    orderBy: asc(schema.form.createdAt),
+  });
+
+  if (workflowForms.length === 0) {
+    throw new InvariantError(`No forms found in workflow ${workflowId}`);
+  }
+
+  // Create a hash of form IDs and their updated timestamps to detect changes
+  const formHash = workflowForms.map((f) => `${f.id}:${f.updatedAt.getTime()}`).join("|");
+
+  // Check if existing merged form is still valid
+  if (existingMergedFormId) {
+    const existingForm = await db.query.form.findFirst({
+      where: and(
+        eq(schema.form.id, existingMergedFormId),
+        eq(schema.form.organizationId, member.organizationId),
+        isNull(schema.form.deletedAt),
+      ),
+    });
+
+    // If form exists with the same name pattern, check if it's still valid
+    // We store the hash in the form name for now since metadata field doesn't exist
+    if (existingForm && existingForm.name.includes(formHash.substring(0, 10))) {
+      return { formId: existingMergedFormId, formHash };
+    }
+  }
+
+  // Need to create new merged form
+  return await db.transaction(async (tx) => {
+    // Create conversation for the merged form
+    const [conversation] = await tx
+      .insert(schema.conversation)
+      .values({ organizationId: member.organizationId })
+      .returning();
+    invariant(conversation);
+
+    // Get workflow name for form name
+    const workflow = await tx.query.workflow.findFirst({
+      where: eq(schema.workflow.id, workflowId),
+    });
+
+    // Create the merged form
+    const [mergedForm] = await tx
+      .insert(schema.form)
+      .values({
+        organizationId: member.organizationId,
+        workflowId,
+        conversationId: conversation.id,
+        name: `Merged: ${workflow?.name || workflowId} [${formHash.substring(0, 10)}]`,
+        hint: `Auto-generated merged form for template ${templateId}`,
+      })
+      .returning();
+    invariant(mergedForm);
+
+    // Merge all groups from all forms
+    let groupOrder = 0;
+    for (const sourceForm of workflowForms) {
+      for (const sourceGroup of sourceForm.groups) {
+        // Insert group with new IDs
+        const [newGroup] = await tx
+          .insert(schema.formGroup)
+          .values({
+            formId: mergedForm.id,
+            name: `${sourceForm.name} - ${sourceGroup.name}`,
+            order: groupOrder++,
+            type: sourceGroup.type,
+            multi: sourceGroup.multi,
+            hint: sourceGroup.hint,
+          })
+          .returning();
+        invariant(newGroup);
+
+        // Copy all fields
+        for (const sourceField of sourceGroup.fields) {
+          await tx.insert(schema.formField).values({
+            formGroupId: newGroup.id,
+            name: sourceField.name,
+            type: sourceField.type,
+            order: sourceField.order,
+            hint: sourceField.hint,
+            options: sourceField.options,
+          });
+        }
+
+        // Copy all derived fields
+        for (const sourceDerived of sourceGroup.derived) {
+          await tx.insert(schema.formDerived).values({
+            formGroupId: newGroup.id,
+            name: sourceDerived.name,
+            prompt: sourceDerived.prompt,
+          });
+        }
+      }
+    }
+
+    return { formId: mergedForm.id, formHash };
+  });
+}
+
+/**
+ * Get all forms for an organization with pagination
+ */
+export async function getFormsForOrganization({
+  member,
+  limit = 100,
+}: {
+  member: Member;
+  limit?: number;
+}) {
+  const forms = await db.query.form.findMany({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      isNull(schema.form.deletedAt),
+    ),
+    columns: {
+      id: true,
+      name: true,
+      updatedAt: true,
+    },
+    orderBy: [desc(schema.form.updatedAt)],
+    limit,
+  });
+
+  return { ok: true, data: forms };
+}
+
+/**
+ * Get multiple forms by their IDs
+ */
+export async function getFormsByIds({ member, formIds }: { member: Member; formIds: string[] }) {
+  if (formIds.length === 0) {
+    return { ok: true, data: [] };
+  }
+
+  const forms = await db.query.form.findMany({
+    where: and(
+      eq(schema.form.organizationId, member.organizationId),
+      inArray(schema.form.id, formIds),
+      isNull(schema.form.deletedAt),
+    ),
+    columns: {
+      id: true,
+      name: true,
+      organizationId: true,
+    },
+  });
+
+  if (forms.length !== formIds.length) {
+    return { ok: false, error: "not-found" };
+  }
+
+  return { ok: true, data: forms };
+}