@contractspec/example.saas-boilerplate 1.44.0

package/dist/shared/mock-data.d.ts

@@ -0,0 +1,86 @@
+//#region src/shared/mock-data.d.ts
+/**
+ * Shared mock data for saas-boilerplate handlers.
+ */
+declare const MOCK_PROJECTS: ({
+  id: string;
+  name: string;
+  description: string;
+  slug: string;
+  organizationId: string;
+  createdBy: string;
+  status: "ACTIVE";
+  isPublic: boolean;
+  tags: string[];
+  createdAt: Date;
+  updatedAt: Date;
+} | {
+  id: string;
+  name: string;
+  description: string;
+  slug: string;
+  organizationId: string;
+  createdBy: string;
+  status: "DRAFT";
+  isPublic: boolean;
+  tags: string[];
+  createdAt: Date;
+  updatedAt: Date;
+} | {
+  id: string;
+  name: string;
+  description: string;
+  slug: string;
+  organizationId: string;
+  createdBy: string;
+  status: "ARCHIVED";
+  isPublic: boolean;
+  tags: string[];
+  createdAt: Date;
+  updatedAt: Date;
+})[];
+declare const MOCK_SUBSCRIPTION: {
+  id: string;
+  organizationId: string;
+  planId: string;
+  planName: string;
+  status: "ACTIVE";
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+  limits: {
+    projects: number;
+    users: number;
+    storage: number;
+    apiCalls: number;
+  };
+  usage: {
+    projects: number;
+    users: number;
+    storage: number;
+    apiCalls: number;
+  };
+};
+declare const MOCK_USAGE_SUMMARY: {
+  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;
+  }[];
+};
+//#endregion
+export { MOCK_PROJECTS, MOCK_SUBSCRIPTION, MOCK_USAGE_SUMMARY };
+//# sourceMappingURL=mock-data.d.ts.map

package/dist/shared/mock-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-data.d.ts","names":[],"sources":["../../src/shared/mock-data.ts"],"sourcesContent":[],"mappings":";;AAMA;;cAAa;;;;;;EAyDA,SAAA,EAAA,MAAA;EAwBA,MAAA,EAAA,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAxBA;;;;;;sBAoBZ;oBAAA;;;;;;;;;;;;;;cAIY"}

package/dist/shared/mock-data.js

@@ -0,0 +1,138 @@
+//#region src/shared/mock-data.ts
+/**
+* Shared mock data for saas-boilerplate handlers.
+*/
+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",
+		isPublic: false,
+		tags: [
+			"marketing",
+			"website",
+			"redesign"
+		],
+		createdAt: /* @__PURE__ */ new Date("2024-01-15T10:00:00Z"),
+		updatedAt: /* @__PURE__ */ 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",
+		isPublic: false,
+		tags: [
+			"mobile",
+			"app",
+			"v2"
+		],
+		createdAt: /* @__PURE__ */ new Date("2024-02-01T09:00:00Z"),
+		updatedAt: /* @__PURE__ */ 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",
+		isPublic: false,
+		tags: ["api", "integration"],
+		createdAt: /* @__PURE__ */ new Date("2024-03-10T08:00:00Z"),
+		updatedAt: /* @__PURE__ */ 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",
+		isPublic: true,
+		tags: [
+			"analytics",
+			"dashboard",
+			"reporting"
+		],
+		createdAt: /* @__PURE__ */ new Date("2023-10-01T12:00:00Z"),
+		updatedAt: /* @__PURE__ */ new Date("2024-02-28T16:45:00Z")
+	}
+];
+const MOCK_SUBSCRIPTION = {
+	id: "sub-1",
+	organizationId: "demo-org",
+	planId: "pro",
+	planName: "Professional",
+	status: "ACTIVE",
+	currentPeriodStart: /* @__PURE__ */ new Date("2024-04-01T00:00:00Z"),
+	currentPeriodEnd: /* @__PURE__ */ new Date("2024-05-01T00:00:00Z"),
+	limits: {
+		projects: 25,
+		users: 10,
+		storage: 50,
+		apiCalls: 1e5
+	},
+	usage: {
+		projects: 4,
+		users: 5,
+		storage: 12.5,
+		apiCalls: 45230
+	}
+};
+const MOCK_USAGE_SUMMARY = {
+	organizationId: "demo-org",
+	period: "current_month",
+	apiCalls: {
+		total: 45230,
+		limit: 1e5,
+		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
+		}
+	]
+};
+
+//#endregion
+export { MOCK_PROJECTS, MOCK_SUBSCRIPTION, MOCK_USAGE_SUMMARY };
+//# sourceMappingURL=mock-data.js.map

