soundlink 2.1.0 → 2.3.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.
@@ -30,10 +30,10 @@ type CampaignSortBy = 'createdAt' | 'status';
30
30
  type SoundlinkSortBy = 'createdAt';
31
31
  /** Allowed `sortBy` values for breakdown list requests. */
32
32
  type BreakdownSortBy = 'report_date' | 'spend_total';
33
- /** Allowed `sortBy` values for soundlink timeseries. */
34
- type SoundlinkTimeseriesSortBy = 'report_date';
35
- /** Allowed `sortBy` values for soundlink engagement (top tracks). */
36
- type SoundlinkEngagementSortBy = 'totalStreams' | 'totalListeners';
33
+ /** Allowed `sortBy` values for soundlink breakdown list requests. */
34
+ type SoundlinkBreakdownSortBy = 'report_date' | 'country_code';
35
+ /** Allowed `sortBy` values for soundlink engagement list requests. */
36
+ type SoundlinkEngagementSortBy = 'report_date';
37
37
  /** Sort direction for list endpoints. */
38
38
  type SortOrder = 'asc' | 'desc';
39
39
  /** Lifecycle status for a self-serve soundlink. */
@@ -397,32 +397,6 @@ interface DateRangeParams {
397
397
  /** Inclusive end date. Must not be before `startDate`. */
398
398
  endDate?: string;
399
399
  }
400
- /** Query params for {@link SoundlinksResource.metricsTimeseries}. */
401
- interface SoundlinkTimeseriesParams extends DateRangeParams {
402
- page?: number;
403
- /** Default: `50`. Max: **500**. */
404
- pageSize?: number;
405
- /** Default: `report_date`. */
406
- sortBy?: SoundlinkTimeseriesSortBy;
407
- /** Default: `asc`. */
408
- sortOrder?: SortOrder;
409
- }
410
- /**
411
- * Query params for {@link SoundlinksResource.engagement}.
412
- *
413
- * `startDate`/`endDate` snap to Insights windows only (yesterday, last 7 days
414
- * ending today, or all-time). Arbitrary ranges resolve to all-time.
415
- * Omitting `startDate` always uses all-time (not createdAt).
416
- */
417
- interface SoundlinkEngagementParams extends DateRangeParams {
418
- page?: number;
419
- /** Default: `10`. Max: **100**. */
420
- pageSize?: number;
421
- /** Default: `totalStreams`. */
422
- sortBy?: SoundlinkEngagementSortBy;
423
- /** Default: `desc`. */
424
- sortOrder?: SortOrder;
425
- }
426
400
  /** Self-serve soundlink summary from {@link SoundlinksResource.list}. */
