@scalemule/sdk 0.0.75 → 0.0.77
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 +26 -0
- package/dist/experiments-RH_CTd1R.d.mts +53 -0
- package/dist/experiments-RH_CTd1R.d.ts +53 -0
- package/dist/flags/server.d.mts +4 -0
- package/dist/flags/server.d.ts +4 -0
- package/dist/flags/server.js +17 -0
- package/dist/flags/server.mjs +17 -0
- package/dist/index.d.mts +253 -1
- package/dist/index.d.ts +253 -1
- package/dist/index.js +191 -2
- package/dist/index.mjs +178 -1
- package/package.json +1 -1
package/dist/index.mjs
CHANGED
|
@@ -5684,6 +5684,58 @@ var BillingService = class extends ServiceModule {
|
|
|
5684
5684
|
}
|
|
5685
5685
|
};
|
|
5686
5686
|
|
|
5687
|
+
// src/experiments.ts
|
|
5688
|
+
var EXPERIMENTS_PROPERTY = "experiments";
|
|
5689
|
+
var EXPERIMENT_EXPOSED_EVENT = "experiment_exposed";
|
|
5690
|
+
var MAX_EXPERIMENTS_PER_EVENT = 10;
|
|
5691
|
+
var KEY_PATTERN = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
|
|
5692
|
+
var VARIANT_PATTERN = /^[a-z0-9][a-z0-9_.:-]{0,63}$/;
|
|
5693
|
+
function isExperimentKey(value) {
|
|
5694
|
+
return typeof value === "string" && KEY_PATTERN.test(value);
|
|
5695
|
+
}
|
|
5696
|
+
function isVariantKey(value) {
|
|
5697
|
+
return typeof value === "string" && VARIANT_PATTERN.test(value);
|
|
5698
|
+
}
|
|
5699
|
+
function experimentVariant(evaluation) {
|
|
5700
|
+
if (!evaluation) return null;
|
|
5701
|
+
if (isVariantKey(evaluation.variant_key)) return evaluation.variant_key;
|
|
5702
|
+
if (isVariantKey(evaluation.value)) return evaluation.value;
|
|
5703
|
+
return null;
|
|
5704
|
+
}
|
|
5705
|
+
function normalizeExperiments(input) {
|
|
5706
|
+
const result = {};
|
|
5707
|
+
if (!input || typeof input !== "object" || Array.isArray(input)) return result;
|
|
5708
|
+
let count = 0;
|
|
5709
|
+
for (const [key, value] of Object.entries(input)) {
|
|
5710
|
+
if (count >= MAX_EXPERIMENTS_PER_EVENT) break;
|
|
5711
|
+
if (isExperimentKey(key) && isVariantKey(value)) {
|
|
5712
|
+
result[key] = value;
|
|
5713
|
+
count++;
|
|
5714
|
+
}
|
|
5715
|
+
}
|
|
5716
|
+
return result;
|
|
5717
|
+
}
|
|
5718
|
+
function withExperiments(properties, experiments) {
|
|
5719
|
+
const normalized = normalizeExperiments({
|
|
5720
|
+
...normalizeExperiments(properties?.[EXPERIMENTS_PROPERTY]),
|
|
5721
|
+
...experiments ?? {}
|
|
5722
|
+
});
|
|
5723
|
+
if (Object.keys(normalized).length === 0) return properties;
|
|
5724
|
+
return { ...properties ?? {}, [EXPERIMENTS_PROPERTY]: normalized };
|
|
5725
|
+
}
|
|
5726
|
+
function exposureEvent(flagKey, variant) {
|
|
5727
|
+
if (!isExperimentKey(flagKey)) throw new Error(`Invalid experiment flag key: ${flagKey}`);
|
|
5728
|
+
if (!isVariantKey(variant)) throw new Error(`Invalid experiment variant: ${variant}`);
|
|
5729
|
+
return {
|
|
5730
|
+
event_name: EXPERIMENT_EXPOSED_EVENT,
|
|
5731
|
+
event_category: "system",
|
|
5732
|
+
properties: { flag_key: flagKey, variant, [EXPERIMENTS_PROPERTY]: { [flagKey]: variant } }
|
|
5733
|
+
};
|
|
5734
|
+
}
|
|
5735
|
+
function exposureStorageKey(flagKey) {
|
|
5736
|
+
return `sm_experiment_exposed:${flagKey}`;
|
|
5737
|
+
}
|
|
5738
|
+
|
|
5687
5739
|
// src/services/analytics.ts
|
|
5688
5740
|
var AnalyticsService = class extends ServiceModule {
|
|
5689
5741
|
constructor() {
|
|
@@ -5700,6 +5752,14 @@ var AnalyticsService = class extends ServiceModule {
|
|
|
5700
5752
|
}
|
|
5701
5753
|
return this.post("/v2/events", payload, options);
|
|
5702
5754
|
}
|
|
5755
|
+
/**
|
|
5756
|
+
* Track that a visitor saw an experiment variant. Send it once per visitor and flag; the event
|
|
5757
|
+
* carries `properties.experiments` so the experiment report attributes it.
|
|
5758
|
+
*/
|
|
5759
|
+
async trackExposure(flagKey, variant, userId, options) {
|
|
5760
|
+
const event = exposureEvent(flagKey, variant);
|
|
5761
|
+
return this.track(event.event_name, event.properties, userId, options);
|
|
5762
|
+
}
|
|
5703
5763
|
async trackBatch(events, options) {
|
|
5704
5764
|
const mapped = events.map(({ event, ...rest }) => ({ event_name: event, ...rest }));
|
|
5705
5765
|
return this.post("/v2/events/batch", { events: mapped }, options);
|
|
@@ -5774,6 +5834,19 @@ var FlagsService = class extends ServiceModule {
|
|
|
5774
5834
|
async evaluate(flagKey, context = {}, environment = "prod", options) {
|
|
5775
5835
|
return this.post("/evaluate", { flag_key: flagKey, environment, context }, options);
|
|
5776
5836
|
}
|
|
5837
|
+
/**
|
|
5838
|
+
* Assign a visitor to an experiment: a flag with weighted variants, evaluated with a stable
|
|
5839
|
+
* identifier (`session_id` or `user_id`) so the assignment is sticky. Attach the result to
|
|
5840
|
+
* analytics events with `withExperiments` and track one exposure with `analytics.trackExposure`.
|
|
5841
|
+
*/
|
|
5842
|
+
async experiment(flagKey, context = {}, environment = "prod", options) {
|
|
5843
|
+
const response = await this.evaluate(flagKey, context, environment, options);
|
|
5844
|
+
if (response.error || !response.data) return { data: null, error: response.error };
|
|
5845
|
+
return {
|
|
5846
|
+
data: { flag_key: flagKey, variant: experimentVariant(response.data), evaluation: response.data },
|
|
5847
|
+
error: null
|
|
5848
|
+
};
|
|
5849
|
+
}
|
|
5777
5850
|
async evaluateBatch(flagKeys, context = {}, environment = "prod", options) {
|
|
5778
5851
|
return this.post(
|
|
5779
5852
|
"/evaluate/batch",
|
|
@@ -7026,6 +7099,97 @@ var CommunityMapsGeographyService = class extends ServiceModule {
|
|
|
7026
7099
|
}
|
|
7027
7100
|
};
|
|
7028
7101
|
|
|
7102
|
+
// src/services/local-intelligence.ts
|
|
7103
|
+
var LocalIntelligenceService = class extends ServiceModule {
|
|
7104
|
+
constructor() {
|
|
7105
|
+
super(...arguments);
|
|
7106
|
+
this.basePath = "/v1/news";
|
|
7107
|
+
}
|
|
7108
|
+
scope(publication) {
|
|
7109
|
+
return `/intelligence/publications/${encodeURIComponent(publication)}`;
|
|
7110
|
+
}
|
|
7111
|
+
records(publication, params = {}, options) {
|
|
7112
|
+
return this._get(this.withQuery(`${this.scope(publication)}/records`, params), options);
|
|
7113
|
+
}
|
|
7114
|
+
get(publication, record, options) {
|
|
7115
|
+
return this._get(`${this.scope(publication)}/records/${encodeURIComponent(record)}`, options);
|
|
7116
|
+
}
|
|
7117
|
+
changes(publication, params = {}, options) {
|
|
7118
|
+
return this._get(this.withQuery(`${this.scope(publication)}/changes`, params), options);
|
|
7119
|
+
}
|
|
7120
|
+
briefing(publication, params, options) {
|
|
7121
|
+
return this._get(this.withQuery(`${this.scope(publication)}/briefing`, params), options);
|
|
7122
|
+
}
|
|
7123
|
+
/** Agent-safe explicit preferences: evaluated for this request and never saved. */
|
|
7124
|
+
briefingForPreferences(publication, input, options) {
|
|
7125
|
+
return this.post(`${this.scope(publication)}/briefing`, input, options);
|
|
7126
|
+
}
|
|
7127
|
+
preferences(publication, options) {
|
|
7128
|
+
return this._get(`${this.scope(publication)}/preferences`, options);
|
|
7129
|
+
}
|
|
7130
|
+
savePreferences(publication, expectedRevision, preferences, options) {
|
|
7131
|
+
return this.put(
|
|
7132
|
+
`${this.scope(publication)}/preferences`,
|
|
7133
|
+
{ expected_revision: expectedRevision, preferences },
|
|
7134
|
+
options
|
|
7135
|
+
);
|
|
7136
|
+
}
|
|
7137
|
+
deletePreferences(publication, options) {
|
|
7138
|
+
return this.del(`${this.scope(publication)}/preferences`, options);
|
|
7139
|
+
}
|
|
7140
|
+
feedback(publication, record, recordRevision, outcome, options) {
|
|
7141
|
+
return this.post(
|
|
7142
|
+
`${this.scope(publication)}/records/${encodeURIComponent(record)}/feedback`,
|
|
7143
|
+
{ record_revision: recordRevision, outcome },
|
|
7144
|
+
options
|
|
7145
|
+
);
|
|
7146
|
+
}
|
|
7147
|
+
deleteFeedback(publication, record, options) {
|
|
7148
|
+
return this.del(`${this.scope(publication)}/records/${encodeURIComponent(record)}/feedback`, options);
|
|
7149
|
+
}
|
|
7150
|
+
/** Requires a human editor with publication publish authority. */
|
|
7151
|
+
release(publication, input, idempotencyKey, options) {
|
|
7152
|
+
return this.post(`/publications/${encodeURIComponent(publication)}/intelligence`, input, {
|
|
7153
|
+
...options,
|
|
7154
|
+
headers: { ...options?.headers, "idempotency-key": idempotencyKey }
|
|
7155
|
+
});
|
|
7156
|
+
}
|
|
7157
|
+
withdraw(publication, record, expectedRevision, reason, options) {
|
|
7158
|
+
return this.post(
|
|
7159
|
+
`/publications/${encodeURIComponent(publication)}/intelligence/${encodeURIComponent(record)}/withdraw`,
|
|
7160
|
+
{ expected_revision: expectedRevision, reason },
|
|
7161
|
+
options
|
|
7162
|
+
);
|
|
7163
|
+
}
|
|
7164
|
+
};
|
|
7165
|
+
function applyIntelligenceChanges(current, changes, now = Date.now()) {
|
|
7166
|
+
if (changes.contract_version !== "basenews/1" || changes.scope.application_id !== current.scope.application_id || changes.scope.publication_id !== current.scope.publication_id)
|
|
7167
|
+
throw new Error("Intelligence change scope mismatch");
|
|
7168
|
+
const sequenceValue = (value) => {
|
|
7169
|
+
if (!/^(0|[1-9][0-9]{0,19})$/.test(value)) throw new Error("Invalid intelligence sequence");
|
|
7170
|
+
return BigInt(value);
|
|
7171
|
+
};
|
|
7172
|
+
let sequence = sequenceValue(current.sequence);
|
|
7173
|
+
let previous = -1n;
|
|
7174
|
+
const next = new Map(current.records);
|
|
7175
|
+
for (const item of changes.items) {
|
|
7176
|
+
const received = sequenceValue(item.sequence);
|
|
7177
|
+
if (received <= previous) throw new Error("Unordered intelligence change batch");
|
|
7178
|
+
previous = received;
|
|
7179
|
+
if (received <= sequence) continue;
|
|
7180
|
+
if (received !== sequence + 1n) throw new Error("Intelligence change gap; resume the previous cursor");
|
|
7181
|
+
sequence = received;
|
|
7182
|
+
if (item.removed || !item.record) next.delete(item.id);
|
|
7183
|
+
else if (item.record.id !== item.id) throw new Error("Intelligence change identity mismatch");
|
|
7184
|
+
else if (!next.has(item.id) || next.get(item.id).revision <= item.record.revision) next.set(item.id, item.record);
|
|
7185
|
+
}
|
|
7186
|
+
for (const [id, record] of next) {
|
|
7187
|
+
const expiry = Date.parse(record.refresh_after);
|
|
7188
|
+
if (record.contract_version !== "basenews/1" || !Number.isFinite(expiry) || expiry <= now) next.delete(id);
|
|
7189
|
+
}
|
|
7190
|
+
return { scope: current.scope, sequence: sequence.toString(), records: next };
|
|
7191
|
+
}
|
|
7192
|
+
|
|
7029
7193
|
// src/services/polls.ts
|
|
7030
7194
|
var PollsService = class extends ServiceModule {
|
|
7031
7195
|
constructor() {
|
|
@@ -9173,6 +9337,7 @@ var ScaleMule = class {
|
|
|
9173
9337
|
this.leaderboard = new LeaderboardService(this._client);
|
|
9174
9338
|
this.listings = new ListingsService(this._client);
|
|
9175
9339
|
this.communityMaps = new CommunityMapsService(this._client);
|
|
9340
|
+
this.localIntelligence = new LocalIntelligenceService(this._client);
|
|
9176
9341
|
this.polls = new PollsService(this._client);
|
|
9177
9342
|
this.events = new EventsService(this._client);
|
|
9178
9343
|
this.graph = new GraphService(this._client);
|
|
@@ -9339,6 +9504,8 @@ export {
|
|
|
9339
9504
|
CreatorMakerService,
|
|
9340
9505
|
DataService,
|
|
9341
9506
|
DecisionsService,
|
|
9507
|
+
EXPERIMENTS_PROPERTY,
|
|
9508
|
+
EXPERIMENT_EXPOSED_EVENT,
|
|
9342
9509
|
ErrorCodes,
|
|
9343
9510
|
EventsService,
|
|
9344
9511
|
FlagContentService,
|
|
@@ -9350,7 +9517,9 @@ export {
|
|
|
9350
9517
|
LeaderboardService,
|
|
9351
9518
|
LeadsService,
|
|
9352
9519
|
ListingsService,
|
|
9520
|
+
LocalIntelligenceService,
|
|
9353
9521
|
LoggerService,
|
|
9522
|
+
MAX_EXPERIMENTS_PER_EVENT,
|
|
9354
9523
|
MEDIA_PRESETS,
|
|
9355
9524
|
MediaService,
|
|
9356
9525
|
NotificationsService,
|
|
@@ -9381,6 +9550,7 @@ export {
|
|
|
9381
9550
|
WebPushManager,
|
|
9382
9551
|
WebhooksService,
|
|
9383
9552
|
WorkspacesService,
|
|
9553
|
+
applyIntelligenceChanges,
|
|
9384
9554
|
buildClientContextHeaders,
|
|
9385
9555
|
calculateTotalParts,
|
|
9386
9556
|
canPerform,
|
|
@@ -9391,6 +9561,9 @@ export {
|
|
|
9391
9561
|
detectCountryFromE164,
|
|
9392
9562
|
detectNetworkClass,
|
|
9393
9563
|
ensureAnonymousId,
|
|
9564
|
+
experimentVariant,
|
|
9565
|
+
exposureEvent,
|
|
9566
|
+
exposureStorageKey,
|
|
9394
9567
|
extractClientContext,
|
|
9395
9568
|
findPhoneCountryByCode,
|
|
9396
9569
|
findPhoneCountryByDialCode,
|
|
@@ -9399,8 +9572,11 @@ export {
|
|
|
9399
9572
|
getMeasuredBandwidthMbps,
|
|
9400
9573
|
getPartRange,
|
|
9401
9574
|
hasMinRoleLevel,
|
|
9575
|
+
isExperimentKey,
|
|
9402
9576
|
isValidE164Phone,
|
|
9577
|
+
isVariantKey,
|
|
9403
9578
|
normalizeAndValidatePhone,
|
|
9579
|
+
normalizeExperiments,
|
|
9404
9580
|
normalizePhoneNumber,
|
|
9405
9581
|
pollSharePercent,
|
|
9406
9582
|
pollVoterKey,
|
|
@@ -9410,5 +9586,6 @@ export {
|
|
|
9410
9586
|
startMediaCapture,
|
|
9411
9587
|
uploadMultipartToS3,
|
|
9412
9588
|
uploadSingleToS3,
|
|
9413
|
-
validateIP
|
|
9589
|
+
validateIP,
|
|
9590
|
+
withExperiments
|
|
9414
9591
|
};
|