chrxmaticc-framework 1.0.2

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/README.md

@@ -0,0 +1,176 @@
+# chrxmaticc-framework
+
+A batteries-included Discord bot framework built on discord.js v14 with Lavalink music, AI integration, XP system and Postgres support — all in ~10 lines.
+
+---
+
+## Install
+
+```bash
+npm install chrxmaticc-framework discord.js
+```
+
+---
+
+## Basic setup
+
+```js
+require("dotenv").config();
+const { ChrxClient } = require("chrxmaticc-framework");
+
+const bot = new ChrxClient({
+  token: process.env.BOT_TOKEN,
+});
+
+bot.start();
+```
+
+---
+
+## With music
+
+```js
+const { ChrxClient } = require("chrxmaticc-framework");
+
+const bot = new ChrxClient({
+  token: process.env.BOT_TOKEN,
+  lavalink: {
+    host: process.env.LAVA_HOST,
+    port: 2333,
+    password: process.env.LAVA_PASS,
+    secure: false,
+  },
+  modules: {
+    music: true,
+  },
+});
+
+bot.start();
+```
+
+---
+
+## Full setup (music + AI + XP + database)
+
+```js
+require("dotenv").config();
+const { ChrxClient } = require("chrxmaticc-framework");
+
+const bot = new ChrxClient({
+  token: process.env.BOT_TOKEN,
+
+  lavalink: {
+    host: process.env.LAVA_HOST,
+    port: 2333,
+    password: process.env.LAVA_PASS,
+    secure: false,
+  },
+
+  modules: {
+    music: true,
+    xp: true,
+    database: process.env.DATABASE_URL,
+    ai: {
+      apiKey: process.env.AI_KEY,
+      model: "gpt-3.5-turbo",
+      provider: "openai", // or "anthropic"
+    },
+  },
+});
+
+bot.start();
+```
+
+---
+
+## Commands
+
+Put your commands in a `commands/` folder (subfolders supported):
+
+```js
+// commands/ping.js
+const { SlashCommandBuilder } = require("discord.js");
+
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName("ping")
+    .setDescription("Pong!"),
+  async execute(interaction) {
+    await interaction.reply("Pong!");
+  },
+};
+```
+
+---
+
+## Events
+
+Put your events in an `events/` folder:
+
+```js
+// events/ready.js
+module.exports = {
+  name: "ready",
+  once: true,
+  execute(client) {
+    console.log(`Logged in as ${client.user.tag}`);
+  },
+};
+```
+
+---
+
+## Song markers (built-in)
+
+The music module includes a clip marker system. Use `/player-set` to set start/end timestamps on any song.
+
+```
+/player-set start 1:43        → jumps to 1:43 when the song plays
+/player-set end 2:44          → cuts off at 2:44
+/player-set end 2:44 loop:true → loops between start and end markers
+/player-set clear both        → removes all markers from the song
+```
+
+---
+
+## AI usage in commands
+
+```js
+async execute(interaction) {
+  const answer = await interaction.client.ai.ask("What is the meaning of life?");
+  await interaction.reply(answer);
+}
+```
+
+---
+
+## XP usage in commands
+
+```js
+async execute(interaction) {
+  const data = await interaction.client.chrx.xp.getUser(
+    interaction.user.id,
+    interaction.guild.id
+  );
+  await interaction.reply(`You are level ${data.level} with ${data.xp} XP.`);
+}
+```
+
+---
+
+## .env example
+
+```env
+BOT_TOKEN=your_bot_token
+CLIENT_ID=your_client_id
+LAVA_HOST=your_lavalink_host
+LAVA_PORT=2333
+LAVA_PASS=your_lavalink_password
+LAVA_SECURE=false
+DATABASE_URL=your_postgres_url
+AI_KEY=your_ai_key
+```
+
+---
+
+## Made by Chrxmee-Bits

package/core/AIWrapper.js

