@contractspec/example.saas-boilerplate 0.0.0-canary-20260113170453

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/src/shared/overlay-types.ts

@@ -0,0 +1,39 @@
+export interface OverlayDefinition {
+  overlayId: string;
+  version: string;
+  description: string;
+  appliesTo: Record<string, string>;
+  modifications: OverlayModification[];
+}
+
+export type OverlayModification =
+  | HideFieldModification
+  | RenameLabelModification
+  | AddBadgeModification
+  | SetLimitModification;
+
+export interface HideFieldModification {
+  type: 'hideField';
+  field: string;
+  reason?: string;
+}
+
+export interface RenameLabelModification {
+  type: 'renameLabel';
+  field: string;
+  newLabel: string;
+}
+
+export interface AddBadgeModification {
+  type: 'addBadge';
+  position: 'header' | 'footer';
+  label: string;
+  variant: 'warning' | 'info' | 'error' | 'success' | 'default';
+}
+
+export interface SetLimitModification {
+  type: 'setLimit';
+  field: string;
+  max: number;
+  message: string;
+}

package/src/tests/operations.test-spec.ts

@@ -0,0 +1,109 @@
+import { defineTestSpec } from '@contractspec/lib.contracts';
+
+export const ProjectListTest = defineTestSpec({
+  meta: {
+    key: 'saas.project.list.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for listing projects',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.project.list', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.project.list' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.project.list' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const ProjectGetTest = defineTestSpec({
+  meta: {
+    key: 'saas.project.get.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for getting project',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.project.get', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.project.get' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.project.get' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const BillingSubscriptionGetTest = defineTestSpec({
+  meta: {
+    key: 'saas.billing.subscription.get.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for getting subscription',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.billing.subscription.get', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.billing.subscription.get' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.billing.subscription.get' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});
+
+export const BillingUsageSummaryTest = defineTestSpec({
+  meta: {
+    key: 'saas.billing.usage.summary.test',
+    version: '1.0.0',
+    stability: 'experimental',
+    owners: ['@example.saas-boilerplate'],
+    description: 'Test for getting usage summary',
+    tags: ['test'],
+  },
+  target: {
+    type: 'operation',
+    operation: { key: 'saas.billing.usage.summary', version: '1.0.0' },
+  },
+  scenarios: [
+    {
+      key: 'success',
+      when: { operation: { key: 'saas.billing.usage.summary' } },
+      then: [{ type: 'expectOutput', match: {} }],
+    },
+    {
+      key: 'error',
+      when: { operation: { key: 'saas.billing.usage.summary' } },
+      then: [{ type: 'expectError' }],
+    },
+  ],
+});

package/src/ui/SaasDashboard.tsx

@@ -0,0 +1,325 @@
+'use client';
+
+/**
+ * SaaS Dashboard
+ *
+ * Fully integrated with ContractSpec example handlers
+ * and design-system components.
+ *
+ * Commands wired:
+ * - CreateProjectContract -> Create Project button + modal
+ * - UpdateProjectContract -> Edit project via modal
+ * - DeleteProjectContract -> Delete project via modal
+ */
+import { useState, useCallback } from 'react';
+import {
+  StatCard,
+  StatCardGroup,
+  StatusChip,
+  EntityCard,
+  EmptyState,
+  LoaderBlock,
+  ErrorState,
+  Button,
+} from '@contractspec/lib.design-system';
+import {
+  useProjectList,
+  type Project,
+  type Subscription,
+} from './hooks/useProjectList';
+import { useProjectMutations } from './hooks/useProjectMutations';
+import { CreateProjectModal } from './modals/CreateProjectModal';
+import { ProjectActionsModal } from './modals/ProjectActionsModal';
+
+type Tab = 'projects' | 'billing' | 'settings';
+
+function getStatusTone(
+  status: Project['status']
+): 'success' | 'warning' | 'neutral' | 'danger' {
+  switch (status) {
+    case 'ACTIVE':
+      return 'success';
+    case 'DRAFT':
+      return 'neutral';
+    case 'ARCHIVED':
+      return 'warning';
+    default:
+      return 'neutral';
+  }
+}
+
+export function SaasDashboard() {
+  const [activeTab, setActiveTab] = useState<Tab>('projects');
+  const [isCreateModalOpen, setIsCreateModalOpen] = useState(false);
+  const [selectedProject, setSelectedProject] = useState<Project | null>(null);
+  const [isProjectActionsOpen, setIsProjectActionsOpen] = useState(false);
+
+  const { data, subscription, loading, error, stats, refetch } =
+    useProjectList();
+
+  const mutations = useProjectMutations({
+    onSuccess: () => {
+      refetch();
+    },
+  });
+
+  const handleProjectClick = useCallback((project: Project) => {
+    setSelectedProject(project);
+    setIsProjectActionsOpen(true);
+  }, []);
+
+  const tabs: { id: Tab; label: string; icon: string }[] = [
+    { id: 'projects', label: 'Projects', icon: '📁' },
+    { id: 'billing', label: 'Billing', icon: '💳' },
+    { id: 'settings', label: 'Settings', icon: '⚙️' },
+  ];
+
+  if (loading && !data) {
+    return <LoaderBlock label="Loading dashboard..." />;
+  }
+
+  if (error) {
+    return (
+      <ErrorState
+        title="Failed to load dashboard"
+        description={error.message}
+        onRetry={refetch}
+        retryLabel="Retry"
+      />
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <h2 className="text-2xl font-bold">SaaS Dashboard</h2>
+        {activeTab === 'projects' && (
+          <Button onPress={() => setIsCreateModalOpen(true)}>
+            <span className="mr-2">+</span> New Project
+          </Button>
+        )}
+      </div>
+
+      {/* Stats Row */}
+      {stats && subscription && (
+        <StatCardGroup>
+          <StatCard label="Projects" value={stats.total.toString()} />
+          <StatCard label="Active" value={stats.activeCount.toString()} />
+          <StatCard label="Draft" value={stats.draftCount.toString()} />
+          <StatCard
+            label="Plan"
+            value={subscription.plan}
+            hint={subscription.status}
+          />
+        </StatCardGroup>
+      )}
+
+      {/* Navigation Tabs */}
+      <nav className="bg-muted flex gap-1 rounded-lg p-1" role="tablist">
+        {tabs.map((tab) => (
+          <button
+            key={tab.id}
+            type="button"
+            role="tab"
+            aria-selected={activeTab === tab.id}
+            onClick={() => setActiveTab(tab.id)}
+            className={`flex flex-1 items-center justify-center gap-2 rounded-md px-4 py-2 text-sm font-medium transition-colors ${
+              activeTab === tab.id
+                ? 'bg-background text-foreground shadow-sm'
+                : 'text-muted-foreground hover:text-foreground'
+            }`}
+          >
+            <span>{tab.icon}</span>
+            {tab.label}
+          </button>
+        ))}
+      </nav>
+
+      {/* Tab Content */}
+      <div className="min-h-[400px]" role="tabpanel">
+        {activeTab === 'projects' && (
+          <ProjectsTab data={data} onProjectClick={handleProjectClick} />
+        )}
+        {activeTab === 'billing' && <BillingTab subscription={subscription} />}
+        {activeTab === 'settings' && <SettingsTab />}
+      </div>
+
+      {/* Create Project Modal */}
+      <CreateProjectModal
+        isOpen={isCreateModalOpen}
+        onClose={() => setIsCreateModalOpen(false)}
+        onSubmit={async (input) => {
+          await mutations.createProject(input);
+        }}
+        isLoading={mutations.createState.loading}
+      />
+
+      {/* Project Actions Modal */}
+      <ProjectActionsModal
+        isOpen={isProjectActionsOpen}
+        project={selectedProject}
+        onClose={() => {
+          setIsProjectActionsOpen(false);
+          setSelectedProject(null);
+        }}
+        onUpdate={async (input) => {
+          await mutations.updateProject(input);
+        }}
+        onArchive={async (projectId) => {
+          await mutations.archiveProject(projectId);
+        }}
+        onActivate={async (projectId) => {
+          await mutations.activateProject(projectId);
+        }}
+        onDelete={async (projectId) => {
+          await mutations.deleteProject(projectId);
+        }}
+        isLoading={mutations.isLoading}
+      />
+    </div>
+  );
+}
+
+interface ProjectsTabProps {
+  data: ReturnType<typeof useProjectList>['data'];
+  onProjectClick?: (project: Project) => void;
+}
+
+function ProjectsTab({ data, onProjectClick }: ProjectsTabProps) {
+  if (!data?.items.length) {
+    return (
+      <EmptyState
+        title="No projects yet"
+        description="Create your first project to get started."
+      />
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
+        {data.items.map((project: Project) => (
+          <EntityCard
+            key={project.id}
+            cardTitle={project.name}
+            cardSubtitle={project.tier}
+            meta={
+              <p className="text-muted-foreground text-sm">
+                {project.description}
+              </p>
+            }
+            chips={
+              <StatusChip
+                tone={getStatusTone(project.status)}
+                label={project.status}
+              />
+            }
+            footer={
+              <div className="flex w-full items-center justify-between">
+                <span className="text-muted-foreground text-xs">
+                  {project.updatedAt.toLocaleDateString()}
+                </span>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onPress={() => onProjectClick?.(project)}
+                >
+                  Actions
+                </Button>
+              </div>
+            }
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function BillingTab({ subscription }: { subscription: Subscription | null }) {
+  if (!subscription) return null;
+
+  return (
+    <div className="space-y-6">
+      <div className="border-border bg-card rounded-xl border p-6">
+        <div className="flex items-start justify-between">
+          <div>
+            <h3 className="text-lg font-semibold">{subscription.plan} Plan</h3>
+            <p className="text-muted-foreground text-sm">
+              Current period:{' '}
+              {subscription.currentPeriodStart.toLocaleDateString()} -{' '}
+              {subscription.currentPeriodEnd.toLocaleDateString()}
+            </p>
+            <p className="text-muted-foreground text-sm">
+              Billing cycle: {subscription.billingCycle}
+            </p>
+          </div>
+          <StatusChip tone="success" label={subscription.status} />
+        </div>
+
+        <div className="mt-4 flex gap-3">
+          <Button variant="outline" onPress={() => alert('Upgrade clicked!')}>
+            Upgrade Plan
+          </Button>
+          <Button
+            variant="ghost"
+            onPress={() => alert('Manage Billing clicked!')}
+          >
+            Manage Billing
+          </Button>
+        </div>
+      </div>
+
+      {subscription.cancelAtPeriodEnd && (
+        <div className="border-border bg-destructive/10 text-destructive rounded-xl border p-4">
+          <p className="text-sm font-medium">
+            ⚠️ Your subscription will be cancelled at the end of the current
+            period.
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function SettingsTab() {
+  return (
+    <div className="space-y-6">
+      <div className="border-border bg-card rounded-xl border p-6">
+        <h3 className="mb-4 text-lg font-semibold">Organization Settings</h3>
+        <div className="space-y-4">
+          <div>
+            <label htmlFor="org-name" className="text-sm font-medium">
+              Organization Name
+            </label>
+            <input
+              id="org-name"
+              type="text"
+              defaultValue="Demo Organization"
+              className="border-input bg-background mt-1 block w-full rounded-md border px-3 py-2"
+            />
+          </div>
+          <div>
+            <label htmlFor="timezone" className="text-sm font-medium">
+              Default Timezone
+            </label>
+            <select
+              id="timezone"
+              className="border-input bg-background mt-1 block w-full rounded-md border px-3 py-2"
+            >
+              <option>UTC</option>
+              <option>America/New_York</option>
+              <option>Europe/London</option>
+              <option>Asia/Tokyo</option>
+            </select>
+          </div>
+          <div className="pt-2">
+            <Button onPress={() => alert('Settings saved!')}>
+              Save Settings
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}