kewa-react-native 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Topchunks Solutions
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,592 @@
+# kewa-react-native
+
+**Package:** `kewa-react-native` v1.0.0  
+**Author:** Topchunks Solutions Pvt Ltd
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Initialization](#initialization)
+- [SDK API](#sdk-api)
+- [Use Cases](#use-cases)
+- [React Integration](#react-integration)
+- [Auto Tracking](#auto-tracking)
+- [Automatic Events](#automatic-events)
+- [Offline Queue](#offline-queue)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+---
+
+## Overview
+
+Kewa Analytics SDK for React Native enables tracking in mobile apps. It captures user behavior, sends events to your Kewa backend, manages contact identity, and queues events when the device is offline.
+
+**Key capabilities:**
+
+- Custom and predefined events (`trackEvent`, screen views, errors, button presses)
+- User lifecycle tracking (login, registration, logout, properties)
+- Automatic app lifecycle events (`app_launch`, `app_foreground`, `app_background`)
+- Offline event queue with automatic retry
+- React hooks (`KewaProvider`, `useKewa`, `useAutoTracker`)
+- Full TypeScript support
+
+---
+
+## Requirements
+
+
+| Dependency     | Version     |
+| -------------- | ----------- |
+| `react`        | `>= 16.8.0` |
+| `react-native` | `>= 0.60.0` |
+
+
+Bundled dependencies (installed automatically with the package):
+
+- `@react-native-async-storage/async-storage`
+- `@react-native-community/netinfo`
+- `react-native-device-info`
+
+**Platform support:**
+
+- Bare / core React Native — fully supported
+- Expo development build — supported (`expo prebuild` + `expo run:ios` / `expo run:android`)
+- Expo Go — **not supported** (`react-native-device-info` requires native code)
+
+---
+
+## Installation
+
+### 1. Install the package
+
+```bash
+npm install kewa-react-native
+# or
+yarn add kewa-react-native
+```
+
+### 2. iOS
+
+Native dependencies are linked automatically (React Native 0.60+). Install CocoaPods after adding the package:
+
+```bash
+cd ios
+pod install
+cd ..
+```
+
+Then build and run:
+
+```bash
+npx react-native run-ios
+```
+
+### 3. Android
+
+Autolinking handles native modules. Sync Gradle and run:
+
+```bash
+npx react-native run-android
+```
+
+If you use a custom Gradle setup, ensure your `settings.gradle` includes autolinked native modules (default in RN 0.60+).
+
+### 4. Expo (development build)
+
+```bash
+npx expo prebuild
+npx expo run:ios
+# or
+npx expo run:android
+```
+
+### Local development
+
+```bash
+npm install /path/to/kewa-react-native
+```
+
+The package runs `npm run build` automatically via the `prepare` script.
+
+---
+
+## Initialization
+
+Wrap your app in `KewaProvider` (recommended) or call `Kewa.init()` once at startup. Do not use both.
+
+### Configuration options
+
+```typescript
+interface KewaConfig {
+  appUrl: string;                      // Required — base URL of your Kewa instance
+  apiKey: string;                      // Required — sent as `secret` header
+  projectId?: string;                  // Required when tracking is enabled
+  disableTracking?: boolean;           // Default: false — master switch; all SDK methods no-op
+  disableEventTracking?: boolean;      // Default: false — blocks trackEvent and wrappers
+  disableAppStateTracking?: boolean;   // Default: false — blocks app_foreground / app_background
+  disableScreenViewTracking?: boolean; // Default: false — blocks auto screen_view from navigation
+  batchSize?: number;                  // Default: 10 (reserved for future batch API)
+  maxQueueSize?: number;               // Default: 100 — max offline queued events
+  enableDebugLogging?: boolean;        // Default: false — log payloads to Metro console
+}
+```
+
+
+| Flag                        | Default | Effect                                                                              |
+| --------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `disableTracking`           | `false` | Master switch. No network, no listeners, all methods no-op                          |
+| `disableEventTracking`      | `false` | Blocks events via `trackEvent` and wrappers (`trackLogin`, `trackScreenView`, etc.) |
+| `disableAppStateTracking`   | `false` | Blocks only `app_foreground` and `app_background`                                   |
+| `disableScreenViewTracking` | `false` | Blocks automatic `screen_view` from React Navigation integration                    |
+
+
+`disableTracking` overrides all other disable flags. Trailing slashes on `appUrl` are stripped automatically.
+
+### Option 1: `KewaProvider` (recommended)
+
+```tsx
+import React, { useRef } from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { KewaProvider, KewaAutoTracker } from 'kewa-react-native';
+
+export default function App() {
+  const navigationRef = useRef(null);
+  const { onReady, onStateChange } = KewaAutoTracker.setupNavigationTracking(navigationRef);
+
+  return (
+    <KewaProvider
+      config={{
+        appUrl: 'https://your-kewa-instance.com',
+        projectId: '39r48kjbddkj',
+        apiKey: 'your-api-key',
+        enableDebugLogging: __DEV__,
+      }}
+    >
+      <NavigationContainer
+        ref={navigationRef}
+        onReady={onReady}
+        onStateChange={onStateChange}
+      >
+        {/* screens */}
+      </NavigationContainer>
+    </KewaProvider>
+  );
+}
+```
+
+`KewaProvider` calls `init()` on mount and `cleanup()` on unmount.
+
+### Option 2: Imperative init
+
+```typescript
+import Kewa from 'kewa-react-native';
+
+await Kewa.init({
+  appUrl: 'https://your-kewa-instance.com',
+  projectId: '39r48kjbddkj',
+  apiKey: 'your-api-key',
+  maxQueueSize: 100,
+  enableDebugLogging: __DEV__,
+});
+
+// Optional — when tearing down
+Kewa.cleanup();
+```
+
+On init, the SDK collects device info, sets up app-state listeners, drains the offline queue, and sends `app_launch` (unless event tracking is disabled).
+
+---
+
+## SDK API
+
+All methods are available on the default `Kewa` singleton and via `useKewa()` inside `KewaProvider`.
+
+### `init(config: KewaConfig): Promise<void>`
+
+Initializes the SDK. See [Initialization](#initialization).
+
+### `trackEvent(eventName, eventData?, contactData?): Promise<void>`
+
+Track any custom event. Every event automatically includes user properties in the contact fields.
+
+```typescript
+await Kewa.trackEvent('product_viewed', {
+  productId: 'abc123',
+  category: 'electronics',
+  price: 299.99,
+});
+
+// Attach contact fields to a single event
+await Kewa.trackEvent(
+  'newsletter_signup',
+  { source: 'home_banner' },
+  { email: 'user@example.com', firstname: 'Jane' },
+);
+```
+
+### `setUserProperties(properties): Promise<void>`
+
+Merges properties into local storage and updates in Kewa Backend automatically. All fields are optional.
+
+```typescript
+await Kewa.setUserProperties({
+  email: 'user@example.com',
+  firstname: 'Jane',
+  plan: 'premium',
+});
+```
+
+### `trackLogin(userData): Promise<void>`
+
+Sends a `user_login` event. Default `loginMethod` is `'custom'`.
+
+```typescript
+await Kewa.trackLogin({
+  userId: 'user123',
+  email: 'user@example.com',
+  loginMethod: 'google', // 'email' | 'google' | 'facebook' | 'apple' | 'phone' | 'custom'
+});
+```
+
+### `trackRegistration(userData): Promise<void>`
+
+Sends a `user_registration` event. Default `registrationMethod` is `'email'`.
+
+```typescript
+await Kewa.trackRegistration({
+  userId: 'user123',
+  email: 'user@example.com',
+  registrationMethod: 'google', // 'email' | 'google' | 'facebook' | 'apple' | 'phone'
+});
+```
+
+### `trackLogout(): Promise<void>`
+
+Sends a `user_logout` event, then clears all the tracking data including any user properties set earlier.
+
+```typescript
+await Kewa.trackLogout();
+```
+
+### `trackScreenView(screenName, additionalData?): Promise<void>`
+
+Sends a `screen_view` event.
+
+```typescript
+await Kewa.trackScreenView('ProductDetail', {
+  previousScreen: 'Home',
+  screenClass: 'ProductDetailScreen',
+  loadTime: 320,
+  params: { productId: 'abc123' },
+});
+```
+
+### `trackError(error, context?, isFatal?): Promise<void>`
+
+Sends an `error` event with message, stack trace, name, and optional context.
+
+```typescript
+try {
+  await riskyOperation();
+} catch (error) {
+  await Kewa.trackError(error as Error, { screen: 'Checkout' }, false);
+}
+```
+
+### `reset(): Promise<void>`
+
+Clears tracking data, and stored user properties locally without sending a logout event. Use when you need to wipe identity silently (e.g. account deletion flow).
+
+```typescript
+await Kewa.reset();
+```
+
+### Getters
+
+
+| Method                | Returns                  | Description                          |
+| --------------------- | ------------------------ | ------------------------------------ |
+| `getKtcId()`          | `Promise<string | null>` | Locally stored contact ID            |
+| `getDeviceId()`       | `Promise<string | null>` | Kewa-assigned device ID              |
+| `getUserProperties()` | `Promise<ContactData>`   | Merged contact properties in storage |
+| `isSDKInitialized()`  | `boolean`                | Whether `init()` completed           |
+
+
+```typescript
+const contactId = await Kewa.getKtcId();
+const deviceId = await Kewa.getDeviceId();
+const props = await Kewa.getUserProperties();
+const ready = Kewa.isSDKInitialized();
+```
+
+### `cleanup(): void`
+
+Removes the `AppState` listener and network monitor. Called automatically by `KewaProvider` on unmount.
+
+```typescript
+Kewa.cleanup();
+```
+
+### Package exports
+
+```typescript
+import Kewa from 'kewa-react-native';
+import { KewaProvider, useKewa, useAutoTracker } from 'kewa-react-native';
+import { KewaTracker, KewaAutoTracker } from 'kewa-react-native';
+import { KEWA_CONSTANTS, DeviceInfoCollector } from 'kewa-react-native';
+import type { KewaConfig, ContactData, KewaEvent, KewaResponse } from 'kewa-react-native';
+```
+
+---
+
+## Use Cases
+
+### App login
+
+After the user authenticates in your app, call `trackLogin` to record the login event and attach user identity to subsequent events.
+
+```tsx
+import { useKewa } from 'kewa-react-native';
+
+function LoginScreen() {
+  const { trackLogin, setUserProperties } = useKewa();
+
+  const handleLogin = async () => {
+    const user = await authenticateWithYourBackend();
+
+    await trackLogin({
+      userId: user.id,
+      email: user.email,
+      loginMethod: 'email',
+    });
+
+    // Optionally sync profile fields immediately
+    await setUserProperties({
+      email: user.email,
+      firstname: user.firstName,
+      lastname: user.lastName,
+    });
+
+    navigation.navigate('Home');
+  };
+
+  return <Button title="Log in" onPress={handleLogin} />;
+}
+```
+
+The backend may return a `ktc_id` and `device_id` which the SDK stores automatically for future events.
+
+### App register
+
+Call `trackRegistration` when a new account is created.
+
+```tsx
+import { useKewa } from 'kewa-react-native';
+
+function RegisterScreen() {
+  const { trackRegistration, setUserProperties } = useKewa();
+
+  const handleRegister = async () => {
+    const user = await createAccountOnYourBackend();
+
+    await trackRegistration({
+      userId: user.id,
+      email: user.email,
+      registrationMethod: 'email',
+    });
+
+    await setUserProperties({
+      email: user.email,
+      firstname: user.firstName,
+      lastname: user.lastName,
+    });
+
+    navigation.navigate('Onboarding');
+  };
+
+  return <Button title="Create account" onPress={handleRegister} />;
+}
+```
+
+### Set user properties
+
+Update contact/profile fields at any time — after login, on profile edit, or after a purchase. Properties are merged locally and synced to the backend.
+
+```typescript
+import Kewa from 'kewa-react-native';
+
+// After profile update
+await Kewa.setUserProperties({
+  plan: 'premium',
+  company: 'Acme Inc',
+  preferred_locale: 'en-US',
+});
+
+// After purchase
+await Kewa.setUserProperties({
+  plan: 'premium',
+  subscriptionDate: new Date().toISOString(),
+  totalPurchases: 3,
+});
+```
+
+Supported fields include `id`, `email`, `firstname`, `lastname`, `mobile`, `company`, address fields, social profiles, and any custom keys via the `ContactData` index signature.
+
+### App logout (clears everything)
+
+Call `trackLogout` when the user signs out. This sends a `user_logout` event and **clears all local identity** — `ktc_id`, `device_id`, and user properties — so the next session starts anonymous.
+
+```tsx
+import { useKewa } from 'kewa-react-native';
+
+function ProfileScreen() {
+  const { trackLogout } = useKewa();
+
+  const handleLogout = async () => {
+    await signOutFromYourBackend();
+    await trackLogout(); // sends user_logout + clears ktc_id, device_id, user properties
+    navigation.reset({ index: 0, routes: [{ name: 'Login' }] });
+  };
+
+  return <Button title="Log out" onPress={handleLogout} />;
+}
+```
+
+---
+
+## React Integration
+
+### `useKewa()`
+
+Returns the full SDK API. Must be used inside `KewaProvider`.
+
+```tsx
+function CheckoutScreen() {
+  const {
+    trackEvent,
+    trackLogin,
+    trackLogout,
+    trackRegistration,
+    trackScreenView,
+    trackError,
+    setUserProperties,
+    reset,
+    getKtcId,
+    getDeviceId,
+    getUserProperties,
+    isSDKInitialized,
+  } = useKewa();
+}
+```
+
+### `useAutoTracker()`
+
+UI-focused helpers bound to the provider instance.
+
+```tsx
+function HomeScreen() {
+  const { trackButtonPress, trackFormSubmission, trackError } = useAutoTracker();
+
+  return (
+    <>
+      <Button onPress={trackButtonPress('subscribe', { plan: 'premium' })} />
+      <Button onPress={trackFormSubmission('newsletter', { source: 'home' })} />
+    </>
+  );
+}
+```
+
+---
+
+## Auto Tracking
+
+`KewaTracker` / `KewaAutoTracker` are static utilities that use the shared `Kewa` singleton.
+
+### React Navigation screen tracking
+
+```typescript
+const navigationRef = useRef(null);
+const { onReady, onStateChange } = KewaAutoTracker.setupNavigationTracking(navigationRef);
+
+<NavigationContainer ref={navigationRef} onReady={onReady} onStateChange={onStateChange}>
+```
+
+Disabled when `disableTracking`, `disableEventTracking`, or `disableScreenViewTracking` is `true`.
+
+### Button and form tracking
+
+```typescript
+<Button onPress={KewaTracker.trackButtonPress('cta_signup', { variant: 'hero' })} />
+<Button onPress={KewaTracker.trackFormSubmission('contact_form', { fields: 3 })} />
+```
+
+### Error tracking
+
+```typescript
+KewaAutoTracker.trackError(error, { component: 'PaymentForm' });
+```
+
+---
+
+## Automatic Events
+
+
+| Event            | Trigger                     | Disabled when                                                             |
+| ---------------- | --------------------------- | ------------------------------------------------------------------------- |
+| `app_launch`     | SDK init completes          | `disableTracking` or `disableEventTracking`                               |
+| `app_foreground` | App returns from background | `disableTracking` or `disableAppStateTracking`                            |
+| `app_background` | App moves to background     | `disableTracking` or `disableAppStateTracking`                            |
+| `screen_view`    | Navigation route change     | `disableTracking`, `disableEventTracking`, or `disableScreenViewTracking` |
+
+
+Predefined event name constants are available on `KEWA_CONSTANTS.EVENTS`.
+
+---
+
+## Offline Queue
+
+1. If the device is offline or a send fails, the event is saved to AsyncStorage.
+2. Queue is capped at `maxQueueSize` (default **100**); oldest events are dropped when full.
+3. Queue is processed on SDK init and when the app returns to foreground.
+4. Events are sent one at a time.
+
+---
+
+## Troubleshooting
+
+
+| Issue                               | Solution                                                         |
+| ----------------------------------- | ---------------------------------------------------------------- |
+| Events not sending                  | Verify `appUrl`, `projectId`, `apiKey`, and network connectivity |
+| `projectId is required` error       | Pass `projectId` or set `disableTracking: true`                  |
+| `ktc_id` not updating               | Confirm backend returns `id` in the response                     |
+| `NativeModule.RNDeviceInfo is null` | Not running in Expo Go — use a dev build or bare RN              |
+| Queue growing                       | Check backend availability; adjust `maxQueueSize` if needed      |
+| Duplicate init                      | Use either `KewaProvider` or manual `Kewa.init()`, not both      |
+| SDK not initialized warning         | Call `init()` via provider or manually before tracking           |
+
+
+### Verify the endpoint manually
+
+```bash
+curl -X POST 'https://your-kewa-instance.com/t/39r48kjbddkj/mtc/event/track' \
+  -H 'Content-Type: application/json' \
+  -H 'secret: YOUR_API_KEY' \
+  -d '{
+    "event": "test_event",
+    "timestamp": "2026-06-09T00:00:00.000Z",
+    "data": {},
+    "contact": {},
+    "kewa_device_id": null,
+    "device": { "platform": "ios", "appVersion": "1.0.0" }
+  }'
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/lib/KewaProvider.d.ts

@@ -0,0 +1,26 @@
+import React, { ReactNode } from 'react';
+import { KewaAnalytics } from './core/KewaAnalytics';
+import { KewaConfig, ContactData, BaseEventData, UserLoginEvent, UserRegistrationEvent, ScreenViewEvent } from './types';
+export interface KewaContextValue {
+    trackEvent: (eventName: string, eventData?: BaseEventData, contactData?: ContactData) => Promise<void>;
+    setUserProperties: (properties: ContactData) => Promise<void>;
+    trackLogin: (userData: Partial<UserLoginEvent>) => Promise<void>;
+    trackLogout: () => Promise<void>;
+    trackRegistration: (userData: Partial<UserRegistrationEvent>) => Promise<void>;
+    trackScreenView: (screenName: string, additionalData?: Partial<ScreenViewEvent>) => Promise<void>;
+    trackError: (error: Error, context?: Record<string, any>, isFatal?: boolean) => Promise<void>;
+    reset: () => Promise<void>;
+    getKtcId: () => Promise<string | null>;
+    getDeviceId: () => Promise<string | null>;
+    getUserProperties: () => Promise<ContactData>;
+    isSDKInitialized: () => boolean;
+}
+interface KewaProviderProps {
+    config: KewaConfig;
+    children: ReactNode;
+    kewa?: KewaAnalytics;
+}
+export declare function KewaProvider({ config, children, kewa }: KewaProviderProps): React.JSX.Element;
+export declare function useKewa(): KewaContextValue;
+export declare function getDefaultKewaInstance(): KewaAnalytics;
+export {};