@withgateway/sdk 0.1.3
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/README.md +229 -0
- package/dist/context/index.d.mts +225 -0
- package/dist/context/index.d.ts +225 -0
- package/dist/context/index.js +440 -0
- package/dist/context/index.js.map +1 -0
- package/dist/context/index.mjs +411 -0
- package/dist/context/index.mjs.map +1 -0
- package/dist/experiments/index.d.mts +260 -0
- package/dist/experiments/index.d.ts +260 -0
- package/dist/experiments/index.js +407 -0
- package/dist/experiments/index.js.map +1 -0
- package/dist/experiments/index.mjs +374 -0
- package/dist/experiments/index.mjs.map +1 -0
- package/dist/index-Caw3XVub.d.mts +193 -0
- package/dist/index-Caw3XVub.d.ts +193 -0
- package/dist/index.d.mts +20 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +1476 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +1434 -0
- package/dist/index.mjs.map +1 -0
- package/dist/memory/index.d.mts +124 -0
- package/dist/memory/index.d.ts +124 -0
- package/dist/memory/index.js +192 -0
- package/dist/memory/index.js.map +1 -0
- package/dist/memory/index.mjs +164 -0
- package/dist/memory/index.mjs.map +1 -0
- package/dist/security/index.d.mts +114 -0
- package/dist/security/index.d.ts +114 -0
- package/dist/security/index.js +297 -0
- package/dist/security/index.js.map +1 -0
- package/dist/security/index.mjs +275 -0
- package/dist/security/index.mjs.map +1 -0
- package/dist/tracing/index.d.mts +1 -0
- package/dist/tracing/index.d.ts +1 -0
- package/dist/tracing/index.js +226 -0
- package/dist/tracing/index.js.map +1 -0
- package/dist/tracing/index.mjs +202 -0
- package/dist/tracing/index.mjs.map +1 -0
- package/package.json +112 -0
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
var __defProp = Object.defineProperty;
|
|
2
|
+
var __export = (target, all) => {
|
|
3
|
+
for (var name in all)
|
|
4
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
5
|
+
};
|
|
6
|
+
|
|
7
|
+
// src/experiments/assignment.ts
|
|
8
|
+
import { createHash } from "crypto";
|
|
9
|
+
function computeHash(experimentKey, userId) {
|
|
10
|
+
const raw = createHash("sha256").update(`${experimentKey}:${userId}`).digest("hex");
|
|
11
|
+
return parseInt(raw.slice(0, 8), 16) / 4294967296;
|
|
12
|
+
}
|
|
13
|
+
function assignVariant(config, userId) {
|
|
14
|
+
if (!config.variants || config.variants.length === 0) {
|
|
15
|
+
return null;
|
|
16
|
+
}
|
|
17
|
+
const bucket = computeHash(config.key, userId);
|
|
18
|
+
const trafficThreshold = config.trafficPercent / 100;
|
|
19
|
+
if (bucket >= trafficThreshold) {
|
|
20
|
+
return null;
|
|
21
|
+
}
|
|
22
|
+
const normalizedBucket = bucket / trafficThreshold;
|
|
23
|
+
const totalWeight = config.variants.reduce((sum, v) => sum + v.weight, 0);
|
|
24
|
+
if (totalWeight <= 0) {
|
|
25
|
+
return config.variants[0] ?? null;
|
|
26
|
+
}
|
|
27
|
+
let cumulative = 0;
|
|
28
|
+
for (const variant of config.variants) {
|
|
29
|
+
cumulative += variant.weight / totalWeight;
|
|
30
|
+
if (normalizedBucket < cumulative) {
|
|
31
|
+
return variant;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
return config.variants[config.variants.length - 1] ?? null;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// src/experiments/context.ts
|
|
38
|
+
import { AsyncLocalStorage } from "async_hooks";
|
|
39
|
+
var experimentContextStorage = new AsyncLocalStorage();
|
|
40
|
+
function getExperimentContext() {
|
|
41
|
+
return experimentContextStorage.getStore();
|
|
42
|
+
}
|
|
43
|
+
function setExperimentContext(context) {
|
|
44
|
+
experimentContextStorage.enterWith(context);
|
|
45
|
+
}
|
|
46
|
+
function clearExperimentContext() {
|
|
47
|
+
experimentContextStorage.enterWith(void 0);
|
|
48
|
+
}
|
|
49
|
+
function runWithExperimentContext(context, fn) {
|
|
50
|
+
return experimentContextStorage.run(context, fn);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// src/experiments/exposure-logger.ts
|
|
54
|
+
var ExposureLogger = class {
|
|
55
|
+
buffer = [];
|
|
56
|
+
batchSize;
|
|
57
|
+
flushIntervalMs;
|
|
58
|
+
apiUrl;
|
|
59
|
+
apiKey;
|
|
60
|
+
secretKey;
|
|
61
|
+
flushTimer = null;
|
|
62
|
+
isFlushing = false;
|
|
63
|
+
constructor(config) {
|
|
64
|
+
this.apiUrl = config.apiUrl.replace(/\/$/, "");
|
|
65
|
+
this.apiKey = config.apiKey;
|
|
66
|
+
this.secretKey = config.secretKey ?? "";
|
|
67
|
+
this.batchSize = config.batchSize ?? 100;
|
|
68
|
+
this.flushIntervalMs = config.flushIntervalMs ?? 5e3;
|
|
69
|
+
this.flushTimer = setInterval(() => {
|
|
70
|
+
this.flush().catch((err) => {
|
|
71
|
+
console.error("[gateway] Exposure flush error:", err);
|
|
72
|
+
});
|
|
73
|
+
}, this.flushIntervalMs);
|
|
74
|
+
if (this.flushTimer.unref) {
|
|
75
|
+
this.flushTimer.unref();
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
log(exposure) {
|
|
79
|
+
this.buffer.push(exposure);
|
|
80
|
+
if (this.buffer.length >= this.batchSize) {
|
|
81
|
+
this.flush().catch((err) => {
|
|
82
|
+
console.error("[gateway] Exposure flush error:", err);
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
async flush() {
|
|
87
|
+
if (this.isFlushing || this.buffer.length === 0) {
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
this.isFlushing = true;
|
|
91
|
+
const batch = this.buffer.splice(0, this.buffer.length);
|
|
92
|
+
try {
|
|
93
|
+
const authHeader = this.secretKey ? `Basic ${Buffer.from(`${this.apiKey}:${this.secretKey}`).toString("base64")}` : `Bearer ${this.apiKey}`;
|
|
94
|
+
const response = await fetch(
|
|
95
|
+
`${this.apiUrl}/api/public/experiments/exposures/batch`,
|
|
96
|
+
{
|
|
97
|
+
method: "POST",
|
|
98
|
+
headers: {
|
|
99
|
+
"Content-Type": "application/json",
|
|
100
|
+
Authorization: authHeader
|
|
101
|
+
},
|
|
102
|
+
body: JSON.stringify({
|
|
103
|
+
exposures: batch
|
|
104
|
+
})
|
|
105
|
+
}
|
|
106
|
+
);
|
|
107
|
+
if (!response.ok) {
|
|
108
|
+
this.buffer.unshift(...batch);
|
|
109
|
+
console.error(
|
|
110
|
+
`[gateway] Failed to log exposures: ${response.status} ${response.statusText}`
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
} catch (error) {
|
|
114
|
+
this.buffer.unshift(...batch);
|
|
115
|
+
console.error("[gateway] Network error logging exposures:", error);
|
|
116
|
+
} finally {
|
|
117
|
+
this.isFlushing = false;
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
async shutdown() {
|
|
121
|
+
if (this.flushTimer) {
|
|
122
|
+
clearInterval(this.flushTimer);
|
|
123
|
+
this.flushTimer = null;
|
|
124
|
+
}
|
|
125
|
+
await this.flush();
|
|
126
|
+
}
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
// src/experiments/client.ts
|
|
130
|
+
var ExperimentClient = class {
|
|
131
|
+
apiUrl;
|
|
132
|
+
apiKey;
|
|
133
|
+
secretKey;
|
|
134
|
+
projectId;
|
|
135
|
+
configs = /* @__PURE__ */ new Map();
|
|
136
|
+
exposureLogger;
|
|
137
|
+
constructor(config) {
|
|
138
|
+
this.apiUrl = config.apiUrl.replace(/\/$/, "");
|
|
139
|
+
this.apiKey = config.apiKey;
|
|
140
|
+
this.secretKey = config.secretKey ?? "";
|
|
141
|
+
this.projectId = config.projectId;
|
|
142
|
+
this.exposureLogger = new ExposureLogger({
|
|
143
|
+
apiUrl: this.apiUrl,
|
|
144
|
+
apiKey: this.apiKey,
|
|
145
|
+
secretKey: this.secretKey,
|
|
146
|
+
batchSize: config.exposureLogger?.batchSize,
|
|
147
|
+
flushIntervalMs: config.exposureLogger?.flushIntervalMs
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
async register(input) {
|
|
151
|
+
const config = {
|
|
152
|
+
key: input.key,
|
|
153
|
+
trafficPercent: input.trafficPercent ?? 100,
|
|
154
|
+
variants: input.variants.map((v) => ({
|
|
155
|
+
key: v.key,
|
|
156
|
+
weight: v.weight ?? 1,
|
|
157
|
+
config: v.config ?? {}
|
|
158
|
+
}))
|
|
159
|
+
};
|
|
160
|
+
this.configs.set(config.key, config);
|
|
161
|
+
const syncToBackend = input.syncToBackend ?? true;
|
|
162
|
+
if (syncToBackend) {
|
|
163
|
+
this.syncToBackendAsync(config, input.evaluatorNames).catch((err) => {
|
|
164
|
+
console.error(
|
|
165
|
+
`[gateway] Failed to sync experiment ${config.key}:`,
|
|
166
|
+
err
|
|
167
|
+
);
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
async fetch(experimentKeys) {
|
|
172
|
+
const url = new URL(`${this.apiUrl}/api/public/experiments`);
|
|
173
|
+
if (experimentKeys && experimentKeys.length > 0) {
|
|
174
|
+
url.searchParams.set("keys", experimentKeys.join(","));
|
|
175
|
+
}
|
|
176
|
+
const authHeader = this.secretKey ? `Basic ${Buffer.from(`${this.apiKey}:${this.secretKey}`).toString("base64")}` : `Bearer ${this.apiKey}`;
|
|
177
|
+
const response = await fetch(url.toString(), {
|
|
178
|
+
method: "GET",
|
|
179
|
+
headers: {
|
|
180
|
+
Authorization: authHeader
|
|
181
|
+
}
|
|
182
|
+
});
|
|
183
|
+
if (!response.ok) {
|
|
184
|
+
throw new Error(
|
|
185
|
+
`Failed to fetch experiments: ${response.status} ${response.statusText}`
|
|
186
|
+
);
|
|
187
|
+
}
|
|
188
|
+
const data = await response.json();
|
|
189
|
+
for (const config of data.experiments) {
|
|
190
|
+
this.configs.set(config.key, config);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
async getVariant(experimentKey, userId, options) {
|
|
194
|
+
const fetchIfMissing = options?.fetchIfMissing ?? true;
|
|
195
|
+
let config = this.configs.get(experimentKey);
|
|
196
|
+
if (!config && fetchIfMissing) {
|
|
197
|
+
try {
|
|
198
|
+
await this.fetch([experimentKey]);
|
|
199
|
+
config = this.configs.get(experimentKey);
|
|
200
|
+
} catch (error) {
|
|
201
|
+
console.error(
|
|
202
|
+
`[gateway] Failed to fetch experiment ${experimentKey}:`,
|
|
203
|
+
error
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
if (!config) {
|
|
208
|
+
return {
|
|
209
|
+
variant: null,
|
|
210
|
+
inExperiment: false,
|
|
211
|
+
experimentKey,
|
|
212
|
+
run: (fn) => fn()
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
const variant = assignVariant(config, userId);
|
|
216
|
+
if (!variant) {
|
|
217
|
+
return {
|
|
218
|
+
variant: null,
|
|
219
|
+
inExperiment: false,
|
|
220
|
+
experimentKey,
|
|
221
|
+
run: (fn) => fn()
|
|
222
|
+
};
|
|
223
|
+
}
|
|
224
|
+
this.exposureLogger.log({
|
|
225
|
+
userId,
|
|
226
|
+
experimentId: experimentKey,
|
|
227
|
+
variantKey: variant.key,
|
|
228
|
+
timestamp: (/* @__PURE__ */ new Date()).toISOString()
|
|
229
|
+
});
|
|
230
|
+
const context = {
|
|
231
|
+
experimentId: experimentKey,
|
|
232
|
+
variantKey: variant.key,
|
|
233
|
+
userId
|
|
234
|
+
};
|
|
235
|
+
setExperimentContext(context);
|
|
236
|
+
return {
|
|
237
|
+
variant,
|
|
238
|
+
inExperiment: true,
|
|
239
|
+
experimentKey,
|
|
240
|
+
run: (fn) => runWithExperimentContext(context, fn)
|
|
241
|
+
};
|
|
242
|
+
}
|
|
243
|
+
getConfig(experimentKey) {
|
|
244
|
+
return this.configs.get(experimentKey);
|
|
245
|
+
}
|
|
246
|
+
async shutdown() {
|
|
247
|
+
await this.exposureLogger.shutdown();
|
|
248
|
+
}
|
|
249
|
+
async syncToBackendAsync(config, evaluatorNames) {
|
|
250
|
+
const authHeader = this.secretKey ? `Basic ${Buffer.from(`${this.apiKey}:${this.secretKey}`).toString("base64")}` : `Bearer ${this.apiKey}`;
|
|
251
|
+
const response = await fetch(`${this.apiUrl}/api/public/experiments`, {
|
|
252
|
+
method: "POST",
|
|
253
|
+
headers: {
|
|
254
|
+
"Content-Type": "application/json",
|
|
255
|
+
Authorization: authHeader
|
|
256
|
+
},
|
|
257
|
+
body: JSON.stringify({
|
|
258
|
+
key: config.key,
|
|
259
|
+
trafficPercent: config.trafficPercent,
|
|
260
|
+
variants: config.variants,
|
|
261
|
+
evaluatorNames: evaluatorNames ?? []
|
|
262
|
+
})
|
|
263
|
+
});
|
|
264
|
+
if (!response.ok) {
|
|
265
|
+
const text = await response.text();
|
|
266
|
+
throw new Error(
|
|
267
|
+
`Failed to sync experiment: ${response.status} ${response.statusText} - ${text}`
|
|
268
|
+
);
|
|
269
|
+
}
|
|
270
|
+
console.log(`[gateway] Synced experiment '${config.key}' to backend`);
|
|
271
|
+
}
|
|
272
|
+
};
|
|
273
|
+
|
|
274
|
+
// src/experiments/otel.ts
|
|
275
|
+
var EXPERIMENT_ATTRIBUTES = {
|
|
276
|
+
EXPERIMENT_ID: "gateway.experiment.id",
|
|
277
|
+
VARIANT_KEY: "gateway.variant.key",
|
|
278
|
+
USER_ID: "gateway.experiment.user_id"
|
|
279
|
+
};
|
|
280
|
+
var ExperimentSpanProcessor = class {
|
|
281
|
+
onStart(span, _parentContext) {
|
|
282
|
+
const ctx = getExperimentContext();
|
|
283
|
+
if (ctx) {
|
|
284
|
+
span.setAttribute(EXPERIMENT_ATTRIBUTES.EXPERIMENT_ID, ctx.experimentId);
|
|
285
|
+
span.setAttribute(EXPERIMENT_ATTRIBUTES.VARIANT_KEY, ctx.variantKey);
|
|
286
|
+
span.setAttribute(EXPERIMENT_ATTRIBUTES.USER_ID, ctx.userId);
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
onEnd(_span) {
|
|
290
|
+
}
|
|
291
|
+
async shutdown() {
|
|
292
|
+
}
|
|
293
|
+
async forceFlush() {
|
|
294
|
+
}
|
|
295
|
+
};
|
|
296
|
+
function addExperimentAttributes(span, experimentId, variantKey, userId) {
|
|
297
|
+
span.setAttribute(EXPERIMENT_ATTRIBUTES.EXPERIMENT_ID, experimentId);
|
|
298
|
+
span.setAttribute(EXPERIMENT_ATTRIBUTES.VARIANT_KEY, variantKey);
|
|
299
|
+
span.setAttribute(EXPERIMENT_ATTRIBUTES.USER_ID, userId);
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
// src/experiments/singleton.ts
|
|
303
|
+
var singleton_exports = {};
|
|
304
|
+
__export(singleton_exports, {
|
|
305
|
+
clearExperimentContext: () => clearExperimentContext2,
|
|
306
|
+
fetch: () => fetch2,
|
|
307
|
+
getClient: () => getClient,
|
|
308
|
+
getVariant: () => getVariant,
|
|
309
|
+
init: () => init,
|
|
310
|
+
register: () => register,
|
|
311
|
+
shutdown: () => shutdown
|
|
312
|
+
});
|
|
313
|
+
var client = null;
|
|
314
|
+
function init(config) {
|
|
315
|
+
client = new ExperimentClient({
|
|
316
|
+
apiUrl: config.baseUrl,
|
|
317
|
+
apiKey: config.apiKey,
|
|
318
|
+
secretKey: config.secretKey,
|
|
319
|
+
projectId: config.projectId ?? ""
|
|
320
|
+
});
|
|
321
|
+
}
|
|
322
|
+
async function register(input) {
|
|
323
|
+
if (!client) {
|
|
324
|
+
throw new Error(
|
|
325
|
+
"Experiments not initialized. Call experiments.init() first."
|
|
326
|
+
);
|
|
327
|
+
}
|
|
328
|
+
return client.register(input);
|
|
329
|
+
}
|
|
330
|
+
async function getVariant(experimentKey, userId, options) {
|
|
331
|
+
if (!client) {
|
|
332
|
+
throw new Error(
|
|
333
|
+
"Experiments not initialized. Call experiments.init() first."
|
|
334
|
+
);
|
|
335
|
+
}
|
|
336
|
+
return client.getVariant(experimentKey, userId, options);
|
|
337
|
+
}
|
|
338
|
+
async function fetch2(experimentKeys) {
|
|
339
|
+
if (!client) {
|
|
340
|
+
throw new Error(
|
|
341
|
+
"Experiments not initialized. Call experiments.init() first."
|
|
342
|
+
);
|
|
343
|
+
}
|
|
344
|
+
return client.fetch(experimentKeys);
|
|
345
|
+
}
|
|
346
|
+
async function shutdown() {
|
|
347
|
+
if (client) {
|
|
348
|
+
await client.shutdown();
|
|
349
|
+
client = null;
|
|
350
|
+
}
|
|
351
|
+
clearExperimentContext();
|
|
352
|
+
}
|
|
353
|
+
function clearExperimentContext2() {
|
|
354
|
+
clearExperimentContext();
|
|
355
|
+
}
|
|
356
|
+
function getClient() {
|
|
357
|
+
return client;
|
|
358
|
+
}
|
|
359
|
+
export {
|
|
360
|
+
EXPERIMENT_ATTRIBUTES,
|
|
361
|
+
ExperimentClient,
|
|
362
|
+
ExperimentSpanProcessor,
|
|
363
|
+
ExposureLogger,
|
|
364
|
+
addExperimentAttributes,
|
|
365
|
+
assignVariant,
|
|
366
|
+
clearExperimentContext,
|
|
367
|
+
computeHash,
|
|
368
|
+
experimentContextStorage,
|
|
369
|
+
singleton_exports as experiments,
|
|
370
|
+
getExperimentContext,
|
|
371
|
+
runWithExperimentContext,
|
|
372
|
+
setExperimentContext
|
|
373
|
+
};
|
|
374
|
+
//# sourceMappingURL=index.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../src/experiments/assignment.ts","../../src/experiments/context.ts","../../src/experiments/exposure-logger.ts","../../src/experiments/client.ts","../../src/experiments/otel.ts","../../src/experiments/singleton.ts"],"sourcesContent":["/**\n * Deterministic variant assignment for A/B experiments.\n *\n * Algorithm:\n * 1. Hash (experiment_key + user_id) → deterministic bucket [0, 1)\n * 2. If bucket >= traffic_percent/100 → user not in experiment\n * 3. Otherwise, normalize bucket within traffic and assign to variant by weight\n */\n\nimport { createHash } from \"crypto\";\nimport type { ExperimentConfig, Variant } from \"./types\";\n\nexport function computeHash(experimentKey: string, userId: string): number {\n const raw = createHash(\"sha256\")\n .update(`${experimentKey}:${userId}`)\n .digest(\"hex\");\n // Divide by 2³² to keep range strictly [0, 1)\n return parseInt(raw.slice(0, 8), 16) / 0x100000000;\n}\n\nexport function assignVariant(\n config: ExperimentConfig,\n userId: string,\n): Variant | null {\n if (!config.variants || config.variants.length === 0) {\n return null;\n }\n\n const bucket = computeHash(config.key, userId);\n const trafficThreshold = config.trafficPercent / 100;\n\n if (bucket >= trafficThreshold) {\n return null;\n }\n\n const normalizedBucket = bucket / trafficThreshold;\n const totalWeight = config.variants.reduce((sum, v) => sum + v.weight, 0);\n\n if (totalWeight <= 0) {\n return config.variants[0] ?? null;\n }\n\n let cumulative = 0;\n for (const variant of config.variants) {\n cumulative += variant.weight / totalWeight;\n if (normalizedBucket < cumulative) {\n return variant;\n }\n }\n\n return config.variants[config.variants.length - 1] ?? null;\n}\n","/**\n * Async context management for experiments.\n *\n * Uses AsyncLocalStorage.enterWith() to set context that persists for the\n * remainder of the current async execution context. This provides:\n *\n * - Request isolation in concurrent server environments\n * - Context that survives across async boundaries (streaming, etc.)\n * - No callback wrapper required\n *\n * The context persists until clearExperimentContext() is called or the\n * async context naturally ends (e.g., request completes).\n */\n\nimport { AsyncLocalStorage } from \"async_hooks\";\nimport type { ExperimentContext } from \"./types\";\n\n// AsyncLocalStorage for request-scoped context\nexport const experimentContextStorage =\n new AsyncLocalStorage<ExperimentContext>();\n\n/**\n * Get the current experiment context.\n */\nexport function getExperimentContext(): ExperimentContext | undefined {\n return experimentContextStorage.getStore();\n}\n\n/**\n * Set the experiment context for the current async execution.\n *\n * Uses enterWith() which sets context for the remainder of the current\n * async execution without requiring a callback wrapper. This means:\n * - Context persists across await boundaries\n * - Context is isolated per request in concurrent environments\n * - Context persists until clearExperimentContext() or request ends\n *\n * Called by getVariant() when a user is assigned to a variant.\n */\nexport function setExperimentContext(context: ExperimentContext): void {\n experimentContextStorage.enterWith(context);\n}\n\n/**\n * Clear the experiment context.\n *\n * Call this when you're done with an experiment session (e.g., after handling\n * a user request) to stop attributing spans to the experiment.\n *\n * Note: In most server frameworks, the async context naturally ends when the\n * request completes, so this is optional but recommended for explicit cleanup.\n */\nexport function clearExperimentContext(): void {\n // enterWith(undefined) effectively clears the context\n experimentContextStorage.enterWith(undefined as unknown as ExperimentContext);\n}\n\n/**\n * Run a function with experiment context (scoped).\n *\n * The context is automatically cleared when the function completes.\n * This is useful for synchronous operations or fully-contained async operations.\n *\n * For streaming/async patterns, prefer setExperimentContext() which persists\n * across async boundaries.\n */\nexport function runWithExperimentContext<T>(\n context: ExperimentContext,\n fn: () => T,\n): T {\n return experimentContextStorage.run(context, fn);\n}\n","/**\n * Batched asynchronous exposure logging.\n *\n * Collects exposure events in memory and flushes periodically\n * or when the batch size threshold is reached.\n */\n\nimport type { Exposure, ExposureLoggerConfig } from \"./types\";\n\nexport class ExposureLogger {\n private buffer: Exposure[] = [];\n private readonly batchSize: number;\n private readonly flushIntervalMs: number;\n private readonly apiUrl: string;\n private readonly apiKey: string;\n private readonly secretKey: string;\n private flushTimer: ReturnType<typeof setInterval> | null = null;\n private isFlushing = false;\n\n constructor(config: ExposureLoggerConfig) {\n this.apiUrl = config.apiUrl.replace(/\\/$/, \"\");\n this.apiKey = config.apiKey;\n this.secretKey = config.secretKey ?? \"\";\n this.batchSize = config.batchSize ?? 100;\n this.flushIntervalMs = config.flushIntervalMs ?? 5_000;\n\n this.flushTimer = setInterval(() => {\n this.flush().catch((err) => {\n console.error(\"[gateway] Exposure flush error:\", err);\n });\n }, this.flushIntervalMs);\n\n if (this.flushTimer.unref) {\n this.flushTimer.unref();\n }\n }\n\n log(exposure: Exposure): void {\n this.buffer.push(exposure);\n if (this.buffer.length >= this.batchSize) {\n this.flush().catch((err) => {\n console.error(\"[gateway] Exposure flush error:\", err);\n });\n }\n }\n\n async flush(): Promise<void> {\n if (this.isFlushing || this.buffer.length === 0) {\n return;\n }\n\n this.isFlushing = true;\n const batch = this.buffer.splice(0, this.buffer.length);\n\n try {\n const authHeader = this.secretKey\n ? `Basic ${Buffer.from(`${this.apiKey}:${this.secretKey}`).toString(\"base64\")}`\n : `Bearer ${this.apiKey}`;\n\n const response = await fetch(\n `${this.apiUrl}/api/public/experiments/exposures/batch`,\n {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n Authorization: authHeader,\n },\n body: JSON.stringify({\n exposures: batch,\n }),\n },\n );\n if (!response.ok) {\n this.buffer.unshift(...batch);\n console.error(\n `[gateway] Failed to log exposures: ${response.status} ${response.statusText}`,\n );\n }\n } catch (error) {\n this.buffer.unshift(...batch);\n console.error(\"[gateway] Network error logging exposures:\", error);\n } finally {\n this.isFlushing = false;\n }\n }\n\n async shutdown(): Promise<void> {\n if (this.flushTimer) {\n clearInterval(this.flushTimer);\n this.flushTimer = null;\n }\n await this.flush();\n }\n}\n","/**\n * Main A/B experiment client for TypeScript.\n *\n * Mirrors the Python SDK's ExperimentClient in:\n * gatewaysdk/sdk/src/gatewaysdk/experiments/client.py\n */\n\nimport { assignVariant } from \"./assignment\";\nimport { runWithExperimentContext, setExperimentContext } from \"./context\";\nimport { ExposureLogger } from \"./exposure-logger\";\nimport type {\n ExperimentClientConfig,\n ExperimentConfig,\n GetVariantResult,\n RegisterExperimentInput,\n} from \"./types\";\n\nexport class ExperimentClient {\n private readonly apiUrl: string;\n private readonly apiKey: string;\n private readonly secretKey: string;\n private readonly projectId: string;\n private readonly configs = new Map<string, ExperimentConfig>();\n private readonly exposureLogger: ExposureLogger;\n\n constructor(config: ExperimentClientConfig) {\n this.apiUrl = config.apiUrl.replace(/\\/$/, \"\");\n this.apiKey = config.apiKey;\n this.secretKey = config.secretKey ?? \"\";\n this.projectId = config.projectId;\n this.exposureLogger = new ExposureLogger({\n apiUrl: this.apiUrl,\n apiKey: this.apiKey,\n secretKey: this.secretKey,\n batchSize: config.exposureLogger?.batchSize,\n flushIntervalMs: config.exposureLogger?.flushIntervalMs,\n });\n }\n\n async register(input: RegisterExperimentInput): Promise<void> {\n const config: ExperimentConfig = {\n key: input.key,\n trafficPercent: input.trafficPercent ?? 100,\n variants: input.variants.map((v) => ({\n key: v.key,\n weight: v.weight ?? 1,\n config: v.config ?? {},\n })),\n };\n\n this.configs.set(config.key, config);\n\n const syncToBackend = input.syncToBackend ?? true;\n if (syncToBackend) {\n this.syncToBackendAsync(config, input.evaluatorNames).catch((err) => {\n console.error(\n `[gateway] Failed to sync experiment ${config.key}:`,\n err,\n );\n });\n }\n }\n\n async fetch(experimentKeys?: string[]): Promise<void> {\n const url = new URL(`${this.apiUrl}/api/public/experiments`);\n if (experimentKeys && experimentKeys.length > 0) {\n url.searchParams.set(\"keys\", experimentKeys.join(\",\"));\n }\n\n const authHeader = this.secretKey\n ? `Basic ${Buffer.from(`${this.apiKey}:${this.secretKey}`).toString(\"base64\")}`\n : `Bearer ${this.apiKey}`;\n\n const response = await fetch(url.toString(), {\n method: \"GET\",\n headers: {\n Authorization: authHeader,\n },\n });\n\n if (!response.ok) {\n throw new Error(\n `Failed to fetch experiments: ${response.status} ${response.statusText}`,\n );\n }\n\n const data = (await response.json()) as {\n experiments: ExperimentConfig[];\n };\n for (const config of data.experiments) {\n this.configs.set(config.key, config);\n }\n }\n\n async getVariant(\n experimentKey: string,\n userId: string,\n options?: { fetchIfMissing?: boolean },\n ): Promise<GetVariantResult> {\n const fetchIfMissing = options?.fetchIfMissing ?? true;\n\n let config = this.configs.get(experimentKey);\n if (!config && fetchIfMissing) {\n try {\n await this.fetch([experimentKey]);\n config = this.configs.get(experimentKey);\n } catch (error) {\n console.error(\n `[gateway] Failed to fetch experiment ${experimentKey}:`,\n error,\n );\n }\n }\n\n if (!config) {\n return {\n variant: null,\n inExperiment: false,\n experimentKey,\n run: (fn) => fn(),\n };\n }\n\n const variant = assignVariant(config, userId);\n if (!variant) {\n return {\n variant: null,\n inExperiment: false,\n experimentKey,\n run: (fn) => fn(),\n };\n }\n\n this.exposureLogger.log({\n userId,\n experimentId: experimentKey,\n variantKey: variant.key,\n timestamp: new Date().toISOString(),\n });\n\n const context = {\n experimentId: experimentKey,\n variantKey: variant.key,\n userId,\n };\n\n // Set context via enterWith() so spans created anywhere in this async chain are tagged.\n // Context is automatically isolated per request - no cross-request contamination.\n setExperimentContext(context);\n\n return {\n variant,\n inExperiment: true,\n experimentKey,\n run: (fn) => runWithExperimentContext(context, fn),\n };\n }\n\n getConfig(experimentKey: string): ExperimentConfig | undefined {\n return this.configs.get(experimentKey);\n }\n\n async shutdown(): Promise<void> {\n await this.exposureLogger.shutdown();\n }\n\n private async syncToBackendAsync(\n config: ExperimentConfig,\n evaluatorNames?: string[],\n ): Promise<void> {\n const authHeader = this.secretKey\n ? `Basic ${Buffer.from(`${this.apiKey}:${this.secretKey}`).toString(\"base64\")}`\n : `Bearer ${this.apiKey}`;\n\n const response = await fetch(`${this.apiUrl}/api/public/experiments`, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n Authorization: authHeader,\n },\n body: JSON.stringify({\n key: config.key,\n trafficPercent: config.trafficPercent,\n variants: config.variants,\n evaluatorNames: evaluatorNames ?? [],\n }),\n });\n\n if (!response.ok) {\n const text = await response.text();\n throw new Error(\n `Failed to sync experiment: ${response.status} ${response.statusText} - ${text}`,\n );\n }\n\n console.log(`[gateway] Synced experiment '${config.key}' to backend`);\n }\n}\n","/**\n * OpenTelemetry integration for A/B experiments.\n *\n * Provides a SpanProcessor that automatically injects experiment\n * context into spans. Mirrors the Python SDK's TracingContextSpanProcessor.\n */\n\nimport type { Context } from \"@opentelemetry/api\";\nimport type {\n SpanProcessor,\n Span,\n ReadableSpan,\n} from \"@opentelemetry/sdk-trace-base\";\nimport { getExperimentContext } from \"./context\";\n\nexport const EXPERIMENT_ATTRIBUTES = {\n EXPERIMENT_ID: \"gateway.experiment.id\",\n VARIANT_KEY: \"gateway.variant.key\",\n USER_ID: \"gateway.experiment.user_id\",\n} as const;\n\nexport class ExperimentSpanProcessor implements SpanProcessor {\n onStart(span: Span, _parentContext: Context): void {\n const ctx = getExperimentContext();\n if (ctx) {\n span.setAttribute(EXPERIMENT_ATTRIBUTES.EXPERIMENT_ID, ctx.experimentId);\n span.setAttribute(EXPERIMENT_ATTRIBUTES.VARIANT_KEY, ctx.variantKey);\n span.setAttribute(EXPERIMENT_ATTRIBUTES.USER_ID, ctx.userId);\n }\n }\n\n onEnd(_span: ReadableSpan): void {}\n\n async shutdown(): Promise<void> {}\n\n async forceFlush(): Promise<void> {}\n}\n\nexport function addExperimentAttributes(\n span: Span,\n experimentId: string,\n variantKey: string,\n userId: string,\n): void {\n span.setAttribute(EXPERIMENT_ATTRIBUTES.EXPERIMENT_ID, experimentId);\n span.setAttribute(EXPERIMENT_ATTRIBUTES.VARIANT_KEY, variantKey);\n span.setAttribute(EXPERIMENT_ATTRIBUTES.USER_ID, userId);\n}\n","/**\n * Singleton experiment client for simple usage.\n *\n * This mirrors the Python SDK's `gateway.experiments` singleton pattern.\n * For advanced use cases, instantiate ExperimentClient directly.\n */\n\nimport { ExperimentClient } from \"./client\";\nimport { clearExperimentContext as clearContext } from \"./context\";\nimport type {\n ExperimentClientConfig,\n GetVariantResult,\n RegisterExperimentInput,\n} from \"./types\";\n\nlet client: ExperimentClient | null = null;\n\nexport interface InitConfig {\n apiKey: string;\n secretKey?: string;\n baseUrl: string;\n projectId?: string;\n}\n\n/**\n * Initialize the experiments singleton.\n * Must be called before using other methods.\n */\nexport function init(config: InitConfig): void {\n client = new ExperimentClient({\n apiUrl: config.baseUrl,\n apiKey: config.apiKey,\n secretKey: config.secretKey,\n projectId: config.projectId ?? \"\",\n });\n}\n\n/**\n * Register an experiment configuration.\n */\nexport async function register(input: RegisterExperimentInput): Promise<void> {\n if (!client) {\n throw new Error(\n \"Experiments not initialized. Call experiments.init() first.\",\n );\n }\n return client.register(input);\n}\n\n/**\n * Get variant for a user. Returns null if user is not in experiment.\n */\nexport async function getVariant(\n experimentKey: string,\n userId: string,\n options?: { fetchIfMissing?: boolean },\n): Promise<GetVariantResult> {\n if (!client) {\n throw new Error(\n \"Experiments not initialized. Call experiments.init() first.\",\n );\n }\n return client.getVariant(experimentKey, userId, options);\n}\n\n/**\n * Fetch experiment configurations from the backend.\n */\nexport async function fetch(experimentKeys?: string[]): Promise<void> {\n if (!client) {\n throw new Error(\n \"Experiments not initialized. Call experiments.init() first.\",\n );\n }\n return client.fetch(experimentKeys);\n}\n\n/**\n * Flush pending exposures and shut down the client.\n */\nexport async function shutdown(): Promise<void> {\n if (client) {\n await client.shutdown();\n client = null;\n }\n // Also clear any lingering experiment context\n clearContext();\n}\n\n/**\n * Clear the current experiment context.\n *\n * Call this when you're done with an experiment session (e.g., after handling\n * a user request) to stop attributing new spans to the experiment.\n *\n * This mirrors Python's `gateway.experiments.clear_current_experiment()`.\n */\nexport function clearExperimentContext(): void {\n clearContext();\n}\n\n/**\n * Get the underlying ExperimentClient instance.\n * Returns null if not initialized.\n */\nexport function getClient(): ExperimentClient | null {\n return client;\n}\n"],"mappings":"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","names":["clearExperimentContext","fetch","fetch","clearExperimentContext"]}
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the tracing module.
|
|
3
|
+
*/
|
|
4
|
+
interface TracingConfig {
|
|
5
|
+
/**
|
|
6
|
+
* Gateway server URL (e.g., "https://app.gateway.dev").
|
|
7
|
+
* Falls back to GATEWAY_HOST or GATEWAY_HOST env var.
|
|
8
|
+
*/
|
|
9
|
+
host?: string;
|
|
10
|
+
/**
|
|
11
|
+
* Public key for authentication (pk-lf-...).
|
|
12
|
+
* Falls back to GATEWAY_PUBLIC_KEY or GATEWAY_PUBLIC_KEY env var.
|
|
13
|
+
*/
|
|
14
|
+
publicKey?: string;
|
|
15
|
+
/**
|
|
16
|
+
* Secret key for authentication (sk-lf-...).
|
|
17
|
+
* Falls back to GATEWAY_SECRET_KEY or GATEWAY_SECRET_KEY env var.
|
|
18
|
+
*/
|
|
19
|
+
secretKey?: string;
|
|
20
|
+
/**
|
|
21
|
+
* Service name for resource attributes.
|
|
22
|
+
* Defaults to "gatewaysdk-tracing".
|
|
23
|
+
*/
|
|
24
|
+
serviceName?: string;
|
|
25
|
+
/**
|
|
26
|
+
* Environment name (e.g., "production", "staging").
|
|
27
|
+
* Sets resource attribute for filtering traces in Gateway.
|
|
28
|
+
*/
|
|
29
|
+
environment?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Application version (e.g., "1.2.3", git SHA).
|
|
32
|
+
* Sets resource attribute for tracking regressions.
|
|
33
|
+
*/
|
|
34
|
+
version?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Whether to enable debug logging to console.
|
|
37
|
+
* Defaults to false.
|
|
38
|
+
*/
|
|
39
|
+
debug?: boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Whether to automatically add ExperimentSpanProcessor when imported
|
|
42
|
+
* from the main entry ("@withgateway/sdk"). Has no effect when imported
|
|
43
|
+
* from the subpath ("@withgateway/sdk/tracing") — use customSpanProcessors
|
|
44
|
+
* instead.
|
|
45
|
+
* Defaults to true.
|
|
46
|
+
*/
|
|
47
|
+
enableExperiments?: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* Additional span processors to register with the provider.
|
|
50
|
+
* These are added before the BatchSpanProcessor (which handles export).
|
|
51
|
+
*
|
|
52
|
+
* When using the main entry (`import { tracing } from "@withgateway/sdk"`),
|
|
53
|
+
* ExperimentSpanProcessor is automatically added unless enableExperiments
|
|
54
|
+
* is false. When using the subpath import, pass it here manually:
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* ```typescript
|
|
58
|
+
* import * as tracing from "@withgateway/sdk/tracing";
|
|
59
|
+
* import { ExperimentSpanProcessor } from "@withgateway/sdk/experiments";
|
|
60
|
+
*
|
|
61
|
+
* tracing.init({ customSpanProcessors: [new ExperimentSpanProcessor()] });
|
|
62
|
+
* ```
|
|
63
|
+
*/
|
|
64
|
+
customSpanProcessors?: unknown[];
|
|
65
|
+
/**
|
|
66
|
+
* Custom OTLP endpoint URL. If not provided, derived from host.
|
|
67
|
+
*/
|
|
68
|
+
endpoint?: string;
|
|
69
|
+
/**
|
|
70
|
+
* Batch processor configuration.
|
|
71
|
+
*/
|
|
72
|
+
batch?: {
|
|
73
|
+
/** Max spans buffered in memory. Default: 2048 */
|
|
74
|
+
maxQueueSize?: number;
|
|
75
|
+
/** How often to flush spans (ms). Default: 5000 */
|
|
76
|
+
scheduledDelayMillis?: number;
|
|
77
|
+
/** Max spans per export call. Default: 512 */
|
|
78
|
+
maxExportBatchSize?: number;
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
interface TracingState {
|
|
82
|
+
initialized: boolean;
|
|
83
|
+
provider: unknown | null;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Initialization and lifecycle management for GatewaySDK tracing.
|
|
88
|
+
*
|
|
89
|
+
* This module provides the core init(), shutdown(), and flush() functions
|
|
90
|
+
* for managing the OpenTelemetry TracerProvider lifecycle.
|
|
91
|
+
*
|
|
92
|
+
* Mirrors the Python SDK's tracing.init() for a consistent developer experience.
|
|
93
|
+
*/
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Initialize GatewaySDK tracing with automatic OpenTelemetry configuration.
|
|
97
|
+
*
|
|
98
|
+
* This function configures OpenTelemetry with a connection to Gateway
|
|
99
|
+
* and sets up the ExperimentSpanProcessor for automatic experiment tagging.
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* ```typescript
|
|
103
|
+
* import { tracing } from "@withgateway/sdk";
|
|
104
|
+
*
|
|
105
|
+
* // Using environment variables (GATEWAY_HOST, GATEWAY_PUBLIC_KEY, GATEWAY_SECRET_KEY)
|
|
106
|
+
* tracing.init();
|
|
107
|
+
*
|
|
108
|
+
* // Or with explicit configuration
|
|
109
|
+
* tracing.init({
|
|
110
|
+
* host: "https://app.gateway.dev",
|
|
111
|
+
* publicKey: "pk-lf-...",
|
|
112
|
+
* secretKey: "sk-lf-...",
|
|
113
|
+
* serviceName: "my-agent",
|
|
114
|
+
* environment: "production",
|
|
115
|
+
* });
|
|
116
|
+
* ```
|
|
117
|
+
*/
|
|
118
|
+
declare function init(config?: TracingConfig): void;
|
|
119
|
+
/**
|
|
120
|
+
* Force flush all pending spans without shutting down.
|
|
121
|
+
*
|
|
122
|
+
* Useful for ensuring spans are exported at specific points
|
|
123
|
+
* (e.g., after completing a batch of work) without ending the tracing session.
|
|
124
|
+
*
|
|
125
|
+
* @returns Promise that resolves when flush completes
|
|
126
|
+
*/
|
|
127
|
+
declare function flush(): Promise<void>;
|
|
128
|
+
/**
|
|
129
|
+
* Force flush all pending spans and shutdown the tracer provider.
|
|
130
|
+
*
|
|
131
|
+
* This function should be called before process exit to ensure all spans
|
|
132
|
+
* are exported. It is safe to call multiple times.
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* ```typescript
|
|
136
|
+
* import { tracing } from "@withgateway/sdk";
|
|
137
|
+
*
|
|
138
|
+
* tracing.init();
|
|
139
|
+
*
|
|
140
|
+
* // On shutdown
|
|
141
|
+
* process.on("SIGTERM", async () => {
|
|
142
|
+
* await tracing.shutdown();
|
|
143
|
+
* process.exit(0);
|
|
144
|
+
* });
|
|
145
|
+
* ```
|
|
146
|
+
*/
|
|
147
|
+
declare function shutdown(): Promise<void>;
|
|
148
|
+
/**
|
|
149
|
+
* Check if tracing has been initialized.
|
|
150
|
+
*/
|
|
151
|
+
declare function isInitialized(): boolean;
|
|
152
|
+
/**
|
|
153
|
+
* Check if Gateway is configured via environment variables.
|
|
154
|
+
*/
|
|
155
|
+
declare function isGatewayConfigured(): boolean;
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Tracing module for GatewaySDK TypeScript SDK.
|
|
159
|
+
*
|
|
160
|
+
* Provides a simple init() function that configures OpenTelemetry with
|
|
161
|
+
* Gateway, mirroring the Python SDK's tracing.init() experience.
|
|
162
|
+
*
|
|
163
|
+
* @example
|
|
164
|
+
* ```typescript
|
|
165
|
+
* import { tracing } from "@withgateway/sdk";
|
|
166
|
+
*
|
|
167
|
+
* // Initialize with environment variables
|
|
168
|
+
* tracing.init();
|
|
169
|
+
*
|
|
170
|
+
* // Or with explicit configuration
|
|
171
|
+
* tracing.init({
|
|
172
|
+
* host: "https://app.gateway.dev",
|
|
173
|
+
* publicKey: "pk-lf-...",
|
|
174
|
+
* secretKey: "sk-lf-...",
|
|
175
|
+
* });
|
|
176
|
+
*
|
|
177
|
+
* // Ensure cleanup on shutdown
|
|
178
|
+
* process.on("SIGTERM", () => tracing.shutdown());
|
|
179
|
+
* ```
|
|
180
|
+
*/
|
|
181
|
+
|
|
182
|
+
type _tracingModule_TracingConfig = TracingConfig;
|
|
183
|
+
type _tracingModule_TracingState = TracingState;
|
|
184
|
+
declare const _tracingModule_flush: typeof flush;
|
|
185
|
+
declare const _tracingModule_init: typeof init;
|
|
186
|
+
declare const _tracingModule_isGatewayConfigured: typeof isGatewayConfigured;
|
|
187
|
+
declare const _tracingModule_isInitialized: typeof isInitialized;
|
|
188
|
+
declare const _tracingModule_shutdown: typeof shutdown;
|
|
189
|
+
declare namespace _tracingModule {
|
|
190
|
+
export { type _tracingModule_TracingConfig as TracingConfig, type _tracingModule_TracingState as TracingState, _tracingModule_flush as flush, _tracingModule_init as init, _tracingModule_isGatewayConfigured as isGatewayConfigured, _tracingModule_isInitialized as isInitialized, _tracingModule_shutdown as shutdown };
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
export { type TracingConfig as T, _tracingModule as _, type TracingState as a, isGatewayConfigured as b, isInitialized as c, flush as f, init as i, shutdown as s };
|