react-native-test-adx 0.1.3 → 0.1.4

package/README.md

@@ -1,16 +1,12 @@
 # react-native-adaxon
 
-Adaxon React Native / Expo SDK for event tracking and offer recommendations.
+React Native / Expo SDK for event tracking and offer recommendations.
 
-The SDK talks to the MTS tracker over HTTPS. The app does not call Kafka or MySQL.
-
-```text
-Mobile app  →  Adaxon SDK  →  HTTPS  →  MTS tracker  →  Kafka  →  MTS API  →  MySQL
-```
+**Dependencies:** `react` and `react-native` only. The SDK does not bundle AsyncStorage, NetInfo, or other storage/network libraries.
 
 ## Install
 
-### Production apps
+**Production**
 
 ```sh
 npm install react-native-adaxon
@@ -20,53 +16,21 @@ yarn add react-native-adaxon
 npx expo install react-native-adaxon
 ```
 
-```ts
-import { AdaxonProvider, useAdaxon } from 'react-native-adaxon';
-```
-
-### Testing / staging apps
+**Testing / staging**
 
 ```sh
 npm install react-native-test-adx
 ```
 
-```ts
-import { AdaxonProvider, useAdaxon } from 'react-native-test-adx';
-```
-
-Both packages expose the same API. Only the npm name differs.
-
-## Quick start (React Native)
-
-Wrap the app in `AdaxonProvider`. Screens use `useAdaxon()`.
+Both packages expose the same public API.
 
-Tracking does **not** write React state, so `logEvent` / `track` will not re-render the tree.
-
-### Configuration
-
-The SDK owns the tracker host and API paths (`/event/tracking`, `/api/mts/recommendations`, `/click/tracking`). The app only provides credentials.
-
-| Field | Required | Default |
-|---|---|---|
-| `appId` | **Yes** | None. MTS app id (`adx_…`). |
-| `sdkKey` | **Yes** | None. Sent as the `x-sdk-key` header. |
-| `storage` | No | In-memory event queue and anonymous id. Offline events and the generated id are lost on app restart. |
-| `timeoutMs` | No | `10000` |
-| `testMode` | No | `false` (`sdk_version` gets a `-test` suffix when true) |
-| `externalUserId` | No | Unset |
-
-The SDK detects the device platform and collects device/app fields automatically. Do **not** pass a tracker URL — requests go to the SDK `BASE_URL`.
+## Quick start
 
 ```tsx
-import {
-  AdaxonProvider,
-  AdxEvent,
-  useAdaxon,
-  type RecommendationOffer,
-} from 'react-native-adaxon';
-import { Button, Text, View } from 'react-native';
-
-function App() {
+import { AdaxonProvider, useAdaxon } from 'react-native-adaxon';
+import { Button, Text } from 'react-native';
+
+export default function App() {
   return (
     <AdaxonProvider
       configuration={{
@@ -81,266 +45,426 @@ function App() {
 }
 
 function HomeScreen() {
-  const {
-    isInitialized,
-    logEvent,
-    trackPurchase,
-    trackAddToCart,
-    loadRecommendations,
-    showOffer,
-  } = useAdaxon();
+  const { isInitialized, initializationError, logEvent } = useAdaxon();
 
   if (!isInitialized) {
-    return <Text>Initializing…</Text>;
+    return <Text>{initializationError ?? 'Initializing…'}</Text>;
   }
 
   return (
-    <View>
-      <Button
-        title="Custom event"
-        onPress={() =>
-          logEvent('level_completed', {
-            level_number: 10,
-            coins_used: 50,
-          })
-        }
-      />
-      <Button
-        title="Purchase"
-        onPress={() =>
-          trackPurchase({
-            order_id: 'ORD123',
-            amount: 999,
-            currency: 'INR',
-          })
-        }
-      />
-      <Button
-        title="Add to cart"
-        onPress={() =>
-          trackAddToCart({
-            product_id: 'P123',
-            price: 499,
-            currency: 'INR',
-          })
-        }
-      />
-      <Button
-        title="Load offers"
-        onPress={async () => {
-          const offers: RecommendationOffer[] = await loadRecommendations(
-            'recommendation_view',
-            { placement: 'home' }
-          );
-          if (offers[0]) {
-            await showOffer(offers[0]);
-          }
-        }}
-      />
-    </View>
+    <Button
+      title="Track event"
+      onPress={() => logEvent('level_completed', { level_number: 10 })}
+    />
   );
 }
 ```
 
