@tpmjs/nps-analysis 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,84 @@
+import * as ai from 'ai';
+
+/**
+ * NPS Analysis Tool for TPMJS
+ * Analyzes NPS survey responses and extracts themes
+ *
+ * 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 NPSResponse {
+    score: number;
+    comment?: string;
+    respondentId?: string;
+    date?: string;
+}
+interface NPSCategory {
+    category: 'promoter' | 'passive' | 'detractor';
+    count: number;
+    percentage: number;
+    responses: NPSResponse[];
+    themes: string[];
+}
+interface NPSAnalysis {
+    npsScore: number;
+    totalResponses: number;
+    distribution: {
+        promoters: NPSCategory;
+        passives: NPSCategory;
+        detractors: NPSCategory;
+    };
+    topThemes: {
+        promoterThemes: string[];
+        detractorThemes: string[];
+    };
+    recommendations: string[];
+    summary: string;
+}
+/**
+ * Input type for NPS Analysis Tool
+ */
+type NPSAnalysisInput = {
+    responses: NPSResponse[];
+};
+/**
+ * NPS Analysis Tool
+ * Analyzes NPS survey responses and extracts themes
+ *
+ * This is a proper AI SDK v6 tool that can be used with streamText()
+ */
+declare const npsAnalysisTool: ai.Tool<NPSAnalysisInput, {
+    npsScore: number;
+    totalResponses: number;
+    distribution: {
+        promoters: {
+            category: "promoter";
+            count: number;
+            percentage: number;
+            responses: NPSResponse[];
+            themes: string[];
+        };
+        passives: {
+            category: "passive";
+            count: number;
+            percentage: number;
+            responses: NPSResponse[];
+            themes: never[];
+        };
+        detractors: {
+            category: "detractor";
+            count: number;
+            percentage: number;
+            responses: NPSResponse[];
+            themes: string[];
+        };
+    };
+    topThemes: {
+        promoterThemes: string[];
+        detractorThemes: string[];
+    };
+    recommendations: string[];
+    summary: string;
+}>;
+
+export { type NPSAnalysis, type NPSCategory, type NPSResponse, npsAnalysisTool as default, npsAnalysisTool };

package/dist/index.js