package/dist/shared/mock-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-data.js","names":[],"sources":["../../src/shared/mock-data.ts"],"sourcesContent":["/**\n * Shared mock data for saas-boilerplate handlers.\n */\n\n// ============ Project Mock Data ============\n\nexport const MOCK_PROJECTS = [\n  {\n    id: 'proj-1',\n    name: 'Marketing Website',\n    description: 'Main company website redesign project',\n    slug: 'marketing-website',\n    organizationId: 'demo-org',\n    createdBy: 'user-1',\n    status: 'ACTIVE' as const,\n    isPublic: false,\n    tags: ['marketing', 'website', 'redesign'],\n    createdAt: new Date('2024-01-15T10:00:00Z'),\n    updatedAt: new Date('2024-03-20T14:30:00Z'),\n  },\n  {\n    id: 'proj-2',\n    name: 'Mobile App v2',\n    description: 'Next generation mobile application',\n    slug: 'mobile-app-v2',\n    organizationId: 'demo-org',\n    createdBy: 'user-2',\n    status: 'ACTIVE' as const,\n    isPublic: false,\n    tags: ['mobile', 'app', 'v2'],\n    createdAt: new Date('2024-02-01T09:00:00Z'),\n    updatedAt: new Date('2024-04-05T11:15:00Z'),\n  },\n  {\n    id: 'proj-3',\n    name: 'API Integration',\n    description: 'Third-party API integration project',\n    slug: 'api-integration',\n    organizationId: 'demo-org',\n    createdBy: 'user-1',\n    status: 'DRAFT' as const,\n    isPublic: false,\n    tags: ['api', 'integration'],\n    createdAt: new Date('2024-03-10T08:00:00Z'),\n    updatedAt: new Date('2024-03-10T08:00:00Z'),\n  },\n  {\n    id: 'proj-4',\n    name: 'Analytics Dashboard',\n    description: 'Internal analytics and reporting dashboard',\n    slug: 'analytics-dashboard',\n    organizationId: 'demo-org',\n    createdBy: 'user-3',\n    status: 'ARCHIVED' as const,\n    isPublic: true,\n    tags: ['analytics', 'dashboard', 'reporting'],\n    createdAt: new Date('2023-10-01T12:00:00Z'),\n    updatedAt: new Date('2024-02-28T16:45:00Z'),\n  },\n];\n\n// ============ Subscription Mock Data ============\n\nexport const MOCK_SUBSCRIPTION = {\n  id: 'sub-1',\n  organizationId: 'demo-org',\n  planId: 'pro',\n  planName: 'Professional',\n  status: 'ACTIVE' as const,\n  currentPeriodStart: new Date('2024-04-01T00:00:00Z'),\n  currentPeriodEnd: new Date('2024-05-01T00:00:00Z'),\n  limits: {\n    projects: 25,\n    users: 10,\n    storage: 50, // GB\n    apiCalls: 100000,\n  },\n  usage: {\n    projects: 4,\n    users: 5,\n    storage: 12.5,\n    apiCalls: 45230,\n  },\n};\n\n// ============ Usage Summary Mock Data ============\n\nexport const MOCK_USAGE_SUMMARY = {\n  organizationId: 'demo-org',\n  period: 'current_month',\n  apiCalls: {\n    total: 45230,\n    limit: 100000,\n    percentUsed: 45.23,\n  },\n  storage: {\n    totalGb: 12.5,\n    limitGb: 50,\n    percentUsed: 25,\n  },\n  activeProjects: 4,\n  activeUsers: 5,\n  breakdown: [\n    { date: '2024-04-01', apiCalls: 3200, storageGb: 12.1 },\n    { date: '2024-04-02', apiCalls: 2800, storageGb: 12.2 },\n    { date: '2024-04-03', apiCalls: 4100, storageGb: 12.3 },\n    { date: '2024-04-04', apiCalls: 3600, storageGb: 12.4 },\n    { date: '2024-04-05', apiCalls: 3800, storageGb: 12.5 },\n  ],\n};\n"],"mappings":";;;;AAMA,MAAa,gBAAgB;CAC3B;EACE,IAAI;EACJ,MAAM;EACN,aAAa;EACb,MAAM;EACN,gBAAgB;EAChB,WAAW;EACX,QAAQ;EACR,UAAU;EACV,MAAM;GAAC;GAAa;GAAW;GAAW;EAC1C,2BAAW,IAAI,KAAK,uBAAuB;EAC3C,2BAAW,IAAI,KAAK,uBAAuB;EAC5C;CACD;EACE,IAAI;EACJ,MAAM;EACN,aAAa;EACb,MAAM;EACN,gBAAgB;EAChB,WAAW;EACX,QAAQ;EACR,UAAU;EACV,MAAM;GAAC;GAAU;GAAO;GAAK;EAC7B,2BAAW,IAAI,KAAK,uBAAuB;EAC3C,2BAAW,IAAI,KAAK,uBAAuB;EAC5C;CACD;EACE,IAAI;EACJ,MAAM;EACN,aAAa;EACb,MAAM;EACN,gBAAgB;EAChB,WAAW;EACX,QAAQ;EACR,UAAU;EACV,MAAM,CAAC,OAAO,cAAc;EAC5B,2BAAW,IAAI,KAAK,uBAAuB;EAC3C,2BAAW,IAAI,KAAK,uBAAuB;EAC5C;CACD;EACE,IAAI;EACJ,MAAM;EACN,aAAa;EACb,MAAM;EACN,gBAAgB;EAChB,WAAW;EACX,QAAQ;EACR,UAAU;EACV,MAAM;GAAC;GAAa;GAAa;GAAY;EAC7C,2BAAW,IAAI,KAAK,uBAAuB;EAC3C,2BAAW,IAAI,KAAK,uBAAuB;EAC5C;CACF;AAID,MAAa,oBAAoB;CAC/B,IAAI;CACJ,gBAAgB;CAChB,QAAQ;CACR,UAAU;CACV,QAAQ;CACR,oCAAoB,IAAI,KAAK,uBAAuB;CACpD,kCAAkB,IAAI,KAAK,uBAAuB;CAClD,QAAQ;EACN,UAAU;EACV,OAAO;EACP,SAAS;EACT,UAAU;EACX;CACD,OAAO;EACL,UAAU;EACV,OAAO;EACP,SAAS;EACT,UAAU;EACX;CACF;AAID,MAAa,qBAAqB;CAChC,gBAAgB;CAChB,QAAQ;CACR,UAAU;EACR,OAAO;EACP,OAAO;EACP,aAAa;EACd;CACD,SAAS;EACP,SAAS;EACT,SAAS;EACT,aAAa;EACd;CACD,gBAAgB;CAChB,aAAa;CACb,WAAW;EACT;GAAE,MAAM;GAAc,UAAU;GAAM,WAAW;GAAM;EACvD;GAAE,MAAM;GAAc,UAAU;GAAM,WAAW;GAAM;EACvD;GAAE,MAAM;GAAc,UAAU;GAAM,WAAW;GAAM;EACvD;GAAE,MAAM;GAAc,UAAU;GAAM,WAAW;GAAM;EACvD;GAAE,MAAM;GAAc,UAAU;GAAM,WAAW;GAAM;EACxD;CACF"}

