soundlink 2.7.0 → 2.9.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.
@@ -170,6 +170,11 @@ paths:
170
170
  Returns the Meta pixels configured for the organization. Access tokens
171
171
  are never returned. Today each entry has `platform: meta`.
172
172
 
173
+ Each pixel includes `isDefault` and send-health fields (`status`,
174
+ `lastErrorCode`, `errorSince`). `isDefault` only affects the app's
175
+ soundlink create picker; this API never applies a default pixel on
176
+ create.
177
+
173
178
  Requires `pixels:read`. Organizations without custom pixels enabled
174
179
  get `403 custom_pixel_not_enabled`.
175
180
  tags: [Pixels]
@@ -190,6 +195,10 @@ paths:
190
195
  pixels:
191
196
  - id: '1234567890123456'
192
197
  platform: meta
198
+ isDefault: true
199
+ status: ok
200
+ lastErrorCode: null
201
+ errorSince: null
193
202
  meta:
194
203
  requestId: 550e8400-e29b-41d4-a716-446655440000
195
204
  '401': { $ref: '#/components/responses/Unauthorized' }
@@ -202,12 +211,13 @@ paths:
202
211
  operationId: updatePixel
203
212
  summary: Save an organization pixel
204
213
  description: |
205
- Saves the Conversions API access token for `pixelId`. The same call
206
- creates the pixel or rotates its token, and both return `200`:
214
+ Saves the Conversions API access token and/or default flag for
215
+ `pixelId`. The same call creates the pixel or rotates its token, and
216
+ both return `200`:
207
217
 
208
- - No Meta pixel yet: the pixel is saved.
218
+ - No Meta pixel yet: the pixel is saved (`accessToken` required).
209
219
  - `pixelId` matches a Meta pixel the organization already has: its
210
- access token is replaced.
220
+ access token is replaced when `accessToken` is sent.
211
221
  - A different Meta pixel for the same organization: the new pixel is
212
222
  saved alongside existing ones.
213
223
  - The pixel is configured by another organization: `409
@@ -215,6 +225,8 @@ paths:
215
225
  - The access token is already used with another pixel: `400