@@ -0,0 +1,73 @@
+/**
+ * src/modules/AIWrapper.js
+ * Lightweight wrapper for AI completions.
+ * Pass your API key and model in the options.
+ */
+
+class AIWrapper {
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey      - Your AI API key
+   * @param {string} [options.model]     - Model to use (default: gpt-3.5-turbo)
+   * @param {string} [options.provider]  - "openai" | "anthropic" (default: openai)
+   */
+  constructor(options = {}) {
+    if (!options.apiKey) throw new Error("[AIWrapper] apiKey is required.");
+    this.apiKey = options.apiKey;
+    this.model = options.model ?? "gpt-3.5-turbo";
+    this.provider = options.provider ?? "openai";
+  }
+
+  /**
+   * Send a prompt and get a response string back.
+   * @param {string} prompt
+   * @param {string} [systemPrompt]
+   * @returns {Promise<string>}
+   */
+  async ask(prompt, systemPrompt = "You are a helpful assistant.") {
+    if (this.provider === "anthropic") {
+      return this._askAnthropic(prompt, systemPrompt);
+    }
+    return this._askOpenAI(prompt, systemPrompt);
+  }
+
+  async _askOpenAI(prompt, systemPrompt) {
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: prompt },
+        ],
+      }),
+    });
+    const data = await res.json();
+    return data.choices?.[0]?.message?.content ?? "No response.";
+  }
+
+  async _askAnthropic(prompt, systemPrompt) {
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model: this.model,
+        max_tokens: 1024,
+        system: systemPrompt,
+        messages: [{ role: "user", content: prompt }],
+      }),
+    });
+    const data = await res.json();
+    return data.content?.[0]?.text ?? "No response.";
+  }
+}
+
+module.exports = AIWrapper;

package/core/CommandLoader.js

@@ -0,0 +1,51 @@
+/**
+ * src/core/CommandLoader.js
+ * Auto-loads slash commands from the user's commands folder.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+class CommandLoader {
+  constructor(client, commandsPath) {
+    this.client = client;
+    this.commandsPath = commandsPath ?? path.join(process.cwd(), "commands");
+  }
+
+  load() {
+    if (!fs.existsSync(this.commandsPath)) {
+      console.warn(`[CommandLoader] Commands folder not found at ${this.commandsPath}`);
+      return;
+    }
+
+    const files = fs.readdirSync(this.commandsPath).filter((f) => f.endsWith(".js"));
+
+    for (const file of files) {
+      const command = require(path.join(this.commandsPath, file));
+      if ("data" in command && "execute" in command) {
+        this.client.commands.set(command.data.name, command);
+        console.log(`[CommandLoader] Loaded command: ${command.data.name}`);
+      }
+    }
+
+    // Also scan subfolders one level deep (e.g. commands/music/)
+    const dirs = fs.readdirSync(this.commandsPath, { withFileTypes: true })
+      .filter((d) => d.isDirectory());
+
+    for (const dir of dirs) {
+      const subPath = path.join(this.commandsPath, dir.name);
+      const subFiles = fs.readdirSync(subPath).filter((f) => f.endsWith(".js"));
+      for (const file of subFiles) {
+        const command = require(path.join(subPath, file));
+        if ("data" in command && "execute" in command) {
+          this.client.commands.set(command.data.name, command);
+          console.log(`[CommandLoader] Loaded command: ${command.data.name} (${dir.name})`);
+        }
+      }
+    }
+
+    console.log(`[CommandLoader] ${this.client.commands.size} commands loaded.`);
+  }
+}
+
+module.exports = CommandLoader;

package/core/Database.js

@@ -0,0 +1,48 @@
+/**
+ * src/modules/Database.js
+ * Simple Postgres connection helper.
+ */
+
+const { Pool } = require("pg");
+
+class Database {
+  constructor(connectionString) {
+    this.pool = new Pool({
+      connectionString,
+      ssl: { rejectUnauthorized: false },
+      max: 10,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: 5000,
+      keepAlive: true,
+    });
+
+    this.pool.on("error", (err) => {
+      console.error("[Database] Pool error:", err.message);
+    });
+  }
+
+  async init() {
+    const client = await this.pool.connect();
+    await client.query("SELECT 1");
+    client.release();
+    console.log("[Database] Connection verified.");
+  }
+
+  /**
+   * Run a query against the database.
+   * @param {string} text  SQL query
+   * @param {any[]}  params  Query parameters
+   */
+  async query(text, params) {
+    return this.pool.query(text, params);
+  }
+
+  /**
+   * Get a client from the pool for transactions.
+   */
+  async connect() {
+    return this.pool.connect();
+  }
+}
+
+module.exports = Database;

package/core/EventLoader.js