-Do **not** pass device or app fields. The SDK attaches `device` and `app` automatically on every event.
+Tracking calls do not update React state, so `logEvent` and `track` will not re-render your app.
 
-### Anonymous id
+`AdaxonProvider` is required for full-screen ads (`showAd`).
 
-`user.anonymous_id` is generated by the SDK. It reads a unique id from React Native `NativeModules` when the host exposes one, otherwise it generates a UUID. The value is cached for the process and written to the configured `storage` adapter so the same id is reused across app launches. No third-party device-info package is required.
+## Configuration
 
-### Storage
+Pass `configuration` to `AdaxonProvider`, or to `Adaxon.initialize()` when not using React.
 
-`storage` is optional. It persists the **event queue** (offline / pending events) and the **anonymous id**. Only `appId` and `sdkKey` are required.
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `appId` | Yes | — | Your MTS app id (`adx_…`) |
+| `sdkKey` | Yes | — | Sent as the `x-sdk-key` header |
+| `storage` | No | In-memory | Persists offline event queue and anonymous id |
+| `timeoutMs` | No | `10000` | HTTP timeout in ms |
+| `testMode` | No | `false` | Sets `sdk_version` to `{version}-test` when true |
 
-| What you pass | What happens |
-|---|---|
-| No `storage` | The queue and anonymous id stay in memory. Tracking still works. Both are lost if the app closes. |
-| A storage adapter | Queued events and the anonymous id survive restart. |
+Only `appId` and `sdkKey` are required. Do not pass a tracker URL — the SDK owns the host and API paths.
 
-The adapter is only `getItem` / `setItem` / `removeItem`. You do not implement the queue.
+The SDK attaches `device`, `app`, `user.anonymous_id`, and network fields automatically. Do not pass them in event calls.
 
-### Non-component boot
+### Persistent storage (optional)
 
-`Adaxon.initialize()` is still available if you are not inside a React tree. Prefer the provider in React Native apps.
+By default the SDK uses in-memory storage. Offline events and the anonymous id are lost when the app closes.
 
