@fire-spark/analytics-server 0.0.0-stage → 0.26.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/dist/app-DlzC8Iq0.js +55 -0
- package/dist/google.d.ts +112 -0
- package/dist/google.js +653 -0
- package/dist/index.d.ts +59 -0
- package/dist/index.js +921 -0
- package/dist/json-D5hsBi3M.js +183 -0
- package/dist/meta.d.ts +143 -0
- package/dist/meta.js +498 -0
- package/dist/provider-DIOneNqa.js +22 -0
- package/dist/retry-BRNUy4Of.d.ts +278 -0
- package/dist/tiktok.d.ts +77 -0
- package/dist/tiktok.js +375 -0
- package/package.json +77 -3
- package/README.md +0 -3
package/dist/tiktok.js
ADDED
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
import { a as stringifyJson, f as withProviderRetry, l as postJson, n as compact, o as AnalyticsServerConfigError, r as decimalNumber } from "./json-D5hsBi3M.js";
|
|
2
|
+
import { n as testCodeFor } from "./provider-DIOneNqa.js";
|
|
3
|
+
import { providerEventName } from "@fire-spark/analytics";
|
|
4
|
+
//#region src/tiktok-codes.ts
|
|
5
|
+
const rule = (reason, retryable) => {
|
|
6
|
+
return {
|
|
7
|
+
reason,
|
|
8
|
+
retryable
|
|
9
|
+
};
|
|
10
|
+
};
|
|
11
|
+
const AUTH = rule("auth", false);
|
|
12
|
+
const INVALID = rule("invalid_payload", false);
|
|
13
|
+
const RATE_LIMITED = rule("rate_limited", true);
|
|
14
|
+
const UPSTREAM = rule("upstream_error", true);
|
|
15
|
+
/**
|
|
16
|
+
* TikTok API for Business return codes (v1.3 return codes appendix,
|
|
17
|
+
* https://business-api.tiktok.com/portal/docs/return-codes-appendix/v1.3).
|
|
18
|
+
* `0` (OK) and `20001` (partial success) are handled before this table.
|
|
19
|
+
* A code missing here falls back to `tiktokCodeRule`'s ranges.
|
|
20
|
+
*/
|
|
21
|
+
const TIKTOK_RETURN_CODES = {
|
|
22
|
+
4e4: INVALID,
|
|
23
|
+
40001: AUTH,
|
|
24
|
+
40002: INVALID,
|
|
25
|
+
40006: INVALID,
|
|
26
|
+
40007: INVALID,
|
|
27
|
+
40008: INVALID,
|
|
28
|
+
40009: INVALID,
|
|
29
|
+
40010: INVALID,
|
|
30
|
+
40011: INVALID,
|
|
31
|
+
40013: INVALID,
|
|
32
|
+
40014: INVALID,
|
|
33
|
+
40016: RATE_LIMITED,
|
|
34
|
+
40050: rule("duplicate", false),
|
|
35
|
+
40051: INVALID,
|
|
36
|
+
40052: INVALID,
|
|
37
|
+
40053: INVALID,
|
|
38
|
+
40065: INVALID,
|
|
39
|
+
40100: RATE_LIMITED,
|
|
40
|
+
40101: AUTH,
|
|
41
|
+
40102: AUTH,
|
|
42
|
+
40103: AUTH,
|
|
43
|
+
40104: AUTH,
|
|
44
|
+
40105: AUTH,
|
|
45
|
+
40106: AUTH,
|
|
46
|
+
40107: AUTH,
|
|
47
|
+
40108: AUTH,
|
|
48
|
+
40109: AUTH,
|
|
49
|
+
40110: AUTH,
|
|
50
|
+
40112: AUTH,
|
|
51
|
+
40113: AUTH,
|
|
52
|
+
40115: AUTH,
|
|
53
|
+
40116: AUTH,
|
|
54
|
+
40117: AUTH,
|
|
55
|
+
40118: AUTH,
|
|
56
|
+
40119: AUTH,
|
|
57
|
+
40121: AUTH,
|
|
58
|
+
40122: AUTH,
|
|
59
|
+
40124: AUTH,
|
|
60
|
+
40125: AUTH,
|
|
61
|
+
40131: AUTH,
|
|
62
|
+
40132: RATE_LIMITED,
|
|
63
|
+
40133: RATE_LIMITED,
|
|
64
|
+
40200: INVALID,
|
|
65
|
+
40201: INVALID,
|
|
66
|
+
/** Runtime error; TikTok says a retry may resolve it. */
|
|
67
|
+
40202: UPSTREAM,
|
|
68
|
+
40300: AUTH,
|
|
69
|
+
40301: AUTH,
|
|
70
|
+
40502: RATE_LIMITED,
|
|
71
|
+
40700: INVALID,
|
|
72
|
+
40900: INVALID,
|
|
73
|
+
40901: INVALID,
|
|
74
|
+
40902: UPSTREAM,
|
|
75
|
+
40903: UPSTREAM,
|
|
76
|
+
40904: INVALID,
|
|
77
|
+
40905: INVALID,
|
|
78
|
+
40906: INVALID,
|
|
79
|
+
40907: INVALID,
|
|
80
|
+
40908: INVALID,
|
|
81
|
+
40909: INVALID,
|
|
82
|
+
40910: INVALID,
|
|
83
|
+
40911: INVALID,
|
|
84
|
+
40912: INVALID,
|
|
85
|
+
40913: UPSTREAM,
|
|
86
|
+
40914: INVALID,
|
|
87
|
+
40915: INVALID,
|
|
88
|
+
41e3: AUTH,
|
|
89
|
+
41001: INVALID,
|
|
90
|
+
41002: INVALID,
|
|
91
|
+
5e4: UPSTREAM,
|
|
92
|
+
50002: UPSTREAM,
|
|
93
|
+
51305: UPSTREAM,
|
|
94
|
+
60001: UPSTREAM
|
|
95
|
+
};
|
|
96
|
+
/** Rule for a non-zero TikTok `code`. */
|
|
97
|
+
const tiktokCodeRule = (code) => {
|
|
98
|
+
const known = TIKTOK_RETURN_CODES[code];
|
|
99
|
+
if (known) return known;
|
|
100
|
+
if (code >= 5e4) return UPSTREAM;
|
|
101
|
+
return INVALID;
|
|
102
|
+
};
|
|
103
|
+
//#endregion
|
|
104
|
+
//#region src/tiktok.ts
|
|
105
|
+
const PROVIDER = "tiktok";
|
|
106
|
+
const MAX_BATCH = 1e3;
|
|
107
|
+
const PIXEL_CODE = /^[A-Za-z0-9]{1,64}$/;
|
|
108
|
+
const API_VERSIONS = /* @__PURE__ */ new Set(["v1.3"]);
|
|
109
|
+
const PARTIAL_SUCCESS = 20001;
|
|
110
|
+
const contentsOf = (event) => {
|
|
111
|
+
return (event.items ?? []).map((item) => {
|
|
112
|
+
const c1 = {
|
|
113
|
+
content_id: item.id,
|
|
114
|
+
price: decimalNumber(item.price)
|
|
115
|
+
};
|
|
116
|
+
const c2 = { quantity: decimalNumber(item.quantity) };
|
|
117
|
+
const c3 = { content_name: item.name };
|
|
118
|
+
const c4 = {
|
|
119
|
+
content_category: item.category,
|
|
120
|
+
brand: item.brand
|
|
121
|
+
};
|
|
122
|
+
return compact({
|
|
123
|
+
...c1,
|
|
124
|
+
...c2,
|
|
125
|
+
...c3,
|
|
126
|
+
...c4
|
|
127
|
+
});
|
|
128
|
+
});
|
|
129
|
+
};
|
|
130
|
+
const propertiesOf = (event) => {
|
|
131
|
+
const priced = (event.items ?? []).length > 0;
|
|
132
|
+
const p1 = {
|
|
133
|
+
currency: event.currency,
|
|
134
|
+
value: decimalNumber(event.value)
|
|
135
|
+
};
|
|
136
|
+
const p2 = { order_id: event.order_id };
|
|
137
|
+
const p3 = { content_type: priced ? "product" : void 0 };
|
|
138
|
+
return compact({
|
|
139
|
+
...p1,
|
|
140
|
+
...p2,
|
|
141
|
+
...p3,
|
|
142
|
+
contents: contentsOf(event)
|
|
143
|
+
});
|
|
144
|
+
};
|
|
145
|
+
const userOf = (event) => {
|
|
146
|
+
const { user, click_ids: clickIds } = event;
|
|
147
|
+
const u1 = {
|
|
148
|
+
email: user.email_sha256,
|
|
149
|
+
phone: user.phone_e164_sha256
|
|
150
|
+
};
|
|
151
|
+
const u2 = { external_id: user.external_id_sha256 };
|
|
152
|
+
const u3 = {
|
|
153
|
+
ttclid: clickIds.ttclid,
|
|
154
|
+
ttp: clickIds.ttp
|
|
155
|
+
};
|
|
156
|
+
const u4 = {
|
|
157
|
+
ip: event.ipAddress,
|
|
158
|
+
user_agent: event.userAgent
|
|
159
|
+
};
|
|
160
|
+
const u5 = { locale: event.context.locale };
|
|
161
|
+
return compact({
|
|
162
|
+
...u1,
|
|
163
|
+
...u2,
|
|
164
|
+
...u3,
|
|
165
|
+
...u4,
|
|
166
|
+
...u5
|
|
167
|
+
});
|
|
168
|
+
};
|
|
169
|
+
/** One Events API 2.0 web event. `event` is the `ttq.track` name. */
|
|
170
|
+
const tiktokEventOf = (event, options) => {
|
|
171
|
+
const e1 = {
|
|
172
|
+
event: providerEventName(PROVIDER, event.name),
|
|
173
|
+
event_time: Math.floor(event.timestamp / 1e3),
|
|
174
|
+
event_id: event.event_id
|
|
175
|
+
};
|
|
176
|
+
const e2 = { user: userOf(event) };
|
|
177
|
+
const e3 = {
|
|
178
|
+
page: compact({
|
|
179
|
+
url: event.source_url,
|
|
180
|
+
referrer: event.referrer_url
|
|
181
|
+
}),
|
|
182
|
+
properties: propertiesOf(event)
|
|
183
|
+
};
|
|
184
|
+
const e4 = { limited_data_use: options.limitedDataUse };
|
|
185
|
+
return compact({
|
|
186
|
+
...e1,
|
|
187
|
+
...e2,
|
|
188
|
+
...e3,
|
|
189
|
+
...e4
|
|
190
|
+
});
|
|
191
|
+
};
|
|
192
|
+
const recordOf = (value) => {
|
|
193
|
+
return !!value && typeof value === "object" && !Array.isArray(value) ? value : {};
|
|
194
|
+
};
|
|
195
|
+
const textOf = (value) => {
|
|
196
|
+
return typeof value === "string" && value ? value : void 0;
|
|
197
|
+
};
|
|
198
|
+
const statusOutcome = (status) => {
|
|
199
|
+
if (status >= 500) return {
|
|
200
|
+
reason: "upstream_error",
|
|
201
|
+
retry: true
|
|
202
|
+
};
|
|
203
|
+
if (status === 429) return {
|
|
204
|
+
reason: "rate_limited",
|
|
205
|
+
retry: true
|
|
206
|
+
};
|
|
207
|
+
if (status === 401 || status === 403) return {
|
|
208
|
+
reason: "auth",
|
|
209
|
+
retry: false
|
|
210
|
+
};
|
|
211
|
+
return {
|
|
212
|
+
reason: "invalid_payload",
|
|
213
|
+
retry: false
|
|
214
|
+
};
|
|
215
|
+
};
|
|
216
|
+
/** TikTok response → outcome, per the retry matrix and return codes. */
|
|
217
|
+
const classifyTikTokReply = (reply) => {
|
|
218
|
+
const body = recordOf(reply.body);
|
|
219
|
+
const code = typeof body.code === "number" ? body.code : void 0;
|
|
220
|
+
const traceId = textOf(body.request_id);
|
|
221
|
+
const base = {
|
|
222
|
+
httpStatus: reply.status,
|
|
223
|
+
traceId
|
|
224
|
+
};
|
|
225
|
+
if (reply.status !== 200) {
|
|
226
|
+
const { reason, retry } = statusOutcome(reply.status);
|
|
227
|
+
const b1 = {
|
|
228
|
+
outcome: "failed",
|
|
229
|
+
reason,
|
|
230
|
+
retryable: retry
|
|
231
|
+
};
|
|
232
|
+
return {
|
|
233
|
+
...base,
|
|
234
|
+
...b1,
|
|
235
|
+
providerCode: code
|
|
236
|
+
};
|
|
237
|
+
}
|
|
238
|
+
if (code === 0 || code === PARTIAL_SUCCESS) return {
|
|
239
|
+
...base,
|
|
240
|
+
outcome: "sent",
|
|
241
|
+
retryable: false,
|
|
242
|
+
providerCode: code
|
|
243
|
+
};
|
|
244
|
+
if (code === void 0) {
|
|
245
|
+
const b1 = {
|
|
246
|
+
reason: "upstream_error",
|
|
247
|
+
retryable: true
|
|
248
|
+
};
|
|
249
|
+
return {
|
|
250
|
+
...base,
|
|
251
|
+
outcome: "failed",
|
|
252
|
+
...b1
|
|
253
|
+
};
|
|
254
|
+
}
|
|
255
|
+
const { reason, retryable } = tiktokCodeRule(code);
|
|
256
|
+
const outcome = reason === "duplicate" ? "skipped" : "failed";
|
|
257
|
+
return {
|
|
258
|
+
...base,
|
|
259
|
+
outcome,
|
|
260
|
+
reason,
|
|
261
|
+
retryable,
|
|
262
|
+
providerCode: code
|
|
263
|
+
};
|
|
264
|
+
};
|
|
265
|
+
const hasIdentifier = (event) => {
|
|
266
|
+
const { user, click_ids: clickIds } = event;
|
|
267
|
+
const b1 = [
|
|
268
|
+
clickIds.ttclid,
|
|
269
|
+
clickIds.ttp,
|
|
270
|
+
user.email_sha256
|
|
271
|
+
];
|
|
272
|
+
const b2 = [
|
|
273
|
+
user.phone_e164_sha256,
|
|
274
|
+
user.external_id_sha256,
|
|
275
|
+
event.ipAddress
|
|
276
|
+
];
|
|
277
|
+
return [...b1, ...b2].some((value) => !!value);
|
|
278
|
+
};
|
|
279
|
+
const assertOptions = (options) => {
|
|
280
|
+
if (!PIXEL_CODE.test(String(options.pixelCode ?? ""))) throw new AnalyticsServerConfigError("TIKTOK_PIXEL_CODE_INVALID", "tiktokEventsApi: pixelCode must be the TikTok pixel code");
|
|
281
|
+
if (typeof options.accessToken !== "string" || !options.accessToken.trim()) throw new AnalyticsServerConfigError("TIKTOK_ACCESS_TOKEN_REQUIRED", "tiktokEventsApi: accessToken is required");
|
|
282
|
+
const version = options.apiVersion ?? "v1.3";
|
|
283
|
+
if (!API_VERSIONS.has(version)) throw new AnalyticsServerConfigError("TIKTOK_API_VERSION_INVALID", "tiktokEventsApi: apiVersion must be v1.3");
|
|
284
|
+
return version;
|
|
285
|
+
};
|
|
286
|
+
const prepare = (events) => {
|
|
287
|
+
const ready = [];
|
|
288
|
+
const skipped = [];
|
|
289
|
+
const skip = (event, reason) => {
|
|
290
|
+
const b1 = {
|
|
291
|
+
provider: PROVIDER,
|
|
292
|
+
eventIds: [event.event_id]
|
|
293
|
+
};
|
|
294
|
+
const b2 = {
|
|
295
|
+
outcome: "skipped",
|
|
296
|
+
reason,
|
|
297
|
+
retryable: false
|
|
298
|
+
};
|
|
299
|
+
skipped.push({
|
|
300
|
+
...b1,
|
|
301
|
+
...b2,
|
|
302
|
+
attempts: 0
|
|
303
|
+
});
|
|
304
|
+
};
|
|
305
|
+
for (const event of events) if (!providerEventName(PROVIDER, event.name)) skip(event, "not_mapped");
|
|
306
|
+
else if (!hasIdentifier(event)) skip(event, "no_identifier");
|
|
307
|
+
else ready.push(event);
|
|
308
|
+
return {
|
|
309
|
+
ready,
|
|
310
|
+
skipped
|
|
311
|
+
};
|
|
312
|
+
};
|
|
313
|
+
/**
|
|
314
|
+
* TikTok Events API 2.0 destination (web events). The token travels in
|
|
315
|
+
* the `Access-Token` header and is never logged.
|
|
316
|
+
*/
|
|
317
|
+
const tiktokEventsApi = (options) => {
|
|
318
|
+
const version = assertOptions(options);
|
|
319
|
+
const pixelCode = String(options.pixelCode);
|
|
320
|
+
const accessToken = options.accessToken.trim();
|
|
321
|
+
const url = `https://business-api.tiktok.com/open_api/${version}/event/track/`;
|
|
322
|
+
const headers = { "Access-Token": accessToken };
|
|
323
|
+
const send = async (events, ctx) => {
|
|
324
|
+
const data = events.map((event) => tiktokEventOf(event, options));
|
|
325
|
+
const test_event_code = testCodeFor(PROVIDER, options, ctx);
|
|
326
|
+
const body = stringifyJson(compact({
|
|
327
|
+
event_source: "web",
|
|
328
|
+
event_source_id: pixelCode,
|
|
329
|
+
test_event_code,
|
|
330
|
+
data
|
|
331
|
+
}));
|
|
332
|
+
const final = await withProviderRetry(ctx, async (signal) => {
|
|
333
|
+
const reply = await postJson(ctx, {
|
|
334
|
+
url,
|
|
335
|
+
body,
|
|
336
|
+
headers
|
|
337
|
+
}, signal);
|
|
338
|
+
return classifyTikTokReply(reply);
|
|
339
|
+
});
|
|
340
|
+
if (final.providerCode === PARTIAL_SUCCESS) {
|
|
341
|
+
const p1 = "tiktok accepted part of the batch (code 20001)";
|
|
342
|
+
const b2 = {
|
|
343
|
+
level: "warning",
|
|
344
|
+
source: "provider"
|
|
345
|
+
};
|
|
346
|
+
const eventIds = events.map((event) => event.event_id);
|
|
347
|
+
const b3 = {
|
|
348
|
+
providerCode: PARTIAL_SUCCESS,
|
|
349
|
+
traceId: final.traceId
|
|
350
|
+
};
|
|
351
|
+
ctx.report({
|
|
352
|
+
...b2,
|
|
353
|
+
provider: PROVIDER,
|
|
354
|
+
message: p1,
|
|
355
|
+
eventIds,
|
|
356
|
+
...b3
|
|
357
|
+
});
|
|
358
|
+
}
|
|
359
|
+
const eventIds = events.map((event) => event.event_id);
|
|
360
|
+
return {
|
|
361
|
+
provider: PROVIDER,
|
|
362
|
+
eventIds,
|
|
363
|
+
...final
|
|
364
|
+
};
|
|
365
|
+
};
|
|
366
|
+
return {
|
|
367
|
+
id: PROVIDER,
|
|
368
|
+
maxBatchSize: MAX_BATCH,
|
|
369
|
+
runtimes: ["web"],
|
|
370
|
+
prepare,
|
|
371
|
+
send
|
|
372
|
+
};
|
|
373
|
+
};
|
|
374
|
+
//#endregion
|
|
375
|
+
export { TIKTOK_RETURN_CODES, classifyTikTokReply, tiktokCodeRule, tiktokEventOf, tiktokEventsApi };
|
package/package.json
CHANGED
|
@@ -1,6 +1,80 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fire-spark/analytics-server",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.26.0",
|
|
4
|
+
"description": "Fire Spark server-side tracking relay (Meta Conversions API, TikTok Events API, Google Data Manager API)",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"sideEffects": false,
|
|
7
|
+
"files": [
|
|
8
|
+
"dist"
|
|
9
|
+
],
|
|
10
|
+
"main": "./dist/index.js",
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"exports": {
|
|
13
|
+
".": {
|
|
14
|
+
"types": "./dist/index.d.ts",
|
|
15
|
+
"import": "./dist/index.js",
|
|
16
|
+
"default": "./dist/index.js"
|
|
17
|
+
},
|
|
18
|
+
"./meta": {
|
|
19
|
+
"types": "./dist/meta.d.ts",
|
|
20
|
+
"import": "./dist/meta.js",
|
|
21
|
+
"default": "./dist/meta.js"
|
|
22
|
+
},
|
|
23
|
+
"./tiktok": {
|
|
24
|
+
"types": "./dist/tiktok.d.ts",
|
|
25
|
+
"import": "./dist/tiktok.js",
|
|
26
|
+
"default": "./dist/tiktok.js"
|
|
27
|
+
},
|
|
28
|
+
"./google": {
|
|
29
|
+
"types": "./dist/google.d.ts",
|
|
30
|
+
"import": "./dist/google.js",
|
|
31
|
+
"default": "./dist/google.js"
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"big.js": "6.2.1"
|
|
36
|
+
},
|
|
37
|
+
"peerDependencies": {
|
|
38
|
+
"@fire-spark/analytics": "^0.26.0"
|
|
39
|
+
},
|
|
40
|
+
"devDependencies": {
|
|
41
|
+
"@types/big.js": "6.2.2",
|
|
42
|
+
"tsdown": "^0.22.14",
|
|
43
|
+
"typescript": "^7.0.2",
|
|
44
|
+
"vitest": "^2.1.8",
|
|
45
|
+
"@fire-spark/analytics": "0.26.0"
|
|
46
|
+
},
|
|
47
|
+
"publishConfig": {
|
|
48
|
+
"access": "public"
|
|
49
|
+
},
|
|
50
|
+
"tsdown": {
|
|
51
|
+
"entry": [
|
|
52
|
+
"src/index.ts",
|
|
53
|
+
"src/meta.ts",
|
|
54
|
+
"src/tiktok.ts",
|
|
55
|
+
"src/google.ts"
|
|
56
|
+
],
|
|
57
|
+
"format": [
|
|
58
|
+
"esm"
|
|
59
|
+
],
|
|
60
|
+
"platform": "neutral",
|
|
61
|
+
"dts": {
|
|
62
|
+
"tsconfig": "tsconfig.build.json"
|
|
63
|
+
},
|
|
64
|
+
"clean": true,
|
|
65
|
+
"deps": {
|
|
66
|
+
"neverBundle": [
|
|
67
|
+
"@fire-spark/analytics"
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
},
|
|
71
|
+
"scripts": {
|
|
72
|
+
"build": "tsdown",
|
|
73
|
+
"dev": "tsdown --watch",
|
|
74
|
+
"check-types": "tsc --noEmit",
|
|
75
|
+
"test:utils": "vitest run",
|
|
76
|
+
"lint": "oxlint ./src --max-warnings=0",
|
|
77
|
+
"format": "oxfmt ./src",
|
|
78
|
+
"check-format": "oxfmt --check ./src"
|
|
79
|
+
}
|
|
6
80
|
}
|
package/README.md
DELETED