feat(billing): add Subscription model + repository (#3249)

* feat(billing): add Subscription model, schema, and repository

Implement the Subscription Mongoose model with Stripe integration fields
(stripeCustomerId, stripeSubscriptionId, plan, status, currentPeriodEnd,
cancelAtPeriodEnd), Zod validation schema, and repository with CRUD +
findByOrganization and findByStripeCustomerId queries.

Closes #3241

* fix(billing): address review feedback on Subscription model

- Validate organization as ObjectId format in Zod schema
- Normalize empty Stripe IDs to undefined to prevent sparse index issues
- Fix id/_id inconsistency in update/remove repository methods
- Add defensive guard in findByStripeCustomerId for falsy input
- Update JSDoc @return to @returns and add Promise return types
- Add unit tests for ObjectId validation and Stripe ID normalization

* refactor(billing): drive plan and status enums from config

* fix(billing): correct update JSDoc return type to include null

* fix(billing): address CodeRabbit review findings

- Complete Stripe subscription status enum with all 8 official statuses
- Fix resolveId to prevent invalid IDs from silently creating new records
- Normalize stripeCustomerId by trimming before query

* docs(skills): add multi-entity naming rule and config-driven enum guidance

* refactor(organizations): use config.billing.plans for plan enum

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/.gitkeep

@@ -0,0 +1,71 @@
+/**
+ * Module dependencies
+ */
+import mongoose from 'mongoose';
+
+import config from '../../../config/index.js';
+
+const Schema = mongoose.Schema;
+
+/**
+ * Data Model Mongoose
+ */
+const SubscriptionMongoose = new Schema(
+  {
+    organization: {
+      type: Schema.ObjectId,
+      ref: 'Organization',
+      unique: true,
+      required: true,
+    },
+    stripeCustomerId: {
+      type: String,
+      unique: true,
+      sparse: true,
+    },
+    stripeSubscriptionId: {
+      type: String,
+      unique: true,
+      sparse: true,
+    },
+    plan: {
+      type: String,
+      enum: config.billing.plans,
+      default: 'free',
+    },
+    status: {
+      type: String,
+      enum: config.billing.statuses,
+      default: 'active',
+    },
+    currentPeriodEnd: {
+      type: Date,
+    },
+    cancelAtPeriodEnd: {
+      type: Boolean,
+      default: false,
+    },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+/**
+ * Returns the hex string representation of the document ObjectId.
+ * @returns {string} Hex string of the ObjectId.
+ */
+function addID() {
+  return this._id.toHexString();
+}
+
+/**
+ * Model configuration
+ */
+SubscriptionMongoose.virtual('id').get(addID);
+// Ensure virtual fields are serialised.
+SubscriptionMongoose.set('toJSON', {
+  virtuals: true,
+});
+
+mongoose.model('Subscription', SubscriptionMongoose);

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

@@ -0,0 +1,39 @@
+/**
+ * Module dependencies
+ */
+import { z } from 'zod';
+
+import config from '../../../config/index.js';
+
+/**
+ *  Data Schema
+ */
+const objectIdRegex = /^[a-f\d]{24}$/i;
+
+const Subscription = z.object({
+  organization: z
+    .string()
+    .trim()
+    .regex(objectIdRegex, 'organization must be a valid ObjectId'),
+  stripeCustomerId: z
+    .string()
+    .trim()
+    .optional()
+    .transform((val) => (val === '' ? undefined : val)),
+  stripeSubscriptionId: z
+    .string()
+    .trim()
+    .optional()
+    .transform((val) => (val === '' ? undefined : val)),
+  plan: z.enum(config.billing.plans).default('free'),
+  status: z.enum(config.billing.statuses).default('active'),
+  currentPeriodEnd: z.coerce.date().nullable().optional(),
+  cancelAtPeriodEnd: z.boolean().default(false),
+});
+
+const SubscriptionUpdate = Subscription.partial();
+
+export default {
+  Subscription,
+  SubscriptionUpdate,
+};

modules/billing/models/subscription.schema.js

@@ -0,0 +1,114 @@
+/**
+ * Module dependencies
+ */
+import mongoose from 'mongoose';
+
+const Subscription = mongoose.model('Subscription');
+
+const defaultPopulate = [
+  {
+    path: 'organization',
+    select: 'name slug plan',
+  },
+];
+
+/**
+ * Resolves the identifier from a subscription object or raw id.
+ * @param {Object|string} value - The subscription object or id string.
+ * @returns {string|undefined} The resolved id.
+ */
+const resolveId = (value) => {
+  if (typeof value === 'string' || value instanceof mongoose.Types.ObjectId) return value;
+  return value?._id || value?.id;
+};
+
+/**
+ * @function list
+ * @description Data access operation to fetch all subscriptions from the database with an optional filter.
+ * @param {Object} [filter] - Optional filter to apply to the query.
+ * @returns {Promise<Array>} A promise resolving to an array of subscriptions.
+ */
+const list = (filter) => Subscription.find(filter).populate(defaultPopulate).sort('-createdAt').exec();
+
+/**
+ * @function create
+ * @description Data access operation to create a new subscription in the database.
+ * @param {Object} subscription - The subscription object to create.
+ * @returns {Promise<Object>} A promise resolving to the created subscription.
+ */
+const create = (subscription) => new Subscription(subscription).save().then((doc) => doc.populate(defaultPopulate));
+
+/**
+ * @function get
+ * @description Data access operation to fetch a single subscription by its ID.
+ * @param {String} id - The ID of the subscription to fetch.
+ * @returns {Promise<Object|null>} A promise resolving to the retrieved subscription or null if the ID is not valid.
+ */
+const get = (id) => {
+  if (!mongoose.Types.ObjectId.isValid(id)) return null;
+  return Subscription.findOne({ _id: id }).populate(defaultPopulate).exec();
+};
+
+/**
+ * @function update
+ * @description Data access operation to update an existing subscription in the database.
+ * @param {Object} subscription - The subscription object containing the updated details.
+ * @returns {Promise<Object>|null} A promise resolving to the updated subscription, or null if the ID is invalid.
+ */
+const update = (subscription) => {
+  const id = resolveId(subscription);
+  if (id !== undefined) {
+    if (!mongoose.Types.ObjectId.isValid(id)) return null;
+    // eslint-disable-next-line no-unused-vars
+    const { _id, id: _virtualId, ...payload } = subscription;
+    return Subscription.findByIdAndUpdate(id, payload, { returnDocument: 'after', runValidators: true })
+      .populate(defaultPopulate)
+      .exec();
+  }
+  return new Subscription(subscription).save().then((doc) => doc.populate(defaultPopulate));
+};
+
+/**
+ * @function remove
+ * @description Data access operation to delete a single subscription by its ID.
+ * @param {Object} subscription - The subscription object to delete.
+ * @returns {Promise<Object|null>} A promise resolving to a confirmation of the deletion or null if invalid.
+ */
+const remove = (subscription) => {
+  const id = resolveId(subscription);
+  if (!id || !mongoose.Types.ObjectId.isValid(id)) return null;
+  return Subscription.deleteOne({ _id: id }).exec();
+};
+
+/**
+ * @function findByOrganization
+ * @description Data access operation to fetch a subscription by organization ID.
+ * @param {String} organizationId - The organization ID.
+ * @returns {Promise<Object|null>} A promise resolving to the retrieved subscription or null.
+ */
+const findByOrganization = (organizationId) => {
+  if (!mongoose.Types.ObjectId.isValid(organizationId)) return null;
+  return Subscription.findOne({ organization: organizationId }).populate(defaultPopulate).exec();
+};
+
+/**
+ * @function findByStripeCustomerId
+ * @description Data access operation to fetch a subscription by Stripe customer ID.
+ * @param {String} stripeCustomerId - The Stripe customer ID.
+ * @returns {Promise<Object|null>} A promise resolving to the retrieved subscription or null.
+ */
+const findByStripeCustomerId = (stripeCustomerId) => {
+  const normalizedStripeCustomerId = stripeCustomerId?.trim();
+  if (!normalizedStripeCustomerId) return null;
+  return Subscription.findOne({ stripeCustomerId: normalizedStripeCustomerId }).populate(defaultPopulate).exec();
+};
+
+export default {
+  list,
+  create,
+  get,
+  update,
+  remove,
+  findByOrganization,
+  findByStripeCustomerId,
+};