@shipeasy/sdk 5.3.0 → 6.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -27
- package/dist/client/index.d.mts +90 -18
- package/dist/client/index.d.ts +90 -18
- package/dist/client/index.js +100 -11
- package/dist/client/index.mjs +96 -10
- package/dist/openfeature-server/index.d.mts +19 -19
- package/dist/openfeature-server/index.d.ts +19 -19
- package/dist/openfeature-web/index.d.mts +12 -12
- package/dist/openfeature-web/index.d.ts +12 -12
- package/dist/server/index.d.mts +134 -45
- package/dist/server/index.d.ts +134 -45
- package/dist/server/index.js +113 -45
- package/dist/server/index.mjs +107 -43
- package/package.json +1 -1
|
@@ -101,8 +101,8 @@ interface AutoCollectGroups {
|
|
|
101
101
|
errors: boolean;
|
|
102
102
|
engagement: boolean;
|
|
103
103
|
}
|
|
104
|
-
type
|
|
105
|
-
interface
|
|
104
|
+
type EngineEnv = "dev" | "staging" | "prod";
|
|
105
|
+
interface EngineOptions {
|
|
106
106
|
sdkKey: string;
|
|
107
107
|
baseUrl?: string;
|
|
108
108
|
autoGuardrails?: boolean;
|
|
@@ -121,7 +121,7 @@ interface FlagsClientBrowserOptions {
|
|
|
121
121
|
*/
|
|
122
122
|
autoCollectAlways?: boolean;
|
|
123
123
|
/** Which published env to read values from. Defaults to "prod". */
|
|
124
|
-
env?:
|
|
124
|
+
env?: EngineEnv;
|
|
125
125
|
/**
|
|
126
126
|
* Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
|
|
127
127
|
* getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
|
|
@@ -158,11 +158,11 @@ interface FlagsClientBrowserOptions {
|
|
|
158
158
|
* Test mode — no network at all. identify()/init are no-ops (never call
|
|
159
159
|
* /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
|
|
160
160
|
* starts "ready" with an empty eval result. Prefer the
|
|
161
|
-
* {@link
|
|
161
|
+
* {@link Engine.forTesting} factory over passing this directly.
|
|
162
162
|
*/
|
|
163
163
|
testMode?: boolean;
|
|
164
164
|
}
|
|
165
|
-
declare class
|
|
165
|
+
declare class Engine {
|
|
166
166
|
private readonly sdkKey;
|
|
167
167
|
private readonly baseUrl;
|
|
168
168
|
private readonly autoGuardrails;
|
|
@@ -187,7 +187,7 @@ declare class FlagsClientBrowser {
|
|
|
187
187
|
private readonly configOverrides;
|
|
188
188
|
private readonly experimentOverrides;
|
|
189
189
|
private onOverrideChange;
|
|
190
|
-
constructor(opts:
|
|
190
|
+
constructor(opts: EngineOptions);
|
|
191
191
|
/**
|
|
192
192
|
* Build a no-network, immediately-usable browser client for tests
|
|
193
193
|
* (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
|
|
@@ -196,12 +196,12 @@ declare class FlagsClientBrowser {
|
|
|
196
196
|
* key required.
|
|
197
197
|
*
|
|
198
198
|
* ```ts
|
|
199
|
-
* const client =
|
|
199
|
+
* const client = Engine.forTesting();
|
|
200
200
|
* client.overrideFlag("new_checkout", true);
|
|
201
201
|
* client.getFlag("new_checkout"); // true
|
|
202
202
|
* ```
|
|
203
203
|
*/
|
|
204
|
-
static forTesting(opts?: Partial<
|
|
204
|
+
static forTesting(opts?: Partial<EngineOptions>): Engine;
|
|
205
205
|
identify(user: User): Promise<void>;
|
|
206
206
|
/**
|
|
207
207
|
* Report a structured error into the errors primitive. Flushes immediately
|
|
@@ -289,10 +289,10 @@ interface ShipeasySdkBridge {
|
|
|
289
289
|
*
|
|
290
290
|
* ```ts
|
|
291
291
|
* import { OpenFeature } from "@openfeature/web-sdk";
|
|
292
|
-
* import {
|
|
292
|
+
* import { Engine } from "@shipeasy/sdk/client";
|
|
293
293
|
* import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-web";
|
|
294
294
|
*
|
|
295
|
-
* const client = new
|
|
295
|
+
* const client = new Engine({ sdkKey: NEXT_PUBLIC_SHIPEASY_CLIENT_KEY });
|
|
296
296
|
* await OpenFeature.setContext({ targetingKey: "u1", plan: "pro" });
|
|
297
297
|
* await OpenFeature.setProviderAndWait(new ShipeasyProvider(client));
|
|
298
298
|
*
|
|
@@ -307,7 +307,7 @@ interface ShipeasySdkBridge {
|
|
|
307
307
|
|
|
308
308
|
/**
|
|
309
309
|
* Shipeasy OpenFeature provider (client/web paradigm). Wraps a
|
|
310
|
-
* `
|
|
310
|
+
* `Engine`. Context changes are reconciled through `identify()`;
|
|
311
311
|
* flag reads come from the cached eval result.
|
|
312
312
|
*/
|
|
313
313
|
declare class ShipeasyProvider implements Provider {
|
|
@@ -316,7 +316,7 @@ declare class ShipeasyProvider implements Provider {
|
|
|
316
316
|
readonly name: "shipeasy";
|
|
317
317
|
};
|
|
318
318
|
readonly runsOn: "client";
|
|
319
|
-
constructor(client:
|
|
319
|
+
constructor(client: Engine);
|
|
320
320
|
/** Identify with the initial static context so the first read is warm. */
|
|
321
321
|
initialize(context?: EvaluationContext): Promise<void>;
|
|
322
322
|
/** Re-identify when the application author changes the static context. */
|
|
@@ -101,8 +101,8 @@ interface AutoCollectGroups {
|
|
|
101
101
|
errors: boolean;
|
|
102
102
|
engagement: boolean;
|
|
103
103
|
}
|
|
104
|
-
type
|
|
105
|
-
interface
|
|
104
|
+
type EngineEnv = "dev" | "staging" | "prod";
|
|
105
|
+
interface EngineOptions {
|
|
106
106
|
sdkKey: string;
|
|
107
107
|
baseUrl?: string;
|
|
108
108
|
autoGuardrails?: boolean;
|
|
@@ -121,7 +121,7 @@ interface FlagsClientBrowserOptions {
|
|
|
121
121
|
*/
|
|
122
122
|
autoCollectAlways?: boolean;
|
|
123
123
|
/** Which published env to read values from. Defaults to "prod". */
|
|
124
|
-
env?:
|
|
124
|
+
env?: EngineEnv;
|
|
125
125
|
/**
|
|
126
126
|
* Per-evaluation usage telemetry. ON by default — each getFlag/getConfig/
|
|
127
127
|
* getExperiment/getKillswitch call fires one fire-and-forget sendBeacon so
|
|
@@ -158,11 +158,11 @@ interface FlagsClientBrowserOptions {
|
|
|
158
158
|
* Test mode — no network at all. identify()/init are no-ops (never call
|
|
159
159
|
* /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
|
|
160
160
|
* starts "ready" with an empty eval result. Prefer the
|
|
161
|
-
* {@link
|
|
161
|
+
* {@link Engine.forTesting} factory over passing this directly.
|
|
162
162
|
*/
|
|
163
163
|
testMode?: boolean;
|
|
164
164
|
}
|
|
165
|
-
declare class
|
|
165
|
+
declare class Engine {
|
|
166
166
|
private readonly sdkKey;
|
|
167
167
|
private readonly baseUrl;
|
|
168
168
|
private readonly autoGuardrails;
|
|
@@ -187,7 +187,7 @@ declare class FlagsClientBrowser {
|
|
|
187
187
|
private readonly configOverrides;
|
|
188
188
|
private readonly experimentOverrides;
|
|
189
189
|
private onOverrideChange;
|
|
190
|
-
constructor(opts:
|
|
190
|
+
constructor(opts: EngineOptions);
|
|
191
191
|
/**
|
|
192
192
|
* Build a no-network, immediately-usable browser client for tests
|
|
193
193
|
* (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
|
|
@@ -196,12 +196,12 @@ declare class FlagsClientBrowser {
|
|
|
196
196
|
* key required.
|
|
197
197
|
*
|
|
198
198
|
* ```ts
|
|
199
|
-
* const client =
|
|
199
|
+
* const client = Engine.forTesting();
|
|
200
200
|
* client.overrideFlag("new_checkout", true);
|
|
201
201
|
* client.getFlag("new_checkout"); // true
|
|
202
202
|
* ```
|
|
203
203
|
*/
|
|
204
|
-
static forTesting(opts?: Partial<
|
|
204
|
+
static forTesting(opts?: Partial<EngineOptions>): Engine;
|
|
205
205
|
identify(user: User): Promise<void>;
|
|
206
206
|
/**
|
|
207
207
|
* Report a structured error into the errors primitive. Flushes immediately
|
|
@@ -289,10 +289,10 @@ interface ShipeasySdkBridge {
|
|
|
289
289
|
*
|
|
290
290
|
* ```ts
|
|
291
291
|
* import { OpenFeature } from "@openfeature/web-sdk";
|
|
292
|
-
* import {
|
|
292
|
+
* import { Engine } from "@shipeasy/sdk/client";
|
|
293
293
|
* import { ShipeasyProvider } from "@shipeasy/sdk/openfeature-web";
|
|
294
294
|
*
|
|
295
|
-
* const client = new
|
|
295
|
+
* const client = new Engine({ sdkKey: NEXT_PUBLIC_SHIPEASY_CLIENT_KEY });
|
|
296
296
|
* await OpenFeature.setContext({ targetingKey: "u1", plan: "pro" });
|
|
297
297
|
* await OpenFeature.setProviderAndWait(new ShipeasyProvider(client));
|
|
298
298
|
*
|
|
@@ -307,7 +307,7 @@ interface ShipeasySdkBridge {
|
|
|
307
307
|
|
|
308
308
|
/**
|
|
309
309
|
* Shipeasy OpenFeature provider (client/web paradigm). Wraps a
|
|
310
|
-
* `
|
|
310
|
+
* `Engine`. Context changes are reconciled through `identify()`;
|
|
311
311
|
* flag reads come from the cached eval result.
|
|
312
312
|
*/
|
|
313
313
|
declare class ShipeasyProvider implements Provider {
|
|
@@ -316,7 +316,7 @@ declare class ShipeasyProvider implements Provider {
|
|
|
316
316
|
readonly name: "shipeasy";
|
|
317
317
|
};
|
|
318
318
|
readonly runsOn: "client";
|
|
319
|
-
constructor(client:
|
|
319
|
+
constructor(client: Engine);
|
|
320
320
|
/** Identify with the initial static context so the first read is warm. */
|
|
321
321
|
initialize(context?: EvaluationContext): Promise<void>;
|
|
322
322
|
/** Re-identify when the application author changes the static context. */
|
package/dist/server/index.d.mts
CHANGED
|
@@ -181,7 +181,7 @@ interface StickyEntry {
|
|
|
181
181
|
/**
|
|
182
182
|
* Pluggable sticky-bucketing store for the server (doc 20 §2). Keyed by the
|
|
183
183
|
* bucketing unit; the value is that unit's per-experiment assignments. Absent
|
|
184
|
-
* from {@link
|
|
184
|
+
* from {@link EngineOptions} ⇒ today's deterministic behaviour. Use
|
|
185
185
|
* {@link createInMemoryStickyStore} or a cookie-bridge built from request
|
|
186
186
|
* cookies.
|
|
187
187
|
*/
|
|
@@ -198,7 +198,7 @@ interface Killswitch {
|
|
|
198
198
|
killed: 0 | 1 | boolean;
|
|
199
199
|
switches?: Record<string, 0 | 1 | boolean>;
|
|
200
200
|
}
|
|
201
|
-
/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link
|
|
201
|
+
/** Body of `GET /sdk/flags` — the snapshot's `flags` field. See {@link Engine.fromSnapshot}. */
|
|
202
202
|
interface FlagsBlob {
|
|
203
203
|
version: string;
|
|
204
204
|
plan: string;
|
|
@@ -208,7 +208,7 @@ interface FlagsBlob {
|
|
|
208
208
|
}>;
|
|
209
209
|
killswitches: Record<string, Killswitch>;
|
|
210
210
|
}
|
|
211
|
-
/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link
|
|
211
|
+
/** Body of `GET /sdk/experiments` — the snapshot's `experiments` field. See {@link Engine.fromSnapshot}. */
|
|
212
212
|
interface ExpsBlob {
|
|
213
213
|
version: string;
|
|
214
214
|
universes: Record<string, Universe>;
|
|
@@ -221,12 +221,12 @@ interface BootstrapPayload {
|
|
|
221
221
|
killswitches: Record<string, boolean | Record<string, boolean>>;
|
|
222
222
|
}
|
|
223
223
|
declare const ANON_ID_COOKIE = "__se_anon_id";
|
|
224
|
-
type
|
|
225
|
-
interface
|
|
224
|
+
type EngineEnv = "dev" | "staging" | "prod";
|
|
225
|
+
interface EngineOptions {
|
|
226
226
|
apiKey: string;
|
|
227
227
|
baseUrl?: string;
|
|
228
228
|
/** Which published env to read values from. Defaults to "prod". */
|
|
229
|
-
env?:
|
|
229
|
+
env?: EngineEnv;
|
|
230
230
|
/**
|
|
231
231
|
* Preload the flags blob synchronously without a network fetch. Primarily
|
|
232
232
|
* for tests; production callers should rely on init()/initOnce().
|
|
@@ -261,12 +261,12 @@ interface FlagsClientOptions {
|
|
|
261
261
|
/**
|
|
262
262
|
* Test mode — no network at all. init()/initOnce() are no-ops (never fetch),
|
|
263
263
|
* track() is a no-op, telemetry is forced off, and the client starts
|
|
264
|
-
* "initialized" with an empty blob. Prefer the {@link
|
|
264
|
+
* "initialized" with an empty blob. Prefer the {@link Engine.forTesting}
|
|
265
265
|
* factory over passing this directly.
|
|
266
266
|
*/
|
|
267
267
|
testMode?: boolean;
|
|
268
268
|
}
|
|
269
|
-
declare class
|
|
269
|
+
declare class Engine {
|
|
270
270
|
private readonly apiKey;
|
|
271
271
|
private readonly baseUrl;
|
|
272
272
|
private readonly env;
|
|
@@ -286,7 +286,7 @@ declare class FlagsClient {
|
|
|
286
286
|
private readonly configOverrides;
|
|
287
287
|
private readonly experimentOverrides;
|
|
288
288
|
private readonly changeListeners;
|
|
289
|
-
constructor(opts:
|
|
289
|
+
constructor(opts: EngineOptions);
|
|
290
290
|
/**
|
|
291
291
|
* Build a no-network, immediately-usable client for tests (Statsig-style).
|
|
292
292
|
* init()/initOnce() are no-ops (never fetch), track() is a no-op, telemetry
|
|
@@ -294,12 +294,12 @@ declare class FlagsClient {
|
|
|
294
294
|
* with overrideFlag/overrideConfig/overrideExperiment. No SDK key required.
|
|
295
295
|
*
|
|
296
296
|
* ```ts
|
|
297
|
-
* const client =
|
|
297
|
+
* const client = Engine.forTesting();
|
|
298
298
|
* client.overrideFlag("new_checkout", true);
|
|
299
299
|
* client.getFlag("new_checkout", { user_id: "u1" }); // true
|
|
300
300
|
* ```
|
|
301
301
|
*/
|
|
302
|
-
static forTesting(opts?: Partial<
|
|
302
|
+
static forTesting(opts?: Partial<EngineOptions>): Engine;
|
|
303
303
|
/**
|
|
304
304
|
* Build a fully OFFLINE client from a pre-captured snapshot — no network ever.
|
|
305
305
|
* Reuses the test-mode plumbing (init()/initOnce()/track() are no-ops,
|
|
@@ -313,14 +313,14 @@ declare class FlagsClient {
|
|
|
313
313
|
static fromSnapshot(snapshot: {
|
|
314
314
|
flags: FlagsBlob;
|
|
315
315
|
experiments: ExpsBlob;
|
|
316
|
-
}):
|
|
316
|
+
}): Engine;
|
|
317
317
|
/**
|
|
318
318
|
* Build a fully OFFLINE client from a snapshot JSON file on disk (Node only —
|
|
319
319
|
* not available in the browser entrypoint). The file must contain
|
|
320
320
|
* `{ "flags": <GET /sdk/flags body>, "experiments": <GET /sdk/experiments body> }`.
|
|
321
|
-
* See {@link
|
|
321
|
+
* See {@link Engine.fromSnapshot}.
|
|
322
322
|
*/
|
|
323
|
-
static fromFile(path: string):
|
|
323
|
+
static fromFile(path: string): Engine;
|
|
324
324
|
init(): Promise<void>;
|
|
325
325
|
initOnce(): Promise<void>;
|
|
326
326
|
/** Force `getFlag(name, …)` to return `value`, ignoring the fetched gate. */
|
|
@@ -440,8 +440,8 @@ interface FetchLabelsOptions {
|
|
|
440
440
|
timeoutMs?: number;
|
|
441
441
|
}
|
|
442
442
|
declare function fetchLabelsForSSR(opts: FetchLabelsOptions): Promise<LabelFile | null>;
|
|
443
|
-
declare function configureShipeasyServer(opts:
|
|
444
|
-
declare function getShipeasyServerClient():
|
|
443
|
+
declare function configureShipeasyServer(opts: EngineOptions): Engine;
|
|
444
|
+
declare function getShipeasyServerClient(): Engine | null;
|
|
445
445
|
declare function _resetShipeasyServerForTests(): void;
|
|
446
446
|
interface ShipeasyServerConfig {
|
|
447
447
|
/**
|
|
@@ -463,13 +463,13 @@ interface ShipeasyServerConfig {
|
|
|
463
463
|
/**
|
|
464
464
|
* Disable per-evaluation usage telemetry. ON by default. On Cloudflare
|
|
465
465
|
* Workers each beacon is an outbound subrequest, so disable on hot SSR paths
|
|
466
|
-
* that evaluate many flags per request. See {@link
|
|
466
|
+
* that evaluate many flags per request. See {@link EngineOptions.disableTelemetry}.
|
|
467
467
|
*/
|
|
468
468
|
disableTelemetry?: boolean;
|
|
469
469
|
/**
|
|
470
470
|
* Attribute names usable for targeting but never persisted in analytics
|
|
471
471
|
* (LD/Statsig `privateAttributes`). Stripped from every outbound `track()`
|
|
472
|
-
* payload. See {@link
|
|
472
|
+
* payload. See {@link EngineOptions.privateAttributes}.
|
|
473
473
|
*/
|
|
474
474
|
privateAttributes?: string[];
|
|
475
475
|
}
|
|
@@ -477,8 +477,22 @@ interface ShipeasyServerHandle {
|
|
|
477
477
|
flags: Record<string, boolean>;
|
|
478
478
|
configs: Record<string, unknown>;
|
|
479
479
|
experiments: Record<string, ExperimentResult<Record<string, unknown>>>;
|
|
480
|
-
/**
|
|
481
|
-
|
|
480
|
+
/**
|
|
481
|
+
* Structured `<script>` tag specs to drop into the document head: the
|
|
482
|
+
* cross-platform `se-bootstrap.js` tag (hydrates window.__SE_BOOTSTRAP +
|
|
483
|
+
* writes the anon cookie) and, when there are SSR strings or a client key,
|
|
484
|
+
* the i18n loader tag. Use this in React: scripts inserted via
|
|
485
|
+
* `dangerouslySetInnerHTML` do NOT execute, so render real `<script>`
|
|
486
|
+
* elements from these specs (see apps/ui root layout).
|
|
487
|
+
*/
|
|
488
|
+
getBootstrapData(emit?: BootstrapEmitOptions): BootstrapData;
|
|
489
|
+
/**
|
|
490
|
+
* The same tags rendered as an HTML string, for non-React SSR (Express, raw
|
|
491
|
+
* templates) where the markup is emitted directly into the served HTML (and
|
|
492
|
+
* therefore executes normally). This is the canonical cross-platform shape
|
|
493
|
+
* every server SDK mirrors.
|
|
494
|
+
*/
|
|
495
|
+
getBootstrapTags(emit?: BootstrapEmitOptions): string;
|
|
482
496
|
}
|
|
483
497
|
/**
|
|
484
498
|
* Initialise the ShipEasy server SDK, evaluate flags for this request, and
|
|
@@ -487,37 +501,53 @@ interface ShipeasyServerHandle {
|
|
|
487
501
|
* payloads and i18n falls back to hardcoded strings.
|
|
488
502
|
*/
|
|
489
503
|
declare function shipeasy(opts: ShipeasyServerConfig): Promise<ShipeasyServerHandle>;
|
|
490
|
-
interface
|
|
491
|
-
/** i18n profile recorded
|
|
504
|
+
interface BootstrapEmitOptions {
|
|
505
|
+
/** i18n profile recorded on both tags so the client loader matches SSR. Defaults to "en:prod". */
|
|
492
506
|
i18nProfile?: string;
|
|
493
|
-
/** When true, tEl() embeds label markers so the devtools can highlight them. */
|
|
494
|
-
editLabels?: boolean;
|
|
495
507
|
/**
|
|
496
|
-
* Stable anonymous bucketing id the server evaluated against. Emitted
|
|
497
|
-
*
|
|
498
|
-
* `__se_anon_id` cookie, so the
|
|
499
|
-
*
|
|
500
|
-
* middleware doesn't cover. See
|
|
508
|
+
* Stable anonymous bucketing id the server evaluated against. Emitted as
|
|
509
|
+
* `data-anon-id`; se-bootstrap.js exposes it on window.__SE_BOOTSTRAP and
|
|
510
|
+
* persists it (pre-paint) to the first-party `__se_anon_id` cookie, so the
|
|
511
|
+
* browser SDK buckets identically to SSR. Normally minted by edge
|
|
512
|
+
* middleware; this is the fallback for routes it doesn't cover. See
|
|
513
|
+
* experiment-platform/18-identity-bucketing.md.
|
|
501
514
|
*/
|
|
502
515
|
anonId?: string;
|
|
516
|
+
/**
|
|
517
|
+
* Public client key. When provided, the i18n loader tag can revalidate
|
|
518
|
+
* strings at runtime (`data-key`). Optional — the bootstrap tag NEVER carries
|
|
519
|
+
* a key, and SSR first paint works keyless via `data-strings`.
|
|
520
|
+
*/
|
|
521
|
+
clientKey?: string;
|
|
522
|
+
/** CDN base for the tag `src`s. Defaults to https://cdn.shipeasy.ai. */
|
|
523
|
+
baseUrl?: string;
|
|
524
|
+
}
|
|
525
|
+
interface ScriptTagSpec {
|
|
526
|
+
src: string;
|
|
527
|
+
/** Attribute name → value. An empty-string value renders as a bare boolean attribute (e.g. `data-se-bootstrap`). */
|
|
528
|
+
attrs: Record<string, string>;
|
|
529
|
+
}
|
|
530
|
+
interface BootstrapData {
|
|
531
|
+
/** se-bootstrap.js tag — always present. */
|
|
532
|
+
bootstrap: ScriptTagSpec;
|
|
533
|
+
/** i18n loader tag — null when there are no SSR strings and no client key. */
|
|
534
|
+
i18nLoader: ScriptTagSpec | null;
|
|
503
535
|
}
|
|
504
536
|
/**
|
|
505
|
-
*
|
|
506
|
-
*
|
|
507
|
-
*
|
|
508
|
-
* server-side). The browser supplies its own client key via
|
|
509
|
-
* `shipeasy({ clientKey })` from @shipeasy/sdk/client, which also injects the
|
|
510
|
-
* runtime i18n loader. This script emits:
|
|
511
|
-
* - window.__se_devtools_config (when devtoolsAdminUrl is set)
|
|
512
|
-
* - window.__SE_BOOTSTRAP (flags + configs + experiments + i18n DATA + i18nProfile, NO key)
|
|
513
|
-
* - window.i18n shim from SSR strings (prevents hydration mismatches / FOUC)
|
|
514
|
-
* - devtools overlay loader when ?se / ?se_devtools is present
|
|
515
|
-
*
|
|
516
|
-
* Framework-agnostic: set innerHTML on a <script> element, nothing else required.
|
|
537
|
+
* Build the structured `<script>` tag specs for the SSR bootstrap. Render
|
|
538
|
+
* these as REAL `<script>` elements (React: scripts set via innerHTML do not
|
|
539
|
+
* execute). No SDK key is ever embedded in the bootstrap tag.
|
|
517
540
|
*/
|
|
518
|
-
declare function
|
|
541
|
+
declare function getBootstrapData(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapEmitOptions): BootstrapData;
|
|
542
|
+
/**
|
|
543
|
+
* The bootstrap (and optional i18n loader) tags as an HTML string, for non-React
|
|
544
|
+
* SSR (Express, raw templates) where the markup is emitted directly into the
|
|
545
|
+
* served HTML and executes normally. React callers should use
|
|
546
|
+
* {@link getBootstrapData} and render real `<script>` elements instead.
|
|
547
|
+
*/
|
|
548
|
+
declare function getBootstrapTags(bootstrap: BootstrapPayload | null, i18nData: I18nForRequest | null, opts: BootstrapEmitOptions): string;
|
|
519
549
|
declare const flags: {
|
|
520
|
-
configure(opts:
|
|
550
|
+
configure(opts: EngineOptions): void;
|
|
521
551
|
/**
|
|
522
552
|
* Long-running server: starts the background poll. Call once at app boot.
|
|
523
553
|
* Throws if the initial fetch fails (caller decides whether to crash or degrade).
|
|
@@ -540,7 +570,7 @@ declare const flags: {
|
|
|
540
570
|
ks(name: string, switchKey?: string): boolean;
|
|
541
571
|
track(userId: string, eventName: string, props?: Record<string, unknown>): void;
|
|
542
572
|
/** Emit an exposure for an enrolled experiment at the decision point. See
|
|
543
|
-
* {@link
|
|
573
|
+
* {@link Engine.logExposure}. No-op before configure(). */
|
|
544
574
|
logExposure(user: string | User, name: string): void;
|
|
545
575
|
/**
|
|
546
576
|
* Evaluate all flags / configs / experiments for a user against the locally
|
|
@@ -549,6 +579,65 @@ declare const flags: {
|
|
|
549
579
|
*/
|
|
550
580
|
evaluate(user: User, rawUrl?: string): BootstrapPayload;
|
|
551
581
|
};
|
|
582
|
+
/** Transform YOUR application's user object into Shipeasy targeting attributes. */
|
|
583
|
+
type AttributesFn<U = unknown> = (user: U) => User;
|
|
584
|
+
interface ConfigureOptions<U = unknown> extends Omit<EngineOptions, "apiKey"> {
|
|
585
|
+
/** Server key — the single key the server side accepts (SHIPEASY_SERVER_KEY). */
|
|
586
|
+
apiKey: string;
|
|
587
|
+
/**
|
|
588
|
+
* Map your own user object into the attribute bag every flag/experiment
|
|
589
|
+
* evaluation sees. Runs once per `new Client(user)`. Omit when you already
|
|
590
|
+
* pass a plain attribute object (identity transform — the object is used
|
|
591
|
+
* verbatim, so it should carry `user_id`/`anonymous_id` + any targeting attrs).
|
|
592
|
+
*/
|
|
593
|
+
attributes?: AttributesFn<U>;
|
|
594
|
+
}
|
|
595
|
+
/**
|
|
596
|
+
* Configure the SDK once at app boot, then evaluate per user with
|
|
597
|
+
* `new Client(user)`. Builds the process-wide {@link Engine} (polling + blob
|
|
598
|
+
* cache + HTTP) and registers the `attributes` transform. The first call wins;
|
|
599
|
+
* later calls return the existing engine (mirrors {@link configureShipeasyServer}).
|
|
600
|
+
*
|
|
601
|
+
* ```ts
|
|
602
|
+
* import { configure, Client } from "@shipeasy/sdk/server";
|
|
603
|
+
*
|
|
604
|
+
* configure({
|
|
605
|
+
* apiKey: process.env.SHIPEASY_SERVER_KEY!,
|
|
606
|
+
* attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan, country: u.geo.country }),
|
|
607
|
+
* });
|
|
608
|
+
*
|
|
609
|
+
* const flags = new Client(currentUser);
|
|
610
|
+
* if (flags.getFlag("new_checkout")) { ... }
|
|
611
|
+
* ```
|
|
612
|
+
*/
|
|
613
|
+
declare function configure<U = unknown>(opts: ConfigureOptions<U>): Engine;
|
|
614
|
+
/** Test seam: reset the registered attribute transform. */
|
|
615
|
+
declare function _resetConfigureForTests(): void;
|
|
616
|
+
/**
|
|
617
|
+
* A user-bound evaluation handle. Construct one per user/request — it's cheap
|
|
618
|
+
* (it delegates to the {@link Engine} built by {@link configure}); it does NOT
|
|
619
|
+
* open its own connection or poll. The configured `attributes` transform runs
|
|
620
|
+
* once here, so every getFlag/getConfig/getExperiment reads the same bag.
|
|
621
|
+
*
|
|
622
|
+
* ```ts
|
|
623
|
+
* const flags = new Client(req.user);
|
|
624
|
+
* flags.getFlag("new_checkout"); // no user arg — bound at construction
|
|
625
|
+
* flags.getExperiment("price_test", { price: 9 });
|
|
626
|
+
* ```
|
|
627
|
+
*/
|
|
628
|
+
declare class Client<U = unknown> {
|
|
629
|
+
private readonly engine;
|
|
630
|
+
/** The resolved attribute bag this handle evaluates against. */
|
|
631
|
+
readonly attributes: User;
|
|
632
|
+
constructor(user: U);
|
|
633
|
+
getFlag(name: string, defaultValue?: boolean): boolean;
|
|
634
|
+
getFlagDetail(name: string): FlagDetail;
|
|
635
|
+
getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
|
|
636
|
+
getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
|
|
637
|
+
getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P): ExperimentResult<P>;
|
|
638
|
+
/** Read a killswitch (not user-bound; mirrors {@link Engine.getKillswitch}). */
|
|
639
|
+
getKillswitch(name: string, switchKey?: string): boolean;
|
|
640
|
+
}
|
|
552
641
|
interface SeeApi {
|
|
553
642
|
/**
|
|
554
643
|
* Report a handled problem and its product consequence:
|
|
@@ -600,4 +689,4 @@ interface SeeApi {
|
|
|
600
689
|
*/
|
|
601
690
|
declare const see: SeeApi;
|
|
602
691
|
|
|
603
|
-
export { ANON_ID_COOKIE, type
|
|
692
|
+
export { ANON_ID_COOKIE, type AttributesFn, type BootstrapData, type BootstrapEmitOptions, type BootstrapPayload, Client, type ConfigureOptions, type Consequence, Engine, type EngineEnv, type EngineOptions, type ExperimentResult, type ExpsBlob, FLAG_REASONS, type FetchLabelsOptions, type FlagDetail, type FlagReason, type FlagsBlob, type GetConfigOptions, type I18nForRequest, type LabelFile, type ScriptTagSpec, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type StickyBucketStore, type StickyEntry, type User, type Violation, _murmur3ForTests, _resetConfigureForTests, _resetShipeasyServerForTests, configure, configureShipeasyServer, createInMemoryStickyStore, fetchLabelsForSSR, flags, getBootstrapData, getBootstrapTags, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
|