@contractspec/example.saas-boilerplate 1.44.0

package/src/docs/saas-boilerplate.docblock.ts

@@ -0,0 +1,98 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const saasBoilerplateDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.saas-boilerplate.goal',
+    title: 'SaaS Boilerplate — Goal',
+    summary:
+      'Multi-tenant SaaS foundation with orgs, members, projects, settings, and usage.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/saas-boilerplate/goal',
+    tags: ['saas', 'goal'],
+    body: `## Why it matters
+- Provides a regenerable SaaS base: orgs, members, projects, settings, usage/billing.
+- Avoids drift across identity, settings, and usage capture.
+
+## Business/Product goal
+- Ship SaaS faster with tenant isolation, RBAC, and usage metering baked in.
+- Keep audit/notifications ready for compliance and customer comms.
+
+## Success criteria
+- Spec changes to org/project/settings/usage regenerate UI/API/events cleanly.
+- Tenant isolation and RBAC stay enforced; usage data is captured with PII scopes.`,
+  },
+  {
+    id: 'docs.examples.saas-boilerplate.usage',
+    title: 'SaaS Boilerplate — Usage',
+    summary: 'How to seed, extend, and regenerate the SaaS base.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/saas-boilerplate/usage',
+    tags: ['saas', 'usage'],
+    body: `## Setup
+1) Seed (if available) or create orgs, members, and projects via UI.
+2) Configure Notifications for invites and project events; set policy.pii for sensitive fields.
+
+## Extend & regenerate
+1) Adjust schemas (project metadata, settings, usage records) in spec.
+2) Regenerate to sync UI/API/events and usage metering.
+3) Use Feature Flags to roll out new settings or billing fields gradually.
+
+## Guardrails
+- Keep tenant/role context explicit in contracts and presentations.
+- Emit events for invites, project changes, and usage records; log in Audit Trail.
+- Redact sensitive user/org data in markdown/JSON outputs.`,
+  },
+  {
+    id: 'docs.examples.saas-boilerplate.reference',
+    title: 'SaaS Boilerplate — Reference',
+    summary:
+      'Entities, contracts, events, and presentations for the SaaS starter.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/saas-boilerplate',
+    tags: ['saas', 'reference'],
+    body: `## Entities
+- Organization, Member, Role, Project, AppSettings, UserSettings, BillingUsage.
+
+## Contracts
+- org/project CRUD, invites, role assignment, usage recording.
+
+## Events
+- org.created, member.invited/accepted, project.created/updated, usage.recorded.
+
+## Presentations
+- Org/project dashboards, member management, settings screens, usage views.
+
+## Notes
+- Tenant isolation is mandatory; enforce via RBAC/policies.
+- Usage/Metering drives billing/limits; keep units explicit.`,
+  },
+  {
+    id: 'docs.examples.saas-boilerplate.constraints',
+    title: 'SaaS Boilerplate — Constraints & Safety',
+    summary:
+      'Internal guardrails for tenancy, RBAC, usage metering, and regeneration.',
+    kind: 'reference',
+    visibility: 'internal',
+    route: '/docs/examples/saas-boilerplate/constraints',
+    tags: ['saas', 'constraints', 'internal'],
+    body: `## Constraints
+- Tenant isolation and RBAC must remain explicit in spec; no implicit defaults in code.
+- Events to emit: org.created, member.invited/accepted, project.created/updated, usage.recorded.
+- Regeneration must not change billing/usage semantics without spec diffs.
+
+## PII & Settings
+- Mark PII (user emails, names) for redaction; keep settings scoped to org/member.
+- Avoid leaking secrets/config in markdown/JSON presentations.
+
+## Verification
+- Add fixtures for usage recording and role changes.
+- Ensure Audit/Notifications remain wired for invites/project updates.
+- Use Feature Flags for new settings/billing fields; default safe/off.`,
+  },
+];
+
+registerDocBlocks(saasBoilerplateDocBlocks);

package/src/example.ts

