sea-dev 1.0.0

package/apps/api/src/routes/v2/pipelines/handlers.ts

@@ -0,0 +1,261 @@
+import {
+  addManualInput,
+  addStepDependency,
+  createPipelineStep,
+  deletePipelineStep,
+  getAllBlockersForRun,
+  getCitationChain,
+  removeManualInput,
+  removeStepDependency,
+  updatePipelineStep,
+} from "@sea/core";
+import type { MemberHydrated } from "@sea/dal/member";
+import type { FastifyReply } from "fastify";
+import type {
+  AddManualInputRequest,
+  AddStepDependencyRequest,
+  CreateStepRequest,
+  UpdateStepRequest,
+} from "./schemas";
+
+// Step CRUD Handlers
+export async function createStepHandler(
+  body: CreateStepRequest,
+  pipelineId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await createPipelineStep({
+      member,
+      pipelineId,
+      name: body.name,
+      description: body.description,
+      prompt: body.prompt,
+      type: body.type,
+      role: body.role,
+      stepOrder: body.stepOrder,
+      outputFormIds: body.outputFormIds,
+      toolsAllowed: body.toolsAllowed,
+      integrationConfig: body.integrationConfig,
+    });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply.code(404).send({ description: "Pipeline not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to create step" });
+    }
+
+    return result.data;
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to create step" });
+  }
+}
+
+export async function updateStepHandler(
+  body: UpdateStepRequest,
+  stepId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await updatePipelineStep({
+      member,
+      stepId,
+      name: body.name,
+      description: body.description,
+      prompt: body.prompt,
+      type: body.type,
+      role: body.role,
+      outputFormIds: body.outputFormIds,
+      toolsAllowed: body.toolsAllowed,
+      integrationConfig: body.integrationConfig,
+    });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply.code(404).send({ description: "Step not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to update step" });
+    }
+
+    return result.data;
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to update step" });
+  }
+}
+
+export async function deleteStepHandler(
+  stepId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await deletePipelineStep({ member, stepId });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply.code(404).send({ description: "Step not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to delete step" });
+    }
+
+    return result.data;
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to delete step" });
+  }
+}
+
+// Step Dependency Handlers
+export async function addStepDependencyHandler(
+  { parentStepId, multiFormGroupId }: AddStepDependencyRequest,
+  childStepId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await addStepDependency({
+      member,
+      childStepId,
+      parentStepId,
+      multiFormGroupId: multiFormGroupId ?? null,
+    });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply.code(404).send({ description: "Step not found or access denied" });
+      }
+      if (result.error === "validation-error") {
+        return reply.code(400).send({ description: "Validation error" });
+      }
+      return reply.code(500).send({ description: "Failed to add step dependency" });
+    }
+
+    return result.data;
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to add step dependency" });
+  }
+}
+
+export async function removeStepDependencyHandler(
+  dependencyId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await removeStepDependency({ member, dependencyId });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply.code(404).send({ description: "Dependency not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to remove step dependency" });
+    }
+
+    return { success: true };
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to remove step dependency" });
+  }
+}
+
+// Manual Input Handlers
+export async function addManualInputHandler(
+  { submissionId }: AddManualInputRequest,
+  runStepId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await addManualInput({ member, runStepId, submissionId });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply
+          .code(404)
+          .send({ description: "Step or submission not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to add manual input" });
+    }
+
+    return result.data;
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to add manual input" });
+  }
+}
+
+export async function removeManualInputHandler(
+  manualInputId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await removeManualInput({ member, manualInputId });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply.code(404).send({ description: "Manual input not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to remove manual input" });
+    }
+
+    return { success: true };
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to remove manual input" });
+  }
+}
+
+// Blocker Handler
+export async function getAllBlockersForRunHandler(
+  runId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await getAllBlockersForRun({ member, runId });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply.code(404).send({ description: "Run not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to retrieve blockers" });
+    }
+
+    return result.data;
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to retrieve blockers" });
+  }
+}
+
+// Citation Chain Handler
+export async function getCitationChainHandler(
+  submissionItemVersionId: string,
+  member: MemberHydrated,
+  reply: FastifyReply,
+) {
+  try {
+    const result = await getCitationChain({ member, submissionItemVersionId });
+
+    if (!result.ok) {
+      if (result.error === "not-found") {
+        return reply
+          .code(404)
+          .send({ description: "Submission item version not found or access denied" });
+      }
+      return reply.code(500).send({ description: "Failed to retrieve citation chain" });
+    }
+
+    return { chain: result.data };
+  } catch (error) {
+    console.error(error);
+    return reply.code(500).send({ description: "Failed to retrieve citation chain" });
+  }
+}

