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

package/src/billing/billing.event.ts

@@ -0,0 +1,108 @@
+import { ScalarTypeEnum, defineSchemaModel } from '@contractspec/lib.schema';
+import { defineEvent } from '@contractspec/lib.contracts';
+
+/**
+ * Payload when feature usage is recorded.
+ */
+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 },
+  },
+});
+
+/**
+ * Payload when usage limit is reached.
+ */
+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 },
+  },
+});
+
+/**
+ * Payload when subscription status changes.
+ */
+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 },
+  },
+});
+
+/**
+ * Event: Feature usage has been recorded.
+ */
+export const UsageRecordedEvent = defineEvent({
+  meta: {
+    key: 'billing.usage.recorded',
+    version: '1.0.0',
+    description: 'Feature usage has been recorded.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['billing', 'usage', 'recorded'],
+  },
+  payload: UsageRecordedPayload,
+});
+
+/**
+ * Event: Usage limit has been reached for a feature.
+ */
+export const UsageLimitReachedEvent = defineEvent({
+  meta: {
+    key: 'billing.limit.reached',
+    version: '1.0.0',
+    description: 'Usage limit has been reached for a feature.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['billing', 'limit', 'reached'],
+  },
+  payload: UsageLimitReachedPayload,
+});
+
+/**
+ * Event: Subscription status has changed.
+ */
+export const SubscriptionChangedEvent = defineEvent({
+  meta: {
+    key: 'billing.subscription.changed',
+    version: '1.0.0',
+    description: 'Subscription status has changed.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['billing', 'subscription', 'changed'],
+  },
+  payload: SubscriptionChangedPayload,
+});

package/src/billing/billing.handler.ts

