@critical-path/core 0.23.0 → 0.24.0

package/src/schemas/index.ts

@@ -0,0 +1,337 @@
+/**
+ * Request payload schemas for Critical Path resources.
+ *
+ * Exposed from `@critical-path/core/schemas` (not the package root) so browser bundles of core do
+ * not pull in zod. Create schemas omit server-assigned fields (`id`, `createdAt`, `updatedAt`, task
+ * `key`); update schemas additionally make every field optional and omit the owning `projectId`.
+ * Unknown keys are stripped rather than rejected, so older clients that send whole objects keep
+ * working while protected fields are never written.
+ */
+import { z } from 'zod';
+import { ValidationError, type ValidationIssue } from '../domain/errors.js';
+
+/**
+ * Parses `data` with `schema`, returning the cleaned value (unknown keys stripped, defaults
+ * applied) or throwing a `ValidationError` whose `issues` list every problem.
+ */
+export function parsePayload<S extends z.ZodTypeAny>(schema: S, data: unknown): z.output<S> {
+  const result = schema.safeParse(data ?? {});
+  if (result.success) return result.data;
+  const issues: ValidationIssue[] = result.error.issues.map((issue) => ({
+    path: issue.path.join('.'),
+    message: issue.message
+  }));
+  const summary = issues.map((i) => (i.path ? `${i.path}: ${i.message}` : i.message)).join('; ');
+  throw new ValidationError(`Invalid request body: ${summary}`, issues);
+}
+
+const isoString = z.string();
+const nonEmpty = z.string().min(1);
+
+export const SemanticStatusSchema = z.enum(['not_started', 'in_progress', 'completed', 'canceled']);
+export const AuthorTypeSchema = z.enum(['user', 'agent', 'system']);
+
+export const StatusDefinitionSchema = z.object({
+  key: nonEmpty,
+  label: z.string(),
+  category: SemanticStatusSchema
+});
+
+export const WorkScheduleSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  timezone: z.string().optional(),
+  defaultHoursPerDay: z.number().nonnegative().optional(),
+  days: z.array(
+    z.object({
+      dayOfWeek: z.number().int().min(0).max(6),
+      isWorkingDay: z.boolean(),
+      hours: z.array(z.object({ start: z.string(), end: z.string() })).optional()
+    })
+  ),
+  holidays: z
+    .array(z.object({ date: z.string(), name: z.string().optional(), halfDay: z.boolean().optional() }))
+    .optional()
+});
+
+export const CustomFieldDefinitionSchema = z.object({
+  id: z.string(),
+  key: nonEmpty,
+  label: z.string(),
+  type: z.enum(['text', 'number', 'date', 'boolean', 'single_select', 'multi_select', 'user']),
+  options: z.array(z.string()).optional(),
+  required: z.boolean().optional(),
+  defaultValue: z.unknown().optional()
+});
+
+export const TaskTypeDefinitionSchema = z.object({
+  key: nonEmpty,
+  label: z.string(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  defaultStatusKey: z.string().optional(),
+  workflowId: z.string().optional()
+});
+
+const customFields = z.record(z.unknown());
+const metadata = z.record(z.unknown());
+
+// --- Workflows ---
+
+export const CreateWorkflowSchema = z.object({
+  name: nonEmpty,
+  description: z.string().optional(),
+  statuses: z.array(StatusDefinitionSchema),
+  transitions: z
+    .array(
+      z.object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        fromStatusKey: z.string(),
+        toStatusKey: z.string()
+      })
+    )
+    .default([]),
+  taskTypes: z.array(TaskTypeDefinitionSchema).optional(),
+  defaultStatusKey: z.string().optional(),
+  isDefault: z.boolean().optional()
+});
+export const UpdateWorkflowSchema = CreateWorkflowSchema.partial();
+
+// --- Projects ---
+
+export const CreateProjectSchema = z.object({
+  key: z.string().optional(),
+  name: nonEmpty,
+  description: z.string().optional(),
+  ownerId: z.string().optional(),
+  members: z.array(z.string()).optional(),
+  teamIds: z.array(z.string()).optional(),
+  workflowId: z.string().optional(),
+  taskTypes: z.array(TaskTypeDefinitionSchema).optional(),
+  statusDefinitions: z.array(StatusDefinitionSchema).optional(),
+  priorityDefinitions: z
+    .array(z.object({ key: z.string(), label: z.string(), level: z.number().optional() }))
+    .optional(),
+  customFieldDefinitions: z.array(CustomFieldDefinitionSchema).optional(),
+  schedule: WorkScheduleSchema.optional(),
+  startDate: isoString.optional(),
+  targetEndDate: isoString.optional()
+});
+export const UpdateProjectSchema = CreateProjectSchema.partial();
+
+// --- Tasks ---
+
+const taskFields = {
+  title: nonEmpty,
+  description: z.string().optional(),
+  status: z.string().optional(),
+  semanticStatus: SemanticStatusSchema.optional(),
+  priority: z.string().optional(),
+  taskType: z.string().optional(),
+  assigneeId: z.string().optional(),
+  assignees: z
+    .array(
+      z.object({
+        id: z.string(),
+        name: z.string().optional(),
+        role: z.string().optional(),
+        type: z.enum(['user', 'agent', 'team']).optional(),
+        avatarUrl: z.string().optional()
+      })
+    )
+    .optional(),
+  reporterId: z.string().optional(),
+  reviewerId: z.string().optional(),
+  iterationId: z.string().optional(),
+  teamId: z.string().optional(),
+  containerId: z.string().optional(),
+  deliverableId: z.string().optional(),
+  plannedStartDate: isoString.optional(),
+  actualStartDate: isoString.optional(),
+  actualEndDate: isoString.optional(),
+  completedAt: isoString.optional(),
+  dueDate: isoString.optional(),
+  estimatedHours: z.number().nonnegative().optional(),
+  loggedHours: z.number().nonnegative().optional(),
+  actualHours: z.number().nonnegative().optional(),
+  billableHours: z.number().nonnegative().optional(),
+  estimatedDurationMinutes: z.number().nonnegative().optional(),
+  actualDurationMinutes: z.number().nonnegative().optional(),
+  billableDurationMinutes: z.number().nonnegative().optional(),
+  actualDurationSeconds: z.number().nonnegative().optional(),
+  inProgressSince: isoString.nullable().optional(),
+  blockedDurationSeconds: z.number().nonnegative().optional(),
+  blockedSince: isoString.nullable().optional(),
+  progress: z.number().min(0).max(100).optional(),
+  isBlocked: z.boolean().optional(),
+  blockedReason: z.string().nullable().optional(),
+  tags: z.array(z.string()).optional(),
+  todos: z
+    .array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        completed: z.boolean(),
+        createdAt: isoString.optional(),
+        completedAt: isoString.optional()
+      })
+    )
+    .optional(),
+  customFields: customFields.optional(),
+  parentId: z.string().optional()
+};
+
+export const CreateTaskSchema = z.object({ projectId: nonEmpty, ...taskFields });
+
+/** Actor fields accepted on task updates; ignored when the server resolves the caller. */
+const actorClaimFields = {
+  actorId: z.string().optional(),
+  actorName: z.string().optional(),
+  actorType: z.string().optional(),
+  actor: z
+    .object({ userId: z.string(), username: z.string().optional(), actorType: z.string().optional() })
+    .optional()
+};
+
+export const UpdateTaskSchema = z.object(taskFields).partial().extend(actorClaimFields);
+
+// --- Dependencies ---
+
+export const CreateDependencySchema = z.object({
+  dependsOnTaskId: nonEmpty,
+  type: z.enum(['blocking', 'blocked_by', 'relates_to']).default('blocking')
+});
+
+// --- Deliverables ---
+
+const deliverableFields = {
+  title: nonEmpty,
+  description: z.string().optional(),
+  status: z.string().optional(),
+  format: z.string().optional(),
+  specs: z.record(z.unknown()).optional(),
+  leadId: z.string().optional(),
+  reviewerId: z.string().optional(),
+  dueDate: isoString.optional(),
+  deliveredAt: isoString.optional(),
+  outputUrls: z.array(z.string()).optional(),
+  customFields: customFields.optional()
+};
+export const CreateDeliverableSchema = z.object({ projectId: nonEmpty, ...deliverableFields });
+export const UpdateDeliverableSchema = z.object(deliverableFields).partial();
+
+// --- Teams ---
+
+export const CreateTeamSchema = z.object({
+  name: nonEmpty,
+  description: z.string().optional(),
+  leaderId: z.string().optional(),
+  memberIds: z.array(z.string()).default([]),
+  weeklyCapacityHours: z.number().nonnegative().optional(),
+  schedule: WorkScheduleSchema.optional()
+});
+export const UpdateTeamSchema = CreateTeamSchema.partial();
+
+// --- Containers ---
+
+const containerFields = {
+  name: nonEmpty,
+  description: z.string().optional(),
+  parentId: z.string().optional(),
+  type: z.string().optional(),
+  color: z.string().optional()
+};
+export const CreateContainerSchema = z.object({ projectId: nonEmpty, ...containerFields });
+export const UpdateContainerSchema = z.object(containerFields).partial();
+
+// --- Iterations ---
+
+const iterationFields = {
+  name: nonEmpty,
+  goal: z.string().optional(),
+  type: z.string().optional(),
+  startDate: isoString.optional(),
+  endDate: isoString.optional(),
+  status: z.enum(['planning', 'active', 'completed']).default('planning')
+};
+export const CreateIterationSchema = z.object({ projectId: nonEmpty, ...iterationFields });
+export const UpdateIterationSchema = z
+  .object({ ...iterationFields, status: z.enum(['planning', 'active', 'completed']) })
+  .partial();
+
+// --- Comments & Reactions ---
+
+export const CreateCommentSchema = z.object({
+  taskId: nonEmpty,
+  /** Required unless the server resolves the caller, in which case it is replaced. */
+  authorId: z.string().optional(),
+  authorType: AuthorTypeSchema.optional(),
+  parentId: z.string().optional(),
+  content: nonEmpty,
+  mentions: z.array(z.string()).optional(),
+  metadata: metadata.optional()
+});
+export const UpdateCommentSchema = z
+  .object({ content: nonEmpty, mentions: z.array(z.string()), metadata })
+  .partial();
+
+export const CommentReactionSchema = z.object({
+  emoji: nonEmpty,
+  /** Required unless the server resolves the caller, in which case it is replaced. */
+  userId: z.string().optional()
+});
+
+// --- Attachments ---
+
+const attachmentLinks = {
+  taskId: z.string().optional(),
+  projectId: z.string().optional(),
+  commentId: z.string().optional(),
+  /** Required unless the server resolves the caller, in which case it is replaced. */
+  uploaderId: z.string().optional(),
+  uploaderType: AuthorTypeSchema.optional(),
+  artifactType: z.enum(['plan', 'spec', 'deliverable', 'review', 'general']).optional(),
+  metadata: metadata.optional()
+};
+
+export const CreateAttachmentSchema = z.object({
+  ...attachmentLinks,
+  filename: nonEmpty,
+  // Linked (rather than uploaded) files often have no known type or size.
+  mimeType: nonEmpty.default('application/octet-stream'),
+  sizeBytes: z.number().int().nonnegative().default(0),
+  url: nonEmpty,
+  storageKey: z.string().optional()
+});
+
+export const UploadAttachmentSchema = z.object({
+  ...attachmentLinks,
+  filename: nonEmpty,
+  data: z.string(),
+  mimeType: z.string().optional(),
+  pathPrefix: z.string().optional(),
+  encoding: z.enum(['base64', 'utf-8', 'binary']).optional()
+});
+
+export const PresignAttachmentSchema = z.object({
+  storageKey: nonEmpty,
+  expiresInSeconds: z.number().int().positive().optional(),
+  contentType: z.string().optional()
+});
+
+// --- Time Tracking ---
+
+export const LogTimeSchema = z.object({
+  taskId: nonEmpty,
+  hours: z.number().positive(),
+  isBillable: z.boolean().optional(),
+  description: z.string().optional(),
+  userId: z.string().optional(),
+  loggedAt: isoString.optional()
+});
+
+export type CreateTaskPayload = z.infer<typeof CreateTaskSchema>;
+export type UpdateTaskPayload = z.infer<typeof UpdateTaskSchema>;
+export type CreateProjectPayload = z.infer<typeof CreateProjectSchema>;
+export type UpdateProjectPayload = z.infer<typeof UpdateProjectSchema>;