-```ts
-import { Adaxon } from 'react-native-adaxon';
+Pass any object that implements `AdaxonStorageAdapter`:
 
-await Adaxon.initialize({
-  appId: 'adx_your_app_id',
-  sdkKey: 'your_sdk_key',
-});
+```tsx
+<AdaxonProvider
+  configuration={{
+    appId: 'adx_your_app_id',
+    sdkKey: 'your_sdk_key',
+    storage: {
+      getItem: (key) => myKeyValueStore.get(key),
+      setItem: (key, value) => myKeyValueStore.set(key, value),
+      removeItem: (key) => myKeyValueStore.delete(key),
+    },
+  }}
+>
+  {/* … */}
+</AdaxonProvider>
+```
 
-await Adaxon.logEvent('level_completed', { level_number: 10 });
+---
+
+## Public API reference
+
+Everything below is exported from `react-native-adaxon` / `react-native-test-adx` via `src/index.ts`.
+
+**React apps:** use `AdaxonProvider` + `useAdaxon()`.
+
+**Non-React apps:** use the `Adaxon` singleton (`AdaxonSdk.shared`).
+
+### `AdaxonProvider`
+
+Initializes the SDK when the app mounts and mounts the interstitial overlay for ads.
+
+```tsx
+import { AdaxonProvider } from 'react-native-adaxon';
+
+<AdaxonProvider
+  configuration={{ appId: 'adx_your_app_id', sdkKey: 'your_sdk_key' }}
+  listener={{
+    onInitializationComplete: () => console.log('Adaxon ready'),
+    onInitializationFailed: (code, message) =>
+      console.warn('Adaxon init failed', code, message),
+  }}
+>
+  {/* your app */}
+</AdaxonProvider>
 ```
 
-## API
+| Prop | Required | Description |
+|---|---|---|
+| `configuration` | Yes | SDK credentials and optional settings |
+| `listener` | No | Init success/failure callbacks |
+| `children` | Yes | App content |
 
-| Method | What it does |
-|---|---|
-| `AdaxonProvider` | Starts the SDK once when the app mounts |
-| `useAdaxon()` | Hook for screens: track, recommendations, offers |
-| `logEvent(name, values)` | Custom or predefined event |
-| `trackPurchase(params)` | Sends `adx_purchase` |
-| `trackAddToCart(params)` | Sends `adx_add_to_cart` |
-| `trackLogin(params)` | Sends `adx_login` |
-| `trackCompleteRegistration(params)` | Sends `adx_complete_registration` |
-| `track` / `trackBatch` | Send immediately. `trackBatch` accepts 1–100 events |
-| `enqueueEvent(name, properties)` | Store an event locally; does not send yet |
-| `processPendingEvents()` | Send queued events in batches of up to 100 |
-| `loadRecommendations(eventName, properties)` | POST `/api/mts/recommendations` |
-| `showOffer(offer)` | Opens the offer URL and tracks `offer_opened` |
-| `setExternalUserId(id)` | Attaches `external_user_id` on later events |
-
-Predefined names: `AdxEvent.PURCHASE`, `AdxEvent.ADD_TO_CART`, `AdxEvent.LOGIN`, `AdxEvent.COMPLETE_REGISTRATION`.
-
-## Event queue and batch processing
-
-`track` and `trackBatch` send immediately. Use `enqueueEvent` / `processPendingEvents` when events should wait in the local queue.
+---
 
-```ts
-const { enqueueEvent, processPendingEvents } = useAdaxon();
+### `useAdaxon()`
+
+Hook that returns init status and all tracking, queue, and ad methods. Must be used inside `AdaxonProvider`.
+
+```tsx
+const adaxon = useAdaxon();
+```
+
+#### `isInitialized`
+
+`boolean` — `true` after the SDK initializes successfully.
+
+```tsx
+const { isInitialized } = useAdaxon();
+
+if (!isInitialized) {
+  return <Text>Loading…</Text>;
+}
+```
+
+#### `initializationError`
+
+`string | null` — error message when initialization failed; `null` on success or while initializing.
+
+```tsx
+const { isInitialized, initializationError } = useAdaxon();
+
+if (!isInitialized) {
+  return <Text>{initializationError ?? 'Initializing…'}</Text>;
+}
+```
+
+#### `logEvent(eventName, values?, options?)`
+
+Track a custom event. `values` are normalized to event properties.
+
+```tsx
+const { logEvent } = useAdaxon();
+
+await logEvent('level_completed', { level_number: 10, coins_used: 50 });
+```
+
+Event names must match `^[a-zA-Z][a-zA-Z0-9_]*$` and be at most 100 characters.
+
+#### `track(eventName, properties?, options?)`
+
+Send one event immediately when online. When offline, the event is queued automatically.
+
+```tsx
+const { track } = useAdaxon();
+
+await track('button_clicked', { button_name: 'checkout' });
+```
+
+#### `trackBatch(events)`
+
+Send 1–100 events in one request when online. When offline, events are queued automatically.
+
+```tsx
+const { trackBatch } = useAdaxon();
+
+await trackBatch([
+  { eventName: 'screen_view', properties: { screen: 'home' } },
+  { eventName: 'screen_view', properties: { screen: 'settings' } },
+]);
+```
+
+#### `enqueueEvent(eventName, properties?, options?)`
+
+Store an event locally without sending it. Use `processPendingEvents()` to flush the queue.
+
+```tsx
+const { enqueueEvent } = useAdaxon();
 
 await enqueueEvent('level_completed', { level_number: 10 });
+```
+
+#### `processPendingEvents()`
+
+Flush queued events in FIFO order, up to 100 per batch. Returns a `BatchProcessResult`.
+
+```tsx
+const { processPendingEvents } = useAdaxon();
+
 const result = await processPendingEvents();
 // result.status: 'completed' | 'stopped' | 'already_processing'
+// result.eventsProcessed, result.batchesSent, result.failedQueueIds
 ```
 
