soundlink 2.5.0 → 2.7.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 +12 -0
- package/README.md +32 -0
- package/dist/cjs/index.cjs +136 -10
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +203 -2
- package/dist/esm/index.js +136 -11
- package/dist/esm/index.js.map +1 -1
- package/package.json +1 -1
package/dist/esm/index.d.ts
CHANGED
|
@@ -243,6 +243,28 @@ interface WalletData {
|
|
|
243
243
|
/** ISO 8601. `null` when the organization has no credits row. */
|
|
244
244
|
updatedAt: string | null;
|
|
245
245
|
}
|
|
246
|
+
/** Ad platform for an organization pixel. Only `meta` is supported today. */
|
|
247
|
+
type PixelPlatform = 'meta';
|
|
248
|
+
/** One pixel from {@link PixelsResource.list} / {@link PixelsResource.update}. */
|
|
249
|
+
interface Pixel {
|
|
250
|
+
id: string;
|
|
251
|
+
platform: PixelPlatform;
|
|
252
|
+
}
|
|
253
|
+
/** Payload from `GET /v1/pixels`. */
|
|
254
|
+
interface PixelListData {
|
|
255
|
+
pixels: Pixel[];
|
|
256
|
+
}
|
|
257
|
+
/** Body for `PUT /v1/pixels/{pixelId}`. */
|
|
258
|
+
interface UpdatePixelRequest {
|
|
259
|
+
platform: PixelPlatform;
|
|
260
|
+
/** Conversions API access token. Stored and never returned. */
|
|
261
|
+
accessToken: string;
|
|
262
|
+
}
|
|
263
|
+
/** Payload from `POST /v1/pixels/{pixelId}/test-events`. */
|
|
264
|
+
interface PixelTestEventData {
|
|
265
|
+
status: 'sent';
|
|
266
|
+
pixelId: string;
|
|
267
|
+
}
|
|
246
268
|
/** One variant under a creative group (`GET .../metrics/creatives`). */
|
|
247
269
|
interface CreativeMetricsChild {
|
|
248
270
|
caption: string | null;
|
|
@@ -730,10 +752,104 @@ interface EngagementExportParams extends DateRangeParams {
|
|
|
730
752
|
}
|
|
731
753
|
/** Query params for breakdown JSONL export. Max **90 days** per request. */
|
|
732
754
|
type BreakdownExportParams = DateRangeParams;
|
|
755
|
+
/**
|
|
756
|
+
* One row of the `soundlink_cohort_retention_daily` v1.0 schema.
|
|
757
|
+
* Day-N fields are `null` until that day has passed for the cohort date.
|
|
758
|
+
*/
|
|
759
|
+
interface CohortRetentionDailyRow {
|
|
760
|
+
provider: 'soundlink';
|
|
761
|
+
account_id: string;
|
|
762
|
+
schema_version: string;
|
|
763
|
+
/** UTC calendar date (`YYYY-MM-DD`). */
|
|
764
|
+
cohort_date: string;
|
|
765
|
+
cohort_date_timezone: 'UTC';
|
|
766
|
+
exported_at: string;
|
|
767
|
+
soundlink_id: string;
|
|
768
|
+
soundlink_name: string;
|
|
769
|
+
soundlink_target_type: 'track' | 'playlist' | null;
|
|
770
|
+
soundlink_target_isrc?: string | null;
|
|
771
|
+
soundlink_target_spotify_track_id?: string | null;
|
|
772
|
+
soundlink_target_playlist_id?: string | null;
|
|
773
|
+
cohort_size: number;
|
|
774
|
+
returned_on_day_1: number | null;
|
|
775
|
+
retention_by_day_1: number | null;
|
|
776
|
+
returned_on_day_2: number | null;
|
|
777
|
+
retention_by_day_2: number | null;
|
|
778
|
+
returned_on_day_3: number | null;
|
|
779
|
+
retention_by_day_3: number | null;
|
|
780
|
+
returned_on_day_4: number | null;
|
|
781
|
+
retention_by_day_4: number | null;
|
|
782
|
+
returned_on_day_5: number | null;
|
|
783
|
+
retention_by_day_5: number | null;
|
|
784
|
+
returned_on_day_6: number | null;
|
|
785
|
+
retention_by_day_6: number | null;
|
|
786
|
+
returned_on_day_7: number | null;
|
|
787
|
+
retention_by_day_7: number | null;
|
|
788
|
+
}
|
|
789
|
+
/** Payload from campaign/soundlink `metrics/retention`. */
|
|
790
|
+
interface CohortRetentionListData {
|
|
791
|
+
schemaVersion: string;
|
|
792
|
+
items: CohortRetentionDailyRow[];
|
|
793
|
+
}
|
|
794
|
+
/** Path param for listening-insights endpoints. */
|
|
795
|
+
type ListeningInsight = 'other-artists' | 'catalog-dig-in' | 'stream-split';
|
|
796
|
+
/** Date window returned with every listening insight (from the listening graph). */
|
|
797
|
+
interface ListeningInsightWindow {
|
|
798
|
+
startDate: string;
|
|
799
|
+
endDate: string;
|
|
800
|
+
}
|
|
801
|
+
interface OtherArtistsInsightArtist {
|
|
802
|
+
/** Lowercased, trimmed artist name. */
|
|
803
|
+
artist: string;
|
|
804
|
+
listeners: number;
|
|
805
|
+
streams: number;
|
|
806
|
+
}
|
|
807
|
+
interface OtherArtistsListeningInsight {
|
|
808
|
+
soundlinkId: string;
|
|
809
|
+
campaignId: string | null;
|
|
810
|
+
insight: 'other-artists';
|
|
811
|
+
window: ListeningInsightWindow;
|
|
812
|
+
artists: OtherArtistsInsightArtist[];
|
|
813
|
+
}
|
|
814
|
+
interface CatalogDigInInsightArtist {
|
|
815
|
+
artist: string;
|
|
816
|
+
playlistListeners: number;
|
|
817
|
+
playlistStreams: number;
|
|
818
|
+
catalogListeners: number;
|
|
819
|
+
catalogStreams: number;
|
|
820
|
+
catalogTracks: number;
|
|
821
|
+
/** catalogListeners / playlistListeners. Null when playlistListeners is 0. */
|
|
822
|
+
catalogListenerRate: number | null;
|
|
823
|
+
}
|
|
824
|
+
interface CatalogDigInListeningInsight {
|
|
825
|
+
soundlinkId: string;
|
|
826
|
+
campaignId: string | null;
|
|
827
|
+
insight: 'catalog-dig-in';
|
|
828
|
+
window: ListeningInsightWindow;
|
|
829
|
+
artists: CatalogDigInInsightArtist[];
|
|
830
|
+
}
|
|
831
|
+
type StreamSplitEngagementContext = 'promoted' | 'playlist' | 'artist_catalog';
|
|
832
|
+
interface StreamSplitContext {
|
|
833
|
+
engagementContext: StreamSplitEngagementContext;
|
|
834
|
+
listeners: number;
|
|
835
|
+
streams: number;
|
|
836
|
+
tracks: number;
|
|
837
|
+
}
|
|
838
|
+
interface StreamSplitListeningInsight {
|
|
839
|
+
soundlinkId: string;
|
|
840
|
+
campaignId: string | null;
|
|
841
|
+
insight: 'stream-split';
|
|
842
|
+
window: ListeningInsightWindow;
|
|
843
|
+
contexts: StreamSplitContext[];
|
|
844
|
+
}
|
|
845
|
+
/** Discriminated on `insight`. */
|
|
846
|
+
type ListeningInsightsData = OtherArtistsListeningInsight | CatalogDigInListeningInsight | StreamSplitListeningInsight;
|
|
733
847
|
|
|
734
848
|
interface HttpGetOptions {
|
|
735
849
|
path: string;
|
|
736
850
|
query?: Record<string, string | number | boolean | undefined | null>;
|
|
851
|
+
/** Override the client timeout for this request only (milliseconds). */
|
|
852
|
+
timeout?: number;
|
|
737
853
|
}
|
|
738
854
|
interface HttpJsonlOptions extends HttpGetOptions {
|
|
739
855
|
accept?: string;
|
|
@@ -763,7 +879,7 @@ declare class HttpClient {
|
|
|
763
879
|
private readonly options;
|
|
764
880
|
constructor(options: SoundlinkOptions);
|
|
765
881
|
get resolvedOptions(): ResolvedSoundlinkClientOptions;
|
|
766
|
-
get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
|
|
882
|
+
get<T>({ path, query, timeout }: HttpGetOptions): Promise<ApiResponse<T>>;
|
|
767
883
|
post<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
768
884
|
patch<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
769
885
|
put<T>({ path, body, query, headers, idempotencyKey, }: HttpMutationOptions): Promise<ApiResponse<T>>;
|
|
@@ -858,6 +974,53 @@ declare class StrategiesResource {
|
|
|
858
974
|
*/
|
|
859
975
|
list(): Promise<ApiResponse<StrategiesCatalogData>>;
|
|
860
976
|
}
|
|
977
|
+
/**
|
|
978
|
+
* Organization Meta pixels (`/v1/pixels`).
|
|
979
|
+
* Read needs `pixels:read`; write and test-events need `pixels:write`.
|
|
980
|
+
*/
|
|
981
|
+
declare class PixelsResource {
|
|
982
|
+
private readonly http;
|
|
983
|
+
constructor(http: HttpClient);
|
|
984
|
+
/**
|
|
985
|
+
* List Meta pixels saved for the organization.
|
|
986
|
+
*
|
|
987
|
+
* Maps to `GET /v1/pixels`. Requires `pixels:read`.
|
|
988
|
+
* Returns `403 custom_pixel_not_enabled` when the feature is off.
|
|
989
|
+
*
|
|
990
|
+
* @example
|
|
991
|
+
* ```ts
|
|
992
|
+
* const { data } = await soundlink.pixels.list();
|
|
993
|
+
* ```
|
|
994
|
+
*/
|
|
995
|
+
list(): Promise<ApiResponse<PixelListData>>;
|
|
996
|
+
/**
|
|
997
|
+
* Save or rotate a Meta pixel access token.
|
|
998
|
+
*
|
|
999
|
+
* Maps to `PUT /v1/pixels/{pixelId}`. Requires `pixels:write`.
|
|
1000
|
+
* Does not require an `Idempotency-Key`. The access token is never returned.
|
|
1001
|
+
*
|
|
1002
|
+
* @example
|
|
1003
|
+
* ```ts
|
|
1004
|
+
* const { data } = await soundlink.pixels.update('1234567890123456', {
|
|
1005
|
+
* platform: 'meta',
|
|
1006
|
+
* accessToken: process.env.META_CAPI_TOKEN!,
|
|
1007
|
+
* });
|
|
1008
|
+
* ```
|
|
1009
|
+
*/
|
|
1010
|
+
update(pixelId: string, body: UpdatePixelRequest): Promise<ApiResponse<Pixel>>;
|
|
1011
|
+
/**
|
|
1012
|
+
* Send a live Meta Conversions API test event to a saved pixel.
|
|
1013
|
+
*
|
|
1014
|
+
* Maps to `POST /v1/pixels/{pixelId}/test-events`. Requires `pixels:write`.
|
|
1015
|
+
* This is not a sandbox event — it appears in Events Manager.
|
|
1016
|
+
*
|
|
1017
|
+
* @example
|
|
1018
|
+
* ```ts
|
|
1019
|
+
* const { data } = await soundlink.pixels.sendTestEvent('1234567890123456');
|
|
1020
|
+
* ```
|
|
1021
|
+
*/
|
|
1022
|
+
sendTestEvent(pixelId: string): Promise<ApiResponse<PixelTestEventData>>;
|
|
1023
|
+
}
|
|
861
1024
|
/** Campaign tiers (`/v1/campaigns/{id}/tiers`). Wallet only (`generation: 3`). */
|
|
862
1025
|
declare class CampaignTiersResource {
|
|
863
1026
|
private readonly http;
|
|
@@ -912,6 +1075,15 @@ declare class CampaignsResource {
|
|
|
912
1075
|
* Omit `startDate` for the full history. Max `pageSize` is **100**.
|
|
913
1076
|
*/
|
|
914
1077
|
activity(campaignId: string, params?: CampaignActivityParams): Promise<ApiResponse<CampaignActivityData>>;
|
|
1078
|
+
/**
|
|
1079
|
+
* What listeners who connected through this campaign went on to play.
|
|
1080
|
+
*
|
|
1081
|
+
* Maps to `GET /v1/campaigns/{campaignId}/listening-insights/{insight}`.
|
|
1082
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
1083
|
+
* Date window comes from the listening graph — do not send `startDate`/`endDate`.
|
|
1084
|
+
* Uses a 120s timeout (insights often take 30–50s).
|
|
1085
|
+
*/
|
|
1086
|
+
listeningInsights(campaignId: string, insight: ListeningInsight): Promise<ApiResponse<ListeningInsightsData>>;
|
|
915
1087
|
/**
|
|
916
1088
|
* Create a wallet-funded campaign.
|
|
917
1089
|
*
|
|
@@ -1057,6 +1229,23 @@ declare class SoundlinksResource {
|
|
|
1057
1229
|
* @param params - Inclusive `YYYY-MM-DD` date range.
|
|
1058
1230
|
*/
|
|
1059
1231
|
metricsOverview(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<SoundlinkMetricsOverview>>;
|
|
1232
|
+
/**
|
|
1233
|
+
* Cohort retention for a soundlink (`soundlink_cohort_retention_daily`).
|
|
1234
|
+
*
|
|
1235
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/retention`.
|
|
1236
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
1237
|
+
* One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
|
|
1238
|
+
*/
|
|
1239
|
+
retention(soundlinkId: string, params?: DateRangeParams): Promise<ApiResponse<CohortRetentionListData>>;
|
|
1240
|
+
/**
|
|
1241
|
+
* What listeners who connected through this soundlink went on to play.
|
|
1242
|
+
*
|
|
1243
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/listening-insights/{insight}`.
|
|
1244
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
1245
|
+
* Date window comes from the listening graph — do not send `startDate`/`endDate`.
|
|
1246
|
+
* Uses a 120s timeout (insights often take 30–50s).
|
|
1247
|
+
*/
|
|
1248
|
+
listeningInsights(soundlinkId: string, insight: ListeningInsight): Promise<ApiResponse<ListeningInsightsData>>;
|
|
1060
1249
|
}
|
|
1061
1250
|
/**
|
|
1062
1251
|
* Country-level daily metrics (`soundlink_country_daily` schema).
|
|
@@ -1158,6 +1347,14 @@ declare class MetricsResource {
|
|
|
1158
1347
|
* Max `pageSize` is **500**.
|
|
1159
1348
|
*/
|
|
1160
1349
|
creativeDaily(campaignId: string, params?: CreativeDailyParams): Promise<ApiResponse<CreativeDailyData>>;
|
|
1350
|
+
/**
|
|
1351
|
+
* Cohort retention for the campaign's linked soundlink (`soundlink_cohort_retention_daily`).
|
|
1352
|
+
*
|
|
1353
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/retention`.
|
|
1354
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
1355
|
+
* One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
|
|
1356
|
+
*/
|
|
1357
|
+
retention(campaignId: string, params?: DateRangeParams): Promise<ApiResponse<CohortRetentionListData>>;
|
|
1161
1358
|
}
|
|
1162
1359
|
/**
|
|
1163
1360
|
* Country-level daily metrics (`campaign_country_daily` schema).
|
|
@@ -1229,6 +1426,8 @@ declare class Soundlink {
|
|
|
1229
1426
|
readonly wallet: WalletResource;
|
|
1230
1427
|
/** Growth strategy catalog. Requires `campaigns:read` scope. */
|
|
1231
1428
|
readonly strategies: StrategiesResource;
|
|
1429
|
+
/** Organization Meta pixels. Read needs `pixels:read`; write needs `pixels:write`. */
|
|
1430
|
+
readonly pixels: PixelsResource;
|
|
1232
1431
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
1233
1432
|
readonly campaigns: CampaignsResource;
|
|
1234
1433
|
/** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
|
|
@@ -1262,10 +1461,12 @@ declare class SoundlinkConfigError extends SoundlinkSdkError {
|
|
|
1262
1461
|
|
|
1263
1462
|
declare const DEFAULT_BASE_URL = "https://api.getsoundlink.com";
|
|
1264
1463
|
declare const DEFAULT_TIMEOUT_MS = 30000;
|
|
1464
|
+
/** Listening insights often take 30–50s; the Public API recommends ≥120s. */
|
|
1465
|
+
declare const LISTENING_INSIGHTS_TIMEOUT_MS = 120000;
|
|
1265
1466
|
declare const DEFAULT_MAX_RETRIES = 2;
|
|
1266
1467
|
declare const API_KEY_PREFIX = "sk_";
|
|
1267
1468
|
declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
1268
1469
|
declare const SOUNDLINKS_MAX_PAGE_SIZE = 100;
|
|
1269
1470
|
declare const METRICS_MAX_PAGE_SIZE = 500;
|
|
1270
1471
|
|
|
1271
|
-
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 CampaignActivityData, type CampaignActivityItem, type CampaignActivityParams, type CampaignAutoRenewData, 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 CreativeDailyData, type CreativeDailyParams, type CreativeDailyRow, type CreativeDirection, type CreativeMetrics, type CreativeMetricsChild, type CreativeMetricsGroup, 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 TierLearningStatus, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignAutoRenewRequest, type UpdateCampaignTiersRequest, type WalletData, getStreamRowCount, resolveClientOptions };
|
|
1472
|
+
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 CampaignActivityData, type CampaignActivityItem, type CampaignActivityParams, type CampaignAutoRenewData, type CampaignCreateData, type CampaignDetail, type CampaignGeneration, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignStopData, type CampaignSummary, type CampaignTier, type CampaignTiersData, type CatalogDigInInsightArtist, type CatalogDigInListeningInsight, type CohortRetentionDailyRow, type CohortRetentionListData, type CreateCampaignRequest, type CreateCampaignRequestBase, type CreateCampaignRequestBuiltIn, type CreateCampaignRequestCustom, type CreateSoundlinkRequest, type CreativeDailyData, type CreativeDailyParams, type CreativeDailyRow, type CreativeDirection, type CreativeMetrics, type CreativeMetricsChild, type CreativeMetricsGroup, 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, LISTENING_INSIGHTS_TIMEOUT_MS, type ListeningInsight, type ListeningInsightWindow, type ListeningInsightsData, METRICS_MAX_PAGE_SIZE, type MetricsOverview, type OtherArtistsInsightArtist, type OtherArtistsListeningInsight, type Pagination, type PingData, type Pixel, type PixelListData, type PixelPlatform, type PixelTestEventData, 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 StreamSplitContext, type StreamSplitEngagementContext, type StreamSplitListeningInsight, type TierLearningStatus, type TierStatusUpdateItem, type TierTargeting, type UpdateCampaignAutoRenewRequest, type UpdateCampaignTiersRequest, type UpdatePixelRequest, type WalletData, getStreamRowCount, resolveClientOptions };
|
package/dist/esm/index.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// src/constants/defaults.ts
|
|
2
2
|
var DEFAULT_BASE_URL = "https://api.getsoundlink.com";
|
|
3
3
|
var DEFAULT_TIMEOUT_MS = 3e4;
|
|
4
|
+
var LISTENING_INSIGHTS_TIMEOUT_MS = 12e4;
|
|
4
5
|
var DEFAULT_MAX_RETRIES = 2;
|
|
5
6
|
var API_KEY_PREFIX = "sk_";
|
|
6
7
|
var CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
@@ -197,15 +198,19 @@ var HttpClient = class {
|
|
|
197
198
|
get resolvedOptions() {
|
|
198
199
|
return this.options;
|
|
199
200
|
}
|
|
200
|
-
async get({ path, query }) {
|
|
201
|
+
async get({ path, query, timeout }) {
|
|
201
202
|
const url = joinUrl(
|
|
202
203
|
this.options.baseUrl,
|
|
203
204
|
`${API_VERSION_PREFIX}${path}${buildQueryString(query ?? {})}`
|
|
204
205
|
);
|
|
205
|
-
return this.requestJson(
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
206
|
+
return this.requestJson(
|
|
207
|
+
url,
|
|
208
|
+
{
|
|
209
|
+
method: "GET",
|
|
210
|
+
headers: this.buildHeaders()
|
|
211
|
+
},
|
|
212
|
+
timeout
|
|
213
|
+
);
|
|
209
214
|
}
|
|
210
215
|
async post({
|
|
211
216
|
path,
|
|
@@ -328,10 +333,10 @@ var HttpClient = class {
|
|
|
328
333
|
...extra
|
|
329
334
|
};
|
|
330
335
|
}
|
|
331
|
-
async requestJson(url, init) {
|
|
336
|
+
async requestJson(url, init, timeoutMs) {
|
|
332
337
|
let response;
|
|
333
338
|
try {
|
|
334
|
-
response = await this.fetchWithRetry(url, init);
|
|
339
|
+
response = await this.fetchWithRetry(url, init, timeoutMs);
|
|
335
340
|
} catch (error) {
|
|
336
341
|
throw toTransportError(error);
|
|
337
342
|
}
|
|
@@ -377,12 +382,13 @@ var HttpClient = class {
|
|
|
377
382
|
...retryAfter !== void 0 ? { retryAfter } : {}
|
|
378
383
|
});
|
|
379
384
|
}
|
|
380
|
-
async fetchWithRetry(url, init) {
|
|
385
|
+
async fetchWithRetry(url, init, timeoutMs) {
|
|
381
386
|
const { maxRetries, timeout, fetch } = this.options;
|
|
387
|
+
const requestTimeout = timeoutMs ?? timeout;
|
|
382
388
|
let attempt = 0;
|
|
383
389
|
let response = await fetch(url, {
|
|
384
390
|
...init,
|
|
385
|
-
signal: AbortSignal.timeout(
|
|
391
|
+
signal: AbortSignal.timeout(requestTimeout)
|
|
386
392
|
});
|
|
387
393
|
while (attempt < maxRetries && (response.status === 429 || response.status >= 500)) {
|
|
388
394
|
const retryAfter = parseRetryAfterHeader(response.headers.get("Retry-After"));
|
|
@@ -391,7 +397,7 @@ var HttpClient = class {
|
|
|
391
397
|
await sleep(delayMs);
|
|
392
398
|
response = await fetch(url, {
|
|
393
399
|
...init,
|
|
394
|
-
signal: AbortSignal.timeout(
|
|
400
|
+
signal: AbortSignal.timeout(requestTimeout)
|
|
395
401
|
});
|
|
396
402
|
}
|
|
397
403
|
return response;
|
|
@@ -509,6 +515,62 @@ var StrategiesResource = class {
|
|
|
509
515
|
return this.http.get({ path: "/strategies" });
|
|
510
516
|
}
|
|
511
517
|
};
|
|
518
|
+
var PixelsResource = class {
|
|
519
|
+
constructor(http) {
|
|
520
|
+
this.http = http;
|
|
521
|
+
}
|
|
522
|
+
http;
|
|
523
|
+
/**
|
|
524
|
+
* List Meta pixels saved for the organization.
|
|
525
|
+
*
|
|
526
|
+
* Maps to `GET /v1/pixels`. Requires `pixels:read`.
|
|
527
|
+
* Returns `403 custom_pixel_not_enabled` when the feature is off.
|
|
528
|
+
*
|
|
529
|
+
* @example
|
|
530
|
+
* ```ts
|
|
531
|
+
* const { data } = await soundlink.pixels.list();
|
|
532
|
+
* ```
|
|
533
|
+
*/
|
|
534
|
+
list() {
|
|
535
|
+
return this.http.get({ path: "/pixels" });
|
|
536
|
+
}
|
|
537
|
+
/**
|
|
538
|
+
* Save or rotate a Meta pixel access token.
|
|
539
|
+
*
|
|
540
|
+
* Maps to `PUT /v1/pixels/{pixelId}`. Requires `pixels:write`.
|
|
541
|
+
* Does not require an `Idempotency-Key`. The access token is never returned.
|
|
542
|
+
*
|
|
543
|
+
* @example
|
|
544
|
+
* ```ts
|
|
545
|
+
* const { data } = await soundlink.pixels.update('1234567890123456', {
|
|
546
|
+
* platform: 'meta',
|
|
547
|
+
* accessToken: process.env.META_CAPI_TOKEN!,
|
|
548
|
+
* });
|
|
549
|
+
* ```
|
|
550
|
+
*/
|
|
551
|
+
update(pixelId, body) {
|
|
552
|
+
return this.http.put({
|
|
553
|
+
path: `/pixels/${encodeURIComponent(pixelId)}`,
|
|
554
|
+
body
|
|
555
|
+
});
|
|
556
|
+
}
|
|
557
|
+
/**
|
|
558
|
+
* Send a live Meta Conversions API test event to a saved pixel.
|
|
559
|
+
*
|
|
560
|
+
* Maps to `POST /v1/pixels/{pixelId}/test-events`. Requires `pixels:write`.
|
|
561
|
+
* This is not a sandbox event — it appears in Events Manager.
|
|
562
|
+
*
|
|
563
|
+
* @example
|
|
564
|
+
* ```ts
|
|
565
|
+
* const { data } = await soundlink.pixels.sendTestEvent('1234567890123456');
|
|
566
|
+
* ```
|
|
567
|
+
*/
|
|
568
|
+
sendTestEvent(pixelId) {
|
|
569
|
+
return this.http.post({
|
|
570
|
+
path: `/pixels/${encodeURIComponent(pixelId)}/test-events`
|
|
571
|
+
});
|
|
572
|
+
}
|
|
573
|
+
};
|
|
512
574
|
var CampaignTiersResource = class {
|
|
513
575
|
constructor(http) {
|
|
514
576
|
this.http = http;
|
|
@@ -598,6 +660,20 @@ var CampaignsResource = class {
|
|
|
598
660
|
}
|
|
599
661
|
});
|
|
600
662
|
}
|
|
663
|
+
/**
|
|
664
|
+
* What listeners who connected through this campaign went on to play.
|
|
665
|
+
*
|
|
666
|
+
* Maps to `GET /v1/campaigns/{campaignId}/listening-insights/{insight}`.
|
|
667
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
668
|
+
* Date window comes from the listening graph — do not send `startDate`/`endDate`.
|
|
669
|
+
* Uses a 120s timeout (insights often take 30–50s).
|
|
670
|
+
*/
|
|
671
|
+
listeningInsights(campaignId, insight) {
|
|
672
|
+
return this.http.get({
|
|
673
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/listening-insights/${encodeURIComponent(insight)}`,
|
|
674
|
+
timeout: LISTENING_INSIGHTS_TIMEOUT_MS
|
|
675
|
+
});
|
|
676
|
+
}
|
|
601
677
|
/**
|
|
602
678
|
* Create a wallet-funded campaign.
|
|
603
679
|
*
|
|
@@ -806,6 +882,36 @@ var SoundlinksResource = class {
|
|
|
806
882
|
}
|
|
807
883
|
});
|
|
808
884
|
}
|
|
885
|
+
/**
|
|
886
|
+
* Cohort retention for a soundlink (`soundlink_cohort_retention_daily`).
|
|
887
|
+
*
|
|
888
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/metrics/retention`.
|
|
889
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
890
|
+
* One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
|
|
891
|
+
*/
|
|
892
|
+
retention(soundlinkId, params = {}) {
|
|
893
|
+
return this.http.get({
|
|
894
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/metrics/retention`,
|
|
895
|
+
query: {
|
|
896
|
+
startDate: params.startDate,
|
|
897
|
+
endDate: params.endDate
|
|
898
|
+
}
|
|
899
|
+
});
|
|
900
|
+
}
|
|
901
|
+
/**
|
|
902
|
+
* What listeners who connected through this soundlink went on to play.
|
|
903
|
+
*
|
|
904
|
+
* Maps to `GET /v1/soundlinks/{soundlinkId}/listening-insights/{insight}`.
|
|
905
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
906
|
+
* Date window comes from the listening graph — do not send `startDate`/`endDate`.
|
|
907
|
+
* Uses a 120s timeout (insights often take 30–50s).
|
|
908
|
+
*/
|
|
909
|
+
listeningInsights(soundlinkId, insight) {
|
|
910
|
+
return this.http.get({
|
|
911
|
+
path: `/soundlinks/${encodeURIComponent(soundlinkId)}/listening-insights/${encodeURIComponent(insight)}`,
|
|
912
|
+
timeout: LISTENING_INSIGHTS_TIMEOUT_MS
|
|
913
|
+
});
|
|
914
|
+
}
|
|
809
915
|
};
|
|
810
916
|
var SoundlinkBreakdownMetricsResource = class {
|
|
811
917
|
constructor(http) {
|
|
@@ -959,6 +1065,22 @@ var MetricsResource = class {
|
|
|
959
1065
|
}
|
|
960
1066
|
});
|
|
961
1067
|
}
|
|
1068
|
+
/**
|
|
1069
|
+
* Cohort retention for the campaign's linked soundlink (`soundlink_cohort_retention_daily`).
|
|
1070
|
+
*
|
|
1071
|
+
* Maps to `GET /v1/campaigns/{campaignId}/metrics/retention`.
|
|
1072
|
+
* Requires `metrics:read` and a premium plan (`403 premium_plan_required` otherwise).
|
|
1073
|
+
* One row per cohort date that has first plays. Day-N fields stay `null` until that day has passed.
|
|
1074
|
+
*/
|
|
1075
|
+
retention(campaignId, params = {}) {
|
|
1076
|
+
return this.http.get({
|
|
1077
|
+
path: `/campaigns/${encodeURIComponent(campaignId)}/metrics/retention`,
|
|
1078
|
+
query: {
|
|
1079
|
+
startDate: params.startDate,
|
|
1080
|
+
endDate: params.endDate
|
|
1081
|
+
}
|
|
1082
|
+
});
|
|
1083
|
+
}
|
|
962
1084
|
};
|
|
963
1085
|
var BreakdownMetricsResource = class {
|
|
964
1086
|
constructor(http) {
|
|
@@ -1032,6 +1154,8 @@ var Soundlink = class {
|
|
|
1032
1154
|
wallet;
|
|
1033
1155
|
/** Growth strategy catalog. Requires `campaigns:read` scope. */
|
|
1034
1156
|
strategies;
|
|
1157
|
+
/** Organization Meta pixels. Read needs `pixels:read`; write needs `pixels:write`. */
|
|
1158
|
+
pixels;
|
|
1035
1159
|
/** List, fetch, and manage campaigns. Read needs `campaigns:read`; writes need `campaigns:write`. */
|
|
1036
1160
|
campaigns;
|
|
1037
1161
|
/** Self-serve soundlinks. Read needs `soundlinks:read`; create/delete need `soundlinks:write`. */
|
|
@@ -1049,12 +1173,13 @@ var Soundlink = class {
|
|
|
1049
1173
|
this.ping = pingResource.ping.bind(pingResource);
|
|
1050
1174
|
this.wallet = new WalletResource(http);
|
|
1051
1175
|
this.strategies = new StrategiesResource(http);
|
|
1176
|
+
this.pixels = new PixelsResource(http);
|
|
1052
1177
|
this.campaigns = new CampaignsResource(http);
|
|
1053
1178
|
this.soundlinks = new SoundlinksResource(http);
|
|
1054
1179
|
this.metrics = new MetricsResource(http);
|
|
1055
1180
|
}
|
|
1056
1181
|
};
|
|
1057
1182
|
|
|
1058
|
-
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 };
|
|
1183
|
+
export { API_KEY_PREFIX, CAMPAIGNS_MAX_PAGE_SIZE, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, HttpClient, LISTENING_INSIGHTS_TIMEOUT_MS, METRICS_MAX_PAGE_SIZE, SOUNDLINKS_MAX_PAGE_SIZE, Soundlink, SoundlinkConfigError, SoundlinkParseError, SoundlinkSdkError, getStreamRowCount, resolveClientOptions };
|
|
1059
1184
|
//# sourceMappingURL=index.js.map
|
|
1060
1185
|
//# sourceMappingURL=index.js.map
|