Pricing

from $0.70 / 1,000 person name cleaneds

Superclean Person Names

Clean messy person names for cold email and CRM. Extracts first names for personalization, fixes ALL CAPS, handles McDonald/O'Brien/van der Berg correctly, strips titles (Dr.) and credentials (PhD). Three styles: first name only, casual, or formal.

Pricing

from $0.70 / 1,000 person name cleaneds

Rating

0.0

(0)

Developer

Superlative

Actor stats

Bookmarked

Total users

Monthly active users

8 days ago

Last modified

Superclean Company Names

superlativetech/superclean-company-names

Transform messy company names into clean formats for outreach. Removes legal suffixes (Inc, LLC, Ltd), fixes ALL CAPS, preserves brand identity. Perfect for cold email personalization, CRM cleanup, and lead enrichment. Supports casual, formal, and legal output styles. LLM-powered normalizer.

Superlative

Superclean Job Titles

superlativetech/superclean-job-titles

Clean messy job titles instantly. AI fixes abbreviations (Sr. → Senior), removes junk (Ninja, Rockstar), strips department tags, and standardizes formats. 3 output styles for CRM, spreadsheets, or analytics. Better data means better lead scoring and personalization.

Superlative

Superclean Product Names

superlativetech/superclean-product-names

Clean messy product names from e-commerce exports and web scraping. AI removes promo text, prices, SKUs, and formatting noise. Three styles: Clean (core name only), Full (with attributes), Searchable (lowercase for dedup). Works with Shopify, Amazon, and any catalog data.

Superlative

Clearbit Person

tomba-io/clearbit-person

Enriches person information using the Tomba Person Enrichment API

Tomba io

Email Finder & Verifier

startuphub/email-finder

Find and verify a person's work email from their first name, last name, and company domain.

StartupHub

Superclean URLs

superlativetech/superclean-urls

Clean messy URLs from lead exports. Remove 60+ tracking parameters (utm_*, fbclid, gclid), normalize format, extract domains, and optionally verify URLs are reachable. Perfect for cold email personalization and CRM data hygiene.

Superlative

Instagram Related Person Scraper

scrapemesh/instagram-related-person-scraper

🔎 Instagram Related Person Scraper (instagram-related-person-scraper) extracts similar/suggested profiles from public IG accounts—usernames, names, bios, profile URLs, and categories. 🚀 Ideal for influencer discovery, competitor research, audience growth & lead lists.

ScrapeMesh

Instagram Related Person Scraper

scrapium/instagram-related-person-scraper

🔎 Instagram Related Person Scraper finds and exports related accounts from public IG profiles—names, handles & profile links. 📊 Ideal for influencer discovery, competitor mapping & audience research. ⚡ Fast, accurate, and compliance-friendly. 🚀

Scrapium

🎉 Linkedin Profiles

prog-party/linkedin-profiles

Search for Linkedin profiles by person name.

Prog Party

LinkedIn Person Profile

truefetch/linkedin-person-profile

Export any LinkedIn Person profile — current role, company, city, education, skills, certifications, and 15 fields. Feed CRM or recruiting pipelines. $100 per 1,000.

TrueFetch

5.0

{ "name": "superclean-person-names", "version": "0.1.0", "type": "module", "description": "Clean messy person names for cold email personalization, CRM, and lead lists. Handles ALL CAPS, titles, credentials, and special cases like McDonald and O'Brien.", "engines": { "node": ">=18.0.0" }, "dependencies": { "apify": "^3.5.2", "openai": "^4.0.0" }, "scripts": { "start": "node ./src/main.js", "test": "node --test tests/*.test.js" }, "author": "Superlative", "license": "ISC" }