427
401
  interface SoundlinkSummary {
428
402
  soundlinkId: string;
@@ -439,9 +413,26 @@ interface SoundlinkSummary {
439
413
  /** Full soundlink detail from {@link SoundlinksResource.get}. */
440
414
  interface SoundlinkDetail extends SoundlinkSummary {
441
415
  autoFollow: boolean;
416
+ artistIdFollow: string | null;
442
417
  metaPixelId: string | null;
443
418
  tiktokPixelId: string | null;
444
419
  }
420
+ /** Body for `POST /v1/soundlinks`. */
421
+ interface CreateSoundlinkRequest {
422
+ name: string;
423
+ /** HTTPS Spotify track or playlist URL. */
424
+ spotifyUrl: string;
425
+ autoFollow?: boolean;
426
+ /** Spotify artist ID for auto-follow on track links. Ignored for playlists. */
427
+ artistIdFollow?: string;
428
+ /** Must be sent together with `metaConversionAccessToken`. */
429
+ metaPixelId?: string;
430
+ /**
431
+ * Meta Conversions API token. Write-only: accepted on create, never returned.
432
+ * Must be sent together with `metaPixelId`.
433
+ */
434
+ metaConversionAccessToken?: string;
435
+ }
445
436
  /** Paginated soundlink list payload. */
446
437
  interface SoundlinkListData {
447
438
  items: SoundlinkSummary[];
@@ -457,16 +448,12 @@ interface SoundlinkMetricsOverview {
457
448
  link_clicks: number | null;
458
449
  streams: number;
459
450
  listeners: number;
460
- new_listeners: number | null;
461
- returning_listeners: number | null;
462
- new_listener_streams: number | null;
463
- returning_listener_streams: number | null;
464
451
  followers: number;
465
452
  streams_per_listener: number;
466
453
  ctr_lp: number | null;
467
454
  }
468
- /** One row of the `soundlink_daily` v1.0 schema. */
469
- interface SoundlinkDailyRow {
455
+ /** One row of the `soundlink_country_daily` v1.0 schema. */
456
+ interface SoundlinkBreakdownRow {
470
457
  provider: 'soundlink';
471
458
  account_id: string;
472
459
  schema_version: string;
@@ -476,10 +463,11 @@ interface SoundlinkDailyRow {
476
463
  exported_at: string;
477
464
  soundlink_id: string;
478
465
  soundlink_name: string;
479
- soundlink_target_type: SoundlinkTargetType | null;
466
+ soundlink_target_type: 'track' | 'playlist' | null;
480
467
  soundlink_target_isrc: string | null;
481
468
  soundlink_target_spotify_track_id: string | null;
482
469
  soundlink_target_playlist_id: string | null;
470
+ country_code: string;
483
471
  views: number;
484
472
  link_clicks: number | null;
485
473
  streams: number;
@@ -492,25 +480,72 @@ interface SoundlinkDailyRow {
492
480
  streams_per_listener: number;
493
481
  ctr_lp: number | null;
494
482
  }
495
- /** Paginated soundlink timeseries payload. */
496
- interface SoundlinkTimeseriesData {
483
+ /** Paginated soundlink breakdown list payload. */
484
+ interface SoundlinkBreakdownListData {
497
485
  schemaVersion: string;
498
- items: SoundlinkDailyRow[];
486
+ items: SoundlinkBreakdownRow[];
499
487
  pagination: Pagination;
500
488
  }
501
- /** One aggregated top track from {@link SoundlinksResource.engagement}. */
502
- interface SoundlinkEngagementItem {
503
- trackId: string;
504
- trackName: string;
505
- totalStreams: number;
506
- totalListeners: number;
507
- streamsPerListener: number;
508
- }
509
- /** Paginated soundlink engagement payload. */
510
- interface SoundlinkEngagementData {
511
- items: SoundlinkEngagementItem[];
489
+ /** One row of the `soundlink_engagement_daily` v1.0 schema. */
490
+ interface SoundlinkEngagementRow {
491
+ provider: 'soundlink';
492
+ account_id: string;
493
+ schema_version: string;
494
+ report_date: string;
495
+ report_date_timezone: 'UTC';
496
+ exported_at: string;
497
+ soundlink_id: string;
498
+ soundlink_name: string;
499
+ soundlink_target_type: 'track' | 'playlist' | null;
500
+ soundlink_target_isrc: string | null;
501
+ soundlink_target_spotify_track_id: string | null;
502
+ soundlink_target_playlist_id: string | null;
503
+ engagement_context: EngagementContext;
504
+ country_code: string;
505
+ engaged_track_isrc: string | null;
506
+ engaged_spotify_track_id: string;
507
+ engaged_track_name: string;
508
+ playlist_position: number | null;
509
+ new_listeners: number;
510
+ returning_listeners: number;
511
+ listeners: number;
512
+ new_listener_streams: number;
513
+ returning_listener_streams: number;
514
+ streams: number;
515
+ spl: number;
516
+ }
517
+ /** Paginated soundlink engagement list payload. */
518
+ interface SoundlinkEngagementListData {
519
+ schemaVersion: string;
520
+ items: SoundlinkEngagementRow[];
512
521
  pagination: Pagination;
513
522
  }
523
+ /** Query params for {@link SoundlinkBreakdownMetricsResource.list}. */
524
+ interface SoundlinkBreakdownListParams extends DateRangeParams {
525
+ page?: number;
526
+ /** Default: `50`. Max: **500**. */
527
+ pageSize?: number;
528
+ /** Default: `report_date`. */
529
+ sortBy?: SoundlinkBreakdownSortBy;
530
+ /** Default: `asc`. */
531
+ sortOrder?: SortOrder;
532
+ }
533
+ /**
534
+ * Query params for {@link SoundlinkEngagementMetricsResource.list}.
535
+ *
536
+ * Defaults to the last 90 days ending today; max **90 days** per request.
537
+ */
538
+ interface SoundlinkEngagementListParams extends DateRangeParams {
539
+ page?: number;
540
+ /** Default: `50`. Max: **500**. */
541
+ pageSize?: number;
542
+ /** Filter to a single engagement context. Omit to return both. */
543
+ engagementContext?: EngagementContext;
544
+ /** Default: `report_date`. */
545
+ sortBy?: SoundlinkEngagementSortBy;
546
+ /** Default: `asc`. */
547
+ sortOrder?: SortOrder;
548
+ }
514
549
  /** Query params for {@link BreakdownMetricsResource.list}. */
515
550
  interface BreakdownListParams extends DateRangeParams {
516
551
  page?: number;
@@ -563,6 +598,7 @@ declare class HttpClient {
563
598
  get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
564
599
  post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
565
600
  patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
601
+ delete<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
566
602
  getJsonl<T>({ path, query, accept, }: HttpJsonlOptions): Promise<ApiResponse<JsonlStream<T>>>;
567
603
  private mutateJson;
568
604
  private buildHeaders;
@@ -592,16 +628,16 @@ interface ExportResource<T, P extends DateRangeParams> {
592
628
  /**
593
629
  * Stream export rows as newline-delimited JSON.
594
630
  *
595
- * @param campaignId - Soundlink campaign ID.
631
+ * @param id - Campaign or soundlink ID.
596
632
  * @param params - Optional date range (max 90 days per request).
597
633
  */
598
- (campaignId: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
634
+ (id: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
599
635
  /**
600
636
  * Download all export rows into memory.
601
637
  *
602
638
  * Prefer {@link ExportResource | the stream} for large datasets.
603
639
  */
604
- collect(campaignId: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
640
+ collect(id: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
605
641
  }
606
642
  /** System endpoints (`GET /v1/ping`). */
607
643
  declare class PingResource {
@@ -742,20 +778,27 @@ declare class CampaignsResource {
742
778
  listAll(params?: Omit<CampaignListParams, 'page'>): AsyncGenerator<CampaignListData['items'][number], void, void>;
743
779
  }
744
780
  /**
745
- * Self-serve soundlinks (`/v1/soundlinks/*`). Requires `soundlinks:read`.
781
+ * Self-serve soundlinks (`/v1/soundlinks/*`).
746
782
  *
747
- * Only soundlinks that are **not** linked to a campaign. Campaign-backed
748
- * soundlinks are served by the Campaigns API.
783
+ * List, get, and metrics require `soundlinks:read`. Create and delete require
784
+ * `soundlinks:write`. Only soundlinks that are **not** linked to a campaign.
785
+ * Campaign-backed soundlinks are served by the Campaigns API.
749
786
  *
750
787
  * @example
751
788
  * ```ts
752
789
  * await soundlink.soundlinks.list();
753
790
  * await soundlink.soundlinks.get(soundlinkId);
791
+ * await soundlink.soundlinks.create({ name, spotifyUrl }, { idempotencyKey });
792
+ * await soundlink.soundlinks.delete(soundlinkId);
754
793
  * await soundlink.soundlinks.metricsOverview(soundlinkId);
755
794
  * ```
756
795
  */
757
796
  declare class SoundlinksResource {
758
797
  private readonly http;
798
+ /** Per-day country breakdown and JSONL export. */
799
+ readonly breakdown: SoundlinkBreakdownMetricsResource;
800
+ /** Per-day track engagement and JSONL export. */
801
+ readonly engagement: SoundlinkEngagementMetricsResource;
759
802
  constructor(http: HttpClient);
760
803
  /**
761
804
  * List self-serve soundlinks for the authenticated organization.
@@ -779,6 +822,31 @@ declare class SoundlinksResource {
779
822
  * @param soundlinkId - Identifier returned by {@link SoundlinksResource.list}.
780
823
  */
781
824
  get(soundlinkId: string): Promise<ApiResponse<SoundlinkDetail>>;
825
+ /**
826
+ * Create a self-serve soundlink.
827
+ *
828
+ * Maps to `POST /v1/soundlinks`. Requires `soundlinks:write` and
829
+ * `Idempotency-Key`. Does not create a campaign.
830
+ *
831
+ * @example
832
+ * ```ts
833
+ * const { data, error } = await soundlink.soundlinks.create(
834
+ * {
835
+ * name: 'Midnight Drive',
836
+ * spotifyUrl: 'https://open.spotify.com/track/...',
837
+ * },
838
+ * { idempotencyKey: 'create-midnight-drive-01' },
839
+ * );
840
+ * ```
841
+ */
842
+ create(body: CreateSoundlinkRequest, options: IdempotencyOptions): Promise<ApiResponse<SoundlinkDetail>>;
843
+ /**
844
+ * Archive a self-serve soundlink (`status: archived`). Same as Archive in the app.
845
+ *
846
+ * Maps to `DELETE /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:write`.
847
+ * Does not send `Idempotency-Key`. List and detail still return the row.
848
+ */
849
+ delete(soundlinkId: string): Promise<ApiResponse<SoundlinkDetail>>;
782
850
  /**
783
851
  * Soundlink-level metric totals for a date range.
784
852
  *
@@ -790,30 +858,56 @@ declare class SoundlinksResource {
790
858
  * @param params - Inclusive `YYYY-MM-DD` date range.
791
859
  */
792
860
  metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
861
+ }
862
+ /**
863
+ * Country-level daily metrics (`soundlink_country_daily` schema).
864
+ *
865
+ * Access via `soundlink.soundlinks.breakdown`.
866
+ */
867
+ declare class SoundlinkBreakdownMetricsResource {
868
+ private readonly http;
793
869
  /**
794
- * Per-day metrics for a soundlink (`soundlink_daily` schema).
870
+ * Stream full breakdown export as JSONL.
795
871
  *
796
- * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/timeseries`.
797
- * Max `pageSize` is **500** (default 50). Requires `soundlinks:read`.
872
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
873
+ */
874
+ readonly export: ExportResource<SoundlinkBreakdownRow, BreakdownExportParams>;
875
+ constructor(http: HttpClient);
876
+ /**
877
+ * Paginated per-day, per-country breakdown rows.
878
+ *
879
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
880
+ * Max `pageSize` is **500** (default 50).
798
881
  *
799
882
  * @param soundlinkId - Soundlink identifier.
800
883
  * @param params - Date range, pagination, and sort options.
801
884
  */
802
- metricsTimeseries(soundlinkId: string, params?: SoundlinkTimeseriesParams): Promise<ApiResponse<SoundlinkTimeseriesData>>;
885
+ list(soundlinkId: string, params?: SoundlinkBreakdownListParams): Promise<ApiResponse<SoundlinkBreakdownListData>>;
886
+ }
887
+ /**
888
+ * Per-track engagement metrics (`soundlink_engagement_daily` schema).
889
+ *
890
+ * Access via `soundlink.soundlinks.engagement`.
891
+ */
892
+ declare class SoundlinkEngagementMetricsResource {
893
+ private readonly http;
803
894
  /**
804
- * Top tracks for a soundlink (period totals, not daily rows).
895
+ * Stream full engagement export as JSONL.
805
896
  *
806
- * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
807
- * Max `pageSize` is **100**. Requires `soundlinks:read`.
897
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
898
+ */
899
+ readonly export: ExportResource<SoundlinkEngagementRow, EngagementExportParams>;
900
+ constructor(http: HttpClient);
901
+ /**
902
+ * Paginated per-day, per-track engagement rows.
808
903
  *
809
- * Date ranges snap to Insights windows only: yesterday, last 7 days ending
810
- * today, or all-time. Arbitrary ranges resolve to all-time. Omitting
811
- * `startDate` always uses all-time (not createdAt).
904
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
905
+ * Max `pageSize` is **500** (default 50).
812
906
  *
813
907
  * @param soundlinkId - Soundlink identifier.
814
- * @param params - Date range, pagination, and sort options.
908
+ * @param params - Date range, engagement context filter, pagination, and sort.
815
909
  */
816
- engagement(soundlinkId: string, params?: SoundlinkEngagementParams): Promise<ApiResponse<SoundlinkEngagementData>>;
910
+ list(soundlinkId: string, params?: SoundlinkEngagementListParams): Promise<ApiResponse<SoundlinkEngagementListData>>;
817
911
  }
818
912
  /**
819
913
  * Campaign metrics (`/v1/campaigns/{id}/metrics/*`). Requires `metrics:read`.
@@ -921,7 +1015,7 @@ declare class Soundlink {
921
1015
  readonly strategies: StrategiesResource;
922
1016
  /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
923
1017
  readonly campaigns: CampaignsResource;
924
- /** Self-serve soundlinks (list, detail, metrics). Requires `soundlinks:read` scope. */
1018
+ /** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
925
1019
  readonly soundlinks: SoundlinksResource;
926
1020
  /** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
927
1021
  readonly metrics: MetricsResource;
@@ -958,4 +1052,4 @@ declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
958
1052
  declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
959
1053
  declare const METRICS_MAX_PAGE_SIZE = 500;
960
1054
 
961
- export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, type BudgetDecreaseMode, type BudgetIncreaseMode, type BuiltInStrategyType, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreativeDirection, type CustomTier, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type DecreaseCampaignBudgetData, type DecreaseCampaignBudgetRequest, type DoItForMeCreativeDirection, type EngagementContext, type EngagementExportParams, type EngagementRow, type ExportCollection, type ExportResource, type FullControlCreativeDirection, type Genre, HttpClient, type IdempotencyOptions, type IncreaseCampaignBudgetData, type IncreaseCampaignBudgetRequest, type JsonlStream, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type Pagination, type PingData, type PublicApiErrorCode, SOUNDLINKS_MAX_PAGE_SIZE, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkDailyRow, type SoundlinkDetail, type SoundlinkEngagementData, type SoundlinkEngagementItem, type SoundlinkEngagementParams, type SoundlinkEngagementSortBy, type SoundlinkListData, type SoundlinkListParams, type SoundlinkMetricsOverview, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type SoundlinkSortBy, type SoundlinkStatus, type SoundlinkSummary, type SoundlinkTargetType, type SoundlinkTimeseriesData, type SoundlinkTimeseriesParams, type SoundlinkTimeseriesSortBy, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignTiersRequest, getStreamRowCount, resolveClientOptions };
1055
+ export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, type BudgetDecreaseMode, type BudgetIncreaseMode, type BuiltInStrategyType, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreateSoundlinkRequest, type CreativeDirection, type CustomTier, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type DecreaseCampaignBudgetData, type DecreaseCampaignBudgetRequest, type DoItForMeCreativeDirection, type EngagementContext, type EngagementExportParams, type EngagementRow, type ExportCollection, type ExportResource, type FullControlCreativeDirection, type Genre, HttpClient, type IdempotencyOptions, type IncreaseCampaignBudgetData, type IncreaseCampaignBudgetRequest, type JsonlStream, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type Pagination, type PingData, type PublicApiErrorCode, SOUNDLINKS_MAX_PAGE_SIZE, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkBreakdownListData, type SoundlinkBreakdownListParams, type SoundlinkBreakdownRow, type SoundlinkBreakdownSortBy, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkDetail, type SoundlinkEngagementListData, type SoundlinkEngagementListParams, type SoundlinkEngagementRow, type SoundlinkEngagementSortBy, type SoundlinkListData, type SoundlinkListParams, type SoundlinkMetricsOverview, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type SoundlinkSortBy, type SoundlinkStatus, type SoundlinkSummary, type SoundlinkTargetType, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignTiersRequest, getStreamRowCount, resolveClientOptions };
package/dist/esm/index.js CHANGED
@@ -237,6 +237,21 @@ var HttpClient = class {
237
237
  idempotencyKey
238
238
  });
239
239
  }
240
+ async delete({
241
+ path,
242
+ body,
243
+ query,
244
+ headers,
245
+ idempotencyKey
246
+ }) {
247
+ return this.mutateJson("DELETE", {
248
+ path,
249
+ body,
250
+ query,
251
+ headers,
252
+ idempotencyKey
253
+ });
254
+ }
240
255
  async getJsonl({
241
256
  path,
242
257
  query,
@@ -396,14 +411,14 @@ function getStreamRowCount(stream) {
396
411
 
397
412
  // src/resources/index.ts
398
413
  function createExportResource(http, buildPath, buildQuery) {
399
- const exportFn = ((campaignId, params = {}) => {
414
+ const exportFn = ((id, params = {}) => {
400
415
  return http.getJsonl({
401
- path: buildPath(campaignId),
416
+ path: buildPath(id),
402
417
  query: buildQuery(params)
403
418
  });
404
419
  });
405
- exportFn.collect = async (campaignId, params = {}) => {
406
- const response = await exportFn(campaignId, params);
420
+ exportFn.collect = async (id, params = {}) => {
421
+ const response = await exportFn(id, params);
407
422
  if (response.error || !response.data) {
408
423
  return {
409
424
  data: null,
@@ -630,8 +645,14 @@ var CampaignsResource = class {
630
645
  var SoundlinksResource = class {
631
646
  constructor(http) {
632
647
  this.http = http;
648
+ this.breakdown = new SoundlinkBreakdownMetricsResource(http);
649
+ this.engagement = new SoundlinkEngagementMetricsResource(http);
633
650
  }
634
651
  http;
652
+ /** Per-day country breakdown and JSONL export. */
653
+ breakdown;
654
+ /** Per-day track engagement and JSONL export. */
655
+ engagement;
635
656
  /**
636
657
  * List self-serve soundlinks for the authenticated organization.
637
658
  *
@@ -668,6 +689,41 @@ var SoundlinksResource = class {
668
689
  path: `/soundlinks/${encodeURIComponent(soundlinkId)}`
669
690
  });
670
691
  }
692
+ /**
693
+ * Create a self-serve soundlink.
694
+ *
695
+ * Maps to `POST /v1/soundlinks`. Requires `soundlinks:write` and
696
+ * `Idempotency-Key`. Does not create a campaign.
697
+ *
698
+ * @example
699
+ * ```ts
700
+ * const { data, error } = await soundlink.soundlinks.create(
701
+ * {
702
+ * name: 'Midnight Drive',
703
+ * spotifyUrl: 'https://open.spotify.com/track/...',
704
+ * },
705
+ * { idempotencyKey: 'create-midnight-drive-01' },
706
+ * );
707
+ * ```
708
+ */
709
+ create(body, options) {
710
+ return this.http.post({
711
+ path: "/soundlinks",
712
+ body,
713
+ idempotencyKey: options.idempotencyKey
714
+ });
715
+ }
716
+ /**
717
+ * Archive a self-serve soundlink (`status: archived`). Same as Archive in the app.
718
+ *
719
+ * Maps to `DELETE /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:write`.
720
+ * Does not send `Idempotency-Key`. List and detail still return the row.
721
+ */
722
+ delete(soundlinkId) {
723
+ return this.http.delete({
724
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}`
725
+ });
726
+ }
671
727
  /**
672
728
  * Soundlink-level metric totals for a date range.
673
729
  *
@@ -687,18 +743,38 @@ var SoundlinksResource = class {
687
743
  }
688
744
  });
689
745
  }
746
+ };
747
+ var SoundlinkBreakdownMetricsResource = class {
748
+ constructor(http) {
749
+ this.http = http;
750
+ this.export = createExportResource(
751
+ http,
752
+ (soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown/export`,
753
+ (params) => ({
754
+ startDate: params.startDate,
755
+ endDate: params.endDate
756
+ })
757
+ );
758
+ }
759
+ http;
760
+ /**
761
+ * Stream full breakdown export as JSONL.
762
+ *
763
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
764
+ */
765
+ export;
690
766
  /**
691
- * Per-day metrics for a soundlink (`soundlink_daily` schema).
767
+ * Paginated per-day, per-country breakdown rows.
692
768
  *
693
- * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/timeseries`.
694
- * Max `pageSize` is **500** (default 50). Requires `soundlinks:read`.
769
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
770
+ * Max `pageSize` is **500** (default 50).
695
771
  *
696
772
  * @param soundlinkId - Soundlink identifier.
697
773
  * @param params - Date range, pagination, and sort options.
698
774
  */
699
- metricsTimeseries(soundlinkId, params = {}) {
775
+ list(soundlinkId, params = {}) {
700
776
  return this.http.get({
701
- path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/timeseries`,
777
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown`,
702
778
  query: {
703
779
  startDate: params.startDate,
704
780
  endDate: params.endDate,
@@ -709,25 +785,43 @@ var SoundlinksResource = class {
709
785
  }
710
786
  });
711
787
  }
788
+ };
789
+ var SoundlinkEngagementMetricsResource = class {
790
+ constructor(http) {
791
+ this.http = http;
792
+ this.export = createExportResource(
793
+ http,
794
+ (soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement/export`,
795
+ (params) => ({
796
+ startDate: params.startDate,
797
+ endDate: params.endDate,
798
+ engagementContext: params.engagementContext
799
+ })
800
+ );
801
+ }
802
+ http;
712
803
  /**
713
- * Top tracks for a soundlink (period totals, not daily rows).
804
+ * Stream full engagement export as JSONL.
714
805
  *
715
- * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
716
- * Max `pageSize` is **100**. Requires `soundlinks:read`.
806
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
807
+ */
808
+ export;
809
+ /**
810
+ * Paginated per-day, per-track engagement rows.
717
811
  *
718
- * Date ranges snap to Insights windows only: yesterday, last 7 days ending
719
- * today, or all-time. Arbitrary ranges resolve to all-time. Omitting
720
- * `startDate` always uses all-time (not createdAt).
812
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
813
+ * Max `pageSize` is **500** (default 50).
721
814
  *
722
815
  * @param soundlinkId - Soundlink identifier.
723
- * @param params - Date range, pagination, and sort options.
816
+ * @param params - Date range, engagement context filter, pagination, and sort.
724
817
  */
725
- engagement(soundlinkId, params = {}) {
818
+ list(soundlinkId, params = {}) {
726
819
  return this.http.get({
727
820
  path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement`,
728
821
  query: {
729
822
  startDate: params.startDate,
730
823
  endDate: params.endDate,
824
+ engagementContext: params.engagementContext,
731
825
  page: params.page,
732
826
  pageSize: params.pageSize,
733
827
  sortBy: params.sortBy,
@@ -846,7 +940,7 @@ var Soundlink = class {
846
940
  strategies;
847
941
  /** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
848
942
  campaigns;
849
- /** Self-serve soundlinks (list, detail, metrics). Requires `soundlinks:read` scope. */
943
+ /** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
850
944
  soundlinks;
851
945
  /** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
852
946
  metrics;