@capillarytech/react-native-hydra-lib 1.7.0-beta.1

package/README.md

@@ -0,0 +1,491 @@
+# @capillary/react-native-hydra-lib
+
+[![npm version](https://badge.fury.io/js/@capillary%2Freact-native-hydra-lib.svg)](https://badge.fury.io/js/@capillary%2Freact-native-hydra-lib)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![React Native](https://img.shields.io/badge/React%20Native-0.77.0-blue.svg)](https://reactnative.dev/)
+
+A comprehensive React Native library that provides seamless integration with Hydra native iOS and Android SDKs, enabling powerful mobile engagement and analytics capabilities.
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Platform-Specific Setup](#platform-specific-setup)
+- [Security & Compliance](#security--compliance)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Troubleshooting](#troubleshooting)
+- [Changelog](#changelog)
+- [Support](#support)
+- [License](#license)
+
+## Features
+
+✨ **Core Capabilities**
+
+- 🚀 **Native Performance**: Direct integration with iOS and Android native SDKs
+- 📱 **Cross-Platform**: Unified API for both iOS and Android platforms
+- 🔧 **TypeScript Support**: Full TypeScript definitions and IntelliSense
+- 🎯 **Modern Architecture**: Built with latest React Native Turbo Modules
+
+🛡️ **Security & Compliance**
+
+- 📋 **SBOM Generation**: Automatic Software Bill of Materials creation
+- 🔒 **Supply Chain Security**: Comprehensive dependency tracking
+- 📊 **Compliance Ready**: SPDX 2.3 format support for enterprise requirements
+
+🔄 **Developer Experience**
+
+- 📚 **Comprehensive Documentation**: Detailed guides and examples
+- ⚡ **Hot Reload Support**: Seamless development experience
+- 🧪 **Example App**: Full-featured example implementation
+- 🔧 **Easy Integration**: Simple setup with minimal configuration
+
+## Requirements
+
+| Platform         | Version                 |
+| ---------------- | ----------------------- |
+| **React Native** | >= 0.72.0               |
+| **iOS**          | >= 13.0                 |
+| **Android**      | >= API 21 (Android 5.0) |
+| **Node.js**      | >= 18.0.0               |
+| **targetSdk**    | >= 32                   |
+| **compileSdk**   | >= 32                   |
+
+## Installation
+
+### Using npm
+
+```bash
+npm install @capillary/react-native-hydra-lib
+```
+
+## Project Setup
+
+Before you start development, you need to set up your environment:
+
+1. Create a `.env` file in the project root with the following variables:
+
+```sh
+HYDRA_GITHUB_USER_NAME=your_github_username
+HYDRA_IOS_GITHUB_PAT=your_github_personal_access_token
+```
+
+2. Run the setup script:
+
+```sh
+./scripts/setup_local.sh
+```
+
+This script will:
+
+- Configure your GitHub credentials for accessing private repositories
+- Set up necessary environment variables
+- Configure Git authentication for Capillary repositories
+
+Note: The setup script will run automatically when you install dependencies in the example app.
+
+### Using yarn
+
+```bash
+yarn add @capillary/react-native-hydra-lib
+```
+
+### Post-Installation Setup
+
+After installation, the library automatically generates SBOM (Software Bill of Materials) files for security and compliance tracking.
+
+#### iOS Setup
+
+```bash
+cd ios && pod install
+```
+
+#### Android Setup
+
+No additional setup required for Android.
+
+## Quick Start
+
+### Basic Integration
+
+```typescript
+import { HydraLib } from '@capillary/react-native-hydra-lib';
+
+// Initialize using Firebase Remote Config
+// This is the recommended way to initialize the SDK
+const initializeHydra = async () => {
+  try {
+    await HydraLib.setFirebaseRemoteConfigKeys({
+      keyForAccountId: 'hydra_account_id',
+      keyForBaseUrl: 'hydra_base_url',
+      keyForSsl: 'hydra_ssl_public_key',
+      keyForRemoteLogLevel: 'hydra_remote_log_level'
+    });
+    console.log('Hydra SDK initialized successfully');
+  } catch (error) {
+    console.error('Failed to initialize Hydra SDK:', error);
+  }
+};
+
+// Alternative: Initialize using Account Config directly
+const initializeWithAccountConfig = async () => {
+  try {
+    await HydraLib.setHydraAccountConfig({
+      accountId: 'your-account-id',
+      baseUrl: 'your-base-url',
+      sslPublicKey: 'your-ssl-public-key',
+      remoteDebugLevel: 4 // 0-5, where 0 is off and 5 is verbose
+    });
+    console.log('Hydra SDK initialized successfully');
+  } catch (error) {
+    console.error('Failed to initialize Hydra SDK:', error);
+  }
+};
+
+// Call during app startup
+initializeHydra();
+```
+
+
+## API Reference
+
+### Core Methods
+
+#### `setFirebaseRemoteConfigKeys(keys: HydraFirebaseRemoteConfigKeys): Promise<void>`
+
+Initializes the Hydra SDK using Firebase Remote Config keys.
+
+**Parameters:**
+
+- `keys`: Object containing Firebase Remote Config key names
+  - `keyForAccountId`: Key for account ID in Firebase Remote Config
+  - `keyForBaseUrl`: Key for base URL in Firebase Remote Config
+  - `keyForSsl`: Key for SSL public key in Firebase Remote Config
+  - `keyForRemoteLogLevel`: Key for remote debug level in Firebase Remote Config
+
+**Example:**
+
+```typescript
+await HydraLib.setFirebaseRemoteConfigKeys({
+  keyForAccountId: 'hydra_account_id',
+  keyForBaseUrl: 'hydra_base_url',
+  keyForSsl: 'hydra_ssl_public_key',
+  keyForRemoteLogLevel: 'hydra_remote_log_level'
+});
+```
+
+#### `setHydraAccountConfig(config: HydraAccountConfig): Promise<void>`
+
+Sets the Hydra account configuration directly without using Firebase Remote Config.
+
+**Parameters:**
+
+- `config`: Account configuration object
+  - `accountId`: Your Hydra account ID
+  - `baseUrl`: Base URL for the Hydra API
+  - `sslPublicKey`: SSL public key for secure communication
+  - `remoteDebugLevel`: Debug level (0-5, where 0 is off and 5 is verbose)
+
+**Example:**
+
+```typescript
+await HydraLib.setHydraAccountConfig({
+  accountId: 'your-account-id',
+  baseUrl: 'your-base-url',
+  sslPublicKey: 'your-ssl-public-key',
+  remoteDebugLevel: 4
+});
+```
+
+#### `signIn(userDetails: UserDetails, customData?: object): Promise<void>`
+
+Signs in a user with the provided details.
+
+**Parameters:**
+
+- `userDetails`: User profile information
+- `customData`: Optional custom attributes
+
+**Example:**
+
+```typescript
+await HydraLib.signIn({
+  userId: 'user123',
+  email: 'user@example.com'
+}, {
+  preferences: ['tech', 'mobile']
+});
+```
+
+#### `signOut(customerId: string): Promise<void>`
+
+Signs out the user with the specified customer ID.
+
+**Parameters:**
+
+- `customerId`: The ID of the customer to sign out
+
+**Example:**
+
+```typescript
+await HydraLib.signOut('user123');
+```
+
+### Messaging Methods
+
+#### `showNotificationCenter(): Promise<void>`
+
+Displays the notification center UI.
+
+#### `hideNotificationCenterIfShowing(): Promise<void>`
+
+Hides the notification center if it's currently visible.
+
+#### `getInboxMessages(): Promise<void>`
+
+Retrieves the list of inbox messages.
+
+#### `getUnreadInboxMessagesCount(): Promise<number>`
+
+Returns the number of unread inbox messages.
+
+### Utility Methods
+
+#### `getSDKVersion(): Promise<string>`
+
+Returns the current SDK version.
+
+#### `isInitialized(): Promise<boolean>`
+
+Checks if the SDK is properly initialized.
+
+## Platform-Specific Setup
+
+### iOS Configuration
+
+Add the following to your `ios/YourApp/Info.plist`:
+
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>This app uses location for personalized content</string>
+<key>NSUserNotificationUsageDescription</key>
+<string>This app sends notifications for important updates</string>
+```
+
+### Android Configuration
+
+Add permissions to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:required="false" />
+```
+
+## Security & Compliance
+
+### SBOM (Software Bill of Materials)
+
+This library automatically generates SBOM files for security and compliance tracking:
+
+- **Main Project SBOM**: `sbom.spdx.json` (generated in project root)
+- **Example Project SBOM**: `example/example_sbom.spdx.json`
+
+#### SBOM Generation
+
+The SBOM is automatically generated during:
+
+- Package installation (`postinstall` script)
+- Manual execution: `npm run generate-sbom`
+
+#### SBOM Features
+
+- ✅ **SPDX 2.3 Compliant**: Industry standard format
+- ✅ **Comprehensive Coverage**: All dependencies tracked
+- ✅ **Automatic Updates**: Regenerated when dependencies change
+- ✅ **Supply Chain Security**: Complete dependency lineage
+- ✅ **Enterprise Ready**: Compliance with security requirements
+
+### Deprecation Policy
+
+We follow a structured deprecation policy to ensure smooth transitions:
+
+- **📅 Advance Notice**: 6-12 months before removal
+- **🔄 Migration Support**: Comprehensive guides and examples
+- **⚠️ Clear Warnings**: Development-time deprecation warnings
+- **📚 Documentation**: Detailed migration paths
+
+For complete details, see our [Deprecation Policy](./DEPRECATION_POLICY.md).
+
+## Development
+
+### Running the Example App
+
+```bash
+# Install dependencies
+yarn install
+
+# iOS
+yarn example ios
+
+# Android
+yarn example android
+```
+
+### Building the Library
+
+```bash
+# Build TypeScript
+yarn prepare
+
+# Run tests
+yarn test
+
+# Lint code
+yarn lint
+
+# Type checking
+yarn typecheck
+```
+
+### Scripts
+
+| Script               | Description              |
+| -------------------- | ------------------------ |
+| `yarn test`          | Run tests                |
+| `yarn typecheck`     | TypeScript type checking |
+| `yarn lint`          | ESLint code linting      |
+| `yarn prepare`       | Build the library        |
+| `yarn generate-sbom` | Generate SBOM files      |
+| `yarn clean`         | Clean build artifacts    |
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+### Development Workflow
+
+1. **Fork** the repository
+2. **Clone** your fork
+3. **Create** a feature branch
+4. **Make** your changes
+5. **Test** your changes
+6. **Submit** a pull request
+
+### Code Standards
+
+- **TypeScript**: All code must be TypeScript
+- **ESLint**: Follow our linting rules
+- **Testing**: Add tests for new features
+- **Documentation**: Update docs for API changes
+
+## Troubleshooting
+
+### Common Issues
+
+#### Installation Issues
+
+**Problem**: `pod install` fails on iOS
+
+```bash
+# Solution: Clean and reinstall
+cd ios
+rm -rf Pods Podfile.lock
+pod install
+```
+
+**Problem**: Android build fails
+
+```bash
+# Solution: Clean and rebuild
+cd android
+./gradlew clean
+cd ..
+yarn android
+```
+
+#### Runtime Issues
+
+**Problem**: SDK initialization fails
+
+- Verify your API key is correct
+- Check network connectivity
+- Ensure required permissions are granted
+
+**Problem**: TypeScript errors
+
+```bash
+# Solution: Regenerate types
+yarn prepare
+```
+
+### Getting Help
+
+1. **Check Documentation**: Review this README and guides
+2. **Search Issues**: Look for existing solutions in GitHub issues
+3. **Ask Questions**: Create a new issue with detailed information
+4. **Community Support**: Join our discussions
+
+## Changelog & Release Notes
+
+### Quick Links
+
+- 📋 **[Changelog](./CHANGELOG.md)**: Complete change history in standard format
+- 📝 **[Release Notes](./RELEASE_NOTES.md)**: Detailed release information with examples
+- 🔄 **[Migration Guide](./MIGRATION.md)**: Version upgrade instructions
+- 📚 **[Deprecation Policy](./DEPRECATION_POLICY.md)**: How we handle deprecations
+
+### Recent Updates
+
+- **v1.3.0**: Added SBOM generation, multi-instance support, enhanced security
+- **v1.2.x**: Enhanced iOS and Android SDK integration, Firebase Remote Config
+- **v1.1.x**: Initial stable release with core features
+
+## Support
+
+### Documentation
+
+- 📚 **API Reference**: Detailed API documentation
+- 🎯 **Examples**: Working code examples
+- 🔧 **Platform Guides**: iOS and Android specific setup
+- 📋 **Migration Guides**: Version upgrade instructions
+
+### Community
+
+- 🐛 **Issues**: [GitHub Issues](https://github.com/Capillary/react-native-hydra-lib/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/Capillary/react-native-hydra-lib/discussions)
+- 📧 **Contact**: [rakesh.ostwal@capillarytech.com](mailto:rakesh.ostwal@capillarytech.com)
+
+### Enterprise Support
+
+For enterprise customers, we provide:
+
+- Priority support and SLA
+- Custom integration assistance
+- Security and compliance consulting
+- Training and onboarding
+
+Contact us at [enterprise@capillarytech.com](mailto:enterprise@capillarytech.com)
+
+## License
+
+MIT License - see the [LICENSE](./LICENSE) file for details.
+
+---
+
+## About Capillary Technologies
+
+[Capillary Technologies](https://www.capillarytech.com/) is a leading provider of customer engagement and commerce solutions. Our Hydra SDK enables businesses to create personalized, omnichannel experiences that drive customer loyalty and growth.
+
+---
+
+**Made with ❤️ by the Capillary Technologies team**
+
+_This library was created using [create-react-native-library](https://github.com/callstack/react-native-builder-bob)_
+
+