fix(billing): add getSignupGrant export + harden co-presence guard

Phase 0 gate [critical]: export getSignupGrant(planId) helper from billing.plan.service.js
Phase 0 gate [medium]:   co-presence guard returns plan without partial fields on mismatch
Phase 0 gate [low]:      rename hasGrant/hasOneShot → hasSignupGrant/hasOneShotFlag for clarity
Add tests: getSignupGrant returns 500 for free, undefined for pro/unknown;
           co-presence guard early-return drops lone signupGrant or oneShot

Author: PierreBrisorgueil

modules/billing/services/billing.plan.service.js

@@ -33,16 +33,18 @@ const getPlanFromConfig = (planId) => {
   // N2 signup-grant fields — only present when configured (optional on the def).
   // Guard: signupGrant and oneShot must be defined together (co-presence invariant).
   // This mirrors the Zod schema refine() and catches misconfigured planDefinitions at runtime.
-  const hasGrant = def.signupGrant !== undefined;
-  const hasOneShot = def.oneShot !== undefined;
-  if (hasGrant !== hasOneShot) {
+  const hasSignupGrant = def.signupGrant !== undefined;
+  const hasOneShotFlag = def.oneShot !== undefined;
+  if (hasSignupGrant !== hasOneShotFlag) {
     logger.warn(
       '[billing.plan] signupGrant and oneShot must be defined together — check planDefinitions config',
       { planId: def.planId, signupGrant: def.signupGrant, oneShot: def.oneShot },
     );
+    // Do not attach partial/broken grant fields — return plan without them.
+    return plan;
   }
-  if (hasGrant) plan.signupGrant = def.signupGrant;
-  if (hasOneShot) plan.oneShot = def.oneShot;
+  if (hasSignupGrant) plan.signupGrant = def.signupGrant;
+  if (hasOneShotFlag) plan.oneShot = def.oneShot;
 
   return plan;
 };
@@ -75,7 +77,22 @@ const getPlanByVersion = (planId, version) => {
   return plan;
 };
 
+/**
+ * @desc Get the signup grant amount for a given planId (N2 Free Tier Grant feature).
+ *       Returns the signupGrant value if the plan definition has it, or undefined.
+ *       Callers must handle undefined as "no grant configured for this plan".
+ *
+ * @param {string} planId - The logical plan identifier (e.g. "free").
+ * @returns {number|undefined} The signupGrant value, or undefined.
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js service, not Qwik
+const getSignupGrant = (planId) => {
+  const plan = getPlanFromConfig(planId);
+  return plan?.signupGrant;
+};
+
 export default {
   getActivePlan,
   getPlanByVersion,
+  getSignupGrant,
 };

modules/billing/tests/billing.plan.service.unit.tests.js

@@ -145,6 +145,47 @@ describe('BillingPlanService unit tests:', () => {
       BillingPlanService.getActivePlan('pro');
       expect(mockLogger.warn).not.toHaveBeenCalled();
     });
+
+    test('does not attach lone signupGrant when oneShot is missing (co-presence guard early return)', () => {
+      mockConfig.billing.planDefinitions = [
+        { planId: 'free', meterQuota: 0, signupGrant: 500, ratios: {} },
+      ];
+      const result = BillingPlanService.getActivePlan('free');
+      expect(result.signupGrant).toBeUndefined();
+      expect(result.oneShot).toBeUndefined();
+    });
+
+    test('does not attach lone oneShot when signupGrant is missing (co-presence guard early return)', () => {
+      mockConfig.billing.planDefinitions = [
+        { planId: 'free', meterQuota: 0, oneShot: true, ratios: {} },
+      ];
+      const result = BillingPlanService.getActivePlan('free');
+      expect(result.signupGrant).toBeUndefined();
+      expect(result.oneShot).toBeUndefined();
+    });
+  });
+
+  describe('getSignupGrant', () => {
+    test('returns signupGrant for a plan with both signupGrant and oneShot set', () => {
+      mockConfig.billing.planDefinitions = [
+        { planId: 'free', meterQuota: 0, signupGrant: 500, oneShot: true, ratios: {} },
+      ];
+      const grant = BillingPlanService.getSignupGrant('free');
+      expect(grant).toBe(500);
+    });
+
+    test('returns undefined for plans without signupGrant', () => {
+      mockConfig.billing.planDefinitions = [
+        { planId: 'pro', meterQuota: 8000, ratios: {} },
+      ];
+      const grant = BillingPlanService.getSignupGrant('pro');
+      expect(grant).toBeUndefined();
+    });
+
+    test('returns undefined for unknown planId', () => {
+      const grant = BillingPlanService.getSignupGrant('nonexistent');
+      expect(grant).toBeUndefined();
+    });
   });
 
   describe('getPlanByVersion', () => {