@lssm/example.saas-boilerplate 0.0.0-canary-20251215234153 → 0.0.0-canary-20251216023757

package/src/project/project.contracts.ts

@@ -0,0 +1,185 @@
+import { defineCommand, defineQuery } from '@lssm/lib.contracts/spec';
+import {
+  ProjectModel,
+  CreateProjectInputModel,
+  UpdateProjectInputModel,
+  GetProjectInputModel,
+  DeleteProjectInputModel,
+  DeleteProjectOutputModel,
+  ProjectDeletedPayloadModel,
+  ListProjectsInputModel,
+  ListProjectsOutputModel,
+} from './project.schema';
+
+const OWNERS = ['example.saas-boilerplate'] as const;
+
+/**
+ * Create a new project.
+ */
+export const CreateProjectContract = defineCommand({
+  meta: {
+    name: '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: [
+      {
+        name: 'project.created',
+        version: 1,
+        when: 'Project is created',
+        payload: ProjectModel,
+      },
+    ],
+    audit: ['project.created'],
+  },
+});
+
+/**
+ * Get project by ID.
+ */
+export const GetProjectContract = defineQuery({
+  meta: {
+    name: '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',
+  },
+});
+
+/**
+ * Update a project.
+ */
+export const UpdateProjectContract = defineCommand({
+  meta: {
+    name: '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: [
+      {
+        name: 'project.updated',
+        version: 1,
+        when: 'Project is updated',
+        payload: ProjectModel,
+      },
+    ],
+    audit: ['project.updated'],
+  },
+});
+
+/**
+ * Delete a project.
+ */
+export const DeleteProjectContract = defineCommand({
+  meta: {
+    name: '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: [
+      {
+        name: 'project.deleted',
+        version: 1,
+        when: 'Project is deleted',
+        payload: ProjectDeletedPayloadModel,
+      },
+    ],
+    audit: ['project.deleted'],
+  },
+});
+
+/**
+ * List organization projects.
+ */
+export const ListProjectsContract = defineQuery({
+  meta: {
+    name: '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',
+  },
+});
+

package/src/{entities/project.ts → project/project.entity.ts}