@@ -0,0 +1,137 @@
+/**
+ * Mock handlers for Billing contracts.
+ */
+import { MOCK_SUBSCRIPTION, MOCK_USAGE_SUMMARY } from '../shared/mock-data';
+
+// Types inferred from contract schemas
+export interface Subscription {
+  id: string;
+  organizationId: string;
+  planId: string;
+  planName: string;
+  status: 'ACTIVE' | 'TRIALING' | 'PAST_DUE' | 'CANCELED' | 'UNPAID';
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+  limits: {
+    projects: number;
+    users: number;
+    storage: number;
+    apiCalls: number;
+  };
+  usage: {
+    projects: number;
+    users: number;
+    storage: number;
+    apiCalls: number;
+  };
+}
+
+export interface UsageSummary {
+  organizationId: string;
+  period: string;
+  apiCalls: {
+    total: number;
+    limit: number;
+    percentUsed: number;
+  };
+  storage: {
+    totalGb: number;
+    limitGb: number;
+    percentUsed: number;
+  };
+  activeProjects: number;
+  activeUsers: number;
+  breakdown: {
+    date: string;
+    apiCalls: number;
+    storageGb: number;
+  }[];
+}
+
+export interface RecordUsageInput {
+  metric: string;
+  quantity: number;
+  timestamp?: Date;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CheckFeatureAccessInput {
+  feature: string;
+}
+
+export interface CheckFeatureAccessOutput {
+  allowed: boolean;
+  reason?:
+    | 'PLAN_LIMIT'
+    | 'FEATURE_NOT_INCLUDED'
+    | 'QUOTA_EXCEEDED'
+    | 'SUBSCRIPTION_INACTIVE';
+  currentUsage?: number;
+  limit?: number;
+}
+
+/**
+ * Mock handler for GetSubscriptionContract.
+ */
+export async function mockGetSubscriptionHandler(): Promise<Subscription> {
+  return MOCK_SUBSCRIPTION;
+}
+
+/**
+ * Mock handler for GetUsageSummaryContract.
+ */
+export async function mockGetUsageSummaryHandler(input: {
+  period?: string;
+}): Promise<UsageSummary> {
+  return {
+    ...MOCK_USAGE_SUMMARY,
+    period: input.period ?? 'current_month',
+  };
+}
+
+/**
+ * Mock handler for RecordUsageContract.
+ */
+export async function mockRecordUsageHandler(
+  input: RecordUsageInput
+): Promise<{ recorded: boolean; newTotal: number }> {
+  const currentUsage = MOCK_USAGE_SUMMARY.apiCalls.total;
+  const newTotal = currentUsage + input.quantity;
+
+  return {
+    recorded: true,
+    newTotal,
+  };
+}
+
+/**
+ * Mock handler for CheckFeatureAccessContract.
+ */
+export async function mockCheckFeatureAccessHandler(
+  input: CheckFeatureAccessInput
+): Promise<CheckFeatureAccessOutput> {
+  const { feature } = input;
+
+  const featureMap: Record<string, CheckFeatureAccessOutput> = {
+    custom_domains: {
+      allowed: true,
+    },
+    api_access: {
+      allowed: true,
+      currentUsage: MOCK_USAGE_SUMMARY.apiCalls.total,
+      limit: MOCK_USAGE_SUMMARY.apiCalls.limit,
+    },
+    advanced_analytics: {
+      allowed: false,
+      reason: 'FEATURE_NOT_INCLUDED',
+    },
+    unlimited_projects: {
+      allowed: false,
+      reason: 'PLAN_LIMIT',
+      currentUsage: MOCK_SUBSCRIPTION.usage.projects,
+      limit: MOCK_SUBSCRIPTION.limits.projects,
+    },
+  };
+
+  return featureMap[feature] ?? { allowed: true };
+}

package/src/billing/billing.operations.ts

@@ -0,0 +1,187 @@
+import { defineCommand, defineQuery } from '@contractspec/lib.contracts';
+import {
+  CheckFeatureAccessInputModel,
+  CheckFeatureAccessOutputModel,
+  GetUsageSummaryInputModel,
+  GetUsageSummaryOutputModel,
+  RecordUsageInputModel,
+  RecordUsageOutputModel,
+  SubscriptionModel,
+  UsageRecordedPayloadModel,
+} from './billing.schema';
+
+const OWNERS = ['@example.saas-boilerplate'] as const;
+
+/**
+ * Get subscription status.
+ */
+export const GetSubscriptionContract = defineQuery({
+  meta: {
+    key: 'saas.billing.subscription.get',
+    version: '1.0.0',
+    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',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-subscription-happy-path',
+        given: ['Organization has active subscription'],
+        when: ['User requests subscription status'],
+        then: ['Subscription details are returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-basic',
+        input: null,
+        output: {
+          plan: 'pro',
+          status: 'active',
+          currentPeriodEnd: '2025-02-01T00:00:00Z',
+        },
+      },
+    ],
+  },
+});
+
+/**
+ * Record feature usage.
+ */
+export const RecordUsageContract = defineCommand({
+  meta: {
+    key: 'saas.billing.usage.record',
+    version: '1.0.0',
+    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: [
+      {
+        key: 'billing.usage.recorded',
+        version: '1.0.0',
+        when: 'Usage is recorded',
+        payload: UsageRecordedPayloadModel,
+      },
+    ],
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'record-usage-happy-path',
+        given: ['Organization exists'],
+        when: ['System records feature usage'],
+        then: ['Usage is recorded'],
+      },
+    ],
+    examples: [
+      {
+        key: 'record-api-call',
+        input: { feature: 'api_calls', quantity: 1, idempotencyKey: 'abc-123' },
+        output: { recorded: true, currentUsage: 100 },
+      },
+    ],
+  },
+});
+
+/**
+ * Get usage summary.
+ */
+export const GetUsageSummaryContract = defineQuery({
+  meta: {
+    key: 'saas.billing.usage.summary',
+    version: '1.0.0',
+    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',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'get-usage-happy-path',
+        given: ['Organization has usage history'],
+        when: ['User requests usage summary'],
+        then: ['Usage metrics are returned'],
+      },
+    ],
+    examples: [
+      {
+        key: 'get-current-usage',
+        input: { period: 'current' },
+        output: { features: [{ name: 'api_calls', used: 100, limit: 1000 }] },
+      },
+    ],
+  },
+});
+
+/**
+ * Check feature access.
+ */
+export const CheckFeatureAccessContract = defineQuery({
+  meta: {
+    key: 'saas.billing.feature.check',
+    version: '1.0.0',
+    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',
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: 'check-access-granted',
+        given: ['Organization is on Pro plan'],
+        when: ['User checks access to Pro feature'],
+        then: ['Access is granted'],
+      },
+    ],
+    examples: [
+      {
+        key: 'check-advanced-reports',
+        input: { feature: 'advanced_reports' },
+        output: { hasAccess: true, reason: 'Included in Pro plan' },
+      },
+    ],
+  },
+});

package/src/billing/billing.presentation.ts