216
226
  invalid_request`.
217
227
  - `platform` other than `meta`: `400 invalid_request`.
228
+ - Optional `isDefault` sets or clears the org default for Meta. At
229
+ least one of `accessToken` or `isDefault` is required.
218
230
 
219
231
  The response never includes the access token. Use
220
232
  `POST /v1/pixels/{pixelId}/test-events` to check the pixel and token.
@@ -247,6 +259,7 @@ paths:
247
259
  example:
248
260
  platform: meta
249
261
  accessToken: 'EAAB...'
262
+ isDefault: true
250
263
  responses:
251
264
  '200':
252
265
  description: Pixel saved or token rotated
@@ -258,6 +271,10 @@ paths:
258
271
  data:
259
272
  id: '1234567890123456'
260
273
  platform: meta
274
+ isDefault: true
275
+ status: ok
276
+ lastErrorCode: null
277
+ errorSince: null
261
278
  meta:
262
279
  requestId: 550e8400-e29b-41d4-a716-446655440000
263
280
  '400': { $ref: '#/components/responses/UpdatePixelBadRequest' }
@@ -267,6 +284,45 @@ paths:
267
284
  '429': { $ref: '#/components/responses/RateLimited' }
268
285
  '500': { $ref: '#/components/responses/InternalError' }
269
286
 
287
+ delete:
288
+ operationId: deletePixel
289
+ summary: Delete an organization pixel
290
+ description: |
291
+ Deletes the Meta pixel `pixelId` for the organization.
292
+
293
+ - `204` when deleted.
294
+ - `404 not_found` when the pixel is not configured for the organization.
295
+ - `409 pixel_in_use` when any smart link still uses the pixel as its
296
+ main or side pixel (`details.smartLinkCount`).
297
+
298
+ Requires `pixels:write`. Organizations without custom pixels enabled
299
+ get `403 custom_pixel_not_enabled`.
300
+
301
+ **Auth:** Accepts API key or OAuth Bearer (`pixels:write`).
302
+ tags: [Pixels]
303
+ x-required-scope: pixels:write
304
+ security:
305
+ - apiKeyBearerAuth: []
306
+ - oauthBearer: []
307
+
308
+ parameters:
309
+ - name: pixelId
310
+ in: path
311
+ required: true
312
+ schema:
313
+ type: string
314
+ minLength: 1
315
+ description: Pixel id on the ad platform.
316
+ responses:
317
+ '204':
318
+ description: Pixel deleted
319
+ '401': { $ref: '#/components/responses/Unauthorized' }
320
+ '403': { $ref: '#/components/responses/PixelForbidden' }
321
+ '404': { $ref: '#/components/responses/NotFound' }
322
+ '409': { $ref: '#/components/responses/PixelInUse' }
323
+ '429': { $ref: '#/components/responses/RateLimited' }
324
+ '500': { $ref: '#/components/responses/InternalError' }
325
+
270
326
  /v1/pixels/{pixelId}/test-events:
271
327
  post:
272
328
  operationId: sendPixelTestEvents
@@ -2099,6 +2155,9 @@ paths:
2099
2155
  country_code: US
2100
2156
  views: 4821
2101
2157
  link_clicks: 890
2158
+ spotify_link_clicks: 820
2159
+ apple_music_link_clicks: 50
2160
+ youtube_music_link_clicks: 10
2102
2161
  streams: 203
2103
2162
  listeners: 145
2104
2163
  new_listeners: 120
@@ -2183,8 +2242,8 @@ paths:
2183
2242
  schema:
2184
2243
  $ref: '#/components/schemas/SoundlinkCountryDailyRow'
2185
2244
  example: |
2186
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"US","views":4821,"link_clicks":890,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
2187
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"DE","views":2103,"link_clicks":31,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
2245
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"US","views":4821,"link_clicks":890,"spotify_link_clicks":820,"apple_music_link_clicks":50,"youtube_music_link_clicks":10,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
2246
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"DE","views":2103,"link_clicks":31,"spotify_link_clicks":28,"apple_music_link_clicks":2,"youtube_music_link_clicks":0,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
2188
2247
  '400': { $ref: '#/components/responses/BadRequest' }
2189
2248
  '401': { $ref: '#/components/responses/Unauthorized' }
2190
2249
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -2781,12 +2840,33 @@ components:
2781
2840
 
2782
2841
  Pixel:
2783
2842
  type: object
2784
- required: [id, platform]
2843
+ required: [id, platform, isDefault, status, lastErrorCode, errorSince]
2785
2844
  properties:
2786
2845
  id:
2787
2846
  type: string
2788
2847
  platform:
2789
2848
  $ref: '#/components/schemas/PixelPlatform'
2849
+ isDefault:
2850
+ type: boolean
2851
+ description: |
2852
+ Whether this pixel is the organization's default for its platform.
2853
+ Only drives the app soundlink create picker; create APIs never
2854
+ fall back to it.
2855
+ status:
2856
+ type: string
2857
+ enum: [ok, error]
2858
+ description: |
2859
+ `error` while an open send-error episode exists for this pixel;
2860
+ `ok` otherwise.
2861
+ lastErrorCode:
2862
+ type: string
2863
+ nullable: true
2864
+ description: Platform error code for the open episode, or `null`.
2865
+ errorSince:
2866
+ type: string
2867
+ format: date-time
2868
+ nullable: true
2869
+ description: When the open error episode started, or `null`.
2790
2870
 
2791
2871
  PixelListResponse:
2792
2872
  type: object
@@ -2806,14 +2886,21 @@ components:
2806
2886
 
2807
2887
  UpdatePixelRequest:
2808
2888
  type: object
2809
- required: [platform, accessToken]
2889
+ required: [platform]
2810
2890
  properties:
2811
2891
  platform:
2812
2892
  $ref: '#/components/schemas/PixelPlatform'
2813
2893
  accessToken:
2814
2894
  type: string
2815
2895
  minLength: 1
2816
- description: Conversions API access token. Stored and never returned.
2896
+ description: |
2897
+ Conversions API access token. Stored and never returned. Required
2898
+ when creating a new pixel; optional when only updating `isDefault`.
2899
+ isDefault:
2900
+ type: boolean
2901
+ description: |
2902
+ Sets or clears the organization's default Meta pixel. At least one
2903
+ of `accessToken` or `isDefault` must be present.
2817
2904
 
2818
2905
  UpdatePixelResponse:
2819
2906
  type: object
@@ -3023,11 +3110,10 @@ components:
3023
3110
  - learning_edit_ack_required
3024
3111
  - wallet_not_enabled
3025
3112
  - premium_plan_required
3026
- - youtube_music_not_enabled
3027
- - attribution_not_enabled
3028
3113
  - soundlink_plan_required
3029
3114
  - custom_pixel_not_enabled
3030
3115
  - meta_pixel_conflict
3116
+ - pixel_in_use
3031
3117
  - insufficient_credit
3032
3118
  - idempotency_key_conflict
3033
3119
  - rate_limit_exceeded
@@ -4475,14 +4561,16 @@ components:
4475
4561
  metaPixelId:
4476
4562
  type: string
4477
4563
  description: |
4478
- Meta pixel ID. Must be sent together with
4479
- `metaConversionAccessToken`. Omit both to skip Meta tracking.
4564
+ Meta pixel ID. Send with `metaConversionAccessToken` to save or
4565
+ rotate the token (unchanged). Or send `metaPixelId` alone to reuse
4566
+ a pixel the organization already saved (requires pixel settings).
4567
+ Omit both to skip Meta tracking. Never applies an org default.
4480
4568
  metaConversionAccessToken:
4481
4569
  type: string
4482
4570
  writeOnly: true
4483
4571
  description: |
4484
4572
  Meta Conversions API access token. Write-only: accepted on create,
4485
- never returned on GET. Must be sent together with `metaPixelId`.
4573
+ never returned on GET. When present, `metaPixelId` is required.
4486
4574
  appleMusicUrl:
4487
4575
  type: string
4488
4576
  format: uri
@@ -4515,8 +4603,7 @@ components:
4515
4603
  description: |
4516
4604
  When false, the landing page skips Spotify login and only tracks
4517
4605
  the landing-page click. Omit or send true to keep attribution.
4518
- Sending false requires the organization to be allowed to turn
4519
- attribution off, and cannot be combined with `autoFollow: true`.
4606
+ Cannot be combined with `autoFollow: true`.
4520
4607
 
4521
4608
  SoundlinkDetail:
4522
4609
  allOf:
@@ -4666,6 +4753,9 @@ components:
4666
4753
  - soundlink_target_type
4667
4754
  - country_code
4668
4755
  - views
4756
+ - spotify_link_clicks
4757
+ - apple_music_link_clicks
4758
+ - youtube_music_link_clicks
4669
4759
  - streams
4670
4760
  - listeners
4671
4761
  - followers
@@ -4728,8 +4818,28 @@ components:
4728
4818
  type: integer
4729
4819
  nullable: true
4730
4820
  description: |
4731
- CTA clicks across all DSPs on the landing page. Null if not tracked
4732
- for this soundlink type.
4821
+ CTA clicks across all DSPs on the landing page (including DSPs
4822
+ without a dedicated column). Always >= the sum of
4823
+ `spotify_link_clicks` + `apple_music_link_clicks` +
4824
+ `youtube_music_link_clicks` — do not derive a per-DSP count by
4825
+ subtraction. Null if not tracked for this soundlink type.
4826
+ spotify_link_clicks:
4827
+ type: integer
4828
+ description: |
4829
+ Continue sessions to Spotify from the landing page. Safe to sum
4830
+ across countries and days.
4831
+ apple_music_link_clicks:
4832
+ type: integer
4833
+ description: |
4834
+ Continue sessions to Apple Music from the landing page (outbound
4835
+ click only; no Apple Music playback attribution). Safe to sum
4836
+ across countries and days.
4837
+ youtube_music_link_clicks:
4838
+ type: integer
4839
+ description: |
4840
+ Continue sessions to YouTube Music from the landing page (outbound
4841
+ click only; no YouTube Music playback attribution). Often `0` on
4842
+ standalone soundlink marts. Safe to sum across countries and days.
4733
4843
  streams:
4734
4844
  type: integer
4735
4845
  description: |
@@ -5449,19 +5559,25 @@ components:
5449
5559
  message: 'Idempotency-Key header is required and must not be empty.'
5450
5560
  meta:
5451
5561
  requestId: 550e8400-e29b-41d4-a716-446655440000
5452
- pixel_pair:
5562
+ pixel_token_without_id:
5453
5563
  value:
5454
5564
  error:
5455
5565
  code: invalid_request
5456
5566
  message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
5457
5567
  meta:
5458
5568
  requestId: 550e8400-e29b-41d4-a716-446655440000
5569
+ pixel_not_owned:
5570
+ value:
5571
+ error:
5572
+ code: invalid_request
5573
+ message: "This pixel can't be used with this account. Check the pixel ID and access token, or contact support."
5574
+ meta:
5575
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5459
5576
 
5460
5577
  CreateSoundlinkForbidden:
5461
5578
  description: |
5462
- Valid credentials but missing the `soundlinks:write` scope, the
5463
- organization has no self-serve plan, or the organization is not allowed
5464
- to create a soundlink with attribution off.
5579
+ Valid credentials but missing the `soundlinks:write` scope, or the
5580
+ organization has no self-serve plan.
5465
5581
  content:
5466
5582
  application/json:
5467
5583
  schema:
@@ -5481,13 +5597,6 @@ components:
5481
5597
  message: 'Creating a Soundlink requires a self-serve plan.'
5482
5598
  meta:
5483
5599
  requestId: 550e8400-e29b-41d4-a716-446655440000
5484
- attribution_not_enabled:
5485
- value:
5486
- error:
5487
- code: attribution_not_enabled
5488
- message: 'This organization cannot create a soundlink with attribution off.'
5489
- meta:
5490
- requestId: 550e8400-e29b-41d4-a716-446655440000
5491
5600
  CreateSoundlinkUnprocessable:
5492
5601
  description: Request body is well-formed but the Spotify URL is invalid.
5493
5602
  content:
@@ -5568,6 +5677,24 @@ components:
5568
5677
  meta:
5569
5678
  requestId: 550e8400-e29b-41d4-a716-446655440000
5570
5679
 
5680
+ PixelInUse:
5681
+ description: |
5682
+ The pixel is still used by one or more smart links and cannot be deleted.
5683
+ content:
5684
+ application/json:
5685
+ schema:
5686
+ $ref: '#/components/schemas/ErrorResponse'
5687
+ examples:
5688
+ pixel_in_use:
5689
+ value:
5690
+ error:
5691
+ code: pixel_in_use
5692
+ message: "This pixel is used by smart links and can't be deleted."
5693
+ details:
5694
+ smartLinkCount: 2
5695
+ meta:
5696
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5697
+
5571
5698
  PixelTestEventBadRequest:
5572
5699
  description: |
5573
5700
  Meta rejected the event because the pixel id or access token is wrong.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "soundlink",
3
- "version": "2.7.0",
3
+ "version": "2.9.0",
4
4
  "description": "Official TypeScript SDK for the Soundlink Public API",
5
5
  "license": "MIT",
6
6
  "type": "module",