@equilateral_ai/mindmeld 3.0.0

package/src/handlers/helpers/subscriptionTiers.js

@@ -0,0 +1,1168 @@
+/**
+ * Subscription Tiers Configuration
+ * MindMeld/Rapport v3
+ *
+ * Pricing Model (per user/month):
+ * - Free: $0 (basic invariants only, no standards)
+ * - Team: $49 (community contribution) / $99 (private)
+ * - Professional: $149 (community contribution) / $199 (private)
+ * - Enterprise: Contact sales
+ *
+ * Community Contribution:
+ * - Lower price tiers contribute learned patterns back to community
+ * - Private tiers keep all patterns within the organization
+ *
+ * Early Adopter Discount:
+ * - 80% off first year if subscribed within 30 days of launch
+ * - Coupon code: FOUNDER80 (auto-applied at checkout)
+ *
+ * Standards Hierarchy:
+ * - Free: NO standards (basic invariants only)
+ * - Team: Community standards (curated set, no picker - all enabled)
+ * - Professional: Full library with standards picker (user preferences)
+ * - Enterprise: Custom packs + full library + preferences
+ *
+ * Standards Packages:
+ * - Community Standards: Curated patterns from MindMeld community
+ * - Compliance Standards: SOC2/HIPAA/PCI patterns
+ * - AWS Best Practices: Well-Architected patterns
+ * - Custom Packs: Enterprise-specific curated standards
+ */
+
+/**
+ * Early Adopter Discount Configuration
+ *
+ * Auto-applied at checkout for eligible users (no manual code entry needed)
+ * Code can still be shared for referral tracking
+ */
+const EARLY_ADOPTER_DISCOUNT = {
+    enabled: true,
+    discountPercent: 80, // 80% off
+    eligibilityWindowDays: 30, // Must subscribe within 30 days of account creation
+    durationMonths: 12, // Discount applies for first 12 months
+    stripeCouponId: process.env.STRIPE_COUPON_FOUNDER || 'FOUNDER80',
+    autoApply: true, // Automatically apply at checkout if eligible
+    shareableCode: 'FOUNDER80', // For referral/sharing (same discount)
+    description: '80% off your first year - Founding Member Special',
+    displayMessage: 'FOUNDER80 applied - Founding Member discount!'
+};
+
+/**
+ * Standards packages available by tier
+ */
+const STANDARDS_PACKAGES = {
+    community: {
+        name: 'Community Standards',
+        description: 'Curated patterns from the MindMeld community',
+        source: 'api:mindmeld.dev/standards/community',
+        categories: ['patterns', 'integrations', 'frameworks', 'development_principles', 'cost_optimization', 'api_design', 'testing'],
+        pickable: false // Team tier gets all, no picking
+    },
+    compliance: {
+        name: 'Compliance Standards',
+        description: 'SOC2, HIPAA, PCI-DSS compliance patterns',
+        source: 'api:mindmeld.dev/standards/compliance',
+        categories: ['soc2', 'hipaa', 'pci', 'gdpr', 'audit'],
+        pickable: true // Professional+ can pick which to enable
+    },
+    aws: {
+        name: 'AWS Best Practices',
+        description: 'Well-Architected Framework patterns',
+        source: 'api:mindmeld.dev/standards/aws',
+        categories: ['security', 'reliability', 'performance', 'cost', 'operations'],
+        pickable: true // Professional+ can pick which to enable
+    },
+    custom: {
+        name: 'Custom Packs',
+        description: 'Enterprise-specific curated standards packages',
+        source: 'api:mindmeld.dev/standards/custom',
+        categories: ['enterprise_custom'],
+        pickable: true // Enterprise can configure custom packs
+    }
+};
+
+const SUBSCRIPTION_TIERS = {
+    free: {
+        name: 'Free',
+        displayName: 'Solo Developer',
+        priceMonthly: 0,
+        priceAnnual: 0,
+        maxCollaborators: 1, // Just the user
+        maxProjects: 3,
+        maxInvariants: 10,
+        standards: [], // NO standards - basic invariants only
+        canPickStandards: false,
+        features: ['local_context', 'basic_invariants'],
+        stripeProductId: null,
+        stripePriceIdMonthly: null,
+        stripePriceIdAnnual: null
+    },
+    team: {
+        name: 'Team',
+        displayName: 'Pro Solo',
+        priceMonthly: 49, // Per user - $49/user/mo (community contribution)
+        priceAnnual: 490, // ~2 months free
+        perUser: true,
+        maxCollaborators: 5,
+        maxProjects: 5,
+        maxInvariants: 50,
+        standards: ['community'], // ~25 community-curated standards
+        canPickStandards: false, // No picker - all community standards enabled
+        communityContribution: true, // Patterns feed back to community
+        features: [
+            'local_context',
+            'shared_invariants',
+            'cross_platform_sync',
+            'team_memory',
+            'community_standards',
+            'community_feedback' // Patterns feed back to community repo
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_TEAM || 'prod_Tn3KhkNBqHwfJ1',
+        stripePriceIdMonthly: process.env.STRIPE_PRICE_TEAM_MONTHLY || 'price_1SpTDmQoD4pT2xXuMG8yUqiz',
+        stripePriceIdAnnual: process.env.STRIPE_PRICE_TEAM_ANNUAL || 'price_1SpTDrQoD4pT2xXu5qU33axg'
+    },
+    team_private: {
+        name: 'Team Private',
+        displayName: 'Pro Solo (Private)',
+        priceMonthly: 99, // Per user - $99/user/mo (private standards)
+        priceAnnual: 990, // ~2 months free
+        perUser: true,
+        maxCollaborators: 5,
+        maxProjects: 5,
+        maxInvariants: 50,
+        standards: ['community'], // Access to community standards
+        canPickStandards: false,
+        communityContribution: false, // Patterns stay private
+        features: [
+            'local_context',
+            'shared_invariants',
+            'cross_platform_sync',
+            'team_memory',
+            'community_standards',
+            'private_patterns' // Patterns do NOT feed back to community
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_TEAM_PRIVATE || 'prod_Tn3KEmFEbA3y2T',
+        stripePriceIdMonthly: process.env.STRIPE_PRICE_TEAM_PRIVATE_MONTHLY || 'price_1SpTE5QoD4pT2xXu0ry2yL7j',
+        stripePriceIdAnnual: process.env.STRIPE_PRICE_TEAM_PRIVATE_ANNUAL || 'price_1SpTE6QoD4pT2xXuCiDZ37Ge'
+    },
+    professional: {
+        name: 'Professional',
+        displayName: 'Growing Team',
+        priceMonthly: 149, // Per user - $149/user/mo (community contribution)
+        priceAnnual: 1490, // ~2 months free
+        perUser: true,
+        maxCollaborators: 10,
+        maxProjects: null, // Unlimited
+        maxInvariants: 200,
+        standards: ['community', 'compliance', 'aws'], // Full 100+ standards library
+        canPickStandards: true, // Can pick which standards to enable
+        communityContribution: true, // Patterns feed back to community
+        features: [
+            'local_context',
+            'shared_invariants',
+            'cross_platform_sync',
+            'team_memory',
+            'priority_support',
+            'analytics',
+            'standards_picker',
+            'community_standards',
+            'compliance_standards',
+            'aws_standards',
+            'community_feedback'
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_PROFESSIONAL || 'prod_Tn3Kz8u744njE8',
+        stripePriceIdMonthly: process.env.STRIPE_PRICE_PROFESSIONAL_MONTHLY || 'price_1SpTELQoD4pT2xXukzY5iodd',
+        stripePriceIdAnnual: process.env.STRIPE_PRICE_PROFESSIONAL_ANNUAL || 'price_1SpTELQoD4pT2xXuwoa3zAtA'
+    },
+    professional_private: {
+        name: 'Professional Private',
+        displayName: 'Growing Team (Private)',
+        priceMonthly: 199, // Per user - $199/user/mo (private standards)
+        priceAnnual: 1990, // ~2 months free
+        perUser: true,
+        maxCollaborators: 10,
+        maxProjects: null, // Unlimited
+        maxInvariants: 200,
+        standards: ['community', 'compliance', 'aws'], // Full 100+ standards library
+        canPickStandards: true, // Can pick which standards to enable
+        communityContribution: false, // Patterns stay private
+        features: [
+            'local_context',
+            'shared_invariants',
+            'cross_platform_sync',
+            'team_memory',
+            'priority_support',
+            'analytics',
+            'standards_picker',
+            'community_standards',
+            'compliance_standards',
+            'aws_standards',
+            'private_patterns'
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_PROFESSIONAL_PRIVATE || 'prod_Tn3LxewfKvzfNc',
+        stripePriceIdMonthly: process.env.STRIPE_PRICE_PROFESSIONAL_PRIVATE_MONTHLY || 'price_1SpTEaQoD4pT2xXujb9l87Su',
+        stripePriceIdAnnual: process.env.STRIPE_PRICE_PROFESSIONAL_PRIVATE_ANNUAL || 'price_1SpTEaQoD4pT2xXuxQx8CTIv'
+    },
+    enterprise: {
+        name: 'Enterprise',
+        displayName: 'Organization',
+        priceMonthly: null, // Contact sales
+        priceAnnual: null, // Contact sales
+        contactSales: true,
+        perUser: false,
+        maxCollaborators: null, // Unlimited
+        maxProjects: null, // Unlimited
+        maxInvariants: null, // Unlimited
+        standards: ['community', 'compliance', 'aws', 'custom'], // All standards + custom packs
+        canPickStandards: true, // Can pick which standards to enable + custom packs
+        features: [
+            'local_context',
+            'shared_invariants',
+            'cross_platform_sync',
+            'team_memory',
+            'priority_support',
+            'analytics',
+            'standards_picker',
+            'custom_packs',
+            'community_standards',
+            'compliance_standards',
+            'aws_standards',
+            'sso',
+            'audit_trail',
+            'knowledge_curation',
+            'attribution_tracking',
+            'dedicated_support',
+            'custom_integrations'
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_ENTERPRISE || 'prod_Tn3Lmdaa1yhQtD',
+        stripePriceIdMonthly: null, // Contact sales
+        stripePriceIdAnnual: null // Contact sales
+    }
+};
+
+/**
+ * Get tier configuration
+ * @param {string} tierName - Tier identifier
+ * @returns {object|null} Tier configuration
+ */
+function getTierConfig(tierName) {
+    return SUBSCRIPTION_TIERS[tierName?.toLowerCase()] || null;
+}
+
+/**
+ * Check if tier has a feature
+ * @param {string} tierName - Tier identifier
+ * @param {string} feature - Feature name
+ * @returns {boolean}
+ */
+function hasFeature(tierName, feature) {
+    const tier = getTierConfig(tierName);
+    return tier ? tier.features.includes(feature) : false;
+}
+
+/**
+ * Check subscription limits
+ * @param {object} client - Client record with subscription info
+ * @param {string} action - Action being performed (add_collaborator, create_project, etc.)
+ * @param {object} counts - Current counts { collaborators, projects, invariants }
+ * @returns {object} { allowed: boolean, message: string, limit: number }
+ */
+function checkSubscriptionLimits(client, action, counts) {
+    const tier = getTierConfig(client.subscription_tier || 'free');
+    if (!tier) {
+        return { allowed: false, message: 'Invalid subscription tier', limit: 0 };
+    }
+
+    switch (action) {
+        case 'add_collaborator':
+            const collabLimit = tier.maxCollaborators;
+            if (counts.collaborators >= collabLimit) {
+                return {
+                    allowed: false,
+                    message: `${tier.displayName} tier allows up to ${collabLimit} collaborators. Upgrade to add more.`,
+                    limit: collabLimit
+                };
+            }
+            break;
+
+        case 'create_project':
+            const projectLimit = tier.maxProjects;
+            if (counts.projects >= projectLimit) {
+                return {
+                    allowed: false,
+                    message: `${tier.displayName} tier allows up to ${projectLimit} projects. Upgrade to create more.`,
+                    limit: projectLimit
+                };
+            }
+            break;
+
+        case 'add_invariant':
+            const invariantLimit = tier.maxInvariants;
+            if (invariantLimit !== null && counts.invariants >= invariantLimit) {
+                return {
+                    allowed: false,
+                    message: `${tier.displayName} tier allows up to ${invariantLimit} invariants. Upgrade for more.`,
+                    limit: invariantLimit
+                };
+            }
+            break;
+    }
+
+    return { allowed: true, message: 'OK', limit: null };
+}
+
+/**
+ * Get Stripe price ID for tier and billing interval
+ * @param {string} tierName - Tier identifier
+ * @param {string} billingInterval - 'monthly' or 'annual'
+ * @returns {string|null} Stripe price ID
+ */
+function getStripePriceId(tierName, billingInterval = 'monthly') {
+    const tier = getTierConfig(tierName);
+    if (!tier) return null;
+
+    return billingInterval === 'annual'
+        ? tier.stripePriceIdAnnual
+        : tier.stripePriceIdMonthly;
+}
+
+/**
+ * Get Stripe product ID for tier
+ * @param {string} tierName - Tier identifier
+ * @returns {string|null} Stripe product ID
+ */
+function getStripeProductId(tierName) {
+    const tier = getTierConfig(tierName);
+    return tier ? tier.stripeProductId : null;
+}
+
+/**
+ * Get recommended upgrade for a limit reason
+ * @param {string} currentTier - Current tier name
+ * @param {string} reason - Reason for upgrade (collaborators, projects, features)
+ * @returns {object} { tier: string, name: string, price: number }
+ */
+function getRecommendedUpgrade(currentTier, reason) {
+    const tierOrder = ['free', 'team', 'professional', 'enterprise'];
+    const currentIndex = tierOrder.indexOf(currentTier?.toLowerCase() || 'free');
+
+    // Recommend next tier up
+    const nextTier = tierOrder[Math.min(currentIndex + 1, tierOrder.length - 1)];
+    const tier = getTierConfig(nextTier);
+
+    return {
+        tier: nextTier,
+        name: tier.displayName,
+        price: tier.priceMonthly,
+        perUser: tier.perUser
+    };
+}
+
+/**
+ * Calculate monthly cost for tier based on user count
+ * @param {string} tierName - Tier identifier
+ * @param {number} userCount - Number of users
+ * @param {string} billingInterval - 'monthly' or 'annual'
+ * @returns {number} Total monthly cost
+ */
+function calculateTierCost(tierName, userCount, billingInterval = 'monthly') {
+    const tier = getTierConfig(tierName);
+    if (!tier) return 0;
+
+    const price = billingInterval === 'annual'
+        ? tier.priceAnnual / 12
+        : tier.priceMonthly;
+
+    return tier.perUser ? price * userCount : price;
+}
+
+/**
+ * Get all tiers for display
+ * @returns {array} Array of tier configs with tier key
+ */
+function getAllTiers() {
+    return Object.entries(SUBSCRIPTION_TIERS).map(([key, config]) => ({
+        id: key,
+        ...config
+    }));
+}
+
+/**
+ * Get standards packages available for a tier
+ * @param {string} tierName - Tier identifier
+ * @returns {array} Array of standards package configs
+ */
+function getTierStandards(tierName) {
+    const tier = getTierConfig(tierName);
+    if (!tier) return []; // Default to no standards (free tier behavior)
+
+    return tier.standards.map(std => STANDARDS_PACKAGES[std]).filter(Boolean);
+}
+
+/**
+ * Check if tier has access to a standards package
+ * @param {string} tierName - Tier identifier
+ * @param {string} standardsPackage - Package name (community, compliance, aws, custom)
+ * @returns {boolean}
+ */
+function hasStandardsAccess(tierName, standardsPackage) {
+    const tier = getTierConfig(tierName);
+    return tier ? tier.standards.includes(standardsPackage) : false;
+}
+
+/**
+ * Check if tier can pick/select specific standards
+ * Only professional and enterprise tiers can pick standards.
+ * Team tier gets curated set with no picking.
+ * Free tier gets no standards.
+ * @param {string} tierName - Tier identifier
+ * @returns {boolean}
+ */
+function canPickStandards(tierName) {
+    const tier = getTierConfig(tierName);
+    return tier ? tier.canPickStandards === true : false;
+}
+
+/**
+ * Get all standards packages info
+ * @returns {object} STANDARDS_PACKAGES object
+ */
+function getAllStandardsPackages() {
+    return STANDARDS_PACKAGES;
+}
+
+/**
+ * Get enabled standards for a user based on their tier and preferences
+ * @param {string} userId - User ID (email)
+ * @param {string} companyId - Company ID
+ * @param {string} tier - Subscription tier
+ * @param {object} options - Optional parameters
+ * @param {function} options.queryUserPreferences - Async function to query user standard preferences
+ * @param {function} options.queryCustomPack - Async function to query enterprise custom pack
+ * @returns {Promise<array>} Array of enabled standard IDs
+ */
+async function getEnabledStandardsForUser(userId, companyId, tier, options = {}) {
+    const tierConfig = getTierConfig(tier);
+
+    // Free tier: NO standards
+    if (!tierConfig || tier === 'free') {
+        return [];
+    }
+
+    // Team tier: All community standards enabled (no picker)
+    if (tier === 'team') {
+        // Return all community standards - no preferences, all enabled
+        const communityPackage = STANDARDS_PACKAGES.community;
+        if (options.queryAllCommunityStandards) {
+            // Query all community standards from the database/API
+            return await options.queryAllCommunityStandards();
+        }
+        // Fallback: return package info indicating all community standards
+        return [{
+            package: 'community',
+            allEnabled: true,
+            categories: communityPackage.categories
+        }];
+    }
+
+    // Professional tier: Full library with picker (user preferences)
+    if (tier === 'professional') {
+        if (options.queryUserPreferences) {
+            // Query user's enabled standards preferences
+            const preferences = await options.queryUserPreferences(userId, companyId);
+            return preferences.enabledStandards || [];
+        }
+        // Fallback: return available packages with picker info
+        return tierConfig.standards.map(pkg => ({
+            package: pkg,
+            pickable: true,
+            enabled: [] // User needs to configure preferences
+        }));
+    }
+
+    // Enterprise tier: Custom packs + full library + preferences
+    if (tier === 'enterprise') {
+        const enabledStandards = [];
+
+        // Get custom pack if configured
+        if (options.queryCustomPack) {
+            const customPack = await options.queryCustomPack(companyId);
+            if (customPack && customPack.standards) {
+                enabledStandards.push({
+                    package: 'custom',
+                    standards: customPack.standards,
+                    packName: customPack.name
+                });
+            }
+        }
+
+        // Get user preferences for standard library
+        if (options.queryUserPreferences) {
+            const preferences = await options.queryUserPreferences(userId, companyId);
+            if (preferences.enabledStandards) {
+                enabledStandards.push({
+                    package: 'library',
+                    standards: preferences.enabledStandards
+                });
+            }
+        }
+
+        // Fallback: return available packages with picker info
+        if (enabledStandards.length === 0) {
+            return tierConfig.standards.map(pkg => ({
+                package: pkg,
+                pickable: true,
+                enabled: []
+            }));
+        }
+
+        return enabledStandards;
+    }
+
+    // Unknown tier: return empty
+    return [];
+}
+
+/**
+ * Normalize tier name (handles legacy 'starter' -> 'team' mapping)
+ * @param {string} tierName - Tier identifier (may be legacy)
+ * @returns {string} Normalized tier name
+ */
+function normalizeTierName(tierName) {
+    const normalized = tierName?.toLowerCase();
+    // Handle legacy tier names
+    if (normalized === 'starter') {
+        return 'team';
+    }
+    return normalized || 'free';
+}
+
+/**
+ * Check if user is eligible for early adopter discount
+ * @param {Date} accountCreatedAt - When user account was created
+ * @returns {object} { eligible: boolean, daysRemaining: number, discount: object }
+ */
+function checkEarlyAdopterEligibility(accountCreatedAt) {
+    if (!EARLY_ADOPTER_DISCOUNT.enabled) {
+        return { eligible: false, daysRemaining: 0, discount: null };
+    }
+
+    const createdDate = new Date(accountCreatedAt);
+    const now = new Date();
+    const daysSinceCreation = Math.floor((now - createdDate) / (1000 * 60 * 60 * 24));
+    const daysRemaining = Math.max(0, EARLY_ADOPTER_DISCOUNT.eligibilityWindowDays - daysSinceCreation);
+
+    return {
+        eligible: daysSinceCreation <= EARLY_ADOPTER_DISCOUNT.eligibilityWindowDays,
+        daysRemaining,
+        daysSinceCreation,
+        discount: EARLY_ADOPTER_DISCOUNT
+    };
+}
+
+/**
+ * Get early adopter discount config
+ * @returns {object} EARLY_ADOPTER_DISCOUNT config
+ */
+function getEarlyAdopterDiscount() {
+    return EARLY_ADOPTER_DISCOUNT;
+}
+
+/**
+ * Calculate discounted price for early adopter
+ * @param {string} tierName - Tier identifier
+ * @param {number} userCount - Number of users
+ * @param {string} billingInterval - 'monthly' or 'annual'
+ * @returns {object} { originalPrice, discountedPrice, savings, discountPercent }
+ */
+function calculateEarlyAdopterPrice(tierName, userCount, billingInterval = 'monthly') {
+    const originalPrice = calculateTierCost(tierName, userCount, billingInterval);
+    const discountedPrice = originalPrice * (1 - EARLY_ADOPTER_DISCOUNT.discountPercent / 100);
+
+    return {
+        originalPrice,
+        discountedPrice: Math.round(discountedPrice * 100) / 100,
+        savings: Math.round((originalPrice - discountedPrice) * 100) / 100,
+        discountPercent: EARLY_ADOPTER_DISCOUNT.discountPercent,
+        discountDuration: `${EARLY_ADOPTER_DISCOUNT.durationMonths} months`
+    };
+}
+
+/**
+ * Check if tier requires community contribution (lower price tier)
+ * @param {string} tierName - Tier identifier
+ * @returns {boolean}
+ */
+function requiresCommunityContribution(tierName) {
+    const tier = getTierConfig(tierName);
+    return tier ? tier.communityContribution === true : false;
+}
+
+/**
+ * Get the private variant of a tier
+ * @param {string} tierName - Base tier name (e.g., 'team')
+ * @returns {string|null} Private tier name or null
+ */
+function getPrivateTierVariant(tierName) {
+    const privateTier = `${tierName}_private`;
+    return getTierConfig(privateTier) ? privateTier : null;
+}
+
+/**
+ * Get base tier from private variant
+ * @param {string} tierName - Tier name (may be private variant)
+ * @returns {string} Base tier name
+ */
+function getBaseTier(tierName) {
+    return tierName?.replace('_private', '') || tierName;
+}
+
+// ==============================================
+// BILLING TYPE FUNCTIONS
+// ==============================================
+
+/**
+ * Valid billing types
+ * - stripe: Standard credit card billing via Stripe
+ * - invoice: Enterprise invoice billing (billable_users tracked)
+ * - internal: Internal/free clients (no billing)
+ */
+const BILLING_TYPES = {
+    STRIPE: 'stripe',
+    INVOICE: 'invoice',
+    INTERNAL: 'internal'
+};
+
+/**
+ * Check if client uses Stripe billing
+ * @param {object} client - Client record
+ * @returns {boolean}
+ */
+function usesStripeBilling(client) {
+    return (client.billing_type || 'stripe') === BILLING_TYPES.STRIPE;
+}
+
+/**
+ * Check if client is enterprise invoice billing
+ * @param {object} client - Client record
+ * @returns {boolean}
+ */
+function usesInvoiceBilling(client) {
+    return client.billing_type === BILLING_TYPES.INVOICE;
+}
+
+/**
+ * Check if client is internal (free)
+ * @param {object} client - Client record
+ * @returns {boolean}
+ */
+function isInternalClient(client) {
+    return client.billing_type === BILLING_TYPES.INTERNAL;
+}
+
+/**
+ * Check collaborator limits based on billing type
+ * @param {object} client - Client record with billing_type and subscription_tier
+ * @param {number} currentCollaboratorCount - Current number of collaborators
+ * @returns {object} { allowed: boolean, message: string, billingAction: string|null }
+ */
+function checkCollaboratorBillingLimits(client, currentCollaboratorCount) {
+    const billingType = client.billing_type || 'stripe';
+
+    switch (billingType) {
+        case BILLING_TYPES.INTERNAL:
+            // Internal clients have no limits
+            return {
+                allowed: true,
+                message: 'OK',
+                billingAction: null,
+                unlimited: true
+            };
+
+        case BILLING_TYPES.INVOICE:
+            // Enterprise invoice clients - no hard limits, just increment billable users
+            return {
+                allowed: true,
+                message: 'OK',
+                billingAction: 'increment_billable_users',
+                unlimited: true
+            };
+
+        case BILLING_TYPES.STRIPE:
+        default:
+            // Standard Stripe billing - use subscription tier limits
+            const limitCheck = checkSubscriptionLimits(
+                client,
+                'add_collaborator',
+                { collaborators: currentCollaboratorCount }
+            );
+            return {
+                ...limitCheck,
+                billingAction: limitCheck.allowed ? null : 'upgrade_required'
+            };
+    }
+}
+
+/**
+ * Get billing type display name
+ * @param {string} billingType - Billing type code
+ * @returns {string} Human-readable name
+ */
+function getBillingTypeDisplayName(billingType) {
+    switch (billingType) {
+        case BILLING_TYPES.INVOICE:
+            return 'Enterprise Invoice';
+        case BILLING_TYPES.INTERNAL:
+            return 'Internal (Free)';
+        case BILLING_TYPES.STRIPE:
+        default:
+            return 'Credit Card (Stripe)';
+    }
+}
+
+// ==============================================
+// ENTERPRISE PACKAGES & ADD-ONS
+// ==============================================
+
+/**
+ * Enterprise package configurations
+ * Sold in seat packs of 25 minimum
+ */
+const ENTERPRISE_PACKAGES = {
+    base: {
+        name: 'Pro+ Base',
+        displayName: 'Enterprise Pro+ Base',
+        pricePerSeat: 179,
+        minSeats: 25,
+        seatIncrement: 25,
+        features: [
+            'sso',
+            'audit_trail',
+            'dedicated_support',
+            '99_9_sla',
+            'admin_dashboard',
+            'all_professional_features'
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_ENTERPRISE || 'prod_Tn3Lmdaa1yhQtD',
+        stripePriceIdMonthly25: process.env.STRIPE_PRICE_ENT_BASE_MONTHLY || 'price_1SrXDCQoD4pT2xXuS8RPpS9X',
+        stripePriceIdAnnual25: process.env.STRIPE_PRICE_ENT_BASE_ANNUAL || 'price_1SrXDCQoD4pT2xXukOTjeUpv'
+    },
+    full: {
+        name: 'Full Platform',
+        displayName: 'Enterprise Full Platform',
+        pricePerSeat: 219,
+        minSeats: 25,
+        seatIncrement: 25,
+        includes: ['base', 'engineering_intelligence', 'knowledge_continuity'],
+        features: [
+            'sso',
+            'audit_trail',
+            'dedicated_support',
+            '99_9_sla',
+            'admin_dashboard',
+            'all_professional_features',
+            // Engineering Intelligence features
+            'activity_dashboards',
+            'attention_alerts',
+            'session_commit_correlation',
+            'roi_reporting',
+            // Knowledge Continuity features
+            'knowledge_capture',
+            'turnover_protection',
+            'onboarding_acceleration',
+            'knowledge_transfer_docs'
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_ENTERPRISE || 'prod_Tn3Lmdaa1yhQtD',
+        stripePriceIdMonthly25: process.env.STRIPE_PRICE_ENT_FULL_MONTHLY || 'price_1SrXDCQoD4pT2xXuBKUuXRsT',
+        stripePriceIdAnnual25: process.env.STRIPE_PRICE_ENT_FULL_ANNUAL || 'price_1SrXDDQoD4pT2xXuIeWZ0VDa'
+    }
+};
+
+/**
+ * Enterprise add-on modules
+ * Can be added to 'base' package (already included in 'full')
+ */
+const ENTERPRISE_ADDONS = {
+    engineering_intelligence: {
+        id: 'engineering_intelligence',
+        name: 'Engineering Intelligence',
+        displayName: 'Engineering Intelligence Add-on',
+        description: 'Activity dashboards, attention alerts, session-to-commit correlation, ROI reporting',
+        pricePerSeat: 29,
+        minSeats: 25,
+        requires: ['enterprise_base'],
+        features: [
+            'activity_dashboards',
+            'attention_alerts',
+            'session_commit_correlation',
+            'roi_reporting'
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_ADDON_ENG_INTEL || 'prod_TpBat7IZySP7MB',
+        stripePriceIdMonthly25: process.env.STRIPE_PRICE_ADDON_ENG_INTEL_MONTHLY || 'price_1SrXDXQoD4pT2xXuk4bDjKm8',
+        stripePriceIdAnnual25: process.env.STRIPE_PRICE_ADDON_ENG_INTEL_ANNUAL || 'price_1SrXDYQoD4pT2xXuD3EdKBs1'
+    },
+    knowledge_continuity: {
+        id: 'knowledge_continuity',
+        name: 'Knowledge Continuity',
+        displayName: 'Knowledge Continuity Add-on',
+        description: 'Key employee capture, turnover protection, onboarding acceleration, knowledge transfer docs',
+        pricePerSeat: 49,
+        minSeats: 25,
+        requires: ['enterprise_base'],
+        features: [
+            'knowledge_capture',
+            'turnover_protection',
+            'onboarding_acceleration',
+            'knowledge_transfer_docs'
+        ],
+        stripeProductId: process.env.STRIPE_PRODUCT_ADDON_KNOWLEDGE || 'prod_TpBaOkMV4fsctv',
+        stripePriceIdMonthly25: process.env.STRIPE_PRICE_ADDON_KNOWLEDGE_MONTHLY || 'price_1SrXDYQoD4pT2xXuFYZy90r0',
+        stripePriceIdAnnual25: process.env.STRIPE_PRICE_ADDON_KNOWLEDGE_ANNUAL || 'price_1SrXDYQoD4pT2xXuxULSElxH'
+    }
+};
+
+/**
+ * Volume discount tiers for enterprise
+ * Applied based on total seat count
+ */
+const VOLUME_DISCOUNTS = [
+    { minSeats: 150, discount: 0.15, label: '15% off' },
+    { minSeats: 100, discount: 0.12, label: '12% off' },
+    { minSeats: 75, discount: 0.08, label: '8% off' },
+    { minSeats: 50, discount: 0.05, label: '5% off' },
+    { minSeats: 25, discount: 0, label: 'Standard pricing' }
+];
+
+/**
+ * Get volume discount for seat count
+ * @param {number} seatCount - Number of seats
+ * @returns {object} { discount: number, label: string }
+ */
+function getVolumeDiscount(seatCount) {
+    for (const tier of VOLUME_DISCOUNTS) {
+        if (seatCount >= tier.minSeats) {
+            return { discount: tier.discount, label: tier.label };
+        }
+    }
+    return { discount: 0, label: 'Standard pricing' };
+}
+
+/**
+ * Validate enterprise seat count
+ * Must be >= 25 and multiple of 25
+ * @param {number} seatCount - Requested seat count
+ * @returns {object} { valid: boolean, message: string, correctedCount: number }
+ */
+function validateSeatCount(seatCount) {
+    const minSeats = 25;
+    const increment = 25;
+
+    if (!seatCount || seatCount < minSeats) {
+        return {
+            valid: false,
+            message: `Enterprise requires minimum ${minSeats} seats`,
+            correctedCount: minSeats
+        };
+    }
+
+    if (seatCount % increment !== 0) {
+        const corrected = Math.ceil(seatCount / increment) * increment;
+        return {
+            valid: false,
+            message: `Seats must be in increments of ${increment}. Rounded up to ${corrected}.`,
+            correctedCount: corrected
+        };
+    }
+
+    return {
+        valid: true,
+        message: 'OK',
+        correctedCount: seatCount
+    };
+}
+
+/**
+ * Calculate enterprise subscription cost
+ * @param {string} packageType - 'base' or 'full'
+ * @param {number} seatCount - Number of seats (must be multiple of 25)
+ * @param {string[]} addons - Array of addon IDs (only for 'base' package)
+ * @param {string} billingInterval - 'monthly' or 'annual'
+ * @returns {object} { subtotal, discount, discountAmount, total, breakdown }
+ */
+function calculateEnterpriseCost(packageType, seatCount, addons = [], billingInterval = 'monthly') {
+    const pkg = ENTERPRISE_PACKAGES[packageType];
+    if (!pkg) {
+        throw new Error(`Invalid enterprise package: ${packageType}`);
+    }
+
+    const volumeDiscount = getVolumeDiscount(seatCount);
+    const breakdown = [];
+
+    // Base package cost
+    let subtotal = pkg.pricePerSeat * seatCount;
+    breakdown.push({
+        item: pkg.name,
+        pricePerSeat: pkg.pricePerSeat,
+        seats: seatCount,
+        amount: pkg.pricePerSeat * seatCount
+    });
+
+    // Add-on costs (only for 'base' package, 'full' already includes everything)
+    if (packageType === 'base' && addons.length > 0) {
+        for (const addonId of addons) {
+            const addon = ENTERPRISE_ADDONS[addonId];
+            if (addon) {
+                const addonCost = addon.pricePerSeat * seatCount;
+                subtotal += addonCost;
+                breakdown.push({
+                    item: addon.name,
+                    pricePerSeat: addon.pricePerSeat,
+                    seats: seatCount,
+                    amount: addonCost
+                });
+            }
+        }
+    }
+
+    // Apply volume discount
+    const discountAmount = subtotal * volumeDiscount.discount;
+    let total = subtotal - discountAmount;
+
+    // Annual pricing (2 months free = 10 months for price of 12)
+    if (billingInterval === 'annual') {
+        total = total * 10; // 10 months worth
+        return {
+            subtotal: subtotal * 12,
+            discount: volumeDiscount.discount,
+            discountLabel: volumeDiscount.label,
+            discountAmount: discountAmount * 12,
+            annualDiscount: subtotal * 2, // 2 months free
+            total,
+            monthlyEquivalent: total / 12,
+            breakdown,
+            billingInterval: 'annual'
+        };
+    }
+
+    return {
+        subtotal,
+        discount: volumeDiscount.discount,
+        discountLabel: volumeDiscount.label,
+        discountAmount,
+        total,
+        breakdown,
+        billingInterval: 'monthly'
+    };
+}
+
+/**
+ * Get enterprise package configuration
+ * @param {string} packageType - 'base' or 'full'
+ * @returns {object|null} Package configuration
+ */
+function getEnterprisePackage(packageType) {
+    return ENTERPRISE_PACKAGES[packageType] || null;
+}
+
+/**
+ * Get enterprise add-on configuration
+ * @param {string} addonId - Add-on identifier
+ * @returns {object|null} Add-on configuration
+ */
+function getEnterpriseAddon(addonId) {
+    return ENTERPRISE_ADDONS[addonId] || null;
+}
+
+/**
+ * Get all enterprise add-ons
+ * @returns {object} ENTERPRISE_ADDONS object
+ */
+function getAllEnterpriseAddons() {
+    return ENTERPRISE_ADDONS;
+}
+
+/**
+ * Check if client has enterprise feature access
+ * @param {object} client - Client record with enterprise_package and subscribed_addons
+ * @param {string} feature - Feature to check
+ * @returns {boolean}
+ */
+function hasEnterpriseFeature(client, feature) {
+    if (client.subscription_tier !== 'enterprise') {
+        return false;
+    }
+
+    const pkg = ENTERPRISE_PACKAGES[client.enterprise_package];
+    if (!pkg) {
+        return false;
+    }
+
+    // Check if feature is in package
+    if (pkg.features.includes(feature)) {
+        return true;
+    }
+
+    // Check add-ons
+    const addons = client.subscribed_addons || [];
+    for (const addonId of addons) {
+        const addon = ENTERPRISE_ADDONS[addonId];
+        if (addon && addon.features.includes(feature)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Get all features available to enterprise client
+ * @param {object} client - Client record
+ * @returns {string[]} Array of available feature IDs
+ */
+function getEnterpriseFeatures(client) {
+    if (client.subscription_tier !== 'enterprise') {
+        return [];
+    }
+
+    const pkg = ENTERPRISE_PACKAGES[client.enterprise_package];
+    if (!pkg) {
+        return [];
+    }
+
+    const features = new Set(pkg.features);
+
+    // Add features from subscribed add-ons
+    const addons = client.subscribed_addons || [];
+    for (const addonId of addons) {
+        const addon = ENTERPRISE_ADDONS[addonId];
+        if (addon) {
+            addon.features.forEach(f => features.add(f));
+        }
+    }
+
+    return Array.from(features);
+}
+
+/**
+ * Check enterprise seat limits
+ * @param {object} client - Client record with seat_count
+ * @param {number} currentUserCount - Current number of users
+ * @returns {object} { allowed, message, seatsAvailable, billingAction }
+ */
+function checkEnterpriseSeatLimits(client, currentUserCount) {
+    if (client.subscription_tier !== 'enterprise') {
+        return { allowed: true, message: 'Not enterprise tier' };
+    }
+
+    const seatCount = client.seat_count || 25;
+    const seatsAvailable = seatCount - currentUserCount;
+
+    if (currentUserCount >= seatCount) {
+        return {
+            allowed: false,
+            message: `All ${seatCount} enterprise seats are in use. Purchase additional seats to add more users.`,
+            seatsAvailable: 0,
+            seatsUsed: currentUserCount,
+            seatCount,
+            billingAction: 'purchase_seats'
+        };
+    }
+
+    return {
+        allowed: true,
+        message: 'OK',
+        seatsAvailable,
+        seatsUsed: currentUserCount,
+        seatCount,
+        billingAction: null
+    };
+}
+
+/**
+ * Get Stripe price ID for enterprise package
+ * @param {string} packageType - 'base' or 'full'
+ * @param {string} billingInterval - 'monthly' or 'annual'
+ * @returns {string|null} Stripe price ID
+ */
+function getEnterprisePriceId(packageType, billingInterval = 'monthly') {
+    const pkg = ENTERPRISE_PACKAGES[packageType];
+    if (!pkg) return null;
+
+    return billingInterval === 'annual'
+        ? pkg.stripePriceIdAnnual25
+        : pkg.stripePriceIdMonthly25;
+}
+
+/**
+ * Get Stripe price ID for enterprise add-on
+ * @param {string} addonId - Add-on identifier
+ * @param {string} billingInterval - 'monthly' or 'annual'
+ * @returns {string|null} Stripe price ID
+ */
+function getAddonPriceId(addonId, billingInterval = 'monthly') {
+    const addon = ENTERPRISE_ADDONS[addonId];
+    if (!addon) return null;
+
+    return billingInterval === 'annual'
+        ? addon.stripePriceIdAnnual25
+        : addon.stripePriceIdMonthly25;
+}
+
+module.exports = {
+    // Constants
+    SUBSCRIPTION_TIERS,
+    STANDARDS_PACKAGES,
+    EARLY_ADOPTER_DISCOUNT,
+    ENTERPRISE_PACKAGES,
+    ENTERPRISE_ADDONS,
+    VOLUME_DISCOUNTS,
+
+    // Tier functions
+    getTierConfig,
+    hasFeature,
+    checkSubscriptionLimits,
+    getStripePriceId,
+    getStripeProductId,
+    getRecommendedUpgrade,
+    calculateTierCost,
+    getAllTiers,
+    normalizeTierName,
+
+    // Standards functions
+    getTierStandards,
+    hasStandardsAccess,
+    getAllStandardsPackages,
+    canPickStandards,
+    getEnabledStandardsForUser,
+
+    // Community vs Private functions
+    requiresCommunityContribution,
+    getPrivateTierVariant,
+    getBaseTier,
+
+    // Early adopter discount functions
+    checkEarlyAdopterEligibility,
+    getEarlyAdopterDiscount,
+    calculateEarlyAdopterPrice,
+
+    // Billing type functions
+    BILLING_TYPES,
+    usesStripeBilling,
+    usesInvoiceBilling,
+    isInternalClient,
+    checkCollaboratorBillingLimits,
+    getBillingTypeDisplayName,
+
+    // Enterprise functions
+    getVolumeDiscount,
+    validateSeatCount,
+    calculateEnterpriseCost,
+    getEnterprisePackage,
+    getEnterpriseAddon,
+    getAllEnterpriseAddons,
+    hasEnterpriseFeature,
+    getEnterpriseFeatures,
+    checkEnterpriseSeatLimits,
+    getEnterprisePriceId,
+    getAddonPriceId
+};