@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/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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.