react-native-advanced-share-intent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-native-advanced-share-intent contributors
+
+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,345 @@
+# react-native-advanced-share-intent
+
+Lightweight React Native share intent handling for Android and iOS Share Extensions.
+
+`react-native-advanced-share-intent` exposes a small typed API for reading content shared into your app from Android share sheets and iOS Share Extensions. It supports cold starts, foreground shares, text, URLs, images, videos, documents, multiple files, metadata, and explicit cleanup.
+
+## Features
+
+- Android `ACTION_SEND` and `ACTION_SEND_MULTIPLE`
+- iOS Share Extension support with App Groups
+- Cold-start delivery with `getInitialShare()`
+- Foreground delivery with `addShareListener()`
+- Cleanup with `clearSharedData()`
+- Text, URL, image, video, document, and multi-file shares
+- File name, size, MIME type, original URI, and capture date metadata where available
+- iOS Photos asset preservation with `ph://` local identifiers when available
+- TypeScript definitions
+- No runtime dependencies
+- React Native autolinking support
+
+## Installation
+
+Using npm:
+
+```sh
+npm install react-native-advanced-share-intent
+```
+
+Using Yarn:
+
+```sh
+yarn add react-native-advanced-share-intent
+```
+
+For iOS, install pods after adding the package:
+
+```sh
+cd ios && pod install
+```
+
+Rebuild the native app after installation.
+
+## Android Setup
+
+Add share intent filters to the activity that hosts React Native. Keep `launchMode="singleTask"` so foreground shares arrive through `onNewIntent`.
+
+```xml
+<activity
+  android:name=".MainActivity"
+  android:launchMode="singleTask"
+  android:exported="true">
+
+  <intent-filter>
+    <action android:name="android.intent.action.SEND" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <data android:mimeType="text/*" />
+    <data android:mimeType="image/*" />
+    <data android:mimeType="video/*" />
+    <data android:mimeType="application/*" />
+  </intent-filter>
+
+  <intent-filter>
+    <action android:name="android.intent.action.SEND_MULTIPLE" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <data android:mimeType="image/*" />
+    <data android:mimeType="video/*" />
+    <data android:mimeType="application/*" />
+  </intent-filter>
+</activity>
+```
+
+Android returns shared files as provider-backed `content://` URIs. The library does not copy large file bytes into JavaScript memory. Pass the URI to your uploader, media pipeline, or a native file-copy step when your app needs a local copy.
+
+## iOS Setup
+
+iOS share delivery requires a Share Extension and an App Group. The library includes `AdvancedShareIntentShareExtension`, a base extension controller that collects shared items, stores a compact payload in the App Group, and opens the containing app.
+
+1. In Xcode, add a Share Extension target.
+2. Enable the same App Group on the main app target and the Share Extension target.
+3. Add a URL scheme to the main app, for example `myapp`.
+4. In your extension target, subclass the included controller:
+
+```swift
+import AdvancedShareIntent
+
+final class ShareViewController: AdvancedShareIntentShareExtension {
+  override var appGroupIdentifier: String {
+    "group.com.example.myapp"
+  }
+
+  override var containingAppScheme: String {
+    "myapp"
+  }
+}
+```
+
+5. Configure the App Group from JavaScript before reading initial data:
+
+```ts
+import ShareIntent from 'react-native-advanced-share-intent';
+
+await ShareIntent.setAppGroupIdentifier('group.com.example.myapp');
+await ShareIntent.setContainingAppScheme('myapp');
+
+const initialShare = await ShareIntent.getInitialShare();
+```
+
+The extension preserves Photos library items as `ph://` URIs with `localIdentifier` when iOS exposes a `PHAsset`. Other files are copied into the App Group container and returned as `file://` URLs. For long-running uploads, copy or consume those files promptly after receiving the payload, then call `clearSharedData()` to remove cached share-extension files.
+
+## Usage
+
+Read the share that launched the app:
+
+```ts
+import ShareIntent from 'react-native-advanced-share-intent';
+
+const share = await ShareIntent.getInitialShare();
+
+if (share) {
+  console.log(share.text);
+  console.log(share.files);
+}
+```
+
+Listen for new shares while the app is running:
+
+```ts
+import { useEffect, useState } from 'react';
+import ShareIntent, {
+  type ShareIntentPayload,
+} from 'react-native-advanced-share-intent';
+
+export function useShareIntent() {
+  const [share, setShare] = useState<ShareIntentPayload | null>(null);
+
+  useEffect(() => {
+    ShareIntent.getInitialShare().then(setShare);
+
+    const subscription = ShareIntent.addShareListener(setShare);
+    return () => subscription.remove();
+  }, []);
+
+  return share;
+}
+```
+
+Clear processed shared data:
+
+```ts
+await ShareIntent.clearSharedData();
+```
+
+Named function exports are also available:
+
+```ts
+import {
+  getInitialShare,
+  addShareListener,
+  clearSharedData,
+} from 'react-native-advanced-share-intent';
+```
+
+For a compact copyable component, see [`examples/BasicShareIntent.tsx`](examples/BasicShareIntent.tsx).
+
+## API Reference
+
+### `getInitialShare()`
+
+```ts
+getInitialShare(): Promise<ShareIntentPayload | null>
+```
+
+Returns the share payload that launched the app, or `null` when the app was not opened from a share.
+
+### `addShareListener(listener)`
+
+```ts
+addShareListener(listener: ShareIntentListener): EmitterSubscription
+```
+
+Subscribes to share payloads delivered after the app is already running. Call `subscription.remove()` during cleanup.
+
+### `clearSharedData()`
+
+```ts
+clearSharedData(): Promise<void>
+```
+
+Clears the cached share payload and removes iOS App Group files created by the Share Extension.
+
+### `setAppGroupIdentifier(identifier)`
+
+```ts
+setAppGroupIdentifier(identifier: string): Promise<void>
+```
+
+iOS only. Sets the App Group used by the containing app and Share Extension.
+
+### `setContainingAppScheme(scheme)`
+
+```ts
+setContainingAppScheme(scheme: string): Promise<void>
+```
+
+iOS only. Stores the URL scheme used by the Share Extension to reopen the containing app.
+
+### Types
+
+```ts
+type ShareIntentPayload = {
+  text?: string;
+  subject?: string;
+  title?: string;
+  mimeType?: string;
+  files: SharedFile[];
+  webUrl?: string;
+  isInitial: boolean;
+  receivedAt: number;
+};
+
+type SharedFile = {
+  uri: string;
+  fileName?: string;
+  name?: string;
+  mimeType?: string;
+  size?: number;
+  type: 'text' | 'image' | 'video' | 'document' | 'unknown';
+  dateTaken?: number;
+  localIdentifier?: string;
+  originalUri?: string;
+};
+```
+
+## Example App
+
+The example app stays in the GitHub repository so contributors and users can test the native behavior. It is excluded from the npm package through the root `package.json` `files` allowlist.
+
+Clone and run the example app with npm:
+
+```sh
+git clone https://github.com/engr-touqeer/react-native-advanced-share-intent
+cd react-native-advanced-share-intent/example
+npm install
+cd ios && pod install
+cd ..
+npm run ios
+npm run android
+```
+
+Or run it with Yarn:
+
+```sh
+git clone https://github.com/engr-touqeer/react-native-advanced-share-intent
+cd react-native-advanced-share-intent/example
+yarn install
+cd ios && pod install
+cd ..
+yarn ios
+yarn android
+```
+
+The Android example is configured to receive share intents and display the parsed payload. For iOS testing, add a Share Extension target to the example app and follow the iOS setup above with your own App Group and URL scheme.
+
+## Publishing
+
+Install, build, and inspect the package with npm:
+
+```sh
+npm install
+npm run build
+npm pack --dry-run
+```
+
+Install, build, and inspect the package with Yarn:
+
+```sh
+yarn install
+yarn build
+yarn pack --dry-run
+```
+
+Publish manually only after reviewing the dry-run output:
+
+```sh
+npm login
+npm whoami
+npm publish --access public
+```
+
+npm requires either account 2FA or a granular access token with publish access and bypass 2FA enabled. If publish fails with `E403`, confirm 2FA is enabled for your npm account or create a granular npm access token with the required publishing permissions.
+
+The npm package is intentionally limited to:
+
+```txt
+android/
+ios/
+src/
+index.js
+index.mjs
+index.d.ts
+react-native.config.js
+react-native-advanced-share-intent.podspec
+README.md
+LICENSE
+```
+
+This keeps the published package lightweight while preserving the full example app in GitHub.
+
+## Lockfile Policy
+
+Use one package manager lockfile style in committed changes. This repository uses npm as the primary lockfile source with `package-lock.json`. Yarn is supported for installs and scripts, but `yarn.lock` should not be committed unless the project intentionally switches to Yarn as the primary package manager.
+
+## Troubleshooting
+
+### The native module is not linked
+
+Run `pod install` for iOS, rebuild the native app, and make sure React Native autolinking can see the package.
+
+### Android shares do not arrive while the app is open
+
+Confirm the host activity uses `android:launchMode="singleTask"` and has the `SEND` or `SEND_MULTIPLE` intent filters for the MIME types you want to support.
+
+### iOS returns `null`
+
+Confirm the main app and Share Extension use the same App Group, the Share Extension subclasses `AdvancedShareIntentShareExtension`, and JavaScript calls `setAppGroupIdentifier()` before `getInitialShare()`.
+
+### Large files are slow or fail to upload
+
+The library returns provider or App Group file URIs. Copy, stream, or upload those files from a native-capable file pipeline instead of reading large files into JavaScript memory.
+
+## Contributing
+
+Issues and pull requests are welcome. Please keep changes focused, preserve Android and iOS share intent behavior, and test with text, one file, and multiple files where possible.
+
+Before opening a pull request:
+
+```sh
+npm install
+npm run build
+npm pack --dry-run
+```
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,37 @@
+buildscript {
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath("com.android.tools.build:gradle:8.7.3")
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21")
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+
+android {
+  namespace "com.advancedshareintent"
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 23)
+    targetSdkVersion safeExtGet("targetSdkVersion", 35)
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+}

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/java/com/advancedshareintent/AdvancedShareIntentModule.kt

