@tpmjs/email-subject-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,62 @@
+import * as ai from 'ai';
+
+/**
+ * Email Subject Score Tool for TPMJS
+ * Scores email subject lines for open rate potential
+ *
+ * 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 SubjectScore {
+    subject: string;
+    overallScore: number;
+    scores: {
+        length: {
+            score: number;
+            ideal: string;
+            current: number;
+        };
+        clarity: {
+            score: number;
+            reason: string;
+        };
+        urgency: {
+            score: number;
+            reason: string;
+        };
+        curiosity: {
+            score: number;
+            reason: string;
+        };
+        personalization: {
+            score: number;
+            reason: string;
+        };
+    };
+    suggestions: string[];
+    predictedOpenRate: 'low' | 'medium' | 'high';
+}
+interface SubjectScores {
+    scores: SubjectScore[];
+    bestSubject: string;
+    averageScore: number;
+}
+/**
+ * Input type for Email Subject Score Tool
+ */
+type EmailSubjectScoreInput = {
+    subjects: string[];
+};
+/**
+ * Email Subject Score Tool
+ * Scores email subject lines for open rate potential
+ *
+ * This is a proper AI SDK v6 tool that can be used with streamText()
+ */
+declare const emailSubjectScoreTool: ai.Tool<EmailSubjectScoreInput, {
+    scores: SubjectScore[];
+    bestSubject: string;
+    averageScore: number;
+}>;
+
+export { type SubjectScore, type SubjectScores, emailSubjectScoreTool as default, emailSubjectScoreTool };

package/dist/index.js

