diff --git a/README.md b/README.md
index 444b5fe..544b763 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,18 @@
-# React Native Uploads SDK
+# FastPix React Native Uploads SDK - resumable, chunked video and file uploads for iOS and Android
-The **FastPix React Native Uploads SDK** provides reliable, resumable, and high-performance uploads for large files in React Native applications. It supports chunked uploads, automatic retries, pause and resume, network recovery, and real-time progress tracking on both Android and iOS.
+[](https://www.npmjs.com/package/@fastpix/react-native-uploads)
+[](https://www.npmjs.com/package/@fastpix/react-native-uploads)
+[](https://github.com/FastPix/react-native-uploader/blob/main/LICENSE)
+[](https://github.com/FastPix/react-native-uploader)
+[](https://www.typescriptlang.org/)
-> Please note that this SDK is designed to work only with **FastPix** and is not a general-purpose uploads SDK.
+The **FastPix React Native Uploads SDK** (`@fastpix/react-native-uploads`) provides reliable, resumable, high-performance uploads for large videos and files in React Native apps. It handles chunked uploads, automatic per-chunk retries, pause and resume, network recovery, and real-time progress tracking on both Android and iOS.
-## Table of Contents
+**Works with:** React Native 0.70+ · iOS 13+ · Android 5.0+ (API 21) · TypeScript · any file picker (`file://` URIs)
-- [Features](#features)
-- [Prerequisites](#prerequisites)
-- [Platform Support](#platform-support)
-- [Installation](#installation)
-- [Basic Usage](#basic-usage)
-- [Resumable Uploads: Pause, Resume & Network Recovery](#resumable-uploads-pause-resume--network-recovery)
-- [Chunk-Level Retry Tracking](#chunk-level-retry-tracking)
-- [Lifecycle Events Reference](#lifecycle-events-reference)
-- [Upload Control Methods](#upload-control-methods)
-- [API Reference](#api-reference)
- - [Configuration Parameters](#configuration-parameters)
-- [Example App](#example-app)
-- [Troubleshooting](#troubleshooting)
-- [Additional References](#additional-references)
+📖 **Docs:** https://fastpix.com/docs/upload-videos/upload-videos-from-device · 📦 **npm:** https://www.npmjs.com/package/@fastpix/react-native-uploads · 🚀 **Dashboard:** https://dashboard.fastpix.com
+
+> Note that this SDK is designed to work only with **FastPix** and is not a general-purpose uploads SDK.
## Features
@@ -32,9 +25,96 @@ The **FastPix React Native Uploads SDK** provides reliable, resumable, and high-
* **Flexible File URI Support** – Accepts `file://` URIs and plain filesystem paths, with automatic URL-decoding of percent-encoded paths.
* **Lifecycle Events** – Listen to upload progress, state changes, and completion events.
-## Prerequisites
+
+
+## Start here
+
+If you are using the FastPix React Native Uploads SDK for the first time, follow these steps in order:
+
+1. [Check your environment](#check-your-environment)
+2. [Install the SDK](#install-the-sdk)
+3. [Generate a signed upload URL](#generate-a-signed-upload-url)
+4. [Upload your first file](#upload-your-first-file)
+5. [Verify your upload](#verify-your-upload)
+6. [Understand the upload workflow](#understand-the-upload-workflow)
+
+Do not skip the verification steps. If an environment, install, or signed-URL problem occurs, fix it before continuing.
+
+
+
+### Before you begin
+
+To use the SDK, make sure you have:
+
+- Node.js 18 or later.
+- A React Native app (0.70+); if you do not have one, [Install the SDK](#install-the-sdk) shows how to create it.
+- iOS: Xcode and CocoaPods (macOS), plus an iOS Simulator or a physical iPhone (iOS 13+).
+- Android: JDK 17 and Android Studio (SDK and an emulator), or a physical Android device (Android 5.0 / API 21+).
+- A FastPix account, with an Access Token and a Secret Key.
+- A video or file to upload, available as a `file://` URI (typically from a media picker).
+
+#### Platform Support
+
+| Platform | Minimum version |
+| ------------ | ------------------ |
+| Android | API 21 (Android 5.0) |
+| iOS | iOS 13.0 |
+| React Native | 0.70+ |
+
+FastPix uploads use a **signed URL**: your Access Token and Secret Key stay on your backend and are never shipped in the app. You generate a short-lived signed URL on your server (see [Generate a signed upload URL](#generate-a-signed-upload-url)) and hand only that URL to the SDK.
+
+> **Security:** Never ship your Access Token or Secret Key in the app bundle. Generate signed URLs from your backend and return only the signed URL to the client.
+
+
+
+## Check your environment
+
+React Native needs Node plus a native build toolchain, not a single runtime. Check Node first:
+
+```bash
+node --version
+```
+
+The output should be `v18` or later. Then run the React Native environment doctor, which checks Xcode, CocoaPods, the JDK, the Android SDK, and available simulators and emulators in one pass:
+
+```bash
+npx react-native doctor
+```
+
+Fix anything it flags before you install the SDK. For a full walkthrough, see the React Native [environment setup guide](https://reactnative.dev/docs/set-up-your-environment).
+
+
-### Generate a signed upload URL
+## Install the SDK
+
+If you do not have a React Native app yet, create one first:
+
+```bash
+npx @react-native-community/cli@latest init FastPixUploaderDemo
+cd FastPixUploaderDemo
+```
+
+Then install the SDK using npm or your preferred package manager:
+
+```bash
+npm install @fastpix/react-native-uploads
+```
+
+The SDK bundles its runtime dependencies (`@react-native-community/netinfo`, `react-native-blob-util`, and `axios`), so there are no peer dependencies to install manually.
+
+### iOS — install native pods
+
+The bundled native modules auto-link on React Native 0.70+. After installing the package, run:
+
+```bash
+cd ios && pod install && cd ..
+```
+
+**Android:** No manual linking or extra setup is required — the native modules auto-link.
+
+
+
+## Generate a signed upload URL
To get started with the SDK, you will need a signed URL.
@@ -42,12 +122,16 @@ To make API requests, you'll need a valid **Access Token** and **Secret Key**. S
Once you have your credentials, use the [Upload media from device](https://fastpix.com/docs/video-on-demand-api/upload-and-import-videos/direct-upload-video-media) API to generate a signed URL for uploading media.
+
+
### What is a Signed URL?
A signed URL is a pre-authenticated URL that allows secure, direct uploads to FastPix storage without exposing your **Access Token** and **Secret Key** inside your mobile app. You create the URL on a trusted server (or a short-lived backend call), then hand only that URL to the SDK on the device.
> **Never ship your `Access Token` / `Secret Key` in the app bundle.** Generate signed URLs from your backend and return only the signed URL to the client.
+
+
### Sample Code: Generating a Signed URL
Here is a self-contained service that calls the FastPix Direct Upload API and returns a signed URL. It uses `axios` and `base-64` for the Basic Auth header (the same approach used by the bundled example app in [`test-example/src/Services/ApiService.ts`](test-example/src/Services/ApiService.ts)):
@@ -92,6 +176,10 @@ export async function generateSignedUrl(metadata = { uploadedBy: "react_native_a
}
```
+> **Endpoint note:** FastPix is migrating API hosts from `.io` to `.com`. The `api.fastpix.io` host above still works for backward compatibility, but new integrations should prefer `https://api.fastpix.com/v1/on-demand`.
+
+
+
### Integration: create a Signed URL, then Upload
Because `endpoint` accepts an **async factory** (`() => Promise`), you can plug the signed-URL generator straight in. The async factory runs once when `start()` is called, so the URL is created lazily and stays fresh:
@@ -129,53 +217,76 @@ export async function uploadVideo(fileUri) {
This example uses every constructor option — see [Configuration Parameters](#configuration-parameters) for the full table with types, defaults, and constraints.
-## Platform Support
+
-| Platform | Minimum version |
-| ------------ | ------------------ |
-| Android | API 21 (Android 5.0) |
-| iOS | iOS 13.0 |
-| React Native | 0.70+ |
+## Upload your first file
-## Installation
+```javascript
+import { FastPixUpload } from "@fastpix/react-native-uploads";
-To install the SDK, use npm or your preferred package manager:
+const upload = new FastPixUpload({
+ endpoint: "https://storage.googleapis.com/...your-signed-url...", // Replace with the signed URL.
+ fileUri: asset.uri, // file:// URI from your image picker.
+ chunkSize: 5 * 1024, // Minimum allowed chunk size is 5120KB (5MB).
-```bash
-npm install @fastpix/react-native-uploads
+ // Additional optional parameters can be specified here as needed
+});
+
+await upload.start();
```
-The SDK bundles its runtime dependencies (`@react-native-community/netinfo`, `react-native-blob-util`, and `axios`), so there are no peer dependencies to install manually.
+**Parameters used above:** `endpoint`, `fileUri`, `chunkSize` — see [Configuration Parameters](#configuration-parameters) for types, defaults, and constraints.
-### iOS — install native pods
+
-The bundled native modules auto-link on React Native 0.70+. After installing the package, run:
+### Verify your upload
-```bash
-cd ios && pod install && cd ..
-```
+Run the app and start an upload. Your integration is working when:
-**Android:** No manual linking or extra setup is required — the native modules auto-link.
+- The `progress` event advances and reaches 100%, and the `success` event fires (see [Lifecycle Events Reference](#lifecycle-events-reference)).
+- The uploaded media appears in your [FastPix Dashboard](https://dashboard.fastpix.com/).
-## Basic Usage
+Keep the `uploadId` returned when you generated the signed URL for tracking. If the upload never starts or fails, see [Troubleshooting](#troubleshooting).
-### Integration
+
-```javascript
-import { FastPixUpload } from "@fastpix/react-native-uploads";
+## Understand the upload workflow
-const upload = new FastPixUpload({
- endpoint: "https://storage.googleapis.com/...your-signed-url...", // Replace with the signed URL.
- fileUri: asset.uri, // file:// URI from your image picker.
- chunkSize: 5 * 1024, // Minimum allowed chunk size is 5120KB (5MB).
+Your backend creates a short-lived signed URL (so your Access Token and Secret Key never ship in the app); the SDK then uploads the file to that URL in resumable chunks and confirms each chunk's offset with the server, so any pause or network drop continues from where it left off.
- // Additional optional parameters can be specified here as needed
-});
+```mermaid
+flowchart TD
+ BE["Your backend
(Access Token + Secret Key)"] -->|"POST /v1/on-demand/upload"| API["FastPix Direct Upload API"]
+ API -->|"returns signed URL"| APP["React Native app
(file picker gives file:// URI)"]
+ APP -->|"endpoint = signed URL
fileUri = file:// path"| SDK["new FastPixUpload(...)"]
+ SDK --> CH["Split file into chunks
(5 MB - 500 MB each)"]
+ CH --> UP{"Upload each chunk"}
+ UP -->|"chunk confirmed"| NEXT["Server stores last offset"]
+ NEXT -->|"more chunks"| UP
+ UP -->|"network drop or error"| RETRY["Pause / retry that chunk
resume from last offset"]
+ RETRY --> UP
+ NEXT -->|"all chunks done"| DONE["success event
media ready in FastPix"]
-await upload.start();
+ classDef fp fill:#5D09C7,stroke:#5D09C7,color:#ffffff;
+ classDef ok fill:#0CB16D,stroke:#0CB16D,color:#ffffff;
+ class SDK,CH,UP fp;
+ class DONE ok;
```
-**Parameters used above:** `endpoint`, `fileUri`, `chunkSize` — see [Configuration Parameters](#configuration-parameters) for types, defaults, and constraints.
+
+
+## Next steps
+
+After your first upload works, use the SDK to:
+
+- Pause, resume, and recover from network drops - see [Resumable Uploads: Pause, Resume & Network Recovery](#resumable-uploads-pause-resume--network-recovery).
+- Track retries per chunk - see [Chunk-Level Retry Tracking](#chunk-level-retry-tracking).
+- React to upload lifecycle events - see [Lifecycle Events Reference](#lifecycle-events-reference).
+- Control the upload (start, pause, resume, abort) - see [Upload Control Methods](#upload-control-methods).
+- Configure chunk size, retries, file-size limits, and more - see [API Reference](#api-reference).
+- Run a complete working screen - see [Example App](#example-app).
+
+
## Resumable Uploads: Pause, Resume & Network Recovery
@@ -190,6 +301,8 @@ There are two ways an upload can pause:
Both emit a `pause` event carrying a `reason` (`'user'` or `'network'`), so your UI can react appropriately.
+
+
### Minimal pause / resume flow
```javascript
@@ -216,6 +329,8 @@ await upload.resume(); // re-syncs the server offset, then continues
**Parameters used above:** `endpoint`, `fileUri`, `chunkSize`, `maxRetries` — see [Configuration Parameters](#configuration-parameters) for types, defaults, and constraints.
+
+
### Full React component: progress bar with pause / resume / abort
A complete, copy-paste example wiring the resumable lifecycle to UI controls. The same flow is implemented end-to-end in the bundled [`test-example/`](test-example/) app.
@@ -280,6 +395,8 @@ export function VideoUploader({ fileUri }) {
**Parameters used above:** `endpoint`, `fileUri`, `chunkSize`, `maxRetries`, `retryDelay`, `enableLogs` — see [Configuration Parameters](#configuration-parameters) for types, defaults, and constraints.
+
+
### Automatic network recovery
The SDK automatically resumes uploads when network connectivity is restored. While an upload is in flight the SDK monitors connectivity via `@react-native-community/netinfo`:
@@ -290,6 +407,8 @@ The SDK automatically resumes uploads when network connectivity is restored. Whi
An upload paused by you (`reason: 'user'`) is **not** auto-resumed on reconnect — that stays under your control, so a user-paused upload never restarts behind their back.
+
+
## Chunk-Level Retry Tracking
Retries are tracked **per individual chunk** rather than with a single global counter. Each chunk gets its own budget of `maxRetries` attempts with exponential back-off, so one flaky chunk can never exhaust the retry allowance of the others.
@@ -316,6 +435,8 @@ upload.on("chunkSuccess", ({ chunkIndex }) => {
});
```
+
+
## Lifecycle Events Reference
Subscribe to upload lifecycle events using `upload.on(event, handler)`. Each subscription returns a cleanup function, making it easy to use with React's `useEffect`.
@@ -383,6 +504,8 @@ upload.on("online", () => {
});
```
+
+
### Supported Events
| Event | Description |
@@ -401,6 +524,7 @@ upload.on("online", () => {
| `offline` | Fired when network connectivity is lost. |
| `online` | Fired when network connectivity is restored. |
+
## Upload Control Methods
@@ -430,6 +554,8 @@ You can control the upload lifecycle with the following methods:
upload.abort(); // Permanently cancels and releases all resources; emits `abort` before removing listeners
```
+
+
## API Reference
### `FastPixUpload`
@@ -450,6 +576,8 @@ The `FastPixUpload` constructor accepts the following parameters:
| `maxFileSize` | `number` (in KB) | Optional | Maximum allowed file size. `0` means no limit. Files exceeding this fail immediately before any network request. Default is `0`. |
| `enableLogs` | `boolean` | Optional | Enable SDK-internal debug logging to the console. Recommended for development; disable in production. Default is `false`. |
+
+
#### Example usage of integrating all parameters
```javascript
@@ -478,6 +606,8 @@ await upload.start();
// upload.abort();
```
+
+
### Methods
| Method | Signature | Description |
@@ -489,6 +619,8 @@ await upload.start();
| `on(event, handler)` | `(event, handler) => () => void` | Subscribes to a [lifecycle event](#supported-events). **Returns an unsubscribe function.** |
| `off(event, handler)` | `(event, handler) => void` | Manually removes a previously registered listener. |
+
+
### Getters
| Getter | Type | Description |
@@ -497,6 +629,8 @@ await upload.start();
| `progress` | `UploadProgressSnapshot` | A point-in-time snapshot of upload progress (bytes, percentage, current chunk). |
| `stateHistory` | `ReadonlyArray<{ from, to, at }>` | An ordered log of every state transition, each with a timestamp (`at`). |
+
+
### Types
#### `UploadState`
@@ -537,6 +671,8 @@ Describes the byte range of a single chunk. Exported for consumers that need to
For the full list of event payloads, see [Supported Events](#supported-events).
+
+
## Example App
A complete React Native example application is included in the repository to help you get started quickly.
@@ -553,6 +689,8 @@ The example demonstrates:
Refer to the **`test-example/`** directory for the complete implementation.
+
+
## Troubleshooting
| Symptom | Likely cause | Fix |
@@ -567,6 +705,52 @@ Refer to the **`test-example/`** directory for the complete implementation.
Enable `enableLogs: true` in the constructor to see detailed SDK-internal logs while diagnosing issues (disable in production).
+
+
+## Which FastPix repo do I need?
+
+This SDK uploads from a React Native app. For other platforms and the backend piece:
+
+| I want to... | Repo |
+|---|---|
+| Generate signed upload URLs from a Node backend | [node-sdk](https://github.com/FastPix/node-sdk) |
+| Add resumable uploads in the browser (JS) | [web-uploads-sdk](https://github.com/FastPix/web-uploads-sdk) |
+| Add a React uploader component (web) | [react-web-uploader](https://github.com/FastPix/react-web-uploader) |
+| Add resumable uploads to a native iOS app | [iOS-Uploads](https://github.com/FastPix/iOS-Uploads) |
+| Play the uploaded video on the web | [web-player-component](https://github.com/FastPix/web-player-component) |
+
+Browse everything in the [FastPix organization](https://github.com/orgs/FastPix/repositories).
+
+
+
+## FAQ
+
+**What does this SDK do?**
+It uploads large videos and files from a React Native app to FastPix in resumable chunks, with pause/resume, per-chunk retries, and automatic network recovery. See [Features](#features).
+
+**Which package do I install?**
+`npm install @fastpix/react-native-uploads`. See [Installation](#install-the-sdk).
+
+**Do I need a signed URL? Why?**
+Yes. You generate a short-lived signed URL on your backend so your Access Token and Secret Key never ship inside the app. The device only ever sees the signed URL. See [Generate a signed upload URL](#generate-a-signed-upload-url).
+
+**Does it work with Expo?**
+It ships native modules (NetInfo, blob-util), so it needs a bare/dev-client React Native build (0.70+), not Expo Go. See [Platform Support](#platform-support).
+
+**What is the minimum and maximum chunk size?**
+5 MB (5120 KB) to 500 MB (512000 KB), and the value must be a multiple of 256. See [Configuration Parameters](#configuration-parameters).
+
+**How does resume work after a network drop?**
+Each chunk's offset is confirmed by the server, so the upload continues from the last confirmed offset - completed chunks are never re-sent. Network-triggered pauses resume automatically. See [Resumable Uploads](#resumable-uploads-pause-resume--network-recovery).
+
+**Do I need to run `pod install`?**
+On iOS, yes: `cd ios && pod install`. Android auto-links with no extra steps. See [Installation](#install-the-sdk).
+
+**Is it written in TypeScript?**
+Yes - the SDK ships types, and all options, events, and getters are typed. See [API Reference](#api-reference).
+
+
+
## Additional References
[FastPix Homepage](https://www.fastpix.com/)
@@ -574,4 +758,4 @@ Enable `enableLogs: true` in the constructor to see detailed SDK-internal logs w
## Detailed Usage
-For more detailed steps and advanced usage, please refer to the official [FastPix Documentation](https://fastpix.com/docs/upload-videos/upload-videos-from-device#resumable-uploading-of-large-files).
+For more detailed steps and advanced usage, please refer to the official [FastPix Documentation](https://fastpix.com/docs/upload-videos/upload-videos-from-device#uploading-large-media-files).