fix: keep feature flag overrides when upgrading (#4934)

Currently any plan change results in the override of the plan flags to
the default values of the new plan. Any override that was set is
discarded. (ie: an enabled flag or a manually increased limit will be
lost)
This PR is ensuring flags aren't reset if more generous that the new
plan default when upgrading or migrating. Downgrading always results in
applying default flags for new plan.
<!-- Summary by @propel-code-bot -->

---

**Preserve feature-flag overrides on plan upgrades/migrations**

Adds logic so that when a team upgrades or migrates to a different
billing plan, any flag that was previously overridden to a *more
generous* value is retained. A full reset to new-plan defaults still
happens on downgrades.

Key pieces are the new `mergeFlags` helper in
`packages/shared/lib/services/plans/plans.ts` and the
downgrade-detection utility `isPotentialDowngrade` in
`packages/shared/lib/services/plans/definitions.ts`.
`handlePlanChanged()` now calls `mergeFlags` and applies the merged set
instead of blindly spreading `newPlan.flags`. A comprehensive Vitest
suite validates merge behaviour across upgrade, migration and downgrade
scenarios.

<details>
<summary><strong>Key Changes</strong></summary>

• Introduced `mergeFlags` to combine `currentPlan` and
`newPlanDefinition.flags` while preserving overrides when appropriate
• Injected `mergedFlags` into `updatePlanByTeam()` inside
`handlePlanChanged()` instead of raw `newPlan.flags`
• Added downgrade detection via `isPotentialDowngrade` with an explicit
downgrade matrix
• Exposed helper `getPlanDefinition` for tests and internal lookup
• Added 100+ line unit test `plans.unit.test.ts` covering downgrade,
upgrade and migration paths
• Minor type additions (`PlanDefinition`) and import adjustments

</details>

<details>
<summary><strong>Affected Areas</strong></summary>

• `packages/shared/lib/services/plans/plans.ts` (plan update flow)
• `packages/shared/lib/services/plans/definitions.ts` (plan metadata
helpers)
• `packages/shared/lib/services/plans/plans.unit.test.ts` (new tests)

</details>

---
*This summary was automatically generated by @propel-code-bot*

Author: TBonnin

packages/shared/lib/services/plans/definitions.ts

@@ -303,3 +303,119 @@ export const plansList: PlanDefinition[] = [
     scaleLegacyPlan,
     growthLegacyPlan
 ];
+
+export function getPlanDefinition(code: PlanDefinition['code']): PlanDefinition | null {
+    const plan = plansList.find((p) => p.code === code);
+    return plan || null;
+}
+export function isPotentialDowngrade({ from, to }: { from: PlanDefinition['code']; to: PlanDefinition['code'] }): boolean {
+    // Matrix defining whether moving from one plan to another is a downgrade
+    // true = downgrade, false = not a downgrade
+    // Plan hierarchy: free < starter < growth < enterprise
+    // Account for all possible combinations, not just the acceptable transitions defined in nextPlan/prevPlan (ie: manual changes in billing system)
+    // v2 plans are equivalent to their non-v2 counterparts (lateral moves = not downgrades)
+    // legacy plans are equivalent to their current counterparts (lateral moves = not downgrades)
+    // scale-legacy is positioned between growth and enterprise
+    const downgradeMatrix = {
+        free: {
+            free: false,
+            'starter-v2': false,
+            'growth-v2': false,
+            starter: false,
+            growth: false,
+            enterprise: false,
+            'starter-legacy': false,
+            'scale-legacy': false,
+            'growth-legacy': false
+        },
+        'starter-v2': {
+            free: true,
+            'starter-v2': false,
+            'growth-v2': false,
+            starter: false,
+            growth: false,
+            enterprise: false,
+            'starter-legacy': false,
+            'scale-legacy': false,
+            'growth-legacy': false
+        },
+        'growth-v2': {
+            free: true,
+            'starter-v2': true,
+            'growth-v2': false,
+            starter: true,
+            growth: false,
+            enterprise: false,
+            'starter-legacy': true,
+            'scale-legacy': false,
+            'growth-legacy': false
+        },
+        starter: {
+            free: true,
+            'starter-v2': false,
+            'growth-v2': false,
+            starter: false,
+            growth: false,
+            enterprise: false,
+            'starter-legacy': false,
+            'scale-legacy': false,
+            'growth-legacy': false
+        },
+        growth: {
+            free: true,
+            'starter-v2': true,
+            'growth-v2': false,
+            starter: true,
+            growth: false,
+            enterprise: false,
+            'starter-legacy': true,
+            'scale-legacy': false,
+            'growth-legacy': false
+        },
+        enterprise: {
+            free: true,
+            'starter-v2': true,
+            'growth-v2': true,
+            starter: true,
+            growth: true,
+            enterprise: false,
+            'starter-legacy': true,
+            'scale-legacy': true,
+            'growth-legacy': true
+        },
+        'starter-legacy': {
+            free: true,
+            'starter-v2': false,
+            'growth-v2': false,
+            starter: false,
+            growth: false,
+            enterprise: false,
+            'starter-legacy': false,
+            'scale-legacy': false,
+            'growth-legacy': false
+        },
+        'growth-legacy': {
+            free: true,
+            'starter-v2': true,
+            'growth-v2': false,
+            starter: true,
+            growth: false,
+            enterprise: false,
+            'starter-legacy': true,
+            'scale-legacy': false,
+            'growth-legacy': false
+        },
+        'scale-legacy': {
+            free: true,
+            'starter-v2': true,
+            'growth-v2': true,
+            starter: true,
+            growth: true,
+            enterprise: false,
+            'starter-legacy': true,
+            'scale-legacy': false,
+            'growth-legacy': true
+        }
+    } satisfies Record<PlanDefinition['code'], Record<PlanDefinition['code'], boolean>>;
+    return downgradeMatrix[from][to];
+}

packages/shared/lib/services/plans/plans.ts

@@ -2,10 +2,10 @@ import ms from 'ms';
 
 import { Err, Ok, flagHasPlan } from '@nangohq/utils';
 
-import { freePlan, plansList } from './definitions.js';
+import { freePlan, isPotentialDowngrade, plansList } from './definitions.js';
 import { productTracking } from '../../utils/productTracking.js';
 
-import type { DBPlan, DBTeam } from '@nangohq/types';
+import type { DBPlan, DBTeam, PlanDefinition } from '@nangohq/types';
 import type { Result } from '@nangohq/utils';
 import type { Knex } from 'knex';
 
@@ -148,6 +148,9 @@ export async function handlePlanChanged(
         return Ok(true);
     }
 
+    // Merge current plan flags with new plan defaults
+    const mergedFlags = mergeFlags({ currentPlan: currentPlan.value, newPlanDefinition: newPlan });
+
     // Only update subscription date from free to paid (undefined = no update)
     const isCurrentFree = currentPlan.value.name === freePlan.code;
     const isNewPaid = newPlan.code !== freePlan.code;
@@ -160,7 +163,7 @@ export async function handlePlanChanged(
         orb_future_plan_at: null,
         ...(orbCustomerId ? { orb_customer_id: orbCustomerId } : {}),
         ...(isCurrentFree && isNewPaid ? { orb_subscribed_at: new Date() } : {}),
-        ...newPlan.flags
+        ...mergedFlags
     });
 
     if (updated.isErr()) {
@@ -175,3 +178,118 @@ export async function handlePlanChanged(
 
     return Ok(true);
 }
+
+export function mergeFlags({ currentPlan, newPlanDefinition }: { currentPlan: DBPlan; newPlanDefinition: PlanDefinition }): PlanDefinition['flags'] {
+    // Downgrades always use new plan defaults and reset any overrides
+    if (isPotentialDowngrade({ from: currentPlan.name, to: newPlanDefinition.code })) {
+        return newPlanDefinition.flags;
+    }
+
+    const overrides: Partial<PlanDefinition['flags']> = {};
+    const keys = Object.keys(currentPlan) as (keyof DBPlan)[];
+    for (const key of keys) {
+        const isFlagKey = ((key: keyof DBPlan): key is keyof PlanDefinition['flags'] & keyof DBPlan => {
+            return key in newPlanDefinition.flags;
+        })(key);
+
+        // Skip keys that are not plan flags
+        if (!isFlagKey) continue;
+
+        // Skip undefined values in new plan flags
+        if (newPlanDefinition.flags[key] === undefined) continue;
+
+        switch (key) {
+            // These are not plan flags, skip them
+            case 'stripe_customer_id':
+            case 'stripe_payment_id':
+            case 'orb_customer_id':
+            case 'orb_subscription_id':
+            case 'orb_future_plan':
+            case 'orb_future_plan_at':
+            case 'orb_subscribed_at':
+            case 'trial_start_at':
+            case 'trial_end_at':
+            case 'trial_extension_count':
+            case 'trial_end_notified_at':
+            case 'trial_expired':
+            case 'created_at':
+            case 'updated_at':
+                break;
+            // BOOLEAN FLAGS - keep override if false
+            case 'auto_idle': {
+                overrides[key] = !currentPlan[key] ? false : newPlanDefinition.flags[key];
+                break;
+            }
+            // BOOLEAN FLAGS - keep override if true
+            case 'has_otel':
+            case 'has_sync_variants':
+            case 'has_webhooks_script':
+            case 'has_webhooks_forward':
+            case 'can_disable_connect_ui_watermark':
+            case 'can_override_docs_connect_url':
+            case 'can_customize_connect_ui_theme': {
+                overrides[key] = currentPlan[key] ? true : newPlanDefinition.flags[key];
+                break;
+            }
+            // NUMBER FLAGS - keep override if higher, null means unlimited
+            case 'webhook_forwards_max':
+            case 'monthly_actions_max':
+            case 'monthly_active_records_max':
+            case 'connections_max':
+            case 'records_max':
+            case 'proxy_max':
+            case 'function_executions_max':
+            case 'function_compute_gbms_max':
+            case 'function_logs_max': {
+                const currentValue = currentPlan[key];
+                const newValue = newPlanDefinition.flags[key] || 0;
+                if (currentValue === null || currentValue > newValue) {
+                    overrides[key] = null;
+                }
+                break;
+            }
+            // NUMBER FLAGS - keep override if higher
+            case 'environments_max': {
+                const currentValue = currentPlan[key];
+                const newValue = newPlanDefinition.flags[key] || 0;
+                if (currentValue > newValue) {
+                    overrides[key] = currentValue;
+                }
+                break;
+            }
+            // NUMBER FLAGS - keep override if lower
+            case 'sync_frequency_secs_min': {
+                const currentValue = currentPlan[key];
+                const newValue = newPlanDefinition.flags[key] || 0;
+                if (currentValue < newValue) {
+                    overrides[key] = currentValue;
+                }
+                break;
+            }
+            // SPECIAL CASES
+            case 'api_rate_limit_size': {
+                const sizeIndex: Record<DBPlan['api_rate_limit_size'], number> = {
+                    s: 1,
+                    m: 2,
+                    l: 3,
+                    xl: 4,
+                    '2xl': 5,
+                    '3xl': 6,
+                    '4xl': 7
+                };
+                const currentIndex = sizeIndex[currentPlan[key]];
+                const newIndex = sizeIndex[newPlanDefinition.flags[key]];
+                if (currentIndex > newIndex) {
+                    overrides[key] = currentPlan[key];
+                }
+                break;
+            }
+            default:
+                ((_exhaustiveCheck: never) => {
+                    throw new Error(`Unhandled plan flag key in mergeFlags: ${key}`);
+                })(key);
+        }
+    }
+
+    return { ...newPlanDefinition.flags, ...overrides };
+}

packages/shared/lib/services/plans/plans.unit.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPlanDefinition } from './definitions.js';
+import { mergeFlags } from './plans.js';
+
+import type { DBPlan, PlanDefinition } from '@nangohq/types';
+
+describe('mergeFlags', () => {
+    describe('when downgrading', () => {
+        it('should reset all flags to new plan default values, including overrides', () => {
+            const currentPlan = makePlan({
+                code: 'starter-v2',
+                flagOverrides: {
+                    environments_max: 99,
+                    api_rate_limit_size: 'xl',
+                    has_otel: true,
+                    proxy_max: 99_999_999
+                }
+            });
+            const newPlanDefinition = getPlanDefinition('free')!;
+            const newFlags = mergeFlags({
+                currentPlan,
+                newPlanDefinition
+            });
+
+            expect(newFlags).toMatchObject(newPlanDefinition.flags);
+        });
+    });
+
+    describe.each([
+        { from: 'free', to: 'starter-v2' }, // upgrade from free
+        { from: 'starter-v2', to: 'growth-v2' }, // upgrade from paid
+        { from: 'starter', to: 'starter-v2' }, // migration
+        { from: 'starter-legacy', to: 'starter-v2' }, // migration
+        { from: 'starter', to: 'growth-v2' }, // upgrade and migration
+        { from: 'starter-legacy', to: 'growth-v2' } // upgrade and migration
+    ] as { from: PlanDefinition['code']; to: PlanDefinition['code'] }[])('when upgrading/migrating from $from to $to', ({ from, to }) => {
+        it('should apply new plan defaults if no overrides', () => {
+            const currentPlan = makePlan({ code: from, flagOverrides: {} });
+            const newPlanDefinition = getPlanDefinition(to)!;
+            const newFlags = mergeFlags({
+                currentPlan,
+                newPlanDefinition
+            });
+            expect(newFlags).toMatchObject(newPlanDefinition.flags);
+        });
+        it('should apply new plan defaults and keep more generous overrides', () => {
+            const currentPlan = makePlan({
+                code: from,
+                flagOverrides: {
+                    environments_max: 50,
+                    has_otel: true,
+                    api_rate_limit_size: '2xl',
+                    proxy_max: 99_999_999,
+                    auto_idle: true,
+                    can_disable_connect_ui_watermark: false
+                }
+            });
+            const newPlanDefinition = getPlanDefinition(to)!;
+            const newFlags = mergeFlags({
+                currentPlan,
+                newPlanDefinition
+            });
+
+            expect(newFlags).toMatchObject({
+                ...newPlanDefinition.flags,
+                environments_max: 50, // Keep override
+                has_otel: true, // Keep override
+                api_rate_limit_size: '2xl' // Keep override
+                // proxy_max: new plan more generous default (null)
+                // auto_idle: new plan more generous default (false)
+                // can_disable_connect_ui_watermark: new plan more generous default (true)
+            });
+        });
+    });
+});
+
+function makePlan({ code, flagOverrides }: { code: DBPlan['name']; flagOverrides: PlanDefinition['flags'] }): DBPlan {
+    const defaultPlanDefinition = getPlanDefinition(code)!;
+    return {
+        id: 1,
+        account_id: 1,
+        name: code,
+        created_at: new Date(),
+        updated_at: new Date(),
+        stripe_customer_id: null,
+        stripe_payment_id: null,
+        orb_customer_id: null,
+        orb_subscription_id: null,
+        orb_future_plan: null,
+        orb_future_plan_at: null,
+        orb_subscribed_at: null,
+        trial_start_at: null,
+        trial_end_at: null,
+        trial_extension_count: 0,
+        trial_end_notified_at: null,
+        trial_expired: null,
+        api_rate_limit_size: 'm',
+        monthly_actions_max: null,
+        monthly_active_records_max: null,
+        sync_frequency_secs_min: 3600,
+        auto_idle: false,
+        has_sync_variants: false,
+        has_otel: false,
+        has_webhooks_forward: false,
+        has_webhooks_script: false,
+        can_customize_connect_ui_theme: false,
+        can_override_docs_connect_url: false,
+        can_disable_connect_ui_watermark: false,
+        environments_max: 2,
+        connections_max: null,
+        records_max: null,
+        proxy_max: null,
+        function_executions_max: null,
+        function_compute_gbms_max: null,
+        webhook_forwards_max: null,
+        function_logs_max: null,
+        ...defaultPlanDefinition,
+        ...flagOverrides
+    };
+}