package/src/schemas/schemas.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import type { z } from 'zod';
+import type {
+  CreateTaskInput,
+  Task,
+  CreateProjectInput,
+  Project,
+  Workflow,
+  CreateDeliverableInput,
+  Deliverable,
+  Team,
+  TaskContainer,
+  Iteration,
+  Comment,
+  CreateAttachmentInput,
+  TimeEntry
+} from '../types/index.js';
+import {
+  CreateTaskSchema,
+  UpdateTaskSchema,
+  CreateProjectSchema,
+  UpdateProjectSchema,
+  CreateWorkflowSchema,
+  CreateDeliverableSchema,
+  UpdateDeliverableSchema,
+  CreateTeamSchema,
+  CreateContainerSchema,
+  UpdateContainerSchema,
+  CreateIterationSchema,
+  CreateCommentSchema,
+  UpdateCommentSchema,
+  CreateAttachmentSchema,
+  LogTimeSchema
+} from './index.js';
+
+/**
+ * Compile-time check that a schema covers exactly the writable keys of a domain type. If a field
+ * is added to a type in `types/index.ts` but not to its schema, the build fails here instead of
+ * the field being silently stripped from API requests.
+ */
+type SameKeys<Schema, Expected> = [Exclude<keyof Schema, keyof Expected>, Exclude<keyof Expected, keyof Schema>] extends [
+  never,
+  never
+]
+  ? true
+  : { extraInSchema: Exclude<keyof Schema, keyof Expected>; missingFromSchema: Exclude<keyof Expected, keyof Schema> };
+
+type Infer<S extends z.ZodTypeAny> = z.infer<S>;
+type ServerAssigned = 'id' | 'createdAt' | 'updatedAt';
+type ActorClaims = 'actorId' | 'actorName' | 'actorType' | 'actor';
+
+const keyChecks: true[] = [
+  true as SameKeys<Infer<typeof CreateTaskSchema>, Omit<CreateTaskInput, 'key'>>,
+  true as SameKeys<Omit<Infer<typeof UpdateTaskSchema>, ActorClaims>, Omit<Task, ServerAssigned | 'key' | 'projectId'>>,
+  // `workflow` is a denormalised copy resolved from `workflowId`, so it is not writable.
+  true as SameKeys<Infer<typeof CreateProjectSchema>, Omit<CreateProjectInput, 'workflow'>>,
+  true as SameKeys<Infer<typeof UpdateProjectSchema>, Omit<Project, ServerAssigned | 'workflow'>>,
+  true as SameKeys<Infer<typeof CreateWorkflowSchema>, Omit<Workflow, ServerAssigned>>,
+  true as SameKeys<Infer<typeof CreateDeliverableSchema>, CreateDeliverableInput>,
+  true as SameKeys<Infer<typeof UpdateDeliverableSchema>, Omit<Deliverable, ServerAssigned | 'projectId'>>,
+  true as SameKeys<Infer<typeof CreateTeamSchema>, Omit<Team, ServerAssigned>>,
+  true as SameKeys<Infer<typeof CreateContainerSchema>, Omit<TaskContainer, ServerAssigned>>,
+  true as SameKeys<Infer<typeof UpdateContainerSchema>, Omit<TaskContainer, ServerAssigned | 'projectId'>>,
+  true as SameKeys<Infer<typeof CreateIterationSchema>, Omit<Iteration, 'id' | 'createdAt'>>,
+  // Reactions are managed through the reactions endpoints.
+  true as SameKeys<Infer<typeof CreateCommentSchema>, Omit<Comment, ServerAssigned | 'reactions'>>,
+  true as SameKeys<Infer<typeof UpdateCommentSchema>, Pick<Comment, 'content' | 'mentions' | 'metadata'>>,
+  true as SameKeys<Infer<typeof CreateAttachmentSchema>, CreateAttachmentInput>,
+  true as SameKeys<Infer<typeof LogTimeSchema>, Omit<TimeEntry, 'id'>>
+];
+
+describe('request schemas', () => {
+  it('cover the writable fields of each domain type', () => {
+    expect(keyChecks.every(Boolean)).toBe(true);
+  });
+
+  it('strip server-assigned and unknown fields', () => {
+    const parsed = UpdateTaskSchema.parse({
+      title: 'ok',
+      id: 'hijack',
+      projectId: 'other',
+      createdAt: '1999-01-01',
+      key: 'X-1',
+      junk: true
+    });
+    expect(parsed).toEqual({ title: 'ok' });
+  });
+
+  it('reject wrong types and out-of-range values', () => {
+    expect(UpdateTaskSchema.safeParse({ status: 123 }).success).toBe(false);
+    expect(UpdateTaskSchema.safeParse({ progress: 140 }).success).toBe(false);
+    expect(CreateTaskSchema.safeParse({ projectId: 'p1' }).success).toBe(false);
+    expect(LogTimeSchema.safeParse({ taskId: 't1', hours: 0 }).success).toBe(false);
+  });
+
+  it('apply defaults for optional collections and enums', () => {
+    expect(CreateTeamSchema.parse({ name: 'Core' }).memberIds).toEqual([]);
+    expect(CreateIterationSchema.parse({ projectId: 'p1', name: 'S1' }).status).toBe('planning');
+    expect(CreateWorkflowSchema.parse({ name: 'W', statuses: [] }).transitions).toEqual([]);
+  });
+
+  it('keep lifecycle fields writable for imports and backfills', () => {
+    const parsed = CreateTaskSchema.parse({
+      projectId: 'p1',
+      title: 'Imported',
+      completedAt: '2026-01-02T00:00:00.000Z',
+      actualStartDate: '2026-01-01T00:00:00.000Z'
+    });
+    expect(parsed.completedAt).toBe('2026-01-02T00:00:00.000Z');
+  });
+});

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/errors.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/actor.test.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/fractional-index.test.ts","./src/utils/fractional-index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}
+{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/errors.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/actor.test.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/schemas/index.ts","./src/schemas/schemas.test.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/fractional-index.test.ts","./src/utils/fractional-index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}