-How it works:
-
-```text
-Persistent event queue
-        ↓
-Get next ≤ 100 events (FIFO)
-        ↓
-POST /event/tracking
-        ↓
-   Success → remove those events → next batch
-   Failure → keep events → stop (retry later)
+When the device is offline, `track`, `trackBatch`, and `logEvent` queue events automatically. When connectivity returns, pending events flush in the background. On startup, pending events also flush when the network is available.
+
+#### `trackPurchase(params, options?)`
+
+Track a purchase event (`AdxEvent.PURCHASE`). Maps `amount` → `adx_revenue`, `currency` → `adx_currency`, `product_id`/`content_id` → `adx_content_id`.
+
+```tsx
+const { trackPurchase } = useAdaxon();
+
+await trackPurchase({
+  order_id: 'ORD123',
+  amount: 999,
+  currency: 'INR',
+  product_id: 'P123',
+});
 ```
 
-Rules:
+#### `trackAddToCart(params, options?)`
 
-- Pending events are stored through the `storage` adapter when you pass one, so they survive app restart. If you omit `storage`, they stay in memory only.
-- Events are processed in creation order (FIFO).
-- Each request contains at most **100** events. A queue of 250 is sent as 100 + 100 + 50.
-- Events are removed only after the API confirms success (`success: true`). On network, HTTP, or unknown errors they stay in the queue.
-- Only one processor runs at a time for the same app. A second `processPendingEvents()` call returns `already_processing`.
-- Large queues are read 100 events at a time. The SDK does not load the whole queue into memory.
-- On `Adaxon.initialize()` / `AdaxonProvider` mount, pending events start flushing in the background without blocking startup when the network is available.
-- Pass `removeItem` on the storage adapter so successful events can be deleted. If it is omitted, the SDK writes an empty value instead.
+Track an add-to-cart event (`AdxEvent.ADD_TO_CART`). Maps `price` → `adx_revenue`, `currency` → `adx_currency`, `product_id`/`content_id` → `adx_content_id`.
 
-## Network loss
+```tsx
+const { trackAddToCart } = useAdaxon();
 
-The SDK watches connectivity through the host app's NetInfo / Expo Network listener. It does **not** poll.
+await trackAddToCart({
+  product_id: 'P123',
+  price: 499,
+  currency: 'INR',
+  quantity: 1,
+});
+```
 
-- Online: `track` / `trackBatch` send immediately, same as before.
-- Offline: events are stored in the event queue and no API request is made.
-- Offline → online: the batch processor is notified once and pending events are flushed. Duplicate `ONLINE` events do not start extra processors.
-- `isNetworkAvailable()` reports the current state. `destroy()` (and Provider unmount) removes the network listener.
+#### `trackLogin(params?, options?)`
 
-A missing or failing network module does not crash the app. Tracking continues as online until the device is known to be offline.
+Track a login event (`AdxEvent.LOGIN`).
 
-Offline events use the same `storage` adapter as above. Without it, they are held in memory and are lost if the app is closed before the network returns.
+```tsx
+const { trackLogin } = useAdaxon();
 
