@splitsoftware/splitio 11.0.0-rc.2 → 11.0.0-rc.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.
@@ -1,1689 +0,0 @@
1
- // Type definitions for JavaScript and NodeJS Split Software SDK
2
- // Project: http://www.split.io/
3
- // Definitions by: Nico Zelaya <https://github.com/NicoZelaya/>
4
-
5
- import { RedisOptions } from "ioredis";
6
- import { RequestOptions } from "http";
7
-
8
- export as namespace SplitIO;
9
- export = SplitIO;
10
-
11
- /**
12
- * @typedef {Object} EventConsts
13
- * @property {string} SDK_READY The ready event.
14
- * @property {string} SDK_READY_FROM_CACHE The ready event when fired with cached data.
15
- * @property {string} SDK_READY_TIMED_OUT The timeout event.
16
- * @property {string} SDK_UPDATE The update event.
17
- */
18
- type EventConsts = {
19
- SDK_READY: 'init::ready',
20
- SDK_READY_FROM_CACHE: 'init::cache-ready',
21
- SDK_READY_TIMED_OUT: 'init::timeout',
22
- SDK_UPDATE: 'state::update'
23
- };
24
- /**
25
- * SDK Modes.
26
- * @typedef {string} SDKMode
27
- */
28
- type SDKMode = 'standalone' | 'consumer';
29
- /**
30
- * Storage types.
31
- * @typedef {string} StorageType
32
- */
33
- type StorageType = 'MEMORY' | 'LOCALSTORAGE' | 'REDIS';
34
- /**
35
- * Settings interface. This is a representation of the settings the SDK expose, that's why
36
- * most of it's props are readonly. Only features should be rewritten when localhost mode is active.
37
- * @interface ISettings
38
- */
39
- interface ISettings {
40
- readonly core: {
41
- authorizationKey: string,
42
- key: SplitIO.SplitKey,
43
- labelsEnabled: boolean,
44
- IPAddressesEnabled: boolean
45
- },
46
- readonly mode: SDKMode,
47
- readonly scheduler: {
48
- featuresRefreshRate: number,
49
- impressionsRefreshRate: number,
50
- impressionsQueueSize: number,
51
- /**
52
- * @deprecated
53
- */
54
- metricsRefreshRate?: number,
55
- telemetryRefreshRate: number,
56
- segmentsRefreshRate: number,
57
- offlineRefreshRate: number,
58
- eventsPushRate: number,
59
- eventsQueueSize: number,
60
- pushRetryBackoffBase: number
61
- },
62
- readonly startup: {
63
- readyTimeout: number,
64
- requestTimeoutBeforeReady: number,
65
- retriesOnFailureBeforeReady: number,
66
- eventsFirstPushWindow: number
67
- },
68
- readonly storage: {
69
- prefix: string,
70
- options: Object,
71
- type: StorageType
72
- },
73
- readonly preloadedData?: SplitIO.PreloadedData,
74
- readonly urls: {
75
- events: string,
76
- sdk: string,
77
- auth: string,
78
- streaming: string,
79
- telemetry: string
80
- },
81
- readonly debug: boolean | LogLevel,
82
- readonly version: string,
83
- /**
84
- * Mocked features map if using in browser, or mocked features file path string if using in NodeJS.
85
- */
86
- features: SplitIO.MockedFeaturesMap | SplitIO.MockedFeaturesFilePath,
87
- readonly streamingEnabled: boolean,
88
- readonly sync: {
89
- splitFilters: SplitIO.SplitFilter[],
90
- impressionsMode: SplitIO.ImpressionsMode,
91
- enabled: boolean,
92
- flagSpecVersion: string,
93
- requestOptions?: {
94
- getHeaderOverrides?: (context: { headers: Record<string, string> }) => Record<string, string>
95
- }
96
- }
97
- /**
98
- * User consent status if using in browser. Undefined if using in NodeJS.
99
- */
100
- readonly userConsent?: SplitIO.ConsentStatus
101
- }
102
- /**
103
- * Log levels.
104
- * @typedef {string} LogLevel
105
- */
106
- type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE';
107
- /**
108
- * Logger API
109
- * @interface ILoggerAPI
110
- */
111
- interface ILoggerAPI {
112
- /**
113
- * Enables SDK logging to the console.
114
- * @function enable
115
- * @returns {void}
116
- */
117
- enable(): void,
118
- /**
119
- * Disables SDK logging.
120
- * @function disable
121
- * @returns {void}
122
- */
123
- disable(): void,
124
- /**
125
- * Sets a log level for the SDK logs.
126
- * @function setLogLevel
127
- * @returns {void}
128
- */
129
- setLogLevel(logLevel: LogLevel): void,
130
- /**
131
- * Log level constants. Use this to pass them to setLogLevel function.
132
- */
133
- LogLevel: {
134
- [level in LogLevel]: LogLevel
135
- }
136
- }
137
- /**
138
- * User consent API
139
- * @interface IUserConsentAPI
140
- */
141
- interface IUserConsentAPI {
142
- /**
143
- * Sets or updates the user consent status. Possible values are `true` and `false`, which represent user consent `'GRANTED'` and `'DECLINED'` respectively.
144
- * - `true ('GRANTED')`: the user has granted consent for tracking events and impressions. The SDK will send them to Split cloud.
145
- * - `false ('DECLINED')`: the user has declined consent for tracking events and impressions. The SDK will not send them to Split cloud.
146
- *
147
- * NOTE: calling this method updates the user consent at a factory level, affecting all clients of the same factory.
148
- *
149
- * @function setStatus
150
- * @param {boolean} userConsent The user consent status, true for 'GRANTED' and false for 'DECLINED'.
151
- * @returns {boolean} Whether the provided param is a valid value (i.e., a boolean value) or not.
152
- */
153
- setStatus(userConsent: boolean): boolean;
154
- /**
155
- * Gets the user consent status.
156
- *
157
- * @function getStatus
158
- * @returns {ConsentStatus} The user consent status.
159
- */
160
- getStatus(): SplitIO.ConsentStatus;
161
- /**
162
- * Consent status constants. Use this to compare with the getStatus function result.
163
- */
164
- Status: {
165
- [status in SplitIO.ConsentStatus]: SplitIO.ConsentStatus
166
- }
167
- }
168
- /**
169
- * Common settings between Browser and NodeJS settings interface.
170
- * @interface ISharedSettings
171
- */
172
- interface ISharedSettings {
173
- /**
174
- * Boolean value to indicate whether the logger should be enabled or disabled, or a log level string.
175
- *
176
- * Examples:
177
- * ```javascript
178
- * config.debug = true
179
- * config.debug = 'WARN'
180
- * ```
181
- * @property {boolean | LogLevel} debug
182
- * @default false
183
- */
184
- debug?: boolean | LogLevel,
185
- /**
186
- * The impression listener, which is optional. Whatever you provide here needs to comply with the SplitIO.IImpressionListener interface,
187
- * which will check for the logImpression method.
188
- * @property {IImpressionListener} impressionListener
189
- * @default undefined
190
- */
191
- impressionListener?: SplitIO.IImpressionListener,
192
- /**
193
- * Boolean flag to enable the streaming service as default synchronization mechanism. In the event of any issue with streaming,
194
- * the SDK would fallback to the polling mechanism. If false, the SDK would poll for changes as usual without attempting to use streaming.
195
- * @property {boolean} streamingEnabled
196
- * @default true
197
- */
198
- streamingEnabled?: boolean,
199
- /**
200
- * SDK synchronization settings.
201
- * @property {Object} sync
202
- */
203
- sync?: {
204
- /**
205
- * List of feature flag filters. These filters are used to fetch a subset of the feature flag definitions in your environment, in order to reduce the delay of the SDK to be ready.
206
- * This configuration is only meaningful when the SDK is working in "standalone" mode.
207
- *
208
- * Example:
209
- * `splitFilter: [
210
- * { type: 'byName', values: ['my_feature_flag_1', 'my_feature_flag_2'] }, // will fetch feature flags named 'my_feature_flag_1' and 'my_feature_flag_2'
211
- * ]`
212
- * @property {SplitIO.SplitFilter[]} splitFilters
213
- */
214
- splitFilters?: SplitIO.SplitFilter[]
215
- /**
216
- * Impressions Collection Mode. Option to determine how impressions are going to be sent to Split servers.
217
- * Possible values are 'DEBUG', 'OPTIMIZED', and 'NONE'.
218
- * - DEBUG: will send all the impressions generated (recommended only for debugging purposes).
219
- * - OPTIMIZED: will send unique impressions to Split servers, avoiding a considerable amount of traffic that duplicated impressions could generate.
220
- * - NONE: will send unique keys evaluated per feature to Split servers instead of full blown impressions, avoiding a considerable amount of traffic that impressions could generate.
221
- *
222
- * @property {string} impressionsMode
223
- * @default 'OPTIMIZED'
224
- */
225
- impressionsMode?: SplitIO.ImpressionsMode,
226
- /**
227
- * Controls the SDK continuous synchronization flags.
228
- *
229
- * When `true` a running SDK will process rollout plan updates performed on the UI (default).
230
- * When false it'll just fetch all data upon init
231
- *
232
- * @property {boolean} enabled
233
- * @default true
234
- */
235
- enabled?: boolean
236
- }
237
- }
238
- /**
239
- * Common settings interface for SDK instances on NodeJS.
240
- * @interface INodeBasicSettings
241
- * @extends ISharedSettings
242
- */
243
- interface INodeBasicSettings extends ISharedSettings {
244
- /**
245
- * SDK Startup settings for NodeJS.
246
- * @property {Object} startup
247
- */
248
- startup?: {
249
- /**
250
- * Maximum amount of time used before notify a timeout.
251
- * @property {number} readyTimeout
252
- * @default 15
253
- */
254
- readyTimeout?: number,
255
- /**
256
- * Time to wait for a request before the SDK is ready. If this time expires, JS Sdk will retry 'retriesOnFailureBeforeReady' times before notifying its failure to be 'ready'.
257
- * @property {number} requestTimeoutBeforeReady
258
- * @default 15
259
- */
260
- requestTimeoutBeforeReady?: number,
261
- /**
262
- * How many quick retries we will do while starting up the SDK.
263
- * @property {number} retriesOnFailureBeforeReady
264
- * @default 1
265
- */
266
- retriesOnFailureBeforeReady?: number,
267
- /**
268
- * For SDK posts the queued events data in bulks with a given rate, but the first push window is defined separately,
269
- * to better control on browsers. This number defines that window before the first events push.
270
- *
271
- * @property {number} eventsFirstPushWindow
272
- * @default 0
273
- */
274
- eventsFirstPushWindow?: number,
275
- },
276
- /**
277
- * SDK scheduler settings.
278
- * @property {Object} scheduler
279
- */
280
- scheduler?: {
281
- /**
282
- * The SDK polls Split servers for changes to feature flag definitions. This parameter controls this polling period in seconds.
283
- * @property {number} featuresRefreshRate
284
- * @default 60
285
- */
286
- featuresRefreshRate?: number,
287
- /**
288
- * The SDK sends information on who got what treatment at what time back to Split servers to power analytics. This parameter controls how often this data is sent to Split servers. The parameter should be in seconds.
289
- * @property {number} impressionsRefreshRate
290
- * @default 300
291
- */
292
- impressionsRefreshRate?: number,
293
- /**
294
- * The maximum number of impression items we want to queue. If we queue more values, it will trigger a flush and reset the timer.
295
- * If you use a 0 here, the queue will have no maximum size.
296
- * @property {number} impressionsQueueSize
297
- * @default 30000
298
- */
299
- impressionsQueueSize?: number,
300
- /**
301
- * The SDK sends diagnostic metrics to Split servers. This parameters controls this metric flush period in seconds.
302
- * @property {number} metricsRefreshRate
303
- * @default 120
304
- * @deprecated This parameter is ignored now. Use `telemetryRefreshRate` instead.
305
- */
306
- metricsRefreshRate?: number,
307
- /**
308
- * The SDK sends diagnostic metrics to Split servers. This parameters controls this metric flush period in seconds.
309
- * @property {number} telemetryRefreshRate
310
- * @default 3600
311
- */
312
- telemetryRefreshRate?: number,
313
- /**
314
- * The SDK polls Split servers for changes to segment definitions. This parameter controls this polling period in seconds.
315
- * @property {number} segmentsRefreshRate
316
- * @default 60
317
- */
318
- segmentsRefreshRate?: number,
319
- /**
320
- * The SDK posts the queued events data in bulks. This parameter controls the posting rate in seconds.
321
- * @property {number} eventsPushRate
322
- * @default 60
323
- */
324
- eventsPushRate?: number,
325
- /**
326
- * The maximum number of event items we want to queue. If we queue more values, it will trigger a flush and reset the timer.
327
- * If you use a 0 here, the queue will have no maximum size.
328
- * @property {number} eventsQueueSize
329
- * @default 500
330
- */
331
- eventsQueueSize?: number,
332
- /**
333
- * For mocking/testing only. The SDK will refresh the features mocked data when mode is set to "localhost" by defining the key.
334
- * For more information see {@link https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK#localhost-mode}
335
- * @property {number} offlineRefreshRate
336
- * @default 15
337
- */
338
- offlineRefreshRate?: number
339
- /**
340
- * When using streaming mode, seconds to wait before re attempting to connect for push notifications.
341
- * Next attempts follow intervals in power of two: base seconds, base x 2 seconds, base x 4 seconds, ...
342
- * @property {number} pushRetryBackoffBase
343
- * @default 1
344
- */
345
- pushRetryBackoffBase?: number,
346
- },
347
- /**
348
- * SDK Core settings for NodeJS.
349
- * @property {Object} core
350
- */
351
- core: {
352
- /**
353
- * Your SDK key.
354
- * @see {@link https://help.split.io/hc/en-us/articles/360019916211-API-keys}
355
- * @property {string} authorizationKey
356
- */
357
- authorizationKey: string,
358
- /**
359
- * Disable labels from being sent to Split backend. Labels may contain sensitive information.
360
- * @property {boolean} labelsEnabled
361
- * @default true
362
- */
363
- labelsEnabled?: boolean
364
- /**
365
- * Disable machine IP and Name from being sent to Split backend.
366
- * @property {boolean} IPAddressesEnabled
367
- * @default true
368
- */
369
- IPAddressesEnabled?: boolean
370
- },
371
- /**
372
- * Defines which kind of storage we should instantiate.
373
- * @property {Object} storage
374
- */
375
- storage?: {
376
- /**
377
- * Storage type to be instantiated by the SDK.
378
- * @property {StorageType} type
379
- * @default 'MEMORY'
380
- */
381
- type?: StorageType,
382
- /**
383
- * Options to be passed to the selected storage.
384
- * @property {Object} options
385
- */
386
- options?: Object,
387
- /**
388
- * Optional prefix to prevent any kind of data collision between SDK versions.
389
- * @property {string} prefix
390
- * @default 'SPLITIO'
391
- */
392
- prefix?: string
393
- },
394
- /**
395
- * The SDK mode. Possible values are "standalone", which is the default when using a synchronous storage, like 'MEMORY' and 'LOCALSTORAGE',
396
- * and "consumer", which must be set when using an asynchronous storage, like 'REDIS'. For "localhost" mode, use "localhost" as authorizationKey.
397
- * @property {SDKMode} mode
398
- * @default 'standalone'
399
- */
400
- mode?: SDKMode,
401
- /**
402
- * Mocked features file path. For testing purposes only. For using this you should specify "localhost" as authorizationKey on core settings.
403
- * @see {@link https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK#localhost-mode}
404
- * @property {MockedFeaturesFilePath} features
405
- * @default '$HOME/.split'
406
- */
407
- features?: SplitIO.MockedFeaturesFilePath,
408
- }
409
- /**
410
- * Common API for entities that expose status handlers.
411
- * @typedef IStatusInterface
412
- */
413
- type IStatusInterface<TEventEmitter extends SplitIO.IEventEmitter = SplitIO.EventEmitter> = TEventEmitter & {
414
- /**
415
- * Constant object containing the SDK events for you to use.
416
- * @property {EventConsts} Event
417
- */
418
- Event: EventConsts,
419
- /**
420
- * Returns a promise that resolves once the SDK has finished loading (`SDK_READY` event emitted) or rejected if the SDK has timedout (`SDK_READY_TIMED_OUT` event emitted).
421
- * As it's meant to provide similar flexibility to the event approach, given that the SDK might be eventually ready after a timeout event, the `ready` method will return a resolved promise once the SDK is ready.
422
- *
423
- * Caveats: the method was designed to avoid an unhandled Promise rejection if the rejection case is not handled, so that `onRejected` handler is optional when using promises.
424
- * However, when using async/await syntax, the rejection should be explicitly propagated like in the following example:
425
- * ```
426
- * try {
427
- * await client.ready().catch((e) => { throw e; });
428
- * // SDK is ready
429
- * } catch(e) {
430
- * // SDK has timedout
431
- * }
432
- * ```
433
- *
434
- * @function ready
435
- * @returns {Promise<void>}
436
- */
437
- ready(): Promise<void>
438
- }
439
- /**
440
- * Common definitions between clients for different environments interface.
441
- * @typedef IBasicClient
442
- */
443
- type IBasicClient<TEventEmitter extends SplitIO.IEventEmitter = SplitIO.EventEmitter> = IStatusInterface<TEventEmitter> & {
444
- /**
445
- * Destroys the client instance.
446
- * In 'standalone' mode, this method will flush any pending impressions and events, and stop the synchronization of feature flag definitions with the backend.
447
- * In 'consumer' mode, this method will disconnect the SDK from the Redis or Pluggable storage.
448
- *
449
- * @function destroy
450
- * @returns {Promise<void>} A promise that resolves once the client is destroyed.
451
- */
452
- destroy(): Promise<void>
453
- }
454
- /**
455
- * Common definitions between SDK instances for different environments interface.
456
- * @interface IBasicSDK
457
- */
458
- interface IBasicSDK {
459
- /**
460
- * Current settings of the SDK instance.
461
- * @property settings
462
- */
463
- settings: ISettings,
464
- /**
465
- * Logger API.
466
- * @property Logger
467
- */
468
- Logger: ILoggerAPI
469
- /**
470
- * Destroys all the clients created by this factory.
471
- * @function destroy
472
- * @returns {Promise<void>}
473
- */
474
- destroy(): Promise<void>
475
- }
476
- /****** Exposed namespace ******/
477
- /**
478
- * Types and interfaces for `@splitsoftware/splitio` package for usage when integrating JavaScript SDK with TypeScript.
479
- * For the SDK package information see {@link https://www.npmjs.com/package/@splitsoftware/splitio}
480
- */
481
- declare namespace SplitIO {
482
- /**
483
- * EventEmitter interface based on a subset of the NodeJS.EventEmitter methods. Used by the JavaScript Browser SDK and React Native SDK.
484
- */
485
- interface IEventEmitter {
486
- addListener(event: string, listener: (...args: any[]) => void): this
487
- on(event: string, listener: (...args: any[]) => void): this
488
- once(event: string, listener: (...args: any[]) => void): this
489
- removeListener(event: string, listener: (...args: any[]) => void): this
490
- off(event: string, listener: (...args: any[]) => void): this
491
- removeAllListeners(event?: string): this
492
- emit(event: string, ...args: any[]): boolean
493
- }
494
-
495
- /**
496
- * NodeJS.EventEmitter interface. Used by the JavaScript SDK for both flavours: server-side (NodeJS) and client-side (Browser).
497
- *
498
- * @see {@link https://nodejs.org/api/events.html}
499
- */
500
- interface EventEmitter extends IEventEmitter {
501
- addListener(event: string | symbol, listener: (...args: any[]) => void): this;
502
- on(event: string | symbol, listener: (...args: any[]) => void): this;
503
- once(event: string | symbol, listener: (...args: any[]) => void): this;
504
- removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
505
- off(event: string | symbol, listener: (...args: any[]) => void): this;
506
- removeAllListeners(event?: string | symbol): this;
507
- emit(event: string | symbol, ...args: any[]): boolean;
508
- setMaxListeners(n: number): this;
509
- getMaxListeners(): number;
510
- listeners(event: string | symbol): Function[];
511
- rawListeners(event: string | symbol): Function[];
512
- listenerCount(type: string | symbol): number;
513
- // Added in Node 6...
514
- prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
515
- prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
516
- eventNames(): Array<string | symbol>;
517
- }
518
- /**
519
- * Feature flag treatment value, returned by getTreatment.
520
- * @typedef {string} Treatment
521
- */
522
- type Treatment = string;
523
- /**
524
- * Feature flag treatment promise that resolves to actual treatment value.
525
- * @typedef {Promise<string>} AsyncTreatment
526
- */
527
- type AsyncTreatment = Promise<string>;
528
- /**
529
- * An object with the treatments for a bulk of feature flags, returned by getTreatments. For example:
530
- * {
531
- * feature1: 'on',
532
- * feature2: 'off
533
- * }
534
- * @typedef {Object.<Treatment>} Treatments
535
- */
536
- type Treatments = {
537
- [featureName: string]: Treatment
538
- };
539
- /**
540
- * Feature flag treatments promise that resolves to the actual SplitIO.Treatments object.
541
- * @typedef {Promise<Treatments>} AsyncTreatments
542
- */
543
- type AsyncTreatments = Promise<Treatments>;
544
- /**
545
- * Feature flag evaluation result with treatment and configuration, returned by getTreatmentWithConfig.
546
- * @typedef {Object} TreatmentWithConfig
547
- * @property {string} treatment The treatment string
548
- * @property {string | null} config The stringified version of the JSON config defined for that treatment, null if there is no config for the resulting treatment.
549
- */
550
- type TreatmentWithConfig = {
551
- treatment: string,
552
- config: string | null
553
- };
554
- /**
555
- * Feature flag treatment promise that resolves to actual treatment with config value.
556
- * @typedef {Promise<TreatmentWithConfig>} AsyncTreatmentWithConfig
557
- */
558
- type AsyncTreatmentWithConfig = Promise<TreatmentWithConfig>;
559
- /**
560
- * An object with the treatments with configs for a bulk of feature flags, returned by getTreatmentsWithConfig.
561
- * Each existing configuration is a stringified version of the JSON you defined on the Split user interface. For example:
562
- * {
563
- * feature1: { treatment: 'on', config: null }
564
- * feature2: { treatment: 'off', config: '{"bannerText":"Click here."}' }
565
- * }
566
- * @typedef {Object.<TreatmentWithConfig>} Treatments
567
- */
568
- type TreatmentsWithConfig = {
569
- [featureName: string]: TreatmentWithConfig
570
- };
571
- /**
572
- * Feature flag treatments promise that resolves to the actual SplitIO.TreatmentsWithConfig object.
573
- * @typedef {Promise<TreatmentsWithConfig>} AsyncTreatmentsWithConfig
574
- */
575
- type AsyncTreatmentsWithConfig = Promise<TreatmentsWithConfig>;
576
- /**
577
- * Possible Split SDK events.
578
- * @typedef {string} Event
579
- */
580
- type Event = 'init::timeout' | 'init::ready' | 'init::cache-ready' | 'state::update';
581
- /**
582
- * Attributes should be on object with values of type string, boolean, number (dates should be sent as millis since epoch) or array of strings or numbers.
583
- * @typedef {Object.<AttributeType>} Attributes
584
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#attribute-syntax}
585
- */
586
- type Attributes = {
587
- [attributeName: string]: AttributeType
588
- };
589
- /**
590
- * Type of an attribute value
591
- * @typedef {string | number | boolean | Array<string | number>} AttributeType
592
- */
593
- type AttributeType = string | number | boolean | Array<string | number>;
594
- /**
595
- * Properties should be an object with values of type string, number, boolean or null. Size limit of ~31kb.
596
- * @typedef {Object.<number, string, boolean, null>} Properties
597
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#track
598
- */
599
- type Properties = {
600
- [propertyName: string]: string | number | boolean | null
601
- };
602
- /**
603
- * The SplitKey object format.
604
- * @typedef {Object.<string>} SplitKeyObject
605
- */
606
- type SplitKeyObject = {
607
- matchingKey: string,
608
- bucketingKey: string
609
- };
610
- /**
611
- * The customer identifier. Could be a SplitKeyObject or a string.
612
- * @typedef {SplitKeyObject|string} SplitKey
613
- */
614
- type SplitKey = SplitKeyObject | string;
615
- /**
616
- * Path to file with mocked features (for node).
617
- * @typedef {string} MockedFeaturesFilePath
618
- */
619
- type MockedFeaturesFilePath = string;
620
- /**
621
- * Object with mocked features mapping (for browser). We need to specify the featureName as key, and the mocked treatment as value.
622
- * @typedef {Object} MockedFeaturesMap
623
- */
624
- type MockedFeaturesMap = {
625
- [featureName: string]: string | TreatmentWithConfig
626
- };
627
- /**
628
- * Object with information about an impression. It contains the generated impression DTO as well as
629
- * complementary information around where and how it was generated in that way.
630
- * @typedef {Object} ImpressionData
631
- */
632
- type ImpressionData = {
633
- impression: {
634
- feature: string,
635
- keyName: string,
636
- treatment: string,
637
- time: number,
638
- bucketingKey?: string,
639
- label: string,
640
- changeNumber: number,
641
- pt?: number,
642
- },
643
- attributes?: SplitIO.Attributes,
644
- ip: string,
645
- hostname: string,
646
- sdkLanguageVersion: string
647
- };
648
- /**
649
- * Data corresponding to one feature flag view.
650
- * @typedef {Object} SplitView
651
- */
652
- type SplitView = {
653
- /**
654
- * The name of the feature flag.
655
- * @property {string} name
656
- */
657
- name: string,
658
- /**
659
- * The traffic type of the feature flag.
660
- * @property {string} trafficType
661
- */
662
- trafficType: string,
663
- /**
664
- * Whether the feature flag is killed or not.
665
- * @property {boolean} killed
666
- */
667
- killed: boolean,
668
- /**
669
- * The list of treatments available for the feature flag.
670
- * @property {Array<string>} treatments
671
- */
672
- treatments: Array<string>,
673
- /**
674
- * Current change number of the feature flag.
675
- * @property {number} changeNumber
676
- */
677
- changeNumber: number,
678
- /**
679
- * Map of configurations per treatment.
680
- * Each existing configuration is a stringified version of the JSON you defined on the Split user interface.
681
- * @property {Object.<string>} configs
682
- */
683
- configs: {
684
- [treatmentName: string]: string
685
- },
686
- /**
687
- * List of sets of the feature flag.
688
- * @property {string[]} sets
689
- */
690
- sets: string[],
691
- /**
692
- * The default treatment of the feature flag.
693
- * @property {string} defaultTreatment
694
- */
695
- defaultTreatment: string,
696
- };
697
- /**
698
- * A promise that resolves to a feature flag view.
699
- * @typedef {Promise<SplitView>} SplitView
700
- */
701
- type SplitViewAsync = Promise<SplitView>;
702
- /**
703
- * An array containing the SplitIO.SplitView elements.
704
- */
705
- type SplitViews = Array<SplitView>;
706
- /**
707
- * A promise that resolves to an SplitIO.SplitViews array.
708
- * @typedef {Promise<SplitViews>} SplitViewsAsync
709
- */
710
- type SplitViewsAsync = Promise<SplitViews>;
711
- /**
712
- * An array of feature flag names.
713
- * @typedef {Array<string>} SplitNames
714
- */
715
- type SplitNames = Array<string>;
716
- /**
717
- * A promise that resolves to an array of feature flag names.
718
- * @typedef {Promise<SplitNames>} SplitNamesAsync
719
- */
720
- type SplitNamesAsync = Promise<SplitNames>;
721
- /**
722
- * Synchronous storage valid types for NodeJS.
723
- * @typedef {string} NodeSyncStorage
724
- */
725
- type NodeSyncStorage = 'MEMORY';
726
- /**
727
- * Asynchronous storages valid types for NodeJS.
728
- * @typedef {string} NodeAsyncStorage
729
- */
730
- type NodeAsyncStorage = 'REDIS';
731
- /**
732
- * Storage valid types for the browser.
733
- * @typedef {string} BrowserStorage
734
- */
735
- type BrowserStorage = 'MEMORY' | 'LOCALSTORAGE';
736
- /**
737
- * Impression listener interface. This is the interface that needs to be implemented
738
- * by the element you provide to the SDK as impression listener.
739
- * @interface IImpressionListener
740
- * @see {@link https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK#listener}
741
- */
742
- interface IImpressionListener {
743
- logImpression(data: SplitIO.ImpressionData): void
744
- }
745
- /**
746
- * Available URL settings for the SDKs.
747
- */
748
- type UrlSettings = {
749
- /**
750
- * String property to override the base URL where the SDK will get rollout plan related data, like feature flags and segments definitions.
751
- * @property {string} sdk
752
- * @default 'https://sdk.split.io/api'
753
- */
754
- sdk?: string,
755
- /**
756
- * String property to override the base URL where the SDK will post event-related information like impressions.
757
- * @property {string} events
758
- * @default 'https://events.split.io/api'
759
- */
760
- events?: string,
761
- /**
762
- * String property to override the base URL where the SDK will get authorization tokens to be used with functionality that requires it, like streaming.
763
- * @property {string} auth
764
- * @default 'https://auth.split.io/api'
765
- */
766
- auth?: string,
767
- /**
768
- * String property to override the base URL where the SDK will connect to receive streaming updates.
769
- * @property {string} streaming
770
- * @default 'https://streaming.split.io'
771
- */
772
- streaming?: string,
773
- /**
774
- * String property to override the base URL where the SDK will post telemetry data.
775
- * @property {string} telemetry
776
- * @default 'https://telemetry.split.io/api'
777
- */
778
- telemetry?: string
779
- };
780
-
781
- /**
782
- * SplitFilter type.
783
- *
784
- * @typedef {string} SplitFilterType
785
- */
786
- type SplitFilterType = 'bySet' | 'byName' | 'byPrefix';
787
- /**
788
- * Defines a feature flag filter, described by a type and list of values.
789
- */
790
- interface SplitFilter {
791
- /**
792
- * Type of the filter.
793
- *
794
- * @property {SplitFilterType} type
795
- */
796
- type: SplitFilterType,
797
- /**
798
- * List of values: feature flag names for 'byName' filter type, and feature flag name prefixes for 'byPrefix' type.
799
- *
800
- * @property {string[]} values
801
- */
802
- values: string[],
803
- }
804
- /**
805
- * ImpressionsMode type
806
- * @typedef {string} ImpressionsMode
807
- */
808
- type ImpressionsMode = 'OPTIMIZED' | 'DEBUG' | 'NONE';
809
- /**
810
- * User consent status.
811
- * @typedef {string} ConsentStatus
812
- */
813
- type ConsentStatus = 'GRANTED' | 'DECLINED' | 'UNKNOWN';
814
- /**
815
- * Defines the format of rollout plan data to preload on the factory storage (cache).
816
- */
817
- type PreloadedData = Object;
818
- /**
819
- * Settings interface for SDK instances created on the browser
820
- * @interface IBrowserSettings
821
- * @extends ISharedSettings
822
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#configuration}
823
- */
824
- interface IBrowserSettings extends ISharedSettings {
825
- /**
826
- * SDK Startup settings for the Browser.
827
- * @property {Object} startup
828
- */
829
- startup?: {
830
- /**
831
- * Maximum amount of time used before notify a timeout.
832
- * @property {number} readyTimeout
833
- * @default 1.5
834
- */
835
- readyTimeout?: number,
836
- /**
837
- * Time to wait for a request before the SDK is ready. If this time expires, JS Sdk will retry 'retriesOnFailureBeforeReady' times before notifying its failure to be 'ready'.
838
- * @property {number} requestTimeoutBeforeReady
839
- * @default 1.5
840
- */
841
- requestTimeoutBeforeReady?: number,
842
- /**
843
- * How many quick retries we will do while starting up the SDK.
844
- * @property {number} retriesOnFailureBeforeReady
845
- * @default 1
846
- */
847
- retriesOnFailureBeforeReady?: number,
848
- /**
849
- * For SDK posts the queued events data in bulks with a given rate, but the first push window is defined separately,
850
- * to better control on browsers. This number defines that window before the first events push.
851
- *
852
- * @property {number} eventsFirstPushWindow
853
- * @default 10
854
- */
855
- eventsFirstPushWindow?: number,
856
- },
857
- /**
858
- * SDK scheduler settings.
859
- * @property {Object} scheduler
860
- */
861
- scheduler?: {
862
- /**
863
- * The SDK polls Split servers for changes to feature flag definitions. This parameter controls this polling period in seconds.
864
- * @property {number} featuresRefreshRate
865
- * @default 60
866
- */
867
- featuresRefreshRate?: number,
868
- /**
869
- * The SDK sends information on who got what treatment at what time back to Split servers to power analytics. This parameter controls how often this data is sent to Split servers. The parameter should be in seconds.
870
- * @property {number} impressionsRefreshRate
871
- * @default 60
872
- */
873
- impressionsRefreshRate?: number,
874
- /**
875
- * The maximum number of impression items we want to queue. If we queue more values, it will trigger a flush and reset the timer.
876
- * If you use a 0 here, the queue will have no maximum size.
877
- * @property {number} impressionsQueueSize
878
- * @default 30000
879
- */
880
- impressionsQueueSize?: number,
881
- /**
882
- * The SDK sends diagnostic metrics to Split servers. This parameters controls this metric flush period in seconds.
883
- * @property {number} metricsRefreshRate
884
- * @default 120
885
- * @deprecated This parameter is ignored now. Use `telemetryRefreshRate` instead.
886
- */
887
- metricsRefreshRate?: number,
888
- /**
889
- * The SDK sends diagnostic metrics to Split servers. This parameters controls this metric flush period in seconds.
890
- * @property {number} telemetryRefreshRate
891
- * @default 3600
892
- */
893
- telemetryRefreshRate?: number,
894
- /**
895
- * The SDK polls Split servers for changes to segment definitions. This parameter controls this polling period in seconds.
896
- * @property {number} segmentsRefreshRate
897
- * @default 60
898
- */
899
- segmentsRefreshRate?: number,
900
- /**
901
- * The SDK posts the queued events data in bulks. This parameter controls the posting rate in seconds.
902
- * @property {number} eventsPushRate
903
- * @default 60
904
- */
905
- eventsPushRate?: number,
906
- /**
907
- * The maximum number of event items we want to queue. If we queue more values, it will trigger a flush and reset the timer.
908
- * If you use a 0 here, the queue will have no maximum size.
909
- * @property {number} eventsQueueSize
910
- * @default 500
911
- */
912
- eventsQueueSize?: number,
913
- /**
914
- * For mocking/testing only. The SDK will refresh the features mocked data when mode is set to "localhost" by defining the key.
915
- * For more information see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#localhost-mode}
916
- * @property {number} offlineRefreshRate
917
- * @default 15
918
- */
919
- offlineRefreshRate?: number,
920
- /**
921
- * When using streaming mode, seconds to wait before re attempting to connect for push notifications.
922
- * Next attempts follow intervals in power of two: base seconds, base x 2 seconds, base x 4 seconds, ...
923
- * @property {number} pushRetryBackoffBase
924
- * @default 1
925
- */
926
- pushRetryBackoffBase?: number,
927
- },
928
- /**
929
- * SDK Core settings for the browser.
930
- * @property {Object} core
931
- */
932
- core: {
933
- /**
934
- * Your SDK key.
935
- * @see {@link https://help.split.io/hc/en-us/articles/360019916211-API-keys}
936
- * @property {string} authorizationKey
937
- */
938
- authorizationKey: string,
939
- /**
940
- * Customer identifier. Whatever this means to you.
941
- * @see {@link https://help.split.io/hc/en-us/articles/360019916311-Traffic-type}
942
- * @property {SplitKey} key
943
- */
944
- key: SplitKey,
945
- /**
946
- * Disable labels from being sent to Split backend. Labels may contain sensitive information.
947
- * @property {boolean} labelsEnabled
948
- * @default true
949
- */
950
- labelsEnabled?: boolean
951
- },
952
- /**
953
- * Mocked features map. For testing purposes only. For using this you should specify "localhost" as authorizationKey on core settings.
954
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#localhost-mode}
955
- */
956
- features?: MockedFeaturesMap,
957
- /**
958
- * Defines which kind of storage we can instantiate on the browser.
959
- * Possible storage types are 'MEMORY', which is the default, and 'LOCALSTORAGE'.
960
- * @property {Object} storage
961
- */
962
- storage?: {
963
- /**
964
- * Storage type to be instantiated by the SDK.
965
- * @property {BrowserStorage} type
966
- * @default 'MEMORY'
967
- */
968
- type?: BrowserStorage,
969
- /**
970
- * Optional prefix to prevent any kind of data collision between SDK versions.
971
- * @property {string} prefix
972
- * @default 'SPLITIO'
973
- */
974
- prefix?: string
975
- },
976
- /**
977
- * @TODO Add description. Should be inside storage?
978
- */
979
- preloadedData?: SplitIO.PreloadedData,
980
- /**
981
- * List of URLs that the SDK will use as base for it's synchronization functionalities, applicable only when running as standalone.
982
- * Do not change these settings unless you're working an advanced use case, like connecting to the Split proxy.
983
- * @property {Object} urls
984
- */
985
- urls?: UrlSettings,
986
- /**
987
- * User consent status. Possible values are `'GRANTED'`, which is the default, `'DECLINED'` or `'UNKNOWN'`.
988
- * - `'GRANTED'`: the user grants consent for tracking events and impressions. The SDK sends them to Split cloud.
989
- * - `'DECLINED'`: the user declines consent for tracking events and impressions. The SDK does not send them to Split cloud.
990
- * - `'UNKNOWN'`: the user neither grants nor declines consent for tracking events and impressions. The SDK tracks them in its internal storage, and eventually either sends
991
- * them or not if the consent status is updated to 'GRANTED' or 'DECLINED' respectively. The status can be updated at any time with the `UserConsent.setStatus` factory method.
992
- *
993
- * @typedef {string} userConsent
994
- * @default 'GRANTED'
995
- */
996
- userConsent?: ConsentStatus,
997
- sync?: ISharedSettings['sync'] & {
998
- /**
999
- * Custom options object for HTTP(S) requests in the Browser.
1000
- * If provided, this object is merged with the options object passed by the SDK for EventSource and Fetch calls.
1001
- */
1002
- requestOptions?: {
1003
- /**
1004
- * Custom function called before each request, allowing you to add or update headers in SDK HTTP requests.
1005
- * Some headers, such as `SplitSDKVersion`, are required by the SDK and cannot be overridden.
1006
- * To pass multiple headers with the same name, combine their values into a single line, separated by commas. Example: `{ 'Authorization': 'value1, value2' }`
1007
- * Or provide keys with different case since headers are case-insensitive. Example: `{ 'authorization': 'value1', 'Authorization': 'value2' }`
1008
- *
1009
- * NOTE: to pass custom headers to the streaming connection in Browser, you should polyfill the `window.EventSource` object with a library that supports headers,
1010
- * like https://www.npmjs.com/package/event-source-polyfill, since native EventSource does not support them and will be ignored.
1011
- *
1012
- * @property getHeaderOverrides
1013
- * @default undefined
1014
- *
1015
- * @param context - The context for the request.
1016
- * @param context.headers - The current headers in the request.
1017
- * @returns A set of headers to be merged with the current headers.
1018
- *
1019
- * @example
1020
- * const getHeaderOverrides = (context) => {
1021
- * return {
1022
- * 'Authorization': context.headers['Authorization'] + ', other-value',
1023
- * 'custom-header': 'custom-value'
1024
- * };
1025
- * };
1026
- */
1027
- getHeaderOverrides?: (context: { headers: Record<string, string> }) => Record<string, string>
1028
- },
1029
- }
1030
- }
1031
- /**
1032
- * Settings interface for SDK instances created on NodeJS.
1033
- * If your storage is asynchronous (Redis for example) use SplitIO.INodeAsyncSettings instead.
1034
- * @interface INodeSettings
1035
- * @extends INodeBasicSettings
1036
- * @see {@link https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK#configuration}
1037
- */
1038
- interface INodeSettings extends INodeBasicSettings {
1039
- /**
1040
- * List of URLs that the SDK will use as base for it's synchronization functionalities, applicable only when running as standalone.
1041
- * Do not change these settings unless you're working an advanced use case, like connecting to the Split proxy.
1042
- * @property {Object} urls
1043
- */
1044
- urls?: UrlSettings,
1045
- /**
1046
- * Defines which kind of storage we can instantiate on NodeJS for 'standalone' mode.
1047
- * The only possible storage type is 'MEMORY', which is the default.
1048
- * @property {Object} storage
1049
- */
1050
- storage?: {
1051
- /**
1052
- * Synchronous storage type to be instantiated by the SDK.
1053
- * @property {NodeSyncStorage} type
1054
- * @default 'MEMORY'
1055
- */
1056
- type?: NodeSyncStorage,
1057
- /**
1058
- * Optional prefix to prevent any kind of data collision between SDK versions.
1059
- * @property {string} prefix
1060
- * @default 'SPLITIO'
1061
- */
1062
- prefix?: string
1063
- },
1064
- /**
1065
- * The SDK mode. When using the default 'MEMORY' storage, the only possible value is "standalone", which is the default.
1066
- * For "localhost" mode, use "localhost" as authorizationKey.
1067
- *
1068
- * @property {'standalone'} mode
1069
- * @default 'standalone'
1070
- */
1071
- mode?: 'standalone'
1072
- sync?: INodeBasicSettings['sync'] & {
1073
- /**
1074
- * Custom options object for HTTP(S) requests in NodeJS.
1075
- * If provided, this object is merged with the options object passed by the SDK for EventSource and Node-Fetch calls.
1076
- * @see {@link https://www.npmjs.com/package/node-fetch#options}
1077
- */
1078
- requestOptions?: {
1079
- /**
1080
- * Custom function called before each request, allowing you to add or update headers in SDK HTTP requests.
1081
- * Some headers, such as `SplitSDKVersion`, are required by the SDK and cannot be overridden.
1082
- * To pass multiple headers with the same name, combine their values into a single line, separated by commas. Example: `{ 'Authorization': 'value1, value2' }`
1083
- * Or provide keys with different case since headers are case-insensitive. Example: `{ 'authorization': 'value1', 'Authorization': 'value2' }`
1084
- *
1085
- * @property getHeaderOverrides
1086
- * @default undefined
1087
- *
1088
- * @param context - The context for the request.
1089
- * @param context.headers - The current headers in the request.
1090
- * @returns A set of headers to be merged with the current headers.
1091
- *
1092
- * @example
1093
- * const getHeaderOverrides = (context) => {
1094
- * return {
1095
- * 'Authorization': context.headers['Authorization'] + ', other-value',
1096
- * 'custom-header': 'custom-value'
1097
- * };
1098
- * };
1099
- */
1100
- getHeaderOverrides?: (context: { headers: Record<string, string> }) => Record<string, string>
1101
- /**
1102
- * Custom NodeJS HTTP(S) Agent used by the SDK for HTTP(S) requests.
1103
- *
1104
- * You can use it, for example, for certificate pinning or setting a network proxy:
1105
- *
1106
- * ```javascript
1107
- * const { HttpsProxyAgent } = require('https-proxy-agent');
1108
- *
1109
- * const proxyAgent = new HttpsProxyAgent(process.env.HTTPS_PROXY || 'http://10.10.1.10:1080');
1110
- *
1111
- * const factory = SplitFactory({
1112
- * ...
1113
- * sync: {
1114
- * requestOptions: {
1115
- * agent: proxyAgent
1116
- * }
1117
- * }
1118
- * })
1119
- * ```
1120
- *
1121
- * @see {@link https://nodejs.org/api/https.html#class-httpsagent}
1122
- *
1123
- * @property {http.Agent | https.Agent} agent
1124
- * @default undefined
1125
- */
1126
- agent?: RequestOptions["agent"]
1127
- },
1128
- }
1129
- }
1130
- /**
1131
- * Settings interface with async storage for SDK instances created on NodeJS.
1132
- * If your storage is synchronous (by defaut we use memory, which is sync) use SplitIO.INodeSettings instead.
1133
- * @interface INodeAsyncSettings
1134
- * @extends INodeBasicSettings
1135
- * @see {@link https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK#configuration}
1136
- */
1137
- interface INodeAsyncSettings extends INodeBasicSettings {
1138
- /**
1139
- * Defines which kind of async storage we can instantiate on NodeJS for 'consumer' mode.
1140
- * The only possible storage type is 'REDIS'.
1141
- * @property {Object} storage
1142
- */
1143
- storage: {
1144
- /**
1145
- * 'REDIS' storage type to be instantiated by the SDK.
1146
- * @property {NodeAsyncStorage} type
1147
- */
1148
- type: NodeAsyncStorage,
1149
- /**
1150
- * Options to be passed to the Redis storage. Use it with storage type: 'REDIS'.
1151
- * @property {Object} options
1152
- */
1153
- options?: {
1154
- /**
1155
- * Redis URL. If set, `host`, `port`, `db` and `pass` params will be ignored.
1156
- *
1157
- * Examples:
1158
- * ```
1159
- * url: 'localhost'
1160
- * url: '127.0.0.1:6379'
1161
- * url: 'redis://:authpassword@127.0.0.1:6379/0'
1162
- * ```
1163
- * @property {string=} url
1164
- */
1165
- url?: string,
1166
- /**
1167
- * Redis host.
1168
- * @property {string=} host
1169
- * @default 'localhost'
1170
- */
1171
- host?: string,
1172
- /**
1173
- * Redis port.
1174
- * @property {number=} port
1175
- * @default 6379
1176
- */
1177
- port?: number,
1178
- /**
1179
- * Redis database to be used.
1180
- * @property {number=} db
1181
- * @default 0
1182
- */
1183
- db?: number,
1184
- /**
1185
- * Redis password. Don't define if no password is used.
1186
- * @property {string=} pass
1187
- * @default undefined
1188
- */
1189
- pass?: string,
1190
- /**
1191
- * The milliseconds before a timeout occurs during the initial connection to the Redis server.
1192
- * @property {number=} connectionTimeout
1193
- * @default 10000
1194
- */
1195
- connectionTimeout?: number,
1196
- /**
1197
- * The milliseconds before Redis commands are timeout by the SDK.
1198
- * Method calls that involve Redis commands, like `client.getTreatment` or `client.track` calls, are resolved when the commands success or timeout.
1199
- * @property {number=} operationTimeout
1200
- * @default 5000
1201
- */
1202
- operationTimeout?: number,
1203
- /**
1204
- * TLS configuration for Redis connection.
1205
- * @see {@link https://www.npmjs.com/package/ioredis#tls-options }
1206
- *
1207
- * @property {Object=} tls
1208
- * @default undefined
1209
- */
1210
- tls?: RedisOptions['tls'],
1211
- },
1212
- /**
1213
- * Optional prefix to prevent any kind of data collision between SDK versions.
1214
- * @property {string} prefix
1215
- * @default 'SPLITIO'
1216
- */
1217
- prefix?: string
1218
- },
1219
- /**
1220
- * The SDK mode. When using 'REDIS' storage type, the only possible value is "consumer", which is required.
1221
- *
1222
- * @see {@link https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK#state-sharing-redis-integration}
1223
- *
1224
- * @property {'consumer'} mode
1225
- */
1226
- mode: 'consumer'
1227
- }
1228
- /**
1229
- * This represents the interface for the SDK instance with synchronous storage.
1230
- * @interface ISDK
1231
- * @extends IBasicSDK
1232
- */
1233
- interface ISDK extends IBasicSDK {
1234
- /**
1235
- * Returns the default client instance of the SDK.
1236
- * @function client
1237
- * @returns {IClient} The client instance.
1238
- */
1239
- client(): IClient,
1240
- /**
1241
- * Returns a manager instance of the SDK to explore available information.
1242
- * @function manager
1243
- * @returns {IManager} The manager instance.
1244
- */
1245
- manager(): IManager,
1246
- /**
1247
- * @TODO add description
1248
- */
1249
- getState(keys?: SplitKey[]): PreloadedData,
1250
- }
1251
- /**
1252
- * This represents the interface for the SDK instance with synchronous storage and client-side API.
1253
- * @interface IBrowserSDK
1254
- * @extends IBasicSDK
1255
- */
1256
- interface IBrowserSDK<TEventEmitter extends IEventEmitter = EventEmitter> extends IBasicSDK {
1257
- /**
1258
- * Returns the default client instance of the SDK.
1259
- * @function client
1260
- * @returns {IBrowserClient} The client instance.
1261
- */
1262
- client(): IBrowserClient<TEventEmitter>,
1263
- /**
1264
- * Returns a shared client of the SDK.
1265
- * @function client
1266
- * @param {SplitKey} key The key for the new client instance.
1267
- * @returns {IBrowserClient} The client instance.
1268
- */
1269
- client(key: SplitKey): IBrowserClient<TEventEmitter>
1270
- /**
1271
- * Returns a manager instance of the SDK to explore available information.
1272
- * @function manager
1273
- * @returns {IManager} The manager instance.
1274
- */
1275
- manager(): IManager<TEventEmitter>,
1276
- /**
1277
- * User consent API.
1278
- * @property UserConsent
1279
- */
1280
- UserConsent: IUserConsentAPI
1281
- }
1282
- /**
1283
- * This represents the interface for the SDK instance with asynchronous storage.
1284
- * @interface IAsyncSDK
1285
- * @extends IBasicSDK
1286
- */
1287
- interface IAsyncSDK extends IBasicSDK {
1288
- /**
1289
- * Returns the default client instance of the SDK.
1290
- * @function client
1291
- * @returns {IAsyncClient} The asynchronous client instance.
1292
- */
1293
- client(): IAsyncClient,
1294
- /**
1295
- * Returns a manager instance of the SDK to explore available information.
1296
- * @function manager
1297
- * @returns {IManager} The manager instance.
1298
- */
1299
- manager(): IAsyncManager
1300
- }
1301
- /**
1302
- * This represents the interface for the Client instance on server-side, where the user key is not bound to the instance and must be provided on each method call.
1303
- * This interface is available in NodeJS, or when importing the 'server' sub-package (e.g., `import { SplitFactory } from '@splitsoftware/splitio/server'`).
1304
- *
1305
- * @interface IClient
1306
- * @extends IBasicClient
1307
- */
1308
- interface IClient extends IBasicClient {
1309
- /**
1310
- * Returns a Treatment value, which is the treatment string for the given feature.
1311
- *
1312
- * @function getTreatment
1313
- * @param {string} key - The string key representing the consumer.
1314
- * @param {string} featureFlagName - The string that represents the feature flag we want to get the treatment.
1315
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1316
- * @returns {Treatment} The treatment string.
1317
- */
1318
- getTreatment(key: SplitKey, featureFlagName: string, attributes?: Attributes): Treatment,
1319
- /**
1320
- * Returns a TreatmentWithConfig value, which is an object with both treatment and config string for the given feature.
1321
- *
1322
- * @function getTreatmentWithConfig
1323
- * @param {string} key - The string key representing the consumer.
1324
- * @param {string} featureFlagName - The string that represents the feature flag we want to get the treatment.
1325
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1326
- * @returns {TreatmentWithConfig} The TreatmentWithConfig, the object containing the treatment string and the
1327
- * configuration stringified JSON (or null if there was no config for that treatment).
1328
- */
1329
- getTreatmentWithConfig(key: SplitKey, featureFlagName: string, attributes?: Attributes): TreatmentWithConfig,
1330
- /**
1331
- * Returns a Treatments value, which is an object map with the treatments for the given features.
1332
- *
1333
- * @function getTreatments
1334
- * @param {string} key - The string key representing the consumer.
1335
- * @param {Array<string>} featureFlagNames - An array of the feature flag names we want to get the treatments.
1336
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1337
- * @returns {Treatments} The treatments object map.
1338
- */
1339
- getTreatments(key: SplitKey, featureFlagNames: string[], attributes?: Attributes): Treatments,
1340
- /**
1341
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the given features.
1342
- *
1343
- * @function getTreatmentsWithConfig
1344
- * @param {string} key - The string key representing the consumer.
1345
- * @param {Array<string>} featureFlagNames - An array of the feature flag names we want to get the treatments.
1346
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1347
- * @returns {TreatmentsWithConfig} The map with all the TreatmentWithConfig objects
1348
- */
1349
- getTreatmentsWithConfig(key: SplitKey, featureFlagNames: string[], attributes?: Attributes): TreatmentsWithConfig,
1350
- /**
1351
- * Returns a Treatments value, which is an object map with the treatments for the feature flags related to the given flag set.
1352
- *
1353
- * @function getTreatmentsByFlagSet
1354
- * @param {string} key - The string key representing the consumer.
1355
- * @param {string} flagSet - The flag set name we want to get the treatments.
1356
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1357
- * @returns {Treatments} The map with all the Treatments objects
1358
- */
1359
- getTreatmentsByFlagSet(key: SplitKey, flagSet: string, attributes?: Attributes): Treatments,
1360
- /**
1361
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the feature flags related to the given flag set.
1362
- *
1363
- * @function getTreatmentsWithConfigByFlagSet
1364
- * @param {string} key - The string key representing the consumer.
1365
- * @param {string} flagSet - The flag set name we want to get the treatments.
1366
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1367
- * @returns {TreatmentsWithConfig} The map with all the TreatmentWithConfig objects
1368
- */
1369
- getTreatmentsWithConfigByFlagSet(key: SplitKey, flagSet: string, attributes?: Attributes): TreatmentsWithConfig,
1370
- /**
1371
- * Returns a Returns a Treatments value, which is an object with both treatment and config string for to the feature flags related to the given flag sets.
1372
- *
1373
- * @function getTreatmentsByFlagSets
1374
- * @param {string} key - The string key representing the consumer.
1375
- * @param {Array<string>} flagSets - An array of the flag set names we want to get the treatments.
1376
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1377
- * @returns {Treatments} The map with all the Treatments objects
1378
- */
1379
- getTreatmentsByFlagSets(key: SplitKey, flagSets: string[], attributes?: Attributes): Treatments,
1380
- /**
1381
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the feature flags related to the given flag sets.
1382
- *
1383
- * @function getTreatmentsWithConfigByFlagSets
1384
- * @param {string} key - The string key representing the consumer.
1385
- * @param {Array<string>} flagSets - An array of the flag set names we want to get the treatments.
1386
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1387
- * @returns {TreatmentsWithConfig} The map with all the TreatmentWithConfig objects
1388
- */
1389
- getTreatmentsWithConfigByFlagSets(key: SplitKey, flagSets: string[], attributes?: Attributes): TreatmentsWithConfig,
1390
- /**
1391
- * Tracks an event to be fed to the results product on Split user interface.
1392
- *
1393
- * @function track
1394
- * @param {SplitKey} key - The key that identifies the entity related to this event.
1395
- * @param {string} trafficType - The traffic type of the entity related to this event. See {@link https://help.split.io/hc/en-us/articles/360019916311-Traffic-type}
1396
- * @param {string} eventType - The event type corresponding to this event.
1397
- * @param {number=} value - The value of this event.
1398
- * @param {Properties=} properties - The properties of this event. Values can be string, number, boolean or null.
1399
- * @returns {boolean} Whether the event was added to the queue successfully or not.
1400
- */
1401
- track(key: SplitIO.SplitKey, trafficType: string, eventType: string, value?: number, properties?: Properties): boolean,
1402
- }
1403
- /**
1404
- * This represents the interface for the Client instance on client-side, where the user key is bound to the instance on creation and does not need to be provided on each method call.
1405
- * This interface is the default when importing the SDK in the Browser, or when importing the 'client' sub-package (e.g., `import { SplitFactory } from '@splitsoftware/splitio/client'`).
1406
- *
1407
- * @typedef IBrowserClient
1408
- */
1409
- type IBrowserClient<TEventEmitter extends IEventEmitter = EventEmitter> = IBasicClient<TEventEmitter> & {
1410
- /**
1411
- * Returns a Treatment value, which is the treatment string for the given feature.
1412
- *
1413
- * @function getTreatment
1414
- * @param {string} featureFlagName - The string that represents the feature flag we want to get the treatment.
1415
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1416
- * @returns {Treatment} The treatment string.
1417
- */
1418
- getTreatment(featureFlagName: string, attributes?: Attributes): Treatment,
1419
- /**
1420
- * Returns a TreatmentWithConfig value, which an object with both treatment and config string for the given feature.
1421
- *
1422
- * @function getTreatmentWithConfig
1423
- * @param {string} featureFlagName - The string that represents the feature flag we want to get the treatment.
1424
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1425
- * @returns {TreatmentWithConfig} The TreatmentWithConfig, the object containing the treatment string and the
1426
- * configuration stringified JSON (or null if there was no config for that treatment).
1427
- */
1428
- getTreatmentWithConfig(featureFlagName: string, attributes?: Attributes): TreatmentWithConfig,
1429
- /**
1430
- * Returns a Treatments value, which is an object map with the treatments for the given features.
1431
- *
1432
- * @function getTreatments
1433
- * @param {Array<string>} featureFlagNames - An array of the feature flags names we want to get the treatments.
1434
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1435
- * @returns {Treatments} The treatments object map.
1436
- */
1437
- getTreatments(featureFlagNames: string[], attributes?: Attributes): Treatments,
1438
- /**
1439
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the given features.
1440
- *
1441
- * @function getTreatmentsWithConfig
1442
- * @param {Array<string>} featureFlagNames - An array of the feature flag names we want to get the treatments.
1443
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1444
- * @returns {TreatmentsWithConfig} The map with all the TreatmentWithConfig objects
1445
- */
1446
- getTreatmentsWithConfig(featureFlagNames: string[], attributes?: Attributes): TreatmentsWithConfig,
1447
- /**
1448
- * Returns a Treatments value, which is an object map with the treatments for the feature flags related to the given flag set.
1449
- *
1450
- * @function getTreatmentsByFlagSet
1451
- * @param {string} flagSet - The flag set name we want to get the treatments.
1452
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1453
- * @returns {Treatments} The map with all the Treatments objects
1454
- */
1455
- getTreatmentsByFlagSet(flagSet: string, attributes?: Attributes): Treatments,
1456
- /**
1457
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the feature flags related to the given flag set.
1458
- *
1459
- * @function getTreatmentsWithConfigByFlagSet
1460
- * @param {string} flagSet - The flag set name we want to get the treatments.
1461
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1462
- * @returns {TreatmentsWithConfig} The map with all the TreatmentWithConfig objects
1463
- */
1464
- getTreatmentsWithConfigByFlagSet(flagSet: string, attributes?: Attributes): TreatmentsWithConfig,
1465
- /**
1466
- * Returns a Returns a Treatments value, which is an object with both treatment and config string for to the feature flags related to the given flag sets.
1467
- *
1468
- * @function getTreatmentsByFlagSets
1469
- * @param {Array<string>} flagSets - An array of the flag set names we want to get the treatments.
1470
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1471
- * @returns {Treatments} The map with all the Treatments objects
1472
- */
1473
- getTreatmentsByFlagSets(flagSets: string[], attributes?: Attributes): Treatments,
1474
- /**
1475
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the feature flags related to the given flag sets.
1476
- *
1477
- * @function getTreatmentsWithConfigByFlagSets
1478
- * @param {Array<string>} flagSets - An array of the flag set names we want to get the treatments.
1479
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1480
- * @returns {TreatmentsWithConfig} The map with all the TreatmentWithConfig objects
1481
- */
1482
- getTreatmentsWithConfigByFlagSets(flagSets: string[], attributes?: Attributes): TreatmentsWithConfig,
1483
- /**
1484
- * Tracks an event to be fed to the results product on Split user interface.
1485
- *
1486
- * @function track
1487
- * @param {string} trafficType - The traffic type of the entity related to this event. See {@link https://help.split.io/hc/en-us/articles/360019916311-Traffic-type}
1488
- * @param {string} eventType - The event type corresponding to this event.
1489
- * @param {number=} value - The value of this event.
1490
- * @param {Properties=} properties - The properties of this event. Values can be string, number, boolean or null.
1491
- * @returns {boolean} Whether the event was added to the queue successfully or not.
1492
- */
1493
- track(trafficType: string, eventType: string, value?: number, properties?: Properties): boolean,
1494
- /**
1495
- * Add an attribute to client's in memory attributes storage.
1496
- *
1497
- * @param {string} attributeName Attribute name
1498
- * @param {AttributeType} attributeValue Attribute value
1499
- * @returns {boolean} true if the attribute was stored and false otherwise
1500
- */
1501
- setAttribute(attributeName: string, attributeValue: AttributeType): boolean,
1502
- /**
1503
- * Returns the attribute with the given name.
1504
- *
1505
- * @param {string} attributeName Attribute name
1506
- * @returns {AttributeType} Attribute with the given name
1507
- */
1508
- getAttribute(attributeName: string): AttributeType,
1509
- /**
1510
- * Removes from client's in memory attributes storage the attribute with the given name.
1511
- *
1512
- * @param {string} attributeName
1513
- * @returns {boolean} true if attribute was removed and false otherwise
1514
- */
1515
- removeAttribute(attributeName: string): boolean,
1516
- /**
1517
- * Add to client's in memory attributes storage the attributes in 'attributes'.
1518
- *
1519
- * @param {Attributes} attributes Object with attributes to store
1520
- * @returns true if attributes were stored an false otherwise
1521
- */
1522
- setAttributes(attributes: Attributes): boolean,
1523
- /**
1524
- * Return all the attributes stored in client's in memory attributes storage.
1525
- *
1526
- * @returns {Attributes} returns all the stored attributes
1527
- */
1528
- getAttributes(): Attributes,
1529
- /**
1530
- * Remove all the stored attributes in the client's in memory attribute storage.
1531
- *
1532
- * @returns {boolean} true if all attribute were removed and false otherwise
1533
- */
1534
- clearAttributes(): boolean
1535
- }
1536
- /**
1537
- * This represents the interface for the Client instance on server-side with asynchronous storage, like REDIS.
1538
- * User key is not bound to the instance and must be provided on each method call, which returns a promise.
1539
- * This interface is available in NodeJS, or when importing the 'server' sub-package (e.g., `import { SplitFactory } from '@splitsoftware/splitio/server'`).
1540
- *
1541
- * @interface IAsyncClient
1542
- * @extends IBasicClient
1543
- */
1544
- interface IAsyncClient extends IBasicClient {
1545
- /**
1546
- * Returns a Treatment value, which will be (or eventually be) the treatment string for the given feature.
1547
- *
1548
- * @function getTreatment
1549
- * @param {string} key - The string key representing the consumer.
1550
- * @param {string} featureFlagName - The string that represents the feature flag we want to get the treatment.
1551
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1552
- * @returns {AsyncTreatment} Treatment promise that resolves to the treatment string.
1553
- */
1554
- getTreatment(key: SplitKey, featureFlagName: string, attributes?: Attributes): AsyncTreatment,
1555
- /**
1556
- * Returns a TreatmentWithConfig value, which will be (or eventually be) an object with both treatment and config string for the given feature.
1557
- *
1558
- * @function getTreatmentWithConfig
1559
- * @param {string} key - The string key representing the consumer.
1560
- * @param {string} featureFlagName - The string that represents the feature flag we want to get the treatment.
1561
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1562
- * @returns {AsyncTreatmentWithConfig} TreatmentWithConfig promise that resolves to the TreatmentWithConfig object.
1563
- */
1564
- getTreatmentWithConfig(key: SplitKey, featureFlagName: string, attributes?: Attributes): AsyncTreatmentWithConfig,
1565
- /**
1566
- * Returns a Treatments value, which will be (or eventually be) an object map with the treatments for the given features.
1567
- *
1568
- * @function getTreatments
1569
- * @param {string} key - The string key representing the consumer.
1570
- * @param {Array<string>} featureFlagNames - An array of the feature flag names we want to get the treatments.
1571
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1572
- * @returns {AsyncTreatments} Treatments promise that resolves to the treatments object map.
1573
- */
1574
- getTreatments(key: SplitKey, featureFlagNames: string[], attributes?: Attributes): AsyncTreatments,
1575
- /**
1576
- * Returns a TreatmentsWithConfig value, which will be (or eventually be) an object map with the TreatmentWithConfig (an object with both treatment and config string) for the given features.
1577
- *
1578
- * @function getTreatmentsWithConfig
1579
- * @param {string} key - The string key representing the consumer.
1580
- * @param {Array<string>} featureFlagNames - An array of the feature flag names we want to get the treatments.
1581
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1582
- * @returns {AsyncTreatmentsWithConfig} TreatmentsWithConfig promise that resolves to the map of TreatmentsWithConfig objects.
1583
- */
1584
- getTreatmentsWithConfig(key: SplitKey, featureFlagNames: string[], attributes?: Attributes): AsyncTreatmentsWithConfig,
1585
- /**
1586
- * Returns a Treatments value, which is an object map with the treatments for the feature flags related to the given flag set.
1587
- *
1588
- * @function getTreatmentsByFlagSet
1589
- * @param {string} key - The string key representing the consumer.
1590
- * @param {string} flagSet - The flag set name we want to get the treatments.
1591
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1592
- * @returns {AsyncTreatments} Treatments promise that resolves to the treatments object map.
1593
- */
1594
- getTreatmentsByFlagSet(key: SplitKey, flagSet: string, attributes?: Attributes): AsyncTreatments,
1595
- /**
1596
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the feature flags related to the given flag set.
1597
- *
1598
- * @function getTreatmentsWithConfigByFlagSet
1599
- * @param {string} flagSet - The flag set name we want to get the treatments.
1600
- * @param {string} key - The string key representing the consumer.
1601
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1602
- * @returns {AsyncTreatmentsWithConfig} TreatmentsWithConfig promise that resolves to the TreatmentsWithConfig object.
1603
- */
1604
- getTreatmentsWithConfigByFlagSet(key: SplitKey, flagSet: string, attributes?: Attributes): AsyncTreatmentsWithConfig,
1605
- /**
1606
- * Returns a Returns a Treatments value, which is an object with both treatment and config string for to the feature flags related to the given flag sets.
1607
- *
1608
- * @function getTreatmentsByFlagSets
1609
- * @param {string} key - The string key representing the consumer.
1610
- * @param {Array<string>} flagSets - An array of the flag set names we want to get the treatments.
1611
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1612
- * @returns {AsyncTreatments} Treatments promise that resolves to the treatments object map.
1613
- */
1614
- getTreatmentsByFlagSets(key: SplitKey, flagSets: string[], attributes?: Attributes): AsyncTreatments,
1615
- /**
1616
- * Returns a TreatmentsWithConfig value, which is an object map with the TreatmentWithConfig (an object with both treatment and config string) for the feature flags related to the given flag sets.
1617
- *
1618
- * @function getTreatmentsWithConfigByFlagSets
1619
- * @param {string} key - The string key representing the consumer.
1620
- * @param {Array<string>} flagSets - An array of the flag set names we want to get the treatments.
1621
- * @param {Attributes=} attributes - An object of type Attributes defining the attributes for the given key.
1622
- * @returns {AsyncTreatmentsWithConfig} TreatmentsWithConfig promise that resolves to the TreatmentsWithConfig object.
1623
- */
1624
- getTreatmentsWithConfigByFlagSets(key: SplitKey, flagSets: string[], attributes?: Attributes): AsyncTreatmentsWithConfig,
1625
- /**
1626
- * Tracks an event to be fed to the results product on Split user interface, and returns a promise to signal when the event was successfully queued (or not).
1627
- *
1628
- * @function track
1629
- * @param {SplitKey} key - The key that identifies the entity related to this event.
1630
- * @param {string} trafficType - The traffic type of the entity related to this event. See {@link https://help.split.io/hc/en-us/articles/360019916311-Traffic-type}
1631
- * @param {string} eventType - The event type corresponding to this event.
1632
- * @param {number=} value - The value of this event.
1633
- * @param {Properties=} properties - The properties of this event. Values can be string, number, boolean or null.
1634
- * @returns {Promise<boolean>} A promise that resolves to a boolean indicating if the event was added to the queue successfully or not.
1635
- */
1636
- track(key: SplitIO.SplitKey, trafficType: string, eventType: string, value?: number, properties?: Properties): Promise<boolean>
1637
- }
1638
- /**
1639
- * Representation of a manager instance with synchronous storage of the SDK.
1640
- * @typedef IManager
1641
- */
1642
- type IManager<TEventEmitter extends IEventEmitter = EventEmitter> = IStatusInterface<TEventEmitter> & {
1643
- /**
1644
- * Get the array of feature flag names.
1645
- * @function names
1646
- * @returns {SplitNames} The list of feature flag names.
1647
- */
1648
- names(): SplitNames;
1649
- /**
1650
- * Get the array of feature flags data in SplitView format.
1651
- * @function splits
1652
- * @returns {SplitViews} The list of SplitIO.SplitView.
1653
- */
1654
- splits(): SplitViews;
1655
- /**
1656
- * Get the data of a feature flag in SplitView format.
1657
- * @function split
1658
- * @param {string} featureFlagName The name of the feature flag we want to get info of.
1659
- * @returns {SplitView | null} The SplitIO.SplitView of the given feature flag name or null if the feature flag is not found.
1660
- */
1661
- split(featureFlagName: string): SplitView | null;
1662
- }
1663
- /**
1664
- * Representation of a manager instance with asynchronous storage of the SDK.
1665
- * @interface IAsyncManager
1666
- * @extends IStatusInterface
1667
- */
1668
- interface IAsyncManager extends IStatusInterface {
1669
- /**
1670
- * Get the array of feature flag names.
1671
- * @function names
1672
- * @returns {SplitNamesAsync} A promise that resolves to the list of feature flag names.
1673
- */
1674
- names(): SplitNamesAsync;
1675
- /**
1676
- * Get the array of feature flags data in SplitView format.
1677
- * @function splits
1678
- * @returns {SplitViewsAsync} A promise that resolves to the SplitIO.SplitView list.
1679
- */
1680
- splits(): SplitViewsAsync;
1681
- /**
1682
- * Get the data of a feature flag in SplitView format.
1683
- * @function split
1684
- * @param {string} featureFlagName The name of the feature flag we want to get info of.
1685
- * @returns {SplitViewAsync} A promise that resolves to the SplitIO.SplitView value.
1686
- */
1687
- split(featureFlagName: string): SplitViewAsync;
1688
- }
1689
- }