@contractspec/example.saas-boilerplate 3.7.6 → 3.8.2

package/src/billing/billing.operations.ts

@@ -1,13 +1,13 @@
 import { defineCommand, defineQuery } from '@contractspec/lib.contracts-spec';
 import {
-  CheckFeatureAccessInputModel,
-  CheckFeatureAccessOutputModel,
-  GetUsageSummaryInputModel,
-  GetUsageSummaryOutputModel,
-  RecordUsageInputModel,
-  RecordUsageOutputModel,
-  SubscriptionModel,
-  UsageRecordedPayloadModel,
+	CheckFeatureAccessInputModel,
+	CheckFeatureAccessOutputModel,
+	GetUsageSummaryInputModel,
+	GetUsageSummaryOutputModel,
+	RecordUsageInputModel,
+	RecordUsageOutputModel,
+	SubscriptionModel,
+	UsageRecordedPayloadModel,
 } from './billing.schema';
 
 const OWNERS = ['@example.saas-boilerplate'] as const;
@@ -16,172 +16,172 @@ 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',
-        },
-      },
-    ],
-  },
+	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 },
-      },
-    ],
-  },
+	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 }] },
-      },
-    ],
-  },
+	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' },
-      },
-    ],
-  },
+	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

@@ -1,59 +1,59 @@
 import {
-  definePresentation,
-  StabilityEnum,
+	definePresentation,
+	StabilityEnum,
 } from '@contractspec/lib.contracts-spec';
 
 /**
  * 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'],
-  },
+	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'],
-  },
+	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

@@ -1,133 +1,133 @@
 import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 import {
-  SubscriptionStatusSchemaEnum,
-  FeatureAccessReasonEnum,
+	FeatureAccessReasonEnum,
+	SubscriptionStatusSchemaEnum,
 } 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 },
-  },
+	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 },
-  },
+	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 },
-  },
+	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 },
-  },
+	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 },
-  },
+	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 },
-  },
+	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 },
-  },
+	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 },
-  },
+	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 },
-  },
+	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 },
+	},
 });