@metarouter/react-native-sdk 1.7.0 → 1.8.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.
Files changed (31) hide show
  1. package/README.md +164 -56
  2. package/lib/analytics/MetaRouterAnalyticsClient.d.ts +50 -2
  3. package/lib/analytics/MetaRouterAnalyticsClient.d.ts.map +1 -1
  4. package/lib/analytics/MetaRouterAnalyticsClient.js +239 -44
  5. package/lib/analytics/init.d.ts +7 -0
  6. package/lib/analytics/init.d.ts.map +1 -1
  7. package/lib/analytics/init.js +197 -37
  8. package/lib/analytics/lifecycle/lifecycleEvents.d.ts +52 -0
  9. package/lib/analytics/lifecycle/lifecycleEvents.d.ts.map +1 -0
  10. package/lib/analytics/lifecycle/lifecycleEvents.js +66 -0
  11. package/lib/analytics/proxy/proxyClient.d.ts +29 -0
  12. package/lib/analytics/proxy/proxyClient.d.ts.map +1 -1
  13. package/lib/analytics/proxy/proxyClient.js +125 -5
  14. package/lib/analytics/types.d.ts +50 -1
  15. package/lib/analytics/types.d.ts.map +1 -1
  16. package/lib/analytics/utils/appContext.d.ts +20 -0
  17. package/lib/analytics/utils/appContext.d.ts.map +1 -0
  18. package/lib/analytics/utils/appContext.js +22 -0
  19. package/lib/analytics/utils/contextInfo.d.ts +7 -3
  20. package/lib/analytics/utils/contextInfo.d.ts.map +1 -1
  21. package/lib/analytics/utils/contextInfo.js +12 -9
  22. package/lib/analytics/utils/initOptions.d.ts +22 -0
  23. package/lib/analytics/utils/initOptions.d.ts.map +1 -0
  24. package/lib/analytics/utils/initOptions.js +100 -0
  25. package/lib/analytics/utils/lifecycleStorage.d.ts +13 -0
  26. package/lib/analytics/utils/lifecycleStorage.d.ts.map +1 -0
  27. package/lib/analytics/utils/lifecycleStorage.js +35 -0
  28. package/lib/index.d.ts +4 -4
  29. package/lib/index.d.ts.map +1 -1
  30. package/lib/index.js +3 -3
  31. package/package.json +1 -1
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Names + property keys for the four Application lifecycle events.
3
+ */
4
+ import Dispatcher from '../dispatcher';
5
+ import { EnrichedEventPayload } from '../types';
6
+ import { AppContext } from '../utils/appContext';
7
+ export declare const APPLICATION_INSTALLED = "Application Installed";
8
+ export declare const APPLICATION_UPDATED = "Application Updated";
9
+ export declare const APPLICATION_OPENED = "Application Opened";
10
+ export declare const APPLICATION_BACKGROUNDED = "Application Backgrounded";
11
+ export declare const PROP_VERSION = "version";
12
+ export declare const PROP_BUILD = "build";
13
+ export declare const PROP_PREVIOUS_VERSION = "previous_version";
14
+ export declare const PROP_PREVIOUS_BUILD = "previous_build";
15
+ export declare const PROP_FROM_BACKGROUND = "from_background";
16
+ export declare const PROP_REFERRING_APPLICATION = "referring_application";
17
+ export declare const PROP_URL = "url";
18
+ /** Unknown previous_version/previous_build for SDK upgrades from a pre-lifecycle build. */
19
+ export declare const UNKNOWN_PREVIOUS = "unknown";
20
+ export interface DeepLinkInfo {
21
+ url?: string;
22
+ referringApplication?: string;
23
+ }
24
+ /**
25
+ * Builds a fully-enriched track-type EnrichedEventPayload (identity + writeKey
26
+ * + context + messageId + timestamp). Provided by the analytics client so the
27
+ * emitter does not need to know how identity/enrichment are wired.
28
+ */
29
+ export type CreateTrackEvent = (event: string, properties?: Record<string, any>) => EnrichedEventPayload;
30
+ /**
31
+ * Thin emitter that wraps the dispatch path with the lifecycle event shapes.
32
+ * Mirrors the iOS LifecycleEventEmitter: takes a Dispatcher and an enrichment
33
+ * callable plus a process-stable AppContext, then constructs Installed /
34
+ * Updated / Opened / Backgrounded payloads. Construct only when lifecycle
35
+ * tracking is enabled; callers should skip construction entirely when the
36
+ * flag is off.
37
+ */
38
+ export declare class LifecycleEmitter {
39
+ private readonly dispatcher;
40
+ private readonly createTrackEvent;
41
+ private readonly appContext;
42
+ constructor(dispatcher: Dispatcher, createTrackEvent: CreateTrackEvent, appContext: AppContext);
43
+ emitInstalled(): void;
44
+ emitUpdated(previous: {
45
+ version: string;
46
+ build: string;
47
+ }): void;
48
+ emitOpened(fromBackground: boolean, deepLink?: DeepLinkInfo): void;
49
+ emitBackgrounded(): void;
50
+ private dispatch;
51
+ }
52
+ //# sourceMappingURL=lifecycleEvents.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lifecycleEvents.d.ts","sourceRoot":"","sources":["../../../src/analytics/lifecycle/lifecycleEvents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,UAAU,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAEnE,eAAO,MAAM,YAAY,YAAY,CAAC;AACtC,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AACtD,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAE9B,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAC7B,oBAAoB,CAAC;AAE1B;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;gBAGtC,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,gBAAgB,EAClC,UAAU,EAAE,UAAU;IAOxB,aAAa,IAAI,IAAI;IAOrB,WAAW,CAAC,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAS/D,UAAU,CAAC,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI;IAelE,gBAAgB,IAAI,IAAI;IAIxB,OAAO,CAAC,QAAQ;CAIjB"}
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Names + property keys for the four Application lifecycle events.
3
+ */
4
+ export const APPLICATION_INSTALLED = 'Application Installed';
5
+ export const APPLICATION_UPDATED = 'Application Updated';
6
+ export const APPLICATION_OPENED = 'Application Opened';
7
+ export const APPLICATION_BACKGROUNDED = 'Application Backgrounded';
8
+ export const PROP_VERSION = 'version';
9
+ export const PROP_BUILD = 'build';
10
+ export const PROP_PREVIOUS_VERSION = 'previous_version';
11
+ export const PROP_PREVIOUS_BUILD = 'previous_build';
12
+ export const PROP_FROM_BACKGROUND = 'from_background';
13
+ export const PROP_REFERRING_APPLICATION = 'referring_application';
14
+ export const PROP_URL = 'url';
15
+ /** Unknown previous_version/previous_build for SDK upgrades from a pre-lifecycle build. */
16
+ export const UNKNOWN_PREVIOUS = 'unknown';
17
+ /**
18
+ * Thin emitter that wraps the dispatch path with the lifecycle event shapes.
19
+ * Mirrors the iOS LifecycleEventEmitter: takes a Dispatcher and an enrichment
20
+ * callable plus a process-stable AppContext, then constructs Installed /
21
+ * Updated / Opened / Backgrounded payloads. Construct only when lifecycle
22
+ * tracking is enabled; callers should skip construction entirely when the
23
+ * flag is off.
24
+ */
25
+ export class LifecycleEmitter {
26
+ constructor(dispatcher, createTrackEvent, appContext) {
27
+ this.dispatcher = dispatcher;
28
+ this.createTrackEvent = createTrackEvent;
29
+ this.appContext = appContext;
30
+ }
31
+ emitInstalled() {
32
+ this.dispatch(APPLICATION_INSTALLED, {
33
+ [PROP_VERSION]: this.appContext.version,
34
+ [PROP_BUILD]: this.appContext.build,
35
+ });
36
+ }
37
+ emitUpdated(previous) {
38
+ this.dispatch(APPLICATION_UPDATED, {
39
+ [PROP_VERSION]: this.appContext.version,
40
+ [PROP_BUILD]: this.appContext.build,
41
+ [PROP_PREVIOUS_VERSION]: previous.version,
42
+ [PROP_PREVIOUS_BUILD]: previous.build,
43
+ });
44
+ }
45
+ emitOpened(fromBackground, deepLink) {
46
+ const props = {
47
+ [PROP_FROM_BACKGROUND]: fromBackground,
48
+ [PROP_VERSION]: this.appContext.version,
49
+ [PROP_BUILD]: this.appContext.build,
50
+ };
51
+ if (deepLink === null || deepLink === void 0 ? void 0 : deepLink.url) {
52
+ props[PROP_URL] = deepLink.url;
53
+ }
54
+ if (deepLink === null || deepLink === void 0 ? void 0 : deepLink.referringApplication) {
55
+ props[PROP_REFERRING_APPLICATION] = deepLink.referringApplication;
56
+ }
57
+ this.dispatch(APPLICATION_OPENED, props);
58
+ }
59
+ emitBackgrounded() {
60
+ this.dispatch(APPLICATION_BACKGROUNDED, {});
61
+ }
62
+ dispatch(event, properties) {
63
+ const enriched = this.createTrackEvent(event, properties);
64
+ this.dispatcher.enqueue(enriched);
65
+ }
66
+ }
@@ -1,5 +1,11 @@
1
1
  import type { AnalyticsInterface } from '../types';
