From 276018d4969a56a60d1486df23ae8f8da31443a4 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Mon, 11 May 2026 22:27:46 +0200
Subject: [PATCH 1/3] feat(billing): post-grant upgrade prompt variant for
 depleted signupGrant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add exhaustedAfterGrant store getter (free plan + balance<=0 + signup_grant ledger entry)
and post-grant copy variant in BillingUpgradePromptComponent with Boost pack CTA first,
upgrade Growth/Pro second. PricingCard badge already wired via plan.badge — add explicit
tests to document. i18n keys added en+fr.
---
 .../billing.upgradePrompt.component.vue       | 52 ++++++++++-
 src/modules/billing/lang/en.js                |  8 ++
 src/modules/billing/lang/fr.js                |  8 ++
 src/modules/billing/stores/billing.store.js   | 27 ++++++
 ...illing.pricingCard.component.unit.tests.js | 16 ++++
 .../billing/tests/billing.store.unit.tests.js | 74 ++++++++++++++++
 ...ling.upgradePrompt.component.unit.tests.js | 86 +++++++++++++++++++
 7 files changed, 267 insertions(+), 4 deletions(-)

diff --git a/src/modules/billing/components/billing.upgradePrompt.component.vue b/src/modules/billing/components/billing.upgradePrompt.component.vue
index dc848e884..709dc99b6 100644
--- a/src/modules/billing/components/billing.upgradePrompt.component.vue
+++ b/src/modules/billing/components/billing.upgradePrompt.component.vue
@@ -1,5 +1,39 @@
 <template>
-  <v-alert type="info" variant="tonal" prominent class="my-4">
+  <!-- Post-grant variant: signup grant is depleted (Free plan, balance = 0, ledger has signup_grant entry) -->
+  <div v-if="exhaustedAfterGrant" class="my-4">
+    <v-alert type="info" variant="tonal" prominent>
+      <template #text>
+        <p class="font-weight-bold mb-1">{{ $t('billing.upgradePrompt.postGrantTitle') }}</p>
+        <p>{{ $t('billing.upgradePrompt.postGrantBody') }}</p>
+      </template>
+      <template #append>
+        <div class="d-flex flex-column ga-2">
+          <v-btn
+            data-test="cta-pack"
+            color="primary"
+            variant="flat"
+            size="small"
+            class="text-none"
+            @click="$emit('buy-pack')"
+          >
+            {{ $t('billing.upgradePrompt.postGrantBuyPack') }}
+          </v-btn>
+          <v-btn
+            data-test="cta-upgrade"
+            variant="text"
+            size="small"
+            class="text-none"
+            to="/pricing"
+          >
+            {{ $t('billing.upgradePrompt.postGrantUpgrade') }}
+          </v-btn>
+        </div>
+      </template>
+    </v-alert>
+  </div>
+
+  <!-- Default / meter variant -->
+  <v-alert v-else type="info" variant="tonal" prominent class="my-4">
     <template #text>
       <span v-if="hasUsageInfo">{{ $t('billing.upgradePrompt.usageInfo', { current, limit, label: displayLabel }) }}</span>
       <span v-else>{{ $t('billing.upgradePrompt.requirePlan', { plan: requiredPlan }) }}</span>
@@ -34,6 +68,7 @@
  * Module dependencies.
  */
 import { useQuota } from '../composables/billing.useQuota';