package/example.ts

@@ -0,0 +1 @@
+export { default } from './src/example';

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@contractspec/example.saas-boilerplate",
+  "version": "1.44.0",
+  "description": "SaaS Boilerplate - Users, Orgs, Projects, Billing, Settings",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./billing": "./dist/billing/index.js",
+    "./billing/billing.entity": "./dist/billing/billing.entity.js",
+    "./billing/billing.enum": "./dist/billing/billing.enum.js",
+    "./billing/billing.event": "./dist/billing/billing.event.js",
+    "./billing/billing.handler": "./dist/billing/billing.handler.js",
+    "./billing/billing.operations": "./dist/billing/billing.operations.js",
+    "./billing/billing.presentation": "./dist/billing/billing.presentation.js",
+    "./billing/billing.schema": "./dist/billing/billing.schema.js",
+    "./dashboard": "./dist/dashboard/index.js",
+    "./dashboard/dashboard.presentation": "./dist/dashboard/dashboard.presentation.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/saas-boilerplate.docblock": "./dist/docs/saas-boilerplate.docblock.js",
+    "./example": "./dist/example.js",
+    "./handlers": "./dist/handlers/index.js",
+    "./presentations": "./dist/presentations/index.js",
+    "./project": "./dist/project/index.js",
+    "./project/project.entity": "./dist/project/project.entity.js",
+    "./project/project.enum": "./dist/project/project.enum.js",
+    "./project/project.event": "./dist/project/project.event.js",
+    "./project/project.handler": "./dist/project/project.handler.js",
+    "./project/project.operations": "./dist/project/project.operations.js",
+    "./project/project.presentation": "./dist/project/project.presentation.js",
+    "./project/project.schema": "./dist/project/project.schema.js",
+    "./saas-boilerplate.feature": "./dist/saas-boilerplate.feature.js",
+    "./settings": "./dist/settings/index.js",
+    "./settings/settings.entity": "./dist/settings/settings.entity.js",
+    "./settings/settings.enum": "./dist/settings/settings.enum.js",
+    "./shared/mock-data": "./dist/shared/mock-data.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun run"
+  },
+  "dependencies": {
+    "@contractspec/lib.schema": "1.44.0",
+    "@contractspec/lib.contracts": "1.44.0",
+    "@contractspec/lib.bus": "1.44.0",
+    "@contractspec/lib.identity-rbac": "1.44.0",
+    "@contractspec/lib.jobs": "1.44.0",
+    "@contractspec/module.audit-trail": "1.44.0",
+    "@contractspec/module.notifications": "1.44.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.44.0",
+    "@contractspec/tool.typescript": "1.44.0",
+    "tsdown": "^0.18.3",
+    "typescript": "^5.9.3"
+  },
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./billing": "./dist/billing/index.js",
+      "./billing/billing.contracts": "./dist/billing/billing.operations.js",
+      "./billing/billing.entity": "./dist/billing/billing.entity.js",
+      "./billing/billing.enum": "./dist/billing/billing.enum.js",
+      "./billing/billing.event": "./dist/billing/billing.event.js",
+      "./billing/billing.handler": "./dist/billing/billing.handler.js",
+      "./billing/billing.presentation": "./dist/billing/billing.presentation.js",
+      "./billing/billing.schema": "./dist/billing/billing.schema.js",
+      "./dashboard": "./dist/dashboard/index.js",
+      "./dashboard/dashboard.presentation": "./dist/dashboard/dashboard.presentation.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/saas-boilerplate.docblock": "./dist/docs/saas-boilerplate.docblock.js",
+      "./example": "./dist/example.js",
+      "./handlers": "./dist/handlers/index.js",
+      "./presentations": "./dist/presentations/index.js",
+      "./project": "./dist/project/index.js",
+      "./project/project.contracts": "./dist/project/project.operations.js",
+      "./project/project.entity": "./dist/project/project.entity.js",
+      "./project/project.enum": "./dist/project/project.enum.js",
+      "./project/project.event": "./dist/project/project.event.js",
+      "./project/project.handler": "./dist/project/project.handler.js",
+      "./project/project.presentation": "./dist/project/project.presentation.js",
+      "./project/project.schema": "./dist/project/project.schema.js",
+      "./saas-boilerplate.feature": "./dist/saas-boilerplate.feature.js",
+      "./settings": "./dist/settings/index.js",
+      "./settings/settings.entity": "./dist/settings/settings.entity.js",
+      "./settings/settings.enum": "./dist/settings/settings.enum.js",
+      "./shared/mock-data": "./dist/shared/mock-data.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/saas-boilerplate"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/billing/billing.entity.ts

