com-tapp-so-sdk 0.1.0

package/ComTappSoSdk.podspec

@@ -0,0 +1,50 @@
+require "json"
+
+# Define the minimum iOS version supported
+min_ios_version_supported = "13.0"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32'
+
+Pod::Spec.new do |s|
+  s.name         = "ComTappSoSdk"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://www.tapp.so/.git", :tag => "#{s.version}" }
+
+  # Conditionally include source files.
+  # In legacy mode (RCT_NEW_ARCH_ENABLED != '1') exclude files in the generated folder.
+  if ENV['RCT_NEW_ARCH_ENABLED'] == '1'
+    s.source_files = "ios/**/*.{h,m,mm,cpp}"
+  else
+    s.source_files = Dir.glob("ios/**/*.{h,m,mm,cpp}").reject { |path| path.include?("generated") }
+  end
+
+  # Use install_modules_dependencies helper if available (RN >= 0.71.0).
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+
+    # If the new architecture is enabled, add extra dependencies and flags.
+    if ENV['RCT_NEW_ARCH_ENABLED'] == '1'
+      s.compiler_flags = "#{folly_compiler_flags} -DRCT_NEW_ARCH_ENABLED=1"
+      s.pod_target_xcconfig = {
+          "HEADER_SEARCH_PATHS"      => "\"$(PODS_ROOT)/boost\"",
+          "OTHER_CPLUSPLUSFLAGS"     => "-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1",
+          "CLANG_CXX_LANGUAGE_STANDARD" => "c++17"
+      }
+      s.dependency "React-Codegen"
+      s.dependency "RCT-Folly"
+      s.dependency "RCTRequired"
+      s.dependency "RCTTypeSafety"
+      s.dependency "ReactCommon/turbomodule/core"
+    end
+  end
+  s.dependency "Tapp"
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 tapp.so
+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,263 @@
+# Tapp React Native SDK
+
+The official React Native SDK for [Tapp](https://www.tapp.so/) — the growth and attribution platform for modern apps.
+
+![npm version](https://img.shields.io/npm/v/com-tapp-so-sdk)
+![license](https://img.shields.io/npm/l/com-tapp-so-sdk)
+![platform](https://img.shields.io/badge/platform-ios%20%7C%20android-lightgrey)
+
+## Overview
+
+The Tapp React Native SDK allows you to integrate Tapp's powerful attribution and event tracking into your iOS and Android applications. With this SDK, you can:
+
+- **Track Events**: Monitor user actions like purchases, registrations, and custom interactions.
+- **Deep Linking**: Handle deferred deep links to attribute installs and route users to specific content.
+- **Affiliate Integration**: Generate dynamic tracking URLs for influencers and partners.
+- **Cross-Platform Support**: Seamlessly unified API for both iOS and Android.
+
+## Features
+
+- 🚀 **Easy Initialization**: Single configuration step for both platforms.
+- 📊 **Event Tracking**: 40+ predefined event types plus support for custom events.
+- 🔗 **Deep Linking**: Robust support for direct and deferred deep linking.
+- 🌐 **Affiliate URL Generation**: Create tracking links programmatically.
+- ⚡ **TurboModules Support**: Ready for React Native's New Architecture.
+
+## Requirements
+
+- **React Native**: >= 0.70.0
+- **iOS**: 13.0+
+- **Android**: 5.0+ (API Level 21+)
+- **TypeScript**: 5.0+ (recommended)
+
+## Installation
+
+1. Install the package using `yarn` or `npm`:
+
+```sh
+yarn add com-tapp-so-sdk
+# or
+npm install com-tapp-so-sdk
+```
+
+2. **iOS Only**: Install CocoaPods dependencies.
+
+```sh
+cd ios && pod install
+```
+
+3. **Android**: No extra steps required (auto-linked).
+
+## Configuration
+
+To start using the SDK, you need to initialize it with your unique **App Token** and **Auth Token** from the [Tapp Dashboard](https://dashboard.tapp.so).
+
+It is recommended to initialize the SDK early in your app's lifecycle, such as in your root App component `useEffect`.
+
+```tsx
+import React, { useEffect } from 'react';
+import { start } from 'com-tapp-so-sdk';
+
+const App = () => {
+  useEffect(() => {
+    start({
+      authToken: 'YOUR_AUTH_TOKEN',
+      tappToken: 'YOUR_TAPP_TOKEN',
+      env: 'SANDBOX', // or 'PRODUCTION'
+    });
+  }, []);
+
+  return <YourAppContent />;
+};
+```
+
+> **Note**: Use `env: 'SANDBOX'` for development/testing and change to `'PRODUCTION'` for App Store/Play Store builds.
+
+## Usage
+
+### 1. Tracking Events
+
+Track standard or custom events to measure user engagement and campaign performance.
+
+**Standard Event:**
+
+```tsx
+import { handleTappEvent, EventAction } from 'com-tapp-so-sdk';
+
+// Track a "Purchase" event
+await handleTappEvent({
+  eventAction: EventAction.TAPP_PURCHASE,
+  metadata: {
+    price: 29.99,
+    currency: 'USD',
+    product_id: 'prod_123',
+    success: true,
+  },
+});
+```
+
+**Custom Event:**
+
+```tsx
+// Track a custom event with a specific name
+await handleTappEvent({
+  eventAction: EventAction.CUSTOM,
+  customValue: 'my_custom_action',
+  metadata: {
+    level_achieved: 5,
+    score: 1200,
+  },
+});
+```
+
+### 2. Deep Linking & Attribution
+
+Retrieve attribution data when your app is opened via a Tapp link.
+
+**Fetch Deferred Link Data (First Launch):**
+
+```tsx
+import { fetchOriginLinkData } from 'com-tapp-so-sdk';
+
+const checkAttribution = async () => {
+  const result = await fetchOriginLinkData();
+  
+  if (!result.error) {
+    console.log('Attribution Data:', result.data);
+    console.log('Campaign:', result.data?.campaign);
+    console.log('Is First Session:', result.isFirstSession);
+  } else {
+    // Note: This is NOT a fatal error, just means no attribution data was found or config is empty
+    console.log('Attribution Info:', result.message);
+  }
+};
+```
+
+**Handling Deep Links (Runtime):**
+
+```tsx
+import { Linking } from 'react-native';
+import { fetchLinkData, shouldProcess } from 'com-tapp-so-sdk';
+
+// In your deep link handler
+const handleUrl = async (url: string) => {
+  // shouldProcess is async to support both architectures safely
+  const canProcess = await shouldProcess(url);
+  
+  if (canProcess) {
+    const linkData = await fetchLinkData(url);
+    if (!linkData.error) {
+      console.log('Tapp Deep Link Data:', linkData);
+      console.log('Target Content:', linkData.tappUrl);
+    }
+  } else {
+    // Handle standard deep link
+  }
+};
+
+// Listen for incoming links
+Linking.addEventListener('url', ({ url }) => handleUrl(url));
+```
+
+### 3. Generate Affiliate URLs
+
+Create shareable tracking links for your users (e.g., "Invite a Friend").
+
+```tsx
+import { url } from 'com-tapp-so-sdk';
+
+const generateInviteLink = async () => {
+  try {
+    const inviteLink = await url(
+      'user_123',           // Influencer/User ID
+      'summer_promo',       // Ad Group (optional)
+      'banner_v1',          // Creative (optional)
+      { source: 'app_share' } // Custom Data (optional)
+    );
+    console.log('Share this link:', inviteLink);
+  } catch (error) {
+    console.error('Failed to generate link:', error);
+  }
+};
+```
+
+## API Reference
+
+### `start(config: InitConfig): void`
+
+Initializes the SDK.
+
+- `authToken`: Your API authentication token.
+- `tappToken`: Your unique App token.
+- `env`: `'PRODUCTION'` | `'SANDBOX'`.
+
+### `handleTappEvent(event: TappEventType): Promise<string>`
+
+Tracks a user event.
+
+- `eventAction`: One of `EventAction` enums (e.g., `TAPP_LOGIN`, `TAPP_PURCHASE`).
+- `customValue`: String identifier for `EventAction.CUSTOM`.
+- `metadata`: Object `{ [key: string]: string | number | boolean }`.
+
+### `fetchOriginLinkData(): Promise<TappLinkDataResponse>`
+
+Fetches attribution data for the current installation/session (deferred deep linking).
+
+**Response (`TappLinkDataResponse`):**
+- `error`: `boolean` — Indicates if the SDK encountered an issue (e.g. network error).
+- `message`: `string | null` — Error description or info message.
+- `tappUrl`: `string | null` — The deep link URL.
+- `attrTappUrl`: `string | null` — The attributed URL.
+- `influencer`: `string | null` — The influencer associated with the link.
+- `data`: `{ [key: string]: string }` — Custom link data (never null, empty object if none).
+- `isFirstSession`: `boolean` — `true` if this is the first app launch.
+
+### `fetchLinkData(deepLink: string): Promise<TappLinkDataResponse>`
+
+Resolves link data for a specific URL string (used for direct deep linking).
+
+**Returns**: Same response shape as `fetchOriginLinkData`.
+
+### `shouldProcess(deepLink: string): Promise<boolean>`
+
+Checks if the provided URL should be processed by the Tapp SDK.
+Returns `true` if it matches Tapp domains/schemes, `false` otherwise.
+
+### `url(influencer: string, adGroup?: string, creative?: string, data?: object): Promise<string>`
+
+Generates a tracking URL for the specified parameters.
+
+## SDK Guarantees
+
+- **No Throw on Attribution**: `fetchOriginLinkData` and `fetchLinkData` do **not** reject (throw) for standard SDK states (e.g., empty config, no attribution, network error). They resolve an object with `error: true` and a `message`. You should check `response.error` instead of using `try/catch`.
+- **Cross-Platform Consistency**: The response shapes for attribution data are identical on iOS and Android.
+- **Null Safety**: Optional string fields (`tappUrl`, `influencer`) are returned as `null` (not `undefined` or empty strings) when no value is present, allowing for strict type checking.
+
+## Architecture Notes
+
+### React Native New Architecture (Fabric/TurboModules)
+
+This SDK is fully compatible with React Native's New Architecture.
+- **Android**: Supports TurboModules via C++ bindings.
+- **iOS**: Fully implemented in Objective-C++ / Swift with TurboModule support enabled.
+
+No additional configuration is required; the SDK automatically detects the architecture enabled in your project.
+
+## Troubleshooting
+
+**iOS: Build Failures ("Swift compiler error" or "module not found")**
+- Ensure your iOS deployment target is 13.0 or higher.
+- Try cleaning pods: `cd ios && rm -rf Pods Podfile.lock && pod install`.
+- Ensure you open the `.xcworkspace` file, not the `.xcodeproj`.
+
+**Android: "SDK not initialized"**
+- Ensure `start()` is called immediately upon app launch.
+- Check that your `tappToken` matches the package name defined in the Tapp Dashboard.
+
+**Events not showing in Dashboard**
+- Check if `env` is set to `'SANDBOX'` while looking at live data (or vice versa).
+- Verify internet connectivity on the device/simulator.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/android/build.gradle

@@ -0,0 +1,114 @@
+// android/build.gradle (library)
+
+buildscript {
+    // Use project or root ext for Kotlin
+    def kotlin_version = rootProject.ext.has("kotlinVersion")
+        ? rootProject.ext.get("kotlinVersion")
+        : project.properties["ComTappSoSdk_kotlinVersion"]
+
+    repositories {
+        google()
+        mavenCentral()
+        maven { url 'https://jitpack.io' }
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:7.2.1"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+        // React Native Gradle plugin is usually applied via the settings/build of the app;
+        // for a library we only need the 'com.facebook.react' plugin below.
+    }
+}
+
+// --- Helpers (kept from your template) ---
+def getExtOrDefault(name) {
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["ComTappSoSdk_" + name]
+}
+def getExtOrIntegerDefault(name) {
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["ComTappSoSdk_" + name]).toInteger()
+}
+def supportsNamespace() {
+    def parsed = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')
+    def major = parsed[0].toInteger()
+    def minor = parsed[1].toInteger()
+    // Namespace support added in 7.3.0
+    return (major == 7 && minor >= 3) || major >= 8
+}
+def isNewArchitectureEnabled() {
+    return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+// --- Plugins ---
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react" // always apply; don’t gate behind newArch
+
+// --- React / Codegen (Android) ---
+// IMPORTANT:
+//   - libraryName MUST be the npm package name (from package.json "name")
+//   - do NOT set codegenDir (use RN default: android/build/generated/source/codegen)
+react {
+    libraryName = "com-tapp-so-sdk"
+    codegenJavaPackageName = "com.comtappsosdk"
+    // codegenDir = ...  <-- DO NOT set; RN expects default path
+}
+
+android {
+    if (supportsNamespace()) {
+        namespace "com.comtappsosdk"
+        // If you use a non-standard manifest filename:
+        sourceSets {
+            main {
+                manifest.srcFile "src/main/AndroidManifestNew.xml"
+            }
+        }
+    }
+
+    compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+    defaultConfig {
+        minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+        targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+
+        // Keep New Arch toggle available at runtime/build time
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+        // If you need NDK/CMake arch matrix, you can add abiFilters here (optional)
+    }
+
+    buildFeatures {
+        buildConfig true
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+
+    lintOptions {
+        disable "GradleCompatible"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    // ❌ DO NOT point to custom generated folders; RN will generate under:
+    //    android/build/generated/source/codegen/{java|jni}
+    // sourceSets { ... }  <-- removed on purpose
+}
+
+repositories {
+    mavenCentral()
+    google()
+    maven { url 'https://jitpack.io' }
+}
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:${getExtOrDefault('kotlinVersion')}"
+
+  implementation("com.github.tapp-so.Tapp-Android:Tapp-Native:1.1.3")
+}
+
+// namespace "com.comtappsosdk"
+//ComTappSoSdk

package/android/gradle.properties

@@ -0,0 +1,5 @@
+ComTappSoSdk_kotlinVersion=2.0.21
+ComTappSoSdk_minSdkVersion=24
+ComTappSoSdk_targetSdkVersion=34
+ComTappSoSdk_compileSdkVersion=35
+ComTappSoSdk_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>