-## Automatic device information
+await trackLogin({ method: 'email' });
+```
 
-```json
-{
-  "device": {
-    "platform": "android",
-    "os_version": "14",
-    "brand": "Samsung",
-    "model": "S23",
-    "language": "en",
-    "timezone": "Asia/Kolkata"
-  }
+#### `trackCompleteRegistration(params?, options?)`
+
+Track a registration event (`AdxEvent.COMPLETE_REGISTRATION`).
+
+```tsx
+const { trackCompleteRegistration } = useAdaxon();
+
+await trackCompleteRegistration({ method: 'google' });
+```
+
+#### `showAd()`
+
+Show the first eligible offer as a full-screen interstitial. Does nothing if no offer is available.
+
+```tsx
+const { showAd } = useAdaxon();
+
+await showAd();
+```
+
+Requires `AdaxonProvider` for the interstitial overlay.
+
+Interstitial behavior:
+
+- A progress bar runs for about 8 seconds.
+- The close (×) button appears after the bar completes.
+- Tapping the creative opens `offer_url`.
+
+---
+
+### `Adaxon` (imperative API)
+
+Use when React is not available. Exposes the same tracking, queue, and ad methods as `useAdaxon()`, plus lifecycle helpers.
+
+```ts
+import { Adaxon } from 'react-native-adaxon';
+```
+
+#### `Adaxon.initialize(configuration, listener?)`
+
+Initialize the SDK. Required before any other call.
+
+```ts
+await Adaxon.initialize({
+  appId: 'adx_your_app_id',
+  sdkKey: 'your_sdk_key',
+  testMode: false,
+});
+```
+
+#### `Adaxon.isInitialized()`
+
+Returns whether the SDK has been initialized.
+
+```ts
+if (Adaxon.isInitialized()) {
+  await Adaxon.logEvent('app_opened');
 }
 ```
 
-Values come from React Native `Platform` (`src/platform/reactNative.ts`). They are read **once** and cached. Missing optional fields are omitted and never block the request.
+#### `Adaxon.isNetworkAvailable()`
 
-## Automatic app information
+Returns whether the SDK considers the device online.
 
-```json
-{
-  "app": {
-    "package_name": "com.example.app",
-    "app_version": "2.4.1",
-    "sdk_version": "0.1.3"
-  }
+```ts
+if (Adaxon.isNetworkAvailable()) {
+  await Adaxon.processPendingEvents();
 }
 ```
 
-`package_name` and `app_version` are read from native application APIs (Android package / iOS bundle). `sdk_version` is always set by the SDK. Do **not** pass these fields in `logEvent`, `track`, or `trackBatch` — every event, including each item in a batch, receives the same `app` object automatically. Missing optional fields are omitted and never block the request.
-
-## How the folders work
-
-```text
-App screen
-   │  useAdaxon().logEvent(...)  or  enqueueEvent(...) → processPendingEvents()
-   ▼
-components/ + hooks/ + state/     React layer (init only)
-   ▼
-AdaxonSdk.ts                      Public methods
-   ▼
-core/AdaxonClient.ts              Wires services
-   ▼
-services/                         Validate, build JSON, queue, batch, HTTPS
-   ▼
-MTS tracker
+#### `Adaxon.destroy()`
+
+Tear down the SDK instance. `AdaxonProvider` calls this automatically on unmount.
+
+```ts
+Adaxon.destroy();
 ```
 
-| Folder | Role |
+#### Tracking, queue, and ads
+
+These methods match `useAdaxon()`:
+
+| Method | Same as |
 |---|---|
-| `src/index.ts` | Public exports (`Adaxon`, `AdaxonProvider`, `useAdaxon`) |
-| `src/AdaxonSdk.ts` | SDK facade (`initialize`, `logEvent`, queue, offers) |
-| `src/components/` | `AdaxonProvider` |
-| `src/hooks/` | `useAdaxon()` |
-| `src/state/` | Init status only — no event list in React state |
-| `src/core/` | `AdaxonClient` — connects auth, events, queue, HTTP |
-| `src/services/` | Auth, device, app, event build/send, batch processor, network |
-| `src/platform/` | Android/iOS fields. **Only `react-native` import** |
-| `src/config/` | Tracker host, API paths, timeouts, storage key rules |
-| `src/validation/` | Event name, property, and batch-size rules |
-| `src/storage/` | Persistent event queue |
-| `example/src/` | Demo app: `App.tsx`, `screens/`, `components/` |
+| `Adaxon.logEvent` | `useAdaxon().logEvent` |
+| `Adaxon.track` | `useAdaxon().track` |
+| `Adaxon.trackBatch` | `useAdaxon().trackBatch` |
+| `Adaxon.enqueueEvent` | `useAdaxon().enqueueEvent` |
+| `Adaxon.processPendingEvents` | `useAdaxon().processPendingEvents` |
+| `Adaxon.trackPurchase` | `useAdaxon().trackPurchase` |
+| `Adaxon.trackAddToCart` | `useAdaxon().trackAddToCart` |
+| `Adaxon.trackLogin` | `useAdaxon().trackLogin` |
+| `Adaxon.trackCompleteRegistration` | `useAdaxon().trackCompleteRegistration` |
+| `Adaxon.showAd` | `useAdaxon().showAd` |
+
+Example without React:
+
+```ts
+import { Adaxon } from 'react-native-adaxon';
+
+await Adaxon.initialize({
+  appId: 'adx_your_app_id',
+  sdkKey: 'your_sdk_key',
+});
 
-Screens belong in the **host app**, not in the SDK.
+await Adaxon.logEvent('level_completed', { level_number: 10 });
+await Adaxon.trackPurchase({ order_id: 'ORD123', amount: 999, currency: 'INR' });
+await Adaxon.showAd();
+```
 
-Longer walkthrough for managers and teammates: [ARCHITECTURE.md](./ARCHITECTURE.md).  
-Framework cost vs vanilla JS is checked by `src/__tests__/performance.framework.test.tsx`.
+Prefer `AdaxonProvider` in React Native apps so init state and interstitials work correctly.
 
-## Android notes
+---
 
-Credential `platform` in Adaxon must allow Android (`android` or `react_native`).
+### Constants
 
-## Local development (this repo)
+#### `AdxEvent`
 
-```sh
-cd adaxon-sdk
-corepack enable
-yarn
-yarn typecheck
-yarn test --watchman=false
-yarn prepare
-yarn example android:emulator
+Predefined event name constants.
+
+```ts
+import { AdxEvent } from 'react-native-adaxon';
+
+AdxEvent.PURCHASE;              // 'adx_purchase'
+AdxEvent.ADD_TO_CART;           // 'adx_add_to_cart'
+AdxEvent.LOGIN;                 // 'adx_login'
+AdxEvent.COMPLETE_REGISTRATION; // 'adx_complete_registration'
 ```
 
-## Publish to npm
+#### `AdxParam`
 
-```sh
-npm login
-yarn publish:test:dry    # dry-run testing package
-yarn publish:test        # publishes react-native-test-adx
-yarn publish:prod:dry    # dry-run production package
-yarn publish:prod        # publishes react-native-adaxon
+Predefined property name constants used by commerce helpers.
+
+```ts
+import { AdxParam } from 'react-native-adaxon';
+
+AdxParam.REVENUE;    // 'adx_revenue'
+AdxParam.CURRENCY;   // 'adx_currency'
+AdxParam.CONTENT_ID; // 'adx_content_id'
 ```
 
-| Environment | Install |
+---
+
+### Errors
+
+Failed SDK calls throw `AdaxonSdkError` with a `code`:
+
+| Code | Meaning |
 |---|---|
-| Testing | `npm install react-native-test-adx` |
-| Production | `npm install react-native-adaxon` |
+| `INVALID_CONFIG` | Missing or invalid SDK configuration |
+| `VALIDATION_ERROR` | Invalid event name, properties, or batch |
+| `AUTHENTICATION_ERROR` | Invalid SDK key |
+| `HTTP_ERROR` | Server returned an error |
+| `NETWORK_ERROR` | Network request failed |
+| `TIMEOUT` | Request timed out |
+
+```tsx
+import { AdaxonSdkError } from 'react-native-adaxon';
+
+try {
+  await logEvent('invalid name!', {});
+} catch (error) {
+  if (error instanceof AdaxonSdkError) {
+    console.warn(error.code, error.message);
+  }
+}
+```
+
+---
+
+### Exported types
+
+TypeScript types exported for app integration:
+
+| Type | Use |
+|---|---|
+| `AdaxonStorageAdapter` | Custom persistent storage |
+| `AdaxonSdkConfig` | SDK configuration shape |
+| `AdaxonInitializationListener` | Init callbacks for `AdaxonProvider` / `Adaxon.initialize` |
+| `TrackPurchaseParams` | Params for `trackPurchase` |
+| `TrackAddToCartParams` | Params for `trackAddToCart` |
+| `TrackLoginParams` | Params for `trackLogin` / `trackCompleteRegistration` |
+| `EventProperties` | Event property map (`string`, `number`, `boolean`, `null`) |
+| `TrackEventInput` | Single event in `trackBatch` |
+| `TrackEventOptions` | Optional `eventId` / `eventTime` on track calls |
+| `EventIngestionResponse` | Response from track calls |
+| `BatchProcessResult` | Response from `processPendingEvents` |
+
+---
+
+## Android
+
+Your Adaxon credential `platform` must allow Android (`android` or `react_native`).
+
+---
 
 ## License