@@ -0,0 +1,38 @@
+/**
+ * src/core/EventLoader.js
+ * Auto-loads events from the user's events folder.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+class EventLoader {
+  constructor(client, eventsPath) {
+    this.client = client;
+    this.eventsPath = eventsPath ?? path.join(process.cwd(), "events");
+  }
+
+  load() {
+    if (!fs.existsSync(this.eventsPath)) {
+      console.warn(`[EventLoader] Events folder not found at ${this.eventsPath}`);
+      return;
+    }
+
+    const files = fs.readdirSync(this.eventsPath).filter((f) => f.endsWith(".js"));
+
+    for (const file of files) {
+      const event = require(path.join(this.eventsPath, file));
+      if (!event.name || !event.execute) continue;
+
+      if (event.once) {
+        this.client.once(event.name, (...args) => event.execute(...args));
+      } else {
+        this.client.on(event.name, (...args) => event.execute(...args));
+      }
+
+      console.log(`[EventLoader] Loaded event: ${event.name}`);
+    }
+  }
+}
+
+module.exports = EventLoader;

package/core/MusicManager.js

@@ -0,0 +1,78 @@
+/**
+ * src/music/MusicManager.js
+ * Handles all Lavalink events and wires in the song marker system.
+ */
+
+const { EmbedBuilder } = require("discord.js");
+const {
+  applyStartMarker,
+  startEndMarkerWatcher,
+  stopEndMarkerWatcher,
+  getMarkers,
+} = require("./songMarkers");
+
+class MusicManager {
+  constructor(client) {
+    this.client = client;
+    this._registerEvents();
+  }
+
+  _registerEvents() {
+    const lavalink = this.client.lavalink;
+
+    // ── trackStart ────────────────────────────────────────────────────────
+    lavalink.on("trackStart", async (player, track) => {
+      const channel = this.client.channels.cache.get(player.textChannelId);
+      if (channel) {
+        channel.send({
+          embeds: [
+            new EmbedBuilder()
+              .setColor("#5865F2")
+              .setTitle("🎵 Now Playing")
+              .setDescription(`**[${track.info.title}](${track.info.uri})**`)
+              .addFields(
+                { name: "Author", value: track.info.author, inline: true },
+                { name: "Duration", value: this._msToTime(track.info.duration), inline: true },
+                { name: "Requested by", value: `<@${track.info.requester?.id || "Unknown"}>`, inline: true }
+              )
+              .setThumbnail(track.info.artworkUrl)
+              .setTimestamp(),
+          ],
+        }).catch(() => {});
+      }
+
+      // Song marker system
+      const m = getMarkers(track);
+      if (!m) return;
+      if (m.start != null) await applyStartMarker(player, track);
+      if (m.end != null) startEndMarkerWatcher(player, track, m.loop ?? false);
+    });
+
+    // ── trackEnd ──────────────────────────────────────────────────────────
+    lavalink.on("trackEnd", (player) => {
+      stopEndMarkerWatcher(player.guildId);
+    });
+
+    // ── queueEnd ──────────────────────────────────────────────────────────
+    lavalink.on("queueEnd", (player) => {
+      stopEndMarkerWatcher(player.guildId);
+      const channel = this.client.channels.cache.get(player.textChannelId);
+      if (channel) channel.send("✅ Queue finished! Add more songs to keep the vibe going.").catch(() => {});
+    });
+
+    // ── playerDestroy ─────────────────────────────────────────────────────
+    lavalink.on("playerDestroy", (player) => {
+      stopEndMarkerWatcher(player.guildId);
+    });
+  }
+
+  _msToTime(ms) {
+    const s = Math.floor((ms / 1000) % 60);
+    const m = Math.floor((ms / (1000 * 60)) % 60);
+    const h = Math.floor(ms / (1000 * 60 * 60));
+    if (h > 0) return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+    return `${m}:${String(s).padStart(2, "0")}`;
+  }
+}
+
+module.exports = MusicManager;

package/core/XPSystem.js