2
2
  export declare const proxyClient: AnalyticsInterface;
3
+ /**
4
+ * Sets (or clears, with `null`) the client whose init() is in flight, so
5
+ * recordOpenedURL reaches it before the cold-launch Opened is emitted.
6
+ * Cleared as soon as init() settles, before binding.
7
+ */
8
+ export declare function setInitializingClient(client: Pick<AnalyticsInterface, 'recordOpenedURL'> | null): void;
3
9
  /**
4
10
  * Binds or unbinds the real analytics client to the proxy and manages queued calls.
5
11
  *
@@ -30,4 +36,27 @@ export declare const proxyClient: AnalyticsInterface;
30
36
  export declare function setRealClient(client: AnalyticsInterface | null, opts?: {
31
37
  dropPending?: boolean;
32
38
  }): void;
39
+ /** Registers init.ts's session reset, used by `reset()` in every state. */
40
+ export declare function setResetHandler(handler: (() => Promise<void>) | null): void;
41
+ /**
42
+ * Refuses the session: unbinds, drops calls queued before the refusal (they
43
+ * belonged to a session that never bound), settles their promises with the
44
+ * degraded value instead of rejecting, and makes later async calls resolve
45
+ * degraded. Calls made after this point queue and replay on recovery.
46
+ */
47
+ export declare function markConfigDisabled(description: string): void;
48
+ /**
49
+ * Lifts a refusal before a valid init builds its client, so async calls made
50
+ * during that init wait for the incoming bind rather than resolving against
51
+ * the previous verdict.
52
+ */
53
+ export declare function clearConfigDisabled(): void;
54
+ /**
55
+ * Removes and returns queued recordOpenedURL calls, oldest first. The init that
56
+ * builds a client applies them before init() runs: createAnalyticsClient only
57
+ * queues that init, so a URL forwarded right after the call (the usual
58
+ * `Linking.getInitialURL()` wiring) is queued here before any client exists,
59
+ * and replaying it after bind would miss the cold-launch Opened.
60
+ */
61
+ export declare function takePendingOpenedURLs(): Parameters<AnalyticsInterface['recordOpenedURL']>[];
33
62
  //# sourceMappingURL=proxyClient.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"proxyClient.d.ts","sourceRoot":"","sources":["../../../src/analytics/proxy/proxyClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AA2InD,eAAO,MAAM,WAAW,EAAE,kBAkBzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,QAqBjC"}
