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

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@lssm/example.saas-boilerplate",
+  "version": "0.0.0-canary-20251206160926",
+  "description": "SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contracts": "./src/contracts/index.ts",
+    "./contracts/billing": "./src/contracts/billing.ts",
+    "./contracts/project": "./src/contracts/project.ts",
+    "./entities": "./src/entities/index.ts",
+    "./entities/billing": "./src/entities/billing.ts",
+    "./entities/project": "./src/entities/project.ts",
+    "./entities/settings": "./src/entities/settings.ts",
+    "./events": "./src/events.ts",
+    "./feature": "./src/feature.ts",
+    "./handlers": "./src/handlers/index.ts",
+    "./handlers/billing.handlers": "./src/handlers/billing.handlers.ts",
+    "./handlers/mock-data": "./src/handlers/mock-data.ts",
+    "./handlers/project.handlers": "./src/handlers/project.handlers.ts",
+    "./presentations": "./src/presentations/index.ts",
+    "./presentations/billing": "./src/presentations/billing.ts",
+    "./presentations/dashboard": "./src/presentations/dashboard.ts",
+    "./presentations/project-list": "./src/presentations/project-list.ts",
+    "./*": "./*"
+  },
+  "scripts": {
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun run"
+  },
+  "dependencies": {
+    "@lssm/lib.schema": "workspace:*",
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.bus": "workspace:*",
+    "@lssm/lib.identity-rbac": "workspace:*",
+    "@lssm/lib.jobs": "workspace:*",
+    "@lssm/module.audit-trail": "workspace:*",
+    "@lssm/module.notifications": "workspace:*",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./contracts": "./dist/contracts/index.js",
+      "./contracts/billing": "./dist/contracts/billing.js",
+      "./contracts/project": "./dist/contracts/project.js",
+      "./entities": "./dist/entities/index.js",
+      "./entities/billing": "./dist/entities/billing.js",
+      "./entities/project": "./dist/entities/project.js",
+      "./entities/settings": "./dist/entities/settings.js",
+      "./events": "./dist/events.js",
+      "./feature": "./dist/feature.js",
+      "./handlers": "./dist/handlers/index.js",
+      "./handlers/billing.handlers": "./dist/handlers/billing.handlers.js",
+      "./handlers/mock-data": "./dist/handlers/mock-data.js",
+      "./handlers/project.handlers": "./dist/handlers/project.handlers.js",
+      "./presentations": "./dist/presentations/index.js",
+      "./presentations/billing": "./dist/presentations/billing.js",
+      "./presentations/dashboard": "./dist/presentations/dashboard.js",
+      "./presentations/project-list": "./dist/presentations/project-list.js",
+      "./*": "./*"
+    }
+  }
+}

package/src/contracts/billing.ts

