soundlink 1.1.1 → 2.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/CHANGELOG.md CHANGED
@@ -1,10 +1,22 @@
1
1
  # soundlink
2
2
 
3
+ ## 2.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - [#SOU-6455](https://linear.app/getsoundlink/issue/SOU-6455) — **Breaking:** the SDK sends `Authorization: Bearer sk_...` instead of the deprecated `x-api-key` header. Constructor API is unchanged (`new Soundlink({ apiKey })`). Migrate by upgrading the package; no code changes required unless you were reading request headers in tests or proxies that expected `x-api-key`.
8
+
9
+ ## 1.2.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#3](https://github.com/Fan-ID/lib/pull/3) [`279a718`](https://github.com/Fan-ID/lib/commit/279a718eb13c19d57e6f0db2e3a9fbb29af0b0a8) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add Public API write surface: strategies catalog, campaign create / stop / budget / tiers with `Idempotency-Key`, `generation` on campaign types, expanded error codes. Remove unshipped `metrics.engagement.list`. Sync OpenAPI to the current v1 contract. ([SOU-6003](https://linear.app/getsoundlink/issue/SOU-6003))
14
+
3
15
  ## 1.1.1
4
16
 
5
17
  ### Patch Changes
6
18
 
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.
19
+ - [`57ed16a`](https://github.com/Fan-ID/lib/commit/57ed16a090e91297845608935cbec8c074d6e15c) Thanks [@jotanarciso](https://github.com/jotanarciso)! - Add TSDoc comments on public methods and types for IDE hover hints and IntelliSense.
8
20
 
9
21
  ## 1.1.0
10
22
 
package/README.md CHANGED
@@ -8,7 +8,7 @@ Official TypeScript SDK for the [Soundlink Public API](https://docs.getsoundlink
8
8
  npm install soundlink
9
9
  ```
10
10
 
11
- > **Version note:** `1.0.0` on npm was an empty placeholder. **`1.1.0`** is the first official SDK release.
11
+ > **Version note:** `2.x` is the current line. `1.x` sent the deprecated `x-api-key` header — upgrade to `2.0.0+` for `Authorization: Bearer`. Write surface (create / budget / stop / tiers) shipped in `1.2.0` and remains in `2.x`.
12
12
 
13
13
  Requires **Node.js 18+** (native `fetch`). Works in Edge Runtime when `fetch` is available.
14
14
 
@@ -40,9 +40,11 @@ const soundlink = new Soundlink('sk_your_prefix_your_secret');
40
40
  ## Authentication
41
41
 
42
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.
43
+ The SDK sends it as `Authorization: Bearer sk_...` on every request.
44
44
 
45
- Your organization is determined from the key. Do not send Firebase Bearer tokens on the Public API host.
45
+ Your organization is determined from the key. Do not send Firebase ID tokens on the Public API host.
46
+
47
+ Write methods require the `campaigns:write` scope and an `Idempotency-Key` (passed as `idempotencyKey` on the method options).
46
48
 
47
49
  ## Response pattern
48
50
 
@@ -82,11 +84,75 @@ const { data, error } = await soundlink.campaigns.list({
82
84
  });
83
85
 
84
86
  const { data: campaign } = await soundlink.campaigns.get('camp_abc123');
87
+ // campaign.generation === 3 → wallet (writable)
85
88
 
86
89
  // Async iterator across all pages
87
90
  for await (const item of soundlink.campaigns.listAll({ pageSize: 100 })) {
88
- console.log(item.campaignId);
91
+ console.log(item.campaignId, item.generation);
92
+ }
93
+ ```
94
+
95
+ ### Create, budget, tiers, stop (wallet / `generation: 3`)
96
+
97
+ ```typescript
98
+ const { data: strategies } = await soundlink.strategies.list();
99
+
100
+ const { data: created, error: createError } = await soundlink.campaigns.create(
101
+ {
102
+ spotifyUrl: 'https://open.spotify.com/track/...',
103
+ dailyBudget: 20,
104
+ durationDays: 7,
105
+ genre: 'Pop',
106
+ strategyType: 'maximum_growth',
107
+ },
108
+ { idempotencyKey: 'create-mytrack-01' },
109
+ );
110
+
111
+ if (createError || !created) {
112
+ console.error(createError);
113
+ return;
114
+ }
115
+
116
+ await soundlink.campaigns.increaseBudget(
117
+ created.campaignId,
118
+ { amount: 50, mode: 'current_and_renewals' },
119
+ { idempotencyKey: 'budget-inc-01' },
120
+ );
121
+
122
+ // GET returns `tierId`; PATCH expects the same value as `targetingTierId`
123
+ const { data: tiers } = await soundlink.campaigns.tiers.get(created.campaignId);
124
+ if (!tiers) {
125
+ return;
89
126
  }
127
+ await soundlink.campaigns.tiers.update(created.campaignId, {
128
+ items: tiers.tiers.map((tier) => ({
129
+ targetingTierId: tier.tierId,
130
+ isEnabled: tier.isEnabled,
131
+ newAllocationPercent: tier.allocationPercent,
132
+ })),
133
+ });
134
+
135
+ await soundlink.campaigns.stop(created.campaignId, {
136
+ idempotencyKey: 'stop-01',
137
+ });
138
+ ```
139
+
140
+ Custom strategy create (requires `tierTargeting`):
141
+
142
+ ```typescript
143
+ const { data: created } = await soundlink.campaigns.create(
144
+ {
145
+ spotifyUrl: 'https://open.spotify.com/track/...',
146
+ dailyBudget: 20,
147
+ durationDays: 7,
148
+ genre: 'Pop',
149
+ strategyType: 'custom',
150
+ tierTargeting: {
151
+ customTiers: [{ name: 'US focus', countries: ['US'], percentBudget: 100 }],
152
+ },
153
+ },
154
+ { idempotencyKey: 'create-custom-01' },
155
+ );
90
156
  ```
91
157
 
92
158
  ## Metrics
@@ -145,33 +211,38 @@ const soundlink = new Soundlink({
145
211
  apiKey: process.env.SOUNDLINK_API_KEY!,
146
212
  baseUrl: 'https://api.getsoundlink.com', // default
147
213
  timeout: 30_000, // ms, default
148
- maxRetries: 2, // retries on 429/5xx, default
214
+ maxRetries: 2, // retries on 429/5xx (same Idempotency-Key on writes), default
149
215
  fetch: customFetch, // optional, for Edge/tests
150
216
  });
151
217
  ```
152
218
 
153
219
  ## Error codes
154
220
 
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.
221
+ | Code | Typical HTTP |
222
+ | -------------------------- | ------------ |
223
+ | `invalid_api_key` | 401 |
224
+ | `api_key_revoked` | 401 |
225
+ | `api_key_expired` | 401 |
226
+ | `mixed_credentials` | 401 |
227
+ | `insufficient_scope` | 403 |
228
+ | `wallet_not_enabled` | 403 |
229
+ | `not_found` | 404 |
230
+ | `campaign_not_found` | 404 |
231
+ | `invalid_request` | 400 |
232
+ | `invalid_query_parameter` | 400 |
233
+ | `invalid_date_range` | 400 |
234
+ | `page_size_exceeded` | 400 |
235
+ | `insufficient_credit` | 402 |
236
+ | `idempotency_key_conflict` | 409 |
237
+ | `tier_update_cooldown` | 409 |
238
+ | `rate_limit_exceeded` | 429 |
239
+ | `internal_error` | 500 |
240
+
241
+ Include `meta.requestId` (or `error.requestId`) when contacting Soundlink support. On `402 insufficient_credit`, check `error.details` for `available` / `required` wallet amounts.
171
242
 
172
243
  ## API reference
173
244
 
174
- Full endpoint documentation: [getsoundlink.com/docs](https://getsoundlink.com/docs).
245
+ Full endpoint documentation: [docs.getsoundlink.com](https://docs.getsoundlink.com).
175
246
 
176
247
  OpenAPI spec shipped with this package: `openapi/soundlink-public-api-v1.yaml`.
177
248
 
@@ -193,19 +264,27 @@ SOUNDLINK_API_KEY=sk_your_prefix_your_secret npm run test:live
193
264
  npm run test:live -- sk_your_prefix_your_secret
194
265
  ```
195
266
 
196
- The script runs: `ping` → `campaigns.list` → `campaigns.get` → `metrics.overview` (best effort).
267
+ The script runs: `ping` → `strategies.list` → `campaigns.list` (checks `generation`) → `campaigns.get` → `metrics.overview` (best effort).
268
+
269
+ Opt-in write smoke (debits wallet — use a sandbox org):
270
+
271
+ ```bash
272
+ SOUNDLINK_LIVE_WRITE=1 \
273
+ SOUNDLINK_LIVE_SPOTIFY_URL='https://open.spotify.com/track/...' \
274
+ SOUNDLINK_API_KEY=sk_... \
275
+ npm run test:live
276
+ ```
197
277
 
198
278
  ## Roadmap
199
279
 
200
- - `metrics.engagement.list` — spec-ready; backend route pending
201
- - `campaigns.create` — when `campaigns:write` scope opens in v2
280
+ - Video import helpers (`videos:write`) — when prioritized
202
281
  - Webhook helpers — when Public API webhooks ship
203
282
 
204
283
  ## Releases
205
284
 
206
285
  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
286
 
208
- See [CONTRIBUTING.md](./CONTRIBUTING.md#release-process) for the full flow.
287
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full flow.
209
288
 
210
289
  ## Contributing
211
290
 
@@ -25,12 +25,14 @@ function isApiEnvelopeSuccess(body) {
25
25
  return "data" in record && typeof record.meta === "object" && record.meta !== null;
26
26
  }
27
27
  function toApiError(envelope, status, retryAfter) {
28
+ const { details } = envelope.error;
28
29
  return {
29
30
  code: envelope.error.code,
30
31
  message: envelope.error.message,
31
32
  status,
32
33
  requestId: envelope.meta.requestId,
33
- ...retryAfter !== void 0 ? { retryAfter } : {}
34
+ ...retryAfter !== void 0 ? { retryAfter } : {},
35
+ ...details !== void 0 ? { details } : {}
34
36
  };
35
37
  }
36
38
  function successResponse(data, meta) {
@@ -206,6 +208,36 @@ var HttpClient = class {
206
208
  headers: this.buildHeaders()
207
209
  });
208
210
  }
211
+ async post({
212
+ path,
213
+ body,
214
+ query,
215
+ headers,
216
+ idempotencyKey
217
+ }) {
218
+ return this.mutateJson("POST", {
219
+ path,
220
+ body,
221
+ query,
222
+ headers,
223
+ idempotencyKey
224
+ });
225
+ }
226
+ async patch({
227
+ path,
228
+ body,
229
+ query,
230
+ headers,
231
+ idempotencyKey
232
+ }) {
233
+ return this.mutateJson("PATCH", {
234
+ path,
235
+ body,
236
+ query,
237
+ headers,
238
+ idempotencyKey
239
+ });
240
+ }
209
241
  async getJsonl({
210
242
  path,
211
243
  query,
@@ -244,10 +276,27 @@ var HttpClient = class {
244
276
  error: null
245
277
  };
246
278
  }
247
- buildHeaders() {
279
+ mutateJson(method, { path, body, query, headers, idempotencyKey }) {
280
+ const url = joinUrl(
281
+ this.options.baseUrl,
282
+ `${API_VERSION_PREFIX}${path}${buildQueryString(query ?? {})}`
283
+ );
284
+ const requestHeaders = this.buildHeaders({
285
+ ...body !== void 0 ? { "Content-Type": "application/json" } : {},
286
+ ...idempotencyKey !== void 0 ? { "Idempotency-Key": idempotencyKey } : {},
287
+ ...headers
288
+ });
289
+ return this.requestJson(url, {
290
+ method,
291
+ headers: requestHeaders,
292
+ ...body !== void 0 ? { body: JSON.stringify(body) } : {}
293
+ });
294
+ }
295
+ buildHeaders(extra = {}) {
248
296
  return {
249
- "x-api-key": this.options.apiKey,
250
- Accept: "application/json"
297
+ Authorization: `Bearer ${this.options.apiKey}`,
298
+ Accept: "application/json",
299
+ ...extra
251
300
  };
252
301
  }
253
302
  async requestJson(url, init) {
@@ -393,15 +442,67 @@ var PingResource = class {
393
442
  return this.http.get({ path: "/ping" });
394
443
  }
395
444
  };
445
+ var StrategiesResource = class {
446
+ constructor(http) {
447
+ this.http = http;
448
+ }
449
+ http;
450
+ /**
451
+ * List growth strategies available for wallet campaign create.
452
+ *
453
+ * Maps to `GET /v1/strategies`.
454
+ *
455
+ * @example
456
+ * ```ts
457
+ * const { data } = await soundlink.strategies.list();
458
+ * ```
459
+ */
460
+ list() {
461
+ return this.http.get({ path: "/strategies" });
462
+ }
463
+ };
464
+ var CampaignTiersResource = class {
465
+ constructor(http) {
466
+ this.http = http;
467
+ }
468
+ http;
469
+ /**
470
+ * Get current tier allocation for a wallet campaign.
471
+ *
472
+ * Maps to `GET /v1/campaigns/{campaignId}/tiers`. Wallet campaigns only (`generation: 3`).
473
+ */
474
+ get(campaignId) {
475
+ return this.http.get({
476
+ path: `/campaigns/${encodeURIComponent(campaignId)}/tiers`
477
+ });
478
+ }
479
+ /**
480
+ * Update tier enablement and budget shares.
481
+ *
482
+ * Maps to `PATCH /v1/campaigns/{campaignId}/tiers`. Requires `campaigns:write`.
483
+ * Allocation percents across items must sum to 100.
484
+ * Use each tier's `tierId` from {@link CampaignTiersResource.get} as `targetingTierId`.
485
+ * Does not require an `Idempotency-Key` (unlike create / stop / budget).
486
+ */
487
+ update(campaignId, body) {
488
+ return this.http.patch({
489
+ path: `/campaigns/${encodeURIComponent(campaignId)}/tiers`,
490
+ body
491
+ });
492
+ }
493
+ };
396
494
  var CampaignsResource = class {
397
495
  constructor(http) {
398
496
  this.http = http;
497
+ this.tiers = new CampaignTiersResource(http);
399
498
  }
400
499
  http;
500
+ /** Tier allocation for wallet campaigns (`generation: 3`). */
501
+ tiers;
401
502
  /**
402
503
  * List campaigns for the authenticated organization.
403
504
  *
404
- * Maps to `GET /v1/campaigns`. Max `pageSize` is **100**.
505
+ * Maps to `GET /v1/campaigns`. Max `pageSize` is **100**. Requires `campaigns:read`.
405
506
  *
406
507
  * @param params - Pagination and sort options.
407
508
  *
@@ -424,7 +525,7 @@ var CampaignsResource = class {
424
525
  /**
425
526
  * Fetch full details for a single campaign.
426
527
  *
427
- * Maps to `GET /v1/campaigns/{campaignId}`.
528
+ * Maps to `GET /v1/campaigns/{campaignId}`. Requires `campaigns:read`.
428
529
  *
429
530
  * @param campaignId - Campaign identifier returned by {@link CampaignsResource.list}.
430
531
  */
@@ -433,6 +534,70 @@ var CampaignsResource = class {
433
534
  path: `/campaigns/${encodeURIComponent(campaignId)}`
434
535
  });
435
536
  }
537
+ /**
538
+ * Create a wallet-funded campaign.
539
+ *
540
+ * Maps to `POST /v1/campaigns`. Requires `campaigns:write` and `Idempotency-Key`.
541
+ *
542
+ * @example
543
+ * ```ts
544
+ * const { data, error } = await soundlink.campaigns.create(
545
+ * {
546
+ * spotifyUrl: 'https://open.spotify.com/track/...',
547
+ * dailyBudget: 20,
548
+ * durationDays: 7,
549
+ * genre: 'Pop',
550
+ * strategyType: 'maximum_growth',
551
+ * },
552
+ * { idempotencyKey: 'create-mytrack-01' },
553
+ * );
554
+ * ```
555
+ */
556
+ create(body, options) {
557
+ return this.http.post({
558
+ path: "/campaigns",
559
+ body,
560
+ idempotencyKey: options.idempotencyKey
561
+ });
562
+ }
563
+ /**
564
+ * Stop a wallet campaign and refund unspent budget.
565
+ *
566
+ * Maps to `POST /v1/campaigns/{campaignId}/stop`. Requires `campaigns:write`
567
+ * and `Idempotency-Key`. Wallet campaigns only (`generation: 3`).
568
+ */
569
+ stop(campaignId, options) {
570
+ return this.http.post({
571
+ path: `/campaigns/${encodeURIComponent(campaignId)}/stop`,
572
+ idempotencyKey: options.idempotencyKey
573
+ });
574
+ }
575
+ /**
576
+ * Increase wallet campaign budget.
577
+ *
578
+ * Maps to `POST /v1/campaigns/{campaignId}/budget/increase`.
579
+ * Requires `campaigns:write` and `Idempotency-Key`. Wallet only (`generation: 3`).
580
+ */
581
+ increaseBudget(campaignId, body, options) {
582
+ return this.http.post({
583
+ path: `/campaigns/${encodeURIComponent(campaignId)}/budget/increase`,
584
+ body,
585
+ idempotencyKey: options.idempotencyKey
586
+ });
587
+ }
588
+ /**
589
+ * Decrease wallet campaign daily budget.
590
+ *
591
+ * Maps to `POST /v1/campaigns/{campaignId}/budget/decrease`.
592
+ * Requires `campaigns:write` and `Idempotency-Key`. Wallet only (`generation: 3`).
593
+ */
594
+ decreaseBudget(campaignId, body, options) {
595
+ return this.http.post({
596
+ path: `/campaigns/${encodeURIComponent(campaignId)}/budget/decrease`,
597
+ body,
598
+ idempotencyKey: options.idempotencyKey
599
+ });
600
+ }
436
601
  /**
437
602
  * Async iterator over every campaign across all pages.
438
603
  *
@@ -472,7 +637,7 @@ var MetricsResource = class {
472
637
  http;
473
638
  /** Per-day country breakdown and JSONL export. */
474
639
  breakdown;
475
- /** Per-track engagement breakdown and JSONL export. */
640
+ /** Per-track engagement JSONL export. */
476
641
  engagement;
477
642
  /**
478
643
  * Campaign-level metric totals for a date range.
@@ -563,36 +728,15 @@ var EngagementMetricsResource = class {
563
728
  * Maps to `GET /v1/campaigns/{campaignId}/metrics/engagement/export`.
564
729
  */
565
730
  export;
566
- /**
567
- * Paginated per-day, per-track engagement rows.
568
- *
569
- * Maps to `GET /v1/campaigns/{campaignId}/metrics/engagement`.
570
- * Max `pageSize` is **500** (default 50).
571
- *
572
- * @param campaignId - Campaign identifier.
573
- * @param params - Date range, pagination, sort, and optional `engagementContext` filter.
574
- */
575
- list(campaignId, params = {}) {
576
- return this.http.get({
577
- path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/engagement`,
578
- query: {
579
- startDate: params.startDate,
580
- endDate: params.endDate,
581
- page: params.page,
582
- pageSize: params.pageSize,
583
- sortBy: params.sortBy,
584
- sortOrder: params.sortOrder,
585
- engagementContext: params.engagementContext
586
- }
587
- });
588
- }
589
731
  };
590
732
 
591
733
  // src/client/soundlink.ts
592
734
  var Soundlink = class {
593
735
  /** Verify connectivity and authentication. Maps to `GET /v1/ping`. */
594
736
  ping;
595
- /** List and fetch campaigns. Requires `campaigns:read` scope. */
737
+ /** Growth strategy catalog. Requires `campaigns:read` scope. */
738
+ strategies;
739
+ /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
596
740
  campaigns;
597
741
  /** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
598
742
  metrics;
@@ -605,6 +749,7 @@ var Soundlink = class {
605
749
  const http = new HttpClient(options);
606
750
  const pingResource = new PingResource(http);
607
751
  this.ping = pingResource.ping.bind(pingResource);
752
+ this.strategies = new StrategiesResource(http);
608
753
  this.campaigns = new CampaignsResource(http);
609
754
  this.metrics = new MetricsResource(http);
610
755
  }