package/apps/api/src/routes/v2/pipelines/index.ts

@@ -0,0 +1,224 @@
+import { type FastifyInstance } from "fastify";
+import { type ZodTypeProvider } from "fastify-type-provider-zod";
+import * as z from "zod/v4";
+import {
+  addManualInputHandler,
+  addStepDependencyHandler,
+  createStepHandler,
+  deleteStepHandler,
+  getAllBlockersForRunHandler,
+  getCitationChainHandler,
+  removeManualInputHandler,
+  removeStepDependencyHandler,
+  updateStepHandler,
+} from "./handlers";
+import {
+  addManualInputSchema,
+  addStepDependencySchema,
+  citationChainResponseSchema,
+  createStepSchema,
+  manualInputResponseSchema,
+  runBlockersResponseSchema,
+  stepDependencyResponseSchema,
+  stepResponseSchema,
+  updateStepSchema,
+} from "./schemas";
+
+export async function v2PipelinesRouter(app: FastifyInstance) {
+  app
+    .withTypeProvider<ZodTypeProvider>()
+    // Create step
+    .route({
+      method: "POST",
+      url: "/:pipelineId/steps",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Create a new pipeline step with specified configuration including role (extraction/integration/analysis), type (single/multi), output forms, and other settings. Returns the created step ID.",
+        params: z.object({
+          pipelineId: z.string(),
+        }),
+        body: createStepSchema,
+        response: {
+          200: stepResponseSchema,
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, body, member }, reply) =>
+        createStepHandler(body, params.pipelineId, member, reply),
+    })
+    // Update step
+    .route({
+      method: "PATCH",
+      url: "/:pipelineId/steps/:stepId",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Update an existing pipeline step's configuration. All fields are optional; only provided fields will be updated. Returns success status on completion.",
+        params: z.object({
+          pipelineId: z.string(),
+          stepId: z.string(),
+        }),
+        body: updateStepSchema,
+        response: {
+          200: z.object({ success: z.boolean() }),
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, body, member }, reply) =>
+        updateStepHandler(body, params.stepId, member, reply),
+    })
+    // Delete step
+    .route({
+      method: "DELETE",
+      url: "/:pipelineId/steps/:stepId",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Delete a pipeline step. This will cascade delete all dependencies and related data. Returns success status on completion.",
+        params: z.object({
+          pipelineId: z.string(),
+          stepId: z.string(),
+        }),
+        response: {
+          200: z.object({ success: z.boolean() }),
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, member }, reply) => deleteStepHandler(params.stepId, member, reply),
+    })
+    // Add step dependency
+    .route({
+      method: "POST",
+      url: "/:pipelineId/steps/:stepId/dependencies",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Add a parent dependency to a pipeline step. This creates a dependency relationship where the child step depends on the parent step completing first. For multi-type steps, you can specify which form group from the parent output should be processed.",
+        params: z.object({
+          pipelineId: z.string(),
+          stepId: z.string(),
+        }),
+        body: addStepDependencySchema,
+        response: {
+          200: stepDependencyResponseSchema,
+          400: z.object({ description: z.string() }),
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, body, member }, reply) =>
+        addStepDependencyHandler(body, params.stepId, member, reply),
+    })
+    // Remove step dependency
+    .route({
+      method: "DELETE",
+      url: "/:pipelineId/steps/:stepId/dependencies/:dependencyId",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Remove a dependency relationship between two pipeline steps. This allows the child step to execute without waiting for the parent step. Returns success status on completion.",
+        params: z.object({
+          pipelineId: z.string(),
+          stepId: z.string(),
+          dependencyId: z.string(),
+        }),
+        response: {
+          200: z.object({ success: z.boolean() }),
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, member }, reply) =>
+        removeStepDependencyHandler(params.dependencyId, member, reply),
+    })
+    // Get run blockers
+    .route({
+      method: "GET",
+      url: "/runs/:runId/blockers",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Retrieve all blockers for all steps in a pipeline run, grouped by step. Blockers prevent step execution and include missing uploads, incomplete parent steps, missing configuration, or missing manual inputs. Each step includes its blockers with resolution status and timestamps.",
+        params: z.object({
+          runId: z.string(),
+        }),
+        response: {
+          200: runBlockersResponseSchema,
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, member }, reply) =>
+        getAllBlockersForRunHandler(params.runId, member, reply),
+    })
+    // Add manual input
+    .route({
+      method: "POST",
+      url: "/runs/:runId/steps/:stepId/manual-inputs",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Add a manual input submission to a pipeline run step. Manual inputs provide additional context or data beyond what comes from parent step outputs. The submission must belong to the same organization as the pipeline run.",
+        params: z.object({
+          runId: z.string(),
+          stepId: z.string(),
+        }),
+        body: addManualInputSchema,
+        response: {
+          200: manualInputResponseSchema,
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, body, member }, reply) =>
+        addManualInputHandler(body, params.stepId, member, reply),
+    })
+    // Remove manual input
+    .route({
+      method: "DELETE",
+      url: "/runs/:runId/steps/:stepId/manual-inputs/:inputId",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Remove a manual input submission from a pipeline run step. This removes the additional context provided by the manual input. Returns success status on completion.",
+        params: z.object({
+          runId: z.string(),
+          stepId: z.string(),
+          inputId: z.string(),
+        }),
+        response: {
+          200: z.object({ success: z.boolean() }),
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, member }, reply) =>
+        removeManualInputHandler(params.inputId, member, reply),
+    })
+    // Get citation chain
+    .route({
+      method: "GET",
+      url: "/submissions/:subId/items/:itemId/versions/:versionId/citations",
+      schema: {
+        tags: ["Pipelines"],
+        description:
+          "Retrieve the complete citation chain for a submission item version. This traces data provenance recursively from the item back through all transformations to the original source documents or API integrations. Returns a tree structure showing the full lineage of the data.",
+        params: z.object({
+          subId: z.string(),
+          itemId: z.string(),
+          versionId: z.string(),
+        }),
+        response: {
+          200: citationChainResponseSchema,
+          404: z.object({ description: z.string() }),
+          500: z.object({ description: z.string() }),
+        },
+      },
+      handler: async ({ params, member }, reply) =>
+        getCitationChainHandler(params.versionId, member, reply),
+    });
+}