@@ -1,7 +1,7 @@
 import { defineEntity, defineEntityEnum, field, index } from '@lssm/lib.schema';
 
 /**
- * Project status enum.
+ * Project status enum for entities.
  */
 export const ProjectStatusEnum = defineEntityEnum({
   name: 'ProjectStatus',
@@ -86,3 +86,4 @@ export const ProjectMemberEntity = defineEntity({
   },
   indexes: [index.unique(['projectId', 'userId'])],
 });
+

package/src/project/project.enum.ts

@@ -0,0 +1,23 @@
+import { defineEnum } from '@lssm/lib.schema';
+
+/**
+ * Project status enum for contract schemas.
+ * Note: Entity enum is defined separately in project.entity.ts
+ */
+export const ProjectStatusSchemaEnum = defineEnum('ProjectStatus', [
+  'DRAFT',
+  'ACTIVE',
+  'ARCHIVED',
+  'DELETED',
+]);
+
+/**
+ * Project status filter enum (includes 'all' option).
+ */
+export const ProjectStatusFilterEnum = defineEnum('ProjectStatusFilter', [
+  'DRAFT',
+  'ACTIVE',
+  'ARCHIVED',
+  'all',
+]);
+

package/src/project/project.event.ts

@@ -0,0 +1,109 @@
+import { ScalarTypeEnum, defineSchemaModel } from '@lssm/lib.schema';
+import { defineEvent } from '@lssm/lib.contracts';
+
+/**
+ * Payload when a project is created.
+ */
+const ProjectCreatedPayload = defineSchemaModel({
+  name: 'ProjectCreatedPayload',
+  description: 'Payload when a project is created',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    createdBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Payload when a project is updated.
+ */
+const ProjectUpdatedPayload = defineSchemaModel({
+  name: 'ProjectUpdatedPayload',
+  description: 'Payload when a project is updated',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    updatedFields: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: false,
+    },
+    updatedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Payload when a project is deleted.
+ */
+const ProjectDeletedPayload = defineSchemaModel({
+  name: 'ProjectDeletedPayload',
+  description: 'Payload when a project is deleted',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    deletedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    deletedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Payload when a project is archived.
+ */
+const ProjectArchivedPayload = defineSchemaModel({
+  name: 'ProjectArchivedPayload',
+  description: 'Payload when a project is archived',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    archivedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    archivedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+/**
+ * Event: A new project has been created.
+ */
+export const ProjectCreatedEvent = defineEvent({
+  name: 'project.created',
+  version: 1,
+  description: 'A new project has been created.',
+  payload: ProjectCreatedPayload,
+});
+
+/**
+ * Event: A project has been updated.
+ */
+export const ProjectUpdatedEvent = defineEvent({
+  name: 'project.updated',
+  version: 1,
+  description: 'A project has been updated.',
+  payload: ProjectUpdatedPayload,
+});
+
+/**
+ * Event: A project has been deleted.
+ */
+export const ProjectDeletedEvent = defineEvent({
+  name: 'project.deleted',
+  version: 1,
+  description: 'A project has been deleted.',
+  payload: ProjectDeletedPayload,
+});
+
+/**
+ * Event: A project has been archived.
+ */
+export const ProjectArchivedEvent = defineEvent({
+  name: 'project.archived',
+  version: 1,
+  description: 'A project has been archived.',
+  payload: ProjectArchivedPayload,
+});
+

package/src/{handlers/project.handlers.ts → project/project.handler.ts}

@@ -1,7 +1,7 @@
 /**
- * Mock handlers for Project contracts
+ * Mock handlers for Project contracts.
  */
-import { MOCK_PROJECTS } from './mock-data';
+import { MOCK_PROJECTS } from '../shared/mock-data';
 
 // Types inferred from contract schemas
 export interface Project {
@@ -49,7 +49,7 @@ export interface ListProjectsOutput {
 }
 
 /**
- * Mock handler for ListProjectsContract
+ * Mock handler for ListProjectsContract.
  */
 export async function mockListProjectsHandler(
   input: ListProjectsInput
@@ -72,7 +72,6 @@ export async function mockListProjectsHandler(
     );
   }
 
-  // Sort by updatedAt descending
   filtered.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
 
   const total = filtered.length;
@@ -85,7 +84,7 @@ export async function mockListProjectsHandler(
 }
 
 /**
- * Mock handler for GetProjectContract
+ * Mock handler for GetProjectContract.
  */
 export async function mockGetProjectHandler(input: {
   projectId: string;
@@ -100,13 +99,12 @@ export async function mockGetProjectHandler(input: {
 }
 
 /**
- * Mock handler for CreateProjectContract
+ * Mock handler for CreateProjectContract.
  */
 export async function mockCreateProjectHandler(
   input: CreateProjectInput,
   context: { organizationId: string; userId: string }
 ): Promise<Project> {
-  // Simulate slug collision check
   if (input.slug) {
     const exists = MOCK_PROJECTS.some((p) => p.slug === input.slug);
     if (exists) {
@@ -131,7 +129,7 @@ export async function mockCreateProjectHandler(
 }
 
 /**
- * Mock handler for UpdateProjectContract
+ * Mock handler for UpdateProjectContract.
  */
 export async function mockUpdateProjectHandler(
   input: UpdateProjectInput
@@ -155,7 +153,7 @@ export async function mockUpdateProjectHandler(
 }
 
 /**
- * Mock handler for DeleteProjectContract
+ * Mock handler for DeleteProjectContract.
  */
 export async function mockDeleteProjectHandler(input: {
   projectId: string;
@@ -168,3 +166,4 @@ export async function mockDeleteProjectHandler(input: {
 
   return { success: true };
 }
+

package/src/{presentations/project-list.ts → project/project.presentation.ts}

@@ -1,8 +1,5 @@
-/**
- * Project List Presentation Descriptor
- */
 import type { PresentationDescriptorV2 } from '@lssm/lib.contracts';
-import { ProjectModel } from '../contracts/project';
+import { ProjectModel } from './project.schema';
 
 /**
  * Presentation for displaying a list of projects.
@@ -51,3 +48,4 @@ export const ProjectDetailPresentation: PresentationDescriptorV2 = {
     flags: ['saas.projects.enabled'],
   },
 };
+

package/src/project/project.schema.ts

@@ -0,0 +1,145 @@
+import { defineSchemaModel, ScalarTypeEnum } from '@lssm/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 },
+  },
+});
+

package/src/settings/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Settings domain - application, organization, and user settings.
+ */
+
+// Enums
+export { SettingsScopeEnum } from './settings.enum';
+
+// Entities
+export { SettingsEntity, FeatureFlagEntity } from './settings.entity';
+

package/src/{entities/settings.ts → settings/settings.entity.ts}

@@ -1,14 +1,5 @@
-import { defineEntity, defineEntityEnum, field, index } from '@lssm/lib.schema';
-
-/**
- * Settings scope enum.
- */
-export const SettingsScopeEnum = defineEntityEnum({
-  name: 'SettingsScope',
-  values: ['APP', 'ORG', 'USER', 'PROJECT'] as const,
-  schema: 'saas_app',
-  description: 'Scope of a setting.',
-});
+import { defineEntity, field, index } from '@lssm/lib.schema';
+import { SettingsScopeEnum } from './settings.enum';
 
 /**
  * Settings entity - key-value configuration store.
@@ -96,3 +87,4 @@ export const FeatureFlagEntity = defineEntity({
     updatedAt: field.updatedAt(),
   },
 });
+

package/src/settings/settings.enum.ts

@@ -0,0 +1,12 @@
+import { defineEntityEnum } from '@lssm/lib.schema';
+
+/**
+ * Settings scope enum.
+ */
+export const SettingsScopeEnum = defineEntityEnum({
+  name: 'SettingsScope',
+  values: ['APP', 'ORG', 'USER', 'PROJECT'] as const,
+  schema: 'saas_app',
+  description: 'Scope of a setting.',
+});
+

package/src/{handlers → shared}/mock-data.ts

@@ -1,5 +1,5 @@
 /**
- * Mock data for saas-boilerplate handlers
+ * Shared mock data for saas-boilerplate handlers.
  */
 
 // ============ Project Mock Data ============
@@ -108,3 +108,4 @@ export const MOCK_USAGE_SUMMARY = {
     { date: '2024-04-05', apiCalls: 3800, storageGb: 12.5 },
   ],
 };
+