@bananalytics/react-native 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.2.0
+
+A bug-fix release, but the minor version moves because two of the fixes change
+what the SDK sends. Upgrading is strongly recommended: 0.1.x can lose events.
+
+### Fixed
+
+- **A long offline queue was discarded instead of sent.** `flush()` put the
+  whole queue in one request. The queue holds up to 1000 events by default and
+  the server accepts 500, rejecting anything larger with a `400` — which is
+  treated as non-retryable and dropped. A device offline long enough to queue
+  more than 500 events lost all of them on reconnect, silently, and could not
+  recover: the persisted queue reloaded on restart and failed the same way.
+  Events are now sent in chunks of 500, oldest first and sequentially, so their
+  order survives. A failing chunk re-queues from itself onward.
+
+- **Events the server rejected were reported as success.** A `200` does not mean
+  every event was stored — each one is validated and the rest are named in the
+  response body. That body was discarded, so an app could lose part of one event
+  type to a malformed name with nothing anywhere saying so. Rejections are now
+  logged with the server's reason.
+
+- **No event was recorded when the app cold-started.** Lifecycle tracking only
+  ever saw `AppState` transitions, which a fresh launch does not produce — so
+  the first event of a launch was whatever the person happened to tap, and the
+  top of every funnel was short by everyone who opened the app and left.
+
+- **The SDK sent a request to Google on every flush.** Without
+  `@react-native-community/netinfo` installed, the connectivity check fetched a
+  Google endpoint — and returned "online" whether that succeeded or failed, so
+  it decided nothing. Removed; a failed send was already handled by the retry
+  and the queue.
+
+### Changed
+
+- `$app_opened` is emitted once per launch when `trackAppLifecycle` is on. If
+  you count events per session, expect one more.
+- `optOut()` now discards anything still queued, in memory and on disk. It
+  previously only stopped new collection, so already-collected events went out
+  on the next flush — which is exactly the data somebody opting out means.
+
+## 0.1.1
+
+- Initial published release.

package/README.md

@@ -60,7 +60,7 @@ interface BananalyticsConfig {
   maxQueueSize?: number;    // Max events in memory (default: 1000)
   maxRetries?: number;      // Retry attempts (default: 3)
   debug?: boolean;          // Enable console logging (default: false)
-  trackAppLifecycle?: boolean; // Auto-track foreground/background (default: true)
+  trackAppLifecycle?: boolean; // Auto-track app open + foreground/background (default: true)
   trackScreens?: boolean;   // Auto-track screen views (default: false)
   sessionTimeout?: number;  // Session timeout in ms (default: 1800000)
 }