@@ -0,0 +1,80 @@
+/**
+ * src/modules/XPSystem.js
+ * Built-in XP/leveling system.
+ * Requires Database module to be enabled.
+ */
+
+class XPSystem {
+  constructor(client) {
+    this.client = client;
+    this.cooldowns = new Map(); // userId -> timestamp
+    this.cooldownMs = 60000; // 1 minute between XP gains
+
+    this._registerEvent();
+  }
+
+  _registerEvent() {
+    this.client.on("messageCreate", async (message) => {
+      if (message.author.bot || !message.guild) return;
+      if (!this.client.db) return;
+
+      const userId = BigInt(message.author.id);
+      const guildId = BigInt(message.guild.id);
+      const now = Date.now();
+
+      // Cooldown check
+      const key = `${userId}-${guildId}`;
+      if (this.cooldowns.has(key) && now - this.cooldowns.get(key) < this.cooldownMs) return;
+      this.cooldowns.set(key, now);
+
+      const xpGain = Math.floor(Math.random() * 10) + 5; // 5-15 XP per message
+
+      await this.client.db.query(`
+        INSERT INTO chrx_user_xp (user_id, guild_id, xp, level)
+        VALUES ($1, $2, $3, 0)
+        ON CONFLICT (user_id, guild_id)
+        DO UPDATE SET xp = chrx_user_xp.xp + $3
+      `, [userId, guildId, xpGain]);
+
+      // Check for level up
+      const result = await this.client.db.query(
+        `SELECT xp, level FROM chrx_user_xp WHERE user_id = $1 AND guild_id = $2`,
+        [userId, guildId]
+      );
+
+      if (!result.rows.length) return;
+      const { xp, level } = result.rows[0];
+      const xpNeeded = this._xpForLevel(level + 1);
+
+      if (xp >= xpNeeded) {
+        const newLevel = level + 1;
+        await this.client.db.query(
+          `UPDATE chrx_user_xp SET level = $1, xp = 0 WHERE user_id = $2 AND guild_id = $3`,
+          [newLevel, userId, guildId]
+        );
+        message.channel.send(`🎉 ${message.author} leveled up to **level ${newLevel}**!`).catch(() => {});
+      }
+    });
+  }
+
+  /**
+   * Get XP and level for a user in a guild.
+   */
+  async getUser(userId, guildId) {
+    if (!this.client.db) throw new Error("[XPSystem] Database module is not enabled.");
+    const result = await this.client.db.query(
+      `SELECT xp, level FROM chrx_user_xp WHERE user_id = $1 AND guild_id = $2`,
+      [BigInt(userId), BigInt(guildId)]
+    );
+    return result.rows[0] ?? { xp: 0, level: 0 };
+  }
+
+  /**
+   * XP required to reach a given level.
+   */
+  _xpForLevel(level) {
+    return 100 * level * level;
+  }
+}
+
+module.exports = XPSystem;

package/core/client.js

