@contractspec/example.saas-boilerplate 1.44.0

package/src/project/project.handler.ts

@@ -0,0 +1,168 @@
+/**
+ * Mock handlers for Project contracts.
+ */
+import { MOCK_PROJECTS } from '../shared/mock-data';
+
+// Types inferred from contract schemas
+export interface Project {
+  id: string;
+  name: string;
+  description?: string;
+  slug?: string;
+  organizationId: string;
+  createdBy: string;
+  status: 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'DELETED';
+  isPublic: boolean;
+  tags: string[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CreateProjectInput {
+  name: string;
+  description?: string;
+  slug?: string;
+  isPublic?: boolean;
+  tags?: string[];
+}
+
+export interface UpdateProjectInput {
+  projectId: string;
+  name?: string;
+  description?: string;
+  slug?: string;
+  isPublic?: boolean;
+  tags?: string[];
+  status?: 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'DELETED';
+}
+
+export interface ListProjectsInput {
+  status?: 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'all';
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListProjectsOutput {
+  projects: Project[];
+  total: number;
+}
+
+/**
+ * Mock handler for ListProjectsContract.
+ */
+export async function mockListProjectsHandler(
+  input: ListProjectsInput
+): Promise<ListProjectsOutput> {
+  const { status, search, limit = 20, offset = 0 } = input;
+
+  let filtered = [...MOCK_PROJECTS];
+
+  if (status && status !== 'all') {
+    filtered = filtered.filter((p) => p.status === status);
+  }
+
+  if (search) {
+    const q = search.toLowerCase();
+    filtered = filtered.filter(
+      (p) =>
+        p.name.toLowerCase().includes(q) ||
+        p.description?.toLowerCase().includes(q) ||
+        p.tags.some((t) => t.toLowerCase().includes(q))
+    );
+  }
+
+  filtered.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+
+  const total = filtered.length;
+  const projects = filtered.slice(offset, offset + limit);
+
+  return {
+    projects,
+    total,
+  };
+}
+
+/**
+ * Mock handler for GetProjectContract.
+ */
+export async function mockGetProjectHandler(input: {
+  projectId: string;
+}): Promise<Project> {
+  const project = MOCK_PROJECTS.find((p) => p.id === input.projectId);
+
+  if (!project) {
+    throw new Error('NOT_FOUND');
+  }
+
+  return project;
+}
+
+/**
+ * Mock handler for CreateProjectContract.
+ */
+export async function mockCreateProjectHandler(
+  input: CreateProjectInput,
+  context: { organizationId: string; userId: string }
+): Promise<Project> {
+  if (input.slug) {
+    const exists = MOCK_PROJECTS.some((p) => p.slug === input.slug);
+    if (exists) {
+      throw new Error('SLUG_EXISTS');
+    }
+  }
+
+  const now = new Date();
+  return {
+    id: `proj-${Date.now()}`,
+    name: input.name,
+    description: input.description,
+    slug: input.slug ?? input.name.toLowerCase().replace(/\s+/g, '-'),
+    organizationId: context.organizationId,
+    createdBy: context.userId,
+    status: 'DRAFT',
+    isPublic: input.isPublic ?? false,
+    tags: input.tags ?? [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * Mock handler for UpdateProjectContract.
+ */
+export async function mockUpdateProjectHandler(
+  input: UpdateProjectInput
+): Promise<Project> {
+  const project = MOCK_PROJECTS.find((p) => p.id === input.projectId);
+
+  if (!project) {
+    throw new Error('NOT_FOUND');
+  }
+
+  return {
+    ...project,
+    name: input.name ?? project.name,
+    description: input.description ?? project.description,
+    slug: input.slug ?? project.slug,
+    isPublic: input.isPublic ?? project.isPublic,
+    tags: input.tags ?? project.tags,
+    status: input.status ?? project.status,
+    updatedAt: new Date(),
+  };
+}
+
+/**
+ * Mock handler for DeleteProjectContract.
+ */
+export async function mockDeleteProjectHandler(input: {
+  projectId: string;
+}): Promise<{ success: boolean }> {
+  const project = MOCK_PROJECTS.find((p) => p.id === input.projectId);
+
+  if (!project) {
+    throw new Error('NOT_FOUND');
+  }
+
+  return { success: true };
+}

package/src/project/project.operations.ts

@@ -0,0 +1,272 @@
+import {
+  defineCommand,
+  defineQuery,
+} from '@contractspec/lib.contracts/operations';
+import {
+  CreateProjectInputModel,
+  DeleteProjectInputModel,
+  DeleteProjectOutputModel,
+  GetProjectInputModel,
+  ListProjectsInputModel,
+  ListProjectsOutputModel,
+  ProjectDeletedPayloadModel,
+  ProjectModel,
+  UpdateProjectInputModel,
+} from './project.schema';
+
+const OWNERS = ['example.saas-boilerplate'] as const;
+
+/**
+ * Create a new project.
+ */
+export const CreateProjectContract = defineCommand({
+  meta: {
+    key: 'saas.project.create',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'create'],
+    description: 'Create a new project in the organization.',
+    goal: 'Allow users to create projects for organizing work.',
+    context: 'Called from project creation UI or API.',
+  },
+  io: {
+    input: CreateProjectInputModel,
+    output: ProjectModel,
+    errors: {
+      SLUG_EXISTS: {
+        description: 'A project with this slug already exists',
+        http: 409,
+        gqlCode: 'SLUG_EXISTS',
+        when: 'Slug is already taken in the organization',
+      },
+      LIMIT_REACHED: {
+        description: 'Project limit reached for this plan',
+        http: 403,
+        gqlCode: 'LIMIT_REACHED',
+        when: 'Organization has reached project limit',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'project.created',
+        version: 1,
+        when: 'Project is created',
+        payload: ProjectModel,
+      },
+    ],
+    audit: ['project.created'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'create-project-happy-path',
+        given: ['User is authenticated'],
+        when: ['User creates project'],
+        then: ['Project is created', 'ProjectCreated event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'create-basic',
+        input: { name: 'Website Redesign', slug: 'website-redesign' },
+        output: { id: 'proj-123', name: 'Website Redesign', isArchived: false },
+      },
+    ],
+  },
+});
+
+/**
+ * Get project by ID.
+ */
+export const GetProjectContract = defineQuery({
+  meta: {
+    key: 'saas.project.get',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'get'],
+    description: 'Get a project by ID.',
+    goal: 'Retrieve project details.',
+    context: 'Project detail page, API calls.',
+  },
+  io: {
+    input: GetProjectInputModel,
+    output: ProjectModel,
+    errors: {
+      NOT_FOUND: {
+        description: 'Project not found',
+        http: 404,
+        gqlCode: 'NOT_FOUND',
+        when: 'Project ID is invalid or user lacks access',
+      },
+    },
+  },
+  policy: {
+    auth: 'user',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-project-happy-path',
+        given: ['Project exists'],
+        when: ['User requests project'],
+        then: ['Project details are returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-existing',
+        input: { projectId: 'proj-123' },
+        output: { id: 'proj-123', name: 'Website Redesign' },
+      },
+    ],
+  },
+});
+
+/**
+ * Update a project.
+ */
+export const UpdateProjectContract = defineCommand({
+  meta: {
+    key: 'saas.project.update',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'update'],
+    description: 'Update project details.',
+    goal: 'Allow project owners/editors to modify project.',
+    context: 'Project settings page.',
+  },
+  io: {
+    input: UpdateProjectInputModel,
+    output: ProjectModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'project.updated',
+        version: 1,
+        when: 'Project is updated',
+        payload: ProjectModel,
+      },
+    ],
+    audit: ['project.updated'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'update-project-happy-path',
+        given: ['Project exists'],
+        when: ['User updates description'],
+        then: ['Project is updated', 'ProjectUpdated event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'update-desc',
+        input: { projectId: 'proj-123', description: 'New description' },
+        output: { id: 'proj-123', description: 'New description' },
+      },
+    ],
+  },
+});
+
+/**
+ * Delete a project.
+ */
+export const DeleteProjectContract = defineCommand({
+  meta: {
+    key: 'saas.project.delete',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'delete'],
+    description: 'Delete a project (soft delete).',
+    goal: 'Allow project owners to remove projects.',
+    context: 'Project settings page.',
+  },
+  io: {
+    input: DeleteProjectInputModel,
+    output: DeleteProjectOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        key: 'project.deleted',
+        version: 1,
+        when: 'Project is deleted',
+        payload: ProjectDeletedPayloadModel,
+      },
+    ],
+    audit: ['project.deleted'],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'delete-project-happy-path',
+        given: ['Project exists'],
+        when: ['User deletes project'],
+        then: ['Project is deleted', 'ProjectDeleted event is emitted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'delete-existing',
+        input: { projectId: 'proj-123' },
+        output: { success: true },
+      },
+    ],
+  },
+});
+
+/**
+ * List organization projects.
+ */
+export const ListProjectsContract = defineQuery({
+  meta: {
+    key: 'saas.project.list',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'project', 'list'],
+    description: 'List projects in the organization.',
+    goal: 'Show all projects user has access to.',
+    context: 'Project list page, dashboard.',
+  },
+  io: {
+    input: ListProjectsInputModel,
+    output: ListProjectsOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'list-projects-happy-path',
+        given: ['Projects exist'],
+        when: ['User lists projects'],
+        then: ['List of projects is returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'list-all',
+        input: { limit: 10 },
+        output: { items: [], total: 5 },
+      },
+    ],
+  },
+});

