schoolx-ota-manager/README.md

React Native library for managing OTA updates with GitLab integration

# React Native OTA Manager

A React Native library for managing Over-The-Air (OTA) updates with GitLab integration. This library provides automatic version checking, bundle downloading, and installation for React Native apps.

## Features

- ✅ **GitLab Integration**: Direct integration with GitLab repositories
- ✅ **Version Compatibility**: Smart version checking with range operators (>, >=, <, <=, =)
- ✅ **Build Number Tracking**: Automatic build number management
- ✅ **Platform Support**: iOS and Android support
- ✅ **Auto Update**: Configurable automatic update checking
- ✅ **Progress Tracking**: Real-time update progress callbacks
- ✅ **No UI**: Pure logic component, integrate with your own UI

## Installation

```bash
npm install schoolx-ota-manager
# or
yarn add schoolx-ota-manager
```

## Dependencies

Make sure you have these dependencies installed:

```bash
npm install react-native-device-info react-native-ota-hot-update react-native-fs @react-native-async-storage/async-storage axios
```

## Quick Start

### 1. Basic Usage with Component

```tsx
import React, { useRef } from 'react';
import { OTAUpdate } from 'schoolx-ota-manager';

const App = () => {
  const otaRef = useRef();

  const handleProgress = (progress) => {
    console.log('Update progress:', progress.status, progress.message);
  };

  const handleUpdateAvailable = (hasUpdate) => {
    if (hasUpdate) {
      console.log('Update available!');
      // Trigger update installation
      otaRef.current?.installUpdate();
    }
  };

  return (
    <>
      <OTAUpdate
        ref={otaRef}
        gitlabToken="your-gitlab-token"
        gitlabProjectId="your-project-id"
        gitlabBaseUrl="https://gitlab.com/api/v4"
        repoFolder="schoolx-parent"
        onProgress={handleProgress}
        onUpdateAvailable={handleUpdateAvailable}
      />
      {/* Your app content */}
    </>
  );
};
```

### 2. Advanced Usage with OtaManager

```tsx
import React, { useEffect } from 'react';
import { OtaManager } from 'schoolx-ota-manager';

const App = () => {
  useEffect(() => {
    const otaManager = new OtaManager({
      gitlabToken: 'your-gitlab-token',
      gitlabProjectId: 'your-project-id',
      gitlabBaseUrl: 'https://gitlab.com/api/v4',
      repoFolder: 'schoolx-parent',
      platform: 'ios', // or 'android'
      autoUpdate: false,
      checkInterval: 300000
    });

    // Set progress callback
    otaManager.onProgress((progress) => {
      console.log('Progress:', progress);
    });

    // Start auto checking
    otaManager.startAutoCheck();

    // Manual check
    otaManager.checkUpdate().then(updateInfo => {
      if (updateInfo.hasUpdate) {
        otaManager.installUpdate();
      }
    });

    return () => {
      otaManager.stopAutoCheck();
    };
  }, []);

  return (
    // Your app content
  );
};
```

## Configuration

### OtaConfig

```typescript
interface OtaConfig {
  gitlabToken: string;           // GitLab private token
  gitlabProjectId: string;       // GitLab project ID
  gitlabBaseUrl: string;         // GitLab API base URL
  repoFolder: string;            // Repository folder name
  platform: 'ios' | 'android';   // Target platform
  autoUpdate?: boolean;          // Auto install updates
}
```

### Version Format

The `version` field in your `version.json` supports range operators:

```json
{
  "ios": {
    "version": ">=1.0.0",        // App version >= 1.0.0
    "buildNumber": 20241215001,
    "bundleType": "bytecode",
    "commitId": "main",
    "bundlePath": "ios/main.ios.hbc.jsbundle",
    "isForced": false,
    "releaseNotes": "Bug fixes and performance improvements"
  }
}
```

Supported operators: `>`, `>=`, `<`, `<=`, `=` (or no operator for exact match)

## API Reference

### OTAUpdate Component

#### Props
- `gitlabToken`: GitLab private token
- `gitlabProjectId`: GitLab project ID
- `gitlabBaseUrl`: GitLab API base URL
- `repoFolder`: Repository folder name
- `onProgress`: Progress callback
- `onUpdateAvailable`: Update availability callback
- `onUpdateCompleted`: Update completion callback

#### Ref Methods
- `checkUpdate()`: Check for updates
- `installUpdate()`: Install available update
- `checkAndInstallUpdate()`: Check and install if available
- `checkOnAppStart()`: Check for updates when app starts
- `getInstalledBuildNumber()`: Get current build number

### OtaManager Class

#### Methods
- `checkUpdate()`: Check for updates
- `installUpdate()`: Download and install update
- `checkAndInstallUpdate()`: Check and install if available
- `checkOnAppStart()`: Check for updates when app starts
- `onProgress(callback)`: Set progress callback

## File Structure

Your GitLab repository should have this structure:

```
your-repo/
├── version.json
├── ios/
│   └── hermes.ios.hbc.zip
└── android/
    └── hermes.android.hbc.zip
```

## Example version.json

```json
{
  "android": {
    "version": ">=1.0.0",
    "buildNumber": 20241215001,
    "bundleType": "bytecode",
    "commitId": "main",
    "bundlePath": "android/index.android.hbc.bundle",
    "isForced": false,
    "releaseNotes": "Bug fixes and performance improvements"
  },
  "ios": {
    "version": ">=1.0.0",
    "buildNumber": 20241215001,
    "bundleType": "bytecode",
    "commitId": "main",
    "bundlePath": "ios/main.ios.hbc.jsbundle",
    "isForced": false,
    "releaseNotes": "Bug fixes and performance improvements"
  }
}
```

## License

MIT