soundlink 1.0.0 → 1.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 +13 -0
- package/LICENSE +21 -0
- package/README.md +216 -0
- package/dist/cjs/index.cjs +527 -0
- package/dist/cjs/index.cjs.map +1 -0
- package/dist/esm/index.d.ts +269 -0
- package/dist/esm/index.js +513 -0
- package/dist/esm/index.js.map +1 -0
- package/openapi/soundlink-public-api-v1.yaml +1289 -0
- package/package.json +88 -7
- package/index.js +0 -1
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
type PublicApiErrorCode = 'invalid_api_key' | 'api_key_revoked' | 'api_key_expired' | 'mixed_credentials' | 'insufficient_scope' | 'not_found' | 'campaign_not_found' | 'invalid_query_parameter' | 'invalid_date_range' | 'page_size_exceeded' | 'rate_limit_exceeded' | 'internal_error';
|
|
2
|
+
type CampaignStatus = 'creating' | 'active' | 'paused' | 'completed' | 'failed';
|
|
3
|
+
type SocialPlatform = 'meta';
|
|
4
|
+
type EngagementContext = 'catalog' | 'playlist';
|
|
5
|
+
type CampaignSortBy = 'createdAt' | 'status';
|
|
6
|
+
type BreakdownSortBy = 'report_date' | 'spend_total';
|
|
7
|
+
type EngagementSortBy = 'report_date' | 'streams' | 'listeners';
|
|
8
|
+
type SortOrder = 'asc' | 'desc';
|
|
9
|
+
interface ApiMeta {
|
|
10
|
+
requestId: string;
|
|
11
|
+
}
|
|
12
|
+
interface ApiError {
|
|
13
|
+
code: PublicApiErrorCode;
|
|
14
|
+
message: string;
|
|
15
|
+
status: number;
|
|
16
|
+
requestId?: string;
|
|
17
|
+
retryAfter?: number;
|
|
18
|
+
}
|
|
19
|
+
interface ApiResponse<T> {
|
|
20
|
+
data: T | null;
|
|
21
|
+
error: ApiError | null;
|
|
22
|
+
meta?: ApiMeta;
|
|
23
|
+
}
|
|
24
|
+
interface Pagination {
|
|
25
|
+
page: number;
|
|
26
|
+
pageSize: number;
|
|
27
|
+
totalCount: number;
|
|
28
|
+
totalPages: number;
|
|
29
|
+
}
|
|
30
|
+
interface CampaignSummary {
|
|
31
|
+
campaignId: string;
|
|
32
|
+
organizationId: string;
|
|
33
|
+
status: CampaignStatus;
|
|
34
|
+
socialPlatform: SocialPlatform;
|
|
35
|
+
dailyBudget: number;
|
|
36
|
+
totalBudget: number;
|
|
37
|
+
campaignDuration: number;
|
|
38
|
+
createdAt: string;
|
|
39
|
+
updatedAt: string;
|
|
40
|
+
}
|
|
41
|
+
interface CampaignDetail extends CampaignSummary {
|
|
42
|
+
strategyType?: string;
|
|
43
|
+
}
|
|
44
|
+
interface CampaignListData {
|
|
45
|
+
items: CampaignSummary[];
|
|
46
|
+
pagination: Pagination;
|
|
47
|
+
}
|
|
48
|
+
interface PingData {
|
|
49
|
+
status: 'ok';
|
|
50
|
+
}
|
|
51
|
+
interface MetricsOverview {
|
|
52
|
+
listeners: number;
|
|
53
|
+
streams: number;
|
|
54
|
+
followers: number;
|
|
55
|
+
impressions: number | null;
|
|
56
|
+
ad_clicks: number | null;
|
|
57
|
+
link_clicks: number | null;
|
|
58
|
+
spend_media: number;
|
|
59
|
+
spend_total: number;
|
|
60
|
+
fees: number;
|
|
61
|
+
currency: string;
|
|
62
|
+
cpl: number;
|
|
63
|
+
cpf: number;
|
|
64
|
+
streams_per_listener: number;
|
|
65
|
+
}
|
|
66
|
+
interface BreakdownRow {
|
|
67
|
+
provider: 'soundlink';
|
|
68
|
+
account_id: string;
|
|
69
|
+
schema_version: string;
|
|
70
|
+
report_date: string;
|
|
71
|
+
report_date_timezone: 'UTC';
|
|
72
|
+
exported_at: string;
|
|
73
|
+
campaign_id: string;
|
|
74
|
+
campaign_name: string;
|
|
75
|
+
campaign_target_type: 'track' | 'playlist' | null;
|
|
76
|
+
campaign_target_isrc: string | null;
|
|
77
|
+
campaign_target_spotify_track_id: string | null;
|
|
78
|
+
campaign_target_playlist_id: string | null;
|
|
79
|
+
country_code: string;
|
|
80
|
+
impressions: number | null;
|
|
81
|
+
ad_clicks: number | null;
|
|
82
|
+
link_clicks: number | null;
|
|
83
|
+
streams: number;
|
|
84
|
+
listeners: number;
|
|
85
|
+
followers: number;
|
|
86
|
+
streams_per_listener: number;
|
|
87
|
+
spend_media: number;
|
|
88
|
+
spend_total: number;
|
|
89
|
+
fees: number;
|
|
90
|
+
currency: string;
|
|
91
|
+
currency_account: string;
|
|
92
|
+
cpl: number;
|
|
93
|
+
cpf: number;
|
|
94
|
+
cpc_linkclick: number | null;
|
|
95
|
+
ctr_linkclick: number | null;
|
|
96
|
+
ctr_adclick: number | null;
|
|
97
|
+
cost_per_result: number;
|
|
98
|
+
result_type: 'lp_click' | 'stream' | 'follow' | null;
|
|
99
|
+
}
|
|
100
|
+
interface EngagementRow {
|
|
101
|
+
provider: 'soundlink';
|
|
102
|
+
account_id: string;
|
|
103
|
+
schema_version: string;
|
|
104
|
+
report_date: string;
|
|
105
|
+
report_date_timezone: 'UTC';
|
|
106
|
+
exported_at: string;
|
|
107
|
+
campaign_id: string;
|
|
108
|
+
campaign_name: string;
|
|
109
|
+
campaign_target_type: 'track' | 'playlist' | null;
|
|
110
|
+
campaign_target_isrc: string | null;
|
|
111
|
+
campaign_target_spotify_track_id: string | null;
|
|
112
|
+
campaign_target_playlist_id: string | null;
|
|
113
|
+
status: string;
|
|
114
|
+
engagement_context: EngagementContext;
|
|
115
|
+
country_code: string;
|
|
116
|
+
engaged_track_isrc: string | null;
|
|
117
|
+
engaged_spotify_track_id: string;
|
|
118
|
+
engaged_track_name: string;
|
|
119
|
+
playlist_position: number | null;
|
|
120
|
+
new_listeners: number;
|
|
121
|
+
returning_listeners: number;
|
|
122
|
+
listeners: number;
|
|
123
|
+
new_listener_streams: number;
|
|
124
|
+
returning_listener_streams: number;
|
|
125
|
+
streams: number;
|
|
126
|
+
spl: number;
|
|
127
|
+
}
|
|
128
|
+
interface BreakdownListData {
|
|
129
|
+
schemaVersion: string;
|
|
130
|
+
items: BreakdownRow[];
|
|
131
|
+
pagination: Pagination;
|
|
132
|
+
}
|
|
133
|
+
interface EngagementListData {
|
|
134
|
+
schemaVersion: string;
|
|
135
|
+
items: EngagementRow[];
|
|
136
|
+
pagination: Pagination;
|
|
137
|
+
}
|
|
138
|
+
interface ExportCollection<T> {
|
|
139
|
+
rows: T[];
|
|
140
|
+
rowCount: number;
|
|
141
|
+
}
|
|
142
|
+
interface JsonlStream<T> extends AsyncIterable<T> {
|
|
143
|
+
rowCount?: number;
|
|
144
|
+
}
|
|
145
|
+
interface SoundlinkClientOptions {
|
|
146
|
+
apiKey: string;
|
|
147
|
+
baseUrl?: string;
|
|
148
|
+
timeout?: number;
|
|
149
|
+
maxRetries?: number;
|
|
150
|
+
fetch?: typeof fetch;
|
|
151
|
+
}
|
|
152
|
+
type SoundlinkOptions = SoundlinkClientOptions | string;
|
|
153
|
+
interface CampaignListParams {
|
|
154
|
+
page?: number;
|
|
155
|
+
pageSize?: number;
|
|
156
|
+
sortBy?: CampaignSortBy;
|
|
157
|
+
sortOrder?: SortOrder;
|
|
158
|
+
}
|
|
159
|
+
interface DateRangeParams {
|
|
160
|
+
startDate?: string;
|
|
161
|
+
endDate?: string;
|
|
162
|
+
}
|
|
163
|
+
interface BreakdownListParams extends DateRangeParams {
|
|
164
|
+
page?: number;
|
|
165
|
+
pageSize?: number;
|
|
166
|
+
sortBy?: BreakdownSortBy;
|
|
167
|
+
sortOrder?: SortOrder;
|
|
168
|
+
}
|
|
169
|
+
interface EngagementListParams extends DateRangeParams {
|
|
170
|
+
page?: number;
|
|
171
|
+
pageSize?: number;
|
|
172
|
+
sortBy?: EngagementSortBy;
|
|
173
|
+
sortOrder?: SortOrder;
|
|
174
|
+
engagementContext?: EngagementContext;
|
|
175
|
+
}
|
|
176
|
+
interface EngagementExportParams extends DateRangeParams {
|
|
177
|
+
engagementContext?: EngagementContext;
|
|
178
|
+
}
|
|
179
|
+
type BreakdownExportParams = DateRangeParams;
|
|
180
|
+
|
|
181
|
+
interface HttpGetOptions {
|
|
182
|
+
path: string;
|
|
183
|
+
query?: Record<string, string | number | boolean | undefined | null>;
|
|
184
|
+
}
|
|
185
|
+
interface HttpJsonlOptions extends HttpGetOptions {
|
|
186
|
+
accept?: string;
|
|
187
|
+
}
|
|
188
|
+
interface ResolvedSoundlinkClientOptions {
|
|
189
|
+
apiKey: string;
|
|
190
|
+
baseUrl: string;
|
|
191
|
+
timeout: number;
|
|
192
|
+
maxRetries: number;
|
|
193
|
+
fetch: typeof fetch;
|
|
194
|
+
}
|
|
195
|
+
declare function resolveClientOptions(options: SoundlinkOptions): ResolvedSoundlinkClientOptions;
|
|
196
|
+
declare class HttpClient {
|
|
197
|
+
private readonly options;
|
|
198
|
+
constructor(options: SoundlinkOptions);
|
|
199
|
+
get resolvedOptions(): ResolvedSoundlinkClientOptions;
|
|
200
|
+
get<T>({ path, query }: HttpGetOptions): Promise<ApiResponse<T>>;
|
|
201
|
+
getJsonl<T>({ path, query, accept, }: HttpJsonlOptions): Promise<ApiResponse<JsonlStream<T>>>;
|
|
202
|
+
private buildHeaders;
|
|
203
|
+
private requestJson;
|
|
204
|
+
private parseErrorEnvelope;
|
|
205
|
+
private fetchWithRetry;
|
|
206
|
+
}
|
|
207
|
+
declare function getStreamRowCount<T>(stream: AsyncIterable<T>): number | undefined;
|
|
208
|
+
|
|
209
|
+
interface ExportResource<T, P extends DateRangeParams> {
|
|
210
|
+
(campaignId: string, params?: P): Promise<ApiResponse<JsonlStream<T>>>;
|
|
211
|
+
collect(campaignId: string, params?: P): Promise<ApiResponse<ExportCollection<T>>>;
|
|
212
|
+
}
|
|
213
|
+
declare class PingResource {
|
|
214
|
+
private readonly http;
|
|
215
|
+
constructor(http: HttpClient);
|
|
216
|
+
ping(): Promise<ApiResponse<PingData>>;
|
|
217
|
+
}
|
|
218
|
+
declare class CampaignsResource {
|
|
219
|
+
private readonly http;
|
|
220
|
+
constructor(http: HttpClient);
|
|
221
|
+
list(params?: CampaignListParams): Promise<ApiResponse<CampaignListData>>;
|
|
222
|
+
get(campaignId: string): Promise<ApiResponse<CampaignDetail>>;
|
|
223
|
+
listAll(params?: Omit<CampaignListParams, 'page'>): AsyncGenerator<CampaignListData['items'][number], void, void>;
|
|
224
|
+
}
|
|
225
|
+
declare class MetricsResource {
|
|
226
|
+
private readonly http;
|
|
227
|
+
readonly breakdown: BreakdownMetricsResource;
|
|
228
|
+
readonly engagement: EngagementMetricsResource;
|
|
229
|
+
constructor(http: HttpClient);
|
|
230
|
+
overview(campaignId: string, params?: DateRangeParams): Promise<ApiResponse<MetricsOverview>>;
|
|
231
|
+
}
|
|
232
|
+
declare class BreakdownMetricsResource {
|
|
233
|
+
private readonly http;
|
|
234
|
+
readonly export: ExportResource<BreakdownRow, BreakdownExportParams>;
|
|
235
|
+
constructor(http: HttpClient);
|
|
236
|
+
list(campaignId: string, params?: BreakdownListParams): Promise<ApiResponse<BreakdownListData>>;
|
|
237
|
+
}
|
|
238
|
+
declare class EngagementMetricsResource {
|
|
239
|
+
private readonly http;
|
|
240
|
+
readonly export: ExportResource<EngagementRow, EngagementExportParams>;
|
|
241
|
+
constructor(http: HttpClient);
|
|
242
|
+
list(campaignId: string, params?: EngagementListParams): Promise<ApiResponse<EngagementListData>>;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
declare class Soundlink {
|
|
246
|
+
readonly ping: PingResource['ping'];
|
|
247
|
+
readonly campaigns: CampaignsResource;
|
|
248
|
+
readonly metrics: MetricsResource;
|
|
249
|
+
constructor(options: SoundlinkOptions);
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
declare class SoundlinkSdkError extends Error {
|
|
253
|
+
constructor(message: string);
|
|
254
|
+
}
|
|
255
|
+
declare class SoundlinkParseError extends SoundlinkSdkError {
|
|
256
|
+
constructor(message: string);
|
|
257
|
+
}
|
|
258
|
+
declare class SoundlinkConfigError extends SoundlinkSdkError {
|
|
259
|
+
constructor(message: string);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
declare const DEFAULT_BASE_URL = "https://api.getsoundlink.com";
|
|
263
|
+
declare const DEFAULT_TIMEOUT_MS = 30000;
|
|
264
|
+
declare const DEFAULT_MAX_RETRIES = 2;
|
|
265
|
+
declare const API_KEY_PREFIX = "sk_";
|
|
266
|
+
declare const CAMPAIGNS_MAX_PAGE_SIZE = 100;
|
|
267
|
+
declare const METRICS_MAX_PAGE_SIZE = 500;
|
|
268
|
+
|
|
269
|
+
export { API_KEY_PREFIX, type ApiError, type ApiMeta, type ApiResponse, type BreakdownExportParams, type BreakdownListData, type BreakdownListParams, type BreakdownRow, CAMPAIGNS_MAX_PAGE_SIZE, type CampaignDetail, type CampaignListData, type CampaignListParams, type CampaignSortBy, type CampaignStatus, type CampaignSummary, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DateRangeParams, type EngagementContext, type EngagementExportParams, type EngagementListData, type EngagementListParams, type EngagementRow, type EngagementSortBy, type ExportCollection, type ExportResource, HttpClient, 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, getStreamRowCount, resolveClientOptions };
|