package/src/project/project.presentation.ts

@@ -0,0 +1,59 @@
+import type { PresentationSpec } from '@contractspec/lib.contracts';
+import { StabilityEnum } from '@contractspec/lib.contracts';
+import { ProjectModel } from './project.schema';
+
+/**
+ * Presentation for displaying a list of projects.
+ */
+export const ProjectListPresentation: PresentationSpec = {
+  meta: {
+    key: 'saas.project.list',
+    version: 1,
+    title: 'Project List',
+    description:
+      'List view of projects with status, tags, and last updated info',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['project', 'list', 'dashboard'],
+    stability: StabilityEnum.Beta,
+    goal: 'Browse and manage projects',
+    context: 'Project list page',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ProjectListView',
+    props: ProjectModel,
+  },
+  targets: ['react', 'markdown', 'application/json'],
+  policy: {
+    flags: ['saas.projects.enabled'],
+  },
+};
+
+/**
+ * Presentation for project detail view.
+ */
+export const ProjectDetailPresentation: PresentationSpec = {
+  meta: {
+    key: 'saas.project.detail',
+    version: 1,
+    title: 'Project Details',
+    description: 'Detailed view of a project with settings and activity',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['project', 'detail'],
+    stability: StabilityEnum.Beta,
+    goal: 'View and edit project details',
+    context: 'Project detail page',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ProjectDetailView',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.projects.enabled'],
+  },
+};