@@ -0,0 +1,246 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+function scoreLengthCriterion(subject) {
+  const length = subject.length;
+  if (length >= 40 && length <= 60) {
+    return { score: 1, ideal: "40-60 chars (optimal)", current: length };
+  } else if (length >= 30 && length < 40) {
+    return { score: 0.8, ideal: "40-60 chars (optimal)", current: length };
+  } else if (length > 60 && length <= 70) {
+    return { score: 0.7, ideal: "40-60 chars (optimal)", current: length };
+  } else if (length < 30) {
+    return { score: 0.5, ideal: "40-60 chars (optimal)", current: length };
+  } else {
+    return { score: 0.4, ideal: "40-60 chars (optimal)", current: length };
+  }
+}
+function scoreClarityCriterion(subject) {
+  let score = 0.7;
+  const reasons = [];
+  const vagueWords = ["thing", "stuff", "something", "various", "some"];
+  const hasVagueWords = vagueWords.some((word) => subject.toLowerCase().includes(word));
+  if (hasVagueWords) {
+    score -= 0.3;
+    reasons.push("Contains vague language");
+  } else {
+    reasons.push("Uses specific language");
+  }
+  if (/\d+/.test(subject)) {
+    score += 0.2;
+    reasons.push("Includes specific numbers");
+  }
+  if (/[!?]{2,}/.test(subject)) {
+    score -= 0.2;
+    reasons.push("Excessive punctuation reduces clarity");
+  }
+  if (subject === subject.toUpperCase() && subject.length > 5) {
+    score -= 0.3;
+    reasons.push("All caps reduces readability");
+  }
+  return {
+    score: Math.max(0, Math.min(1, score)),
+    reason: reasons.join("; ")
+  };
+}
+function scoreUrgencyCriterion(subject) {
+  const urgencyWords = [
+    "today",
+    "now",
+    "urgent",
+    "limited",
+    "expires",
+    "deadline",
+    "last chance",
+    "ending soon",
+    "hurry",
+    "final",
+    "hours left",
+    "ends tonight"
+  ];
+  const lowerSubject = subject.toLowerCase();
+  const urgencyCount = urgencyWords.filter((word) => lowerSubject.includes(word)).length;
+  if (urgencyCount === 0) {
+    return { score: 0.3, reason: "No urgency indicators" };
+  } else if (urgencyCount === 1) {
+    return { score: 0.8, reason: "Moderate urgency" };
+  } else {
+    return { score: 0.6, reason: "High urgency (may seem pushy)" };
+  }
+}
+function scoreCuriosityCriterion(subject) {
+  let score = 0.5;
+  const reasons = [];
+  if (subject.includes("?")) {
+    score += 0.3;
+    reasons.push("Question creates curiosity");
+  }
+  const curiosityWords = [
+    "secret",
+    "reveal",
+    "discover",
+    "unlock",
+    "insider",
+    "exclusive",
+    "surprising",
+    "you won't believe",
+    "what",
+    "why",
+    "how"
+  ];
+  const curiosityCount = curiosityWords.filter(
+    (word) => subject.toLowerCase().includes(word)
+  ).length;
+  if (curiosityCount > 0) {
+    score += 0.2 * Math.min(curiosityCount, 2);
+    reasons.push("Uses curiosity-inducing language");
+  }
+  const benefitWords = ["free", "save", "bonus", "gift", "win", "earn"];
+  const hasBenefit = benefitWords.some((word) => subject.toLowerCase().includes(word));
+  if (hasBenefit) {
+    score += 0.2;
+    reasons.push("Highlights clear benefit");
+  }
+  if (reasons.length === 0) {
+    reasons.push("Could be more intriguing");
+  }
+  return {
+    score: Math.max(0, Math.min(1, score)),
+    reason: reasons.join("; ")
+  };
+}
+function scorePersonalizationCriterion(subject) {
+  let score = 0.4;
+  const reasons = [];
+  const hasPersonalizationToken = /\{|\[|%/.test(subject);
+  if (hasPersonalizationToken) {
+    score += 0.4;
+    reasons.push("Uses personalization tokens");
+  }
+  const hasYou = /\b(you|your)\b/i.test(subject);
+  if (hasYou) {
+    score += 0.3;
+    reasons.push("Direct personal address");
+  }
+  const hasNamePlaceholder = /\{(first_?name|name)\}/i.test(subject);
+  if (hasNamePlaceholder) {
+    score += 0.3;
+    reasons.push("Includes name placeholder");
+  }
+  if (reasons.length === 0) {
+    reasons.push("No personalization detected");
+  }
+  return {
+    score: Math.max(0, Math.min(1, score)),
+    reason: reasons.join("; ")
+  };
+}
+function generateSuggestions(subject, scores) {
+  const suggestions = [];
+  if (scores.length.current < 30) {
+    suggestions.push("Add more context - subject is too short");
+  } else if (scores.length.current > 70) {
+    suggestions.push("Shorten subject line - may get truncated on mobile");
+  }
+  if (scores.clarity.score < 0.6) {
+    suggestions.push("Use more specific, concrete language");
+  }
+  if (scores.urgency.score < 0.5) {
+    suggestions.push("Consider adding time-sensitive language if appropriate");
+  }
+  if (scores.curiosity.score < 0.5) {
+    suggestions.push("Add intrigue or highlight a benefit to spark curiosity");
+  }
+  if (scores.personalization.score < 0.6) {
+    suggestions.push('Add personalization tokens like {firstName} or use "you/your"');
+  }
+  const spamWords = ["free", "click here", "act now", "limited time", "buy now", "!!!", "100%"];
+  const hasSpamWords = spamWords.some((word) => subject.toLowerCase().includes(word));
+  if (hasSpamWords) {
+    suggestions.push("Reduce spam-trigger words to avoid spam filters");
+  }
+  const hasEmoji = /[\u{1F300}-\u{1F9FF}]/u.test(subject);
+  if (!hasEmoji) {
+    suggestions.push("Consider adding a relevant emoji for visual appeal (test first)");
+  }
+  return suggestions;
+}
+function calculateOverallScore(scores) {
+  const weights = {
+    length: 0.2,
+    clarity: 0.25,
+    urgency: 0.15,
+    curiosity: 0.25,
+    personalization: 0.15
+  };
+  const overall = scores.length.score * weights.length + scores.clarity.score * weights.clarity + scores.urgency.score * weights.urgency + scores.curiosity.score * weights.curiosity + scores.personalization.score * weights.personalization;
+  let openRate;
+  if (overall >= 0.75) {
+    openRate = "high";
+  } else if (overall >= 0.55) {
+    openRate = "medium";
+  } else {
+    openRate = "low";
+  }
+  return { overall, openRate };
+}
+function scoreSubject(subject) {
+  const length = scoreLengthCriterion(subject);
+  const clarity = scoreClarityCriterion(subject);
+  const urgency = scoreUrgencyCriterion(subject);
+  const curiosity = scoreCuriosityCriterion(subject);
+  const personalization = scorePersonalizationCriterion(subject);
+  const scores = {
+    length,
+    clarity,
+    urgency,
+    curiosity,
+    personalization
+  };
+  const { overall, openRate } = calculateOverallScore(scores);
+  const suggestions = generateSuggestions(subject, scores);
+  return {
+    subject,
+    overallScore: Math.round(overall * 100) / 100,
+    scores,
+    suggestions,
+    predictedOpenRate: openRate
+  };
+}
+var emailSubjectScoreTool = tool({
+  description: "Scores email subject lines for open rate potential based on length, clarity, urgency, curiosity, and personalization. Provides detailed feedback and improvement suggestions for each subject line.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      subjects: {
+        type: "array",
+        items: { type: "string" },
+        description: "Array of email subject lines to evaluate",
+        minItems: 1
+      }
+    },
+    required: ["subjects"],
+    additionalProperties: false
+  }),
+  async execute({ subjects }) {
+    if (!subjects || subjects.length === 0) {
+      throw new Error("At least one subject line is required");
+    }
+    if (subjects.some((s) => !s || s.trim().length === 0)) {
+      throw new Error("All subject lines must be non-empty strings");
+    }
+    const scoredSubjects = subjects.map(scoreSubject);
+    const averageScore = scoredSubjects.reduce((sum, s) => sum + s.overallScore, 0) / scoredSubjects.length;
+    const bestSubject = scoredSubjects.reduce(
+      (best, current) => current.overallScore > best.overallScore ? current : best
+    ).subject;
+    return {
+      scores: scoredSubjects,
+      bestSubject,
+      averageScore: Math.round(averageScore * 100) / 100
+    };
+  }
+});
+var index_default = emailSubjectScoreTool;
+
+export { index_default as default, emailSubjectScoreTool };

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@tpmjs/email-subject-score",
+  "version": "0.1.0",
+  "description": "Score email subject lines for open rate potential based on length, urgency, personalization",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "email",
+    "marketing",
+    "subject-line",
+    "ai"
+  ],
+  "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/email-subject-score"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "marketing",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "exportName": "emailSubjectScoreTool",
+        "description": "Scores email subject lines for open rate potential based on length, clarity, urgency, curiosity, and personalization. Provides detailed feedback and improvement suggestions.",
+        "parameters": [
+          {
+            "name": "subjects",
+            "type": "string[]",
+            "description": "Array of email subject lines to evaluate",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "SubjectScores",
+          "description": "Detailed scores for each subject line with overall score, criterion breakdown, suggestions, and predicted open rate (low/medium/high)"
+        },
+        "aiAgent": {
+          "useCase": "Use this tool when users need to evaluate and compare email subject lines for effectiveness. Helps optimize email marketing campaigns by scoring subjects on multiple criteria.",
+          "limitations": "Scores are based on best practices and heuristics, not actual A/B testing data. Results are predictive and should be validated with real campaign data.",
+          "examples": [
+            "Score these subject lines: 'New Product Launch' vs 'You won't believe what we just released'",
+            "Evaluate my email subject for open rate potential",
+            "Compare multiple subject lines and recommend the best one"
+          ]
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}