@@ -0,0 +1,31 @@
+const example = {
+  id: 'saas-boilerplate',
+  title: 'SaaS Boilerplate',
+  summary:
+    'Multi-tenant SaaS foundation with orgs, projects, settings, billing usage, and RBAC.',
+  tags: ['saas', 'multi-tenant', 'billing', 'rbac'],
+  kind: 'template',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.saas-boilerplate',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.saas-boilerplate',
+    feature: './feature',
+    contracts: './contracts',
+    presentations: './presentations',
+    handlers: './handlers',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: {
+      enabled: true,
+      modes: ['playground', 'specs', 'builder', 'markdown', 'evolution'],
+    },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;

package/src/handlers/index.ts

@@ -0,0 +1,20 @@
+/**
+ * SaaS Boilerplate Handlers - re-exports from domain modules for backward compatibility.
+ */
+
+// Billing handlers
+export {
+  mockGetSubscriptionHandler,
+  mockRecordUsageHandler,
+  mockGetUsageSummaryHandler,
+  mockCheckFeatureAccessHandler,
+} from '../billing/billing.handler';
+
+// Project handlers
+export {
+  mockCreateProjectHandler,
+  mockGetProjectHandler,
+  mockListProjectsHandler,
+  mockUpdateProjectHandler,
+  mockDeleteProjectHandler,
+} from '../project/project.handler';

package/src/index.ts

@@ -0,0 +1,71 @@
+// SaaS Boilerplate Example
+// Demonstrates ContractSpec principles for a complete SaaS application
+
+// Export all domain modules
+export * from './billing';
+export * from './project';
+export * from './settings';
+export * from './dashboard';
+
+// Export feature and example metadata
+export * from './saas-boilerplate.feature';
+export { default as example } from './example';
+
+// Import docs for registration
+import './docs';
+
+// Schema composition configuration
+import { identityRbacSchemaContribution } from '@contractspec/lib.identity-rbac';
+import { jobsSchemaContribution } from '@contractspec/lib.jobs';
+import { auditTrailSchemaContribution } from '@contractspec/module.audit-trail';
+import { notificationsSchemaContribution } from '@contractspec/module.notifications';
+import type { ModuleSchemaContribution } from '@contractspec/lib.schema';
+import {
+  ProjectEntity,
+  ProjectMemberEntity,
+  ProjectStatusEnum,
+} from './project/project.entity';
+import {
+  SettingsEntity,
+  FeatureFlagEntity,
+  SettingsScopeEnum,
+} from './settings';
+import {
+  SubscriptionEntity,
+  BillingUsageEntity,
+  UsageLimitEntity,
+  SubscriptionStatusEnum,
+} from './billing/billing.entity';
+
+/**
+ * SaaS boilerplate schema contribution.
+ */
+export const saasBoilerplateSchemaContribution: ModuleSchemaContribution = {
+  moduleId: '@contractspec/example.saas-boilerplate',
+  entities: [
+    ProjectEntity,
+    ProjectMemberEntity,
+    SettingsEntity,
+    FeatureFlagEntity,
+    SubscriptionEntity,
+    BillingUsageEntity,
+    UsageLimitEntity,
+  ],
+  enums: [ProjectStatusEnum, SettingsScopeEnum, SubscriptionStatusEnum],
+};
+
+/**
+ * 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/index.ts

@@ -0,0 +1,36 @@
+/**
+ * SaaS Boilerplate Presentations - re-exports from domain modules for backward compatibility.
+ */
+
+// Billing presentations
+export {
+  SubscriptionPresentation,
+  UsageDashboardPresentation,
+} from '../billing/billing.presentation';
+
+// Project presentations
+export {
+  ProjectListPresentation,
+  ProjectDetailPresentation,
+} from '../project/project.presentation';
+
+// Dashboard presentations
+export {
+  SaasDashboardPresentation,
+  SettingsPanelPresentation,
+} from '../dashboard/dashboard.presentation';
+
+// All presentations collection
+export const SaasBoilerplatePresentations = {
+  // Billing
+  SubscriptionPresentation: undefined,
+  UsageDashboardPresentation: undefined,
+
+  // Project
+  ProjectListPresentation: undefined,
+  ProjectDetailPresentation: undefined,
+
+  // Dashboard
+  SaasDashboardPresentation: undefined,
+  SettingsPanelPresentation: undefined,
+};

package/src/project/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Project domain - project management within organizations.
+ */
+
+// Enums
+export {
+  ProjectStatusSchemaEnum,
+  ProjectStatusFilterEnum,
+} from './project.enum';
+
+// Schema models
+export {
+  ProjectModel,
+  CreateProjectInputModel,
+  UpdateProjectInputModel,
+  GetProjectInputModel,
+  DeleteProjectInputModel,
+  DeleteProjectOutputModel,
+  ProjectDeletedPayloadModel,
+  ListProjectsInputModel,
+  ListProjectsOutputModel,
+} from './project.schema';
+
+// Contracts
+export {
+  CreateProjectContract,
+  GetProjectContract,
+  UpdateProjectContract,
+  DeleteProjectContract,
+  ListProjectsContract,
+} from './project.operations';
+
+// Events
+export {
+  ProjectCreatedEvent,
+  ProjectUpdatedEvent,
+  ProjectDeletedEvent,
+  ProjectArchivedEvent,
+} from './project.event';
+
+// Entities
+export {
+  ProjectStatusEnum,
+  ProjectEntity,
+  ProjectMemberEntity,
+} from './project.entity';
+
+// Presentations
+export {
+  ProjectListPresentation,
+  ProjectDetailPresentation,
+} from './project.presentation';
+
+// Handlers
+export {
+  mockListProjectsHandler,
+  mockGetProjectHandler,
+  mockCreateProjectHandler,
+  mockUpdateProjectHandler,
+  mockDeleteProjectHandler,
+  type Project,
+  type CreateProjectInput,
+  type UpdateProjectInput,
+  type ListProjectsInput,
+  type ListProjectsOutput,
+} from './project.handler';

package/src/project/project.entity.ts

@@ -0,0 +1,93 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@contractspec/lib.schema';
+
+/**
+ * Project status enum for entities.
+ */
+export const ProjectStatusEnum = defineEntityEnum({
+  name: 'ProjectStatus',
+  values: ['DRAFT', 'ACTIVE', 'ARCHIVED', 'DELETED'] as const,
+  schema: 'saas_app',
+  description: 'Status of a project.',
+});
+
+/**
+ * Project entity - team-scoped work container.
+ */
+export const ProjectEntity = defineEntity({
+  name: 'Project',
+  description: 'A project belonging to an organization.',
+  schema: 'saas_app',
+  map: 'project',
+  fields: {
+    id: field.id({ description: 'Unique project ID' }),
+    name: field.string({ description: 'Project name' }),
+    description: field.string({
+      isOptional: true,
+      description: 'Project description',
+    }),
+    slug: field.string({
+      isOptional: true,
+      description: 'URL-friendly identifier',
+    }),
+
+    // Ownership
+    organizationId: field.foreignKey({ description: 'Owning organization' }),
+    createdBy: field.foreignKey({
+      description: 'User who created the project',
+    }),
+
+    // Status
+    status: field.enum('ProjectStatus', { default: 'DRAFT' }),
+
+    // Settings
+    isPublic: field.boolean({
+      default: false,
+      description: 'Whether project is publicly visible',
+    }),
+    settings: field.json({
+      isOptional: true,
+      description: 'Project-specific settings',
+    }),
+
+    // Metadata
+    tags: field.string({ isArray: true, description: 'Project tags' }),
+    metadata: field.json({ isOptional: true }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    archivedAt: field.dateTime({ isOptional: true }),
+  },
+  indexes: [
+    index.on(['organizationId', 'status']),
+    index.on(['organizationId', 'createdAt']),
+    index.unique(['organizationId', 'slug']),
+  ],
+  enums: [ProjectStatusEnum],
+});
+
+/**
+ * ProjectMember entity - project-level access.
+ */
+export const ProjectMemberEntity = defineEntity({
+  name: 'ProjectMember',
+  description: 'User access to a specific project.',
+  schema: 'saas_app',
+  map: 'project_member',
+  fields: {
+    id: field.id(),
+    projectId: field.foreignKey(),
+    userId: field.foreignKey(),
+    role: field.string({
+      description: 'Role in project (owner, editor, viewer)',
+    }),
+    addedBy: field.string({ isOptional: true }),
+    createdAt: field.createdAt(),
+  },
+  indexes: [index.unique(['projectId', 'userId'])],
+});

package/src/project/project.enum.ts

@@ -0,0 +1,22 @@
+import { defineEnum } from '@contractspec/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,128 @@
+import { ScalarTypeEnum, defineSchemaModel } from '@contractspec/lib.schema';
+import { defineEvent } from '@contractspec/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({
+  meta: {
+    key: 'project.created',
+    version: 1,
+    description: 'A new project has been created.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['project', 'created'],
+  },
+  payload: ProjectCreatedPayload,
+});
+
+/**
+ * Event: A project has been updated.
+ */
+export const ProjectUpdatedEvent = defineEvent({
+  meta: {
+    key: 'project.updated',
+    version: 1,
+    description: 'A project has been updated.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['project', 'updated'],
+  },
+  payload: ProjectUpdatedPayload,
+});
+
+/**
+ * Event: A project has been deleted.
+ */
+export const ProjectDeletedEvent = defineEvent({
+  meta: {
+    key: 'project.deleted',
+    version: 1,
+    description: 'A project has been deleted.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['project', 'deleted'],
+  },
+  payload: ProjectDeletedPayload,
+});
+
+/**
+ * Event: A project has been archived.
+ */
+export const ProjectArchivedEvent = defineEvent({
+  meta: {
+    key: 'project.archived',
+    version: 1,
+    description: 'A project has been archived.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['project', 'archived'],
+  },
+  payload: ProjectArchivedPayload,
+});