1
+ {"version":3,"file":"proxyClient.d.ts","sourceRoot":"","sources":["../../../src/analytics/proxy/proxyClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAgOnD,eAAO,MAAM,WAAW,EAAE,kBAoBzB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,GAAG,IAAI,QAG3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,QAuBjC;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,OAAO,EAAE,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,QAEpE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,QAMrD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,SAElC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,UAAU,CACjD,kBAAkB,CAAC,iBAAiB,CAAC,CACtC,EAAE,CAYF"}
@@ -1,6 +1,20 @@
1
1
  const pendingCalls = [];
2
2
  const MAX_PENDING_CALLS = 20;
3
3
  let realClient = null;
4
+ // Description of the config error that refused this session, or null. While
5
+ // set, calls still queue (and replay if a valid init recovers the session),
6
+ // but nothing that returns a promise may wait for a bind that is not coming.
7
+ let configDisabledError = null;
8
+ // Owned by init.ts: reset must work before a bind (it is how a refused or
9
+ // still-initializing session is cleared), so the proxy cannot route it to the
10
+ // bound client alone.
11
+ let resetHandler = null;
12
+ // The client whose init() is still running. recordOpenedURL only fills a
13
+ // one-slot buffer that the cold-launch Application Opened reads during
14
+ // init(), and the proxy binds only after init() resolves — so a cold-launch
15
+ // URL queued for replay would always miss its own Opened and ride on the
16
+ // next resume instead. Routing it here lets it land before that emit.
17
+ let initializingClient = null;
4
18
  const ASYNC_METHODS = {
5
19
  flush: true,
6
20
  getDebugInfo: true,
@@ -9,6 +23,26 @@ const ASYNC_METHODS = {
9
23
  clearAdvertisingId: true,
10
24
  };
11
25
  const isAsyncMethod = (m) => ASYNC_METHODS[m] === true;
26
+ /**
27
+ * What an async call resolves to on a config-refused session. getAnonymousId
28
+ * resolves "" promptly, like iOS and Android: a permanent hang on a
29
+ * misconfigured SDK would be worse than the crash this contract replaces.
30
+ */
31
+ function degradedResult(methodName) {
32
+ switch (methodName) {
33
+ case 'getAnonymousId':
34
+ return '';
35
+ case 'getDebugInfo':
36
+ return {
37
+ lifecycle: 'disabled',
38
+ proxy: true,
39
+ pendingCalls: pendingCalls.length,
40
+ configError: configDisabledError,
41
+ };
42
+ default:
43
+ return undefined;
44
+ }
45
+ }
12
46
  // One in-flight flush at a time
13
47
  let flushInFlight = null;
14
48
  /**
@@ -37,7 +71,7 @@ let flushInFlight = null;
37
71
  function handleMethodCall(methodName, ...args) {
38
72
  var _a;
39
73
  // Real client bound
40
- if (realClient) {
74
+ if (realClient && methodName !== 'reset') {
41
75
  if (methodName === 'flush') {
42
76
  if (flushInFlight)
43
77
  return flushInFlight;
@@ -49,22 +83,46 @@ function handleMethodCall(methodName, ...args) {
49
83
  }
50
84
  return realClient[methodName](...args);
51
85
  }
86
+ if (methodName === 'reset') {
87
+ if (resetHandler) {
88
+ return resetHandler();
89
+ }
90
+ return (realClient ? realClient.reset() : Promise.resolve());
91
+ }
52
92
  // No real client bound yet
93
+ if (methodName === 'recordOpenedURL' && initializingClient) {
94
+ initializingClient.recordOpenedURL(...args);
95
+ return undefined;
96
+ }
97
+ // Refused session: queries answer now and never take a queue slot.
98
+ if (configDisabledError !== null &&
99
+ (methodName === 'getAnonymousId' || methodName === 'getDebugInfo')) {
100
+ return Promise.resolve(degradedResult(methodName));
101
+ }
53
102
  if (pendingCalls.length >= MAX_PENDING_CALLS) {
54
103
  const dropped = pendingCalls.shift();
55
104
  (_a = dropped === null || dropped === void 0 ? void 0 : dropped.reject) === null || _a === void 0 ? void 0 : _a.call(dropped, new Error(`[MetaRouter] Dropped oldest call (queue cap ${MAX_PENDING_CALLS})`));
56
105
  console.warn(`[MetaRouter] Oldest call dropped (queue cap ${MAX_PENDING_CALLS})`);
57
106
  }
58
- // Special-cases while unbound:
59
- if (methodName === 'reset') {
60
- // Nothing to reset pre-bind; resolve immediately
61
- return Promise.resolve();
107
+ if (isAsyncMethod(methodName) && configDisabledError !== null) {
108
+ // Refused session: commands (flush, advertising id) still queue so a
109
+ // recovering valid init replays them like any other call, but their
110
+ // promise resolves now instead of waiting for a bind.
111
+ pendingCalls.push({
112
+ fn: () => {
113
+ if (!realClient)
114
+ return;
115
+ return Promise.resolve(realClient[methodName](...args)).then(() => undefined);
116
+ },
117
+ });
118
+ return Promise.resolve(undefined);
62
119
  }
63
120
  if (isAsyncMethod(methodName)) {
64
121
  // Queue async call and return a promise that resolves after bind+run
65
122
  return new Promise((resolve, reject) => {
66
123
  pendingCalls.push({
67
124
  reject, // keep a handle for dropPending
125
+ degrade: () => resolve(degradedResult(methodName)),
68
126
  fn: async () => {
69
127
  try {
70
128
  if (!realClient) {
@@ -96,6 +154,9 @@ function handleMethodCall(methodName, ...args) {
96
154
  return;
97
155
  realClient[methodName](...args);
98
156
  },
157
+ ...(methodName === 'recordOpenedURL' && {
158
+ openedURL: args,
159
+ }),
99
160
  });
100
161
  return undefined;
101
162
  }
@@ -106,6 +167,7 @@ export const proxyClient = {
106
167
  screen: (name, props) => handleMethodCall('screen', name, props),
107
168
  page: (name, props) => handleMethodCall('page', name, props),
108
169
  alias: (newUserId) => handleMethodCall('alias', newUserId),
170
+ recordOpenedURL: (url, sourceApplication) => handleMethodCall('recordOpenedURL', url, sourceApplication),
109
171
  setAdvertisingId: (advertisingId) => handleMethodCall('setAdvertisingId', advertisingId),
110
172
  clearAdvertisingId: () => handleMethodCall('clearAdvertisingId'),
111
173
  setTracing: (enabled) => handleMethodCall('setTracing', enabled),
@@ -115,6 +177,14 @@ export const proxyClient = {
115
177
  getDebugInfo: () => handleMethodCall('getDebugInfo'),
116
178
  getAnonymousId: () => handleMethodCall('getAnonymousId'),
117
179
  };
180
+ /**
181
+ * Sets (or clears, with `null`) the client whose init() is in flight, so
182
+ * recordOpenedURL reaches it before the cold-launch Opened is emitted.
183
+ * Cleared as soon as init() settles, before binding.
184
+ */
185
+ export function setInitializingClient(client) {
186
+ initializingClient = client;
187
+ }
118
188
  /**
119
189
  * Binds or unbinds the real analytics client to the proxy and manages queued calls.
120
190
  *
@@ -145,6 +215,8 @@ export const proxyClient = {
145
215
  export function setRealClient(client, opts) {
146
216
  var _a;
147
217
  realClient = client;
218
+ // Binding a client, or a reset's unbind, ends any refusal.
219
+ configDisabledError = null;
148
220
  if (client) {
149
221
  const items = pendingCalls.splice(0, pendingCalls.length);
150
222
  for (const { fn } of items) {
@@ -165,3 +237,51 @@ export function setRealClient(client, opts) {
165
237
  flushInFlight = null; // reset coalescer
166
238
  }
167
239
  }
240
+ /** Registers init.ts's session reset, used by `reset()` in every state. */
241
+ export function setResetHandler(handler) {
242
+ resetHandler = handler;
243
+ }
244
+ /**
245
+ * Refuses the session: unbinds, drops calls queued before the refusal (they
246
+ * belonged to a session that never bound), settles their promises with the
247
+ * degraded value instead of rejecting, and makes later async calls resolve
248
+ * degraded. Calls made after this point queue and replay on recovery.
249
+ */
250
+ export function markConfigDisabled(description) {
251
+ var _a;
252
+ realClient = null;
253
+ flushInFlight = null;
254
+ configDisabledError = description;
255
+ const items = pendingCalls.splice(0, pendingCalls.length);
256
+ for (const it of items)
257
+ (_a = it.degrade) === null || _a === void 0 ? void 0 : _a.call(it);
258
+ }
259
+ /**
260
+ * Lifts a refusal before a valid init builds its client, so async calls made
261
+ * during that init wait for the incoming bind rather than resolving against
262
+ * the previous verdict.
263
+ */
264
+ export function clearConfigDisabled() {
265
+ configDisabledError = null;
266
+ }
267
+ /**
268
+ * Removes and returns queued recordOpenedURL calls, oldest first. The init that
269
+ * builds a client applies them before init() runs: createAnalyticsClient only
270
+ * queues that init, so a URL forwarded right after the call (the usual
271
+ * `Linking.getInitialURL()` wiring) is queued here before any client exists,
272
+ * and replaying it after bind would miss the cold-launch Opened.
273
+ */
274
+ export function takePendingOpenedURLs() {
275
+ const taken = [];
276
+ for (let i = 0; i < pendingCalls.length;) {
277
+ const args = pendingCalls[i].openedURL;
278
+ if (args) {
279
+ taken.push(args);
280
+ pendingCalls.splice(i, 1);
281
+ }
282
+ else {
283
+ i++;
284
+ }
285
+ }
286
+ return taken;
287
+ }
@@ -16,20 +16,56 @@ export interface EnrichedEventPayload extends EventWithIdentity {
16
16
  context: EventContext;
17
17
  writeKey: string;
18
18
  }
19
+ /**
20
+ * Why `createAnalyticsClient` refused its options. In development builds the
21
+ * call throws instead; in release the SDK stays inert for the session and
22
+ * reports this through `onConfigError` and `getDebugInfo().configError`.
23
+ * `description` is the same text the iOS and Android SDKs give.
24
+ */
25
+ export type ConfigError = {
26
+ type: 'emptyWriteKey';
27
+ description: string;
28
+ } | {
29
+ type: 'invalidIngestionHost';
30
+ raw: string;
31
+ description: string;
32
+ };
19
33
  export interface InitOptions {
34
+ /** Required. Trimmed; empty or whitespace-only is a config error. */
20
35
  writeKey: string;
36
+ /**
37
+ * Required. An http(s) URL with a host. Trimmed, and trailing slashes are
38
+ * removed. Cleartext http logs a warning unless the host is loopback.
39
+ */
21
40
  ingestionHost: string;
41
+ /** Seconds between automatic flushes (default: 10). Clamped to >= 1. */
22
42
  flushIntervalSeconds?: number;
23
43
  debug?: boolean;
24
44
  /** Max events held in the in-memory queue (default: 2000). Clamped to >= 1. */
25
45
  maxQueueEvents?: number;
26
46
  /**
27
47
  * Max events stored on disk for crash-safety + extended offline periods
28
- * (default: 10000). Must be >= 0. When set to 0, disk persistence is
48
+ * (default: 10000). Negative values are clamped to 0. When set to 0, disk persistence is
29
49
  * disabled and the SDK runs as a pure in-memory pipeline (events are lost
30
50
  * on app kill — documented tradeoff).
31
51
  */
32
52
  maxDiskEvents?: number;
53
+ /**
54
+ * Emit Application Opened/Backgrounded/Installed/Updated events.
55
+ * Defaults to false (opt-in). Matches iOS/Android parity — existing
56
+ * customers upgrading the SDK do not begin emitting lifecycle events
57
+ * until they explicitly set this to true.
58
+ */
59
+ trackLifecycleEvents?: boolean;
60
+ /**
61
+ * Called synchronously by `createAnalyticsClient` when the options are
62
+ * invalid in a release build, after the error is logged. The SDK is inert
63
+ * for the session; a later `createAnalyticsClient` with valid options, or
64
+ * `reset()`, recovers it. Development builds throw from
65
+ * `createAnalyticsClient` instead and never call this. Not called for
66
+ * 401/403/404 responses from the ingestion host.
67
+ */
68
+ onConfigError?: (error: ConfigError) => void;
33
69
  }
34
70
  export interface AnalyticsInterface {
35
71
  track: (event: string, props?: Record<string, any>) => void;
@@ -38,6 +74,19 @@ export interface AnalyticsInterface {
38
74
  screen: (name: string, props?: Record<string, any>) => void;
39
75
  page: (name: string, props?: Record<string, any>) => void;
40
76
  alias: (newUserId: string) => void;
77
+ /**
78
+ * Forward a URL the host received from `Linking` (or platform-specific
79
+ * URL handlers) so it is attached to the next `Application Opened`
80
+ * event. The SDK does not read `Linking` itself, so only URLs passed
81
+ * here are recorded — sanitize before forwarding. One-shot — buffer is
82
+ * cleared on emit; last-write-wins if called multiple times before the
83
+ * next Opened. Safe to call right after createAnalyticsClient(): a URL
84
+ * forwarded while initialization is running still reaches the
85
+ * cold-launch Opened.
86
+ *
87
+ * No-op with an always-on warning when `trackLifecycleEvents` is disabled.
88
+ */
89
+ recordOpenedURL: (url: string, sourceApplication?: string) => void;
41
90
  setAdvertisingId: (advertisingId: string) => Promise<void>;
42
91
  clearAdvertisingId: () => Promise<void>;
43
92
  setTracing: (enabled: boolean) => void;
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,UAAU,GACV,OAAO,GACP,QAAQ,GACR,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IAC5D,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IACjE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IAC/D,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IAC5D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IAC1D,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,gBAAgB,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,kBAAkB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACjD,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE;QACH,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,MAAM,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,EAAE,EAAE;QACF,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,OAAO,CAAC;KACf,CAAC;IACF,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,cAAc,GACd,OAAO,GACP,WAAW,GACX,UAAU,CAAC"}
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Snapshot of the host app's identity (name, version, build, bundle id).
3
+ * Read once at SDK init and reused across every event — both as the `app:`
4
+ * block on the EventContext and as version/build properties on lifecycle
5
+ * events. Mirrors the iOS `AppContext` so a single source of truth flows
6
+ * through the same places on both platforms.
7
+ */
8
+ export interface AppContext {
9
+ name: string;
10
+ version: string;
11
+ build: string;
12
+ namespace: string;
13
+ }
14
+ /**
15
+ * Reads the current app identity from `react-native-device-info`. Falls back
16
+ * to package.json version + 'unknown' for everything else if the native
17
+ * module is missing (e.g. unit tests, Expo Go without the dev client).
18
+ */
19
+ export declare function loadAppContext(): AppContext;
20
+ //# sourceMappingURL=appContext.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"appContext.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/appContext.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAO3C"}
@@ -0,0 +1,22 @@
1
+ import pkg from '../../../package.json';
2
+ let DeviceInfo = null;
3
+ try {
4
+ DeviceInfo = require('react-native-device-info');
5
+ }
6
+ catch {
7
+ DeviceInfo = null;
8
+ }
9
+ /**
10
+ * Reads the current app identity from `react-native-device-info`. Falls back
11
+ * to package.json version + 'unknown' for everything else if the native
12
+ * module is missing (e.g. unit tests, Expo Go without the dev client).
13
+ */
14
+ export function loadAppContext() {
15
+ var _a, _b, _c, _d, _e, _f, _g, _h, _j;
16
+ return {
17
+ name: (_b = (_a = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getApplicationName) === null || _a === void 0 ? void 0 : _a.call(DeviceInfo)) !== null && _b !== void 0 ? _b : 'unknown',
18
+ version: (_e = (_d = (_c = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getVersion) === null || _c === void 0 ? void 0 : _c.call(DeviceInfo)) !== null && _d !== void 0 ? _d : pkg.version) !== null && _e !== void 0 ? _e : 'unknown',
19
+ build: (_g = (_f = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getBuildNumber) === null || _f === void 0 ? void 0 : _f.call(DeviceInfo)) !== null && _g !== void 0 ? _g : 'unknown',
20
+ namespace: (_j = (_h = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getBundleId) === null || _h === void 0 ? void 0 : _h.call(DeviceInfo)) !== null && _j !== void 0 ? _j : 'unknown',
21
+ };
22
+ }
@@ -1,4 +1,5 @@
1
1
  import { EventContext } from '../types';
2
+ import { AppContext } from './appContext';
2
3
  /**
3
4
  * Clears the cached context information, forcing a refresh on the next getContextInfo call.
4
5
  */
@@ -6,13 +7,16 @@ export declare function clearContextCache(): void;
6
7
  /**
7
8
  * Gathers and caches device, app, and environment context information for analytics events.
8
9
  *
9
- * - Collects details such as app name/version, device model/type, OS, screen size, locale, timezone, and network status.
10
- * - Uses `react-native-device-info` and the current environment to populate fields.
10
+ * - Collects details such as device model/type, OS, screen size, locale, timezone, and network status.
11
+ * - Uses `react-native-device-info` and the current environment to populate device/os fields.
12
+ * - Reuses the caller-provided AppContext for the `app:` block so version/build
13
+ * are sourced from the same snapshot used by lifecycle events.
11
14
  * - Caches the result for the lifetime of the app to avoid redundant async calls.
12
15
  * - Returns a context object suitable for event enrichment.
13
16
  *
17
+ * @param appContext - The host app identity snapshot (name, version, build, namespace).
14
18
  * @param advertisingId - Optional advertising identifier (IDFA on iOS, GAID on Android) for ad tracking and attribution.
15
19
  * @returns {Promise<EventContext>} A promise that resolves to the context information object.
16
20
  */
17
- export declare function getContextInfo(advertisingId?: string): Promise<EventContext>;
21
+ export declare function getContextInfo(appContext: AppContext, advertisingId?: string): Promise<EventContext>;
18
22
  //# sourceMappingURL=contextInfo.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"contextInfo.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/contextInfo.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAYxC;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,YAAY,CAAC,CA+DvB"}
1
+ {"version":3,"file":"contextInfo.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/contextInfo.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAY1C;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,UAAU,EACtB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,YAAY,CAAC,CA+DvB"}
@@ -20,16 +20,19 @@ export function clearContextCache() {
20
20
  /**
21
21
  * Gathers and caches device, app, and environment context information for analytics events.
22
22
  *
23
- * - Collects details such as app name/version, device model/type, OS, screen size, locale, timezone, and network status.
24
- * - Uses `react-native-device-info` and the current environment to populate fields.
23
+ * - Collects details such as device model/type, OS, screen size, locale, timezone, and network status.
24
+ * - Uses `react-native-device-info` and the current environment to populate device/os fields.
25
+ * - Reuses the caller-provided AppContext for the `app:` block so version/build
26
+ * are sourced from the same snapshot used by lifecycle events.
25
27
  * - Caches the result for the lifetime of the app to avoid redundant async calls.
26
28
  * - Returns a context object suitable for event enrichment.
27
29
  *
30
+ * @param appContext - The host app identity snapshot (name, version, build, namespace).
28
31
  * @param advertisingId - Optional advertising identifier (IDFA on iOS, GAID on Android) for ad tracking and attribution.
29
32
  * @returns {Promise<EventContext>} A promise that resolves to the context information object.
30
33
  */
31
- export async function getContextInfo(advertisingId) {
32
- var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1;
34
+ export async function getContextInfo(appContext, advertisingId) {
35
+ var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
33
36
  // Return cached context only if it exists AND the advertising ID hasn't changed
34
37
  if (cachedContext && cachedAdvertisingId === advertisingId)
35
38
  return cachedContext;
@@ -64,10 +67,10 @@ export async function getContextInfo(advertisingId) {
64
67
  version: (_q = (_p = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getSystemVersion) === null || _p === void 0 ? void 0 : _p.call(DeviceInfo)) !== null && _q !== void 0 ? _q : 'unknown',
65
68
  },
66
69
  app: {
67
- name: (_s = (_r = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getApplicationName) === null || _r === void 0 ? void 0 : _r.call(DeviceInfo)) !== null && _s !== void 0 ? _s : 'unknown',
68
- version: (_v = (_u = (_t = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getVersion) === null || _t === void 0 ? void 0 : _t.call(DeviceInfo)) !== null && _u !== void 0 ? _u : pkg.version) !== null && _v !== void 0 ? _v : 'unknown',
69
- build: (_x = (_w = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getBuildNumber) === null || _w === void 0 ? void 0 : _w.call(DeviceInfo)) !== null && _x !== void 0 ? _x : 'unknown',
70
- namespace: (_z = (_y = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.getBundleId) === null || _y === void 0 ? void 0 : _y.call(DeviceInfo)) !== null && _z !== void 0 ? _z : 'unknown',
70
+ name: appContext.name,
71
+ version: appContext.version,
72
+ build: appContext.build,
73
+ namespace: appContext.namespace,
71
74
  },
72
75
  screen: {
73
76
  width: Math.round(width),
@@ -77,7 +80,7 @@ export async function getContextInfo(advertisingId) {
77
80
  ...(Platform.OS === 'android'
78
81
  ? {
79
82
  network: {
80
- wifi: (_1 = (await ((_0 = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.isWifiEnabled) === null || _0 === void 0 ? void 0 : _0.call(DeviceInfo)))) !== null && _1 !== void 0 ? _1 : false,
83
+ wifi: (_s = (await ((_r = DeviceInfo === null || DeviceInfo === void 0 ? void 0 : DeviceInfo.isWifiEnabled) === null || _r === void 0 ? void 0 : _r.call(DeviceInfo)))) !== null && _s !== void 0 ? _s : false,
81
84
  },
82
85
  }
83
86
  : {}),
@@ -0,0 +1,22 @@
1
+ import type { ConfigError, InitOptions } from '../types';
2
+ export interface ValidatedInitOptions {
3
+ /** Normalized copy: trimmed key/host, trailing slashes removed, numbers clamped. */
4
+ options: InitOptions;
5
+ /** First error found (writeKey before host), or null when valid. */
6
+ configError: ConfigError | null;
7
+ }
8
+ /** True for localhost / 127.0.0.1 / ::1 (IPv6 brackets stripped), exact match. */
9
+ export declare function isLoopbackHost(host: string): boolean;
10
+ /**
11
+ * Single validation funnel, run once per `createAnalyticsClient` call — the
12
+ * equivalent of the native InitOptions constructor. Never throws: records the
13
+ * first error and clamps every numeric bound with a warning (one policy for
14
+ * all fields, matching iOS and Android). Warnings are logged here and nowhere
15
+ * else, so they appear once per call.
16
+ */
17
+ export declare function validateInitOptions(raw: InitOptions, opts?: {
18
+ logWarnings?: boolean;
19
+ }): ValidatedInitOptions;
20
+ export declare const DEFAULT_MAX_QUEUE_EVENTS = 2000;
21
+ export declare const DEFAULT_MAX_DISK_EVENTS = 10000;
22
+ //# sourceMappingURL=initOptions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"initOptions.d.ts","sourceRoot":"","sources":["../../../src/analytics/utils/initOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAsBzD,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,OAAO,EAAE,WAAW,CAAC;IACrB,oEAAoE;IACpE,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAYD,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIpD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACnC,oBAAoB,CA2EtB;AAED,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,uBAAuB,QAAS,CAAC"}