@@ -0,0 +1,163 @@
+/**
+ * src/core/Client.js
+ * The main ChrxClient class — wraps discord.js Client with
+ * auto loaders, Lavalink, and optional modules.
+ */
+
+const { Client, GatewayIntentBits, Collection, Partials } = require("discord.js");
+const { LavalinkManager } = require("lavalink-client");
+const CommandLoader = require("./CommandLoader");
+const EventLoader = require("./EventLoader");
+const MusicManager = require("./MusicManager");
+const Database = require("./Database");
+const XPSystem = require("./XPSystem");
+const AIWrapper = require("./AIWrapper");
+
+class ChrxClient {
+  /**
+   * @param {object} options
+   * @param {string} options.token                  - Bot token
+   * @param {string} [options.commandsPath]         - Path to commands folder (default: ./commands)
+   * @param {string} [options.eventsPath]           - Path to events folder (default: ./events)
+   * @param {object} [options.lavalink]             - Lavalink config
+   * @param {string} options.lavalink.host
+   * @param {number} [options.lavalink.port]
+   * @param {string} options.lavalink.password
+   * @param {boolean} [options.lavalink.secure]
+   * @param {object} [options.modules]              - Optional modules to enable
+   * @param {boolean} [options.modules.music]       - Enable music system
+   * @param {boolean} [options.modules.xp]          - Enable XP system
+   * @param {boolean} [options.modules.ai]          - Enable AI wrapper
+   * @param {string}  [options.modules.database]    - Postgres connection string
+   * @param {number[]} [options.intents]            - Override default intents
+   */
+  constructor(options = {}) {
+    if (!options.token) throw new Error("[ChrxClient] token is required.");
+
+    this._options = options;
+
+    // ── Discord client ───────────────────────────────────────────────────
+    this.client = new Client({
+      intents: options.intents ?? [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent,
+        GatewayIntentBits.GuildMembers,
+        GatewayIntentBits.GuildVoiceStates,
+        GatewayIntentBits.DirectMessages,
+      ],
+      partials: [Partials.Channel, Partials.Message],
+    });
+
+    this.client.commands = new Collection();
+    this.client.chrx = this; // expose framework on client for use in commands/events
+
+    // ── Lavalink ─────────────────────────────────────────────────────────
+    if (options.lavalink && options.modules?.music !== false) {
+      this._setupLavalink(options.lavalink);
+    }
+
+    // ── Optional modules ─────────────────────────────────────────────────
+    if (options.modules?.database) {
+      this.db = new Database(options.modules.database);
+      this.client.db = this.db;
+    }
+
+    if (options.modules?.xp) {
+      this.xp = new XPSystem(this.client);
+    }
+
+    if (options.modules?.ai) {
+      this.ai = new AIWrapper(options.modules.ai);
+      this.client.ai = this.ai;
+    }
+
+    // ── Loaders ───────────────────────────────────────────────────────────
+    this._commandLoader = new CommandLoader(this.client, options.commandsPath);
+    this._eventLoader = new EventLoader(this.client, options.eventsPath);
+
+    // ── Ready event ───────────────────────────────────────────────────────
+    this.client.once("ready", async () => {
+      if (this.client.lavalink) {
+        await this.client.lavalink.init({
+          id: this.client.user.id,
+          username: this.client.user.username,
+        });
+        console.log("[ChrxClient] Lavalink initialized!");
+      }
+
+      if (this.db) {
+        await this.db.init();
+        console.log("[ChrxClient] Database connected!");
+      }
+
+      console.log(`[ChrxClient] Ready! Logged in as ${this.client.user.tag}`);
+    });
+
+    // ── Voice state forwarding for Lavalink ───────────────────────────────
+    this.client.on("raw", (d) => {
+      if (d.t === "VOICE_SERVER_UPDATE" || d.t === "VOICE_STATE_UPDATE") {
+        this.client.lavalink?.sendRawData(d);
+      }
+    });
+
+    // ── Global error handlers ─────────────────────────────────────────────
+    process.on("unhandledRejection", (reason) => {
+      console.error("[ChrxClient] Unhandled Rejection:", reason);
+    });
+    process.on("uncaughtException", (err) => {
+      console.error("[ChrxClient] Uncaught Exception:", err);
+    });
+  }
+
+  /**
+   * Set up the LavalinkManager and attach it to the client.
+   */
+  _setupLavalink(cfg) {
+    this.client.lavalink = new LavalinkManager({
+      nodes: [
+        {
+          host: cfg.host,
+          port: cfg.port ?? 2333,
+          authorization: cfg.password,
+          secure: cfg.secure ?? false,
+          id: "main",
+        },
+      ],
+      sendToShard: (guildId, payload) => {
+        const guild = this.client.guilds.cache.get(guildId);
+        if (guild) guild.shard.send(payload);
+      },
+      client: {
+        id: process.env.CLIENT_ID,
+        username: "ChrxBot",
+      },
+      playerOptions: {
+        defaultSearchPlatform: "ytsearch",
+        onDisconnect: { destroyPlayer: true },
+        onEmptyQueue: { destroyAfterMs: 30000 },
+      },
+    });
+
+    // Attach music manager (handles events + marker system)
+    this.music = new MusicManager(this.client);
+
+    this.client.lavalink.on("nodeConnect", (node) =>
+      console.log(`[ChrxClient] Lavalink node "${node.id}" connected!`)
+    );
+    this.client.lavalink.on("nodeError", (node, err) =>
+      console.error(`[ChrxClient] Lavalink node "${node.id}" error:`, err.message)
+    );
+  }
+
+  /**
+   * Load commands and events then log in.
+   */
+  async start() {
+    this._commandLoader.load();
+    this._eventLoader.load();
+    await this.client.login(this._options.token);
+  }
+}
+
+module.exports = { ChrxClient };

package/core/index.js

