@tpmjs/churn-risk-score 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 TPMJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import * as ai from 'ai';
+
+/**
+ * Churn Risk Scoring Tool for TPMJS
+ * Scores customer churn risk based on usage, engagement, and support signals
+ *
+ * This is a proper AI SDK v6 tool that can be used with streamText()
+ * Uses jsonSchema() to avoid Zod 4 JSON Schema conversion issues with OpenAI
+ */
+interface CustomerData {
+    id: string;
+    name: string;
+    subscriptionStartDate: string;
+    lastLoginDate?: string;
+    loginCount30Days?: number;
+    activeUsersCount?: number;
+    totalSeats?: number;
+    supportTicketsCount30Days?: number;
+    negativeTicketsCount30Days?: number;
+    npsScore?: number;
+    billingIssues?: boolean;
+    contractEndDate?: string;
+}
+interface RiskFactor {
+    factor: string;
+    impact: 'high' | 'medium' | 'low';
+    score: number;
+    description: string;
+}
+interface ChurnRiskScore {
+    customerId: string;
+    customerName: string;
+    riskScore: number;
+    riskLevel: 'critical' | 'high' | 'medium' | 'low';
+    riskFactors: RiskFactor[];
+    recommendations: string[];
+    summary: string;
+}
+/**
+ * Input type for Churn Risk Score Tool
+ */
+type ChurnRiskScoreInput = {
+    customer: CustomerData;
+};
+/**
+ * Churn Risk Score Tool
+ * Scores customer churn risk based on multiple signals
+ *
+ * This is a proper AI SDK v6 tool that can be used with streamText()
+ */
+declare const churnRiskScoreTool: ai.Tool<ChurnRiskScoreInput, {
+    customerId: string;
+    customerName: string;
+    riskScore: number;
+    riskLevel: "high" | "medium" | "low" | "critical";
+    riskFactors: RiskFactor[];
+    recommendations: string[];
+    summary: string;
+}>;
+
+export { type ChurnRiskScore, type CustomerData, type RiskFactor, churnRiskScoreTool, churnRiskScoreTool as default };

package/dist/index.js