@@ -0,0 +1,266 @@
+package com.advancedshareintent
+
+import android.app.Activity
+import android.content.ClipData
+import android.content.ContentResolver
+import android.content.Intent
+import android.database.Cursor
+import android.net.Uri
+import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
+import android.provider.OpenableColumns
+import android.provider.MediaStore
+import com.facebook.react.bridge.ActivityEventListener
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.LifecycleEventListener
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+
+class AdvancedShareIntentModule(
+  private val reactContext: ReactApplicationContext
+) : ReactContextBaseJavaModule(reactContext), ActivityEventListener, LifecycleEventListener {
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private var initialShare: WritableMap? = null
+  private var latestShare: WritableMap? = null
+  private var hasListeners = false
+
+  init {
+    reactContext.addActivityEventListener(this)
+    reactContext.addLifecycleEventListener(this)
+  }
+
+  override fun getName(): String = NAME
+
+  override fun initialize() {
+    super.initialize()
+    reactContext.currentActivity?.intent?.let { intent ->
+      parseShareIntent(intent, true)?.let { payload ->
+        initialShare = payload.copy()
+        latestShare = payload.copy()
+      }
+    }
+  }
+
+  override fun onNewIntent(intent: Intent) {
+    parseShareIntent(intent, false)?.let { payload ->
+      latestShare = payload.copy()
+      sendEventWhenReady(payload.copy())
+    }
+  }
+
+  override fun onActivityResult(
+    activity: Activity,
+    requestCode: Int,
+    resultCode: Int,
+    data: Intent?
+  ) = Unit
+
+  @ReactMethod
+  fun getInitialShare(promise: Promise) {
+    try {
+      val payload = initialShare ?: reactContext.currentActivity?.intent?.let { parseShareIntent(it, true) }
+      initialShare = payload?.copy()
+      promise.resolve(payload?.copy())
+    } catch (error: Exception) {
+      promise.reject("advanced_share_intent_initial_error", error)
+    }
+  }
+
+  @ReactMethod
+  fun clearSharedData(promise: Promise) {
+    initialShare = null
+    latestShare = null
+    reactContext.currentActivity?.intent?.apply {
+      action = null
+      type = null
+      data = null
+      clipData = null
+      replaceExtras(Bundle())
+    }
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  fun addListener(eventName: String) {
+    hasListeners = true
+    latestShare?.copy()?.let { sendEventWhenReady(it) }
+  }
+
+  @ReactMethod
+  fun removeListeners(count: Int) {
+    hasListeners = false
+  }
+
+  override fun onHostResume() {
+    latestShare?.copy()?.let { sendEventWhenReady(it) }
+  }
+
+  override fun onHostPause() = Unit
+
+  override fun onHostDestroy() = Unit
+
+  private fun parseShareIntent(intent: Intent, isInitial: Boolean): WritableMap? {
+    val action = intent.action ?: return null
+    if (action != Intent.ACTION_SEND && action != Intent.ACTION_SEND_MULTIPLE) {
+      return null
+    }
+
+    val mimeType = intent.type ?: "*/*"
+    val files = Arguments.createArray()
+    val text = intent.getStringExtra(Intent.EXTRA_TEXT)
+    val subject = intent.getStringExtra(Intent.EXTRA_SUBJECT)
+    val title = intent.getStringExtra(Intent.EXTRA_TITLE)
+
+    collectUris(intent).forEach { uri ->
+      grantReadPermission(uri)
+      files.pushMap(uriToFileMap(uri, mimeType))
+    }
+
+    if (text.isNullOrBlank() && files.size() == 0) {
+      return null
+    }
+
+    return Arguments.createMap().apply {
+      if (!text.isNullOrBlank()) putString("text", text)
+      if (!subject.isNullOrBlank()) putString("subject", subject)
+      if (!title.isNullOrBlank()) putString("title", title)
+      putString("mimeType", mimeType)
+      putArray("files", files)
+      putBoolean("isInitial", isInitial)
+      putDouble("receivedAt", System.currentTimeMillis().toDouble())
+      extractWebUrl(text)?.let { putString("webUrl", it) }
+    }
+  }
+
+  private fun collectUris(intent: Intent): List<Uri> {
+    val uris = LinkedHashSet<Uri>()
+    val stream = intent.getParcelableExtra<Uri>(Intent.EXTRA_STREAM)
+    if (stream != null) uris.add(stream)
+
+    val streams = intent.getParcelableArrayListExtra<Uri>(Intent.EXTRA_STREAM)
+    streams?.forEach { uri -> if (uri != null) uris.add(uri) }
+
+    collectClipData(intent.clipData, uris)
+    intent.data?.let { uris.add(it) }
+    return uris.toList()
+  }
+
+  private fun collectClipData(clipData: ClipData?, uris: MutableSet<Uri>) {
+    if (clipData == null) return
+    for (index in 0 until clipData.itemCount) {
+      clipData.getItemAt(index)?.uri?.let { uris.add(it) }
+    }
+  }
+
+  private fun uriToFileMap(uri: Uri, fallbackMimeType: String): WritableMap {
+    val resolver = reactContext.contentResolver
+    val mimeType = resolver.getType(uri) ?: fallbackMimeType
+    val metadata = queryMetadata(resolver, uri)
+
+    return Arguments.createMap().apply {
+      putString("uri", uri.toString())
+      putString("type", classifyMimeType(mimeType))
+      putString("mimeType", mimeType)
+      metadata.name?.let { putString("fileName", it) }
+      metadata.name?.let { putString("name", it) }
+      metadata.size?.let { putDouble("size", it.toDouble()) }
+      metadata.dateTaken?.let { putDouble("dateTaken", it.toDouble()) }
+      putString("originalUri", uri.toString())
+    }
+  }
+
+  private fun queryMetadata(resolver: ContentResolver, uri: Uri): FileMetadata {
+    if (uri.scheme == ContentResolver.SCHEME_FILE) {
+      val path = uri.path ?: return FileMetadata(null, null, null)
+      val file = java.io.File(path)
+      return FileMetadata(file.name, file.takeIf { it.exists() }?.length(), file.takeIf { it.exists() }?.lastModified())
+    }
+
+    var cursor: Cursor? = null
+    return try {
+      cursor = resolver.query(
+        uri,
+        arrayOf(OpenableColumns.DISPLAY_NAME, OpenableColumns.SIZE, MediaStore.MediaColumns.DATE_TAKEN),
+        null,
+        null,
+        null
+      )
+      if (cursor != null && cursor.moveToFirst()) {
+        val nameIndex = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)
+        val sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE)
+        val dateTakenIndex = cursor.getColumnIndex(MediaStore.MediaColumns.DATE_TAKEN)
+        FileMetadata(
+          name = if (nameIndex >= 0) cursor.getString(nameIndex) else null,
+          size = if (sizeIndex >= 0 && !cursor.isNull(sizeIndex)) cursor.getLong(sizeIndex) else null,
+          dateTaken = if (dateTakenIndex >= 0 && !cursor.isNull(dateTakenIndex)) cursor.getLong(dateTakenIndex) else null
+        )
+      } else {
+        FileMetadata(uri.lastPathSegment, null, null)
+      }
+    } catch (_: Exception) {
+      FileMetadata(uri.lastPathSegment, null, null)
+    } finally {
+      cursor?.close()
+    }
+  }
+
+  private fun grantReadPermission(uri: Uri) {
+    try {
+      val flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
+      reactContext.grantUriPermission(reactContext.packageName, uri, flags)
+      reactContext.contentResolver.takePersistableUriPermission(uri, flags)
+    } catch (_: Exception) {
+      // Many providers do not support persisted grants. The temporary share grant is still valid.
+    }
+  }
+
+  private fun sendEventWhenReady(payload: WritableMap, attempt: Int = 0) {
+    if (!hasListeners && attempt < MAX_DELIVERY_ATTEMPTS) {
+      mainHandler.postDelayed({ sendEventWhenReady(payload.copy(), attempt + 1) }, DELIVERY_RETRY_MS)
+      return
+    }
+
+    if (!reactContext.hasActiveCatalystInstance()) {
+      if (attempt < MAX_DELIVERY_ATTEMPTS) {
+        mainHandler.postDelayed({ sendEventWhenReady(payload.copy(), attempt + 1) }, DELIVERY_RETRY_MS)
+      }
+      return
+    }
+
+    reactContext
+      .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+      .emit(EVENT_NAME, payload)
+  }
+
+  private fun WritableMap.copy(): WritableMap = Arguments.makeNativeMap(this.toHashMap())
+
+  private data class FileMetadata(val name: String?, val size: Long?, val dateTaken: Long?)
+
+  companion object {
+    const val NAME = "AdvancedShareIntent"
+    private const val EVENT_NAME = "AdvancedShareIntentReceived"
+    private const val MAX_DELIVERY_ATTEMPTS = 10
+    private const val DELIVERY_RETRY_MS = 500L
+
+    fun classifyMimeType(mimeType: String?): String {
+      val value = mimeType?.lowercase() ?: return "unknown"
+      return when {
+        value.startsWith("image/") -> "image"
+        value.startsWith("video/") -> "video"
+        value.startsWith("text/") -> "text"
+        value == "text/plain" -> "text"
+        else -> "document"
+      }
+    }
+
+    private fun extractWebUrl(text: String?): String? {
+      if (text.isNullOrBlank()) return null
+      return Regex("""https?://\S+""").find(text)?.value
+    }
+  }
+}

package/android/src/main/java/com/advancedshareintent/AdvancedShareIntentPackage.kt

@@ -0,0 +1,16 @@
+package com.advancedshareintent
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class AdvancedShareIntentPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+    return listOf(AdvancedShareIntentModule(reactContext))
+  }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return emptyList()
+  }
+}

package/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './src';
+export * from './src';