crazy-odds-bet-shared 1.0.42 → 1.0.45

package/bookmakers/specifiers/index.js

@@ -0,0 +1,11 @@
+const SpecifiersHelperBase = require('./specifiersHelperBase');
+const SuperbetSpecifiersHelper = require('./superbetSpecifiers');
+const UnibetSpecifiersHelper = require('./unibetSpecifiers');
+const MrBitSpecifiersHelper = require('./mrbitSpecifiers');
+
+module.exports = {
+  SpecifiersHelperBase,
+  SuperbetSpecifiersHelper,
+  UnibetSpecifiersHelper,
+  MrBitSpecifiersHelper
+};

package/bookmakers/specifiers/mrbitSpecifiers.js

@@ -0,0 +1,165 @@
+const { logger } = require('../../utils');
+const SpecifiersHelperBase = require('./specifiersHelperBase');
+
+class MrBitSpecifiersHelper extends SpecifiersHelperBase {
+  constructor(bookmaker, fixture, template, marketOutcome, resources) {
+    super(bookmaker, fixture, template, marketOutcome, resources);
+    this.marketsData = null;
+    this.childMarket = null;
+  }
+
+  getSpecifiers() {
+    const specifiers = {};
+
+    if (this.template?.externalRefs?.[this.bookmaker.slug]?.specifierKeys) {
+      for (const [keyGroup, mappings] of Object.entries(this.template.externalRefs[this.bookmaker.slug].specifierKeys)) {
+        if (!mappings || typeof mappings !== 'object') {
+          logger.warn('Invalid mappings for key group', { keyGroup, mappings });
+          continue;
+        }
+
+        specifiers[keyGroup] = {};
+
+        for (const [key, path] of Object.entries(mappings)) {
+          if (key === 'offset' && keyGroup === 'total') {
+            specifiers[keyGroup][key] = path;
+            logger.debug('Set total offset specifier', { keyGroup, key, value: path });
+            continue;
+          }
+          if (typeof path === 'string') {
+            const filterString = 'marketChild:';
+            const sourceObject = path.startsWith(filterString) ? this.childMarket : this.marketOutcome;
+            const value = this.extractAttributeValue(
+              path.startsWith(filterString) ? path.slice(filterString.length) : path,
+              sourceObject
+            );
+            if (value !== undefined) {
+              specifiers[keyGroup][key] = value;
+              logger.debug('Extracted specifier value', { keyGroup, key, value });
+            } else {
+              logger.warn('Failed to extract specifier value - path not found in market data', { keyGroup, key, path, marketOutcome: this.marketOutcome });
+            }
+          }
+        }
+      }
+    }
+
+    return specifiers;
+  }
+
+  async processExternalRefSpecifiers() {
+    const externalRefSpecifiers = this.getSpecifiers();
+    const templateKeyOrder = this.template?.specifierKeys ? Object.keys(this.template.specifierKeys) : [];
+
+    const specifiers = {};
+
+    for (const keyGroup of templateKeyOrder) {
+      if (externalRefSpecifiers[keyGroup] === undefined) continue;
+
+      const properties = externalRefSpecifiers[keyGroup];
+      switch (keyGroup) {
+        case 'player':
+          specifiers[keyGroup] = await this.getPlayer(properties);
+          break;
+        case 'total':
+          specifiers[keyGroup] = this.getTotal(properties);
+          break;
+        case 'team':
+          specifiers[keyGroup] = this.getTeam(properties);
+          break;
+        case 'quarter':
+          specifiers[keyGroup] = this.getQuarter(properties);
+          break;
+        case 'half':
+          specifiers[keyGroup] = this.getHalf(properties);
+          break;
+        default:
+          specifiers[keyGroup] = properties;
+      }
+    }
+
+    return specifiers;
+  }
+
+  getTotal(externalRef) {
+    const { value, offset } = externalRef;
+    if (offset !== undefined && offset !== null) {
+      const numValue = parseFloat(String(value).replace(/\+/g, '')) || 0;
+      const numOffset = parseFloat(offset) || 0;
+      return { value: String(numValue + numOffset) };
+    }
+    return { value: String(value).replace(/\+/g, '') };
+  }
+
+  async getPlayer(externalRef) {
+    const { name: externalFullName, id: externalRawId } = externalRef;
+    const externalId = this.extractExternalPlayerId(externalRawId);
+    const currentPlayer = await this.getPlayerMapped(externalId, externalFullName);
+
+    return currentPlayer;
+  }
+
+  getQuarter(externalRef) {
+    const { value } = externalRef;
+    return { value: String(this.extractQuarterValue(value)) };
+  }
+
+  getHalf(externalRef) {
+    const { value } = externalRef;
+    return { value: String(this.extractHalfValue(value)) };
+  }
+
+  extractAttributeValue(path, sourceData) {
+    const parts = path.split('.');
+    let current = sourceData;
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (current && typeof current === 'object' && part in current) {
+        current = current[part];
+      } else {
+        logger.warn('Path traversal failed - missing property', { path, failedAtPart: part, failedAtIndex: i });
+        return undefined;
+      }
+    }
+
+    return current;
+  }
+
+  extractExternalPlayerId(externalRawId) {
+    const externalCompetitionName = this.marketsData?.champ?.name || '';
+    const externalCompetitorId = this.marketOutcome?.competitorId;
+    const externalCompetitorName = this.marketsData?.competitors.find((c) => c.id === externalCompetitorId)?.name || '';
+    const str = `${externalRawId}-${externalCompetitionName.slice(0, 3)}-${externalCompetitorName}`;
+    return str
+      .trim()
+      .replace(/\s*\(([^)]*)\)\s*/g, '-$1-')
+      .replace(/[-]+/g, '-')
+      .replace(/^-|-$/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/\./g, '-')
+      .replace(/'/g, '')
+      .replace(/[-]+/g, '-')
+      .toLowerCase();
+  }
+
+  extractQuarterValue(value) {
+    if (value.includes('Sfertul primul') || value.includes('Sfertul întâi')) return '1';
+    if (value.includes('Sfertul al doilea')) return '2';
+    if (value.includes('Sfertul al treilea')) return '3';
+    if (value.includes('Sfertul al patrulea')) return '4';
+
+    return null;
+  }
+
+  extractHalfValue(value) {
+    if (value.includes('Prima repriză')) return '1';
+    if (value.includes('A 2-a repriză')) return '2';
+
+    const s = value.match(/Repriza\s+(\d+)/i);
+
+    return s ? String(s[1]) : null;
+  }
+}
+
+module.exports = MrBitSpecifiersHelper;