+import { useBillingStore } from '../stores/billing.store.js';
 
 /**
  * Component definition.
@@ -86,14 +121,23 @@ export default {
   },
   emits: ['buy-pack'],
   /**
-   * @desc Wires useQuota composable and exposes reactive usage and limits maps.
-   * @returns {{ usage: Object, limits: Object }}
+   * @desc Wires useQuota composable and billing store for exhaustedAfterGrant detection.
+   * @returns {{ usage: Object, limits: Object, billingStore: Object }}
    */
   setup() {
     const { usage, limits } = useQuota();
-    return { usage, limits };
+    const billingStore = useBillingStore();
+    return { usage, limits, billingStore };
   },
   computed: {
+    /**
+     * @desc Whether the current user has exhausted their one-shot Free-tier signup grant.
+     * Delegates to the billing store getter for reactivity.
+     * @returns {boolean}
+     */
+    exhaustedAfterGrant() {
+      return this.billingStore.exhaustedAfterGrant;
+    },
     /**
      * @desc Quota key derived from resource and action.
      * @returns {string}
diff --git a/src/modules/billing/lang/en.js b/src/modules/billing/lang/en.js
index 779e7a1b8..dedb6f6a2 100644
--- a/src/modules/billing/lang/en.js
+++ b/src/modules/billing/lang/en.js
@@ -295,6 +295,14 @@ export const billingEn = {
       buyUnits: 'Buy units',
       /** i18n key: billing.upgradePrompt.upgrade */
       upgrade: 'Upgrade',
+      /** i18n key: billing.upgradePrompt.postGrantTitle */
+      postGrantTitle: 'Your signup grant is depleted',
+      /** i18n key: billing.upgradePrompt.postGrantBody */
+      postGrantBody: 'You used your 500 compute one-shot grant. Buy a Boost pack to keep going, or upgrade for monthly compute.',
+      /** i18n key: billing.upgradePrompt.postGrantBuyPack */
+      postGrantBuyPack: 'Buy Boost pack — $9',
+      /** i18n key: billing.upgradePrompt.postGrantUpgrade */
+      postGrantUpgrade: 'Upgrade Growth / Pro',
     },
   },
 };
diff --git a/src/modules/billing/lang/fr.js b/src/modules/billing/lang/fr.js
index c5e411d75..fc7015e05 100644
--- a/src/modules/billing/lang/fr.js
+++ b/src/modules/billing/lang/fr.js
@@ -289,6 +289,14 @@ export const billingFr = {
       buyUnits: 'Acheter des unités',
       /** i18n key: billing.upgradePrompt.upgrade */
       upgrade: 'Passer à un plan supérieur',
+      /** i18n key: billing.upgradePrompt.postGrantTitle */
+      postGrantTitle: 'Votre crédit de démarrage est épuisé',
+      /** i18n key: billing.upgradePrompt.postGrantBody */
+      postGrantBody: "Vous avez utilisé vos 500 crédits offerts à l'inscription. Achetez un pack Boost pour continuer, ou passez à un abonnement mensuel.",
+      /** i18n key: billing.upgradePrompt.postGrantBuyPack */
+      postGrantBuyPack: 'Acheter un pack Boost — 9 $',
+      /** i18n key: billing.upgradePrompt.postGrantUpgrade */
+      postGrantUpgrade: 'Passer à Growth / Pro',
     },
   },
 };
diff --git a/src/modules/billing/stores/billing.store.js b/src/modules/billing/stores/billing.store.js
index 18e12afff..8d6da573e 100644
--- a/src/modules/billing/stores/billing.store.js
+++ b/src/modules/billing/stores/billing.store.js
@@ -150,6 +150,33 @@ export const useBillingStore = defineStore('billing', {
     extrasLedger: { entries: [], total: 0, page: 1, limit: 20 },
   }),
 
