coderplan-tier 0.2.0 → 0.3.0

package/dist/recommender.js

@@ -40,6 +40,8 @@ export function recommend(usage) {
     const apiOnlyCost = projectedCosts.find((c) => c.tier === "API Only")?.monthlyCost ?? currentMonthlyCost;
     const recommendedCost = projectedCosts.find((c) => c.tier === tier)?.monthlyCost ?? currentMonthlyCost;
     const savings = apiOnlyCost - recommendedCost;
+    // Generate explanation comparing recommended tier to next tier up
+    const explanation = generateExplanation(tier, projectedCosts);
     return {
         tier,
         confidence,
@@ -47,6 +49,7 @@ export function recommend(usage) {
         projectedCosts,
         currentMonthlyCost,
         savings: Math.max(0, savings),
+        explanation,
     };
 }
 function selectLowestCostTier(projectedCosts) {
@@ -130,3 +133,44 @@ function generateReasons(tier, monthlyCost, activeDays, usage) {
     }
     return reasons;
 }
+const TIER_ORDER = ["API Only", "Pro", "Max 5x", "Max 20x"];
+function generateExplanation(recommendedTier, projectedCosts) {
+    const recommendedIdx = TIER_ORDER.indexOf(recommendedTier);
+    const recommendedCost = projectedCosts.find((c) => c.tier === recommendedTier);
+    if (!recommendedCost)
+        return null;
+    // Compare to next tier up (or down if at max)
+    let comparedTier;
+    if (recommendedIdx < TIER_ORDER.length - 1) {
+        comparedTier = TIER_ORDER[recommendedIdx + 1];
+    }
+    else {
+        comparedTier = TIER_ORDER[recommendedIdx - 1];
+    }
+    const comparedCost = projectedCosts.find((c) => c.tier === comparedTier);
+    if (!comparedCost)
+        return null;
+    const subscriptionDiff = comparedCost.subscriptionCost - recommendedCost.subscriptionCost;
+    const overflowDiff = recommendedCost.overflowCost - comparedCost.overflowCost;
+    // Calculate break-even point
+    // At break-even: recSub + recOverflow(x) = compSub + compOverflow(x)
+    // recSub + x*(1-recCoverage) = compSub + x*(1-compCoverage)
+    // x*(compCoverage - recCoverage) = compSub - recSub
+    // x = (compSub - recSub) / (compCoverage - recCoverage)
+    const recCoverage = COVERAGE_RATIO[recommendedTier];
+    const compCoverage = COVERAGE_RATIO[comparedTier];
+    const coverageDiff = compCoverage - recCoverage;
+    let breakEvenCost = 0;
+    if (coverageDiff > 0) {
+        breakEvenCost = Math.round(subscriptionDiff / coverageDiff);
+    }
+    return {
+        recommendedTier,
+        comparedTier,
+        recommendedCost,
+        comparedCost,
+        subscriptionDiff,
+        overflowDiff,
+        breakEvenCost,
+    };
+}

package/dist/renderer.js

@@ -61,6 +61,11 @@ export function renderRecommendation(usage, rec, verbose) {
         lines.push(boxContent(line));
     }
     lines.push(boxBottom());
+    // Why this tier? explanation
+    if (rec.explanation) {
+        lines.push("");
+        lines.push(...renderExplanation(rec.explanation));
+    }
     // Verbose: show detailed metrics
     if (verbose) {
         lines.push("");
@@ -96,9 +101,29 @@ export function renderJson(usage, rec) {
             currentMonthlyCost: rec.currentMonthlyCost,
             projectedSavings: rec.savings,
             tierCosts: rec.projectedCosts,
+            explanation: rec.explanation,
         },
     }, null, 2);
 }
+function renderExplanation(exp) {
+    const lines = [];
+    const rec = exp.recommendedCost;
+    const comp = exp.comparedCost;
+    lines.push(pc.bold(`Why ${exp.recommendedTier} over ${exp.comparedTier}?`));
+    lines.push(`   ${padRight(exp.recommendedTier + ":", 10)} $${rec.subscriptionCost} subscription + $${rec.overflowCost.toFixed(0)} overflow = ${pc.green(`$${rec.monthlyCost.toFixed(0)} total`)}`);
+    lines.push(`   ${padRight(exp.comparedTier + ":", 10)} $${comp.subscriptionCost} subscription + $${comp.overflowCost.toFixed(0)} overflow = ${pc.dim(`$${comp.monthlyCost.toFixed(0)} total`)}`);
+    lines.push("");
+    if (exp.subscriptionDiff > 0 && exp.overflowDiff > 0) {
+        lines.push(`   The $${exp.subscriptionDiff} subscription difference outweighs the $${exp.overflowDiff.toFixed(0)} overflow savings.`);
+    }
+    else if (exp.subscriptionDiff < 0) {
+        lines.push(`   Lower subscription ($${Math.abs(exp.subscriptionDiff)} less) with acceptable overflow.`);
+    }
+    if (exp.breakEvenCost > 0) {
+        lines.push(`   ${pc.dim(`${exp.comparedTier} becomes better when API costs reach ~$${exp.breakEvenCost}/month.`)}`);
+    }
+    return lines;
+}
 // Box drawing helpers
 function boxTop() {
     return pc.dim("╭" + "─".repeat(BOX_WIDTH) + "╮");

package/dist/types.d.ts

@@ -33,6 +33,16 @@ export interface Recommendation {
     projectedCosts: TierCost[];
     currentMonthlyCost: number;
     savings: number;
+    explanation: TierExplanation | null;
+}
+export interface TierExplanation {
+    recommendedTier: Tier;
+    comparedTier: Tier;
+    recommendedCost: TierCost;
+    comparedCost: TierCost;
+    subscriptionDiff: number;
+    overflowDiff: number;
+    breakEvenCost: number;
 }
 export interface TierCost {
     tier: Tier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderplan-tier",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Analyze Claude Code usage and get tier recommendations",
   "type": "module",
   "main": "dist/index.js",