@@ -0,0 +1,233 @@
+import {
+  defineCommand,
+  defineQuery,
+  defineSchemaModel,
+} from '@lssm/lib.contracts';
+import { ScalarTypeEnum, defineEnum } from '@lssm/lib.schema';
+
+const OWNERS = ['example.saas-boilerplate'] as const;
+
+// ============ Enums (for contract schemas) ============
+// Note: Entity enums for Prisma are defined separately in ../entities
+
+const SubscriptionStatusSchemaEnum = defineEnum('SubscriptionStatus', [
+  'TRIALING',
+  'ACTIVE',
+  'PAST_DUE',
+  'CANCELED',
+  'PAUSED',
+]);
+
+export const FeatureAccessReasonEnum = defineEnum('FeatureAccessReason', [
+  'included',
+  'limit_available',
+  'limit_reached',
+  'not_in_plan',
+]);
+
+// ============ Schemas ============
+
+export const SubscriptionModel = defineSchemaModel({
+  name: 'Subscription',
+  description: 'Organization subscription details',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    planId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    planName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: SubscriptionStatusSchemaEnum, isOptional: false },
+    currentPeriodStart: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    currentPeriodEnd: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    trialEndsAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    cancelAtPeriodEnd: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+  },
+});
+
+export const UsageSummaryModel = defineSchemaModel({
+  name: 'UsageSummary',
+  description: 'Usage summary for a feature',
+  fields: {
+    feature: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    used: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    unit: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    percentage: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+  },
+});
+
+export const RecordUsageInputModel = defineSchemaModel({
+  name: 'RecordUsageInput',
+  description: 'Input for recording feature usage',
+  fields: {
+    feature: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    sourceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    sourceType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+  },
+});
+
+export const RecordUsageOutputModel = defineSchemaModel({
+  name: 'RecordUsageOutput',
+  description: 'Output for recording feature usage',
+  fields: {
+    recorded: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    currentUsage: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    limitReached: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+  },
+});
+
+export const UsageRecordedPayloadModel = defineSchemaModel({
+  name: 'UsageRecordedPayload',
+  description: 'Payload for usage.recorded event',
+  fields: {
+    feature: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+  },
+});
+
+export const GetUsageSummaryInputModel = defineSchemaModel({
+  name: 'GetUsageSummaryInput',
+  description: 'Input for getting usage summary',
+  fields: {
+    billingPeriod: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+export const GetUsageSummaryOutputModel = defineSchemaModel({
+  name: 'GetUsageSummaryOutput',
+  description: 'Output for usage summary',
+  fields: {
+    billingPeriod: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    usage: { type: UsageSummaryModel, isArray: true, isOptional: false },
+  },
+});
+
+export const CheckFeatureAccessInputModel = defineSchemaModel({
+  name: 'CheckFeatureAccessInput',
+  description: 'Input for checking feature access',
+  fields: {
+    feature: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const CheckFeatureAccessOutputModel = defineSchemaModel({
+  name: 'CheckFeatureAccessOutput',
+  description: 'Output for feature access check',
+  fields: {
+    hasAccess: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    reason: { type: FeatureAccessReasonEnum, isOptional: true },
+    upgradeUrl: { type: ScalarTypeEnum.URL(), isOptional: true },
+  },
+});
+
+// ============ Contracts ============
+
+/**
+ * Get subscription status.
+ */
+export const GetSubscriptionContract = defineQuery({
+  meta: {
+    name: 'saas.billing.subscription.get',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'billing', 'subscription'],
+    description: 'Get organization subscription status.',
+    goal: 'Show current plan and billing status.',
+    context: 'Billing page, plan upgrade prompts.',
+  },
+  io: {
+    input: null,
+    output: SubscriptionModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+});
+
+/**
+ * Record feature usage.
+ */
+export const RecordUsageContract = defineCommand({
+  meta: {
+    name: 'saas.billing.usage.record',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'billing', 'usage'],
+    description: 'Record usage of a metered feature.',
+    goal: 'Track feature usage for billing.',
+    context: 'Called by services when metered features are used.',
+  },
+  io: {
+    input: RecordUsageInputModel,
+    output: RecordUsageOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+  sideEffects: {
+    emits: [
+      {
+        name: 'billing.usage.recorded',
+        version: 1,
+        when: 'Usage is recorded',
+        payload: UsageRecordedPayloadModel,
+      },
+    ],
+  },
+});
+
+/**
+ * Get usage summary.
+ */
+export const GetUsageSummaryContract = defineQuery({
+  meta: {
+    name: 'saas.billing.usage.summary',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'billing', 'usage'],
+    description: 'Get usage summary for the current billing period.',
+    goal: 'Show usage vs limits.',
+    context: 'Billing page, usage dashboards.',
+  },
+  io: {
+    input: GetUsageSummaryInputModel,
+    output: GetUsageSummaryOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+});
+
+/**
+ * Check feature access.
+ */
+export const CheckFeatureAccessContract = defineQuery({
+  meta: {
+    name: 'saas.billing.feature.check',
+    version: 1,
+    stability: 'stable',
+    owners: [...OWNERS],
+    tags: ['saas', 'billing', 'feature'],
+    description: 'Check if organization has access to a feature.',
+    goal: 'Gate features based on plan/usage.',
+    context: 'Feature access checks, upgrade prompts.',
+  },
+  io: {
+    input: CheckFeatureAccessInputModel,
+    output: CheckFeatureAccessOutputModel,
+  },
+  policy: {
+    auth: 'user',
+  },
+});

package/src/contracts/index.ts

@@ -0,0 +1,36 @@
+// Project contracts and models
+export {
+  ProjectStatusFilterEnum,
+  ProjectModel,
+  CreateProjectInputModel,
+  UpdateProjectInputModel,
+  GetProjectInputModel,
+  DeleteProjectInputModel,
+  DeleteProjectOutputModel,
+  ProjectDeletedPayloadModel,
+  ListProjectsInputModel,
+  ListProjectsOutputModel,
+  CreateProjectContract,
+  GetProjectContract,
+  UpdateProjectContract,
+  DeleteProjectContract,
+  ListProjectsContract,
+} from './project';
+
+// Billing contracts and models
+export {
+  FeatureAccessReasonEnum,
+  SubscriptionModel,
+  UsageSummaryModel,
+  RecordUsageInputModel,
+  RecordUsageOutputModel,
+  UsageRecordedPayloadModel,
+  GetUsageSummaryInputModel,
+  GetUsageSummaryOutputModel,
+  CheckFeatureAccessInputModel,
+  CheckFeatureAccessOutputModel,
+  GetSubscriptionContract,
+  RecordUsageContract,
+  GetUsageSummaryContract,
+  CheckFeatureAccessContract,
+} from './billing';

package/src/contracts/project.ts

@@ -0,0 +1,314 @@
+import { defineCommand, defineQuery } from '@lssm/lib.contracts/spec';
+import {
+  defineSchemaModel,
+  ScalarTypeEnum,
+  defineEnum,
+} from '@lssm/lib.schema';
+
+const OWNERS = ['example.saas-boilerplate'] as const;
+
+// ============ Enums (for contract schemas) ============
+// Note: Entity enums for Prisma are defined separately in ../entities
+
+const ProjectStatusSchemaEnum = defineEnum('ProjectStatus', [
+  'DRAFT',
+  'ACTIVE',
+  'ARCHIVED',
+  'DELETED',
+]);
+
+export const ProjectStatusFilterEnum = defineEnum('ProjectStatusFilter', [
+  'DRAFT',
+  'ACTIVE',
+  'ARCHIVED',
+  'all',
+]);
+
+// ============ Schemas ============
+
+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 },
+  },
+});
+
+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,
+    },
+  },
+});
+
+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 },
+  },
+});
+
+export const GetProjectInputModel = defineSchemaModel({
+  name: 'GetProjectInput',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const DeleteProjectInputModel = defineSchemaModel({
+  name: 'DeleteProjectInput',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const DeleteProjectOutputModel = defineSchemaModel({
+  name: 'DeleteProjectOutput',
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+  },
+});
+
+export const ProjectDeletedPayloadModel = defineSchemaModel({
+  name: 'ProjectDeletedPayload',
+  fields: {
+    projectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+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,
+    },
+  },
+});
+
+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 },
+  },
+});
+
+// ============ Contracts ============
+
+/**
+ * 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',
+  },
+});