@lssm/example.saas-boilerplate 0.0.0-canary-20251206160926

package/src/handlers/billing.handlers.ts

@@ -0,0 +1,139 @@
+/**
+ * Mock handlers for Billing contracts
+ */
+import { MOCK_SUBSCRIPTION, MOCK_USAGE_SUMMARY } from './mock-data';
+
+// Types inferred from contract schemas
+export interface Subscription {
+  id: string;
+  organizationId: string;
+  planId: string;
+  planName: string;
+  status: 'ACTIVE' | 'TRIALING' | 'PAST_DUE' | 'CANCELED' | 'UNPAID';
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+  limits: {
+    projects: number;
+    users: number;
+    storage: number;
+    apiCalls: number;
+  };
+  usage: {
+    projects: number;
+    users: number;
+    storage: number;
+    apiCalls: number;
+  };
+}
+
+export interface UsageSummary {
+  organizationId: string;
+  period: string;
+  apiCalls: {
+    total: number;
+    limit: number;
+    percentUsed: number;
+  };
+  storage: {
+    totalGb: number;
+    limitGb: number;
+    percentUsed: number;
+  };
+  activeProjects: number;
+  activeUsers: number;
+  breakdown: {
+    date: string;
+    apiCalls: number;
+    storageGb: number;
+  }[];
+}
+
+export interface RecordUsageInput {
+  metric: string;
+  quantity: number;
+  timestamp?: Date;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CheckFeatureAccessInput {
+  feature: string;
+}
+
+export interface CheckFeatureAccessOutput {
+  allowed: boolean;
+  reason?:
+    | 'PLAN_LIMIT'
+    | 'FEATURE_NOT_INCLUDED'
+    | 'QUOTA_EXCEEDED'
+    | 'SUBSCRIPTION_INACTIVE';
+  currentUsage?: number;
+  limit?: number;
+}
+
+/**
+ * Mock handler for GetSubscriptionContract
+ */
+export async function mockGetSubscriptionHandler(): Promise<Subscription> {
+  return MOCK_SUBSCRIPTION;
+}
+
+/**
+ * Mock handler for GetUsageSummaryContract
+ */
+export async function mockGetUsageSummaryHandler(input: {
+  period?: string;
+}): Promise<UsageSummary> {
+  return {
+    ...MOCK_USAGE_SUMMARY,
+    period: input.period ?? 'current_month',
+  };
+}
+
+/**
+ * Mock handler for RecordUsageContract
+ */
+export async function mockRecordUsageHandler(
+  input: RecordUsageInput
+): Promise<{ recorded: boolean; newTotal: number }> {
+  // Simulate recording usage
+  const currentUsage = MOCK_USAGE_SUMMARY.apiCalls.total;
+  const newTotal = currentUsage + input.quantity;
+
+  return {
+    recorded: true,
+    newTotal,
+  };
+}
+
+/**
+ * Mock handler for CheckFeatureAccessContract
+ */
+export async function mockCheckFeatureAccessHandler(
+  input: CheckFeatureAccessInput
+): Promise<CheckFeatureAccessOutput> {
+  const { feature } = input;
+
+  // Simulate feature access checks
+  const featureMap: Record<string, CheckFeatureAccessOutput> = {
+    custom_domains: {
+      allowed: true,
+    },
+    api_access: {
+      allowed: true,
+      currentUsage: MOCK_USAGE_SUMMARY.apiCalls.total,
+      limit: MOCK_USAGE_SUMMARY.apiCalls.limit,
+    },
+    advanced_analytics: {
+      allowed: false,
+      reason: 'FEATURE_NOT_INCLUDED',
+    },
+    unlimited_projects: {
+      allowed: false,
+      reason: 'PLAN_LIMIT',
+      currentUsage: MOCK_SUBSCRIPTION.usage.projects,
+      limit: MOCK_SUBSCRIPTION.limits.projects,
+    },
+  };
+
+  return featureMap[feature] ?? { allowed: true };
+}

package/src/handlers/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Mock handlers for saas-boilerplate example
+ *
+ * These handlers provide mock implementations of all contracts
+ * for use in demos, tests, and the sandbox environment.
+ */
+
+// Mock data
+export * from './mock-data';
+
+// Project handlers
+export {
+  mockListProjectsHandler,
+  mockGetProjectHandler,
+  mockCreateProjectHandler,
+  mockUpdateProjectHandler,
+  mockDeleteProjectHandler,
+  type Project,
+  type CreateProjectInput,
+  type UpdateProjectInput,
+  type ListProjectsInput,
+  type ListProjectsOutput,
+} from './project.handlers';
+
+// Billing handlers
+export {
+  mockGetSubscriptionHandler,
+  mockGetUsageSummaryHandler,
+  mockRecordUsageHandler,
+  mockCheckFeatureAccessHandler,
+  type Subscription,
+  type UsageSummary,
+  type RecordUsageInput,
+  type CheckFeatureAccessInput,
+  type CheckFeatureAccessOutput,
+} from './billing.handlers';

package/src/handlers/mock-data.ts

@@ -0,0 +1,110 @@
+/**
+ * Mock data for saas-boilerplate handlers
+ */
+
+// ============ Project Mock Data ============
+
+export const MOCK_PROJECTS = [
+  {
+    id: 'proj-1',
+    name: 'Marketing Website',
+    description: 'Main company website redesign project',
+    slug: 'marketing-website',
+    organizationId: 'demo-org',
+    createdBy: 'user-1',
+    status: 'ACTIVE' as const,
+    isPublic: false,
+    tags: ['marketing', 'website', 'redesign'],
+    createdAt: new Date('2024-01-15T10:00:00Z'),
+    updatedAt: new Date('2024-03-20T14:30:00Z'),
+  },
+  {
+    id: 'proj-2',
+    name: 'Mobile App v2',
+    description: 'Next generation mobile application',
+    slug: 'mobile-app-v2',
+    organizationId: 'demo-org',
+    createdBy: 'user-2',
+    status: 'ACTIVE' as const,
+    isPublic: false,
+    tags: ['mobile', 'app', 'v2'],
+    createdAt: new Date('2024-02-01T09:00:00Z'),
+    updatedAt: new Date('2024-04-05T11:15:00Z'),
+  },
+  {
+    id: 'proj-3',
+    name: 'API Integration',
+    description: 'Third-party API integration project',
+    slug: 'api-integration',
+    organizationId: 'demo-org',
+    createdBy: 'user-1',
+    status: 'DRAFT' as const,
+    isPublic: false,
+    tags: ['api', 'integration'],
+    createdAt: new Date('2024-03-10T08:00:00Z'),
+    updatedAt: new Date('2024-03-10T08:00:00Z'),
+  },
+  {
+    id: 'proj-4',
+    name: 'Analytics Dashboard',
+    description: 'Internal analytics and reporting dashboard',
+    slug: 'analytics-dashboard',
+    organizationId: 'demo-org',
+    createdBy: 'user-3',
+    status: 'ARCHIVED' as const,
+    isPublic: true,
+    tags: ['analytics', 'dashboard', 'reporting'],
+    createdAt: new Date('2023-10-01T12:00:00Z'),
+    updatedAt: new Date('2024-02-28T16:45:00Z'),
+  },
+];
+
+// ============ Subscription Mock Data ============
+
+export const MOCK_SUBSCRIPTION = {
+  id: 'sub-1',
+  organizationId: 'demo-org',
+  planId: 'pro',
+  planName: 'Professional',
+  status: 'ACTIVE' as const,
+  currentPeriodStart: new Date('2024-04-01T00:00:00Z'),
+  currentPeriodEnd: new Date('2024-05-01T00:00:00Z'),
+  limits: {
+    projects: 25,
+    users: 10,
+    storage: 50, // GB
+    apiCalls: 100000,
+  },
+  usage: {
+    projects: 4,
+    users: 5,
+    storage: 12.5,
+    apiCalls: 45230,
+  },
+};
+
+// ============ Usage Summary Mock Data ============
+
+export const MOCK_USAGE_SUMMARY = {
+  organizationId: 'demo-org',
+  period: 'current_month',
+  apiCalls: {
+    total: 45230,
+    limit: 100000,
+    percentUsed: 45.23,
+  },
+  storage: {
+    totalGb: 12.5,
+    limitGb: 50,
+    percentUsed: 25,
+  },
+  activeProjects: 4,
+  activeUsers: 5,
+  breakdown: [
+    { date: '2024-04-01', apiCalls: 3200, storageGb: 12.1 },
+    { date: '2024-04-02', apiCalls: 2800, storageGb: 12.2 },
+    { date: '2024-04-03', apiCalls: 4100, storageGb: 12.3 },
+    { date: '2024-04-04', apiCalls: 3600, storageGb: 12.4 },
+    { date: '2024-04-05', apiCalls: 3800, storageGb: 12.5 },
+  ],
+};

package/src/handlers/project.handlers.ts

@@ -0,0 +1,170 @@
+/**
+ * Mock handlers for Project contracts
+ */
+import { MOCK_PROJECTS } from './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))
+    );
+  }
+
+  // Sort by updatedAt descending
+  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> {
+  // Simulate slug collision check
+  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/index.ts

@@ -0,0 +1,32 @@
+// SaaS Boilerplate Example
+// Demonstrates ContractSpec principles for a complete SaaS application
+
+export * from './entities';
+export * from './contracts';
+export * from './events';
+export * from './handlers';
+export * from './presentations';
+export * from './feature';
+
+// Schema composition configuration
+import { identityRbacSchemaContribution } from '@lssm/lib.identity-rbac';
+import { jobsSchemaContribution } from '@lssm/lib.jobs';
+import { auditTrailSchemaContribution } from '@lssm/module.audit-trail';
+import { notificationsSchemaContribution } from '@lssm/module.notifications';
+import { saasBoilerplateSchemaContribution } from './entities';
+
+/**
+ * Complete schema composition for SaaS Boilerplate.
+ * Use with `database schema:compose` to generate Prisma schema.
+ */
+export const schemaComposition = {
+  modules: [
+    identityRbacSchemaContribution,
+    jobsSchemaContribution,
+    auditTrailSchemaContribution,
+    notificationsSchemaContribution,
+    saasBoilerplateSchemaContribution,
+  ],
+  provider: 'postgresql' as const,
+  outputPath: './prisma/schema/generated.prisma',
+};

package/src/presentations/billing.ts

@@ -0,0 +1,51 @@
+/**
+ * Billing Presentation Descriptors
+ */
+import type { PresentationDescriptorV2 } from '@lssm/lib.contracts';
+
+/**
+ * Presentation for subscription overview.
+ */
+export const SubscriptionPresentation: PresentationDescriptorV2 = {
+  meta: {
+    name: 'saas.billing.subscription',
+    version: 1,
+    description:
+      'Subscription status with plan info, limits, and current usage',
+    domain: 'saas-boilerplate',
+    owners: ['saas-team'],
+    tags: ['billing', 'subscription'],
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'SubscriptionView',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.billing.enabled'],
+  },
+};
+
+/**
+ * Presentation for usage dashboard.
+ */
+export const UsageDashboardPresentation: PresentationDescriptorV2 = {
+  meta: {
+    name: 'saas.billing.usage',
+    version: 1,
+    description: 'Usage metrics and breakdown by resource type',
+    domain: 'saas-boilerplate',
+    owners: ['saas-team'],
+    tags: ['billing', 'usage', 'metrics'],
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'UsageDashboardView',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.billing.enabled'],
+  },
+};

package/src/presentations/dashboard.ts

@@ -0,0 +1,51 @@
+/**
+ * SaaS Dashboard Presentation Descriptor
+ */
+import type { PresentationDescriptorV2 } from '@lssm/lib.contracts';
+
+/**
+ * Main dashboard presentation for the SaaS application.
+ */
+export const SaasDashboardPresentation: PresentationDescriptorV2 = {
+  meta: {
+    name: 'saas.dashboard',
+    version: 1,
+    description:
+      'Main SaaS dashboard with project overview, usage stats, and quick actions',
+    domain: 'saas-boilerplate',
+    owners: ['saas-team'],
+    tags: ['dashboard', 'overview'],
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'SaasDashboard',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.enabled'],
+  },
+};
+
+/**
+ * Settings panel presentation.
+ */
+export const SettingsPanelPresentation: PresentationDescriptorV2 = {
+  meta: {
+    name: 'saas.settings',
+    version: 1,
+    description: 'Organization and user settings panel',
+    domain: 'saas-boilerplate',
+    owners: ['saas-team'],
+    tags: ['settings', 'config'],
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'SettingsPanel',
+  },
+  targets: ['react'],
+  policy: {
+    flags: ['saas.enabled'],
+  },
+};

package/src/presentations/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Presentation descriptors for saas-boilerplate
+ */
+
+// Project presentations
+export {
+  ProjectListPresentation,
+  ProjectDetailPresentation,
+} from './project-list';
+
+// Billing presentations
+export {
+  SubscriptionPresentation,
+  UsageDashboardPresentation,
+} from './billing';
+
+// Dashboard presentations
+export {
+  SaasDashboardPresentation,
+  SettingsPanelPresentation,
+} from './dashboard';
+
+// Re-export all presentations as an array
+import {
+  ProjectListPresentation,
+  ProjectDetailPresentation,
+} from './project-list';
+import {
+  SubscriptionPresentation,
+  UsageDashboardPresentation,
+} from './billing';
+import {
+  SaasDashboardPresentation,
+  SettingsPanelPresentation,
+} from './dashboard';
+
+export const SaasBoilerplatePresentations = [
+  SaasDashboardPresentation,
+  ProjectListPresentation,
+  ProjectDetailPresentation,
+  SubscriptionPresentation,
+  UsageDashboardPresentation,
+  SettingsPanelPresentation,
+];

package/src/presentations/project-list.ts

@@ -0,0 +1,53 @@
+/**
+ * Project List Presentation Descriptor
+ */
+import type { PresentationDescriptorV2 } from '@lssm/lib.contracts';
+import { ProjectModel } from '../contracts/project';
+
+/**
+ * Presentation for displaying a list of projects.
+ */
+export const ProjectListPresentation: PresentationDescriptorV2 = {
+  meta: {
+    name: 'saas.project.list',
+    version: 1,
+    description:
+      'List view of projects with status, tags, and last updated info',
+    domain: 'saas-boilerplate',
+    owners: ['saas-team'],
+    tags: ['project', 'list', 'dashboard'],
+  },
+  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: PresentationDescriptorV2 = {
+  meta: {
+    name: 'saas.project.detail',
+    version: 1,
+    description: 'Detailed view of a project with settings and activity',
+    domain: 'saas-boilerplate',
+    owners: ['saas-team'],
+    tags: ['project', 'detail'],
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ProjectDetailView',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.projects.enabled'],
+  },
+};

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@lssm/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}
+