soundlink 1.0.0 → 1.1.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/CHANGELOG.md ADDED
@@ -0,0 +1,13 @@
1
+ # soundlink
2
+
3
+ ## 1.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - First official TypeScript SDK release for the Soundlink Public API
8
+ - Campaigns: list, get, and `listAll` pagination helper
9
+ - Metrics: overview, breakdown, engagement (spec-ready), and JSONL exports with stream + `collect()`
10
+ - `{ data, error, meta }` response pattern on all methods
11
+ - Node.js 18+ and Edge Runtime support (native `fetch`)
12
+
13
+ > **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