@@ -0,0 +1,56 @@
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
+
+/**
+ * Presentation for subscription overview.
+ */
+export const SubscriptionPresentation = definePresentation({
+  meta: {
+    key: 'saas.billing.subscription',
+    version: '1.0.0',
+    title: 'Subscription Status',
+    description:
+      'Subscription status with plan info, limits, and current usage',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['billing', 'subscription'],
+    stability: StabilityEnum.Beta,
+    goal: 'View subscription plan and status',
+    context: 'Billing section',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'SubscriptionView',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.billing.enabled'],
+  },
+});
+
+/**
+ * Presentation for usage dashboard.
+ */
+export const UsageDashboardPresentation = definePresentation({
+  meta: {
+    key: 'saas.billing.usage',
+    version: '1.0.0',
+    title: 'Usage Dashboard',
+    description: 'Usage metrics and breakdown by resource type',
+    domain: 'saas-boilerplate',
+    owners: ['@saas-team'],
+    tags: ['billing', 'usage', 'metrics'],
+    stability: StabilityEnum.Beta,
+    goal: 'Monitor feature usage and limits',
+    context: 'Billing section',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'UsageDashboardView',
+  },
+  targets: ['react', 'markdown'],
+  policy: {
+    flags: ['saas.billing.enabled'],
+  },
+});

package/src/billing/billing.schema.ts

@@ -0,0 +1,133 @@
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import {
+  SubscriptionStatusSchemaEnum,
+  FeatureAccessReasonEnum,
+} from './billing.enum';
+
+/**
+ * Organization subscription details schema.
+ */
+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 },
+  },
+});
+
+/**
+ * Usage summary for a feature schema.
+ */
+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 },
+  },
+});
+
+/**
+ * Input for recording feature usage.
+ */
+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 },
+  },
+});
+
+/**
+ * Output for recording feature usage.
+ */
+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 },
+  },
+});
+
+/**
+ * Payload for usage.recorded event.
+ */
+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 },
+  },
+});
+
+/**
+ * Input for getting usage summary.
+ */
+export const GetUsageSummaryInputModel = defineSchemaModel({
+  name: 'GetUsageSummaryInput',
+  description: 'Input for getting usage summary',
+  fields: {
+    billingPeriod: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+/**
+ * Output for usage summary.
+ */
+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 },
+  },
+});
+
+/**
+ * Input for checking feature access.
+ */
+export const CheckFeatureAccessInputModel = defineSchemaModel({
+  name: 'CheckFeatureAccessInput',
+  description: 'Input for checking feature access',
+  fields: {
+    feature: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+/**
+ * Output for feature access check.
+ */
+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 },
+  },
+});

package/src/billing/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Billing domain - subscription, usage tracking, and feature access.
+ */
+
+// Enums
+export {
+  SubscriptionStatusSchemaEnum,
+  FeatureAccessReasonEnum,
+} from './billing.enum';
+
+// Schema models
+export {
+  SubscriptionModel,
+  UsageSummaryModel,
+  RecordUsageInputModel,
+  RecordUsageOutputModel,
+  UsageRecordedPayloadModel,
+  GetUsageSummaryInputModel,
+  GetUsageSummaryOutputModel,
+  CheckFeatureAccessInputModel,
+  CheckFeatureAccessOutputModel,
+} from './billing.schema';
+
+// Contracts
+export {
+  GetSubscriptionContract,
+  RecordUsageContract,
+  GetUsageSummaryContract,
+  CheckFeatureAccessContract,
+} from './billing.operations';
+
+// Events
+export {
+  UsageRecordedEvent,
+  UsageLimitReachedEvent,
+  SubscriptionChangedEvent,
+} from './billing.event';
+
+// Entities
+export {
+  SubscriptionStatusEnum,
+  SubscriptionEntity,
+  BillingUsageEntity,
+  UsageLimitEntity,
+} from './billing.entity';
+
+// Presentations
+export {
+  SubscriptionPresentation,
+  UsageDashboardPresentation,
+} from './billing.presentation';
+
+// Handlers
+export {
+  mockGetSubscriptionHandler,
+  mockGetUsageSummaryHandler,
+  mockRecordUsageHandler,
+  mockCheckFeatureAccessHandler,
+  type Subscription,
+  type UsageSummary,
+  type RecordUsageInput,
+  type CheckFeatureAccessInput,
+  type CheckFeatureAccessOutput,
+} from './billing.handler';