@contractspec/example.saas-boilerplate 1.46.0 → 1.47.0

package/src/handlers/saas.handlers.ts

@@ -0,0 +1,300 @@
+/**
+ * Runtime-local SaaS Boilerplate handlers
+ *
+ * Database-backed handlers for project and billing management.
+ */
+import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { web } from '@contractspec/lib.runtime-sandbox';
+const { generateId } = web;
+
+// ============ Types ============
+
+export interface Project {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  name: string;
+  description?: string;
+  status: 'DRAFT' | 'ACTIVE' | 'ARCHIVED';
+  tier: 'FREE' | 'PRO' | 'ENTERPRISE';
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface Subscription {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  plan: 'FREE' | 'PRO' | 'ENTERPRISE';
+  status: 'ACTIVE' | 'PAST_DUE' | 'CANCELED';
+  billingCycle: 'MONTHLY' | 'YEARLY';
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+  cancelAtPeriodEnd: boolean;
+}
+
+export interface ListProjectsInput {
+  projectId: string;
+  organizationId?: string;
+  status?: Project['status'] | 'all';
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListProjectsOutput {
+  items: Project[];
+  total: number;
+  hasMore: boolean;
+}
+
+export interface CreateProjectInput {
+  name: string;
+  description?: string;
+  tier?: Project['tier'];
+}
+
+export interface UpdateProjectInput {
+  id: string;
+  name?: string;
+  description?: string;
+  status?: Project['status'];
+}
+
+// ============ Row Types ============
+
+interface ProjectRow extends Record<string, unknown> {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  name: string;
+  description: string | null;
+  status: string;
+  tier: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface SubscriptionRow extends Record<string, unknown> {
+  id: string;
+  projectId: string;
+  organizationId: string;
+  plan: string;
+  status: string;
+  billingCycle: string;
+  currentPeriodStart: string;
+  currentPeriodEnd: string;
+  cancelAtPeriodEnd: number;
+}
+
+function rowToProject(row: ProjectRow): Project {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    name: row.name,
+    description: row.description ?? undefined,
+    status: row.status as Project['status'],
+    tier: row.tier as Project['tier'],
+    createdAt: new Date(row.createdAt),
+    updatedAt: new Date(row.updatedAt),
+  };
+}
+
+function rowToSubscription(row: SubscriptionRow): Subscription {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    organizationId: row.organizationId,
+    plan: row.plan as Subscription['plan'],
+    status: row.status as Subscription['status'],
+    billingCycle: row.billingCycle as Subscription['billingCycle'],
+    currentPeriodStart: new Date(row.currentPeriodStart),
+    currentPeriodEnd: new Date(row.currentPeriodEnd),
+    cancelAtPeriodEnd: Boolean(row.cancelAtPeriodEnd),
+  };
+}
+
+// ============ Handler Factory ============
+
+export function createSaasHandlers(db: DatabasePort) {
+  /**
+   * List projects
+   */
+  async function listProjects(
+    input: ListProjectsInput
+  ): Promise<ListProjectsOutput> {
+    const {
+      projectId,
+      organizationId,
+      status,
+      search,
+      limit = 20,
+      offset = 0,
+    } = input;
+
+    let whereClause = 'WHERE projectId = ?';
+    const params: (string | number)[] = [projectId];
+
+    if (organizationId) {
+      whereClause += ' AND organizationId = ?';
+      params.push(organizationId);
+    }
+
+    if (status && status !== 'all') {
+      whereClause += ' AND status = ?';
+      params.push(status);
+    }
+
+    if (search) {
+      whereClause += ' AND (name LIKE ? OR description LIKE ?)';
+      params.push(`%${search}%`, `%${search}%`);
+    }
+
+    const countResult = (
+      await db.query(
+        `SELECT COUNT(*) as count FROM saas_project ${whereClause}`,
+        params
+      )
+    ).rows as unknown as { count: number }[];
+    const total = countResult[0]?.count ?? 0;
+
+    const rows = (
+      await db.query(
+        `SELECT * FROM saas_project ${whereClause} ORDER BY createdAt DESC LIMIT ? OFFSET ?`,
+        [...params, limit, offset]
+      )
+    ).rows as unknown as ProjectRow[];
+
+    return {
+      items: rows.map(rowToProject),
+      total,
+      hasMore: offset + rows.length < total,
+    };
+  }
+
+  /**
+   * Get a single project
+   */
+  async function getProject(id: string): Promise<Project | null> {
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [id])
+    ).rows as unknown as ProjectRow[];
+    return rows[0] ? rowToProject(rows[0]) : null;
+  }
+
+  /**
+   * Create a project
+   */
+  async function createProject(
+    input: CreateProjectInput,
+    context: { projectId: string; organizationId: string }
+  ): Promise<Project> {
+    const id = generateId('proj');
+    const now = new Date().toISOString();
+
+    await db.execute(
+      `INSERT INTO saas_project (id, projectId, organizationId, name, description, status, tier, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        context.projectId,
+        context.organizationId,
+        input.name,
+        input.description ?? null,
+        'DRAFT',
+        input.tier ?? 'FREE',
+        now,
+        now,
+      ]
+    );
+
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [id])
+    ).rows as unknown as ProjectRow[];
+
+    return rowToProject(rows[0]!);
+  }
+
+  /**
+   * Update a project
+   */
+  async function updateProject(input: UpdateProjectInput): Promise<Project> {
+    const now = new Date().toISOString();
+    const updates: string[] = ['updatedAt = ?'];
+    const params: (string | null)[] = [now];
+
+    if (input.name !== undefined) {
+      updates.push('name = ?');
+      params.push(input.name);
+    }
+
+    if (input.description !== undefined) {
+      updates.push('description = ?');
+      params.push(input.description);
+    }
+
+    if (input.status !== undefined) {
+      updates.push('status = ?');
+      params.push(input.status);
+    }
+
+    params.push(input.id);
+
+    await db.execute(
+      `UPDATE saas_project SET ${updates.join(', ')} WHERE id = ?`,
+      params
+    );
+
+    const rows = (
+      await db.query(`SELECT * FROM saas_project WHERE id = ?`, [input.id])
+    ).rows as unknown as ProjectRow[];
+
+    if (!rows[0]) {
+      throw new Error('NOT_FOUND');
+    }
+
+    return rowToProject(rows[0]);
+  }
+
+  /**
+   * Delete a project
+   */
+  async function deleteProject(id: string): Promise<void> {
+    await db.execute(`DELETE FROM saas_project WHERE id = ?`, [id]);
+  }
+
+  /**
+   * Get subscription for an organization
+   */
+  async function getSubscription(input: {
+    projectId: string;
+    organizationId?: string;
+  }): Promise<Subscription | null> {
+    let query = `SELECT * FROM saas_subscription WHERE projectId = ?`;
+    const params: string[] = [input.projectId];
+
+    if (input.organizationId) {
+      query += ' AND organizationId = ?';
+      params.push(input.organizationId);
+    }
+
+    query += ' LIMIT 1';
+
+    const rows = (await db.query(query, params))
+      .rows as unknown as SubscriptionRow[];
+    return rows[0] ? rowToSubscription(rows[0]) : null;
+  }
+
+  return {
+    listProjects,
+    getProject,
+    createProject,
+    updateProject,
+    deleteProject,
+    getSubscription,
+  };
+}
+
+export type SaasHandlers = ReturnType<typeof createSaasHandlers>;

package/src/index.ts

@@ -9,6 +9,11 @@ export * from './dashboard';
 
 // Export feature and example metadata
 export * from './saas-boilerplate.feature';
+export * from './ui';
+export {
+  createSaasHandlers,
+  type SaasHandlers,
+} from './handlers/saas.handlers';
 export { default as example } from './example';
 
 // Import docs for registration

package/src/project/project.presentation.ts

@@ -1,11 +1,10 @@
-import type { PresentationSpec } from '@contractspec/lib.contracts';
-import { StabilityEnum } from '@contractspec/lib.contracts';
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
 import { ProjectModel } from './project.schema';
 
 /**
  * Presentation for displaying a list of projects.
  */
-export const ProjectListPresentation: PresentationSpec = {
+export const ProjectListPresentation = definePresentation({
   meta: {
     key: 'saas.project.list',
     version: '1.0.0',
@@ -29,12 +28,12 @@ export const ProjectListPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.projects.enabled'],
   },
-};
+});
 
 /**
  * Presentation for project detail view.
  */
-export const ProjectDetailPresentation: PresentationSpec = {
+export const ProjectDetailPresentation = definePresentation({
   meta: {
     key: 'saas.project.detail',
     version: '1.0.0',
@@ -56,4 +55,4 @@ export const ProjectDetailPresentation: PresentationSpec = {
   policy: {
     flags: ['saas.projects.enabled'],
   },
-};
+});

package/src/saas-boilerplate.feature.ts

@@ -3,13 +3,13 @@
  *
  * Defines the feature module for the SaaS application foundation.
  */
-import type { FeatureModuleSpec } from '@contractspec/lib.contracts';
+import { defineFeature } from '@contractspec/lib.contracts';
 
 /**
  * SaaS Boilerplate feature module that bundles project management,
  * billing, and settings operations into an installable feature.
  */
-export const SaasBoilerplateFeature: FeatureModuleSpec = {
+export const SaasBoilerplateFeature = defineFeature({
   meta: {
     key: 'saas-boilerplate',
     title: 'SaaS Boilerplate',
@@ -110,4 +110,4 @@ export const SaasBoilerplateFeature: FeatureModuleSpec = {
       { key: 'notifications', version: '1.0.0' },
     ],
   },
-};
+});

package/src/seeders/index.ts

@@ -0,0 +1,28 @@
+import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
+
+export async function seedSaasBoilerplate(params: {
+  projectId: string;
+  db: DatabasePort;
+}) {
+  const { projectId, db } = params;
+
+  const existing = await db.query(
+    `SELECT COUNT(*) as count FROM saas_project WHERE "projectId" = $1`,
+    [projectId]
+  );
+  if ((existing.rows[0]?.count as number) > 0) return;
+
+  await db.execute(
+    `INSERT INTO saas_project (id, "projectId", "organizationId", name, description, status, tier)
+     VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+    [
+      'saas_proj_1',
+      projectId,
+      'org_demo',
+      'Demo Project',
+      'A demo SaaS project',
+      'ACTIVE',
+      'PRO',
+    ]
+  );
+}

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' }],
+    },
+  ],
+});