@@ -0,0 +1,158 @@
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index,
+} from '@contractspec/lib.schema';
+
+/**
+ * Subscription status enum for entities.
+ */
+export const SubscriptionStatusEnum = defineEntityEnum({
+  name: 'SubscriptionStatus',
+  values: ['TRIALING', 'ACTIVE', 'PAST_DUE', 'CANCELED', 'PAUSED'] as const,
+  schema: 'saas_app',
+  description: 'Status of a subscription.',
+});
+
+/**
+ * Subscription entity - organization subscription info.
+ */
+export const SubscriptionEntity = defineEntity({
+  name: 'Subscription',
+  description: 'Organization subscription/plan information.',
+  schema: 'saas_app',
+  map: 'subscription',
+  fields: {
+    id: field.id(),
+    organizationId: field.foreignKey({ isUnique: true }),
+
+    // Plan info
+    planId: field.string({ description: 'Plan identifier' }),
+    planName: field.string({ description: 'Plan display name' }),
+
+    // Status
+    status: field.enum('SubscriptionStatus'),
+
+    // Billing cycle
+    currentPeriodStart: field.dateTime(),
+    currentPeriodEnd: field.dateTime(),
+
+    // Trial
+    trialEndsAt: field.dateTime({ isOptional: true }),
+
+    // Cancellation
+    cancelAtPeriodEnd: field.boolean({ default: false }),
+    canceledAt: field.dateTime({ isOptional: true }),
+
+    // External reference
+    stripeSubscriptionId: field.string({ isOptional: true }),
+    stripeCustomerId: field.string({ isOptional: true }),
+
+    // Metadata
+    metadata: field.json({ isOptional: true }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+  },
+  enums: [SubscriptionStatusEnum],
+});
+
+/**
+ * BillingUsage entity - track feature usage.
+ */
+export const BillingUsageEntity = defineEntity({
+  name: 'BillingUsage',
+  description: 'Track usage of metered features.',
+  schema: 'saas_app',
+  map: 'billing_usage',
+  fields: {
+    id: field.id(),
+    organizationId: field.foreignKey(),
+
+    // Feature
+    feature: field.string({
+      description: 'Feature being tracked (e.g., "api_calls", "storage_gb")',
+    }),
+
+    // Usage
+    quantity: field.int({ description: 'Usage quantity' }),
+    unit: field.string({
+      isOptional: true,
+      description: 'Unit of measurement',
+    }),
+
+    // Period
+    billingPeriod: field.string({
+      description: 'Billing period (e.g., "2024-01")',
+    }),
+
+    // Aggregation
+    recordedAt: field.dateTime({ description: 'When usage was recorded' }),
+
+    // Source
+    sourceId: field.string({
+      isOptional: true,
+      description: 'Source of usage (e.g., request ID)',
+    }),
+    sourceType: field.string({ isOptional: true }),
+
+    // Metadata
+    metadata: field.json({ isOptional: true }),
+  },
+  indexes: [
+    index.on(['organizationId', 'feature', 'billingPeriod']),
+    index.on(['organizationId', 'recordedAt']),
+  ],
+});
+
+/**
+ * UsageLimit entity - feature usage limits per plan.
+ */
+export const UsageLimitEntity = defineEntity({
+  name: 'UsageLimit',
+  description: 'Usage limits per plan/organization.',
+  schema: 'saas_app',
+  map: 'usage_limit',
+  fields: {
+    id: field.id(),
+
+    // Scope
+    planId: field.string({
+      isOptional: true,
+      description: 'Plan this limit applies to',
+    }),
+    organizationId: field.string({
+      isOptional: true,
+      description: 'Org-specific override',
+    }),
+
+    // Limit
+    feature: field.string({ description: 'Feature being limited' }),
+    limit: field.int({ description: 'Maximum allowed usage' }),
+    resetPeriod: field.string({
+      default: '"monthly"',
+      description: 'When limit resets',
+    }),
+
+    // Soft/hard limit
+    isSoftLimit: field.boolean({
+      default: false,
+      description: 'Whether to warn vs block',
+    }),
+    overage: field.boolean({
+      default: false,
+      description: 'Whether overage is allowed',
+    }),
+    overageRate: field.float({
+      isOptional: true,
+      description: 'Cost per unit over limit',
+    }),
+
+    // Timestamps
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+  },
+  indexes: [index.unique(['planId', 'feature'])],
+});

package/src/billing/billing.enum.ts

@@ -0,0 +1,23 @@
+import { defineEnum } from '@contractspec/lib.schema';
+
+/**
+ * Subscription status enum for contract schemas.
+ * Note: Entity enum is defined separately in billing.entity.ts
+ */
+export const SubscriptionStatusSchemaEnum = defineEnum('SubscriptionStatus', [
+  'TRIALING',
+  'ACTIVE',
+  'PAST_DUE',
+  'CANCELED',
+  'PAUSED',
+]);
+
+/**
+ * Feature access reason enum.
+ */
+export const FeatureAccessReasonEnum = defineEnum('FeatureAccessReason', [
+  'included',
+  'limit_available',
+  'limit_reached',
+  'not_in_plan',
+]);

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,
+    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,
+    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,
+    description: 'Subscription status has changed.',
+    stability: 'stable',
+    owners: ['@saas-team'],
+    tags: ['billing', 'subscription', 'changed'],
+  },
+  payload: SubscriptionChangedPayload,
+});