@@ -0,0 +1,41 @@
+/**
+ * src/index.js
+ * Main entry point — exports everything the user needs.
+ */
+
+const { ChrxClient } = require("./Client");
+const Database = require("./Database");
+const XPSystem = require("./XPSystem");
+const AIWrapper = require("./AIWrapper");
+const MusicManager = require("./MusicManager");
+const {
+  parseTime,
+  formatTime,
+  setMarker,
+  getMarkers,
+  clearMarker,
+  applyStartMarker,
+  startEndMarkerWatcher,
+  stopEndMarkerWatcher,
+} = require("./songMarkers");
+
+module.exports = {
+  // Core
+  ChrxClient,
+
+  // Modules
+  Database,
+  XPSystem,
+  AIWrapper,
+  MusicManager,
+
+  // Song marker utilities (for advanced users)
+  parseTime,
+  formatTime,
+  setMarker,
+  getMarkers,
+  clearMarker,
+  applyStartMarker,
+  startEndMarkerWatcher,
+  stopEndMarkerWatcher,
+};

package/core/songMarkers.js

@@ -0,0 +1,196 @@
+/**
+ * Song marker system for Discord Music Bots.
+ * Per-track start/end marker system — lavalink-client v2 compatible.
+ *
+ * Markers are stored in memory. They persist as long as the bot is running
+ * but reset on restart. Swap the Map for Postgres if you want them permanent.
+ */
+
+// Key: track URI (or title fallback) → { start?: ms, end?: ms, loop?: bool }
+const markers = new Map();
+
+// Active end-marker watcher per guild: guildId → intervalId
+const endIntervals = new Map();
+
+// ── Time utilities ────────────────────────────────────────────────────────
+
+/**
+ * Parse "mm:ss" or "hh:mm:ss" into milliseconds.
+ * Returns null if the format is invalid.
+ */
+function parseTime(timeStr) {
+  const parts = timeStr.trim().split(":").map(Number);
+  if (parts.some(isNaN)) return null;
+  if (parts.length === 2) return (parts[0] * 60 + parts[1]) * 1000;
+  if (parts.length === 3) return (parts[0] * 3600 + parts[1] * 60 + parts[2]) * 1000;
+  return null;
+}
+
+/**
+ * Format milliseconds into a readable "m:ss" string.
+ */
+function formatTime(ms) {
+  const totalSec = Math.floor(ms / 1000);
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return `${m}:${s.toString().padStart(2, "0")}`;
+}
+
+// ── Key resolution ────────────────────────────────────────────────────────
+
+/**
+ * Get a stable unique key for a track.
+ * lavalink-client v2 stores info under track.info.*
+ */
+function getKey(track) {
+  return track?.info?.uri || track?.info?.title || track?.uri || track?.title || null;
+}
+
+// ── Marker CRUD ───────────────────────────────────────────────────────────
+
+/**
+ * Set a start or end marker on a track.
+ * @param {object} track
+ * @param {"start"|"end"} type
+ * @param {number} ms
+ * @param {boolean} [loop=false]  Only relevant for end markers
+ */
+function setMarker(track, type, ms, loop = false) {
+  const key = getKey(track);
+  if (!key) return;
+  const existing = markers.get(key) || {};
+  markers.set(key, {
+    ...existing,
+    [type]: ms,
+    ...(type === "end" ? { loop } : {}),
+  });
+}
+
+/**
+ * Get the markers object for a track ({ start?, end?, loop? }) or null.
+ */
+function getMarkers(track) {
+  const key = getKey(track);
+  if (!key) return null;
+  return markers.get(key) || null;
+}
+
+/**
+ * Clear a start, end, or both markers from a track.
+ * @param {object} track
+ * @param {"start"|"end"|"both"} type
+ */
+function clearMarker(track, type) {
+  const key = getKey(track);
+  if (!key) return;
+  const existing = markers.get(key);
+  if (!existing) return;
+
+  if (type === "both") {
+    markers.delete(key);
+    return;
+  }
+
+  delete existing[type];
+  if (type === "end") delete existing.loop;
+
+  if (existing.start == null && existing.end == null) {
+    markers.delete(key);
+  } else {
+    markers.set(key, existing);
+  }
+}
+
+// ── Marker application ────────────────────────────────────────────────────
+
+/**
+ * Seek to the start marker when a track begins.
+ * Called inside the trackStart event.
+ *
+ * lavalink-client v2: player.seek(ms) accepts a number.
+ */
+async function applyStartMarker(player, track) {
+  const m = getMarkers(track);
+  if (!m?.start) return;
+
+  // Brief delay so Lavalink has buffered enough to accept a seek
+  await sleep(350);
+
+  try {
+    await player.seek(m.start);
+  } catch (err) {
+    console.error("[SongMarkers] applyStartMarker failed:", err.message);
+  }
+}
+
+/**
+ * Start a 500ms polling interval that enforces the end marker.
+ * When position >= end marker:
+ *   - If loop is true  → seek back to start marker (or 0)
+ *   - If loop is false → skip to the next track
+ *
+ * @param {object} player
+ * @param {object} track
+ * @param {boolean} [loop=false]
+ */
+function startEndMarkerWatcher(player, track, loop = false) {
+  stopEndMarkerWatcher(player.guildId); // always clear before starting fresh
+
+  const m = getMarkers(track);
+  if (!m?.end) return;
+
+  const intervalId = setInterval(async () => {
+    try {
+      // If the player moved on to a different track, stop watching
+      const current = player.queue?.current;
+      if (!current || getKey(current) !== getKey(track)) {
+        stopEndMarkerWatcher(player.guildId);
+        return;
+      }
+
+      // lavalink-client v2: player.position is a number in ms
+      if (player.position >= m.end) {
+        if (loop) {
+          const seekTo = m.start ?? 0;
+          await player.seek(seekTo);
+        } else {
+          // Skip to next track (or stop if queue is empty)
+          await player.skip().catch(() => player.stopTrack());
+          stopEndMarkerWatcher(player.guildId);
+        }
+      }
+    } catch (err) {
+      console.error("[SongMarkers] endMarkerWatcher tick failed:", err.message);
+    }
+  }, 500);
+
+  endIntervals.set(player.guildId, intervalId);
+}
+
+/**
+ * Stop the end marker watcher for a guild.
+ */
+function stopEndMarkerWatcher(guildId) {
+  if (endIntervals.has(guildId)) {
+    clearInterval(endIntervals.get(guildId));
+    endIntervals.delete(guildId);
+  }
+}
+
+// ── Internal ──────────────────────────────────────────────────────────────
+
+function sleep(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+module.exports = {
+  parseTime,
+  formatTime,
+  getKey,
+  setMarker,
+  getMarkers,
+  clearMarker,
+  applyStartMarker,
+  startEndMarkerWatcher,
+  stopEndMarkerWatcher,
+};

package/index.js

@@ -0,0 +1,41 @@
+/**
+ * src/index.js
+ * Main entry point — exports everything the user needs.
+ */
+
+const { ChrxClient } = require("./core/Client");
+const Database = require("./core/Database");
+const XPSystem = require("./core/XPSystem");
+const AIWrapper = require("./core/AIWrapper");
+const MusicManager = require("./core/MusicManager");
+const {
+  parseTime,
+  formatTime,
+  setMarker,
+  getMarkers,
+  clearMarker,
+  applyStartMarker,
+  startEndMarkerWatcher,
+  stopEndMarkerWatcher,
+} = require("./core/songMarkers");
+
+module.exports = {
+  // Core
+  ChrxClient,
+
+  // Modules
+  Database,
+  XPSystem,
+  AIWrapper,
+  MusicManager,
+
+  // Song marker utilities (for advanced users)
+  parseTime,
+  formatTime,
+  setMarker,
+  getMarkers,
+  clearMarker,
+  applyStartMarker,
+  startEndMarkerWatcher,
+  stopEndMarkerWatcher,
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "chrxmaticc-framework",
+  "version": "1.0.2",
+  "description": "A batteries-included Discord bot framework with music, AI, XP and database support.",
+  "main": "index.js",
+  "keywords": [
+    "discord",
+    "discord.js",
+    "lavalink",
+    "music",
+    "bot",
+    "framework",
+    "ai",
+    "xp"
+  ],
+  "author": "Chrxmee-Bits",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Chrxmee-Bits/Chrxmaticc-Framework.git"
+  },
+  "peerDependencies": {
+    "discord.js": "^14.0.0"
+  },
+  "dependencies": {
+    "lavalink-client": "^2.0.0",
+    "pg": "^8.11.0",
+    "dotenv": "^16.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "test": "node -e \"console.log('No tests yet')\"",
+    "prepublishOnly": "npm test"
+  }
+}