@kissmyappss/react-native 0.0.0-stage → 1.0.0

package/lib/client.js

@@ -0,0 +1,511 @@
+"use strict";
+// The KissMyApps app client, with no React Native in it: the app's storage, device and
+// network come in through `Environment`, so the same code runs in tests and in Node.
+// The Android and iOS SDKs follow the same rules; see integrations/analytics-mobile.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KmaClient = exports.EVENT_NAME = exports.DEFAULT_ENDPOINT = exports.SDK_VERSION = void 0;
+exports.uuid = uuid;
+exports.SDK_VERSION = '1.0.0';
+exports.DEFAULT_ENDPOINT = 'https://events.kissmyapps.dev';
+exports.EVENT_NAME = /^[A-Za-z][A-Za-z0-9_.:-]{0,79}$/;
+const KEY = /^kma_pk_(live|test)_[A-Za-z0-9]{20,64}$/;
+const BATCH_SIZE = 50;
+const FLUSH_AT = 30;
+const HEARTBEAT_MS = 60000;
+const MAX_PROPERTIES_BYTES = 32000;
+function uuid() {
+    // Hermes has no crypto.randomUUID; a polyfill may add it.
+    const random = globalThis.crypto;
+    if (random === null || random === void 0 ? void 0 : random.randomUUID)
+        return random.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+class KmaClient {
+    constructor(options, env) {
+        var _a, _b;
+        this.queue = [];
+        this.screenName = null;
+        this.foregroundAt = 0;
+        this.loaded = false;
+        this.waiting = [];
+        this.flushTimer = null;
+        this.heartbeatTimer = null;
+        this.saveTimer = null;
+        this.inflight = null;
+        this.failures = 0;
+        this.lastSent = 0;
+        this.identityPending = false;
+        this.inForeground = false;
+        this.firstLaunch = false;
+        this.stopped = false;
+        if (!KEY.test((_a = options.key) !== null && _a !== void 0 ? _a : '')) {
+            throw new Error('KissMyApps: init needs a client key that starts with kma_pk_');
+        }
+        this.options = {
+            ...options,
+            endpoint: ((_b = options.endpoint) !== null && _b !== void 0 ? _b : exports.DEFAULT_ENDPOINT).replace(/\/+$/, ''),
+        };
+        this.env = env;
+        this.storageKey = `kma:${options.key.slice(-8)}`;
+        this.state = {
+            anonymousId: uuid(),
+            userId: null,
+            traits: null,
+            session: null,
+            optedOut: false,
+        };
+        this.ready = this.load();
+    }
+    // Public API ---------------------------------------------------------------------------
+    /** Records something a person did. */
+    track(name, properties = {}) {
+        this.whenLoaded(() => {
+            if (this.stopped || this.state.optedOut)
+                return;
+            if (!exports.EVENT_NAME.test(name)) {
+                this.warn(`"${name}" is not a valid event name: use letters, numbers and _ . : - (up to 80).`);
+                return;
+            }
+            this.enqueue(name, properties, this.ensureSession());
+        });
+    }
+    /** Records a screen view; later events carry the screen's name. */
+    screen(name, properties = {}) {
+        const screen = String(name !== null && name !== void 0 ? name : '')
+            .trim()
+            .slice(0, 300);
+        if (!screen)
+            return this.warn('screen needs a name.');
+        this.whenLoaded(() => {
+            if (this.stopped || this.state.optedOut)
+                return;
+            const previous = this.screenName;
+            this.screenName = screen;
+            const session = this.ensureSession();
+            if (!session.firstScreen) {
+                session.firstScreen = screen;
+                this.save();
+            }
+            this.enqueue('screen_viewed', { name: screen, ...(previous ? { previous } : {}), ...properties }, session);
+        });
+    }
+    /** Ties this install to your own user ID, with optional traits such as email, name or plan. */
+    identify(userId, traits) {
+        const id = String(userId !== null && userId !== void 0 ? userId : '').trim();
+        if (!id || id.length > 200)
+            return this.warn('identify needs a user ID of 1 to 200 characters.');
+        this.whenLoaded(() => {
+            var _a;
+            this.state.userId = id;
+            if (traits)
+                this.state.traits = { ...((_a = this.state.traits) !== null && _a !== void 0 ? _a : {}), ...this.clean(traits) };
+            this.identityPending = true;
+            this.save();
+            this.scheduleFlush(0);
+        });
+    }
+    /** Updates traits for the current person without changing who they are. */
+    setTraits(traits) {
+        this.whenLoaded(() => {
+            var _a;
+            this.state.traits = { ...((_a = this.state.traits) !== null && _a !== void 0 ? _a : {}), ...this.clean(traits) };
+            this.identityPending = true;
+            this.save();
+            this.scheduleFlush(0);
+        });
+    }
+    /** Forgets the user, for example on sign out: what follows is a new person and session. */
+    reset() {
+        this.whenLoaded(() => {
+            void this.flush();
+            this.state.userId = null;
+            this.state.traits = null;
+            this.identityPending = false;
+            this.state.anonymousId = uuid();
+            this.state.session = null;
+            this.save();
+            if (this.inForeground)
+                this.ensureSession();
+        });
+    }
+    /** Stops recording and drops anything not sent yet, until optIn. Remembered across launches. */
+    optOut() {
+        this.whenLoaded(() => {
+            this.state.optedOut = true;
+            this.queue = [];
+            this.save();
+        });
+    }
+    optIn() {
+        this.whenLoaded(() => {
+            this.state.optedOut = false;
+            this.save();
+        });
+    }
+    getAnonymousId() {
+        return this.state.anonymousId;
+    }
+    getUserId() {
+        return this.state.userId;
+    }
+    getSessionId() {
+        var _a, _b;
+        return (_b = (_a = this.state.session) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : null;
+    }
+    /** Sends everything queued now. */
+    flush() {
+        if (!this.loaded)
+            return this.ready.then(() => this.flush());
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.sendQueued().finally(() => {
+            this.inflight = null;
+        });
+        return this.inflight;
+    }
+    /** Stops timers; the client records nothing more. */
+    shutdown() {
+        this.stopped = true;
+        this.inForeground = false;
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            void this.writeNow();
+        }
+    }
+    // App lifecycle, called by the platform layer ------------------------------------------
+    /** The app came to the front. The first call is the launch. */
+    foreground() {
+        this.whenLoaded(() => {
+            var _a;
+            if (this.stopped || this.inForeground)
+                return;
+            const launch = this.foregroundAt === 0;
+            this.inForeground = true;
+            this.foregroundAt = this.now();
+            if (this.state.optedOut)
+                return;
+            const session = this.ensureSession();
+            if (this.options.trackLifecycle !== false) {
+                if (launch)
+                    this.recordInstallOrUpdate(session);
+                this.enqueue('app_opened', { from_background: !launch }, session);
+            }
+            (_a = this.heartbeatTimer) !== null && _a !== void 0 ? _a : (this.heartbeatTimer = setInterval(() => this.heartbeat(), HEARTBEAT_MS));
+        });
+    }
+    /** The app went to the background: record it and send what is queued while it can. */
+    background() {
+        this.whenLoaded(() => {
+            if (this.stopped || !this.inForeground)
+                return;
+            this.inForeground = false;
+            if (this.heartbeatTimer)
+                clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+            if (this.state.optedOut)
+                return;
+            const session = this.state.session;
+            if (session && this.options.trackLifecycle !== false) {
+                const seconds = Math.round((this.now() - this.foregroundAt) / 1000);
+                this.enqueue('app_backgrounded', { seconds_in_foreground: Math.max(0, seconds) }, session);
+            }
+            if (session)
+                session.last = this.now();
+            void this.writeNow();
+            void this.flush();
+        });
+    }
+    // State --------------------------------------------------------------------------------
+    async load() {
+        var _a, _b, _c;
+        const storage = this.env.storage;
+        if (!storage)
+            this.warn('No storage was given, so each launch counts as a new install.');
+        let saved = null;
+        let queue = [];
+        try {
+            const raw = await (storage === null || storage === void 0 ? void 0 : storage.getItem(this.storageKey));
+            saved = raw ? JSON.parse(raw) : null;
+            const rawQueue = await (storage === null || storage === void 0 ? void 0 : storage.getItem(`${this.storageKey}:queue`));
+            queue = rawQueue ? JSON.parse(rawQueue) : [];
+        }
+        catch {
+            saved = null;
+        }
+        if (saved === null || saved === void 0 ? void 0 : saved.anonymousId) {
+            this.state = {
+                anonymousId: saved.anonymousId,
+                userId: (_a = saved.userId) !== null && _a !== void 0 ? _a : null,
+                traits: (_b = saved.traits) !== null && _b !== void 0 ? _b : null,
+                session: (_c = saved.session) !== null && _c !== void 0 ? _c : null,
+                optedOut: saved.optedOut === true,
+                version: saved.version,
+                build: saved.build,
+            };
+        }
+        // Nothing saved means a first launch, or the app's data was cleared.
+        this.firstLaunch = !(saved === null || saved === void 0 ? void 0 : saved.anonymousId);
+        this.queue = Array.isArray(queue) ? queue : [];
+        this.identityPending = Boolean(this.state.traits);
+        this.loaded = true;
+        // What an earlier launch could not send goes now.
+        if (this.queue.length)
+            this.scheduleFlush(0);
+        for (const run of this.waiting.splice(0))
+            run();
+    }
+    whenLoaded(run) {
+        if (this.loaded)
+            run();
+        else
+            this.waiting.push(run);
+    }
+    recordInstallOrUpdate(session) {
+        const version = this.options.appVersion;
+        const build = this.options.build;
+        if (this.firstLaunch) {
+            this.enqueue('app_installed', this.clean({ version, build }), session);
+        }
+        else if ((version && this.state.version && version !== this.state.version) ||
+            (build && this.state.build && build !== this.state.build)) {
+            this.enqueue('app_updated', this.clean({
+                version,
+                build,
+                previous_version: this.state.version,
+                previous_build: this.state.build,
+            }), session);
+        }
+        this.firstLaunch = false;
+        this.state.version = version !== null && version !== void 0 ? version : this.state.version;
+        this.state.build = build !== null && build !== void 0 ? build : this.state.build;
+        this.save();
+    }
+    save() {
+        if (this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            void this.writeNow();
+        }, 250);
+    }
+    async writeNow() {
+        var _a, _b;
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        try {
+            await ((_a = this.env.storage) === null || _a === void 0 ? void 0 : _a.setItem(this.storageKey, JSON.stringify(this.state)));
+            await ((_b = this.env.storage) === null || _b === void 0 ? void 0 : _b.setItem(`${this.storageKey}:queue`, JSON.stringify(this.queue)));
+        }
+        catch {
+            // Storage full or failing: the client keeps working in memory.
+        }
+    }
+    // Sessions and events -------------------------------------------------------------------
+    now() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.env).now) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Date.now();
+    }
+    ensureSession() {
+        var _a, _b;
+        const now = this.now();
+        const timeout = ((_a = this.options.sessionTimeoutMinutes) !== null && _a !== void 0 ? _a : 30) * 60000;
+        let session = this.state.session;
+        if (!session || now - session.last > timeout) {
+            session = { id: uuid(), started: now, last: now, firstScreen: (_b = this.screenName) !== null && _b !== void 0 ? _b : undefined };
+            this.state.session = session;
+            this.enqueue('session_started', {}, session);
+        }
+        else {
+            session.last = now;
+        }
+        return session;
+    }
+    enqueue(name, properties, session) {
+        var _a, _b, _c;
+        this.queue.push({
+            name,
+            insert_id: uuid(),
+            time: new Date(this.now()).toISOString(),
+            screen: (_a = this.screenName) !== null && _a !== void 0 ? _a : undefined,
+            properties: this.clean(properties),
+            user_id: this.state.userId,
+            anonymous_id: this.state.anonymousId,
+            session_id: session.id,
+            session_started_at: new Date(session.started).toISOString(),
+        });
+        const max = (_b = this.options.maxQueue) !== null && _b !== void 0 ? _b : 1000;
+        if (this.queue.length > max)
+            this.queue.splice(0, this.queue.length - max);
+        this.save();
+        this.scheduleFlush(this.queue.length >= FLUSH_AT ? 0 : ((_c = this.options.flushIntervalSeconds) !== null && _c !== void 0 ? _c : 10) * 1000);
+    }
+    clean(properties) {
+        try {
+            const json = JSON.stringify(properties !== null && properties !== void 0 ? properties : {});
+            if (json.length > MAX_PROPERTIES_BYTES) {
+                this.warn('Event properties are over 32 KB and were dropped.');
+                return {};
+            }
+            const parsed = JSON.parse(json);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    // Sending ------------------------------------------------------------------------------
+    context(session) {
+        const device = this.env.device();
+        return {
+            platform: device.platform,
+            sdk: this.env.sdk,
+            timezone: device.timezone,
+            language: device.language,
+            device_type: device.device_type,
+            device_model: device.device_model,
+            os_name: device.os_name,
+            os_version: device.os_version,
+            app_version: this.options.appVersion,
+            screen_width: Math.round(device.screen_width),
+            screen_height: Math.round(device.screen_height),
+            page_path: session === null || session === void 0 ? void 0 : session.firstScreen,
+        };
+    }
+    /** One request's body: queued events share a person and session; with none, a heartbeat. */
+    body(events) {
+        var _a, _b, _c;
+        const head = events[0];
+        const session = this.state.session;
+        const sessionId = (_a = head === null || head === void 0 ? void 0 : head.session_id) !== null && _a !== void 0 ? _a : session === null || session === void 0 ? void 0 : session.id;
+        const startedAt = (_b = head === null || head === void 0 ? void 0 : head.session_started_at) !== null && _b !== void 0 ? _b : (session ? new Date(session.started).toISOString() : undefined);
+        const live = (session === null || session === void 0 ? void 0 : session.id) === sessionId ? session : null;
+        const current = !head || head.anonymous_id === this.state.anonymousId;
+        const userId = current ? this.state.userId : events[events.length - 1].user_id;
+        const body = {
+            anonymous_id: (_c = head === null || head === void 0 ? void 0 : head.anonymous_id) !== null && _c !== void 0 ? _c : this.state.anonymousId,
+            session: sessionId ? { id: sessionId, started_at: startedAt } : undefined,
+            sent_at: new Date(this.now()).toISOString(),
+            context: this.context(live),
+            events: events.map(({ name, insert_id, time, screen, properties, user_id }) => ({
+                name,
+                insert_id,
+                time,
+                ...(screen ? { screen } : {}),
+                properties,
+                user_id,
+            })),
+        };
+        if (userId)
+            body.user_id = userId;
+        if (current && this.state.traits)
+            body.traits = this.state.traits;
+        return JSON.parse(JSON.stringify(body));
+    }
+    nextBatch() {
+        const head = this.queue[0];
+        if (!head)
+            return [];
+        const batch = [];
+        for (const event of this.queue) {
+            if (event.session_id !== head.session_id ||
+                event.anonymous_id !== head.anonymous_id ||
+                batch.length >= BATCH_SIZE)
+                break;
+            batch.push(event);
+        }
+        return batch;
+    }
+    async post(body) {
+        return this.env.fetch(`${this.options.endpoint}/v1/events`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${this.options.key}` },
+            body: JSON.stringify(body),
+        });
+    }
+    async sendQueued() {
+        while (!this.stopped && !this.state.optedOut) {
+            const batch = this.nextBatch();
+            if (!batch.length && !(this.identityPending && this.state.session))
+                return;
+            const traitsSent = this.state.traits;
+            const carriesIdentity = !batch.length || batch[0].anonymous_id === this.state.anonymousId;
+            let response;
+            try {
+                response = await this.post(this.body(batch));
+            }
+            catch {
+                this.retryLater();
+                return;
+            }
+            const refused = response.status >= 400 &&
+                response.status < 500 &&
+                response.status !== 408 &&
+                response.status !== 429;
+            if (!response.ok && !refused) {
+                this.retryLater();
+                return;
+            }
+            if (refused)
+                this.warn(`Events were refused (${response.status}): ${await response.text().catch(() => '')}`);
+            const sent = new Set(batch.map((event) => event.insert_id));
+            this.queue = this.queue.filter((event) => !sent.has(event.insert_id));
+            if (response.ok && carriesIdentity && this.state.traits === traitsSent) {
+                this.state.traits = null;
+                this.identityPending = false;
+            }
+            this.failures = 0;
+            this.lastSent = this.now();
+            this.save();
+        }
+    }
+    retryLater() {
+        this.failures += 1;
+        this.scheduleFlush(Math.min(60000, 1000 * 2 ** Math.min(this.failures, 6)), true);
+    }
+    scheduleFlush(delay, replace = false) {
+        if (this.stopped)
+            return;
+        if (this.flushTimer) {
+            if (delay > 0 && !replace)
+                return;
+            clearTimeout(this.flushTimer);
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, delay);
+    }
+    /** Keeps an open app counted as online. */
+    heartbeat() {
+        const session = this.state.session;
+        if (this.stopped || this.state.optedOut || !this.inForeground || !session)
+            return;
+        session.last = this.now();
+        if (this.queue.length || this.identityPending) {
+            void this.flush();
+            return;
+        }
+        if (this.now() - this.lastSent < HEARTBEAT_MS - 1000)
+            return;
+        this.post(this.body([]))
+            .then(() => {
+            this.lastSent = this.now();
+        })
+            .catch(() => undefined);
+    }
+    warn(message) {
+        var _a;
+        if (this.options.debug)
+            ((_a = this.env.log) !== null && _a !== void 0 ? _a : console.warn)(`KissMyApps: ${message}`);
+    }
+}
+exports.KmaClient = KmaClient;

package/lib/device.d.ts

@@ -0,0 +1,2 @@
+import type { DeviceInfo } from './client';
+export declare function deviceInfo(): DeviceInfo;

package/lib/device.js

@@ -0,0 +1,59 @@
+"use strict";
+// What React Native itself can tell about the device, with no native module to link.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceInfo = deviceInfo;
+const react_native_1 = require("react-native");
+function timezone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    }
+    catch {
+        return 'UTC';
+    }
+}
+function language() {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const fromSettings = react_native_1.Platform.OS === 'ios'
+        ? ((_c = (_b = (_a = react_native_1.NativeModules.SettingsManager) === null || _a === void 0 ? void 0 : _a.settings) === null || _b === void 0 ? void 0 : _b.AppleLocale) !== null && _c !== void 0 ? _c : (_f = (_e = (_d = react_native_1.NativeModules.SettingsManager) === null || _d === void 0 ? void 0 : _d.settings) === null || _e === void 0 ? void 0 : _e.AppleLanguages) === null || _f === void 0 ? void 0 : _f[0])
+        : (_g = react_native_1.NativeModules.I18nManager) === null || _g === void 0 ? void 0 : _g.localeIdentifier;
+    if (typeof fromSettings === 'string' && fromSettings)
+        return fromSettings.replace(/_/g, '-').split('@')[0];
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().locale || 'en';
+    }
+    catch {
+        return 'en';
+    }
+}
+function deviceInfo() {
+    var _a, _b, _c;
+    const screen = react_native_1.Dimensions.get('screen');
+    const shortSide = Math.min(screen.width, screen.height);
+    const constants = ((_a = react_native_1.Platform.constants) !== null && _a !== void 0 ? _a : {});
+    if (react_native_1.Platform.OS === 'ios') {
+        const pad = react_native_1.Platform.isPad === true || constants.interfaceIdiom === 'pad';
+        return {
+            platform: 'ios',
+            os_name: pad ? 'iPadOS' : 'iOS',
+            os_version: String((_b = constants.osVersion) !== null && _b !== void 0 ? _b : react_native_1.Platform.Version),
+            device_type: pad ? 'tablet' : 'mobile',
+            device_model: pad ? 'iPad' : 'iPhone',
+            screen_width: screen.width,
+            screen_height: screen.height,
+            timezone: timezone(),
+            language: language(),
+        };
+    }
+    const model = typeof constants.Model === 'string' ? constants.Model : undefined;
+    return {
+        platform: 'android',
+        os_name: 'Android',
+        os_version: String((_c = constants.Release) !== null && _c !== void 0 ? _c : react_native_1.Platform.Version),
+        device_type: shortSide >= 600 ? 'tablet' : 'mobile',
+        device_model: model,
+        screen_width: screen.width,
+        screen_height: screen.height,
+        timezone: timezone(),
+        language: language(),
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,33 @@
+import { KmaClient } from './client';
+import type { ClientOptions, Properties, Storage } from './client';
+import type { NavigationRefLike } from './navigation';
+export { KmaClient, SDK_VERSION } from './client';
+export type { ClientOptions, DeviceInfo, Properties, Storage } from './client';
+export type { NavigationRefLike } from './navigation';
+export interface InitOptions extends ClientOptions {
+    /** Where the SDK keeps its IDs and offline queue, such as AsyncStorage. */
+    storage?: Storage;
+}
+export declare const KissMyApps: {
+    /** Starts the SDK once, as early as possible, with the project's client key. */
+    init(options: InitOptions): KmaClient;
+    track(name: string, properties?: Properties): void;
+    screen(name: string, properties?: Properties): void;
+    identify(userId: string | number, traits?: Properties): void;
+    setTraits(traits: Properties): void;
+    reset(): void;
+    flush(): Promise<void>;
+    optOut(): void;
+    optIn(): void;
+    getAnonymousId(): string | null;
+    getSessionId(): string | null;
+};
+/**
+ * Screen views from React Navigation:
+ * `<NavigationContainer ref={ref} {...trackNavigation(ref)}>`.
+ */
+export declare function trackNavigation(ref: NavigationRefLike): {
+    onReady: () => void;
+    onStateChange: () => void;
+};
+export default KissMyApps;