package/bookmakers/specifiers/specifiersHelperBase.js

@@ -0,0 +1,173 @@
+const { logger } = require('../../utils');
+const PlayersHelper = require('../../players');
+
+class SpecifiersHelperBase {
+  constructor(bookmaker, fixture, template, marketOutcome, resources) {
+    this.bookmaker = bookmaker;
+    this.fixture = fixture;
+    this.template = template;
+    this.marketOutcome = marketOutcome;
+    this.resources = resources;
+  }
+
+  async getPlayerMapped(externalId, externalFullName) {
+    const externalFullNameNotEmpty = typeof externalFullName === 'string' && externalFullName.trim().length > 0;
+
+    if (!externalFullNameNotEmpty) {
+      throw new Error(`Player name is empty for ${this.bookmaker.slug} ID: ${externalId}`);
+    }
+
+    // Preview mode - return placeholder player
+    if (this.resources?.preview) {
+      return {
+        id: '__preview__',
+        name: externalFullName || '(preview)',
+        externalBookmakerId: String(externalId),
+        teamId: null,
+        teamName: '(preview — not resolved)',
+        teamAbbreviation: '—',
+        _preview: true
+      };
+    }
+
+    let currentPlayer;
+
+    // Find by external ref id (supports array or single object)
+    currentPlayer = this.resources.players.find((p) => {
+      const val = p.externalRefs?.[this.bookmaker.slug];
+      if (!val) return false;
+      const refs = Array.isArray(val) ? val : [val];
+      return refs.some((r) => String(r.id) === String(externalId));
+    });
+    if (currentPlayer) {
+      logger.debug('Found player by ID', { bookmaker: this.bookmaker.slug, externalId, playerName: currentPlayer.fullName });
+
+      return this.mapCurrentPlayer(currentPlayer);
+    }
+
+    const separator = externalFullName.includes(',') ? ',' : ' ';
+    const { firstName, lastName } = PlayersHelper.parseLastFirstName(externalFullName, separator);
+
+    // Find by name and fixture teams (if available)
+    currentPlayer = this.resources.players.find(
+      (p) =>
+        (p.team._id === this.fixture.homeTeamId || p.team._id === this.fixture.awayTeamId) &&
+        ((p.firstName === firstName && p.lastName === lastName) || (p.firstName === lastName && p.lastName === firstName))
+    );
+
+    if (currentPlayer) {
+      logger.debug('Found player by name match', { bookmaker: this.bookmaker.slug, externalId, playerName: currentPlayer.fullName });
+      await this.addExternalRefToPlayer(currentPlayer, { id: externalId, name: externalFullName });
+      return this.mapCurrentPlayer(currentPlayer);
+    }
+
+    this.resources.debugQueue.queuePlayerDebug(externalFullName, externalId);
+
+    throw new Error(`Player not found for ${this.bookmaker.slug} ID: ${externalId}, name: ${externalFullName}`);
+  }
+
+  mapCurrentPlayer(currentPlayer) {
+    if (!currentPlayer.team._id) {
+      logger.error('Player team not populated - cannot map player', { playerId: currentPlayer._id, playerName: currentPlayer.fullName });
+      throw new Error(`Player team not populated for ${currentPlayer.fullName}`);
+    }
+
+    return {
+      id: currentPlayer._id,
+      name: currentPlayer.fullName,
+      teamId: currentPlayer.team._id,
+      teamName: currentPlayer.team?.name,
+      teamAbbreviation: currentPlayer.team?.metadata?.abbreviation ?? currentPlayer.team?.name.slice(0, 3).toUpperCase()
+    };
+  }
+
+  async addExternalRefToPlayer(player, playerData) {
+    if (this.resources?.preview) return;
+    await player.addExternalRef(this.bookmaker.slug, playerData.id, {
+      name: playerData.name,
+      isActive: true,
+      metadata: playerData.metadata || {}
+    });
+  }
+
+  getTeam(externalRef) {
+    const home = this.fixture.homeTeam;
+    const away = this.fixture.awayTeam;
+    if (!home?._id || !away?._id) {
+      logger.warn('getTeam: homeTeam or awayTeam not populated on fixture');
+      return null;
+    }
+
+    const externalNeedle = externalRef ? String(externalRef.side ?? '').trim() : '';
+    if (!externalNeedle) {
+      logger.warn('getTeam: empty external team label', { externalRef });
+      return null;
+    }
+    const homeNames = this.teamMatchNames(home);
+    const awayNames = this.teamMatchNames(away);
+
+    const homeHit = homeNames.some((n) => this.externalTeamLabelMatches(externalNeedle, n));
+    if (homeHit) {
+      logger.debug('getTeam matched home', { externalNeedle, homeNames });
+      return this.mapTeamSpecifier(home, 'home');
+    }
+
+    const awayHit = awayNames.some((n) => this.externalTeamLabelMatches(externalNeedle, n));
+    if (awayHit) {
+      logger.debug('getTeam matched away', { externalNeedle, awayNames });
+      return this.mapTeamSpecifier(away, 'away');
+    }
+
+    logger.warn('getTeam: no home/away match for label', { externalNeedle, homeNames, awayNames });
+    if (this.resources?.preview) {
+      return {
+        id: '__preview__',
+        name: externalNeedle,
+        abbreviation: '—',
+        _preview: true
+      };
+    }
+    return null;
+  }
+
+  getBookmakerTeamRefs(team) {
+    if (!team?.externalRefs || typeof team.externalRefs !== 'object') return [];
+    const val = team.externalRefs[this.bookmaker.slug];
+    if (val == null) return [];
+    return Array.isArray(val) ? val : [val];
+  }
+
+  teamMatchNames(team) {
+    const refs = this.getBookmakerTeamRefs(team);
+    const fromRefs = refs.map((r) => String(r?.name ?? '').trim()).filter(Boolean);
+    if (fromRefs.length > 0) return fromRefs;
+    if (team?.name) return [String(team.name).trim()];
+    return [];
+  }
+
+  externalTeamLabelMatches(externalStr, candidate) {
+    const a = String(externalStr ?? '').trim().toLowerCase();
+    const b = String(candidate ?? '').trim().toLowerCase();
+    if (!a || !b) return false;
+    return a.includes(b) || b.includes(a);
+  }
+
+  mapTeamSpecifier(teamDoc, side) {
+    const name = teamDoc?.name ?? '';
+    const abbr =
+      teamDoc?.metadata?.abbreviation ??
+      (typeof name === 'string' && name.length > 0 ? name.slice(0, 3).toUpperCase() : '');
+    return {
+      id: teamDoc._id,
+      name,
+      abbreviation: abbr,
+      side
+    };
+  }
+
+  startsWithNumber(str) {
+    return /^\d/.test(String(str));
+  }
+}
+
+module.exports = SpecifiersHelperBase;

