{"_id":"@acapans/lavalink-client","name":"@acapans/lavalink-client","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.3":{"name":"@acapans/lavalink-client","version":"1.0.3","description":"Production-grade Lavalink v4 client with multi-node support, session resuming, and penalty-based load balancing","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","dev":"tsc --watch","test":"node dist/test.js","typecheck":"tsc --noEmit","lint":"eslint src --ext .ts"},"dependencies":{"undici":"^6.21.1","ws":"^8.18.0","ioredis":"^5.4.2"},"devDependencies":{"@types/node":"^22.10.5","@types/ws":"^8.5.13","typescript":"^5.7.2"},"engines":{"node":">=18.0.0"},"keywords":["lavalink","v4","discord","music","audio","voice","websocket","load-balancer","multi-node"],"repository":{"type":"git","url":"git+https://github.com/acapans/lavalink-client.git"},"bugs":{"url":"https://github.com/acapans/lavalink-client/issues"},"homepage":"https://github.com/acapans/lavalink-client#readme","author":{"name":"Lavalink Client Team"},"license":"MIT","gitHead":"4f49a57f21d7f649ba0c1e8c3f42bf432b277df4","_id":"@acapans/lavalink-client@1.0.3","_nodeVersion":"20.20.2","_npmVersion":"11.14.0","dist":{"integrity":"sha512-3fj1UwqF9Yh33JdbxTBOqa2dTO9Q4c+v/leErrECJv1/XV3taTN8Pp7clvhFbHaIf/ZDtAX2zr/GYQxNieWldA==","shasum":"976cf708c5b565ad2052bf57eb74325baa908ce0","tarball":"https://registry.npmjs.org/@acapans/lavalink-client/-/lavalink-client-1.0.3.tgz","fileCount":35,"unpackedSize":141262,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDkFt6bZHf2/IHtf9G9v1lKhHhaBdOHG5O5hx6XBva+aAIhALscrTK+LxQOPuOpIdFH7R10PSm2vzHCaBnv4FQNuYW/"}]},"_npmUser":{"name":"acapan","email":"ibotsboting@gmail.com"},"directories":{},"maintainers":[{"name":"acapan","email":"ibotsboting@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/lavalink-client_1.0.3_1779138337819_0.1868150706208045"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T21:05:37.715Z","1.0.3":"2026-05-18T21:05:37.971Z","modified":"2026-05-18T21:05:38.244Z"},"maintainers":[{"name":"acapan","email":"ibotsboting@gmail.com"}],"description":"Production-grade Lavalink v4 client with multi-node support, session resuming, and penalty-based load balancing","homepage":"https://github.com/acapans/lavalink-client#readme","keywords":["lavalink","v4","discord","music","audio","voice","websocket","load-balancer","multi-node"],"repository":{"type":"git","url":"git+https://github.com/acapans/lavalink-client.git"},"author":{"name":"Lavalink Client Team"},"bugs":{"url":"https://github.com/acapans/lavalink-client/issues"},"license":"MIT","readme":"# Lavalink Client v4\n\nProduction-grade Lavalink v4 client library for Node.js with multi-node support, session resuming, penalty-based load balancing, and circuit breakers.\n\n## Features\n\n- **REST-first Architecture** - Built for Lavalink v4's REST API protocol\n- **Multi-Node Load Balancing** - Penalty-based node selection with configurable weights\n- **WebSocket Resilience** - Exponential backoff with jitter for reconnection\n- **Session Resuming** - Zero-downtime client restarts\n- **Circuit Breakers** - Automatic fault isolation\n- **Queue Persistence** - Redis and in-memory store support\n- **Auto-skip & Auto-resume** - Intelligent playback handling\n- **Player Migration** - Automatic failover on node disconnect\n- **Full TypeScript** - Complete type safety\n\n## Installation\n\n```bash\nnpm install lavalink-client\n```\n\n## Quick Start\n\n```typescript\nimport { Manager, RedisQueueStore } from 'lavalink-client';\n\nconst manager = new Manager({\n  nodes: [\n    {\n      id: 'node-1',\n      host: 'localhost',\n      port: 2333,\n      authorization: 'youshallnotpass',\n      retries: 10,\n      reconnectInterval: 5000,\n    },\n  ],\n  userId: 'YOUR_DISCORD_USER_ID',\n  sendGatewayPayload: (guildId, payload) => {\n    // Forward to Discord gateway\n    guild.shard.send(payload);\n  },\n  queueStore: new RedisQueueStore({ host: 'localhost', port: 6379 }),\n  autoSkip: true,\n  autoResume: true,\n});\n\nmanager.on('nodeConnect', (node) => {\n  console.log(`Node ${node.id} connected`);\n});\n\nmanager.on('trackStart', (player, track) => {\n  console.log(`Playing: ${track.info.title}`);\n});\n\nmanager.connect();\n```\n\n## Configuration Options\n\n### Node Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `id` | string | required | Unique node identifier |\n| `host` | string | required | Lavalink server hostname |\n| `port` | number | required | Lavalink server port |\n| `authorization` | string | required | Lavalink password |\n| `secure` | boolean | false | Use WSS/HTTPS |\n| `regions` | string[] | [] | Voice regions for routing |\n| `retries` | number | 10 | Max reconnection attempts |\n| `reconnectInterval` | number | 5000 | Base reconnection delay (ms) |\n| `resumeTimeout` | number | 30000 | Session resume timeout (ms) |\n| `moveOnDisconnect` | boolean | true | Auto-migrate players on disconnect |\n\n### Manager Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `nodes` | NodeOptions[] | required | Lavalink node configurations |\n| `userId` | string | required | Discord bot user ID |\n| `sendGatewayPayload` | function | required | Discord gateway send function |\n| `queueStore` | QueueStoreManager | Memory | Queue persistence backend |\n| `autoSkip` | boolean | true | Auto-advance on track end/error |\n| `autoResume` | boolean | true | Enable session resuming |\n| `destroyAfterMs` | number | 30000 | Auto-destroy after queue end (ms) |\n| `maxQueueSize` | number | 10000 | Maximum tracks in queue |\n| `maxPreviousTracks` | number | 25 | Maximum history entries |\n\n## Penalty-Based Load Balancing\n\nThe client uses weighted penalty calculation for node selection:\n\n| Component | Weight | Threshold |\n|-----------|--------|-----------|\n| Total Players | 1.0x | >100/node |\n| Playing Players | 2.5x | >50/node |\n| CPU Load | 3.0x | >70% |\n| Memory Ratio | 2.0x | >80% |\n| Frame Deficits | 5.0x | Any non-zero |\n| Frame Nulls | 3.0x | >10/update |\n\n## WebSocket Reconnection\n\nExponential backoff with jitter:\n\n```\ndelay = min(base * 2^attempt + random(0, 0.5 * base * 2^attempt), 60000)\n```\n\nParameters:\n- Base delay: 5s\n- Max delay: 60s\n- Jitter fraction: 50%\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md","_rev":"1-340e741286b8d462c74b9884b8f56c57"}