@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/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
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scalemule/sdk",
3
- "version": "0.0.75",
3
+ "version": "0.0.77",
4
4
  "description": "Official TypeScript/JavaScript SDK for ScaleMule Backend-as-a-Service",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",