package/bookmakers/specifiers/superbetSpecifiers.js

@@ -0,0 +1,125 @@
+const { logger } = require('../../utils');
+const { generateSlug } = require('../../models');
+const SpecifiersHelperBase = require('./specifiersHelperBase');
+
+class SuperbetSpecifiersHelper extends SpecifiersHelperBase {
+  getSpecifiers() {
+    const specifiers = {};
+    const externalRefSpecifiers = this.template?.externalRefs?.[this.bookmaker.slug]?.specifierKeys;
+
+    if (externalRefSpecifiers) {
+      for (const [keyGroup, mappings] of Object.entries(externalRefSpecifiers)) {
+        if (!mappings || typeof mappings !== 'object') {
+          logger.warn('Invalid mappings for key group', { keyGroup, mappings });
+          continue;
+        }
+
+        specifiers[keyGroup] = {};
+
+        for (const [key, path] of Object.entries(mappings)) {
+          if (key === 'offset' && keyGroup === 'total') {
+            specifiers[keyGroup][key] = path;
+            logger.debug('Set total offset specifier', { keyGroup, key, value: path });
+            continue;
+          }
+          if (typeof path === 'string') {
+            const value = this.extractAttributeValue(path);
+            if (value !== undefined) {
+              specifiers[keyGroup][key] = value;
+              logger.debug('Extracted specifier value', { keyGroup, key, value });
+            } else {
+              logger.warn('Failed to extract specifier value - path not found in market data', { keyGroup, key, path, availableKeys: Object.keys(this.marketOutcome) });
+            }
+          }
+        }
+      }
+    }
+
+    return specifiers;
+  }
+
+  extractAttributeValue(path) {
+    const parts = path.split('.');
+    let current = this.marketOutcome;
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (current && typeof current === 'object' && part in current) {
+        current = current[part];
+      } else {
+        logger.debug('Path traversal failed - missing property', { path, failedAtPart: part, failedAtIndex: i });
+        return null;
+      }
+    }
+
+    return current;
+  }
+
+  async processExternalRefSpecifiers() {
+    const externalRefSpecifiers = this.getSpecifiers();
+    const templateKeyOrder = this.template?.specifierKeys ? Object.keys(this.template.specifierKeys) : [];
+
+    const specifiers = {};
+
+    for (const keyGroup of templateKeyOrder) {
+      if (externalRefSpecifiers[keyGroup] === undefined) continue;
+
+      const properties = externalRefSpecifiers[keyGroup];
+      switch (keyGroup) {
+        case 'player':
+          specifiers[keyGroup] = await this.getPlayer(properties);
+          break;
+        case 'total':
+          specifiers[keyGroup] = this.getTotal(properties);
+          break;
+        case 'team':
+          specifiers[keyGroup] = this.getTeam(properties);
+          break;
+        case 'quarter':
+          specifiers[keyGroup] = this.getQuarter(properties);
+          break;
+        case 'half':
+          specifiers[keyGroup] = this.getHalf(properties);
+          break;
+        default:
+          specifiers[keyGroup] = properties;
+      }
+    }
+
+    return specifiers;
+  }
+
+  getTotal(externalRef) {
+    const { value, offset } = externalRef;
+    if (offset !== undefined && offset !== null) {
+      return { value: String(Number(value) + Number(offset)) };
+    }
+    return { value: String(value) };
+  }
+
+  async getPlayer(externalRef) {
+    const { name: externalFullName, id: externalRawId } = externalRef;
+    const externalId = externalRawId ? String(externalRawId) : generateSlug(`auto-generated-${this.fixture.sport.slug}-${externalFullName}`);
+    const currentPlayer = await this.getPlayerMapped(externalId, externalFullName);
+
+    return currentPlayer;
+  }
+
+  getQuarter(externalRef) {
+    const s = String(externalRef?.value ?? '').trim();
+    const m = s.match(/Sfertul\s*([0-9])/i);
+    if (!m) return { value: null };
+    const n = Number(m[1]);
+    if (!Number.isFinite(n) || n < 1 || n > 4) return { value: null };
+    return { value: String(n) };
+  }
+
+  getHalf(externalRef) {
+    const s = String(externalRef?.value ?? '').trim().toLowerCase();
+    if (/^prima\b/.test(s)) return { value: '1' };
+    if (/^a\s+doua\b/.test(s)) return { value: '2' };
+    return { value: null };
+  }
+}
+
+module.exports = SuperbetSpecifiersHelper;

