soundlink 1.1.0 → 1.2.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,5 +1,17 @@
1
1
  # soundlink
2
2
 
3
+ ## 1.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#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))
8
+
9
+ ## 1.1.1
10
+
11
+ ### Patch Changes
12
+
13
+ - [`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.
14
+
3
15
  ## 1.1.0
4
16
 
5
17
  ### Minor Changes
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:** `1.0.0` on npm was an empty placeholder. Use **`>=1.1.0`** for the SDK. Write surface (create / budget / stop / tiers) ships in **`1.2.0`**.
12
12
 
13
13
  Requires **Node.js 18+** (native `fetch`). Works in Edge Runtime when `fetch` is available.
14
14
 
@@ -44,6 +44,8 @@ The SDK sends it in the `x-api-key` header on every request.
44
44
 
45
45
  Your organization is determined from the key. Do not send Firebase Bearer tokens on the Public API host.
46
46
 
47
+ Write methods require the `campaigns:write` scope and an `Idempotency-Key` (passed as `idempotencyKey` on the method options).
48
+
47
49
  ## Response pattern
48
50
 
49
51
  Every method returns:
@@ -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
297
  "x-api-key": this.options.apiKey,
250
- Accept: "application/json"
298
+ Accept: "application/json",
299
+ ...extra
251
300
  };
252
301
  }
253
302
  async requestJson(url, init) {
@@ -377,15 +426,91 @@ var PingResource = class {
377
426
  this.http = http;
378
427
  }
379
428
  http;
429
+ /**
430
+ * Verify connectivity and API key authentication.
431
+ *
432
+ * Accepts any valid v1 key scope. Does not require `campaigns:read` or `metrics:read`.
433
+ *
434
+ * @returns `{ data: { status: 'ok' }, error: null }` on success.
435
+ *
436
+ * @example
437
+ * ```ts
438
+ * const { data, error, meta } = await soundlink.ping();
439
+ * ```
440
+ */
380
441
  ping() {
381
442
  return this.http.get({ path: "/ping" });
382
443
  }
383
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
+ };
384
494
  var CampaignsResource = class {
385
495
  constructor(http) {
386
496
  this.http = http;
497
+ this.tiers = new CampaignTiersResource(http);
387
498
  }
388
499
  http;
500
+ /** Tier allocation for wallet campaigns (`generation: 3`). */
501
+ tiers;
502
+ /**
503
+ * List campaigns for the authenticated organization.
504
+ *
505
+ * Maps to `GET /v1/campaigns`. Max `pageSize` is **100**. Requires `campaigns:read`.
506
+ *
507
+ * @param params - Pagination and sort options.
508
+ *
509
+ * @example
510
+ * ```ts
511
+ * const { data, error } = await soundlink.campaigns.list({ page: 1, pageSize: 100 });
512
+ * ```
513
+ */
389
514
  list(params = {}) {
390
515
  return this.http.get({
391
516
  path: "/campaigns",
@@ -397,11 +522,96 @@ var CampaignsResource = class {
397
522
  }
398
523
  });
399
524
  }
525
+ /**
526
+ * Fetch full details for a single campaign.
527
+ *
528
+ * Maps to `GET /v1/campaigns/{campaignId}`. Requires `campaigns:read`.
529
+ *
530
+ * @param campaignId - Campaign identifier returned by {@link CampaignsResource.list}.
531
+ */
400
532
  get(campaignId) {
401
533
  return this.http.get({
402
534
  path: `/campaigns/${encodeURIComponent(campaignId)}`
403
535
  });
404
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
+ }
601
+ /**
602
+ * Async iterator over every campaign across all pages.
603
+ *
604
+ * Stops silently if a page request returns an error.
605
+ *
606
+ * @param params - Same as {@link CampaignsResource.list} except `page` is managed automatically.
607
+ *
608
+ * @example
609
+ * ```ts
610
+ * for await (const campaign of soundlink.campaigns.listAll({ pageSize: 100 })) {
611
+ * console.log(campaign.campaignId);
612
+ * }
613
+ * ```
614
+ */
405
615
  async *listAll(params = {}) {
406
616
  let page = 1;
407
617
  let totalPages = 1;
@@ -425,8 +635,27 @@ var MetricsResource = class {
425
635
  this.engagement = new EngagementMetricsResource(http);
426
636
  }
427
637
  http;
638
+ /** Per-day country breakdown and JSONL export. */
428
639
  breakdown;
640
+ /** Per-track engagement JSONL export. */
429
641
  engagement;
642
+ /**
643
+ * Campaign-level metric totals for a date range.
644
+ *
645
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/overview`.
646
+ * Aggregates across all countries — use {@link BreakdownMetricsResource.list} for daily rows.
647
+ *
648
+ * @param campaignId - Campaign identifier.
649
+ * @param params - Inclusive `YYYY-MM-DD` date range. Omit for API defaults.
650
+ *
651
+ * @example
652
+ * ```ts
653
+ * const { data } = await soundlink.metrics.overview(campaignId, {
654
+ * startDate: '2026-01-01',
655
+ * endDate: '2026-03-31',
656
+ * });
657
+ * ```
658
+ */
430
659
  overview(campaignId, params = {}) {
431
660
  return this.http.get({
432
661
  path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/overview`,
@@ -450,7 +679,21 @@ var BreakdownMetricsResource = class {
450
679
  );
451
680
  }
452
681
  http;
682
+ /**
683
+ * Stream full breakdown export as JSONL.
684
+ *
685
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown/export`.
686
+ */
453
687
  export;
688
+ /**
689
+ * Paginated per-day, per-country breakdown rows.
690
+ *
691
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/breakdown`.
692
+ * Max `pageSize` is **500** (default 50).
693
+ *
694
+ * @param campaignId - Campaign identifier.
695
+ * @param params - Date range, pagination, and sort options.
696
+ */
454
697
  list(campaignId, params = {}) {
455
698
  return this.http.get({
456
699
  path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/breakdown`,
@@ -479,32 +722,34 @@ var EngagementMetricsResource = class {
479
722
  );
480
723
  }
481
724
  http;
725
+ /**
726
+ * Stream full engagement export as JSONL.
727
+ *
728
+ * Maps to `GET /v1/campaigns/{campaignId}/metrics/engagement/export`.
729
+ */
482
730
  export;
483
- list(campaignId, params = {}) {
484
- return this.http.get({
485
- path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/engagement`,
486
- query: {
487
- startDate: params.startDate,
488
- endDate: params.endDate,
489
- page: params.page,
490
- pageSize: params.pageSize,
491
- sortBy: params.sortBy,
492
- sortOrder: params.sortOrder,
493
- engagementContext: params.engagementContext
494
- }
495
- });
496
- }
497
731
  };
498
732
 
499
733
  // src/client/soundlink.ts
500
734
  var Soundlink = class {
735
+ /** Verify connectivity and authentication. Maps to `GET /v1/ping`. */
501
736
  ping;
737
+ /** Growth strategy catalog. Requires `campaigns:read` scope. */
738
+ strategies;
739
+ /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
502
740
  campaigns;
741
+ /** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
503
742
  metrics;
743
+ /**
744
+ * Create a Soundlink client.
745
+ *
746
+ * @param options - API key string (`sk_*`) or {@link SoundlinkClientOptions}.
747
+ */
504
748
  constructor(options) {
505
749
  const http = new HttpClient(options);
506
750
  const pingResource = new PingResource(http);
507
751
  this.ping = pingResource.ping.bind(pingResource);
752
+ this.strategies = new StrategiesResource(http);
508
753
  this.campaigns = new CampaignsResource(http);
509
754
  this.metrics = new MetricsResource(http);
510
755
  }