soundlink 1.0.0 → 1.1.1
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/CHANGELOG.md +19 -0
- package/LICENSE +21 -0
- package/README.md +216 -0
- package/dist/cjs/index.cjs +627 -0
- package/dist/cjs/index.cjs.map +1 -0
- package/dist/esm/index.d.ts +536 -0
- package/dist/esm/index.js +613 -0
- package/dist/esm/index.js.map +1 -0
- package/openapi/soundlink-public-api-v1.yaml +1289 -0
- package/package.json +88 -7
- package/index.js +0 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# soundlink
|
|
2
|
+
|
|
3
|
+
## 1.1.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`57ed16a`](https://github.com/Fan-ID/lib-sdk/commit/57ed16a090e91297845608935cbec8c074d6e15c) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add TSDoc comments on public methods and types for IDE hover hints and IntelliSense.
|
|
8
|
+
|
|
9
|
+
## 1.1.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- First official TypeScript SDK release for the Soundlink Public API
|
|
14
|
+
- Campaigns: list, get, and `listAll` pagination helper
|
|
15
|
+
- Metrics: overview, breakdown, engagement (spec-ready), and JSONL exports with stream + `collect()`
|
|
16
|
+
- `{ data, error, meta }` response pattern on all methods
|
|
17
|
+
- Node.js 18+ and Edge Runtime support (native `fetch`)
|
|
18
|
+
|
|
19
|
+
> **Note:** `1.0.0` on npm was an empty placeholder. Use `>=1.1.0` for the SDK.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Soundlink
|
|
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
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# soundlink
|
|
2
|
+
|
|
3
|
+
Official TypeScript SDK for the [Soundlink Public API](https://docs.getsoundlink.com).
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install soundlink
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
> **Version note:** `1.0.0` on npm was an empty placeholder. **`1.1.0`** is the first official SDK release.
|
|
12
|
+
|
|
13
|
+
Requires **Node.js 18+** (native `fetch`). Works in Edge Runtime when `fetch` is available.
|
|
14
|
+
|
|
15
|
+
## Quickstart
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { Soundlink } from 'soundlink';
|
|
19
|
+
|
|
20
|
+
const soundlink = new Soundlink({
|
|
21
|
+
apiKey: process.env.SOUNDLINK_API_KEY!,
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
// Verify your key
|
|
25
|
+
const { data, error, meta } = await soundlink.ping();
|
|
26
|
+
if (error) {
|
|
27
|
+
console.error(error.message, meta?.requestId);
|
|
28
|
+
process.exit(1);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
console.log(data?.status); // "ok"
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
You can also pass the API key directly:
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
const soundlink = new Soundlink('sk_your_prefix_your_secret');
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Authentication
|
|
41
|
+
|
|
42
|
+
Pass your Soundlink API key (`sk_<prefix>_<secret>`) via the client constructor.
|
|
43
|
+
The SDK sends it in the `x-api-key` header on every request.
|
|
44
|
+
|
|
45
|
+
Your organization is determined from the key. Do not send Firebase Bearer tokens on the Public API host.
|
|
46
|
+
|
|
47
|
+
## Response pattern
|
|
48
|
+
|
|
49
|
+
Every method returns:
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
type ApiResponse<T> = {
|
|
53
|
+
data: T | null;
|
|
54
|
+
error: ApiError | null;
|
|
55
|
+
meta?: { requestId: string };
|
|
56
|
+
};
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Example:
|
|
60
|
+
|
|
61
|
+
```typescript
|
|
62
|
+
const { data, error } = await soundlink.campaigns.list({ page: 1, pageSize: 100 });
|
|
63
|
+
|
|
64
|
+
if (error) {
|
|
65
|
+
console.error(error.code, error.message, error.requestId);
|
|
66
|
+
return;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
console.log(data.items);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
HTTP errors from the API are **never thrown**. Exceptions are reserved for SDK configuration, parsing, and unexpected transport failures.
|
|
73
|
+
|
|
74
|
+
## Campaigns
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
const { data, error } = await soundlink.campaigns.list({
|
|
78
|
+
page: 1,
|
|
79
|
+
pageSize: 100,
|
|
80
|
+
sortBy: 'createdAt',
|
|
81
|
+
sortOrder: 'desc',
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
const { data: campaign } = await soundlink.campaigns.get('camp_abc123');
|
|
85
|
+
|
|
86
|
+
// Async iterator across all pages
|
|
87
|
+
for await (const item of soundlink.campaigns.listAll({ pageSize: 100 })) {
|
|
88
|
+
console.log(item.campaignId);
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Metrics
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
const { data: overview } = await soundlink.metrics.overview('camp_abc123', {
|
|
96
|
+
startDate: '2026-01-01',
|
|
97
|
+
endDate: '2026-03-31',
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
const { data: breakdown } = await soundlink.metrics.breakdown.list('camp_abc123', {
|
|
101
|
+
page: 1,
|
|
102
|
+
pageSize: 50,
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### JSONL exports (streaming)
|
|
107
|
+
|
|
108
|
+
Export endpoints stream newline-delimited JSON. Use `for await` for pipelines:
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
const { data: stream, error } = await soundlink.metrics.breakdown.export(
|
|
112
|
+
'camp_abc123',
|
|
113
|
+
{
|
|
114
|
+
startDate: '2026-01-01',
|
|
115
|
+
endDate: '2026-03-31',
|
|
116
|
+
},
|
|
117
|
+
);
|
|
118
|
+
|
|
119
|
+
if (error || !stream) return;
|
|
120
|
+
|
|
121
|
+
for await (const row of stream) {
|
|
122
|
+
await warehouse.insert(row);
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Collect all rows into memory when the dataset is small:
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
const { data } = await soundlink.metrics.breakdown.export.collect('camp_abc123');
|
|
130
|
+
console.log(data?.rowCount, data?.rows);
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Engagement exports work the same way:
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
const { data: stream } = await soundlink.metrics.engagement.export('camp_abc123', {
|
|
137
|
+
engagementContext: 'catalog',
|
|
138
|
+
});
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Configuration
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
const soundlink = new Soundlink({
|
|
145
|
+
apiKey: process.env.SOUNDLINK_API_KEY!,
|
|
146
|
+
baseUrl: 'https://api.getsoundlink.com', // default
|
|
147
|
+
timeout: 30_000, // ms, default
|
|
148
|
+
maxRetries: 2, // retries on 429/5xx, default
|
|
149
|
+
fetch: customFetch, // optional, for Edge/tests
|
|
150
|
+
});
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Error codes
|
|
154
|
+
|
|
155
|
+
| Code | Typical HTTP |
|
|
156
|
+
| ------------------------- | ------------ |
|
|
157
|
+
| `invalid_api_key` | 401 |
|
|
158
|
+
| `api_key_revoked` | 401 |
|
|
159
|
+
| `api_key_expired` | 401 |
|
|
160
|
+
| `mixed_credentials` | 401 |
|
|
161
|
+
| `insufficient_scope` | 403 |
|
|
162
|
+
| `not_found` | 404 |
|
|
163
|
+
| `campaign_not_found` | 404 |
|
|
164
|
+
| `invalid_query_parameter` | 400 |
|
|
165
|
+
| `invalid_date_range` | 400 |
|
|
166
|
+
| `page_size_exceeded` | 400 |
|
|
167
|
+
| `rate_limit_exceeded` | 429 |
|
|
168
|
+
| `internal_error` | 500 |
|
|
169
|
+
|
|
170
|
+
Include `meta.requestId` (or `error.requestId`) when contacting Soundlink support.
|
|
171
|
+
|
|
172
|
+
## API reference
|
|
173
|
+
|
|
174
|
+
Full endpoint documentation: [getsoundlink.com/docs](https://getsoundlink.com/docs).
|
|
175
|
+
|
|
176
|
+
OpenAPI spec shipped with this package: `openapi/soundlink-public-api-v1.yaml`.
|
|
177
|
+
|
|
178
|
+
## Test before publish
|
|
179
|
+
|
|
180
|
+
Smoke test against the live API (uses the local SDK source, not npm):
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
# Option A — .env file
|
|
184
|
+
cp .env.example .env
|
|
185
|
+
# edit .env → SOUNDLINK_API_KEY=sk_...
|
|
186
|
+
|
|
187
|
+
npm run test:live
|
|
188
|
+
|
|
189
|
+
# Option B — inline
|
|
190
|
+
SOUNDLINK_API_KEY=sk_your_prefix_your_secret npm run test:live
|
|
191
|
+
|
|
192
|
+
# Option C — CLI argument
|
|
193
|
+
npm run test:live -- sk_your_prefix_your_secret
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The script runs: `ping` → `campaigns.list` → `campaigns.get` → `metrics.overview` (best effort).
|
|
197
|
+
|
|
198
|
+
## Roadmap
|
|
199
|
+
|
|
200
|
+
- `metrics.engagement.list` — spec-ready; backend route pending
|
|
201
|
+
- `campaigns.create` — when `campaigns:write` scope opens in v2
|
|
202
|
+
- Webhook helpers — when Public API webhooks ship
|
|
203
|
+
|
|
204
|
+
## Releases
|
|
205
|
+
|
|
206
|
+
GitHub Releases are created automatically when a **Version packages** PR is merged. Release notes come from `CHANGELOG.md`, with PR/issue links when referenced in changesets.
|
|
207
|
+
|
|
208
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md#release-process) for the full flow.
|
|
209
|
+
|
|
210
|
+
## Contributing
|
|
211
|
+
|
|
212
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
213
|
+
|
|
214
|
+
## License
|
|
215
|
+
|
|
216
|
+
MIT
|