package/bookmakers/specifiers/unibetSpecifiers.js

@@ -0,0 +1,183 @@
+const { logger } = require('../../utils');
+const SpecifiersHelperBase = require('./specifiersHelperBase');
+
+class UnibetSpecifiersHelper extends SpecifiersHelperBase {
+  getSpecifiers(market) {
+    const specifiers = {};
+    const bookmakerSpecifierKeys = this.template?.externalRefs?.[this.bookmaker.slug]?.specifierKeys;
+
+    if (bookmakerSpecifierKeys) {
+      for (const [keyGroup, mappings] of Object.entries(bookmakerSpecifierKeys)) {
+        if (!mappings || typeof mappings !== 'object') {
+          logger.warn('Invalid mappings for key group', { keyGroup, mappings });
+          continue;
+        }
+
+        specifiers[keyGroup] = {};
+
+        for (const [key, path] of Object.entries(mappings)) {
+          if (key === 'offset' && keyGroup === 'total') {
+            specifiers[keyGroup][key] = path;
+            logger.debug('Set total offset specifier', { keyGroup, key, value: path });
+            continue;
+          }
+          if (typeof path === 'string') {
+            const sourceObject = path.startsWith('market:') ? market : this.marketOutcome;
+            const value = this.extractAttributeValue(
+              path.startsWith('market:') ? path.slice(7) : path,
+              sourceObject
+            );
+            if (value !== undefined) {
+              specifiers[keyGroup][key] = value;
+              logger.debug('Extracted specifier value', { keyGroup, key, value });
+            } else {
+              logger.warn('Failed to extract specifier value - path not found in market data', { keyGroup, key, path, marketOutcome: this.marketOutcome });
+            }
+          }
+        }
+      }
+    }
+
+    return specifiers;
+  }
+
+  extractAttributeValue(path, sourceData) {
+    const parts = path.split('.');
+    let current = sourceData;
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (current && typeof current === 'object' && part in current) {
+        current = current[part];
+      } else {
+        logger.warn('Path traversal failed - missing property', { path, failedAtPart: part, failedAtIndex: i });
+        return undefined;
+      }
+    }
+
+    return current;
+  }
+
+  async processExternalRefSpecifiers(market, displayType) {
+    const externalRefSpecifiers = this.getSpecifiers(market);
+    const templateKeyOrder = this.template?.specifierKeys ? Object.keys(this.template.specifierKeys) : [];
+
+    const specifiers = {};
+
+    for (const keyGroup of templateKeyOrder) {
+      if (externalRefSpecifiers[keyGroup] === undefined) continue;
+
+      const properties = externalRefSpecifiers[keyGroup];
+      switch (keyGroup) {
+        case 'player':
+          specifiers[keyGroup] = await this.getPlayer(properties, displayType);
+          break;
+        case 'total':
+          specifiers[keyGroup] = this.getTotal(properties, displayType);
+          break;
+        case 'team':
+          specifiers[keyGroup] = this.getTeam(properties);
+          break;
+        case 'quarter':
+          specifiers[keyGroup] = this.getQuarter(properties);
+          break;
+        case 'half':
+          specifiers[keyGroup] = this.getHalf(properties);
+          break;
+        default:
+          specifiers[keyGroup] = properties;
+      }
+    }
+
+    return specifiers;
+  }
+
+  getTotal(externalRef, displayType) {
+    const { value: rawValue, offset } = externalRef;
+    const value = this.extractTotalValue(rawValue, displayType);
+
+    if (offset !== undefined && offset !== null) {
+      return { value: String(Number(value) + Number(offset)) };
+    }
+
+    return { value };
+  }
+
+  async getPlayer(externalRef, displayType) {
+    const { name: externalRawName, id: externalRawId } = externalRef;
+    const externalFullName = this.extractExternalPlayerName(externalRawName, displayType);
+    const externalId = this.extractExternalPlayerId(externalRawId, displayType);
+    const currentPlayer = await this.getPlayerMapped(externalId, externalFullName);
+
+    return currentPlayer;
+  }
+
+  getQuarter(externalRef) {
+    const { value: rawValue } = externalRef;
+    const value = this.extractQuarterValue(rawValue);
+    return { value };
+  }
+
+  getHalf(externalRef) {
+    const { value: rawValue } = externalRef;
+    const value = this.extractHalfValue(rawValue);
+    return { value };
+  }
+
+  extractTotalValue(rawValue, displayType) {
+    const split = rawValue.split('_');
+    switch (displayType) {
+      case 'MultiParticipant':
+        return split.length === 3 ? split[1] : rawValue;
+      default:
+        return rawValue;
+    }
+  }
+
+  extractExternalPlayerName(rawName, displayType) {
+    const split = rawName.split(' - ');
+    const match = rawName.match(/^(.+?)\s+(\d+\+)$/);
+
+    switch (displayType) {
+      case 'OverUnder':
+        return split.length === 2 ? split[1] : null;
+      case 'MultiParticipant':
+        return match ? match[1] : null;
+      default:
+        return rawName;
+    }
+  }
+
+  extractExternalPlayerId(rawId, displayType) {
+    const split = rawId.split('_');
+    const ids = split[0].split(':');
+    switch (displayType) {
+      case 'OverUnder':
+        return ids.length === 2 ? ids[1] : null;
+      case 'MultiParticipant':
+        return split.length === 3 ? split[0] : null;
+      default:
+        return rawId;
+    }
+  }
+
+  extractQuarterValue(rawValue) {
+    const split = rawValue.split(':');
+    const quarterRaw = split[1];
+    if (this.startsWithNumber(quarterRaw)) {
+      return String(quarterRaw.slice(0, 1));
+    }
+    return quarterRaw;
+  }
+
+  extractHalfValue(rawValue) {
+    const split = rawValue.split(':');
+    const halfRaw = split[1];
+    if (this.startsWithNumber(halfRaw)) {
+      return String(halfRaw.slice(0, 1));
+    }
+    return halfRaw;
+  }
+}
+
+module.exports = UnibetSpecifiersHelper;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crazy-odds-bet-shared",
-  "version": "1.0.42",
+  "version": "1.0.45",
   "description": "Shared MongoDB models and utilities for odds project",
   "main": "index.js",
   "exports": {
@@ -9,14 +9,18 @@
     "./models": "./models/index.js",
     "./models/*": "./models/*.js",
     "./utils": "./utils/index.js",
-    "./files": "./files/index.js"
+    "./files": "./files/index.js",
+    "./players": "./players/index.js",
+    "./bookmakers/specifiers": "./bookmakers/specifiers/index.js"
   },
   "files": [
     "index.js",
     "db",
     "models",
     "utils",
-    "files"
+    "files",
+    "players",
+    "bookmakers"
   ],
   "scripts": {
     "lint": "echo \"Lint not configured yet\"",

package/players/index.js

@@ -0,0 +1,24 @@
+class PlayersHelper {
+  /**
+   * Parse last name and first name from a raw name string.
+   * Never returns null: when parsing fails (no separator or empty part), returns a fallback object.
+   * @param {string} rawName
+   * @param {string} separator
+   * @returns {{firstName: string, lastName: string}}
+   */
+  static parseLastFirstName(rawName, separator = ',') {
+    const trimmed = (rawName || '').trim();
+    if (!trimmed) {
+      return { firstName: '', lastName: '' };
+    }
+    if (!trimmed.includes(separator)) {
+      return { firstName: trimmed, lastName: '' };
+    }
+    const parts = trimmed.split(separator).map((s) => s.trim());
+    const lastName = parts[0] || '';
+    const firstName = parts[1] || '';
+    return { firstName, lastName };
+  }
+}
+
+module.exports = PlayersHelper;