soundlink 2.0.0 → 2.1.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 +6 -0
- package/README.md +34 -1
- package/dist/cjs/index.cjs +114 -0
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +214 -2
- package/dist/esm/index.js +114 -1
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +909 -68
- package/package.json +2 -1
package/dist/esm/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Stable snake_case error codes returned by the Soundlink Public API. */
|
|
2
|
-
type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | '
|
|
2
|
+
type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | 'invalid_token' | 'insufficient_scope' | 'access_denied' | 'not_found' | 'campaign_not_found' | 'invalid_query_parameter' | 'invalid_date_range' | 'page_size_exceeded' | 'invalid_request' | 'invalid_genre' | 'invalid_duration_or_budget' | 'invalid_daily_budget' | 'invalid_duration_days' | 'invalid_spotify_url' | 'invalid_tier_budget_allocation' | 'invalid_tier_status' | 'tier_update_cooldown' | 'wallet_not_enabled' | 'insufficient_credit' | 'idempotency_key_conflict' | 'rate_limit_exceeded' | 'invalid_video_url' | 'video_import_limit_exceeded' | 'video_import_session_not_found' | 'internal_error';
|
|
3
3
|
/**
|
|
4
4
|
* Campaign lifecycle status.
|
|
5
5
|
*
|
|
@@ -26,10 +26,20 @@ type CampaignGeneration = 1 | 2 | 3;
|
|
|
26
26
|
type EngagementContext = 'catalog' | 'playlist';
|
|
27
27
|
/** Allowed `sortBy` values for {@link CampaignListParams}. */
|
|
28
28
|
type CampaignSortBy = 'createdAt' | 'status';
|
|
29
|
+
/** Allowed `sortBy` values for {@link SoundlinkListParams}. */
|
|
30
|
+
type SoundlinkSortBy = 'createdAt';
|
|
29
31
|
/** Allowed `sortBy` values for breakdown list requests. */
|
|
30
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';
|
|
31
37
|
/** Sort direction for list endpoints. */
|
|
32
38
|
type SortOrder = 'asc' | 'desc';
|
|
39
|
+
/** Lifecycle status for a self-serve soundlink. */
|
|
40
|
+
type SoundlinkStatus = 'draft' | 'active' | 'archived';
|
|
41
|
+
/** Spotify resource type promoted by a soundlink. */
|
|
42
|
+
type SoundlinkTargetType = 'track' | 'album' | 'playlist';
|
|
33
43
|
/** Growth strategy for campaign create / catalog. */
|
|
34
44
|
type StrategyType = 'maximum_growth' | 'market_discovery' | 'revenue_maximization' | 'custom';
|
|
35
45
|
/** Non-custom strategies (platform default tiering; no `tierTargeting`). */
|
|
@@ -369,6 +379,17 @@ interface CampaignListParams {
|
|
|
369
379
|
/** Sort direction. Default: `desc`. */
|
|
370
380
|
sortOrder?: SortOrder;
|
|
371
381
|
}
|
|
382
|
+
/** Query params for {@link SoundlinksResource.list}. */
|
|
383
|
+
interface SoundlinkListParams {
|
|
384
|
+
/** Page number (1-indexed). Default: `1`. */
|
|
385
|
+
page?: number;
|
|
386
|
+
/** Items per page. Default: `10`. Max: **100**. */
|
|
387
|
+
pageSize?: number;
|
|
388
|
+
/** Sort field. Default: `createdAt`. */
|
|
389
|
+
sortBy?: SoundlinkSortBy;
|
|
390
|
+
/** Sort direction. Default: `desc`. */
|
|
391
|
+
sortOrder?: SortOrder;
|
|
392
|
+
}
|
|
372
393
|
/** Inclusive date range filter (`YYYY-MM-DD`). */
|
|
373
394
|
interface DateRangeParams {
|
|
374
395
|
/** Inclusive start date. */
|
|
@@ -376,6 +397,120 @@ interface DateRangeParams {
|
|
|
376
397
|
/** Inclusive end date. Must not be before `startDate`. */
|
|
377
398
|
endDate?: string;
|
|
378
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
|
+
/** Self-serve soundlink summary from {@link SoundlinksResource.list}. */
|
|
427
|
+
interface SoundlinkSummary {
|
|
428
|
+
soundlinkId: string;
|
|
429
|
+
organizationId: string;
|
|
430
|
+
name: string;
|
|
431
|
+
/** Public landing page URL (`https://sndl.ink/soundlink/...`). */
|
|
432
|
+
url: string;
|
|
433
|
+
targetType: SoundlinkTargetType | null;
|
|
434
|
+
spotifyUrl: string | null;
|
|
435
|
+
status: SoundlinkStatus;
|
|
436
|
+
/** ISO 8601 creation timestamp. */
|
|
437
|
+
createdAt: string;
|
|
438
|
+
}
|
|
439
|
+
/** Full soundlink detail from {@link SoundlinksResource.get}. */
|
|
440
|
+
interface SoundlinkDetail extends SoundlinkSummary {
|
|
441
|
+
autoFollow: boolean;
|
|
442
|
+
metaPixelId: string | null;
|
|
443
|
+
tiktokPixelId: string | null;
|
|
444
|
+
}
|
|
445
|
+
/** Paginated soundlink list payload. */
|
|
446
|
+
interface SoundlinkListData {
|
|
447
|
+
items: SoundlinkSummary[];
|
|
448
|
+
pagination: Pagination;
|
|
449
|
+
}
|
|
450
|
+
/**
|
|
451
|
+
* Soundlink-level metric totals from {@link SoundlinksResource.metricsOverview}.
|
|
452
|
+
*
|
|
453
|
+
* No financial fields — ads for self-serve soundlinks run in the customer's Meta.
|
|
454
|
+
*/
|
|
455
|
+
interface SoundlinkMetricsOverview {
|
|
456
|
+
views: number;
|
|
457
|
+
link_clicks: number | null;
|
|
458
|
+
streams: number;
|
|
459
|
+
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
|
+
followers: number;
|
|
465
|
+
streams_per_listener: number;
|
|
466
|
+
ctr_lp: number | null;
|
|
467
|
+
}
|
|
468
|
+
/** One row of the `soundlink_daily` v1.0 schema. */
|
|
469
|
+
interface SoundlinkDailyRow {
|
|
470
|
+
provider: 'soundlink';
|
|
471
|
+
account_id: string;
|
|
472
|
+
schema_version: string;
|
|
473
|
+
/** UTC calendar date (`YYYY-MM-DD`). */
|
|
474
|
+
report_date: string;
|
|
475
|
+
report_date_timezone: 'UTC';
|
|
476
|
+
exported_at: string;
|
|
477
|
+
soundlink_id: string;
|
|
478
|
+
soundlink_name: string;
|
|
479
|
+
soundlink_target_type: SoundlinkTargetType | null;
|
|
480
|
+
soundlink_target_isrc: string | null;
|
|
481
|
+
soundlink_target_spotify_track_id: string | null;
|
|
482
|
+
soundlink_target_playlist_id: string | null;
|
|
483
|
+
views: number;
|
|
484
|
+
link_clicks: number | null;
|
|
485
|
+
streams: number;
|
|
486
|
+
listeners: number;
|
|
487
|
+
new_listeners: number | null;
|
|
488
|
+
returning_listeners: number | null;
|
|
489
|
+
new_listener_streams: number | null;
|
|
490
|
+
returning_listener_streams: number | null;
|
|
491
|
+
followers: number;
|
|
492
|
+
streams_per_listener: number;
|
|
493
|
+
ctr_lp: number | null;
|
|
494
|
+
}
|
|
495
|
+
/** Paginated soundlink timeseries payload. */
|
|
496
|
+
interface SoundlinkTimeseriesData {
|
|
497
|
+
schemaVersion: string;
|
|
498
|
+
items: SoundlinkDailyRow[];
|
|
499
|
+
pagination: Pagination;
|
|
500
|
+
}
|
|
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[];
|
|
512
|
+
pagination: Pagination;
|
|
513
|
+
}
|
|
379
514
|
/** Query params for {@link BreakdownMetricsResource.list}. */
|
|
380
515
|
interface BreakdownListParams extends DateRangeParams {
|
|
381
516
|
page?: number;
|
|
@@ -606,6 +741,80 @@ declare class CampaignsResource {
|
|
|
606
741
|
*/
|
|
607
742
|
listAll(params?: Omit<CampaignListParams, 'page'>): AsyncGenerator<CampaignListData['items'][number], void, void>;
|
|
608
743
|
}
|
|
744
|
+
/**
|
|
745
|
+
* Self-serve soundlinks (`/v1/soundlinks/*`). Requires `soundlinks:read`.
|
|
746
|
+
*
|
|
747
|
+
* Only soundlinks that are **not** linked to a campaign. Campaign-backed
|
|
748
|
+
* soundlinks are served by the Campaigns API.
|
|
749
|
+
*
|
|
750
|
+
* @example
|
|
751
|
+
* ```ts
|
|
752
|
+
* await soundlink.soundlinks.list();
|
|
753
|
+
* await soundlink.soundlinks.get(soundlinkId);
|
|
754
|
+
* await soundlink.soundlinks.metricsOverview(soundlinkId);
|
|
755
|
+
* ```
|
|
756
|
+
*/
|
|
757
|
+
declare class SoundlinksResource {
|
|
758
|
+
private readonly http;
|
|
759
|
+
constructor(http: HttpClient);
|
|
760
|
+
/**
|
|
761
|
+
* List self-serve soundlinks for the authenticated organization.
|
|
762
|
+
*
|
|
763
|
+
* Maps to `GET /v1/soundlinks`. Max `pageSize` is **100**. Requires `soundlinks:read`.
|
|
764
|
+
*
|
|
765
|
+
* @param params - Pagination and sort options.
|
|
766
|
+
*
|
|
767
|
+
* @example
|
|
768
|
+
* ```ts
|
|
769
|
+
* const { data, error } = await soundlink.soundlinks.list({ page: 1, pageSize: 100 });
|
|
770
|
+
* ```
|
|
771
|
+
*/
|
|
772
|
+
list(params?: SoundlinkListParams): Promise<ApiResponse<SoundlinkListData>>;
|
|
773
|
+
/**
|
|
774
|
+
* Fetch details for a single self-serve soundlink.
|
|
775
|
+
*
|
|
776
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:read`.
|
|
777
|
+
* Campaign-linked soundlinks return `404`.
|
|
778
|
+
*
|
|
779
|
+
* @param soundlinkId - Identifier returned by {@link SoundlinksResource.list}.
|
|
780
|
+
*/
|
|
781
|
+
get(soundlinkId: string): Promise<ApiResponse<SoundlinkDetail>>;
|
|
782
|
+
/**
|
|
783
|
+
* Soundlink-level metric totals for a date range.
|
|
784
|
+
*
|
|
785
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/overview`.
|
|
786
|
+
* Omit `startDate` to default to the soundlink creation date.
|
|
787
|
+
* No financial fields. Requires `soundlinks:read`.
|
|
788
|
+
*
|
|
789
|
+
* @param soundlinkId - Soundlink identifier.
|
|
790
|
+
* @param params - Inclusive `YYYY-MM-DD` date range.
|
|
791
|
+
*/
|
|
792
|
+
metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
|
|
793
|
+
/**
|
|
794
|
+
* Per-day metrics for a soundlink (`soundlink_daily` schema).
|
|
795
|
+
*
|
|
796
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/timeseries`.
|
|
797
|
+
* Max `pageSize` is **500** (default 50). Requires `soundlinks:read`.
|
|
798
|
+
*
|
|
799
|
+
* @param soundlinkId - Soundlink identifier.
|
|
800
|
+
* @param params - Date range, pagination, and sort options.
|
|
801
|
+
*/
|
|
802
|
+
metricsTimeseries(soundlinkId: string, params?: SoundlinkTimeseriesParams): Promise<ApiResponse<SoundlinkTimeseriesData>>;
|
|
803
|
+
/**
|
|
804
|
+
* Top tracks for a soundlink (period totals, not daily rows).
|
|
805
|
+
*
|
|
806
|
+
* 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).
|
|
812
|
+
*
|
|
813
|
+
* @param soundlinkId - Soundlink identifier.
|
|
814
|
+
* @param params - Date range, pagination, and sort options.
|
|
815
|
+
*/
|
|
816
|
+
engagement(soundlinkId: string, params?: SoundlinkEngagementParams): Promise<ApiResponse<SoundlinkEngagementData>>;
|
|
817
|
+
}
|
|
609
818
|
/**
|
|
610
819
|
* Campaign metrics (`/v1/campaigns/{id}/metrics/*`). Requires `metrics:read`.
|
|
611
820
|
*
|
|
@@ -712,6 +921,8 @@ declare class Soundlink {
|
|
|
712
921
|
readonly strategies: StrategiesResource;
|
|
713
922
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
714
923
|
readonly campaigns: CampaignsResource;
|
|
924
|
+
/** Self-serve soundlinks (list, detail, metrics). Requires `soundlinks:read` scope. */
|
|
925
|
+
readonly soundlinks: SoundlinksResource;
|
|
715
926
|
/** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
|
|
716
927
|
readonly metrics: MetricsResource;
|
|
717
928
|
/**
|
|
@@ -744,6 +955,7 @@ declare const DEFAULT_TIMEOUT_MS = 30000;
|
|
|
744
955
|
declare const DEFAULT_MAX_RETRIES = 2;
|
|
745
956
|
declare const API_KEY_PREFIX = "sk_";
|
|
746
957
|
declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
958
|
+
declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
|
|
747
959
|
declare const METRICS_MAX_PAGE_SIZE = 500;
|
|
748
960
|
|
|
749
|
-
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, type SocialPlatform, type SortOrder, Soundlink, type SoundlinkClientOptions, SoundlinkConfigError, type SoundlinkOptions, SoundlinkParseError, SoundlinkSdkError, type StrategiesCatalogData, type StrategyCatalogItem, type StrategyType, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignTiersRequest, getStreamRowCount, resolveClientOptions };
|
|
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 };
|
package/dist/esm/index.js
CHANGED
|
@@ -4,6 +4,7 @@ var DEFAULT_TIMEOUT_MS = 3e4;
|
|
|
4
4
|
var DEFAULT_MAX_RETRIES = 2;
|
|
5
5
|
var API_KEY_PREFIX = "sk_";
|
|
6
6
|
var CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
7
|
+
var SOUNDLINKS_MAX_PAGE_SIZE = 100;
|
|
7
8
|
var METRICS_MAX_PAGE_SIZE = 500;
|
|
8
9
|
var API_VERSION_PREFIX = "/v1";
|
|
9
10
|
|
|
@@ -626,6 +627,115 @@ var CampaignsResource = class {
|
|
|
626
627
|
}
|
|
627
628
|
}
|
|
628
629
|
};
|
|
630
|
+
var SoundlinksResource = class {
|
|
631
|
+
constructor(http) {
|
|
632
|
+
this.http = http;
|
|
633
|
+
}
|
|
634
|
+
http;
|
|
635
|
+
/**
|
|
636
|
+
* List self-serve soundlinks for the authenticated organization.
|
|
637
|
+
*
|
|
638
|
+
* Maps to `GET /v1/soundlinks`. Max `pageSize` is **100**. Requires `soundlinks:read`.
|
|
639
|
+
*
|
|
640
|
+
* @param params - Pagination and sort options.
|
|
641
|
+
*
|
|
642
|
+
* @example
|
|
643
|
+
* ```ts
|
|
644
|
+
* const { data, error } = await soundlink.soundlinks.list({ page: 1, pageSize: 100 });
|
|
645
|
+
* ```
|
|
646
|
+
*/
|
|
647
|
+
list(params = {}) {
|
|
648
|
+
return this.http.get({
|
|
649
|
+
path: "/soundlinks",
|
|
650
|
+
query: {
|
|
651
|
+
page: params.page,
|
|
652
|
+
pageSize: params.pageSize,
|
|
653
|
+
sortBy: params.sortBy,
|
|
654
|
+
sortOrder: params.sortOrder
|
|
655
|
+
}
|
|
656
|
+
});
|
|
657
|
+
}
|
|
658
|
+
/**
|
|
659
|
+
* Fetch details for a single self-serve soundlink.
|
|
660
|
+
*
|
|
661
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}`. Requires `soundlinks:read`.
|
|
662
|
+
* Campaign-linked soundlinks return `404`.
|
|
663
|
+
*
|
|
664
|
+
* @param soundlinkId - Identifier returned by {@link SoundlinksResource.list}.
|
|
665
|
+
*/
|
|
666
|
+
get(soundlinkId) {
|
|
667
|
+
return this.http.get({
|
|
668
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}`
|
|
669
|
+
});
|
|
670
|
+
}
|
|
671
|
+
/**
|
|
672
|
+
* Soundlink-level metric totals for a date range.
|
|
673
|
+
*
|
|
674
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/overview`.
|
|
675
|
+
* Omit `startDate` to default to the soundlink creation date.
|
|
676
|
+
* No financial fields. Requires `soundlinks:read`.
|
|
677
|
+
*
|
|
678
|
+
* @param soundlinkId - Soundlink identifier.
|
|
679
|
+
* @param params - Inclusive `YYYY-MM-DD` date range.
|
|
680
|
+
*/
|
|
681
|
+
metricsOverview(soundlinkId, params = {}) {
|
|
682
|
+
return this.http.get({
|
|
683
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/overview`,
|
|
684
|
+
query: {
|
|
685
|
+
startDate: params.startDate,
|
|
686
|
+
endDate: params.endDate
|
|
687
|
+
}
|
|
688
|
+
});
|
|
689
|
+
}
|
|
690
|
+
/**
|
|
691
|
+
* Per-day metrics for a soundlink (`soundlink_daily` schema).
|
|
692
|
+
*
|
|
693
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/timeseries`.
|
|
694
|
+
* Max `pageSize` is **500** (default 50). Requires `soundlinks:read`.
|
|
695
|
+
*
|
|
696
|
+
* @param soundlinkId - Soundlink identifier.
|
|
697
|
+
* @param params - Date range, pagination, and sort options.
|
|
698
|
+
*/
|
|
699
|
+
metricsTimeseries(soundlinkId, params = {}) {
|
|
700
|
+
return this.http.get({
|
|
701
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/timeseries`,
|
|
702
|
+
query: {
|
|
703
|
+
startDate: params.startDate,
|
|
704
|
+
endDate: params.endDate,
|
|
705
|
+
page: params.page,
|
|
706
|
+
pageSize: params.pageSize,
|
|
707
|
+
sortBy: params.sortBy,
|
|
708
|
+
sortOrder: params.sortOrder
|
|
709
|
+
}
|
|
710
|
+
});
|
|
711
|
+
}
|
|
712
|
+
/**
|
|
713
|
+
* Top tracks for a soundlink (period totals, not daily rows).
|
|
714
|
+
*
|
|
715
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/engagement`.
|
|
716
|
+
* Max `pageSize` is **100**. Requires `soundlinks:read`.
|
|
717
|
+
*
|
|
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).
|
|
721
|
+
*
|
|
722
|
+
* @param soundlinkId - Soundlink identifier.
|
|
723
|
+
* @param params - Date range, pagination, and sort options.
|
|
724
|
+
*/
|
|
725
|
+
engagement(soundlinkId, params = {}) {
|
|
726
|
+
return this.http.get({
|
|
727
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/engagement`,
|
|
728
|
+
query: {
|
|
729
|
+
startDate: params.startDate,
|
|
730
|
+
endDate: params.endDate,
|
|
731
|
+
page: params.page,
|
|
732
|
+
pageSize: params.pageSize,
|
|
733
|
+
sortBy: params.sortBy,
|
|
734
|
+
sortOrder: params.sortOrder
|
|
735
|
+
}
|
|
736
|
+
});
|
|
737
|
+
}
|
|
738
|
+
};
|
|
629
739
|
var MetricsResource = class {
|
|
630
740
|
constructor(http) {
|
|
631
741
|
this.http = http;
|
|
@@ -736,6 +846,8 @@ var Soundlink = class {
|
|
|
736
846
|
strategies;
|
|
737
847
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
738
848
|
campaigns;
|
|
849
|
+
/** Self-serve soundlinks (list, detail, metrics). Requires `soundlinks:read` scope. */
|
|
850
|
+
soundlinks;
|
|
739
851
|
/** Campaign metrics, breakdowns, and JSONL exports. Requires `metrics:read` scope. */
|
|
740
852
|
metrics;
|
|
741
853
|
/**
|
|
@@ -749,10 +861,11 @@ var Soundlink = class {
|
|
|
749
861
|
this.ping = pingResource.ping.bind(pingResource);
|
|
750
862
|
this.strategies = new StrategiesResource(http);
|
|
751
863
|
this.campaigns = new CampaignsResource(http);
|
|
864
|
+
this.soundlinks = new SoundlinksResource(http);
|
|
752
865
|
this.metrics = new MetricsResource(http);
|
|
753
866
|
}
|
|
754
867
|
};
|
|
755
868
|
|
|
756
|
-
export { API_KEY_PREFIX, CAMPAIGNS_MAX_PAGE_SIZE, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, HttpClient, METRICS_MAX_PAGE_SIZE, Soundlink, SoundlinkConfigError, SoundlinkParseError, SoundlinkSdkError, getStreamRowCount, resolveClientOptions };
|
|
869
|
+
export { API_KEY_PREFIX, CAMPAIGNS_MAX_PAGE_SIZE, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, HttpClient, METRICS_MAX_PAGE_SIZE, SOUNDLINKS_MAX_PAGE_SIZE, Soundlink, SoundlinkConfigError, SoundlinkParseError, SoundlinkSdkError, getStreamRowCount, resolveClientOptions };
|
|
757
870
|
//# sourceMappingURL=index.js.map
|
|
758
871
|
//# sourceMappingURL=index.js.map
|