@contractspec/example.saas-boilerplate 1.44.0

package/src/saas-boilerplate.feature.ts

@@ -0,0 +1,109 @@
+/**
+ * SaaS Boilerplate Feature Module Specification
+ *
+ * Defines the feature module for the SaaS application foundation.
+ */
+import type { FeatureModuleSpec } from '@contractspec/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',
+    version: 1,
+  },
+
+  // All contract operations included in this feature
+  operations: [
+    // Project operations
+    { key: 'saas.project.create', version: 1 },
+    { key: 'saas.project.get', version: 1 },
+    { key: 'saas.project.update', version: 1 },
+    { key: 'saas.project.delete', version: 1 },
+    { key: 'saas.project.list', version: 1 },
+
+    // Billing operations
+    { key: 'saas.billing.subscription.get', version: 1 },
+    { key: 'saas.billing.usage.record', version: 1 },
+    { key: 'saas.billing.usage.summary', version: 1 },
+    { key: 'saas.billing.feature.check', version: 1 },
+  ],
+
+  // Events emitted by this feature
+  events: [
+    // Project events
+    { key: 'project.created', version: 1 },
+    { key: 'project.updated', version: 1 },
+    { key: 'project.deleted', version: 1 },
+    { key: 'project.archived', version: 1 },
+
+    // Billing events
+    { key: 'billing.usage.recorded', version: 1 },
+    { key: 'billing.subscription.changed', version: 1 },
+    { key: 'billing.limit.reached', version: 1 },
+  ],
+
+  // Presentations associated with this feature
+  presentations: [
+    { key: 'saas.dashboard', version: 1 },
+    { key: 'saas.project.list', version: 1 },
+    { key: 'saas.project.detail', version: 1 },
+    { key: 'saas.billing.subscription', version: 1 },
+    { key: 'saas.billing.usage', version: 1 },
+    { key: 'saas.settings', version: 1 },
+  ],
+
+  // Link operations to their primary presentations
+  opToPresentation: [
+    {
+      op: { key: 'saas.project.list', version: 1 },
+      pres: { key: 'saas.project.list', version: 1 },
+    },
+    {
+      op: { key: 'saas.project.get', version: 1 },
+      pres: { key: 'saas.project.detail', version: 1 },
+    },
+    {
+      op: { key: 'saas.billing.subscription.get', version: 1 },
+      pres: { key: 'saas.billing.subscription', version: 1 },
+    },
+    {
+      op: { key: 'saas.billing.usage.summary', version: 1 },
+      pres: { key: 'saas.billing.usage', version: 1 },
+    },
+  ],
+
+  // Target requirements for multi-surface rendering
+  presentationsTargets: [
+    { key: 'saas.dashboard', version: 1, targets: ['react', 'markdown'] },
+    {
+      key: 'saas.project.list',
+      version: 1,
+      targets: ['react', 'markdown', 'application/json'],
+    },
+    {
+      key: 'saas.billing.subscription',
+      version: 1,
+      targets: ['react', 'markdown'],
+    },
+    { key: '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 },
+    ],
+  },
+};

package/src/settings/index.ts

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

package/src/settings/settings.entity.ts

@@ -0,0 +1,89 @@
+import { defineEntity, field, index } from '@contractspec/lib.schema';
+import { SettingsScopeEnum } from './settings.enum';
+
+/**
+ * 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/settings/settings.enum.ts

@@ -0,0 +1,11 @@
+import { defineEntityEnum } from '@contractspec/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/shared/mock-data.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared 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/tsconfig.json

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