Merge remote-tracking branch 'origin/master' into billing-5-get-plans

Author: PierreBrisorgueil

.claude/skills/create-module/SKILL.md

@@ -51,6 +51,19 @@ Files to check in `modules/{new-module-name}/`:
 - Policy function names
 - Test descriptions and fixture data
 
+### 4b. Config-driven enums
+
+Business values (plans, roles, statuses) must be driven by the module config, never hardcoded in models or schemas.
+
+Pattern:
+- Define values in `modules/{module}/config/{module}.development.config.js`
+- Reference in Mongoose model: `enum: config.{section}.{enumName}`
+- Reference in Zod schema: `z.enum(config.{section}.{enumName})`
+
+Example: `config.billing.plans` used in both `billing.subscription.model.mongoose.js` and `billing.subscription.schema.js`.
+
+> Existing reference: `users.schema.js` uses `z.enum(config.whitelists.users.roles)`.
+
 ### 5. Apply renames carefully
 
 - Case-sensitive, whole-word matches where possible

.claude/skills/naming/SKILL.md

@@ -34,6 +34,18 @@ Audit or apply the project's file and folder naming conventions.
 
 > `[.{name}]` is optional — the reference `tasks` module uses the short form (e.g., `tasks.controller.js`, `tasks.service.js`).
 
+### Multi-entity modules
+
+When a module contains multiple entities (e.g., `billing` with `subscription`, `organizations` with `membership`), files are still prefixed by the **module name**, not the entity:
+
+| Correct | Wrong |
+| --- | --- |
+| `billing.subscription.model.mongoose.js` | `subscription.model.mongoose.js` |
+| `billing.subscription.schema.js` | `subscription.schema.js` |
+| `organizations.membership.model.mongoose.js` | `membership.model.mongoose.js` |
+
+Pattern: `{module}.{entity}[.{name}].{type}.js`
+
 ### Naming Tokens
 
 From a module name (e.g., `my-feature`):

modules/billing/config/billing.development.config.js

@@ -1,4 +1,19 @@
 const config = {
+  billing: {
+    // Plans available for subscriptions — extend as needed
+    plans: ['free', 'starter', 'pro', 'enterprise'],
+    // Stripe subscription statuses — see https://docs.stripe.com/api/subscriptions/object#subscription_object-status
+    statuses: [
+      'incomplete',
+      'incomplete_expired',
+      'trialing',
+      'active',
+      'past_due',
+      'canceled',
+      'unpaid',
+      'paused',
+    ],
+  },
   stripe: {
     secretKey: process.env.DEVKIT_NODE_stripe_secretKey ?? '',
     webhookSecret: process.env.DEVKIT_NODE_stripe_webhookSecret ?? '',

modules/billing/models/billing.subscription.model.mongoose.js

@@ -2,6 +2,7 @@
  * Module dependencies
  */
 import mongoose from 'mongoose';
+import config from '../../../config/index.js';
 
 const Schema = mongoose.Schema;
 
@@ -28,12 +29,12 @@ const SubscriptionMongoose = new Schema(
     },
     plan: {
       type: String,
-      enum: ['free', 'starter', 'pro'],
+      enum: config.billing.plans,
       default: 'free',
     },
     status: {
       type: String,
-      enum: ['active', 'past_due', 'canceled', 'trialing', 'incomplete'],
+      enum: config.billing.statuses,
       default: 'active',
     },
     currentPeriodEnd: {

modules/billing/models/billing.subscription.schema.js

@@ -2,6 +2,7 @@
  * Module dependencies
  */
 import { z } from 'zod';
+import config from '../../../config/index.js';
 
 /**
  *  Data Schema
@@ -14,9 +15,6 @@ const optionalStripeId = z
   .optional()
   .transform((val) => (val === '' ? undefined : val));
 
-const plans = ['free', 'starter', 'pro'];
-const statuses = ['active', 'past_due', 'canceled', 'trialing', 'incomplete'];
-
 const baseShape = {
   organization: z.string().trim().regex(objectIdRegex, 'organization must be a valid ObjectId'),
   stripeCustomerId: optionalStripeId,
@@ -26,8 +24,8 @@ const baseShape = {
 
 const Subscription = z.object({
   ...baseShape,
-  plan: z.enum(plans).default('free'),
-  status: z.enum(statuses).default('active'),
+  plan: z.enum(config.billing.plans).default('free'),
+  status: z.enum(config.billing.statuses).default('active'),
   cancelAtPeriodEnd: z.boolean().default(false),
 });
 
@@ -36,8 +34,8 @@ const Subscription = z.object({
  */
 const SubscriptionCore = z.object({
   ...baseShape,
-  plan: z.enum(plans),
-  status: z.enum(statuses),
+  plan: z.enum(config.billing.plans),
+  status: z.enum(config.billing.statuses),
   cancelAtPeriodEnd: z.boolean(),
 });
 

modules/billing/tests/billing.unit.tests.js

@@ -1,6 +1,7 @@
 /**
  * Module dependencies.
  */
+import config from '../../../config/index.js';
 import schema from '../models/billing.subscription.schema.js';
 
 /**
@@ -82,7 +83,7 @@ describe('Billing unit tests:', () => {
     });
 
     test('should accept all valid plan values', (done) => {
-      for (const plan of ['free', 'starter', 'pro']) {
+      for (const plan of config.billing.plans) {
         subscription.plan = plan;
         const result = schema.Subscription.safeParse(subscription);
         expect(result.error).toBeFalsy();
@@ -91,7 +92,7 @@ describe('Billing unit tests:', () => {
     });
 
     test('should accept all valid status values', (done) => {
-      for (const status of ['active', 'past_due', 'canceled', 'trialing', 'incomplete']) {
+      for (const status of config.billing.statuses) {
         subscription.status = status;
         const result = schema.Subscription.safeParse(subscription);
         expect(result.error).toBeFalsy();

modules/organizations/models/organizations.model.mongoose.js

@@ -3,6 +3,8 @@
  */
 import mongoose from 'mongoose';
 
+import config from '../../../config/index.js';
+
 const Schema = mongoose.Schema;
 
 /**
@@ -34,7 +36,7 @@ const OrganizationMongoose = new Schema(
     },
     plan: {
       type: String,
-      enum: ['free', 'starter', 'pro', 'enterprise'],
+      enum: config.billing.plans,
       default: 'free',
     },
     createdBy: {

modules/organizations/models/organizations.schema.js

@@ -3,6 +3,8 @@
  */
 import { z } from 'zod';
 
+import config from '../../../config/index.js';
+
 /**
  * Data Schema
  */
@@ -11,7 +13,7 @@ const Organization = z.object({
   description: z.string().trim().default(''),
   slug: z.string().trim().min(1).toLowerCase().optional(),
   domain: z.string().trim().default(''),
-  plan: z.enum(['free', 'starter', 'pro', 'enterprise']).default('free'),
+  plan: z.enum(config.billing.plans).default('free'),
 });
 
 const OrganizationUpdate = Organization.partial();