package/src/project/project.schema.ts

@@ -0,0 +1,147 @@
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import {
+  ProjectStatusSchemaEnum,
+  ProjectStatusFilterEnum,
+} from './project.enum';
+
+/**
+ * A project within an organization.
+ */
+export const ProjectModel = defineSchemaModel({
+  name: 'Project',
+  description: 'A project within an organization',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    createdBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ProjectStatusSchemaEnum, isOptional: false },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: false,
+    },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Input for creating a project.
+ */
+export const CreateProjectInputModel = defineSchemaModel({
+  name: 'CreateProjectInput',
+  description: 'Input for creating a project',
+  fields: {
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+  },
+});
+
+/**
+ * Input for updating a project.
+ */
+export const UpdateProjectInputModel = defineSchemaModel({
+  name: 'UpdateProjectInput',
+  description: 'Input for updating a project',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    tags: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true,
+    },
+    status: { type: ProjectStatusSchemaEnum, isOptional: true },
+  },
+});
+
+/**
+ * Input for getting a project.
+ */
+export const GetProjectInputModel = defineSchemaModel({
+  name: 'GetProjectInput',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Input for deleting a project.
+ */
+export const DeleteProjectInputModel = defineSchemaModel({
+  name: 'DeleteProjectInput',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Output for delete operation.
+ */
+export const DeleteProjectOutputModel = defineSchemaModel({
+  name: 'DeleteProjectOutput',
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+  },
+});
+
+/**
+ * Payload for project deleted event.
+ */
+export const ProjectDeletedPayloadModel = defineSchemaModel({
+  name: 'ProjectDeletedPayload',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Input for listing projects.
+ */
+export const ListProjectsInputModel = defineSchemaModel({
+  name: 'ListProjectsInput',
+  description: 'Input for listing projects',
+  fields: {
+    status: { type: ProjectStatusFilterEnum, isOptional: true },
+    search: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    limit: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 20,
+    },
+    offset: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 0,
+    },
+  },
+});
+
+/**
+ * Output for listing projects.
+ */
+export const ListProjectsOutputModel = defineSchemaModel({
+  name: 'ListProjectsOutput',
+  description: 'Output for listing projects',
+  fields: {
+    projects: { type: ProjectModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+  },
+});