package/apps/api/src/routes/v2/pipelines/schemas.ts

@@ -0,0 +1,173 @@
+import * as z from "zod/v4";
+
+// Step CRUD Schemas
+export const createStepSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  description: z.string(),
+  prompt: z.string().optional(),
+  type: z.enum(["single", "multi"]),
+  role: z.enum(["extraction", "integration", "analysis"]).nullable(),
+  stepOrder: z.number().int().nonnegative(),
+  outputFormIds: z.array(z.string()).optional(),
+  toolsAllowed: z.array(z.string()).optional(),
+  integrationConfig: z
+    .object({
+      method: z.enum(["GET", "POST", "PUT", "DELETE"]),
+      urlTemplate: z.string(),
+      headers: z.record(z.string(), z.string()),
+      bodyTemplate: z.string().optional(),
+    })
+    .optional(),
+});
+export type CreateStepRequest = z.infer<typeof createStepSchema>;
+
+export const updateStepSchema = z.object({
+  name: z.string().min(1).optional(),
+  description: z.string().optional(),
+  prompt: z.string().optional(),
+  type: z.enum(["single", "multi"]).optional(),
+  role: z.enum(["extraction", "integration", "analysis"]).nullable().optional(),
+  outputFormIds: z.array(z.string()).optional(),
+  toolsAllowed: z.array(z.string()).optional(),
+  integrationConfig: z
+    .object({
+      method: z.enum(["GET", "POST", "PUT", "DELETE"]),
+      urlTemplate: z.string(),
+      headers: z.record(z.string(), z.string()),
+      bodyTemplate: z.string().optional(),
+    })
+    .nullable()
+    .optional(),
+});
+export type UpdateStepRequest = z.infer<typeof updateStepSchema>;
+
+export const stepResponseSchema = z.object({
+  id: z.string(),
+});
+export type StepResponse = z.infer<typeof stepResponseSchema>;
+
+// Step Dependency Schemas
+export const addStepDependencySchema = z.object({
+  parentStepId: z.string().min(1, "Parent step ID is required"),
+  multiFormGroupId: z.string().optional().nullable(),
+});
+export type AddStepDependencyRequest = z.infer<typeof addStepDependencySchema>;
+
+export const stepDependencyResponseSchema = z.object({
+  id: z.string(),
+  childStepId: z.string(),
+  parentStepId: z.string(),
+  multiFormGroupId: z.string().nullable(),
+});
+export type StepDependencyResponse = z.infer<typeof stepDependencyResponseSchema>;
+
+// Manual Input Schemas
+export const addManualInputSchema = z.object({
+  submissionId: z.string().min(1, "Submission ID is required"),
+});
+export type AddManualInputRequest = z.infer<typeof addManualInputSchema>;
+
+export const manualInputResponseSchema = z.object({
+  runStepId: z.string(),
+  submissionId: z.string(),
+});
+export type ManualInputResponse = z.infer<typeof manualInputResponseSchema>;
+
+// Blocker Schemas
+export const blockerSchema = z.object({
+  id: z.string(),
+  blockerType: z.enum([
+    "missing_upload",
+    "parent_incomplete",
+    "missing_config",
+    "missing_manual_input",
+  ]),
+  blockerDetails: z.record(z.string(), z.unknown()),
+  resolved: z.boolean(),
+  resolvedAt: z.date().nullable(),
+  createdAt: z.date(),
+});
+export type BlockerResponse = z.infer<typeof blockerSchema>;
+
+export const stepBlockersSchema = z.object({
+  runStepId: z.string(),
+  stepName: z.string(),
+  stepOrder: z.number(),
+  blockers: z.array(blockerSchema),
+});
+export type StepBlockersResponse = z.infer<typeof stepBlockersSchema>;
+
+export const runBlockersResponseSchema = z.array(stepBlockersSchema);
+export type RunBlockersResponse = z.infer<typeof runBlockersResponseSchema>;
+
+// Citation Chain Schemas
+const citationNodeSchemaBase = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("document"),
+    documentCitationId: z.string(),
+    documentExtractionId: z.string(),
+    documentId: z.string(),
+    documentName: z.string(),
+    path: z.string(),
+    text: z.string(),
+    sourceRef: z.string(),
+  }),
+  z.object({
+    type: z.literal("integration"),
+    requestCallId: z.string(),
+    method: z.string(),
+    url: z.string(),
+    statusCode: z.number().nullable(),
+    durationMs: z.number().nullable(),
+  }),
+  z.object({
+    type: z.literal("manual"),
+    submissionItemVersionId: z.string(),
+    value: z.union([z.string(), z.number(), z.null()]),
+  }),
+]);
+
+export const citationNodeSchema: z.ZodType<CitationNodeResponse> = citationNodeSchemaBase.or(
+  z.object({
+    type: z.literal("transformation"),
+    submissionItemVersionId: z.string(),
+    sourceItemVersionIds: z.array(z.string()),
+    children: z.array(z.lazy(() => citationNodeSchema)),
+  }),
+);
+
+export type CitationNodeResponse =
+  | {
+      type: "document";
+      documentCitationId: string;
+      documentExtractionId: string;
+      documentId: string;
+      documentName: string;
+      path: string;
+      text: string;
+      sourceRef: string;
+    }
+  | {
+      type: "integration";
+      requestCallId: string;
+      method: string;
+      url: string;
+      statusCode: number | null;
+      durationMs: number | null;
+    }
+  | {
+      type: "transformation";
+      submissionItemVersionId: string;
+      sourceItemVersionIds: string[];
+      children: CitationNodeResponse[];
+    }
+  | {
+      type: "manual";
+      submissionItemVersionId: string;
+      value: string | number | null;
+    };
+
+export const citationChainResponseSchema = z.object({
+  chain: citationNodeSchema.nullable(),
+});
+export type CitationChainResponse = z.infer<typeof citationChainResponseSchema>;