@linkforty/mobile-sdk-react-native 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to the LinkForty React Native SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-11-22
+
+### Added
+- Initial release of LinkForty React Native SDK
+- **Deferred Deep Linking** - Route new users to specific content after install
+- **Direct Deep Linking** - Handle Universal Links (iOS) and App Links (Android)
+- **Probabilistic Attribution** - Match installs to clicks with 70%+ confidence
+- **Event Tracking** - Track in-app events with attribution
+- **Privacy-Focused** - No persistent device IDs required
+- **TypeScript Support** - Full type definitions included
+- **Works with Core & Cloud** - Compatible with self-hosted and Cloud instances
+
+### Core Features
+
+#### SDK Initialization
+- `init(config)` - Initialize SDK with base URL and optional API key
+- Support for debug logging during development
+- Customizable attribution window (default: 7 days)
+
+#### Deep Linking
+- `onDeferredDeepLink(callback)` - Handle deferred deep links for new installs
+- `onDeepLink(callback)` - Handle direct deep links for existing users
+- Automatic Universal Links (iOS) and App Links (Android) configuration
+- Deep link data includes UTM parameters and custom parameters
+
+#### Event Tracking
+- `trackEvent(name, properties)` - Track in-app events with optional properties
+- Automatic attribution to install source
+- Webhook triggers for conversion events
+- Support for revenue tracking and custom event properties
+
+#### Data Management
+- `getInstallData()` - Retrieve cached install attribution data
+- `getInstallId()` - Get unique install ID for this app installation
+- `clearData()` - Clear all cached SDK data (useful for testing)
+
+### Device Fingerprinting
+
+Collects the following non-invasive signals for probabilistic attribution:
+- User agent string
+- Device timezone
+- Device language
+- Screen resolution
+- Platform (iOS/Android)
+- Device model and OS version
+- IP address (server-side only)
+
+### API Endpoints
+
+Uses the following LinkForty Core API endpoints:
+- `POST /api/sdk/v1/install` - Report app installation
+- `POST /api/sdk/v1/event` - Track in-app events
+- `GET /api/sdk/v1/attribution/:fingerprint` - Debug attribution data
+- `GET /api/sdk/v1/health` - Health check
+
+### Dependencies
+
+**Peer Dependencies:**
+- `react` >= 16.8.0
+- `react-native` >= 0.60.0
+
+**Runtime Dependencies:**
+- `@react-native-async-storage/async-storage` ^1.21.0
+- `react-native-device-info` ^10.12.0
+
+### Platform Support
+
+- ✅ iOS 12+
+- ✅ Android 5.0+ (API level 21+)
+- ✅ React Native 0.60+
+- ✅ TypeScript 5.3+
+- ✅ Expo (with custom native modules)
+
+### Security
+
+- No persistent device identifiers stored
+- Privacy-focused fingerprinting
+- Configurable attribution window
+- Secure HTTPS-only communication
+- No third-party tracking SDKs
+
+### Documentation
+
+- Comprehensive README with setup instructions
+- TypeScript type definitions included
+- iOS Universal Links setup guide
+- Android App Links setup guide
+- Troubleshooting guide
+- API reference with examples
+
+---
+
+## [Unreleased]
+
+### Changed
+- Removed unused dependencies `@onamfc/developer-log` and `@onamfc/pkg-inspect` to reduce bundle size
+
+### Planned Features
+- iOS SDK (Native Swift) - Q2 2025
+- Android SDK (Native Kotlin) - Q2 2025
+- React Native Expo compatibility mode
+- Offline event queue for poor network conditions
+- Advanced debugging tools
+- Custom domain support
+- A/B testing integration
+- User segmentation
+
+---
+
+## Version History
+
+- **1.0.0** - Initial release (2024-11-22)
+
+## Migration Guides
+
+### Upgrading to 1.0.0
+
+This is the initial release, so no migration is necessary.
+
+## Support
+
+For issues, questions, or feature requests:
+- GitHub Issues: https://github.com/linkforty/react-native-sdk/issues
+- Documentation: https://docs.linkforty.com
+- Discord Community: https://discord.gg/linkforty
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/CONTRIBUTING.md