+  getters: {
+    /**
+     * @desc Returns true when the current org is on the Free plan AND has exhausted
+     * their one-shot signup grant. Specifically: plan === 'free', extrasBalance <= 0,
+     * AND the extrasLedger has at least one entry with source === 'signup_grant'.
+     *
+     * Used to trigger the post-grant upgrade modal variant instead of the regular
+     * meter-exhaustion prompt.
+     *
+     * Returns false when any required state is absent (null-safe).
+     * @param {Object} state Pinia store state
+     * @returns {boolean}
+     */
+    exhaustedAfterGrant: (state) => {
+      if (!state.subscription) return false;
+      if (state.subscription.plan !== 'free') return false;
+      if (!state.extrasBalance) return false;
+      const balance = state.extrasBalance.balance ?? 0;
+      if (balance > 0) return false;
+      // Optional chaining: extrasLedger is initialized to {entries:[]} in devkit state, but
+      // downstream projects may override the store shape, so guard defensively.
+      const entries = state.extrasLedger?.entries;
+      if (!Array.isArray(entries) || entries.length === 0) return false;
+      return entries.some((e) => e.source === 'signup_grant');
+    },
+  },
+
   actions: {
     /**
      * @desc Fetch available billing plans (public).
diff --git a/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js b/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js
index ae69b17c6..b4b18b045 100644
--- a/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js
+++ b/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js
@@ -112,6 +112,22 @@ describe('BillingPricingCardComponent', () => {
     expect(wrapper.text()).toContain('For pros');
   });
 
+  it('renders plan.badge chip when badge is set (e.g. "500 compute @ signup" for Free)', () => {
+    const planWithBadge = { ...freePlan, badge: '500 compute @ signup' };
+    const wrapper = mountComponent({ plan: planWithBadge });
+    expect(wrapper.text()).toContain('500 compute @ signup');
+  });
+
+  it('does not render badge chip when plan.badge is absent', () => {
+    const wrapper = mountComponent({ plan: freePlan });
+    // freePlan has no badge — chip must be absent
+    const chip = wrapper.findComponent({ name: 'v-chip' });
+    // The annual savings chip spacer div is rendered but there's no badge chip
+    // We verify by checking the text doesn't contain any badge content
+    expect(wrapper.text()).not.toContain('500 compute @ signup');
+    expect(wrapper.text()).not.toContain('Most Popular');
+  });
+
   it('displays "Free" for free plan when displayPrice is null', () => {
     const wrapper = mountComponent({ plan: freePlan });
     expect(wrapper.text()).toContain('Free');
diff --git a/src/modules/billing/tests/billing.store.unit.tests.js b/src/modules/billing/tests/billing.store.unit.tests.js
index d5aeb6b94..80c462328 100644
--- a/src/modules/billing/tests/billing.store.unit.tests.js
+++ b/src/modules/billing/tests/billing.store.unit.tests.js
@@ -688,6 +688,80 @@ describe('Billing Store', () => {
     });
   });
 
+  describe('exhaustedAfterGrant getter', () => {
+    it('returns true when plan=free, balance<=0, ledger has signup_grant entry', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'free' };
+      store.extrasBalance = { balance: 0 };
+      store.extrasLedger = { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(true);
+    });
+
+    it('returns true when balance is negative (overdrawn)', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'free' };
+      store.extrasBalance = { balance: -5 };
+      store.extrasLedger = { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(true);
+    });
+
+    it('returns false when plan is not free', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'growth' };
+      store.extrasBalance = { balance: 0 };
+      store.extrasLedger = { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(false);
+    });
+
+    it('returns false when balance is positive', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'free' };
+      store.extrasBalance = { balance: 100 };
+      store.extrasLedger = { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(false);
+    });
+
+    it('returns false when ledger has no signup_grant entry', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'free' };
+      store.extrasBalance = { balance: 0 };
+      store.extrasLedger = { entries: [{ source: 'pack', amount: 500 }], total: 1, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(false);
+    });
+
+    it('returns false when ledger entries are empty', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'free' };
+      store.extrasBalance = { balance: 0 };
+      store.extrasLedger = { entries: [], total: 0, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(false);
+    });
+
+    it('returns false when subscription is null', () => {
+      const store = useBillingStore();
+      store.subscription = null;
+      store.extrasBalance = { balance: 0 };
+      store.extrasLedger = { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(false);
+    });
+
+    it('returns false when extrasBalance is null', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'free' };
+      store.extrasBalance = null;
+      store.extrasLedger = { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(false);
+    });
+
+    it('returns false when extrasLedger has no entries (null-safe)', () => {
+      const store = useBillingStore();
+      store.subscription = { plan: 'free' };
+      store.extrasBalance = { balance: 0 };
+      store.extrasLedger = { entries: null, total: 0, page: 1, limit: 20 };
+      expect(store.exhaustedAfterGrant).toBe(false);
+    });
+  });
+
   describe('clearExtrasIntentId (per-pack)', () => {
     beforeEach(() => {
       sessionStorage.clear();
diff --git a/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js b/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js
index dabecea36..21ed78f8c 100644
--- a/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js
+++ b/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js
@@ -103,4 +103,90 @@ describe('BillingUpgradePrompt', () => {
     expect(wrapper.text()).toContain('This feature requires the');
     expect(wrapper.text()).not.toContain("You've used");
   });
+
+  describe('post-grant variant (exhaustedAfterGrant)', () => {
+    /**
+     * Mount with billing store pre-seeded with the given state fields.
+     * @param {Object} storeState Fields to set on the billingStore.
+     * @returns {import('@vue/test-utils').VueWrapper}
+     */
+    const mountWithStore = (storeState) => {
+      const store = useBillingStore();
+      Object.assign(store, storeState);
+      return mount(BillingUpgradePrompt, {
+        props: { requiredPlan: 'growth', mode: 'meter' },
+        global: {
+          plugins: [vuetify, i18n],
+          stubs: { RouterLink: true },
+        },
+      });
+    };
+
+    it('renders post-grant copy when exhaustedAfterGrant is true', () => {
+      const wrapper = mountWithStore({
+        subscription: { plan: 'free' },
+        extrasBalance: { balance: 0 },
+        extrasLedger: { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      expect(wrapper.text()).toMatch(/signup grant.*depleted|free compute.*used up/i);
+    });
+
+    it('renders Boost pack CTA first (primary) in post-grant variant', () => {
+      const wrapper = mountWithStore({
+        subscription: { plan: 'free' },
+        extrasBalance: { balance: 0 },
+        extrasLedger: { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      const packBtn = wrapper.find('[data-test="cta-pack"]');
+      expect(packBtn.exists()).toBe(true);
+      expect(packBtn.text()).toMatch(/boost|pack/i);
+    });
+
+    it('renders secondary upgrade CTA in post-grant variant', () => {
+      const wrapper = mountWithStore({
+        subscription: { plan: 'free' },
+        extrasBalance: { balance: 0 },
+        extrasLedger: { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      const upgradeBtn = wrapper.find('[data-test="cta-upgrade"]');
+      expect(upgradeBtn.exists()).toBe(true);
+      expect(upgradeBtn.text()).toMatch(/upgrade/i);
+    });
+
+    it('does not render post-grant variant when plan is not free', () => {
+      const wrapper = mountWithStore({
+        subscription: { plan: 'growth' },
+        extrasBalance: { balance: 0 },
+        extrasLedger: { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      expect(wrapper.text()).not.toMatch(/signup grant.*depleted/i);
+    });
+
+    it('does not render post-grant variant when balance is positive', () => {
+      const wrapper = mountWithStore({
+        subscription: { plan: 'free' },
+        extrasBalance: { balance: 100 },
+        extrasLedger: { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      expect(wrapper.text()).not.toMatch(/signup grant.*depleted/i);
+    });
+
+    it('does not render post-grant variant when no signup_grant entry in ledger', () => {
+      const wrapper = mountWithStore({
+        subscription: { plan: 'free' },
+        extrasBalance: { balance: 0 },
+        extrasLedger: { entries: [{ source: 'pack', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      expect(wrapper.text()).not.toMatch(/signup grant.*depleted/i);
+    });
+
+    it('does not render post-grant variant when subscription is null', () => {
+      const wrapper = mountWithStore({
+        subscription: null,
+        extrasBalance: { balance: 0 },
+        extrasLedger: { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      expect(wrapper.text()).not.toMatch(/signup grant.*depleted/i);
+    });
+  });
 });

From b150016272f8ab3893fd958e835596df0bfa1045 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Mon, 11 May 2026 22:37:39 +0200
Subject: [PATCH 2/3] fix(billing): remove unused chip variable in pricingCard
 test (lint)

---
 .../tests/billing.pricingCard.component.unit.tests.js        | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js b/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js
index b4b18b045..17c0e032e 100644
--- a/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js
+++ b/src/modules/billing/tests/billing.pricingCard.component.unit.tests.js
@@ -120,10 +120,7 @@ describe('BillingPricingCardComponent', () => {
 
   it('does not render badge chip when plan.badge is absent', () => {
     const wrapper = mountComponent({ plan: freePlan });
-    // freePlan has no badge — chip must be absent
-    const chip = wrapper.findComponent({ name: 'v-chip' });
-    // The annual savings chip spacer div is rendered but there's no badge chip
-    // We verify by checking the text doesn't contain any badge content
+    // freePlan has no badge — verify by checking the text doesn't contain any badge content
     expect(wrapper.text()).not.toContain('500 compute @ signup');
     expect(wrapper.text()).not.toContain('Most Popular');
   });

From c96ec08da2f264da143c6814b593cb4ab2497c55 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Mon, 11 May 2026 22:41:15 +0200
Subject: [PATCH 3/3] fix(billing): gate post-grant variant to meter mode only
 + test

---
 .../billing.upgradePrompt.component.vue       |  7 ++++---
 ...ling.upgradePrompt.component.unit.tests.js | 20 +++++++++++++++++++
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/src/modules/billing/components/billing.upgradePrompt.component.vue b/src/modules/billing/components/billing.upgradePrompt.component.vue
index 709dc99b6..7d1ef58c0 100644
--- a/src/modules/billing/components/billing.upgradePrompt.component.vue
+++ b/src/modules/billing/components/billing.upgradePrompt.component.vue
@@ -1,6 +1,6 @@
 <template>
-  <!-- Post-grant variant: signup grant is depleted (Free plan, balance = 0, ledger has signup_grant entry) -->
-  <div v-if="exhaustedAfterGrant" class="my-4">
+  <!-- Post-grant variant: signup grant is depleted in meter mode (Free plan, balance = 0, ledger has signup_grant entry) -->
+  <div v-if="exhaustedAfterGrant && mode === 'meter'" class="my-4">
     <v-alert type="info" variant="tonal" prominent>
       <template #text>
         <p class="font-weight-bold mb-1">{{ $t('billing.upgradePrompt.postGrantTitle') }}</p>
@@ -132,7 +132,8 @@ export default {
   computed: {
     /**
      * @desc Whether the current user has exhausted their one-shot Free-tier signup grant.
-     * Delegates to the billing store getter for reactivity.
+     * Delegates to the billing store getter for reactivity. Only rendered in meter mode
+     * (subscription mode is for feature-gating by plan, not meter exhaustion).
      * @returns {boolean}
      */
     exhaustedAfterGrant() {
diff --git a/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js b/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js
index 21ed78f8c..a87fc97fb 100644
--- a/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js
+++ b/src/modules/billing/tests/billing.upgradePrompt.component.unit.tests.js
@@ -188,5 +188,25 @@ describe('BillingUpgradePrompt', () => {
       });
       expect(wrapper.text()).not.toMatch(/signup grant.*depleted/i);
     });
+
+    it('does not render post-grant variant in subscription mode even if exhaustedAfterGrant is true', () => {
+      const store = useBillingStore();
+      Object.assign(store, {
+        subscription: { plan: 'free' },
+        extrasBalance: { balance: 0 },
+        extrasLedger: { entries: [{ source: 'signup_grant', amount: 500 }], total: 1, page: 1, limit: 20 },
+      });
+      // mode='subscription' (default) — post-grant branch must not show, regular prompt must show
+      const wrapper = mount(BillingUpgradePrompt, {
+        props: { requiredPlan: 'growth' }, // mode defaults to 'subscription'
+        global: {
+          plugins: [vuetify, i18n],
+          stubs: { RouterLink: true },
+        },
+      });
+      expect(wrapper.text()).not.toMatch(/signup grant.*depleted/i);
+      // Regular prompt still shows
+      expect(wrapper.text()).toMatch(/requires the|Upgrade/i);
+    });
   });
 });