@@ -73,19 +73,34 @@ interface BananalyticsConfig {
 | `Bananalytics.init(config)` | Initialize the SDK |
 | `Bananalytics.track(event, properties?)` | Track a custom event |
 | `Bananalytics.screen(name, properties?)` | Track a screen view |
-| `Bananalytics.identify(userId, traits?)` | Identify the current user |
+| `Bananalytics.trackRevenue(amount, currency?, properties?, event?)` | Track a purchase. Adds `revenue` and `currency` to the properties, which the server reads into its own columns |
+| `Bananalytics.identify(userId, traits?)` | Identify the current user. Events sent before this are attributed to the same person afterwards |
 | `Bananalytics.reset()` | Clear identity and generate new anonymous ID |
 | `Bananalytics.optIn()` | Resume tracking |
-| `Bananalytics.optOut()` | Stop all tracking |
+| `Bananalytics.optOut()` | Stop tracking and discard anything still queued |
 | `Bananalytics.flush()` | Manually flush queued events |
 
+Any event can carry revenue — adding `revenue` and `currency` to the properties
+of your own purchase event does the same thing as `trackRevenue`.
+
+## Automatically captured
+
+With `trackAppLifecycle` on (the default):
+
+| Event | When |
+|---|---|
+| `$app_opened` | The app starts. A cold start is not a foreground transition, so it needs its own event |
+| `$app_foreground` | The app returns from the background |
+| `$app_background` | The app goes to the background. The queue is persisted and flushed here |
+| `$session_start` / `$session_end` | A session begins or times out (`sessionTimeout`, default 30 min) |
+
 ## Features
 
-- Automatic event batching and flushing
-- Offline persistence with AsyncStorage
+- Automatic event batching and flushing, split into requests the server accepts
+- Offline persistence with AsyncStorage, order preserved across restarts
 - Exponential backoff retry on network failures
 - Session tracking with configurable timeout
-- Privacy controls (opt-in/opt-out)
+- Privacy controls (opt-in/opt-out), and no requests to anyone but your server
 - Zero uncaught exceptions (host app stability is sacred)
 
 ## License

package/dist/context/session.js

@@ -67,12 +67,13 @@ class SessionManager {
     }
     /** Ends the current session. */
     endSession() {
-        if (this.session) {
-            this.logger.debug('Session ended', this.session.id);
-            if (this.onSessionEnd) {
-                this.onSessionEnd(this.session);
-            }
-            this.session = null;
+        if (!this.session)
+            return;
+        const ended = this.session;
+        this.session = null;
+        this.logger.debug('Session ended', ended.id);
+        if (this.onSessionEnd) {
+            this.onSessionEnd(ended);
         }
     }
     startNewSession(timestamp) {

package/dist/core/client.d.ts

@@ -58,6 +58,24 @@ export declare class BananalyticsClient {
      * ```
      */
     screen(screenName: string, properties?: Properties): void;
+    /**
+     * Tracks a purchase or any other event that earned money.
+     *
+     * The server reads `revenue` and `currency` out of the properties of *any*
+     * event, so an app that already tracks its own purchase event can simply add
+     * those two properties instead of switching to this method.
+     *
+     * @param amount - The monetary value. Negative amounts record refunds.
+     * @param currency - ISO 4217 code, e.g. 'USD' or 'EUR'
+     * @param properties - Optional extra properties, such as the product ID
+     * @param eventName - Event name to record it under
+     *
+     * @example
+     * ```ts
+     * client.trackRevenue(9.99, 'EUR', { product_id: 'pro_monthly' });
+     * ```
+     */
+    trackRevenue(amount: number, currency?: string, properties?: Properties, eventName?: string): void;
     /**
      * Identifies the current user.
      *
@@ -85,6 +103,11 @@ export declare class BananalyticsClient {
     optIn(): void;
     /**
      * Opts the user out of analytics tracking. Stops all event collection.
+     *
+     * Anything already queued is discarded rather than sent. Somebody opting out
+     * means the data collected up to that moment too — it is still sitting on
+     * their device, and a queue that keeps draining afterwards would deliver
+     * exactly what they asked not to be delivered.
      */
     optOut(): void;
     /**

package/dist/core/client.js

@@ -83,6 +83,17 @@ class BananalyticsClient {
             }
             this.batcher.start();
             this.initialized = true;
+            // A cold start is not an AppState transition, so the lifecycle tracker
+            // never sees it — it only ever reports coming *back* from the background.
+            // Without this the first event of a fresh launch is whatever the person
+            // happened to tap, and the top of every funnel is short by everyone who
+            // opened the app and left again.
+            //
+            // Fired after identity and session have been restored, so it carries the
+            // same anonymous ID as the rest of the launch rather than a fresh one.
+            if (this.config.trackAppLifecycle) {
+                this.track('$app_opened');
+            }
             this.logger.debug('Bananalytics SDK initialized');
         }
         catch (err) {
@@ -135,6 +146,30 @@ class BananalyticsClient {
             this.logger.error('Failed to track screen', err);
         }
     }
+    /**
+     * Tracks a purchase or any other event that earned money.
+     *
+     * The server reads `revenue` and `currency` out of the properties of *any*
+     * event, so an app that already tracks its own purchase event can simply add
+     * those two properties instead of switching to this method.
+     *
+     * @param amount - The monetary value. Negative amounts record refunds.
+     * @param currency - ISO 4217 code, e.g. 'USD' or 'EUR'
+     * @param properties - Optional extra properties, such as the product ID
+     * @param eventName - Event name to record it under
+     *
+     * @example
+     * ```ts
+     * client.trackRevenue(9.99, 'EUR', { product_id: 'pro_monthly' });
+     * ```
+     */
+    trackRevenue(amount, currency = 'USD', properties, eventName = '$purchase') {
+        if (!Number.isFinite(amount)) {
+            this.logger.error('Revenue amount must be a finite number', amount);
+            return;
+        }
+        this.track(eventName, { ...properties, revenue: amount, currency });
+    }
     /**
      * Identifies the current user.
      *
@@ -193,11 +228,20 @@ class BananalyticsClient {
     }
     /**
      * Opts the user out of analytics tracking. Stops all event collection.
+     *
+     * Anything already queued is discarded rather than sent. Somebody opting out
+     * means the data collected up to that moment too — it is still sitting on
+     * their device, and a queue that keeps draining afterwards would deliver
+     * exactly what they asked not to be delivered.
      */
     optOut() {
         this.consent.optOut().catch((err) => {
             this.logger.error('Failed to opt out', err);
         });
+        this.queue.clear();
+        this.persister.clearQueue().catch((err) => {
+            this.logger.error('Failed to clear persisted queue on opt-out', err);
+        });
     }
     /**
      * Manually flushes all queued events to the backend.

package/dist/index.d.ts

@@ -43,6 +43,20 @@ export declare const Bananalytics: {
      * @param properties - Optional screen properties
      */
     screen(screenName: string, properties?: Properties): void;
+    /**
+     * Tracks a purchase or any other event that earned money.
+     *
+     * @param amount - The monetary value. Negative amounts record refunds.
+     * @param currency - ISO 4217 code, e.g. 'USD' or 'EUR'
+     * @param properties - Optional extra properties, such as the product ID
+     * @param eventName - Event name to record it under
+     *
+     * @example
+     * ```ts
+     * Bananalytics.trackRevenue(9.99, 'EUR', { product_id: 'pro_monthly' });
+     * ```
+     */
+    trackRevenue(amount: number, currency?: string, properties?: Properties, eventName?: string): void;
     /**
      * Identifies the current user.
      *

package/dist/index.js

@@ -69,6 +69,22 @@ exports.Bananalytics = {
     screen(screenName, properties) {
         instance?.screen(screenName, properties);
     },
+    /**
+     * Tracks a purchase or any other event that earned money.
+     *
+     * @param amount - The monetary value. Negative amounts record refunds.
+     * @param currency - ISO 4217 code, e.g. 'USD' or 'EUR'
+     * @param properties - Optional extra properties, such as the product ID
+     * @param eventName - Event name to record it under
+     *
+     * @example
+     * ```ts
+     * Bananalytics.trackRevenue(9.99, 'EUR', { product_id: 'pro_monthly' });
+     * ```
+     */
+    trackRevenue(amount, currency, properties, eventName) {
+        instance?.trackRevenue(amount, currency, properties, eventName);
+    },
     /**
      * Identifies the current user.
      *

package/dist/transport/batcher.js

@@ -3,6 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Batcher = void 0;
 const network_1 = require("../utils/network");
 const retry_1 = require("./retry");
+/**
+ * Most events the server accepts in a single request.
+ *
+ * Mirrors `domain.MaxBatchSize`. Going over it does not get the batch trimmed,
+ * it gets the whole request rejected with a 400 — and a 400 is deliberately not
+ * retried, so an oversized flush does not fail, it deletes. The default queue
+ * holds up to 1000 events, which a device offline for an afternoon reaches
+ * easily: precisely the case the queue exists for.
+ */
+const MAX_BATCH_SIZE = 500;
 /**
  * Manages automatic batching and flushing of events.
  * Flushes on a timer interval or when the queue reaches the threshold.
@@ -76,12 +86,24 @@ class Batcher {
         this.flushing = true;
         const events = this.queue.flush();
         try {
-            await (0, retry_1.withRetry)(() => this.transport.send(events), this.maxRetries, this.logger);
-            this.logger.debug(`Flushed ${events.length} events`);
-        }
-        catch (err) {
-            this.logger.error('Flush failed after retries, re-queueing events', err);
-            this.queue.unshift(events);
+            // Oldest first, one request at a time. Sending them in parallel would be
+            // faster and would also let a later batch land before an earlier one,
+            // which is the ordering the persisted queue exists to preserve.
+            for (let sent = 0; sent < events.length; sent += MAX_BATCH_SIZE) {
+                const chunk = events.slice(sent, sent + MAX_BATCH_SIZE);
+                try {
+                    await (0, retry_1.withRetry)(() => this.transport.send(chunk), this.maxRetries, this.logger);
+                    this.logger.debug(`Flushed ${chunk.length} events`);
+                }
+                catch (err) {
+                    // Put back this chunk and everything after it, then stop: whatever
+                    // stopped this request will stop the next one too, and the events
+                    // already accepted must not be sent twice.
+                    this.logger.error('Flush failed after retries, re-queueing events', err);
+                    this.queue.unshift(events.slice(sent));
+                    return;
+                }
+            }
         }
         finally {
             this.flushing = false;

package/dist/transport/transport.d.ts

@@ -20,4 +20,12 @@ export declare class Transport {
      * ```
      */
     send(events: EventPayload[]): Promise<void>;
+    /**
+     * Warns about events the server accepted the request for but did not store.
+     *
+     * Deliberately never throws: the request succeeded, the good events are
+     * saved, and re-sending the batch would only duplicate them. An unreadable
+     * body is not worth turning a successful flush into a failure either.
+     */
+    private reportRejected;
 }

package/dist/transport/transport.js

@@ -38,7 +38,12 @@ class Transport {
             if (!response.ok) {
                 throw new errors_1.NetworkError(`Ingestion failed with status ${response.status}`, response.status);
             }
-            this.logger.debug(`Successfully sent ${events.length} events`);
+            // A 200 does not mean every event was stored. The server validates each
+            // one and keeps the good ones, reporting the rest in the body — usually a
+            // malformed event name or a property it could not accept. Dropping that
+            // detail on the floor is how an app ends up missing a third of one event
+            // type with nothing anywhere saying so.
+            await this.reportRejected(response, events.length);
         }
         catch (err) {
             if (err instanceof errors_1.NetworkError) {
@@ -47,5 +52,26 @@ class Transport {
             throw new errors_1.NetworkError(`Network request failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /**
+     * Warns about events the server accepted the request for but did not store.
+     *
+     * Deliberately never throws: the request succeeded, the good events are
+     * saved, and re-sending the batch would only duplicate them. An unreadable
+     * body is not worth turning a successful flush into a failure either.
+     */
+    async reportRejected(response, sent) {
+        try {
+            const body = (await response.json());
+            if (body.rejected && body.rejected > 0) {
+                this.logger.warn(`Server rejected ${body.rejected} of ${sent} events: ` +
+                    (body.errors?.join('; ') ?? 'no reason given'));
+                return;
+            }
+            this.logger.debug(`Successfully sent ${body.accepted ?? sent} events`);
+        }
+        catch {
+            this.logger.debug(`Successfully sent ${sent} events`);
+        }
+    }
 }
 exports.Transport = Transport;

package/dist/utils/network.d.ts

@@ -1,7 +1,17 @@
 /**
  * Checks if the device currently has network connectivity.
- * Uses React Native's NetInfo if available, falls back to assuming online.
  *
- * @returns true if connected, false if offline
+ * Uses React Native's NetInfo when the host app has it. Without it there is no
+ * way to ask, so the answer is yes: a failed send is already handled — it
+ * retries with backoff and the events stay queued — whereas wrongly deciding
+ * the device is offline would stop a flush that would have worked.
+ *
+ * There used to be a fallback here that fetched a Google endpoint to test the
+ * connection. It was removed: it returned true whether it succeeded or failed,
+ * so it changed no outcome, and it sent a request to a third party on every
+ * flush interval — from a self-hosted, privacy-first SDK whose whole point is
+ * that the data goes to your server and nowhere else.
+ *
+ * @returns true if connected, false if NetInfo says otherwise
  */
 export declare function isOnline(): Promise<boolean>;

package/dist/utils/network.js

@@ -3,31 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isOnline = isOnline;
 /**
  * Checks if the device currently has network connectivity.
- * Uses React Native's NetInfo if available, falls back to assuming online.
  *
- * @returns true if connected, false if offline
+ * Uses React Native's NetInfo when the host app has it. Without it there is no
+ * way to ask, so the answer is yes: a failed send is already handled — it
+ * retries with backoff and the events stay queued — whereas wrongly deciding
+ * the device is offline would stop a flush that would have worked.
+ *
+ * There used to be a fallback here that fetched a Google endpoint to test the
+ * connection. It was removed: it returned true whether it succeeded or failed,
+ * so it changed no outcome, and it sent a request to a third party on every
+ * flush interval — from a self-hosted, privacy-first SDK whose whole point is
+ * that the data goes to your server and nowhere else.
+ *
+ * @returns true if connected, false if NetInfo says otherwise
  */
 async function isOnline() {
     try {
-        // Try React Native NetInfo (requires @react-native-community/netinfo)
+        // Requires @react-native-community/netinfo in the host app.
         const NetInfo = require('@react-native-community/netinfo');
         const state = await NetInfo.fetch();
         return state.isConnected ?? true;
     }
     catch {
-        // NetInfo not installed — try fetch-based check
-        try {
-            const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), 3000);
-            await fetch('https://clients3.google.com/generate_204', {
-                method: 'HEAD',
-                signal: controller.signal,
-            });
-            clearTimeout(timeout);
-            return true;
-        }
-        catch {
-            return true; // Assume online if we can't determine — better to try and fail
-        }
+        return true;
     }
 }

package/dist/utils/validation.js

@@ -51,7 +51,11 @@ function validateProperties(properties) {
         if (key.length > MAX_PROPERTY_KEY_LENGTH) {
             return `property key "${key}" exceeds ${MAX_PROPERTY_KEY_LENGTH} character limit`;
         }
-        const serialized = JSON.stringify(properties[key]);
+        const value = properties[key];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const serialized = JSON.stringify(value);
         if (serialized.length > MAX_PROPERTY_VALUE_SIZE) {
             return `property value for key "${key}" exceeds ${MAX_PROPERTY_VALUE_SIZE} byte limit: got ${serialized.length}`;
         }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@bananalytics/react-native",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Self-hosted, privacy-first analytics SDK for React Native and Expo apps. Funnels, retention, sessions, geography — your server, your data.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],