@@ -0,0 +1,183 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+function categorizeScore(score) {
+  if (score >= 9) return "promoter";
+  if (score >= 7) return "passive";
+  return "detractor";
+}
+function extractThemesFromComments(comments) {
+  const themeKeywords = {
+    "Easy to Use": ["easy", "simple", "intuitive", "user-friendly", "straightforward"],
+    "Great Support": ["support", "help", "customer service", "responsive", "helpful"],
+    "Feature Rich": ["features", "functionality", "capabilities", "powerful", "comprehensive"],
+    "Good Value": ["value", "price", "worth", "affordable", "reasonable"],
+    Reliable: ["reliable", "stable", "dependable", "consistent", "works well"],
+    "Difficult to Use": ["difficult", "hard", "confusing", "complicated", "complex"],
+    "Missing Features": ["missing", "lack", "need", "want", "wish", "should have"],
+    "Poor Performance": ["slow", "lag", "crash", "freeze", "performance"],
+    Expensive: ["expensive", "costly", "overpriced", "too much", "price"],
+    "Poor Support": ["bad support", "slow response", "unhelpful", "poor service"],
+    "Bugs/Issues": ["bug", "broken", "error", "issue", "problem", "glitch"]
+  };
+  const themeCounts = /* @__PURE__ */ new Map();
+  for (const comment of comments) {
+    const lowerComment = comment.toLowerCase();
+    for (const [theme, keywords] of Object.entries(themeKeywords)) {
+      if (keywords.some((keyword) => lowerComment.includes(keyword))) {
+        themeCounts.set(theme, (themeCounts.get(theme) || 0) + 1);
+      }
+    }
+  }
+  return Array.from(themeCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([theme]) => theme);
+}
+function generateRecommendations(npsScore, detractorThemes, promoterThemes) {
+  const recommendations = [];
+  if (npsScore < 0) {
+    recommendations.push(
+      "CRITICAL: NPS is negative - immediate action required to address customer dissatisfaction"
+    );
+  } else if (npsScore < 30) {
+    recommendations.push("LOW: Focus on addressing detractor concerns to improve NPS");
+  }
+  if (detractorThemes.includes("Difficult to Use")) {
+    recommendations.push("Invest in UX improvements and onboarding materials");
+  }
+  if (detractorThemes.includes("Missing Features")) {
+    recommendations.push("Review feature requests and prioritize high-impact additions");
+  }
+  if (detractorThemes.includes("Poor Performance")) {
+    recommendations.push("Prioritize performance optimization and infrastructure improvements");
+  }
+  if (detractorThemes.includes("Poor Support")) {
+    recommendations.push("Improve support response times and training");
+  }
+  if (detractorThemes.includes("Expensive")) {
+    recommendations.push("Review pricing strategy or add more value to justify current pricing");
+  }
+  if (detractorThemes.includes("Bugs/Issues")) {
+    recommendations.push("Focus on stability and quality assurance");
+  }
+  if (promoterThemes.length > 0) {
+    recommendations.push(
+      `Amplify strengths in marketing: ${promoterThemes.slice(0, 2).join(", ")}`
+    );
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Maintain current service levels and continue monitoring feedback");
+  }
+  return recommendations;
+}
+var npsAnalysisTool = tool({
+  description: "Analyzes NPS survey responses to categorize by promoter/passive/detractor and extract themes from comments. Provides NPS score, distribution, and actionable insights.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      responses: {
+        type: "array",
+        description: "NPS survey responses with score (0-10) and optional comment",
+        items: {
+          type: "object",
+          properties: {
+            score: {
+              type: "number",
+              description: "NPS score from 0-10",
+              minimum: 0,
+              maximum: 10
+            },
+            comment: {
+              type: "string",
+              description: "Optional comment from respondent"
+            },
+            respondentId: {
+              type: "string",
+              description: "Optional respondent identifier"
+            },
+            date: {
+              type: "string",
+              description: "Optional response date (ISO format)"
+            }
+          },
+          required: ["score"]
+        }
+      }
+    },
+    required: ["responses"],
+    additionalProperties: false
+  }),
+  async execute({ responses }) {
+    if (!Array.isArray(responses) || responses.length === 0) {
+      throw new Error("responses must be a non-empty array");
+    }
+    for (const response of responses) {
+      if (response.score < 0 || response.score > 10) {
+        throw new Error(`Invalid NPS score: ${response.score}. Must be between 0 and 10.`);
+      }
+    }
+    const promoters = [];
+    const passives = [];
+    const detractors = [];
+    for (const response of responses) {
+      const category = categorizeScore(response.score);
+      if (category === "promoter") {
+        promoters.push(response);
+      } else if (category === "passive") {
+        passives.push(response);
+      } else {
+        detractors.push(response);
+      }
+    }
+    const totalResponses = responses.length;
+    const promoterPercentage = promoters.length / totalResponses * 100;
+    const detractorPercentage = detractors.length / totalResponses * 100;
+    const npsScore = Math.round(promoterPercentage - detractorPercentage);
+    const promoterComments = promoters.map((r) => r.comment).filter((c) => !!c && c.trim().length > 0);
+    const detractorComments = detractors.map((r) => r.comment).filter((c) => !!c && c.trim().length > 0);
+    const promoterThemes = extractThemesFromComments(promoterComments);
+    const detractorThemes = extractThemesFromComments(detractorComments);
+    const recommendations = generateRecommendations(npsScore, detractorThemes, promoterThemes);
+    let summary = `NPS Score: ${npsScore}. `;
+    summary += `${promoters.length} promoters (${Math.round(promoterPercentage)}%), `;
+    summary += `${passives.length} passives (${Math.round(passives.length / totalResponses * 100)}%), `;
+    summary += `${detractors.length} detractors (${Math.round(detractorPercentage)}%). `;
+    if (detractorThemes.length > 0) {
+      summary += `Top detractor concerns: ${detractorThemes.slice(0, 2).join(", ")}.`;
+    }
+    return {
+      npsScore,
+      totalResponses,
+      distribution: {
+        promoters: {
+          category: "promoter",
+          count: promoters.length,
+          percentage: Math.round(promoterPercentage * 100) / 100,
+          responses: promoters,
+          themes: promoterThemes
+        },
+        passives: {
+          category: "passive",
+          count: passives.length,
+          percentage: Math.round(passives.length / totalResponses * 100 * 100) / 100,
+          responses: passives,
+          themes: []
+        },
+        detractors: {
+          category: "detractor",
+          count: detractors.length,
+          percentage: Math.round(detractorPercentage * 100) / 100,
+          responses: detractors,
+          themes: detractorThemes
+        }
+      },
+      topThemes: {
+        promoterThemes,
+        detractorThemes
+      },
+      recommendations,
+      summary
+    };
+  }
+});
+var index_default = npsAnalysisTool;
+
+export { index_default as default, npsAnalysisTool };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@tpmjs/nps-analysis",
+  "version": "0.1.0",
+  "description": "Analyzes NPS survey responses to categorize by promoter/detractor and extract themes",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "cx",
+    "nps",
+    "survey",
+    "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/nps-analysis"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "cx",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "exportName": "npsAnalysisTool",
+        "description": "Analyzes NPS survey responses to categorize by promoter/passive/detractor and extract themes from comments. Provides NPS score, distribution, and actionable insights.",
+        "parameters": [
+          {
+            "name": "responses",
+            "type": "object[]",
+            "description": "NPS survey responses with score (0-10) and optional comment",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "NPSAnalysis",
+          "description": "NPS breakdown with score, distribution, themes by category, and recommendations"
+        },
+        "aiAgent": {
+          "useCase": "Use this tool to analyze NPS survey results, identify themes from promoters and detractors, and extract actionable insights for product and customer success teams.",
+          "limitations": "Theme extraction is keyword-based. For deeper sentiment analysis, consider using an AI model. Requires sufficient response volume for meaningful analysis.",
+          "examples": [
+            "Analyze quarterly NPS survey results",
+            "Extract themes from detractor comments",
+            "Compare promoter vs detractor feedback"
+          ]
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}