soundlink 2.8.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
@@ -2784,12 +2840,33 @@ components:
2784
2840
 
2785
2841
  Pixel:
2786
2842
  type: object
2787
- required: [id, platform]
2843
+ required: [id, platform, isDefault, status, lastErrorCode, errorSince]
2788
2844
  properties:
2789
2845
  id:
2790
2846
  type: string
2791
2847
  platform:
2792
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`.
2793
2870
 
2794
2871
  PixelListResponse:
2795
2872
  type: object
@@ -2809,14 +2886,21 @@ components:
2809
2886
 
2810
2887
  UpdatePixelRequest:
2811
2888
  type: object
2812
- required: [platform, accessToken]
2889
+ required: [platform]
2813
2890
  properties:
2814
2891
  platform:
2815
2892
  $ref: '#/components/schemas/PixelPlatform'
2816
2893
  accessToken:
2817
2894
  type: string
2818
2895
  minLength: 1
2819
- 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.
2820
2904
 
2821
2905
  UpdatePixelResponse:
2822
2906
  type: object
@@ -3026,11 +3110,10 @@ components:
3026
3110
  - learning_edit_ack_required
3027
3111
  - wallet_not_enabled
3028
3112
  - premium_plan_required
3029
- - youtube_music_not_enabled
3030
- - attribution_not_enabled
3031
3113
  - soundlink_plan_required
3032
3114
  - custom_pixel_not_enabled
3033
3115
  - meta_pixel_conflict
3116
+ - pixel_in_use
3034
3117
  - insufficient_credit
3035
3118
  - idempotency_key_conflict
3036
3119
  - rate_limit_exceeded
@@ -4478,14 +4561,16 @@ components:
4478
4561
  metaPixelId:
4479
4562
  type: string
4480
4563
  description: |
4481
- Meta pixel ID. Must be sent together with
4482
- `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.
4483
4568
  metaConversionAccessToken:
4484
4569
  type: string
4485
4570
  writeOnly: true
4486
4571
  description: |
4487
4572
  Meta Conversions API access token. Write-only: accepted on create,
4488
- never returned on GET. Must be sent together with `metaPixelId`.
4573
+ never returned on GET. When present, `metaPixelId` is required.
4489
4574
  appleMusicUrl:
4490
4575
  type: string
4491
4576
  format: uri
@@ -4518,8 +4603,7 @@ components:
4518
4603
  description: |
4519
4604
  When false, the landing page skips Spotify login and only tracks
4520
4605
  the landing-page click. Omit or send true to keep attribution.
4521
- Sending false requires the organization to be allowed to turn
4522
- attribution off, and cannot be combined with `autoFollow: true`.
4606
+ Cannot be combined with `autoFollow: true`.
4523
4607
 
4524
4608
  SoundlinkDetail:
4525
4609
  allOf:
@@ -5475,19 +5559,25 @@ components:
5475
5559
  message: 'Idempotency-Key header is required and must not be empty.'
5476
5560
  meta:
5477
5561
  requestId: 550e8400-e29b-41d4-a716-446655440000
5478
- pixel_pair:
5562
+ pixel_token_without_id:
5479
5563
  value:
5480
5564
  error:
5481
5565
  code: invalid_request
5482
5566
  message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
5483
5567
  meta:
5484
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
5485
5576
 
5486
5577
  CreateSoundlinkForbidden:
5487
5578
  description: |
5488
- Valid credentials but missing the `soundlinks:write` scope, the
5489
- organization has no self-serve plan, or the organization is not allowed
5490
- 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.
5491
5581
  content:
5492
5582
  application/json:
5493
5583
  schema:
@@ -5507,13 +5597,6 @@ components:
5507
5597
  message: 'Creating a Soundlink requires a self-serve plan.'
5508
5598
  meta:
5509
5599
  requestId: 550e8400-e29b-41d4-a716-446655440000
5510
- attribution_not_enabled:
5511
- value:
5512
- error:
5513
- code: attribution_not_enabled
5514
- message: 'This organization cannot create a soundlink with attribution off.'
5515
- meta:
5516
- requestId: 550e8400-e29b-41d4-a716-446655440000
5517
5600
  CreateSoundlinkUnprocessable:
5518
5601
  description: Request body is well-formed but the Spotify URL is invalid.
5519
5602
  content:
@@ -5594,6 +5677,24 @@ components:
5594
5677
  meta:
5595
5678
  requestId: 550e8400-e29b-41d4-a716-446655440000
5596
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
+
5597
5698
  PixelTestEventBadRequest:
5598
5699
  description: |
5599
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.8.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",