@lemuai/analytics 0.0.0-stage → 1.1.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/dist/core.d.ts ADDED
@@ -0,0 +1,333 @@
1
+ /** Wire types for Lemu tracking protocol v1 (see sdks/spec/protocol.md). */
2
+ type Platform = "web" | "ios" | "android" | "flutter" | "react_native" | "shopify" | "server";
3
+ type MessageType = "page" | "screen" | "track" | "identify";
4
+ type Properties = Record<string, unknown>;
5
+ interface Campaign {
6
+ source?: string;
7
+ medium?: string;
8
+ campaign?: string;
9
+ term?: string;
10
+ content?: string;
11
+ gclid?: string;
12
+ fbclid?: string;
13
+ /** Set by Lemu message links (le2.in): which person the link was sent to. */
14
+ lmclid?: string;
15
+ }
16
+ interface Context {
17
+ platform: Platform;
18
+ library: {
19
+ name: string;
20
+ version: string;
21
+ };
22
+ app?: {
23
+ name?: string;
24
+ version?: string;
25
+ build?: string;
26
+ namespace?: string;
27
+ };
28
+ device?: {
29
+ manufacturer?: string;
30
+ model?: string;
31
+ type?: "phone" | "tablet" | "desktop" | "tv" | "other";
32
+ };
33
+ os?: {
34
+ name?: string;
35
+ version?: string;
36
+ };
37
+ screen?: {
38
+ width?: number;
39
+ height?: number;
40
+ density?: number;
41
+ };
42
+ locale?: string;
43
+ timezone?: string;
44
+ userAgent?: string;
45
+ campaign?: Campaign;
46
+ page?: {
47
+ url?: string;
48
+ path?: string;
49
+ title?: string;
50
+ referrer?: string;
51
+ };
52
+ [key: string]: unknown;
53
+ }
54
+ interface Message {
55
+ type: MessageType;
56
+ messageId: string;
57
+ anonymousId?: string;
58
+ timestamp: string;
59
+ context: Context;
60
+ userId?: string;
61
+ event?: string;
62
+ name?: string;
63
+ properties?: Properties;
64
+ traits?: Properties;
65
+ }
66
+ interface BatchBody {
67
+ writeKey: string;
68
+ sentAt: string;
69
+ batch: Message[];
70
+ }
71
+ /** One line item of a purchase, as Meta defines `contents`. */
72
+ interface PurchaseContent {
73
+ id: string;
74
+ quantity: number;
75
+ item_price?: number;
76
+ title?: string;
77
+ brand?: string;
78
+ category?: string;
79
+ [key: string]: unknown;
80
+ }
81
+ interface PurchaseProperties {
82
+ /** Order total in major units (1499.5 means Rs 1,499.50). */
83
+ value: number;
84
+ /** ISO 4217 code, for example "INR". */
85
+ currency: string;
86
+ /** Your order id. Lets Lemu count one conversion per order however many sources report it. */
87
+ order_id: string;
88
+ contents?: PurchaseContent[];
89
+ content_ids?: string[];
90
+ num_items?: number;
91
+ [key: string]: unknown;
92
+ }
93
+ /** Options every SDK accepts in `init`. */
94
+ interface LemuOptions {
95
+ /** Collection host. Defaults to https://app.lemuai.com (the snippet uses the host it was loaded from). */
96
+ apiHost?: string;
97
+ /** Log every call, request and response to the console. */
98
+ debug?: boolean;
99
+ /** Hold events in memory and write nothing to storage until `setConsent(true)`. */
100
+ requireConsent?: boolean;
101
+ /** Send when this many messages are queued. Web 10, apps 20. */
102
+ flushAt?: number;
103
+ /** Send queued messages after this many milliseconds. Web 1000, apps 30000. */
104
+ flushInterval?: number;
105
+ /** Most messages kept in the queue. Default 1000. */
106
+ maxQueueSize?: number;
107
+ /** Apps: send app_installed, app_updated, app_opened and app_backgrounded. Default true. */
108
+ trackLifecycle?: boolean;
109
+ /** Apps: send deep_link_opened and copy UTM parameters from links. Default true. */
110
+ trackDeepLinks?: boolean;
111
+ /** Web snippet: load experiences and landing page forms (onsite.js) when the site has any live. Default true. */
112
+ onsite?: boolean;
113
+ }
114
+ type MaybePromise<T> = T | Promise<T>;
115
+ /** Key-value storage. Synchronous (browser) or asynchronous (AsyncStorage). */
116
+ interface StorageAdapter {
117
+ get(key: string): MaybePromise<string | null | undefined>;
118
+ set(key: string, value: string): MaybePromise<void>;
119
+ remove(key: string): MaybePromise<void>;
120
+ }
121
+ interface TransportRequest {
122
+ url: string;
123
+ body: string;
124
+ }
125
+ /**
126
+ * Sends one batch. Resolves with the HTTP status (anything that is not a
127
+ * positive number counts as delivered), rejects on a network error. A
128
+ * rejection whose `timeout` property is true means the request may have
129
+ * reached the server.
130
+ */
131
+ interface TransportAdapter {
132
+ send(request: TransportRequest): Promise<number | undefined | void>;
133
+ /** Fire and forget, used when the page or app is going away. Returns false when it could not queue the request. */
134
+ beacon?(request: TransportRequest): boolean;
135
+ }
136
+ /** Context fields the platform knows. `platform` and `library` are added by the client. */
137
+ type ContextAdapter = () => Partial<Context>;
138
+ interface LifecycleHandlers {
139
+ foreground(): void;
140
+ background(): void;
141
+ }
142
+ /** Tells the client when the page or app goes to the background and comes back. */
143
+ interface LifecycleAdapter {
144
+ subscribe(handlers: LifecycleHandlers): (() => void) | void;
145
+ }
146
+ interface Adapters {
147
+ platform: Platform;
148
+ library: {
149
+ name: string;
150
+ version: string;
151
+ };
152
+ storage: StorageAdapter;
153
+ transport: TransportAdapter;
154
+ context: ContextAdapter;
155
+ lifecycle?: LifecycleAdapter;
156
+ /** Platform defaults for options the caller leaves out. */
157
+ defaults?: LemuOptions;
158
+ /** Keep the queue in storage so it survives restarts (apps). */
159
+ persistQueue?: boolean;
160
+ /** Extra storage keys to read at start; available through `stored(key)`. */
161
+ extraKeys?: string[];
162
+ }
163
+
164
+ declare const DEFAULT_API_HOST = "https://app.lemuai.com";
165
+ declare const BATCH_PATH = "/api/v1/pixel/batch";
166
+ /** Storage keys. The browser keeps `_lemu_aid` and `_lemu_optout` in a cookie too. */
167
+ declare const KEYS: {
168
+ anonymousId: string;
169
+ userId: string;
170
+ optOut: string;
171
+ queue: string;
172
+ /** "1" once consent was granted; remembered like the other SDKs do. */
173
+ consent: string;
174
+ };
175
+ /**
176
+ * The platform-agnostic client: queue, batching, retry with backoff, consent,
177
+ * opt-out and identity. Platforms plug in storage, transport, context and
178
+ * lifecycle. No method throws into the host app.
179
+ */
180
+ declare class LemuClient<O extends LemuOptions = LemuOptions> {
181
+ protected a: Adapters;
182
+ protected o: O;
183
+ protected writeKey: string;
184
+ protected host: string;
185
+ protected campaign: Campaign;
186
+ private inited;
187
+ private loaded;
188
+ private calls;
189
+ private values;
190
+ private aid;
191
+ private uid;
192
+ private consent;
193
+ private out;
194
+ private queue;
195
+ private flying;
196
+ /** Requests in flight, so `flush()` can wait for ones an earlier call started. */
197
+ private posts;
198
+ private held;
199
+ /** Storage writes waiting for consent. `null` once consent is given. */
200
+ private writes;
201
+ private timer;
202
+ private retryAt;
203
+ private failures;
204
+ private seq;
205
+ private persisting;
206
+ private unsubscribe;
207
+ private closed;
208
+ constructor(adapters: Adapters);
209
+ /** Starts the client. Calls made before `init` are kept and run after it. */
210
+ init(writeKey: string, options?: O): void;
211
+ track(event: string, properties?: Properties): void;
212
+ page(name?: string | Properties, properties?: Properties): void;
213
+ screen(name: string, properties?: Properties): void;
214
+ /** Sets the user's id (kept until `reset()`) and sends their traits. `identify(traits)` works too. */
215
+ identify(userId?: string | number | null | Properties, traits?: Properties): void;
216
+ /** Sends a `Purchase` event at once. `value`, `currency` and `order_id` are required. */
217
+ purchase(purchase: PurchaseProperties): void;
218
+ /** On logout: a new anonymous id, and the user id is cleared. */
219
+ reset(): void;
220
+ /** Sends everything queued now. Resolves when the requests have finished. */
221
+ flush(): Promise<void>;
222
+ /** With `requireConsent`, starts sending (true) or discards held events and stops (false). */
223
+ setConsent(granted: boolean): void;
224
+ /** Stops all tracking and clears the queue. Remembered across launches. */
225
+ optOut(): void;
226
+ optIn(): void;
227
+ /** The visitor's anonymous id, or null before consent, after opt-out, or before the client has loaded. */
228
+ anonymousId(): string | null;
229
+ userId(): string | null;
230
+ /** Resolves once storage has loaded and calls made before that have run. */
231
+ ready(): Promise<void>;
232
+ /** Stops timers and listeners. Queued messages stay in storage (apps). */
233
+ shutdown(): void;
234
+ /** Called once storage has loaded, before calls made earlier run. */
235
+ protected started(): void;
236
+ protected onForeground(): void;
237
+ protected onBackground(): void;
238
+ /** A value read from storage at start (keys from `adapters.extraKeys`). */
239
+ protected stored(key: string): string | null | undefined;
240
+ /** Writes to storage, or holds the write until consent. */
241
+ protected store(key: string, value: string | null): void;
242
+ protected setCampaign(campaign: Campaign): void;
243
+ protected options(): O;
244
+ /** Runs `fn` now if the client has started, otherwise after it does. Never throws. */
245
+ protected when(fn: () => void, otherwise?: () => void): void;
246
+ protected safe<T>(fn: () => T): T | undefined;
247
+ protected log(...args: unknown[]): void;
248
+ /** Sends what is queued. `beacon` uses the transport's fire-and-forget path when it has one. */
249
+ protected sendNow(beacon: boolean): Promise<void>;
250
+ private load;
251
+ private restore;
252
+ private ensureId;
253
+ private props;
254
+ private context;
255
+ private send;
256
+ private push;
257
+ /** Over the limit: drop the oldest message that isn't a Purchase. */
258
+ private trim;
259
+ private schedule;
260
+ private url;
261
+ private body;
262
+ private post;
263
+ private settle;
264
+ private retry;
265
+ /** Apps: write the queue (including requests in flight) to storage, at most once per tick. */
266
+ private persist;
267
+ private write;
268
+ }
269
+
270
+ /**
271
+ * Event names every Lemu SDK exposes, copied from sdks/spec/events.json
272
+ * (test/events.test.ts checks they match). Standard events use Meta's names
273
+ * exactly, so the same name works for the Meta pixel and for Lemu.
274
+ */
275
+ declare const LemuEvent: {
276
+ readonly PageView: "PageView";
277
+ readonly ViewContent: "ViewContent";
278
+ readonly Search: "Search";
279
+ readonly AddToCart: "AddToCart";
280
+ readonly AddToWishlist: "AddToWishlist";
281
+ readonly InitiateCheckout: "InitiateCheckout";
282
+ readonly AddPaymentInfo: "AddPaymentInfo";
283
+ readonly Purchase: "Purchase";
284
+ readonly Lead: "Lead";
285
+ readonly CompleteRegistration: "CompleteRegistration";
286
+ readonly Subscribe: "Subscribe";
287
+ readonly StartTrial: "StartTrial";
288
+ readonly Schedule: "Schedule";
289
+ readonly SubmitApplication: "SubmitApplication";
290
+ readonly Contact: "Contact";
291
+ readonly CustomizeProduct: "CustomizeProduct";
292
+ readonly Donate: "Donate";
293
+ readonly FindLocation: "FindLocation";
294
+ readonly AppInstalled: "app_installed";
295
+ readonly AppUpdated: "app_updated";
296
+ readonly AppOpened: "app_opened";
297
+ readonly AppBackgrounded: "app_backgrounded";
298
+ readonly DeepLinkOpened: "deep_link_opened";
299
+ readonly ScreenViewed: "screen_viewed";
300
+ };
301
+ type LemuEventName = (typeof LemuEvent)[keyof typeof LemuEvent];
302
+
303
+ type FetchLike = (url: string, init: Record<string, unknown>) => Promise<{
304
+ status: number;
305
+ } | undefined | void>;
306
+ interface FetchTransportOptions {
307
+ /** Headers on every request, for example Content-Type and User-Agent. */
308
+ headers?: Record<string, string>;
309
+ /** Abort a request after this many milliseconds. Default 10000. */
310
+ timeout?: number;
311
+ /** Extra fetch options (keepalive, credentials). */
312
+ init?: Record<string, unknown>;
313
+ /** The fetch function. Defaults to the global one. */
314
+ fetch?: FetchLike;
315
+ }
316
+ /** A transport over `fetch`. A timed-out request rejects with `{ timeout: true }`. */
317
+ declare function fetchTransport(options?: FetchTransportOptions): TransportAdapter;
318
+
319
+ /** Storage that lives only as long as the process. Useful for servers and tests. */
320
+ declare function memoryStorage(initial?: Record<string, string>): StorageAdapter & {
321
+ data: Record<string, string>;
322
+ };
323
+
324
+ /** UUID v4. Uses the platform's crypto when there is one. */
325
+ declare function uuid(): string;
326
+ /** UTM parameters (without `utm_`) plus gclid, fbclid and lmclid (a Lemu
327
+ * message link: which person the link was sent to) from a URL or query string. */
328
+ declare function parseCampaign(url: string | null | undefined): Campaign;
329
+
330
+ /** Kept in step with package.json (test/version.test.ts checks). */
331
+ declare const VERSION = "1.1.0";
332
+
333
+ export { type Adapters, BATCH_PATH, type BatchBody, type Campaign, type Context, type ContextAdapter, DEFAULT_API_HOST, type FetchTransportOptions, KEYS, LemuClient, LemuEvent, type LemuEventName, type LemuOptions, type LifecycleAdapter, type LifecycleHandlers, type Message, type MessageType, type Platform, type Properties, type PurchaseContent, type PurchaseProperties, type StorageAdapter, type TransportAdapter, type TransportRequest, VERSION, fetchTransport, memoryStorage, parseCampaign, uuid };
package/dist/core.js ADDED
@@ -0,0 +1,3 @@
1
+ export { BATCH_PATH, DEFAULT_API_HOST, KEYS, LemuClient, LemuEvent, VERSION, fetchTransport, memoryStorage, parseCampaign, uuid } from './chunk-2J55PE4P.js';
2
+ //# sourceMappingURL=core.js.map
3
+ //# sourceMappingURL=core.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"names":[],"mappings":"","file":"core.js"}