@contractspec/example.saas-boilerplate 1.57.0 → 1.58.0

package/dist/node/billing/index.js

@@ -0,0 +1,688 @@
+// src/billing/billing.entity.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var SubscriptionStatusEnum = defineEntityEnum({
+  name: "SubscriptionStatus",
+  values: ["TRIALING", "ACTIVE", "PAST_DUE", "CANCELED", "PAUSED"],
+  schema: "saas_app",
+  description: "Status of a subscription."
+});
+var SubscriptionEntity = defineEntity({
+  name: "Subscription",
+  description: "Organization subscription/plan information.",
+  schema: "saas_app",
+  map: "subscription",
+  fields: {
+    id: field.id(),
+    organizationId: field.foreignKey({ isUnique: true }),
+    planId: field.string({ description: "Plan identifier" }),
+    planName: field.string({ description: "Plan display name" }),
+    status: field.enum("SubscriptionStatus"),
+    currentPeriodStart: field.dateTime(),
+    currentPeriodEnd: field.dateTime(),
+    trialEndsAt: field.dateTime({ isOptional: true }),
+    cancelAtPeriodEnd: field.boolean({ default: false }),
+    canceledAt: field.dateTime({ isOptional: true }),
+    stripeSubscriptionId: field.string({ isOptional: true }),
+    stripeCustomerId: field.string({ isOptional: true }),
+    metadata: field.json({ isOptional: true }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt()
+  },
+  enums: [SubscriptionStatusEnum]
+});
+var BillingUsageEntity = defineEntity({
+  name: "BillingUsage",
+  description: "Track usage of metered features.",
+  schema: "saas_app",
+  map: "billing_usage",
+  fields: {
+    id: field.id(),
+    organizationId: field.foreignKey(),
+    feature: field.string({
+      description: 'Feature being tracked (e.g., "api_calls", "storage_gb")'
+    }),
+    quantity: field.int({ description: "Usage quantity" }),
+    unit: field.string({
+      isOptional: true,
+      description: "Unit of measurement"
+    }),
+    billingPeriod: field.string({
+      description: 'Billing period (e.g., "2024-01")'
+    }),
+    recordedAt: field.dateTime({ description: "When usage was recorded" }),
+    sourceId: field.string({
+      isOptional: true,
+      description: "Source of usage (e.g., request ID)"
+    }),
+    sourceType: field.string({ isOptional: true }),
+    metadata: field.json({ isOptional: true })
+  },
+  indexes: [
+    index.on(["organizationId", "feature", "billingPeriod"]),
+    index.on(["organizationId", "recordedAt"])
+  ]
+});
+var UsageLimitEntity = defineEntity({
+  name: "UsageLimit",
+  description: "Usage limits per plan/organization.",
+  schema: "saas_app",
+  map: "usage_limit",
+  fields: {
+    id: field.id(),
+    planId: field.string({
+      isOptional: true,
+      description: "Plan this limit applies to"
+    }),
+    organizationId: field.string({
+      isOptional: true,
+      description: "Org-specific override"
+    }),
+    feature: field.string({ description: "Feature being limited" }),
+    limit: field.int({ description: "Maximum allowed usage" }),
+    resetPeriod: field.string({
+      default: '"monthly"',
+      description: "When limit resets"
+    }),
+    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"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt()
+  },
+  indexes: [index.unique(["planId", "feature"])]
+});
+
+// src/billing/billing.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var SubscriptionStatusSchemaEnum = defineEnum("SubscriptionStatus", [
+  "TRIALING",
+  "ACTIVE",
+  "PAST_DUE",
+  "CANCELED",
+  "PAUSED"
+]);
+var FeatureAccessReasonEnum = defineEnum("FeatureAccessReason", [
+  "included",
+  "limit_available",
+  "limit_reached",
+  "not_in_plan"
+]);
+
+// src/billing/billing.event.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+import { defineEvent } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var 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
+});
+var 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
+});
+var 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
+});
+
+// src/shared/mock-data.ts
+var 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: 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",
+    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",
+    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",
+    isPublic: true,
+    tags: ["analytics", "dashboard", "reporting"],
+    createdAt: new Date("2023-10-01T12:00:00Z"),
+    updatedAt: new Date("2024-02-28T16:45:00Z")
+  }
+];
+var MOCK_SUBSCRIPTION = {
+  id: "sub-1",
+  organizationId: "demo-org",
+  planId: "pro",
+  planName: "Professional",
+  status: "ACTIVE",
+  currentPeriodStart: new Date("2024-04-01T00:00:00Z"),
+  currentPeriodEnd: 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
+  }
+};
+var 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 }
+  ]
+};
+
+// src/billing/billing.handler.ts
+async function mockGetSubscriptionHandler() {
+  return MOCK_SUBSCRIPTION;
+}
+async function mockGetUsageSummaryHandler(input) {
+  return {
+    ...MOCK_USAGE_SUMMARY,
+    period: input.period ?? "current_month"
+  };
+}
+async function mockRecordUsageHandler(input) {
+  const currentUsage = MOCK_USAGE_SUMMARY.apiCalls.total;
+  const newTotal = currentUsage + input.quantity;
+  return {
+    recorded: true,
+    newTotal
+  };
+}
+async function mockCheckFeatureAccessHandler(input) {
+  const { feature } = input;
+  const featureMap = {
+    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 };
+}
+
+// src/billing/billing.schema.ts
+import { defineSchemaModel as defineSchemaModel2, ScalarTypeEnum as ScalarTypeEnum2 } from "@contractspec/lib.schema";
+var SubscriptionModel = defineSchemaModel2({
+  name: "Subscription",
+  description: "Organization subscription details",
+  fields: {
+    id: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    organizationId: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    planId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    planName: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    status: { type: SubscriptionStatusSchemaEnum, isOptional: false },
+    currentPeriodStart: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    currentPeriodEnd: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    trialEndsAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    cancelAtPeriodEnd: { type: ScalarTypeEnum2.Boolean(), isOptional: false }
+  }
+});
+var UsageSummaryModel = defineSchemaModel2({
+  name: "UsageSummary",
+  description: "Usage summary for a feature",
+  fields: {
+    feature: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    used: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    limit: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    unit: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    percentage: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: true }
+  }
+});
+var RecordUsageInputModel = defineSchemaModel2({
+  name: "RecordUsageInput",
+  description: "Input for recording feature usage",
+  fields: {
+    feature: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    sourceId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    sourceType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum2.JSONObject(), isOptional: true }
+  }
+});
+var RecordUsageOutputModel = defineSchemaModel2({
+  name: "RecordUsageOutput",
+  description: "Output for recording feature usage",
+  fields: {
+    recorded: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    currentUsage: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    limit: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    limitReached: { type: ScalarTypeEnum2.Boolean(), isOptional: false }
+  }
+});
+var UsageRecordedPayloadModel = defineSchemaModel2({
+  name: "UsageRecordedPayload",
+  description: "Payload for usage.recorded event",
+  fields: {
+    feature: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false }
+  }
+});
+var GetUsageSummaryInputModel = defineSchemaModel2({
+  name: "GetUsageSummaryInput",
+  description: "Input for getting usage summary",
+  fields: {
+    billingPeriod: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+  }
+});
+var GetUsageSummaryOutputModel = defineSchemaModel2({
+  name: "GetUsageSummaryOutput",
+  description: "Output for usage summary",
+  fields: {
+    billingPeriod: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    usage: { type: UsageSummaryModel, isArray: true, isOptional: false }
+  }
+});
+var CheckFeatureAccessInputModel = defineSchemaModel2({
+  name: "CheckFeatureAccessInput",
+  description: "Input for checking feature access",
+  fields: {
+    feature: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+  }
+});
+var CheckFeatureAccessOutputModel = defineSchemaModel2({
+  name: "CheckFeatureAccessOutput",
+  description: "Output for feature access check",
+  fields: {
+    hasAccess: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    reason: { type: FeatureAccessReasonEnum, isOptional: true },
+    upgradeUrl: { type: ScalarTypeEnum2.URL(), isOptional: true }
+  }
+});
+
+// src/billing/billing.operations.ts
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var OWNERS = ["@example.saas-boilerplate"];
+var 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"
+        }
+      }
+    ]
+  }
+});
+var 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 }
+      }
+    ]
+  }
+});
+var 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 }] }
+      }
+    ]
+  }
+});
+var 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" }
+      }
+    ]
+  }
+});
+
+// src/billing/billing.presentation.ts
+import { definePresentation, StabilityEnum } from "@contractspec/lib.contracts";
+var 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"]
+  }
+});
+var 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"]
+  }
+});
+export {
+  mockRecordUsageHandler,
+  mockGetUsageSummaryHandler,
+  mockGetSubscriptionHandler,
+  mockCheckFeatureAccessHandler,
+  UsageSummaryModel,
+  UsageRecordedPayloadModel,
+  UsageRecordedEvent,
+  UsageLimitReachedEvent,
+  UsageLimitEntity,
+  UsageDashboardPresentation,
+  SubscriptionStatusSchemaEnum,
+  SubscriptionStatusEnum,
+  SubscriptionPresentation,
+  SubscriptionModel,
+  SubscriptionEntity,
+  SubscriptionChangedEvent,
+  RecordUsageOutputModel,
+  RecordUsageInputModel,
+  RecordUsageContract,
+  GetUsageSummaryOutputModel,
+  GetUsageSummaryInputModel,
+  GetUsageSummaryContract,
+  GetSubscriptionContract,
+  FeatureAccessReasonEnum,
+  CheckFeatureAccessOutputModel,
+  CheckFeatureAccessInputModel,
+  CheckFeatureAccessContract,
+  BillingUsageEntity
+};