@@ -0,0 +1,240 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+function daysBetween(date1, date2) {
+  const d1 = new Date(date1);
+  const d2 = new Date(date2);
+  return Math.abs(d2.getTime() - d1.getTime()) / (1e3 * 60 * 60 * 24);
+}
+function calculateUsageRisk(customer) {
+  const factors = [];
+  if (customer.lastLoginDate) {
+    const daysSinceLogin = daysBetween(customer.lastLoginDate, (/* @__PURE__ */ new Date()).toISOString());
+    if (daysSinceLogin > 30) {
+      factors.push({
+        factor: "Inactive User",
+        impact: "high",
+        score: 25,
+        description: `No login in ${Math.round(daysSinceLogin)} days`
+      });
+    } else if (daysSinceLogin > 14) {
+      factors.push({
+        factor: "Low Activity",
+        impact: "medium",
+        score: 15,
+        description: `Last login ${Math.round(daysSinceLogin)} days ago`
+      });
+    }
+  }
+  if (customer.loginCount30Days !== void 0) {
+    if (customer.loginCount30Days === 0) {
+      factors.push({
+        factor: "Zero Logins",
+        impact: "high",
+        score: 30,
+        description: "No logins in the last 30 days"
+      });
+    } else if (customer.loginCount30Days < 5) {
+      factors.push({
+        factor: "Low Login Frequency",
+        impact: "medium",
+        score: 15,
+        description: `Only ${customer.loginCount30Days} logins in 30 days`
+      });
+    }
+  }
+  if (customer.activeUsersCount !== void 0 && customer.totalSeats !== void 0) {
+    const utilization = customer.activeUsersCount / customer.totalSeats;
+    if (utilization < 0.3) {
+      factors.push({
+        factor: "Low Seat Utilization",
+        impact: "medium",
+        score: 12,
+        description: `Only ${Math.round(utilization * 100)}% of seats are active`
+      });
+    }
+  }
+  return factors;
+}
+function calculateEngagementRisk(customer) {
+  const factors = [];
+  if (customer.npsScore !== void 0) {
+    if (customer.npsScore <= 6) {
+      factors.push({
+        factor: "Detractor (NPS)",
+        impact: "high",
+        score: 20,
+        description: `NPS score of ${customer.npsScore} indicates dissatisfaction`
+      });
+    } else if (customer.npsScore <= 8) {
+      factors.push({
+        factor: "Passive (NPS)",
+        impact: "medium",
+        score: 10,
+        description: `NPS score of ${customer.npsScore} shows passive satisfaction`
+      });
+    }
+  }
+  if (customer.contractEndDate) {
+    const daysUntilEnd = daysBetween((/* @__PURE__ */ new Date()).toISOString(), customer.contractEndDate);
+    if (daysUntilEnd < 30) {
+      factors.push({
+        factor: "Contract Ending Soon",
+        impact: "high",
+        score: 15,
+        description: `Contract ends in ${Math.round(daysUntilEnd)} days`
+      });
+    } else if (daysUntilEnd < 60) {
+      factors.push({
+        factor: "Contract Renewal Approaching",
+        impact: "medium",
+        score: 8,
+        description: `Contract ends in ${Math.round(daysUntilEnd)} days`
+      });
+    }
+  }
+  return factors;
+}
+function calculateSupportRisk(customer) {
+  const factors = [];
+  if (customer.supportTicketsCount30Days !== void 0) {
+    if (customer.supportTicketsCount30Days > 10) {
+      factors.push({
+        factor: "High Support Volume",
+        impact: "medium",
+        score: 12,
+        description: `${customer.supportTicketsCount30Days} support tickets in 30 days`
+      });
+    }
+  }
+  if (customer.negativeTicketsCount30Days !== void 0 && customer.negativeTicketsCount30Days > 0) {
+    factors.push({
+      factor: "Negative Support Experience",
+      impact: "high",
+      score: 18,
+      description: `${customer.negativeTicketsCount30Days} negative support tickets`
+    });
+  }
+  if (customer.billingIssues) {
+    factors.push({
+      factor: "Billing Issues",
+      impact: "high",
+      score: 20,
+      description: "Active billing or payment issues"
+    });
+  }
+  return factors;
+}
+function generateRecommendations(factors) {
+  const recommendations = [];
+  const factorNames = factors.map((f) => f.factor);
+  if (factorNames.includes("Inactive User") || factorNames.includes("Zero Logins")) {
+    recommendations.push("Schedule an urgent check-in call to understand barriers to adoption");
+  }
+  if (factorNames.includes("Detractor (NPS)")) {
+    recommendations.push("Escalate to account manager for immediate intervention");
+  }
+  if (factorNames.includes("Low Seat Utilization")) {
+    recommendations.push("Offer onboarding sessions to increase team adoption");
+  }
+  if (factorNames.includes("Negative Support Experience")) {
+    recommendations.push("Review support tickets and follow up on unresolved issues");
+  }
+  if (factorNames.includes("Billing Issues")) {
+    recommendations.push("Resolve billing issues immediately - top churn indicator");
+  }
+  if (factorNames.includes("Contract Ending Soon")) {
+    recommendations.push("Initiate renewal conversation with decision maker");
+  }
+  if (factorNames.includes("High Support Volume")) {
+    recommendations.push("Identify root cause of support issues and provide proactive solutions");
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Continue regular engagement and monitor for changes in usage patterns");
+  }
+  return recommendations;
+}
+var churnRiskScoreTool = tool({
+  description: "Scores customer churn risk based on usage, engagement, and support signals. Provides risk score (0-100) with detailed contributing factors and recommendations.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      customer: {
+        type: "object",
+        description: "Customer data with activity metrics",
+        properties: {
+          id: { type: "string", description: "Customer ID" },
+          name: { type: "string", description: "Customer name" },
+          subscriptionStartDate: {
+            type: "string",
+            description: "Subscription start date (ISO format)"
+          },
+          lastLoginDate: { type: "string", description: "Last login date (ISO format)" },
+          loginCount30Days: { type: "number", description: "Number of logins in last 30 days" },
+          activeUsersCount: { type: "number", description: "Number of active users" },
+          totalSeats: { type: "number", description: "Total licensed seats" },
+          supportTicketsCount30Days: {
+            type: "number",
+            description: "Support tickets in last 30 days"
+          },
+          negativeTicketsCount30Days: {
+            type: "number",
+            description: "Negative support tickets in last 30 days"
+          },
+          npsScore: { type: "number", description: "NPS score (0-10)" },
+          billingIssues: {
+            type: "boolean",
+            description: "Whether there are active billing issues"
+          },
+          contractEndDate: { type: "string", description: "Contract end date (ISO format)" }
+        },
+        required: ["id", "name", "subscriptionStartDate"]
+      }
+    },
+    required: ["customer"],
+    additionalProperties: false
+  }),
+  async execute({ customer }) {
+    if (!customer.id || !customer.name) {
+      throw new Error("Customer ID and name are required");
+    }
+    const usageFactors = calculateUsageRisk(customer);
+    const engagementFactors = calculateEngagementRisk(customer);
+    const supportFactors = calculateSupportRisk(customer);
+    const allFactors = [...usageFactors, ...engagementFactors, ...supportFactors];
+    const totalScore = Math.min(
+      100,
+      allFactors.reduce((sum, factor) => sum + factor.score, 0)
+    );
+    let riskLevel;
+    if (totalScore >= 70) {
+      riskLevel = "critical";
+    } else if (totalScore >= 50) {
+      riskLevel = "high";
+    } else if (totalScore >= 25) {
+      riskLevel = "medium";
+    } else {
+      riskLevel = "low";
+    }
+    const recommendations = generateRecommendations(allFactors);
+    const highImpactFactors = allFactors.filter((f) => f.impact === "high");
+    let summary = `${customer.name} has a ${riskLevel} churn risk with a score of ${totalScore}/100.`;
+    if (highImpactFactors.length > 0) {
+      summary += ` Key concerns: ${highImpactFactors.map((f) => f.factor).join(", ")}.`;
+    } else {
+      summary += " No critical risk factors identified.";
+    }
+    return {
+      customerId: customer.id,
+      customerName: customer.name,
+      riskScore: totalScore,
+      riskLevel,
+      riskFactors: allFactors,
+      recommendations,
+      summary
+    };
+  }
+});
+var index_default = churnRiskScoreTool;
+
+export { churnRiskScoreTool, index_default as default };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@tpmjs/churn-risk-score",
+  "version": "0.1.0",
+  "description": "Scores customer churn risk based on usage, engagement, and support signals",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "cx",
+    "churn",
+    "retention",
+    "customer-success",
+    "analytics"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3",
+    "@tpmjs/tsconfig": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ajaxdavis/tpmjs.git",
+    "directory": "packages/tools/official/churn-risk-score"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "cx",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "exportName": "churnRiskScoreTool",
+        "description": "Scores customer churn risk based on usage, engagement, and support signals. Provides risk score (0-100) with detailed contributing factors and recommendations.",
+        "parameters": [
+          {
+            "name": "customer",
+            "type": "object",
+            "description": "Customer data with activity metrics including usage, engagement, and support interactions",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "ChurnRiskScore",
+          "description": "Risk score with contributing factors, risk level, and retention recommendations"
+        },
+        "aiAgent": {
+          "useCase": "Use this tool to identify at-risk customers, prioritize retention efforts, and proactively reduce churn. Ideal for customer success teams and account managers.",
+          "limitations": "Requires comprehensive customer data. Risk scoring is heuristic-based and should be combined with human judgment for critical decisions.",
+          "examples": [
+            "Identify customers at high risk of churning",
+            "Prioritize outreach for retention campaigns",
+            "Monitor customer health scores over time"
+          ]
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}