amberlink-client 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rahul Tarafder
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,159 @@
1
- # Temporary Holding Version
1
+ # AmberLink Client
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/amberlink-client)](https://www.npmjs.com/package/amberlink-client)
4
+ [![npm downloads](https://img.shields.io/npm/dm/amberlink-client)](https://www.npmjs.com/package/amberlink-client)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
6
+
7
+ **AmberLink Client** is a TypeScript/JavaScript client for managing AmberLink audio servers and compatible node implementations. It provides node management, players, queues, filters, lyrics utilities, and related types through a single package.
8
+
9
+
10
+ ## Requirements
11
+
12
+ - Node.js **18 or newer**, or Bun **1.1.27 or newer**.
13
+ - An AmberLink server or compatible node you can connect to.
14
+ - A Discord bot/application and a Discord library for handling voice connections and forwarding voice payloads.
15
+
16
+ AmberLink Client does not replace your Discord library's voice connection implementation. You must connect the bot to voice and implement the `sendToShard` callback for your Discord library.
17
+
18
+
19
+ ## Install
20
+
21
+ ```bash
22
+ npm install amberlink-client
23
+ ```
24
+
25
+
26
+ ## Quick start
27
+
28
+ This minimal setup initializes the manager. The voice-payload callback is deliberately left as an integration point because its implementation differs between Discord libraries.
29
+
30
+ ```ts
31
+ import { AmberLinkManager, NodeType } from "amberlink-client";
32
+
33
+ const clientId = process.env.DISCORD_CLIENT_ID;
34
+ const password = process.env.AMBERLINK_PASSWORD;
35
+
36
+ if (!clientId || !password) {
37
+ throw new Error("Set DISCORD_CLIENT_ID and AMBERLINK_PASSWORD first.");
38
+ }
39
+
40
+
41
+ const manager = new AmberLinkManager({
42
+ nodes: [
43
+ {
44
+ id: "amber-primary",
45
+ host: process.env.AMBERLINK_HOST ?? "127.0.0.1",
46
+ port: Number(process.env.AMBERLINK_PORT ?? 2333),
47
+ authorization: password,
48
+ nodeType: NodeType.AmberLink,
49
+ },
50
+ ],
51
+ client: { id: clientId, username: "MyBot" },
52
+ sendToShard: (guildId, payload) => {
53
+ // Forward payload to your Discord library's voice/shard API.
54
+ // Never log voice payloads or tokens.
55
+ void guildId;
56
+ void payload;
57
+ },
58
+ });
59
+
60
+
61
+ await manager.init({ id: clientId });
62
+ ```
63
+
64
+
65
+ ## Configuration
66
+
67
+ | Property | Description |
68
+ | --- | --- |
69
+ | `nodes` | Node configurations supplied to the manager. |
70
+ | `nodes[].id` | Optional node identifier. |
71
+ | `nodes[].host` | Hostname or IP address of the node. |
72
+ | `nodes[].port` | Node websocket port. |
73
+ | `nodes[].authorization` | Shared secret configured on the server. |
74
+ | `nodes[].nodeType` | Node protocol, selected using `NodeType`. |
75
+ | `client.id` | Discord application/client ID. |
76
+ | `client.username` | Client username reported to the server. |
77
+ | `sendToShard` | Callback for forwarding Discord voice payloads using your Discord library. |
78
+
79
+
80
+ ## Node types
81
+
82
+ The package exports `NodeType` with these documented options:
83
+
84
+ - `NodeType.AmberLink` — AmberLink protocol/server.
85
+ - `NodeType.ThirdPartyNode` — compatible third-party node.
86
+ - `NodeType.NodeLink` — NodeLink protocol implementation.
87
+
88
+ Use the node type that matches the server you are connecting to. Protocol support and feature availability may differ by node.
89
+
90
+
91
+ ## Features
92
+
93
+ - Manager and node lifecycle management
94
+ - AmberLink and NodeLink node implementations
95
+ - Player management and track handling
96
+ - Queue utilities and queue persistence interfaces
97
+ - Audio filter management
98
+ - Lyrics timeline normalization and synchronization helpers
99
+ - TypeScript public types and utility exports
100
+
101
+
102
+ ## Examples
103
+
104
+ - [`examples/amberlink-client/`](./examples/amberlink-client/) — client initialization example.
105
+ - [`examples/amberlink-server/`](./examples/amberlink-server/) — server setup notes.
106
+ - [`examples/`](./examples/) — example index.
107
+
108
+
109
+ ## Development
110
+
111
+ Clone the repository and install development dependencies:
112
+
113
+
114
+ ```bash
115
+ git clone https://github.com/RahulTarafder/AmberLink-Client.git
116
+ cd AmberLink-Client
117
+ npm install
118
+ ```
119
+
120
+ Run checks:
121
+
122
+ ```bash
123
+ npm run typecheck
124
+ npm test
125
+ npm run lint
126
+ ```
127
+
128
+ Available scripts:
129
+
130
+ | Script | Purpose |
131
+ | --- | --- |
132
+ | `npm run build` | Build package output into `dist/`. |
133
+ | `npm run typecheck` | Run TypeScript type checking without emitting files. |
134
+ | `npm test` | Build and run the Node.js test suite. |
135
+ | `npm run lint` | Lint project files. |
136
+ | `npm run lint:fix` | Apply supported lint fixes. |
137
+ | `npm run fmt` | Format project files. |
138
+
139
+ Tests currently focus on lyrics timeline parsing, normalization, timing boundaries, and legacy input compatibility. They are not a substitute for testing against a running audio node and Discord voice connection.
140
+
141
+
142
+ ## Contributing
143
+
144
+ Issues, bug reports, documentation improvements, and pull requests are welcome. Please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before submitting changes.
145
+
146
+
147
+ ## Author
148
+
149
+ **Rahul Tarafder** — [GitHub profile](https://github.com/RahulTarafder)
150
+
151
+
152
+ ## Contributors
153
+
154
+ Thanks to everyone who contributes issues, code, documentation, testing, and feedback. Contributors are recognized through the repository's contribution history. To contribute, see [`CONTRIBUTING.md`](./CONTRIBUTING.md).
155
+
156
+
157
+ ## License
158
+
159
+ Released under the **MIT License**. See [`LICENSE`](./LICENSE) for details.