soundlink 2.1.0 → 2.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.
@@ -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;
@@ -457,16 +431,12 @@ interface SoundlinkMetricsOverview {
457
431
  link_clicks: number | null;
458
432
  streams: number;
459
433
  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
434
  followers: number;
465
435
  streams_per_listener: number;
466
436
  ctr_lp: number | null;
467
437
  }
468
- /** One row of the `soundlink_daily` v1.0 schema. */
469
- interface SoundlinkDailyRow {
438
+ /** One row of the `soundlink_country_daily` v1.0 schema. */
439
+ interface SoundlinkBreakdownRow {
470
440
  provider: 'soundlink';
471
441
  account_id: string;
472
442
  schema_version: string;
@@ -476,10 +446,11 @@ interface SoundlinkDailyRow {
476
446
  exported_at: string;
477
447
  soundlink_id: string;
478
448
  soundlink_name: string;
479
- soundlink_target_type: SoundlinkTargetType | null;
449
+ soundlink_target_type: 'track' | 'playlist' | null;
480
450
  soundlink_target_isrc: string | null;
481
451
  soundlink_target_spotify_track_id: string | null;
482
452
  soundlink_target_playlist_id: string | null;
453
+ country_code: string;
483
454
  views: number;
484
455
  link_clicks: number | null;
485
456
  streams: number;
@@ -492,25 +463,72 @@ interface SoundlinkDailyRow {
492
463
  streams_per_listener: number;
493
464
  ctr_lp: number | null;
494
465
  }
495
- /** Paginated soundlink timeseries payload. */
496
- interface SoundlinkTimeseriesData {
466
+ /** Paginated soundlink breakdown list payload. */
467
+ interface SoundlinkBreakdownListData {
497
468
  schemaVersion: string;
498
- items: SoundlinkDailyRow[];
469
+ items: SoundlinkBreakdownRow[];
499
470
  pagination: Pagination;
500
471
  }
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[];
472
+ /** One row of the `soundlink_engagement_daily` v1.0 schema. */
473
+ interface SoundlinkEngagementRow {
474
+ provider: 'soundlink';
475
+ account_id: string;
476
+ schema_version: string;
477
+ report_date: string;
478
+ report_date_timezone: 'UTC';
479
+ exported_at: string;
480
+ soundlink_id: string;
481
+ soundlink_name: string;
482
+ soundlink_target_type: 'track' | 'playlist' | null;
483
+ soundlink_target_isrc: string | null;
484
+ soundlink_target_spotify_track_id: string | null;
485
+ soundlink_target_playlist_id: string | null;
486
+ engagement_context: EngagementContext;
487
+ country_code: string;
488
+ engaged_track_isrc: string | null;
489
+ engaged_spotify_track_id: string;
490
+ engaged_track_name: string;
491
+ playlist_position: number | null;
492
+ new_listeners: number;
493
+ returning_listeners: number;
494
+ listeners: number;
495
+ new_listener_streams: number;
496
+ returning_listener_streams: number;
497
+ streams: number;
498
+ spl: number;
499
+ }
500
+ /** Paginated soundlink engagement list payload. */
501
+ interface SoundlinkEngagementListData {
502
+ schemaVersion: string;
503
+ items: SoundlinkEngagementRow[];
512
504
  pagination: Pagination;
513
505
  }
506
+ /** Query params for {@link SoundlinkBreakdownMetricsResource.list}. */
507
+ interface SoundlinkBreakdownListParams extends DateRangeParams {
508
+ page?: number;
509
+ /** Default: `50`. Max: **500**. */
510
+ pageSize?: number;
511
+ /** Default: `report_date`. */
512
+ sortBy?: SoundlinkBreakdownSortBy;
513
+ /** Default: `asc`. */
514
+ sortOrder?: SortOrder;
515
+ }
516
+ /**
517
+ * Query params for {@link SoundlinkEngagementMetricsResource.list}.
518
+ *
519
+ * Defaults to the last 90 days ending today; max **90 days** per request.
520
+ */
521
+ interface SoundlinkEngagementListParams extends DateRangeParams {
522
+ page?: number;
523
+ /** Default: `50`. Max: **500**. */
524
+ pageSize?: number;
525
+ /** Filter to a single engagement context. Omit to return both. */
526
+ engagementContext?: EngagementContext;
527
+ /** Default: `report_date`. */
528
+ sortBy?: SoundlinkEngagementSortBy;
529
+ /** Default: `asc`. */
530
+ sortOrder?: SortOrder;
531
+ }
514
532
  /** Query params for {@link BreakdownMetricsResource.list}. */
515
533
  interface BreakdownListParams extends DateRangeParams {
516
534
  page?: number;
@@ -592,16 +610,16 @@ interface ExportResource<T, P extends DateRangeParams> {
592
610
  /**
593
611
  * Stream export rows as newline-delimited JSON.
594
612
  *
595
- * @param campaignId - Soundlink campaign ID.
613
+ * @param id - Campaign or soundlink ID.
596
614
  * @param params - Optional date range (max 90 days per request).
597
615
  */
598
- (campaignId: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
616
+ (id: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
599
617
  /**
600
618
  * Download all export rows into memory.
601
619
  *
602
620
  * Prefer {@link ExportResource | the stream} for large datasets.
603
621
  */
604
- collect(campaignId: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
622
+ collect(id: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
605
623
  }
606
624
  /** System endpoints (`GET /v1/ping`). */
607
625
  declare class PingResource {
@@ -752,10 +770,16 @@ declare class CampaignsResource {
752
770
  * await soundlink.soundlinks.list();
753
771
  * await soundlink.soundlinks.get(soundlinkId);
754
772
  * await soundlink.soundlinks.metricsOverview(soundlinkId);
773
+ * await soundlink.soundlinks.breakdown.list(soundlinkId);
774
+ * await soundlink.soundlinks.engagement.export(soundlinkId);
755
775
  * ```
756
776
  */
757
777
  declare class SoundlinksResource {
758
778
  private readonly http;
779
+ /** Per-day country breakdown and JSONL export. */
780
+ readonly breakdown: SoundlinkBreakdownMetricsResource;
781
+ /** Per-day track engagement and JSONL export. */
782
+ readonly engagement: SoundlinkEngagementMetricsResource;
759
783
  constructor(http: HttpClient);
760
784
  /**
761
785
  * List self-serve soundlinks for the authenticated organization.
@@ -790,30 +814,56 @@ declare class SoundlinksResource {
790
814
  * @param params - Inclusive `YYYY-MM-DD` date range.
791
815
  */
792
816
  metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
817
+ }
818
+ /**
819
+ * Country-level daily metrics (`soundlink_country_daily` schema).
820
+ *
821
+ * Access via `soundlink.soundlinks.breakdown`.
822
+ */
823
+ declare class SoundlinkBreakdownMetricsResource {
824
+ private readonly http;
793
825
  /**
794
- * Per-day metrics for a soundlink (`soundlink_daily` schema).
826
+ * Stream full breakdown export as JSONL.
795
827
  *
796
- * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/timeseries`.
797
- * Max `pageSize` is **500** (default 50). Requires `soundlinks:read`.
828
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
829
+ */
830
+ readonly export: ExportResource<SoundlinkBreakdownRow, BreakdownExportParams>;
831
+ constructor(http: HttpClient);
832
+ /**
833
+ * Paginated per-day, per-country breakdown rows.
834
+ *
835
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
836
+ * Max `pageSize` is **500** (default 50).
798
837
  *
799
838
  * @param soundlinkId - Soundlink identifier.
800
839
  * @param params - Date range, pagination, and sort options.
801
840
  */
802
- metricsTimeseries(soundlinkId: string, params?: SoundlinkTimeseriesParams): Promise<ApiResponse<SoundlinkTimeseriesData>>;
841
+ list(soundlinkId: string, params?: SoundlinkBreakdownListParams): Promise<ApiResponse<SoundlinkBreakdownListData>>;
842
+ }
843
+ /**
844
+ * Per-track engagement metrics (`soundlink_engagement_daily` schema).
845
+ *
846
+ * Access via `soundlink.soundlinks.engagement`.
847
+ */
848
+ declare class SoundlinkEngagementMetricsResource {
849
+ private readonly http;
850
+ /**
851
+ * Stream full engagement export as JSONL.
852
+ *
853
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
854
+ */
855
+ readonly export: ExportResource<SoundlinkEngagementRow, EngagementExportParams>;
856
+ constructor(http: HttpClient);
803
857
  /**
804
- * Top tracks for a soundlink (period totals, not daily rows).
858
+ * Paginated per-day, per-track engagement rows.
805
859
  *
806
860
  * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
807
- * Max `pageSize` is **100**. Requires `soundlinks:read`.
808
- *
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).
861
+ * Max `pageSize` is **500** (default 50).
812
862
  *
813
863
  * @param soundlinkId - Soundlink identifier.
814
- * @param params - Date range, pagination, and sort options.
864
+ * @param params - Date range, engagement context filter, pagination, and sort.
815
865
  */
816
- engagement(soundlinkId: string, params?: SoundlinkEngagementParams): Promise<ApiResponse<SoundlinkEngagementData>>;
866
+ list(soundlinkId: string, params?: SoundlinkEngagementListParams): Promise<ApiResponse<SoundlinkEngagementListData>>;
817
867
  }
818
868
  /**
819
869
  * Campaign metrics (`/v1/campaigns/{id}/metrics/*`). Requires `metrics:read`.
@@ -958,4 +1008,4 @@ declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
958
1008
  declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
959
1009
  declare const METRICS_MAX_PAGE_SIZE = 500;
960
1010
 
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 };
1011
+ 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 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
@@ -396,14 +396,14 @@ function getStreamRowCount(stream) {
396
396
 
397
397
  // src/resources/index.ts
398
398
  function createExportResource(http, buildPath, buildQuery) {
399
- const exportFn = ((campaignId, params = {}) => {
399
+ const exportFn = ((id, params = {}) => {
400
400
  return http.getJsonl({
401
- path: buildPath(campaignId),
401
+ path: buildPath(id),
402
402
  query: buildQuery(params)
403
403
  });
404
404
  });
405
- exportFn.collect = async (campaignId, params = {}) => {
406
- const response = await exportFn(campaignId, params);
405
+ exportFn.collect = async (id, params = {}) => {
406
+ const response = await exportFn(id, params);
407
407
  if (response.error || !response.data) {
408
408
  return {
409
409
  data: null,
@@ -630,8 +630,14 @@ var CampaignsResource = class {
630
630
  var SoundlinksResource = class {
631
631
  constructor(http) {
632
632
  this.http = http;
633
+ this.breakdown = new SoundlinkBreakdownMetricsResource(http);
634
+ this.engagement = new SoundlinkEngagementMetricsResource(http);
633
635
  }
634
636
  http;
637
+ /** Per-day country breakdown and JSONL export. */
638
+ breakdown;
639
+ /** Per-day track engagement and JSONL export. */
640
+ engagement;
635
641
  /**
636
642
  * List self-serve soundlinks for the authenticated organization.
637
643
  *
@@ -687,18 +693,38 @@ var SoundlinksResource = class {
687
693
  }
688
694
  });
689
695
  }
696
+ };
697
+ var SoundlinkBreakdownMetricsResource = class {
698
+ constructor(http) {
699
+ this.http = http;
700
+ this.export = createExportResource(
701
+ http,
702
+ (soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown/export`,
703
+ (params) => ({
704
+ startDate: params.startDate,
705
+ endDate: params.endDate
706
+ })
707
+ );
708
+ }
709
+ http;
690
710
  /**
691
- * Per-day metrics for a soundlink (`soundlink_daily` schema).
711
+ * Stream full breakdown export as JSONL.
692
712
  *
693
- * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/timeseries`.
694
- * Max `pageSize` is **500** (default 50). Requires `soundlinks:read`.
713
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export`.
714
+ */
715
+ export;
716
+ /**
717
+ * Paginated per-day, per-country breakdown rows.
718
+ *
719
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/breakdown`.
720
+ * Max `pageSize` is **500** (default 50).
695
721
  *
696
722
  * @param soundlinkId - Soundlink identifier.
697
723
  * @param params - Date range, pagination, and sort options.
698
724
  */
699
- metricsTimeseries(soundlinkId, params = {}) {
725
+ list(soundlinkId, params = {}) {
700
726
  return this.http.get({
701
- path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/timeseries`,
727
+ path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/breakdown`,
702
728
  query: {
703
729
  startDate: params.startDate,
704
730
  endDate: params.endDate,
@@ -709,25 +735,43 @@ var SoundlinksResource = class {
709
735
  }
710
736
  });
711
737
  }
738
+ };
739
+ var SoundlinkEngagementMetricsResource = class {
740
+ constructor(http) {
741
+ this.http = http;
742
+ this.export = createExportResource(
743
+ http,
744
+ (soundlinkId) => `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement/export`,
745
+ (params) => ({
746
+ startDate: params.startDate,
747
+ endDate: params.endDate,
748
+ engagementContext: params.engagementContext
749
+ })
750
+ );
751
+ }
752
+ http;
712
753
  /**
713
- * Top tracks for a soundlink (period totals, not daily rows).
754
+ * Stream full engagement export as JSONL.
714
755
  *
715
- * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
716
- * Max `pageSize` is **100**. Requires `soundlinks:read`.
756
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export`.
757
+ */
758
+ export;
759
+ /**
760
+ * Paginated per-day, per-track engagement rows.
717
761
  *
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).
762
+ * Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
763
+ * Max `pageSize` is **500** (default 50).
721
764
  *
722
765
  * @param soundlinkId - Soundlink identifier.
723
- * @param params - Date range, pagination, and sort options.
766
+ * @param params - Date range, engagement context filter, pagination, and sort.
724
767
  */
725
- engagement(soundlinkId, params = {}) {
768
+ list(soundlinkId, params = {}) {
726
769
  return this.http.get({
727
770
  path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement`,
728
771
  query: {
729
772
  startDate: params.startDate,
730
773
  endDate: params.endDate,
774
+ engagementContext: params.engagementContext,
731
775
  page: params.page,
732
776
  pageSize: params.pageSize,
733
777
  sortBy: params.sortBy,