1/** 2 * Rule-based pre-processing for person name normalization. 3 * Applies deterministic transformations before LLM processing. 4 */ 5 6import { 7 TITLES, 8 CREDENTIALS, 9 GENERATIONAL_SUFFIXES, 10 LOWERCASE_PARTICLES, 11 NORMALIZE_CHARS, 12 SYMBOL_PATTERN, 13 NON_LATIN_PATTERN, 14 NON_NAME_PATTERNS, 15} from './constants.js'; 16 17/** 18 * Check if a string contains non-Latin script characters (CJK, Arabic, Cyrillic, etc.) 19 * @param {string} str - String to check 20 * @returns {boolean} True if contains non-Latin scripts 21 */ 22function containsNonLatinScript(str) { 23 return NON_LATIN_PATTERN.test(str); 24} 25 26/** 27 * Extract the English (Latin script) portion from a mixed-language string. 28 * Common in lead lists: "李明 (Mike Li)" -> "Mike Li" 29 * @param {string} str - Mixed-language string 30 * @returns {string|null} English portion, or null if no substantial English found 31 */ 32function extractEnglishPortion(str) { 33 if (!str) return null; 34 35 // Look for parenthetical English name first: "李明 (Mike Li)" 36 const parenMatch = str.match(/$([A-Za-z][A-Za-z\s.'-]+)$/); 37 if (parenMatch) { 38 const english = parenMatch[1].trim(); 39 if (english.length >= 2) { 40 return english; 41 } 42 } 43 44 // Extract all Latin script portions 45 const latinPattern = /[A-Za-z][A-Za-z\s.'-]*/g; 46 const matches = str.match(latinPattern); 47 if (!matches) return null; 48 49 let english = matches.join(' ').trim(); 50 english = english.replace(/^[.,\s-]+|[.,\s-]+$/g, '').replace(/\s+/g, ' ').trim(); 51 52 if (english.length >= 2) { 53 return english; 54 } 55 56 return null; 57} 58 59/** 60 * Detect if a word is a title (Dr., Mr., etc.) 61 * @param {string} word - Word to check 62 * @returns {boolean} True if it's a title 63 */ 64function isTitle(word) { 65 return TITLES.has(word.toLowerCase().replace(/\.$/, '')); 66} 67 68/** 69 * Detect if a word is a credential (PhD, MD, etc.) 70 * @param {string} word - Word to check 71 * @returns {boolean} True if it's a credential 72 */ 73function isCredential(word) { 74 return CREDENTIALS.has(word.toLowerCase().replace(/\.$/, '')); 75} 76 77/** 78 * Detect if a word is a generational suffix (Jr., III, etc.) 79 * @param {string} word - Word to check 80 * @returns {boolean} True if it's a generational suffix 81 */ 82function isGenerationalSuffix(word) { 83 return GENERATIONAL_SUFFIXES.has(word.toLowerCase().replace(/\.$/, '')); 84} 85 86/** 87 * Apply special capitalization rules for names like McDonald, O'Brien. 88 * @param {string} word - Word to process 89 * @returns {string} Word with correct capitalization 90 */ 91function applySpecialCaps(word) { 92 const lower = word.toLowerCase(); 93 94 // Handle Mc prefix: McDonald, McBride 95 if (lower.startsWith('mc') && lower.length > 2) { 96 return `Mc${word.charAt(2).toUpperCase()}${word.slice(3).toLowerCase()}`; 97 } 98 99 // Handle Mac prefix: MacArthur, MacDonald 100 // But not words like "machine" or "macy" 101 if (lower.startsWith('mac') && lower.length > 4 && /^mac[a-z]/i.test(lower)) { 102 // Check if it looks like a Scottish name (capital after Mac in original, or long enough) 103 const afterMac = word.slice(3); 104 if (afterMac.length > 0 && (afterMac[0] === afterMac[0].toUpperCase() || lower.length > 5)) { 105 return `Mac${word.charAt(3).toUpperCase()}${word.slice(4).toLowerCase()}`; 106 } 107 } 108 109 // Handle O' prefix: O'Brien, O'Neill 110 if (lower.startsWith("o'") && lower.length > 2) { 111 return `O'${word.charAt(2).toUpperCase()}${word.slice(3).toLowerCase()}`; 112 } 113 114 // Handle D' prefix: D'Angelo, D'Arcy 115 if (lower.startsWith("d'") && lower.length > 2) { 116 return `D'${word.charAt(2).toUpperCase()}${word.slice(3).toLowerCase()}`; 117 } 118 119 return null; // No special caps needed 120} 121 122/** 123 * Convert a word to title case, handling hyphens and special patterns. 124 * @param {string} word - Word to convert 125 * @param {boolean} isFirst - Whether this is the first word 126 * @returns {string} Title-cased word 127 */ 128function titleCaseWord(word, isFirst = false) { 129 if (!word) return word; 130 131 // Check for special capitalization patterns first 132 const special = applySpecialCaps(word); 133 if (special) return special; 134 135 const lower = word.toLowerCase(); 136 137 // Handle particles (van, de, etc.) - lowercase unless first word 138 if (!isFirst && LOWERCASE_PARTICLES.has(lower)) { 139 return lower; 140 } 141 142 // Handle hyphenated names: Mary-Jane, Saint-Pierre 143 if (word.includes('-')) { 144 return word 145 .split('-') 146 .map((part, idx) => titleCaseWord(part, idx === 0 && isFirst)) 147 .join('-'); 148 } 149 150 // Handle apostrophes within words (not at start): Stone's 151 if (word.includes("'") && !lower.startsWith("o'") && !lower.startsWith("d'")) { 152 const parts = word.split("'"); 153 return parts 154 .map((part, idx) => { 155 if (idx === 0) { 156 return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(); 157 } 158 // After apostrophe, lowercase (Stone's, not Stone'S) 159 return part.toLowerCase(); 160 }) 161 .join("'"); 162 } 163 164 // Standard title case 165 return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase(); 166} 167 168/** 169 * Convert a full name to title case, preserving special patterns. 170 * Handles multi-word particles like "van der", "van de", etc. 171 * @param {string} str - Full name string 172 * @returns {string} Title-cased name 173 */ 174function toTitleCase(str) { 175 const words = str.split(/\s+/); 176 const result = []; 177 let inParticle = false; // Track if we're in a multi-word particle 178 179 for (let idx = 0; idx < words.length; idx++) { 180 const word = words[idx]; 181 const lower = word.toLowerCase(); 182 183 // Check if this word follows a particle (like "der" after "van") 184 if (inParticle && LOWERCASE_PARTICLES.has(lower)) { 185 result.push(lower); 186 continue; 187 } 188 189 // Check if this word is a particle 190 if (LOWERCASE_PARTICLES.has(lower) && idx !== 0) { 191 result.push(lower); 192 inParticle = true; 193 continue; 194 } 195 196 // Not a particle or not in particle sequence 197 inParticle = false; 198 result.push(titleCaseWord(word, idx === 0)); 199 } 200 201 return result.join(' '); 202} 203 204/** 205 * Pre-process a person name value. 206 * @param {string} value - The raw input value 207 * @returns {Object} Object with preprocessed value and metadata 208 */ 209export function preprocess(value) { 210 if (!value || typeof value !== 'string') { 211 return { 212 value: '', 213 isNonEnglish: false, 214 extractedEnglish: null, 215 detectedComponents: null, 216 }; 217 } 218 219 let result = value; 220 221 // Check for non-Latin scripts before processing 222 const isNonEnglish = containsNonLatinScript(result); 223 224 // For non-English strings, try to extract the English portion 225 let extractedEnglish = null; 226 if (isNonEnglish) { 227 extractedEnglish = extractEnglishPortion(result); 228 } 229 230 // Step 1: Remove emojis and symbols 231 result = result.replace(SYMBOL_PATTERN, '').trim(); 232 233 // Step 2: Normalize special characters to ASCII (smart quotes, dashes, etc.) 234 for (const [from, to] of Object.entries(NORMALIZE_CHARS)) { 235 result = result.split(from).join(to); 236 } 237 238 // Step 3: Strip non-name content (emails, phone numbers, URLs, company context) 239 for (const pattern of NON_NAME_PATTERNS) { 240 result = result.replace(pattern, '').trim(); 241 } 242 243 // Step 4: Trim and collapse whitespace 244 result = result.trim().replace(/\s+/g, ' '); 245 246 // Step 5: Person name-specific processing (only if English) 247 let detectedComponents = null; 248 if (!isNonEnglish && result) { 249 const processed = preprocessPersonName(result); 250 result = processed.value; 251 detectedComponents = processed.components; 252 } 253 254 return { value: result, isNonEnglish, extractedEnglish, detectedComponents }; 255} 256 257/** 258 * Pre-process person names by detecting components and normalizing case. 259 * @param {string} value - Person name 260 * @returns {Object} Object with cleaned name and detected components 261 */ 262function preprocessPersonName(value) { 263 let result = value; 264 const components = { 265 titles: [], 266 credentials: [], 267 suffixes: [], 268 }; 269 270 // Check if needs case normalization (ALL CAPS or all lowercase) 271 const needsCaseNormalization = result.length > 0 272 && (result === result.toUpperCase() || result === result.toLowerCase()); 273 274 // Step 1: Detect and extract titles from the beginning 275 const words = result.split(/\s+/); 276 let startIdx = 0; 277 while (startIdx < words.length && isTitle(words[startIdx])) { 278 components.titles.push(words[startIdx]); 279 startIdx++; 280 } 281 282 // Step 2: Detect and extract credentials and suffixes from the end 283 // Work backwards through the words 284 let endIdx = words.length - 1; 285 while (endIdx >= startIdx) { 286 const word = words[endIdx].replace(/,/g, ''); // Remove commas 287 if (isCredential(word)) { 288 components.credentials.unshift(word); 289 endIdx--; 290 } else if (isGenerationalSuffix(word)) { 291 components.suffixes.unshift(word); 292 endIdx--; 293 } else { 294 break; 295 } 296 } 297 298 // Extract the core name (between titles and suffixes/credentials) 299 const coreWords = words.slice(startIdx, endIdx + 1); 300 result = coreWords.join(' '); 301 302 // Clean up any stray commas 303 result = result.replace(/,\s*$/, '').replace(/^\s*,/, '').trim(); 304 305 // Step 3: Apply case normalization if needed 306 if (needsCaseNormalization && result) { 307 result = toTitleCase(result); 308 } 309 310 // Step 4: Clean up multiple spaces 311 result = result.replace(/\s+/g, ' ').trim(); 312 313 return { value: result, components }; 314} 315 316/** 317 * Format detected components for a specific style. 318 * @param {string} coreName - The core name (without titles/credentials) 319 * @param {Object} components - Detected components {titles, credentials, suffixes} 320 * @param {string} style - Output style ('first', 'casual', 'formal') 321 * @returns {string} Formatted name 322 */ 323export function formatWithComponents(coreName, components, style) { 324 if (!coreName) return ''; 325 326 switch (style) { 327 case 'first': 328 // Just the first name 329 return coreName.split(/\s+/)[0]; 330 331 case 'casual': 332 // Full name with suffixes but no titles/credentials 333 if (components?.suffixes?.length > 0) { 334 return `${coreName} ${components.suffixes.join(' ')}`; 335 } 336 return coreName; 337 338 case 'formal': 339 // Everything: titles, name, suffixes, credentials 340 const parts = []; 341 if (components?.titles?.length > 0) { 342 parts.push(components.titles.join(' ')); 343 } 344 parts.push(coreName); 345 if (components?.suffixes?.length > 0) { 346 parts.push(components.suffixes.join(' ')); 347 } 348 if (components?.credentials?.length > 0) { 349 parts.push(components.credentials.join(', ')); 350 } 351 return parts.join(' ').replace(/\s+,/, ','); 352 353 default: 354 return coreName; 355 } 356}

1/** 2 * Constants for person name normalization patterns. 3 */ 4 5// Titles to strip (for casual/first styles, keep for formal) 6export const TITLES = new Set([ 7 'dr', 'dr.', 8 'mr', 'mr.', 9 'mrs', 'mrs.', 10 'ms', 'ms.', 11 'miss', 12 'sir', 13 'madam', 14 'prof', 'prof.', 'professor', 15 'rev', 'rev.', 'reverend', 16 'hon', 'hon.', 'honorable', 17 'fr', 'fr.', 'father', 18 'sr', 'sr.', 'sister', // Religious sister, not Senior 19 'br', 'br.', 'brother', 20 'rabbi', 21 'imam', 22 'capt', 'capt.', 'captain', 23 'col', 'col.', 'colonel', 24 'gen', 'gen.', 'general', 25 'lt', 'lt.', 'lieutenant', 26 'maj', 'maj.', 'major', 27 'sgt', 'sgt.', 'sergeant', 28]); 29 30// Generational suffixes (keep for casual/formal, strip for first) 31export const GENERATIONAL_SUFFIXES = new Set([ 32 'jr', 'jr.', 33 'sr', 'sr.', 34 'i', 'ii', 'iii', 'iv', 'v', 'vi', 'vii', 'viii', 35 '1st', '2nd', '3rd', '4th', 36]); 37 38// Professional credentials (strip for casual/first, keep for formal) 39export const CREDENTIALS = new Set([ 40 // Doctoral degrees 41 'phd', 'ph.d', 'ph.d.', 42 'md', 'm.d', 'm.d.', 43 'do', 'd.o', 'd.o.', 44 'dds', 'd.d.s', 'd.d.s.', 45 'dmd', 'd.m.d', 46 'jd', 'j.d', 'j.d.', 47 'edd', 'ed.d', 'ed.d.', 48 'psyd', 'psy.d', 49 'dvm', 'd.v.m', 50 // Master's degrees 51 'mba', 'm.b.a', 'm.b.a.', 52 'ma', 'm.a', 'm.a.', 53 'ms', 'm.s', 'm.s.', 54 'msc', 'm.sc', 55 'med', 'm.ed', 56 'msw', 'm.s.w', 57 'mpa', 'm.p.a', 58 'mph', 'm.p.h', 59 // Professional certifications 60 'cpa', 'c.p.a', 61 'cfa', 'c.f.a', 62 'cfp', 'c.f.p', 63 'pmp', 'p.m.p', 64 'pe', 'p.e', 65 // Medical/nursing 66 'rn', 'r.n', 67 'lpn', 'l.p.n', 68 'np', 'n.p', 69 'pa', 'p.a', 70 'aprn', 71 // Legal 72 'esq', 'esq.', 'esquire', 73 'llb', 'll.b', 74 'llm', 'll.m', 75]); 76 77// Surname prefixes that are PART of the name (don't strip, lowercase in casual style) 78export const SURNAME_PREFIXES = new Set([ 79 'van', 'van der', 'van de', 'van den', 80 'von', 'von der', 81 'de', 'de la', 'del', 'dela', 'della', 'dello', 82 'da', 'das', 'dos', 'du', 83 'di', 84 'le', 'la', 'les', 85 'el', 'al', 86 'bin', 'ibn', 87 'ben', 88 'den', 89 'ter', 90 'ten', 91 'op', 'op de', 92 'st', 'st.', 'saint', 93 'san', 94 'santa', 95]); 96 97// Special capitalization patterns (prefix -> correct form) 98export const SPECIAL_CAPS_PATTERNS = { 99 // Scottish/Irish prefixes 100 "mc": (name) => `Mc${name.charAt(2).toUpperCase()}${name.slice(3).toLowerCase()}`, 101 "mac": (name) => { 102 // MacArthur, MacDonald, but not Macy, Machine 103 if (name.length > 4 && /^mac[a-z]/i.test(name)) { 104 return `Mac${name.charAt(3).toUpperCase()}${name.slice(4).toLowerCase()}`; 105 } 106 return name.charAt(0).toUpperCase() + name.slice(1).toLowerCase(); 107 }, 108 "o'": (name) => `O'${name.charAt(2).toUpperCase()}${name.slice(3).toLowerCase()}`, 109 "d'": (name) => `D'${name.charAt(2).toUpperCase()}${name.slice(3).toLowerCase()}`, 110}; 111 112// Words that should stay lowercase in surnames (when not at start) 113export const LOWERCASE_PARTICLES = new Set([ 114 'van', 'von', 'de', 'da', 'du', 'del', 'della', 'di', 115 'le', 'la', 'les', 'el', 'al', 116 'bin', 'ibn', 'ben', 117 'der', 'den', 'ter', 'ten', 'op', 'het', 118]); 119 120// Special characters to normalize to ASCII equivalents 121export const NORMALIZE_CHARS = { 122 '\u2018': "'", // Left single quote 123 '\u2019': "'", // Right single quote 124 '\u201C': '"', // Left double quote 125 '\u201D': '"', // Right double quote 126 '\u2013': '-', // En dash 127 '\u2014': '-', // Em dash 128 '\u00A0': ' ', // Non-breaking space 129 '\u2026': '...', // Ellipsis 130 '\u00B7': '.', // Middle dot 131 '\u2010': '-', // Hyphen 132 '\u2011': '-', // Non-breaking hyphen 133 '\u2012': '-', // Figure dash 134}; 135 136// Emoji and symbol patterns to remove 137export const SYMBOL_PATTERN = /[\u{1F300}-\u{1F9FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{1F600}-\u{1F64F}\u{1F680}-\u{1F6FF}®™©★☆✨✓✔✗✘●○◆◇→←↑↓]/gu; 138 139// Non-Latin script detection 140export const NON_LATIN_PATTERN = /[\u4E00-\u9FFF\u3400-\u4DBF\u3000-\u303F\u3040-\u309F\u30A0-\u30FF\uAC00-\uD7AF\u0600-\u06FF\u0590-\u05FF\u0400-\u04FF\u0E00-\u0E7F]/; 141 142// Patterns to strip non-name content 143export const NON_NAME_PATTERNS = [ 144 // Email addresses 145 /[\w.-]+@[\w.-]+\.\w+/gi, 146 // Phone numbers (various formats) 147 /\+?1?\s*$?[0-9]{3}$?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}/g, 148 // URLs 149 /https?:\/\/\S+/gi, 150 /www\.\S+/gi, 151 // LinkedIn profile paths 152 /linkedin\.com\/in\/\S+/gi, 153 // Company context patterns 154 /\s+(?:at|@)\s+\S+.*$/i, 155 /,?\s+(?:VP|CEO|CTO|CFO|COO|Director|Manager|Engineer)\s+(?:at|of|@)\s+.+$/i, 156]; 157 158// Credentials that are commonly used as suffixes (for detection) 159export const CREDENTIAL_SUFFIXES_PATTERN = new RegExp( 160 `(?:,\\s*)?\\b(${[...CREDENTIALS].join('|')})\\b\\.?`, 161 'gi' 162); 163 164// Title pattern for detection (at start of string) 165export const TITLE_PATTERN = new RegExp( 166 `^(${[...TITLES].join('|')})\\b\\.?\\s*`, 167 'gi' 168); 169 170// Generational suffix pattern (at end of string) 171export const GENERATIONAL_PATTERN = new RegExp( 172 `(?:,\\s*)?\\b(${[...GENERATIONAL_SUFFIXES].join('|')})\\b\\.?\\s*$`, 173 'gi' 174);

1/** 2 * LLM-based semantic normalization for person names using Apify's OpenRouter standby actor. 3 * @see https://apify.com/apify/openrouter 4 */ 5 6import { log } from 'apify'; 7import OpenAI from 'openai'; 8 9const BATCH_SIZE = 10; // Process items in batches (kept small to avoid truncated LLM responses) 10const MAX_RETRIES = 3; // Maximum retry attempts for API calls 11const INITIAL_RETRY_DELAY_MS = 1000; // Start with 1 second delay 12const DEFAULT_CONCURRENCY = 5; // Default parallel batch limit 13const LARGE_REQUEST_THRESHOLD = 100; // Items threshold for increased concurrency 14const LARGE_REQUEST_CONCURRENCY = 10; // Concurrency for large requests 15const MAX_TOKENS = 2048; // Ensure sufficient output tokens for complete JSON responses 16 17// Apify's OpenRouter standby actor endpoint 18const OPENROUTER_BASE_URL = 'https://openrouter.apify.actor/api/v1'; 19// Direct OpenRouter API endpoint (bring your own key) 20const OPENROUTER_DIRECT_URL = 'https://openrouter.ai/api/v1'; 21 22/** 23 * Style-specific prompt modifiers for first, casual, and formal output. 24 */ 25const STYLE_MODIFIERS = { 26 first: `Extract ONLY the first/given name: 27 - Return JUST the first name, nothing else 28 - "Dr. John Michael Smith Jr." -> "John" 29 - "Mary-Jane O'Brien, PhD" -> "Mary-Jane" (keep hyphenated first names intact) 30 - "van der Berg, Johannes" -> "Johannes" (handle reversed name order) 31 - "J. Robert Smith" -> "Robert" (skip initials, use actual first name if present) 32 - "J.R. Smith" -> "J.R." (if only initials, keep them) 33 - Preserve proper capitalization: "JOHN" -> "John" 34 - Handle nicknames: "William (Bill) Smith" -> "Bill" or "William" (prefer the nickname for cold email)`, 35 36 casual: `Return the FULL NAME (first AND last name). Never return just a first name. 37 - Remove titles: Dr., Mr., Mrs., Ms., Prof., Rev., etc. 38 - Remove credentials: PhD, MD, MBA, CPA, Esq., CISSP, PMP, etc. 39 - ALWAYS KEEP generational suffixes: Jr., Sr., II, III, IV — these are NOT credentials 40 * "Clarence Bunch Jr" -> "Clarence Bunch Jr." (KEEP Jr.) 41 * "DENNIS WALKER SR" -> "Dennis Walker Sr." (KEEP Sr.) 42 * "James Smith III" -> "James Smith III" (KEEP III) 43 - Apply proper capitalization: 44 * "JOHN SMITH" -> "John Smith" 45 * "john smith" -> "John Smith" 46 * "mcdonald" -> "McDonald" 47 * "o'brien" -> "O'Brien" 48 * "van der berg" -> "Johannes van der Berg" (lowercase particles) 49 - Handle reversed names: "Smith, John" -> "John Smith" 50 - IMPORTANT: Always include both first and last name in output: 51 * "Cindy Campbell" -> "Cindy Campbell" (NOT just "Cindy") 52 * "Jeff Rowe" -> "Jeff Rowe" (NOT just "Jeff") 53 - More examples: 54 * "DR. JOHN SMITH JR., PhD" -> "John Smith Jr." 55 * "mary-jane o'brien" -> "Mary-Jane O'Brien" 56 * "JOHANNES VAN DER BERG" -> "Johannes van der Berg" 57 * "Dennis J Walker Jr" -> "Dennis J. Walker Jr."`, 58 59 formal: `Format the complete name professionally with all components: 60 - Keep and properly format titles: "dr" -> "Dr.", "prof" -> "Prof." 61 - Keep and properly format suffixes: "jr" -> "Jr.", "iii" -> "III" 62 - Keep and properly format credentials: "phd" -> "Ph.D.", "md" -> "M.D." 63 - Apply proper capitalization to the name itself 64 - Standard punctuation: periods after abbreviations 65 - Credentials after comma: "John Smith, Ph.D." 66 - Examples: 67 * "dr john smith jr phd" -> "Dr. John Smith Jr., Ph.D." 68 * "MARY O'BRIEN MD" -> "Mary O'Brien, M.D." 69 * "prof johannes van der berg" -> "Prof. Johannes van der Berg"`, 70}; 71 72/** 73 * Get the goal description for each style. 74 */ 75const STYLE_GOALS = { 76 first: 'Just the first name for cold email personalization (e.g., "Hi John,").', 77 casual: 'Clean full name without titles/credentials for CRM and general use.', 78 formal: 'Complete professional name with titles and credentials for formal correspondence.', 79}; 80 81/** 82 * Build the system prompt for person name normalization. 83 * @param {string} style - Output style ('first', 'casual', or 'formal') 84 * @returns {string} System prompt 85 */ 86function buildSystemPrompt(style) { 87 const effectiveStyle = STYLE_MODIFIERS[style] ? style : 'casual'; 88 89 return `You are normalizing person names for professional data cleanup. 90 91GOAL: ${STYLE_GOALS[effectiveStyle]} 92 93RULES: 94${STYLE_MODIFIERS[effectiveStyle]} 95 96SPECIAL CAPITALIZATION RULES: 97- Scottish/Irish names: McDonald, MacArthur, O'Brien, O'Neill 98- Dutch/German names: van der Berg, von Braun (particles lowercase except at start) 99- Italian names: da Vinci, di Caprio (particles lowercase except at start) 100- Hyphenated names: Mary-Jane, Jean-Pierre, Saint-Pierre (capitalize each part) 101- Apostrophes: O'Brien (capital after), Stone's (lowercase 's if possessive - but names usually aren't possessive) 102 103EDGE CASES: 104- Reversed format "Smith, John" -> "John Smith" 105- Nicknames in parentheses: "William (Bill) Smith" -> "Bill Smith" (prefer nickname) 106- Single names: "Madonna", "Cher" -> return as-is 107- Initials: keep middle initials with periods ("J. Robert Smith" -> depends on style) 108 109OUTPUT FORMAT (strict JSON, no comments): 110[{"index": 0, "normalized": "John Smith Jr.", "confidence": 0.95}] 111Return ONLY the JSON array with objects containing "index", "normalized", and "confidence" keys.`; 112} 113 114/** 115 * Create a normalizer instance configured with Apify's OpenRouter standby actor. 116 * Uses APIFY_TOKEN for authentication - no separate API key needed. 117 * @param {string} model - OpenRouter model to use 118 * @param {string} style - Output style ('first', 'casual', or 'formal') 119 * @param {string|null} openRouterApiKey - Optional OpenRouter API key for direct API access (bring your own key) 120 * @returns {Object} Normalizer with normalize() method 121 */ 122export function createNormalizer(model, style = 'casual', openRouterApiKey = null) { 123 let openai; 124 125 if (openRouterApiKey) { 126 log.info('Using direct OpenRouter API (bring your own key)'); 127 openai = new OpenAI({ 128 baseURL: OPENROUTER_DIRECT_URL, 129 apiKey: openRouterApiKey, 130 timeout: 120_000, 131 }); 132 } else { 133 const apifyToken = process.env.APIFY_TOKEN; 134 if (!apifyToken) { 135 throw new Error('APIFY_TOKEN environment variable is required for OpenRouter access'); 136 } 137 openai = new OpenAI({ 138 baseURL: OPENROUTER_BASE_URL, 139 apiKey: 'apify-openrouter', 140 timeout: 120_000, 141 defaultHeaders: { 142 Authorization: `Bearer ${apifyToken}`, 143 }, 144 }); 145 } 146 147 const systemPrompt = buildSystemPrompt(style); 148 149 return { 150 /** 151 * Normalize an array of items using the LLM. 152 * Automatically scales concurrency based on request size. 153 * @param {Array} items - Items with preProcessed values 154 * @returns {Promise<Array>} Items with normalized values, confidence, and reasoning 155 */ 156 async normalize(items) { 157 // Split items into batches 158 const batches = []; 159 for (let i = 0; i < items.length; i += BATCH_SIZE) { 160 batches.push({ 161 items: items.slice(i, i + BATCH_SIZE), 162 startIndex: i, 163 }); 164 } 165 166 const totalBatches = batches.length; 167 168 // Scale concurrency based on total request size 169 const concurrency = items.length >= LARGE_REQUEST_THRESHOLD 170 ? LARGE_REQUEST_CONCURRENCY 171 : DEFAULT_CONCURRENCY; 172 173 log.info(`Processing ${items.length} names in ${totalBatches} batches (concurrency: ${concurrency})`); 174 175 // Process batches in parallel with concurrency limit 176 const results = new Array(items.length); 177 for (let i = 0; i < batches.length; i += concurrency) { 178 const chunk = batches.slice(i, i + concurrency); 179 const chunkStart = i + 1; 180 const chunkEnd = Math.min(i + concurrency, totalBatches); 181 182 log.info(`Processing batches ${chunkStart}-${chunkEnd}/${totalBatches}`); 183 184 const chunkResults = await Promise.allSettled( 185 chunk.map((batch) => normalizeBatch(openai, model, systemPrompt, batch.items)), 186 ); 187 188 // Place results in correct positions 189 chunk.forEach((batch, idx) => { 190 const settled = chunkResults[idx]; 191 if (settled.status === 'fulfilled') { 192 settled.value.forEach((result, resultIdx) => { 193 results[batch.startIndex + resultIdx] = result; 194 }); 195 } else { 196 log.error(`Batch ${i + idx + 1} failed: ${settled.reason?.message}`); 197 batch.items.forEach((item, resultIdx) => { 198 results[batch.startIndex + resultIdx] = { 199 output: item.preProcessed || item.original, 200 confidence: 0, 201 error: settled.reason?.message || 'Batch failed', 202 }; 203 }); 204 } 205 }); 206 } 207 208 return results; 209 }, 210 }; 211} 212 213/** 214 * Sleep for a given number of milliseconds. 215 * @param {number} ms - Milliseconds to sleep 216 * @returns {Promise<void>} 217 */ 218function sleep(ms) { 219 return new Promise((resolve) => { 220 setTimeout(resolve, ms); 221 }); 222} 223 224/** 225 * Check if an error is retryable (network issues, rate limits, server errors). 226 * @param {Error} error - The error to check 227 * @returns {boolean} True if the error is retryable 228 */ 229function isRetryableError(error) { 230 // Network errors 231 if (error.code === 'ECONNRESET' || error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') { 232 return true; 233 } 234 // Rate limiting (429) or server errors (5xx) 235 if (error.status === 429 || error.status >= 500) { 236 return true; 237 } 238 // OpenAI/OpenRouter specific errors 239 if (error.message?.includes('timeout') || error.message?.includes('network')) { 240 return true; 241 } 242 return false; 243} 244 245/** 246 * Normalize a batch of items with a single LLM call. 247 * Includes retry logic with exponential backoff. 248 * @param {OpenAI} openai - OpenAI client instance 249 * @param {string} model - Model identifier 250 * @param {string} systemPrompt - Type-specific system prompt 251 * @param {Array} items - Batch of items to normalize 252 * @returns {Promise<Array>} Normalized items 253 */ 254async function normalizeBatch(openai, model, systemPrompt, items) { 255 const prompt = buildPrompt(items); 256 let lastError; 257 258 for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) { 259 try { 260 const completion = await openai.chat.completions.create({ 261 model, 262 messages: [ 263 { role: 'system', content: systemPrompt }, 264 { role: 'user', content: prompt }, 265 ], 266 temperature: 0.3, // Low temperature for consistent results 267 max_tokens: MAX_TOKENS, // Ensure complete JSON responses 268 timeout: 60000, // 60 second timeout 269 }); 270 271 const responseContent = completion.choices[0]?.message?.content; 272 if (!responseContent) { 273 throw new Error('Empty response from LLM'); 274 } 275 276 return parseResponse(responseContent, items); 277 } catch (error) { 278 lastError = error; 279 280 if (attempt < MAX_RETRIES && isRetryableError(error)) { 281 const delayMs = INITIAL_RETRY_DELAY_MS * (2 ** (attempt - 1)); // Exponential backoff 282 log.warning(`LLM request failed (attempt ${attempt}/${MAX_RETRIES}), retrying in ${delayMs}ms...`, { 283 error: error.message, 284 }); 285 await sleep(delayMs); 286 } else if (attempt < MAX_RETRIES) { 287 // Non-retryable error, don't retry 288 log.error('LLM request failed with non-retryable error', { error: error.message }); 289 break; 290 } 291 } 292 } 293 294 // All retries exhausted or non-retryable error - return pass-through results 295 // instead of crashing the entire run. Failed items get low confidence so users can identify them. 296 const errorMessage = lastError?.message || 'Unknown error'; 297 log.error(`LLM request failed after all retries, returning pass-through for ${items.length} items`, { error: errorMessage }); 298 return items.map((item) => ({ 299 output: item.preProcessed || item.original, 300 confidence: 0, 301 error: errorMessage, 302 })); 303} 304 305/** 306 * Build the user prompt for a batch of items. 307 * @param {Array} items - Items to include in prompt 308 * @returns {string} Formatted prompt 309 */ 310function buildPrompt(items) { 311 const itemList = items.map((item, i) => `${i}. "${item.preProcessed}"`).join('\n'); 312 313 return `Normalize the following ${items.length} person names:\n\n${itemList}`; 314} 315 316/** 317 * Attempt to repair truncated JSON arrays by finding the last complete object. 318 * @param {string} jsonStr - Potentially truncated JSON string 319 * @returns {string} Repaired JSON string (or original if repair not needed/possible) 320 */ 321function repairTruncatedJson(jsonStr) { 322 // Quick check: if it parses, no repair needed 323 try { 324 JSON.parse(jsonStr); 325 return jsonStr; 326 } catch { 327 // Continue with repair attempt 328 } 329 330 // Only attempt repair on arrays 331 if (!jsonStr.trimStart().startsWith('[')) { 332 return jsonStr; 333 } 334 335 // Find the last complete object by looking for the last "}," or "}" before truncation 336 let lastValidEnd = -1; 337 338 // Look for last complete object ending with }, 339 const lastCommaObj = jsonStr.lastIndexOf('},'); 340 if (lastCommaObj > 0) { 341 lastValidEnd = lastCommaObj + 1; // Include the } 342 } 343 344 // Also check for a final object ending with just } 345 const lastBrace = jsonStr.lastIndexOf('}'); 346 if (lastBrace > lastValidEnd) { 347 const afterBrace = jsonStr.slice(lastBrace + 1).trim(); 348 if (afterBrace === '' || afterBrace === ']' || afterBrace.startsWith(',') || afterBrace.startsWith(']')) { 349 lastValidEnd = lastBrace; 350 } 351 } 352 353 if (lastValidEnd > 0) { 354 const repaired = `${jsonStr.slice(0, lastValidEnd + 1)}]`; 355 try { 356 JSON.parse(repaired); 357 log.debug('Repaired truncated JSON response', { 358 originalLength: jsonStr.length, 359 repairedLength: repaired.length, 360 }); 361 return repaired; 362 } catch { 363 // Repair failed, return original 364 } 365 } 366 367 return jsonStr; 368} 369 370/** 371 * Parse the LLM response and map results back to original items. 372 * @param {string} content - Raw LLM response content 373 * @param {Array} originalItems - Original items for fallback 374 * @returns {Array} Items with normalized values 375 */ 376function parseResponse(content, originalItems) { 377 try { 378 // Handle potential markdown code blocks 379 let jsonStr = content.trim(); 380 if (jsonStr.includes('```')) { 381 jsonStr = jsonStr.replace(/```json?\n?/g, '').replace(/```/g, '').trim(); 382 } 383 384 // Strip JavaScript-style comments that LLMs sometimes add 385 jsonStr = jsonStr.replace(/\/\/[^\n]*/g, ''); // Remove // comments 386 jsonStr = jsonStr.replace(/\/\*[\s\S]*?\*\//g, ''); // Remove /* */ comments 387 388 // Fix malformed tuple format: {"0", "name", 0.95} -> {"index": 0, "normalized": "name", "confidence": 0.95} 389 jsonStr = jsonStr.replace( 390 /\{"(\d+)",\s*"([^"]*)",\s*([\d.]+)\}/g, 391 '{"index": $1, "normalized": "$2", "confidence": $3}', 392 ); 393 394 // Handle truncated JSON 395 jsonStr = repairTruncatedJson(jsonStr); 396 397 const parsed = JSON.parse(jsonStr); 398 399 if (!Array.isArray(parsed)) { 400 throw new Error('Response is not an array'); 401 } 402 403 // Map response back to original items 404 return originalItems.map((item, i) => { 405 const result = parsed.find((r) => r.index === i); 406 if (result) { 407 return { 408 ...item, 409 normalized: postProcessName(result.normalized || item.preProcessed), 410 confidence: clampConfidence(result.confidence), 411 }; 412 } 413 // Fallback if item not in response 414 return { 415 ...item, 416 normalized: postProcessName(item.preProcessed), 417 confidence: 0.5, 418 }; 419 }); 420 } catch (error) { 421 log.warning('Failed to parse LLM response', { error: error.message, content: content.slice(0, 200) }); 422 423 // Return pre-processed values with low confidence 424 return originalItems.map((item) => ({ 425 ...item, 426 normalized: postProcessName(item.preProcessed), 427 confidence: 0.4, 428 })); 429 } 430} 431 432/** 433 * Clamp confidence value to valid range [0, 1]. 434 * @param {number} value - Raw confidence value 435 * @returns {number} Clamped confidence 436 */ 437function clampConfidence(value) { 438 if (typeof value !== 'number' || Number.isNaN(value)) { 439 return 0.5; 440 } 441 return Math.max(0, Math.min(1, value)); 442} 443 444/** 445 * Post-process normalized name to fix common issues. 446 * @param {string} text - Normalized text from LLM 447 * @returns {string} Text with fixes applied 448 */ 449function postProcessName(text) { 450 if (!text || typeof text !== 'string') { 451 return text; 452 } 453 454 let result = text.trim(); 455 456 // Fix apostrophe-S capitalization: "O'Brien'S" -> "O'Brien's" 457 // But preserve O'Brien, D'Angelo style 458 result = result.replace(/(\w)'S\b/g, "$1's"); 459 460 // Fix common LLM mistakes with Mc/Mac names 461 result = result.replace(/\bMc([a-z])/g, (_, letter) => `Mc${letter.toUpperCase()}`); 462 463 // Ensure particles are lowercase (except at start) 464 const particles = ['van', 'von', 'de', 'da', 'du', 'del', 'della', 'di', 'le', 'la', 'el', 'al']; 465 for (const particle of particles) { 466 // Match particle not at start of string 467 const pattern = new RegExp(`(?<=\\s)(${particle})(?=\\s)`, 'gi'); 468 result = result.replace(pattern, particle.toLowerCase()); 469 } 470 471 // Clean up multiple spaces 472 result = result.replace(/\s+/g, ' ').trim(); 473 474 return result; 475}

1/** 2 * Superclean Person Names 3 * 4 * Cleans messy person names for cold email personalization, 5 * CRM systems, and lead lists. 6 */ 7 8import http from 'node:http'; 9import { Actor, log } from 'apify'; 10 11import { createNormalizer } from './normalizer.js'; 12import { preprocess } from './preprocessor.js'; 13 14const PPE_EVENT = 'person-name-clean'; 15 16/** 17 * Normalize flexible input formats for Clay/API compatibility. 18 * Accepts: ["string"] or [{input: "string"}] 19 * Returns: ["string"] 20 */ 21function normalizeItems(items) { 22 return items.map((item) => { 23 if (typeof item === 'string') { 24 return item; 25 } 26 if (item && typeof item === 'object' && 'input' in item) { 27 return String(item.input ?? ''); 28 } 29 return String(item ?? ''); 30 }); 31} 32 33await Actor.init(); 34 35if (Actor.config.get('metaOrigin') === 'STANDBY') { 36 startStandbyServer(); 37} else { 38 await runBatchMode(); 39 await Actor.exit(); 40} 41 42// --------------------------------------------------------------------------- 43// Standby mode — HTTP server for instant single-name cleaning 44// --------------------------------------------------------------------------- 45 46function startStandbyServer() { 47 const port = Actor.config.get('containerPort'); 48 49 const server = http.createServer(async (req, res) => { 50 // Readiness probe 51 if (req.headers['x-apify-container-server-readiness-probe']) { 52 res.writeHead(200, { 'Content-Type': 'application/json' }); 53 res.end(JSON.stringify({ status: 'ready' })); 54 return; 55 } 56 57 // GET only 58 if (req.method !== 'GET') { 59 res.writeHead(405, { 'Content-Type': 'application/json' }); 60 res.end(JSON.stringify({ error: 'Method not allowed. Use GET.' })); 61 return; 62 } 63 64 // No input param → serve landing page 65 const reqUrl = new URL(req.url, `http://${req.headers.host}`); 66 if (!reqUrl.searchParams.get('input')) { 67 res.writeHead(200, { 'Content-Type': 'text/html' }); 68 res.end(getLandingPageHtml()); 69 return; 70 } 71 72 try { 73 const result = await handleStandbyRequest(reqUrl, req); 74 await Actor.pushData(result); 75 76 // Charge PPE 77 try { 78 await Actor.charge({ eventName: PPE_EVENT, count: 1 }); 79 } catch (chargeErr) { 80 console.warn(`PPE charge failed: ${chargeErr.message}`); 81 } 82 83 res.writeHead(200, { 'Content-Type': 'application/json' }); 84 res.end(JSON.stringify(result)); 85 } catch (err) { 86 const statusCode = err.statusCode || 500; 87 res.writeHead(statusCode, { 'Content-Type': 'application/json' }); 88 res.end(JSON.stringify({ error: err.message })); 89 } 90 }); 91 92 server.listen(port, () => { 93 console.log(`Superclean Person Names Standby server listening on port ${port}`); 94 }); 95} 96 97async function handleStandbyRequest(reqUrl, req) { 98 const input = reqUrl.searchParams.get('input'); 99 100 if (!input) { 101 const err = new Error("Provide an 'input' query parameter with the person name to clean."); 102 err.statusCode = 400; 103 throw err; 104 } 105 106 const style = reqUrl.searchParams.get('style') || 'casual'; 107 const model = reqUrl.searchParams.get('model') || 'openrouter/auto'; 108 const openRouterApiKey = req.headers['x-openrouter-key'] || null; 109 110 const validStyles = ['first', 'casual', 'formal']; 111 if (!validStyles.includes(style)) { 112 const err = new Error(`Invalid style "${style}". Must be one of: ${validStyles.join(', ')}`); 113 err.statusCode = 400; 114 throw err; 115 } 116 117 const trimmed = input.trim(); 118 if (!trimmed) { 119 return { id: 1, input, output: '', confidence: 0 }; 120 } 121 122 // Preprocess 123 const preprocessResult = preprocess(trimmed); 124 125 // Non-English → return extracted English or original 126 if (preprocessResult.isNonEnglish) { 127 return { 128 id: 1, 129 input: trimmed, 130 output: preprocessResult.extractedEnglish || trimmed, 131 confidence: 0, 132 }; 133 } 134 135 // LLM normalization 136 const item = { 137 id: 1, 138 input: trimmed, 139 preProcessed: preprocessResult.value, 140 isNonEnglish: false, 141 extractedEnglish: preprocessResult.extractedEnglish, 142 detectedComponents: preprocessResult.detectedComponents, 143 }; 144 145 const normalizer = createNormalizer(model, style, openRouterApiKey); 146 const normalizedItems = await normalizer.normalize([item]); 147 148 if (normalizedItems.length === 0) { 149 return { id: 1, input: trimmed, output: trimmed, confidence: 0 }; 150 } 151 152 return { 153 id: 1, 154 input: trimmed, 155 output: normalizedItems[0].normalized, 156 confidence: Math.round(normalizedItems[0].confidence * 100) / 100, 157 }; 158} 159 160// --------------------------------------------------------------------------- 161// Batch mode — existing pipeline for standard Actor runs 162// --------------------------------------------------------------------------- 163 164async function runBatchMode() { 165 // Get input 166 const input = await Actor.getInput(); 167 let { items: rawItems, item } = input || {}; 168 169 // Support single "item" string field for API/integration callers 170 if (typeof item === 'string' && item.trim()) { 171 if (!Array.isArray(rawItems)) rawItems = []; 172 rawItems = [item.trim(), ...rawItems]; 173 } 174 175 // Coerce bare string to array 176 if (typeof rawItems === 'string') rawItems = [rawItems]; 177 178 // Validate input 179 if (!rawItems || !Array.isArray(rawItems) || rawItems.length === 0) { 180 await Actor.fail('Input required: provide "items" (array) or "item" (single string). Example: {"items": ["John Smith"]}'); 181 return; 182 } 183 184 // Extract configuration with defaults 185 const style = input.style ?? 'casual'; 186 const model = input.model ?? 'openrouter/auto'; 187 const openRouterApiKey = input.openRouterApiKey ?? null; 188 189 // Normalize input format (supports both ["string"] and [{input: "string"}]) 190 const items = normalizeItems(rawItems); 191 192 log.info(`Starting normalization of ${items.length} person names`, { 193 style, 194 model, 195 }); 196 197 // Step 1: Run pre-processing on normalized items 198 const processedItems = items.map((item, index) => { 199 // Handle string input 200 const value = typeof item === 'string' ? item : String(item || ''); 201 const id = index + 1; 202 203 // Validate value 204 if (!value.trim()) { 205 log.warning(`Skipping invalid item at index ${index}`, { item }); 206 return null; 207 } 208 209 // Run pre-processing 210 const preprocessResult = preprocess(value); 211 212 return { 213 id, 214 input: value, 215 preProcessed: preprocessResult.value, 216 isNonEnglish: preprocessResult.isNonEnglish, 217 extractedEnglish: preprocessResult.extractedEnglish, 218 detectedComponents: preprocessResult.detectedComponents, 219 }; 220 }); 221 222 // Filter out invalid items 223 const validItems = processedItems.filter((item) => item !== null); 224 225 if (validItems.length === 0) { 226 throw new Error('No valid items to process after input validation'); 227 } 228 229 // Separate English and non-English items 230 const englishItems = validItems.filter((item) => !item.isNonEnglish); 231 const nonEnglishItems = validItems.filter((item) => item.isNonEnglish); 232 233 if (nonEnglishItems.length > 0) { 234 log.info(`Flagging ${nonEnglishItems.length} non-English names for review`); 235 } 236 237 log.info(`Pre-processed ${validItems.length} items (${englishItems.length} English, ${nonEnglishItems.length} non-English)`); 238 239 // Step 2: LLM normalization for English items only 240 let normalizedItems = []; 241 if (englishItems.length > 0) { 242 const normalizer = createNormalizer(model, style, openRouterApiKey); 243 normalizedItems = await normalizer.normalize(englishItems); 244 } 245 246 // Step 3: Build output - combine LLM results with non-English items 247 const englishResults = normalizedItems.map((item) => ({ 248 id: item.id, 249 input: item.input, 250 output: item.normalized, 251 confidence: Math.round(item.confidence * 100) / 100, 252 })); 253 254 const nonEnglishResults = nonEnglishItems.map((item) => ({ 255 id: item.id, 256 input: item.input, 257 output: item.extractedEnglish || item.input, 258 confidence: 0, 259 })); 260 261 const results = [...englishResults, ...nonEnglishResults]; 262 263 // Step 4: Charge PPE per item, then push to dataset 264 let chargedCount = 0; 265 let chargeLimitReached = false; 266 for (const result of results) { 267 if (!chargeLimitReached) { 268 try { 269 const chargeResult = await Actor.charge({ eventName: PPE_EVENT, count: 1 }); 270 chargedCount++; 271 if (chargeResult?.eventChargeLimitReached) { 272 chargeLimitReached = true; 273 console.log(`User spending limit reached after charging ${chargedCount}/${results.length} items`); 274 } 275 } catch (chargeErr) { 276 console.warn(`PPE charge failed: ${chargeErr.message}`); 277 } 278 } 279 } 280 281 await Actor.pushData(results); 282 283 // Log summary 284 const avgConfidence = results.reduce((sum, r) => sum + r.confidence, 0) / results.length; 285 286 log.info(`Normalization complete`, { 287 totalItems: results.length, 288 charged: chargedCount, 289 averageConfidence: Math.round(avgConfidence * 100) / 100, 290 }); 291} 292 293// --------------------------------------------------------------------------- 294// Landing page HTML for Standby mode 295// --------------------------------------------------------------------------- 296 297function getLandingPageHtml() { 298 return `<!DOCTYPE html> 299<html lang="en"> 300<head> 301<meta charset="utf-8"> 302<meta name="viewport" content="width=device-width, initial-scale=1"> 303<title>Superclean Person Names — Superlative</title> 304<link rel="preconnect" href="https://fonts.googleapis.com"> 305<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> 306<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet"> 307<style> 308:root{--color-bg:#0a0e14;--color-surface:#12171f;--color-border:#1e2632;--color-text:#e8eaed;--color-text-muted:#8b95a5;--color-accent:#4ade80;--color-accent-dim:rgba(74,222,128,0.15);--font-display:'Space Mono',monospace;--font-body:'DM Sans',sans-serif} 309*{margin:0;padding:0;box-sizing:border-box} 310body{font-family:var(--font-body);background:var(--color-bg);color:var(--color-text);line-height:1.6;min-height:100vh;overflow-x:hidden} 311a{color:var(--color-accent);text-decoration:none;transition:color .2s ease}a:hover{color:#6ee7a0} 312.grid-bg{position:fixed;top:0;left:0;width:100%;height:100%;background-image:linear-gradient(var(--color-border) 1px,transparent 1px),linear-gradient(90deg,var(--color-border) 1px,transparent 1px);background-size:60px 60px;opacity:.3;pointer-events:none;z-index:0} 313.accent-line{position:fixed;top:0;left:0;width:100%;height:2px;background:linear-gradient(90deg,transparent 0%,var(--color-accent) 50%,transparent 100%);animation:shimmer 3s ease-in-out infinite;z-index:10} 314@keyframes shimmer{0%,100%{transform:translateX(-100%)}50%{transform:translateX(100%)}} 315@keyframes fadeUp{from{opacity:0;transform:translateY(20px)}to{opacity:1;transform:translateY(0)}} 316.container{position:relative;z-index:1;max-width:900px;margin:0 auto;padding:0 24px} 317header{padding:32px 0}.logo{font-family:var(--font-display);font-size:14px;font-weight:700;letter-spacing:.1em;text-transform:uppercase;color:var(--color-text);display:flex;align-items:center;gap:10px;text-decoration:none}.logo:hover{color:var(--color-text)}.logo-mark{width:28px;height:28px;background:var(--color-accent);display:flex;align-items:center;justify-content:center}.logo-mark svg{width:16px;height:16px} 318.hero{padding:80px 0 60px;animation:fadeUp .8s ease-out}.hero-label{font-family:var(--font-display);font-size:12px;font-weight:400;letter-spacing:.15em;text-transform:uppercase;color:var(--color-accent);margin-bottom:24px;display:flex;align-items:center;gap:12px}.hero-label::before{content:'';width:24px;height:1px;background:var(--color-accent)} 319h1{font-family:var(--font-display);font-size:clamp(28px,5vw,44px);font-weight:700;line-height:1.15;margin-bottom:20px;letter-spacing:-.02em}h1 .highlight{color:var(--color-accent)} 320.hero-desc{font-size:18px;color:var(--color-text-muted);max-width:540px;margin-bottom:28px;line-height:1.7}.hero-link{font-family:var(--font-display);font-size:13px;letter-spacing:.05em;color:var(--color-accent);display:inline-flex;align-items:center;gap:6px} 321.section{padding:60px 0;border-top:1px solid var(--color-border);animation:fadeUp .8s ease-out .2s backwards}.section-label{font-family:var(--font-display);font-size:11px;font-weight:400;letter-spacing:.2em;text-transform:uppercase;color:var(--color-text-muted);margin-bottom:24px} 322h2{font-family:var(--font-display);font-size:20px;font-weight:700;margin-bottom:16px;letter-spacing:-.01em}p,li{font-size:15px;color:var(--color-text-muted);line-height:1.7}li{margin-bottom:6px}ul{margin:.5rem 0 1rem 1.25rem}strong{color:var(--color-text);font-weight:600} 323pre{background:var(--color-surface);color:var(--color-text);padding:16px 20px;overflow-x:auto;margin:12px 0 16px;font-family:var(--font-display);font-size:13px;line-height:1.6;border:1px solid var(--color-border)}code{font-family:var(--font-display);font-size:13px}p code,li code,td code{background:var(--color-accent-dim);color:var(--color-accent);padding:2px 6px} 324table{width:100%;border-collapse:collapse;margin:12px 0 16px;font-size:14px}th,td{border:1px solid var(--color-border);padding:10px 14px;text-align:left}th{background:var(--color-surface);color:var(--color-text-muted);font-family:var(--font-display);font-size:12px;font-weight:400;letter-spacing:.05em;text-transform:uppercase}td{color:var(--color-text-muted)} 325.badge{display:inline-block;background:var(--color-accent-dim);color:var(--color-accent);padding:3px 8px;font-family:var(--font-display);font-size:11px;font-weight:400;letter-spacing:.05em} 326.product-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:16px;margin-top:24px}.product-card{background:var(--color-surface);border:1px solid var(--color-border);padding:24px;transition:all .3s ease;text-decoration:none;color:inherit;display:block}.product-card:hover{border-color:var(--color-accent);transform:translateY(-2px)}.product-name{font-family:var(--font-display);font-size:14px;font-weight:700;margin-bottom:8px;color:var(--color-text);display:flex;align-items:center;gap:8px}.product-name .status{font-size:9px;font-weight:400;padding:3px 6px;background:var(--color-accent-dim);color:var(--color-accent);letter-spacing:.1em}.product-desc{font-size:14px;color:var(--color-text-muted);line-height:1.5} 327footer{padding:48px 0;border-top:1px solid var(--color-border)}.footer-content{display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:24px}.footer-text{font-size:13px;color:var(--color-text-muted)}.footer-links{display:flex;gap:24px}.footer-links a{font-family:var(--font-display);font-size:12px;color:var(--color-text-muted);letter-spacing:.05em}.footer-links a:hover{color:var(--color-accent)} 328@media(max-width:600px){.hero{padding:60px 0 40px}.section{padding:40px 0}.footer-content{flex-direction:column;align-items:flex-start}pre{font-size:12px;padding:12px 14px}} 329</style> 330</head> 331<body> 332<div class="grid-bg"></div> 333<div class="accent-line"></div> 334<div class="container"> 335 <header><a href="https://apify.com/superlativetech?fpr=8e9l1" class="logo"><div class="logo-mark"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5"><polyline points="4 17 10 11 4 5"></polyline><line x1="12" y1="19" x2="20" y2="19"></line></svg></div>Superlative</a></header> 336 337 <section class="hero"> 338 <div class="hero-label">Superclean</div> 339 <h1>Person <span class="highlight">Names</span></h1> 340 <p class="hero-desc">Instant person name cleaning. AI-powered normalization for cold email personalization and CRM. Sub-second responses via Standby API.</p> 341 <a href="https://apify.com/superlativetech/superclean-person-names?fpr=8e9l1" class="hero-link">View on Apify Store →</a> 342 </section> 343 344 <section class="section"> 345 <div class="section-label">Features</div> 346 <h2>What this does</h2> 347 <ul> 348 <li><strong>AI-powered cleaning</strong> — LLM normalizes person names with context awareness</li> 349 <li><strong>Three styles</strong> — First name only, Casual, Formal</li> 350 <li><strong>Handles titles</strong> — Strips Dr., Mr., Mrs., PhD, MD, etc.</li> 351 <li><strong>BYOK support</strong> — Use your own OpenRouter API key via header</li> 352 <li><strong>Batch mode</strong> — Process hundreds of names via the standard Actor run</li> 353 </ul> 354 </section> 355 356 <section class="section"> 357 <div class="section-label">Getting Started</div> 358 <h2>Quick start</h2> 359 <p>Replace <code>YOUR_TOKEN</code> with your Apify API token.</p> 360 <p style="margin-top:16px"><strong>Casual style (default):</strong></p> 361 <pre>curl "https://superlativetech--superclean-person-names.apify.actor?token=YOUR_TOKEN&input=DR.+JOHN+SMITH+III"</pre> 362 <p><strong>First name only:</strong></p> 363 <pre>curl "https://superlativetech--superclean-person-names.apify.actor?token=YOUR_TOKEN&input=DR.+JOHN+SMITH+III&style=first"</pre> 364 <p><strong>With your own OpenRouter key:</strong></p> 365 <pre>curl -H "X-OpenRouter-Key: sk-or-..." "https://superlativetech--superclean-person-names.apify.actor?token=YOUR_TOKEN&input=mcdonald,+sarah+jane"</pre> 366 </section> 367 368 <section class="section"> 369 <div class="section-label">Reference</div> 370 <h2>Query parameters</h2> 371 <table> 372 <tr><th>Parameter</th><th>Required</th><th>Description</th></tr> 373 <tr><td><code>input</code></td><td>Yes</td><td>Person name to clean</td></tr> 374 <tr><td><code>style</code></td><td>No</td><td>Output style: <code>first</code>, <code>casual</code> (default), or <code>formal</code></td></tr> 375 <tr><td><code>model</code></td><td>No</td><td>LLM model (default: <code>openrouter/auto</code>)</td></tr> 376 <tr><td><code>token</code></td><td>Yes</td><td>Your Apify API token</td></tr> 377 </table> 378 <h2 style="margin-top:24px">Headers</h2> 379 <table> 380 <tr><th>Header</th><th>Required</th><th>Description</th></tr> 381 <tr><td><code>X-OpenRouter-Key</code></td><td>No</td><td>Your OpenRouter API key for BYOK</td></tr> 382 </table> 383 </section> 384 385 <section class="section"> 386 <div class="section-label">Response</div> 387 <h2>Response format</h2> 388 <pre>{ 389 "id": 1, 390 "input": "DR. JOHN SMITH III", 391 "output": "John Smith", 392 "confidence": 0.95 393}</pre> 394 </section> 395 396 <section class="section"> 397 <div class="section-label">Cost</div> 398 <h2>Pricing</h2> 399 <p>Pay-per-event pricing on the Apify platform:</p> 400 <table> 401 <tr><th>Tier</th><th>Names</th><th>Per 1,000</th></tr> 402 <tr><td>Base</td><td>Any</td><td>$1.00</td></tr> 403 <tr><td><span class="badge">Bronze</span></td><td>100+</td><td>$0.90</td></tr> 404 <tr><td><span class="badge">Silver</span></td><td>1,000+</td><td>$0.80</td></tr> 405 <tr><td><span class="badge">Gold</span></td><td>10,000+</td><td>$0.70</td></tr> 406 </table> 407 </section> 408 409 <section class="section"> 410 <div class="section-label">Auth</div> 411 <h2>Authentication</h2> 412 <p>Authenticate using either method:</p> 413 <ul> 414 <li>Query parameter: <code>?token=YOUR_APIFY_TOKEN</code></li> 415 <li>Header: <code>Authorization: Bearer YOUR_APIFY_TOKEN</code></li> 416 </ul> 417 <p style="margin-top:8px">Get your token from <a href="https://console.apify.com/settings/integrations">Apify Console → Settings → Integrations</a>.</p> 418 </section> 419 420 <section class="section"> 421 <div class="section-label">Superlative</div> 422 <h2>More from Superlative</h2> 423 <div class="product-grid"> 424 <a href="https://apify.com/superlativetech/superclean-company-names?fpr=8e9l1" class="product-card"><div class="product-name">Company Names <span class="status">Live</span></div><p class="product-desc">Normalize company names for CRM and cold email outreach.</p></a> 425 <a href="https://apify.com/superlativetech/superclean-job-titles?fpr=8e9l1" class="product-card"><div class="product-name">Job Titles <span class="status">Live</span></div><p class="product-desc">Standardize job titles for outreach sequences.</p></a> 426 <a href="https://apify.com/superlativetech/superclean-product-names?fpr=8e9l1" class="product-card"><div class="product-name">Product Names <span class="status">Live</span></div><p class="product-desc">Normalize product and brand names from exports.</p></a> 427 <a href="https://apify.com/superlativetech/superclean-places?fpr=8e9l1" class="product-card"><div class="product-name">Places <span class="status">Live</span></div><p class="product-desc">Parse and standardize location strings.</p></a> 428 <a href="https://apify.com/superlativetech/superclean-urls?fpr=8e9l1" class="product-card"><div class="product-name">URLs <span class="status">Live</span></div><p class="product-desc">Clean and normalize URLs from lead data.</p></a> 429 <a href="https://apify.com/superlativetech/superclean-phone-numbers?fpr=8e9l1" class="product-card"><div class="product-name">Phone Numbers <span class="status">Live</span></div><p class="product-desc">Format and validate phone numbers.</p></a> 430 <a href="https://apify.com/superlativetech/dns-lookup?fpr=8e9l1" class="product-card"><div class="product-name">Supernet DNS Lookup <span class="status">Live</span></div><p class="product-desc">Look up DNS records for any domain.</p></a> 431 <a href="https://apify.com/superlativetech/http-api?fpr=8e9l1" class="product-card"><div class="product-name">HTTP API <span class="status">Live</span></div><p class="product-desc">General-purpose HTTP request utility.</p></a> 432 </div> 433 </section> 434 435</div> 436</body> 437</html>`; 438}

{ "actorSpecification": 1, "fields": { "type": "object", "properties": { "id": { "type": "integer", "description": "Row number (1-based)" }, "input": { "type": "string", "description": "The original input value" }, "output": { "type": "string", "description": "The cleaned output value" }, "confidence": { "type": "number", "description": "Confidence score from 0 to 1" } } }, "views": { "overview": { "title": "All Results", "transformation": { "fields": ["id", "input", "output", "confidence"] }, "display": { "component": "table", "properties": { "id": { "label": "ID", "format": "number" }, "input": { "label": "Input", "format": "text" }, "output": { "label": "Output", "format": "text" }, "confidence": { "label": "Confidence", "format": "number" } } } } } }

{ "actorOutputSchemaVersion": 1, "title": "Superclean Person Names Output", "description": "Normalized results with original values, cleaned values, and confidence scores.", "type": "object", "properties": { "allResults": { "type": "string", "title": "All Results", "description": "All normalized names with before/after values and confidence scores", "template": "{{links.apiDefaultDatasetUrl}}/items" } } }

{ "openapi": "3.0.3", "info": { "title": "Superclean Person Names — Standby API", "description": "Instant AI-powered person name normalization via HTTP GET. Clean messy names for cold email personalization, CRM, and lead lists. Supports first, casual, and formal styles.", "version": "0.2.0" }, "paths": { "/": { "get": { "summary": "Clean a person name", "description": "Normalize a single person name using AI. Handles ALL CAPS, titles, credentials, special capitalization (McDonald, O'Brien). Supports BYOK via X-OpenRouter-Key header.", "operationId": "cleanPersonName", "parameters": [ { "name": "input", "in": "query", "description": "Person name to clean (e.g. `DR. JOHN SMITH III`).", "required": true, "schema": { "type": "string", "example": "DR. JOHN SMITH III" } }, { "name": "style", "in": "query", "description": "Output style. `first` returns first name only, `casual` returns first + last, `formal` includes titles.", "required": false, "schema": { "type": "string", "enum": ["first", "casual", "formal"], "default": "casual" } }, { "name": "model", "in": "query", "description": "LLM model to use.", "required": false, "schema": { "type": "string", "default": "openrouter/auto" } } ], "responses": { "200": { "description": "Cleaned person name with confidence score.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CleanedName" }, "examples": { "casual": { "summary": "Casual style", "value": { "id": 1, "input": "DR. JOHN SMITH III", "output": "John Smith", "confidence": 0.95 } }, "first": { "summary": "First name only", "value": { "id": 1, "input": "DR. JOHN SMITH III", "output": "John", "confidence": 0.95 } } } } } }, "400": { "description": "Invalid request — missing input or invalid style.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Provide an 'input' query parameter with the person name to clean." } } } }, "405": { "description": "Method not allowed — only GET is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Method not allowed. Use GET." } } } } } } } }, "components": { "schemas": { "CleanedName": { "type": "object", "required": ["id", "input", "output", "confidence"], "properties": { "id": { "type": "integer", "description": "Row number (always 1 for single-item Standby requests)." }, "input": { "type": "string", "description": "Original person name before cleaning." }, "output": { "type": "string", "description": "Cleaned person name." }, "confidence": { "type": "number", "description": "Confidence score from 0 to 1." } } }, "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "description": "Human-readable error message." } } } } } }

{ "title": "Superclean Person Names", "description": "Paste your person names below and click Start. Results will appear in the Output tab.", "type": "object", "schemaVersion": 1, "properties": { "items": { "title": "Person names", "type": "array", "description": "Enter person names to clean, one per line.", "editor": "stringList", "prefill": ["dr. mary jane o'brien, phd"], "minItems": 1 }, "style": { "title": "Output style", "type": "string", "description": "Choose how names should be formatted in the output.", "enum": ["first", "casual", "formal"], "enumTitles": [ "First name only - for cold email personalization (John)", "Casual - full name without titles/credentials (John Smith Jr.)", "Formal - complete with titles and credentials (Dr. John Smith Jr., Ph.D.)" ], "default": "casual", "editor": "select" }, "model": { "sectionCaption": "Advanced", "title": "AI model", "type": "string", "description": "AI model for normalization. Default auto-routes for best price/performance. Set a specific model like google/gemini-2.0-flash-001 for higher-quality confidence scores. Browse models at openrouter.ai/models.", "default": "openrouter/auto", "editor": "textfield" }, "openRouterApiKey": { "title": "OpenRouter API key (bring your own)", "type": "string", "description": "Optional. Provide your own OpenRouter API key to use the direct OpenRouter API instead of the built-in Apify integration. Get your key at openrouter.ai.", "editor": "textfield", "isSecret": true }, "item": { "title": "Item (single)", "type": "string", "description": "Single person name to clean — shorthand for API/integration callers. If both 'item' and 'items' are provided, 'item' is prepended to the list.", "editor": "textfield", "sectionCaption": "API shorthand", "sectionDescription": "For API and integration callers (Clay, Make, n8n) who want to pass a single item without wrapping it in an array." } }, "required": [] }

{ "actorSpecification": 1, "name": "superclean-person-names", "title": "Superclean Person Names", "description": "Normalize messy person names. Fixes ALL CAPS, titles, credentials, special cases (McDonald, O'Brien). Input: string array. Output: {input, output, confidence}. Batch or instant API.", "version": "0.2", "buildTag": "latest", "usesStandbyMode": true, "webServerSchema": "./web_server_openapi.json", "dockerfile": "../Dockerfile", "input": "./input_schema.json", "output": "./output_schema.json", "storages": { "dataset": "./dataset_schema.json" }, "defaultRunOptions": { "build": "latest", "memoryMbytes": 256, "timeoutSecs": 360 }, "minMemoryMbytes": 256, "maxMemoryMbytes": 1024 }