@@ -0,0 +1,340 @@
+# Contributing to LinkForty React Native SDK
+
+Thank you for your interest in contributing to the LinkForty React Native SDK! We welcome contributions from the community and are grateful for your support.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Testing Guidelines](#testing-guidelines)
+- [Reporting Bugs](#reporting-bugs)
+- [Feature Requests](#feature-requests)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our commitment to creating a welcoming and inclusive environment. Please be respectful and constructive in your interactions.
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally
+3. **Create a branch** for your changes
+4. **Make your changes**
+5. **Test your changes** thoroughly
+6. **Submit a pull request**
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 20+ and npm 10+
+- React Native development environment (iOS and/or Android)
+- React Native 0.76+
+- TypeScript 5.9+
+- Git
+
+### Installation
+
+```bash
+# Clone your fork
+git clone https://github.com/linkforty/react-native-sdk.git
+cd react-native-sdk
+
+# Install dependencies
+npm install
+
+# Build the TypeScript code
+npm run build
+```
+
+### Project Structure
+
+```
+linkforty-react-native-sdk/
+├── src/
+│   ├── index.ts              # Main export file
+│   ├── LinkFortySDK.ts       # Core SDK class
+│   ├── DeepLinkHandler.ts    # Deep link handling
+│   ├── FingerprintCollector.ts # Device fingerprinting
+│   └── types.ts              # TypeScript type definitions
+├── dist/                     # Compiled JavaScript (generated)
+├── package.json
+├── tsconfig.json
+├── README.md
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+└── LICENSE
+```
+
+### Building
+
+```bash
+# Build TypeScript to JavaScript
+npm run build
+
+# Watch mode for development
+npm run build -- --watch
+```
+
+## How to Contribute
+
+### Types of Contributions
+
+We welcome many types of contributions:
+
+- **Bug fixes**
+- **New features**
+- **Documentation improvements**
+- **Code quality improvements**
+- **Test coverage additions**
+- **Platform compatibility fixes**
+- **Examples and tutorials**
+
+### Before You Start
+
+1. **Check existing issues** to see if someone is already working on it
+2. **Open an issue** to discuss major changes before implementing
+3. **Keep pull requests focused** - one feature/fix per PR
+4. **Follow the coding standards** outlined below
+
+## Pull Request Process
+
+### 1. Create a Feature Branch
+
+```bash
+git checkout -b feature/my-new-feature
+# or
+git checkout -b fix/bug-description
+```
+
+### 2. Make Your Changes
+
+- Write clear, concise commit messages
+- Follow the existing code style
+- Add/update tests if applicable
+- Update documentation as needed
+
+### 3. Test Your Changes
+
+```bash
+# Build the SDK
+npm run build
+
+# Test in a sample React Native app
+cd ../sample-app
+npm install ../linkforty-react-native-sdk
+
+# Test on both iOS and Android if possible
+npx react-native run-ios
+npx react-native run-android
+```
+
+
+### 4. Commit Your Changes
+
+```bash
+git add .
+git commit -m "feat: add custom attribution window support"
+```
+
+**Commit Message Format:**
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `style:` Code style changes (formatting, etc.)
+- `refactor:` Code refactoring
+- `test:` Adding or updating tests
+- `chore:` Maintenance tasks
+
+### 5. Push and Create PR
+
+```bash
+git push origin feature/my-new-feature
+```
+
+Then open a Pull Request on GitHub with:
+- Clear title describing the change
+- Description of what changed and why
+- Link to any related issues
+- Screenshots/videos if UI-related
+- Testing instructions
+
+## Coding Standards
+
+### TypeScript
+
+- Use TypeScript for all new code
+- Provide type definitions for all public APIs
+- Avoid `any` types when possible
+- Use interfaces for public types
+- Export all public types from `types.ts`
+
+### Code Style
+
+```typescript
+// ✅ Good
+export async function trackEvent(
+  name: string,
+  properties?: Record<string, any>
+): Promise<void> {
+  if (!this.config) {
+    throw new Error('SDK not initialized. Call init() first.');
+  }
+
+  // Implementation...
+}
+
+// ❌ Avoid
+export async function trackEvent(name,properties) {
+  if(!this.config) throw new Error('SDK not initialized. Call init() first.');
+  // Implementation...
+}
+```
+
+### Best Practices
+
+- **Error Handling**: Always handle errors gracefully
+- **Logging**: Use debug mode for verbose logging
+- **Privacy**: Never log sensitive user data
+- **Performance**: Minimize network requests and storage operations
+- **Compatibility**: Support React Native 0.60+
+- **Platform-Specific**: Use Platform.select() when needed
+
+### Documentation
+
+```typescript
+/**
+ * Track an in-app event with optional properties
+ *
+ * @param name - Event name (e.g., 'purchase', 'signup')
+ * @param properties - Optional event properties
+ * @returns Promise that resolves when event is tracked
+ *
+ * @example
+ * ```typescript
+ * await LinkForty.trackEvent('purchase', {
+ *   amount: 99.99,
+ *   currency: 'USD',
+ *   productId: 'premium_plan'
+ * });
+ * ```
+ */
+async trackEvent(
+  name: string,
+  properties?: Record<string, any>
+): Promise<void>
+```
+
+## Testing Guidelines
+
+### Manual Testing Checklist
+
+Before submitting a PR, test the following:
+
+**iOS:**
+- [ ] Universal Links work correctly
+- [ ] Deferred deep links attribute on first install
+- [ ] Direct deep links open the app
+- [ ] Event tracking works
+- [ ] No crashes or errors in debug mode
+
+**Android:**
+- [ ] App Links work correctly
+- [ ] Deferred deep links attribute on first install
+- [ ] Direct deep links open the app
+- [ ] Event tracking works
+- [ ] No crashes or errors in debug mode
+
+**Both Platforms:**
+- [ ] TypeScript types are correct
+- [ ] Documentation is accurate
+- [ ] No breaking API changes (or documented)
+- [ ] Performance is acceptable
+- [ ] Privacy requirements met
+
+### Test Scenarios
+
+1. **Fresh Install Attribution**
+   - Click a link in mobile browser
+   - Install app from store
+   - Verify `onDeferredDeepLink` receives attribution data
+
+2. **Direct Deep Link**
+   - App is already installed
+   - Click a link in mobile browser
+   - Verify `onDeepLink` is called with correct data
+
+3. **Event Tracking**
+   - Track various events
+   - Verify events appear in backend
+   - Verify webhooks are triggered (if configured)
+
+4. **Edge Cases**
+   - No internet connection
+   - Invalid deep link URLs
+   - Backend server errors
+   - Concurrent SDK calls
+
+## Reporting Bugs
+
+### Before Reporting
+
+1. **Check existing issues** to avoid duplicates
+2. **Update to latest version** to see if it's already fixed
+3. **Test in a fresh React Native project** to isolate the issue
+
+### Bug Report Template
+
+```markdown
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Initialize SDK with '...'
+2. Call method '...'
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened.
+
+**Environment:**
+- OS: [e.g., iOS 17.0, Android 14]
+- React Native version: [e.g., 0.72.0]
+- SDK version: [e.g., 1.0.0]
+- Device: [e.g., iPhone 14 Pro, Pixel 7]
+
+**Logs**
+```typescript
+// Relevant error logs or stack traces
+```
+
+**Additional context**
+Any other context about the problem.
+
+## Feature Requests
+
+We love feature requests! Please include:
+
+1. **Use case** - Why do you need this feature?
+2. **Proposed solution** - How do you think it should work?
+3. **Alternatives** - What alternatives have you considered?
+4. **Platform** - Is this iOS-specific, Android-specific, or both?
+
+## Questions?
+
+- **GitHub Issues**: For bugs and feature requests
+
+## License
+
+By contributing to LinkForty React Native SDK, you agree that your contributions will be licensed under the MIT License.
+
+
+Thank you for making LinkForty better! 🎉

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LinkForty
+
+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.