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

package/src/entities/billing.ts

@@ -0,0 +1,153 @@
+import { defineEntity, defineEntityEnum, field, index } from '@lssm/lib.schema';
+
+/**
+ * Subscription status enum.
+ */
+export const SubscriptionStatusEnum = defineEntityEnum({
+  name: 'SubscriptionStatus',
+  values: ['TRIALING', 'ACTIVE', 'PAST_DUE', 'CANCELED', 'PAUSED'] as const,
+  schema: 'saas_app',
+  description: 'Status of a subscription.',
+});
+
+/**
+ * Subscription entity - organization subscription info.
+ */
+export const SubscriptionEntity = defineEntity({
+  name: 'Subscription',
+  description: 'Organization subscription/plan information.',
+  schema: 'saas_app',
+  map: 'subscription',
+  fields: {
+    id: field.id(),
+    organizationId: field.foreignKey({ isUnique: true }),
+
+    // Plan info
+    planId: field.string({ description: 'Plan identifier' }),
+    planName: field.string({ description: 'Plan display name' }),
+
+    // Status
+    status: field.enum('SubscriptionStatus'),
+
+    // Billing cycle
+    currentPeriodStart: field.dateTime(),
+    currentPeriodEnd: field.dateTime(),
+
+    // Trial
+    trialEndsAt: field.dateTime({ isOptional: true }),
+
+    // Cancellation
+    cancelAtPeriodEnd: field.boolean({ default: false }),
+    canceledAt: field.dateTime({ isOptional: true }),
+
+    // External reference
+    stripeSubscriptionId: field.string({ isOptional: true }),
+    stripeCustomerId: field.string({ isOptional: true }),
+
+    // Metadata
+    metadata: field.json({ isOptional: true }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+  },
+  enums: [SubscriptionStatusEnum],
+});
+
+/**
+ * BillingUsage entity - track feature usage.
+ */
+export const BillingUsageEntity = defineEntity({
+  name: 'BillingUsage',
+  description: 'Track usage of metered features.',
+  schema: 'saas_app',
+  map: 'billing_usage',
+  fields: {
+    id: field.id(),
+    organizationId: field.foreignKey(),
+
+    // Feature
+    feature: field.string({
+      description: 'Feature being tracked (e.g., "api_calls", "storage_gb")',
+    }),
+
+    // Usage
+    quantity: field.int({ description: 'Usage quantity' }),
+    unit: field.string({
+      isOptional: true,
+      description: 'Unit of measurement',
+    }),
+
+    // Period
+    billingPeriod: field.string({
+      description: 'Billing period (e.g., "2024-01")',
+    }),
+
+    // Aggregation
+    recordedAt: field.dateTime({ description: 'When usage was recorded' }),
+
+    // Source
+    sourceId: field.string({
+      isOptional: true,
+      description: 'Source of usage (e.g., request ID)',
+    }),
+    sourceType: field.string({ isOptional: true }),
+
+    // Metadata
+    metadata: field.json({ isOptional: true }),
+  },
+  indexes: [
+    index.on(['organizationId', 'feature', 'billingPeriod']),
+    index.on(['organizationId', 'recordedAt']),
+  ],
+});
+
+/**
+ * UsageLimit entity - feature usage limits per plan.
+ */
+export const UsageLimitEntity = defineEntity({
+  name: 'UsageLimit',
+  description: 'Usage limits per plan/organization.',
+  schema: 'saas_app',
+  map: 'usage_limit',
+  fields: {
+    id: field.id(),
+
+    // Scope
+    planId: field.string({
+      isOptional: true,
+      description: 'Plan this limit applies to',
+    }),
+    organizationId: field.string({
+      isOptional: true,
+      description: 'Org-specific override',
+    }),
+
+    // Limit
+    feature: field.string({ description: 'Feature being limited' }),
+    limit: field.int({ description: 'Maximum allowed usage' }),
+    resetPeriod: field.string({
+      default: '"monthly"',
+      description: 'When limit resets',
+    }),
+
+    // Soft/hard limit
+    isSoftLimit: field.boolean({
+      default: false,
+      description: 'Whether to warn vs block',
+    }),
+    overage: field.boolean({
+      default: false,
+      description: 'Whether overage is allowed',
+    }),
+    overageRate: field.float({
+      isOptional: true,
+      description: 'Cost per unit over limit',
+    }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+  },
+  indexes: [index.unique(['planId', 'feature'])],
+});

package/src/entities/index.ts

@@ -0,0 +1,62 @@
+// Project entities
+export {
+  ProjectStatusEnum,
+  ProjectEntity,
+  ProjectMemberEntity,
+} from './project';
+
+// Settings entities
+export {
+  SettingsScopeEnum,
+  SettingsEntity,
+  FeatureFlagEntity,
+} from './settings';
+
+// Billing entities
+export {
+  SubscriptionStatusEnum,
+  SubscriptionEntity,
+  BillingUsageEntity,
+  UsageLimitEntity,
+} from './billing';
+
+// Re-export identity-rbac entities for convenience
+export {
+  identityRbacSchemaContribution,
+  identityRbacEntities,
+} from '@lssm/lib.identity-rbac';
+
+// Schema contribution
+import {
+  ProjectEntity,
+  ProjectMemberEntity,
+  ProjectStatusEnum,
+} from './project';
+import {
+  SettingsEntity,
+  FeatureFlagEntity,
+  SettingsScopeEnum,
+} from './settings';
+import {
+  SubscriptionEntity,
+  BillingUsageEntity,
+  UsageLimitEntity,
+  SubscriptionStatusEnum,
+} from './billing';
+import type { ModuleSchemaContribution } from '@lssm/lib.schema';
+
+export const saasBoilerplateEntities = [
+  ProjectEntity,
+  ProjectMemberEntity,
+  SettingsEntity,
+  FeatureFlagEntity,
+  SubscriptionEntity,
+  BillingUsageEntity,
+  UsageLimitEntity,
+];
+
+export const saasBoilerplateSchemaContribution: ModuleSchemaContribution = {
+  moduleId: '@lssm/example.saas-boilerplate',
+  entities: saasBoilerplateEntities,
+  enums: [ProjectStatusEnum, SettingsScopeEnum, SubscriptionStatusEnum],
+};

package/src/entities/project.ts

@@ -0,0 +1,88 @@
+import { defineEntity, defineEntityEnum, field, index } from '@lssm/lib.schema';
+
+/**
+ * Project status enum.
+ */
+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/entities/settings.ts

@@ -0,0 +1,98 @@
+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.',
+});
+
+/**
+ * Settings entity - key-value configuration store.
+ */
+export const SettingsEntity = defineEntity({
+  name: 'Settings',
+  description: 'Application, organization, or user settings.',
+  schema: 'saas_app',
+  map: 'settings',
+  fields: {
+    id: field.id(),
+
+    // Key identification
+    key: field.string({
+      description: 'Setting key (e.g., "theme", "notifications.email")',
+    }),
+
+    // Scope
+    scope: field.enum('SettingsScope'),
+    scopeId: field.string({
+      isOptional: true,
+      description: 'ID of scoped entity (org, user, project)',
+    }),
+
+    // Value
+    value: field.json({ description: 'Setting value' }),
+    valueType: field.string({
+      default: '"string"',
+      description: 'Type hint for value',
+    }),
+
+    // Schema
+    schema: field.json({
+      isOptional: true,
+      description: 'JSON schema for validation',
+    }),
+
+    // Metadata
+    description: field.string({ isOptional: true }),
+    isSecret: field.boolean({
+      default: false,
+      description: 'Whether value should be encrypted',
+    }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+  },
+  indexes: [
+    index.unique(['scope', 'scopeId', 'key']),
+    index.on(['scope', 'key']),
+  ],
+  enums: [SettingsScopeEnum],
+});
+
+/**
+ * FeatureFlag entity - feature toggles.
+ */
+export const FeatureFlagEntity = defineEntity({
+  name: 'FeatureFlag',
+  description: 'Feature flags for progressive rollout.',
+  schema: 'saas_app',
+  map: 'feature_flag',
+  fields: {
+    id: field.id(),
+    key: field.string({ isUnique: true, description: 'Feature flag key' }),
+    name: field.string({ description: 'Human-readable name' }),
+    description: field.string({ isOptional: true }),
+
+    // Status
+    enabled: field.boolean({ default: false }),
+
+    // Targeting
+    defaultValue: field.boolean({ default: false }),
+    rules: field.json({ isOptional: true, description: 'Targeting rules' }),
+
+    // Rollout
+    rolloutPercentage: field.int({
+      default: 0,
+      description: 'Percentage rollout (0-100)',
+    }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+  },
+});

package/src/events.ts

@@ -0,0 +1,177 @@
+import { ScalarTypeEnum, defineSchemaModel } from '@lssm/lib.schema';
+import { defineEvent } from '@lssm/lib.contracts';
+
+// ============ Project Event Payloads ============
+
+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 },
+  },
+});
+
+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 },
+  },
+});
+
+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 },
+  },
+});
+
+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 },
+  },
+});
+
+// ============ Billing Event Payloads ============
+
+const UsageRecordedPayload = defineSchemaModel({
+  name: 'UsageRecordedPayload',
+  description: 'Payload when feature usage is recorded',
+  fields: {
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    feature: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    billingPeriod: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    recordedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+const UsageLimitReachedPayload = defineSchemaModel({
+  name: 'UsageLimitReachedPayload',
+  description: 'Payload when usage limit is reached',
+  fields: {
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    feature: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    currentUsage: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    reachedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+const SubscriptionChangedPayload = defineSchemaModel({
+  name: 'SubscriptionChangedPayload',
+  description: 'Payload when subscription status changes',
+  fields: {
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false,
+    },
+    previousPlan: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    newPlan: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    previousStatus: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true,
+    },
+    newStatus: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    changedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+// ============ Project Events ============
+
+export const ProjectCreatedEvent = defineEvent({
+  name: 'project.created',
+  version: 1,
+  description: 'A new project has been created.',
+  payload: ProjectCreatedPayload,
+});
+
+export const ProjectUpdatedEvent = defineEvent({
+  name: 'project.updated',
+  version: 1,
+  description: 'A project has been updated.',
+  payload: ProjectUpdatedPayload,
+});
+
+export const ProjectDeletedEvent = defineEvent({
+  name: 'project.deleted',
+  version: 1,
+  description: 'A project has been deleted.',
+  payload: ProjectDeletedPayload,
+});
+
+export const ProjectArchivedEvent = defineEvent({
+  name: 'project.archived',
+  version: 1,
+  description: 'A project has been archived.',
+  payload: ProjectArchivedPayload,
+});
+
+// ============ Billing Events ============
+
+export const UsageRecordedEvent = defineEvent({
+  name: 'billing.usage.recorded',
+  version: 1,
+  description: 'Feature usage has been recorded.',
+  payload: UsageRecordedPayload,
+});
+
+export const UsageLimitReachedEvent = defineEvent({
+  name: 'billing.limit.reached',
+  version: 1,
+  description: 'Usage limit has been reached for a feature.',
+  payload: UsageLimitReachedPayload,
+});
+
+export const SubscriptionChangedEvent = defineEvent({
+  name: 'billing.subscription.changed',
+  version: 1,
+  description: 'Subscription status has changed.',
+  payload: SubscriptionChangedPayload,
+});
+
+// ============ All Events ============
+
+export const SaasBoilerplateEvents = {
+  ProjectCreatedEvent,
+  ProjectUpdatedEvent,
+  ProjectDeletedEvent,
+  ProjectArchivedEvent,
+  UsageRecordedEvent,
+  UsageLimitReachedEvent,
+  SubscriptionChangedEvent,
+};

package/src/feature.ts

@@ -0,0 +1,107 @@
+/**
+ * SaaS Boilerplate Feature Module Specification
+ *
+ * Defines the feature module for the SaaS application foundation.
+ */
+import type { FeatureModuleSpec } from '@lssm/lib.contracts';
+
+/**
+ * SaaS Boilerplate feature module that bundles project management,
+ * billing, and settings operations into an installable feature.
+ */
+export const SaasBoilerplateFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'saas-boilerplate',
+    title: 'SaaS Boilerplate',
+    description:
+      'SaaS application foundation with projects, billing, and settings',
+    domain: 'saas',
+    owners: ['saas-team'],
+    tags: ['saas', 'projects', 'billing'],
+    stability: 'experimental',
+  },
+
+  // All contract operations included in this feature
+  operations: [
+    // Project operations
+    { name: 'saas.project.create', version: 1 },
+    { name: 'saas.project.get', version: 1 },
+    { name: 'saas.project.update', version: 1 },
+    { name: 'saas.project.delete', version: 1 },
+    { name: 'saas.project.list', version: 1 },
+
+    // Billing operations
+    { name: 'saas.billing.getSubscription', version: 1 },
+    { name: 'saas.billing.recordUsage', version: 1 },
+    { name: 'saas.billing.getUsageSummary', version: 1 },
+    { name: 'saas.billing.checkFeatureAccess', version: 1 },
+  ],
+
+  // Events emitted by this feature
+  events: [
+    // Project events
+    { name: 'project.created', version: 1 },
+    { name: 'project.updated', version: 1 },
+    { name: 'project.deleted', version: 1 },
+
+    // Billing events
+    { name: 'usage.recorded', version: 1 },
+    { name: 'subscription.updated', version: 1 },
+    { name: 'limit.exceeded', version: 1 },
+  ],
+
+  // Presentations associated with this feature
+  presentations: [
+    { name: 'saas.dashboard', version: 1 },
+    { name: 'saas.project.list', version: 1 },
+    { name: 'saas.project.detail', version: 1 },
+    { name: 'saas.billing.subscription', version: 1 },
+    { name: 'saas.billing.usage', version: 1 },
+    { name: 'saas.settings', version: 1 },
+  ],
+
+  // Link operations to their primary presentations
+  opToPresentation: [
+    {
+      op: { name: 'saas.project.list', version: 1 },
+      pres: { name: 'saas.project.list', version: 1 },
+    },
+    {
+      op: { name: 'saas.project.get', version: 1 },
+      pres: { name: 'saas.project.detail', version: 1 },
+    },
+    {
+      op: { name: 'saas.billing.getSubscription', version: 1 },
+      pres: { name: 'saas.billing.subscription', version: 1 },
+    },
+    {
+      op: { name: 'saas.billing.getUsageSummary', version: 1 },
+      pres: { name: 'saas.billing.usage', version: 1 },
+    },
+  ],
+
+  // Target requirements for multi-surface rendering
+  presentationsTargets: [
+    { name: 'saas.dashboard', version: 1, targets: ['react', 'markdown'] },
+    {
+      name: 'saas.project.list',
+      version: 1,
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      name: 'saas.billing.subscription',
+      version: 1,
+      targets: ['react', 'markdown'],
+    },
+    { name: 'saas.billing.usage', version: 1, targets: ['react', 'markdown'] },
+  ],
+
+  // Capability requirements
+  capabilities: {
+    requires: [
+      { key: 'identity', version: 1 },
+      { key: 'audit-trail', version: 1 },
+      { key: 'notifications', version: 1 },
+    ],
+  },
+};