mergn-react-native 1.0.0

package/ios/MergnNotificationHandler.swift

@@ -0,0 +1,160 @@
+import Foundation
+import UIKit
+import UserNotifications
+import mergn_ios
+
+/// Reports notification impressions and taps to the Mergn SDK, and keeps the
+/// SDK's current view controller up to date so in-app popups have somewhere to
+/// present.
+///
+/// Mergn's reference iOS integration puts these calls directly in the host
+/// app's AppDelegate:
+///
+///     UNUserNotificationCenter.current().delegate = self
+///     SDKManager.shared.setCurrentViewController(rootViewController)
+///
+///     func userNotificationCenter(_:willPresent:withCompletionHandler:) {
+///       EventManager.shared.notificationViewed(notificationData: notification.request)
+///     }
+///     func userNotificationCenter(_:didReceive response:withCompletionHandler:) {
+///       EventManager.shared.notificationTapped(notificationData: response.notification.request)
+///     }
+///
+/// A React Native app cannot follow that pattern as-is: expo-notifications and
+/// @react-native-firebase both claim `UNUserNotificationCenter.delegate`, and
+/// whichever loads last wins. Assigning it here would silently break their
+/// notification handling (and vice versa).
+///
+/// So instead of owning the delegate, this observes it. `swizzle()` wraps any
+/// existing delegate's two methods, forwards to Mergn, then calls the original
+/// implementation — so Mergn tracking is additive and the app's own handling is
+/// untouched. On Android the SDK does this inside its own
+/// FireBaseMessagingService, which is why there is no JS API for it on either
+/// platform: both are automatic.
+@objc(MergnNotificationHandler)
+public final class MergnNotificationHandler: NSObject {
+
+  @objc public static let shared = MergnNotificationHandler()
+
+  private var installed = false
+
+  /// Called from the module's `+load`-time hook, after the JS bridge is up so
+  /// that whichever notification library the app uses has already claimed the
+  /// delegate.
+  @objc public func install() {
+    guard !installed else { return }
+    installed = true
+
+    // The SDK needs a live view controller for in-app popups. Refresh it now and
+    // again whenever the app returns to the foreground, since the top-most
+    // controller changes as the user navigates.
+    refreshViewController()
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(refreshViewController),
+      name: UIApplication.didBecomeActiveNotification,
+      object: nil
+    )
+
+    observeNotificationCenterDelegate()
+  }
+
+  @objc private func refreshViewController() {
+    DispatchQueue.main.async {
+      if let top = UIApplication.topViewController() {
+        SDKManager.shared.setCurrentViewController(top)
+      }
+    }
+  }
+
+  // MARK: - Delegate observation
+
+  private func observeNotificationCenterDelegate() {
+    let center = UNUserNotificationCenter.current()
+
+    guard let delegate = center.delegate else {
+      // Nothing else claimed the delegate, so take it ourselves. This is the
+      // plain-RN case with no notification library installed.
+      center.delegate = FallbackDelegate.shared
+      return
+    }
+
+    swizzle(type(of: delegate))
+  }
+
+  /// Wraps the delegate's willPresent / didReceive so Mergn sees every
+  /// notification without displacing the existing handler.
+  private func swizzle(_ cls: AnyClass) {
+    swizzleWillPresent(cls)
+    swizzleDidReceive(cls)
+  }
+
+  private func swizzleWillPresent(_ cls: AnyClass) {
+    let selector = #selector(
+      UNUserNotificationCenterDelegate.userNotificationCenter(_:willPresent:withCompletionHandler:)
+    )
+    guard let original = class_getInstanceMethod(cls, selector) else { return }
+
+    typealias Impl = @convention(c) (
+      AnyObject, Selector, UNUserNotificationCenter, UNNotification,
+      @escaping (UNNotificationPresentationOptions) -> Void
+    ) -> Void
+    let originalImp = unsafeBitCast(method_getImplementation(original), to: Impl.self)
+
+    let block: @convention(block) (
+      AnyObject, UNUserNotificationCenter, UNNotification,
+      @escaping (UNNotificationPresentationOptions) -> Void
+    ) -> Void = { receiver, center, notification, completion in
+      EventManager.shared.notificationViewed(notificationData: notification.request)
+      originalImp(receiver, selector, center, notification, completion)
+    }
+
+    method_setImplementation(original, imp_implementationWithBlock(block))
+  }
+
+  private func swizzleDidReceive(_ cls: AnyClass) {
+    let selector = #selector(
+      UNUserNotificationCenterDelegate.userNotificationCenter(_:didReceive:withCompletionHandler:)
+    )
+    guard let original = class_getInstanceMethod(cls, selector) else { return }
+
+    typealias Impl = @convention(c) (
+      AnyObject, Selector, UNUserNotificationCenter, UNNotificationResponse,
+      @escaping () -> Void
+    ) -> Void
+    let originalImp = unsafeBitCast(method_getImplementation(original), to: Impl.self)
+
+    let block: @convention(block) (
+      AnyObject, UNUserNotificationCenter, UNNotificationResponse, @escaping () -> Void
+    ) -> Void = { receiver, center, response, completion in
+      EventManager.shared.notificationTapped(notificationData: response.notification.request)
+      originalImp(receiver, selector, center, response, completion)
+    }
+
+    method_setImplementation(original, imp_implementationWithBlock(block))
+  }
+
+  /// Used only when no other delegate exists, so notifications still surface and
+  /// get reported.
+  private final class FallbackDelegate: NSObject, UNUserNotificationCenterDelegate {
+    static let shared = FallbackDelegate()
+
+    func userNotificationCenter(
+      _ center: UNUserNotificationCenter,
+      willPresent notification: UNNotification,
+      withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
+    ) {
+      EventManager.shared.notificationViewed(notificationData: notification.request)
+      completionHandler([.banner, .list, .sound, .badge])
+    }
+
+    func userNotificationCenter(
+      _ center: UNUserNotificationCenter,
+      didReceive response: UNNotificationResponse,
+      withCompletionHandler completionHandler: @escaping () -> Void
+    ) {
+      EventManager.shared.notificationTapped(notificationData: response.notification.request)
+      completionHandler()
+    }
+  }
+}

package/ios/NotificationService/Info.plist

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>NotificationService</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>XPC!</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.usernotifications.service</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).NotificationService</string>
+	</dict>
+</dict>
+</plist>

package/ios/NotificationService/NotificationService.swift

@@ -0,0 +1,82 @@
+import UserNotifications
+
+// Rich-push image support. This is Mergn's own iOS implementation, used as
+// given.
+//
+// iOS never downloads a notification image by itself: a push carrying
+// "mutable-content": 1 wakes this extension, which has ~30s to fetch the image
+// and hand it back as a UNNotificationAttachment. With no extension in the app
+// the payload's "image" key is ignored and the banner renders as plain text —
+// which is why real pushes were arriving without the picture.
+//
+// This is the iOS counterpart of what Mergn's FireBaseMessagingService does
+// inside the SDK on Android. The iOS SDK has no attachment handling, and an
+// extension is a separate binary that must be a target of the app, so it cannot
+// be supplied by a framework.
+class NotificationService: UNNotificationServiceExtension {
+
+  var contentHandler: ((UNNotificationContent) -> Void)?
+  var bestAttemptContent: UNMutableNotificationContent?
+
+  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
+    self.contentHandler = contentHandler
+    bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
+
+    // Check for the media URL
+    if let mediaUrlString = request.content.userInfo["image"] as? String,
+       let mediaUrl = URL(string: mediaUrlString) {
+
+      // Download the image
+      downloadImage(from: mediaUrl) { imageData in
+        if let imageData = imageData {
+          // Attach the image as a big picture to the notification
+          self.attachBigImageToNotification(imageData: imageData)
+        }
+
+        // Call the content handler to deliver the notification
+        contentHandler(self.bestAttemptContent!)
+      }
+    } else {
+      // If no image, just return the original notification content
+      contentHandler(self.bestAttemptContent!)
+    }
+  }
+
+  override func serviceExtensionTimeWillExpire() {
+    // Called when the extension is about to time out
+    if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
+      contentHandler(bestAttemptContent)
+    }
+  }
+
+  // Helper function to download the image
+  func downloadImage(from url: URL, completion: @escaping (Data?) -> Void) {
+    let task = URLSession.shared.dataTask(with: url) { data, response, error in
+      if let error = error {
+        print("Error downloading image: \(error)")
+        completion(nil)
+      } else {
+        completion(data)
+      }
+    }
+    task.resume()
+  }
+
+  // Helper function to save the image to a temporary directory
+  func saveImageToTempDirectory(data: Data) -> URL {
+    let tempDirectory = FileManager.default.temporaryDirectory
+    let fileURL = tempDirectory.appendingPathComponent(UUID().uuidString + ".jpg")
+    try? data.write(to: fileURL)
+    return fileURL
+  }
+
+  // Helper function to attach the image as a big picture to the notification
+  func attachBigImageToNotification(imageData: Data) {
+    let imageURL = saveImageToTempDirectory(data: imageData)
+
+    if let attachment = try? UNNotificationAttachment(identifier: "image", url: imageURL, options: nil) {
+      // Attach the image to the notification content
+      bestAttemptContent?.attachments = [attachment]
+    }
+  }
+}

package/mergn-react-native.podspec

@@ -0,0 +1,32 @@
+require 'json'
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+# React Native autolinking finds this podspec automatically, so the client never
+# edits their Podfile: `npm install` + `pod install` is enough.
+Pod::Spec.new do |s|
+  s.name         = 'mergn-react-native'
+  s.version      = package['version']
+  s.summary      = package['description']
+  s.homepage     = package['homepage']
+  s.license      = { :type => 'Commercial' }
+  s.author       = package['author']
+  s.source       = { :git => 'https://mergn.com', :tag => s.version.to_s }
+
+  # mergn_ios.xcframework is built for iOS 14 (see its .swiftinterface flags).
+  # Setting it here means the client's Podfile inherits the floor automatically.
+  s.platforms    = { :ios => '14.0' }
+  s.swift_version = '5.0'
+
+  s.source_files = 'ios/*.{h,m,mm,swift}'
+
+  s.dependency 'MergnSDK', '~> 19.0'
+  s.dependency 'React-Core'
+
+  # The Mergn iOS SDK ships inside this package rather than being downloaded at
+  # install time. That keeps `pod install` offline-safe and avoids depending on
+  # CocoaPods' local-vs-remote pod semantics, which silently fail to link a
+  # vendored framework fetched by prepare_command.
+  #
+  # vendored_frameworks is resolved relative to this podspec, so the framework
+  # must stay in ios/ alongside it.
+end

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mergn-react-native",
+  "version": "1.0.0",
+  "description": "MERGN SDK for React Native \u2014 analytics, attributes, identity and push for Android and iOS from one JS API.",
+  "keywords": [
+    "react-native",
+    "expo",
+    "mergn",
+    "analytics",
+    "push-notifications"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Mergn",
+  "homepage": "https://github.com/SHamzaHMergn/mergn-react-native#readme",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "app.plugin.js": "plugin/index.js",
+  "files": [
+    "src",
+    "plugin",
+    "ios",
+    "android",
+    "app.plugin.js",
+    "mergn-react-native.podspec",
+    "README.md",
+    "scripts",
+    "react-native.config.js",
+    "sdk",
+    "docs",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "expo": ">=50",
+    "react-native": ">=0.72"
+  },
+  "scripts": {
+    "prepack": "node scripts/verify-package.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SHamzaHMergn/mergn-react-native.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SHamzaHMergn/mergn-react-native/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/index.js

@@ -0,0 +1,219 @@
+const {
+  withAndroidManifest,
+  withXcodeProject,
+  withDangerousMod,
+  AndroidConfig,
+} = require("expo/config-plugins");
+const fs = require("fs");
+const path = require("path");
+
+// Autolinking handles registering the native module on both platforms. This
+// plugin covers what autolinking cannot:
+//   - Android: the SDK's FirebaseMessagingService + the permissions it needs
+//   - iOS:     CocoaPods/Xcode quirks that otherwise break the build
+//   - iOS:     the optional rich-push NotificationService extension
+//
+// Everything here is idempotent, so re-running prebuild is safe.
+
+const SERVICE = "com.mergn.insights.firebaseservices.FireBaseMessagingService";
+
+const PERMISSIONS = [
+  "android.permission.INTERNET",
+  "android.permission.POST_NOTIFICATIONS",
+  "android.permission.VIBRATE",
+];
+
+function withMergnAndroid(config) {
+  return withAndroidManifest(config, (cfg) => {
+    const manifest = cfg.modResults;
+
+    for (const name of PERMISSIONS) {
+      AndroidConfig.Manifest.ensurePermission(manifest, name);
+    }
+
+    const application = AndroidConfig.Manifest.getMainApplicationOrThrow(manifest);
+    application.service = application.service ?? [];
+
+    // The SDK's own messaging service must be declared for Mergn pushes to be
+    // delivered on Android; there is no autolinking equivalent for manifest
+    // entries.
+    if (!application.service.some((s) => s.$?.["android:name"] === SERVICE)) {
+      application.service.push({
+        $: {
+          "android:name": SERVICE,
+          "android:exported": "true",
+          "android:enabled": "true",
+        },
+        "intent-filter": [
+          { action: [{ $: { "android:name": "com.google.firebase.MESSAGING_EVENT" } }] },
+        ],
+      });
+    }
+
+    return cfg;
+  });
+}
+
+// Xcode 16/26 writes objectVersion 70+, which CocoaPods' Xcodeproj (<=1.16)
+// cannot serialize — `pod install` dies with "Unable to find compatibility
+// version string for object version `70`". Xcodeproj knows 63 and Xcode opens
+// 63 fine, so pin it. Re-applied each prebuild because Xcode bumps it back
+// whenever the project is opened in the IDE.
+function withCocoaPodsCompatibleProject(config) {
+  return withDangerousMod(config, [
+    "ios",
+    (cfg) => {
+      const pbxproj = path.join(
+        cfg.modRequest.platformProjectRoot,
+        `${cfg.modRequest.projectName}.xcodeproj`,
+        "project.pbxproj"
+      );
+      if (fs.existsSync(pbxproj)) {
+        const before = fs.readFileSync(pbxproj, "utf8");
+        const after = before.replace(/objectVersion = 7\d;/, "objectVersion = 63;");
+        if (after !== before) fs.writeFileSync(pbxproj, after);
+      }
+      return cfg;
+    },
+  ]);
+}
+
+// @react-native-firebase/app adds a script phase that declares the app's BUILT
+// Info.plist as an input but no outputs. Once any app extension has to be
+// embedded, that produces a dependency cycle:
+//   embed .appex -> needs app bundle -> needs Info.plist -> RNFB script -> ...
+// and the build fails with "Cycle inside <app>". Clearing the input and marking
+// the phase always-out-of-date breaks the cycle; the script still runs every
+// build, which is what it wants anyway.
+function withoutFirebaseScriptPhaseCycle(config) {
+  return withDangerousMod(config, [
+    "ios",
+    (cfg) => {
+      const pbxproj = path.join(
+        cfg.modRequest.platformProjectRoot,
+        `${cfg.modRequest.projectName}.xcodeproj`,
+        "project.pbxproj"
+      );
+      if (!fs.existsSync(pbxproj)) return cfg;
+
+      let contents = fs.readFileSync(pbxproj, "utf8");
+      contents = contents.replace(
+        /\/\* \[CP-User\] \[RNFB\] Core Configuration \*\/ = \{([\s\S]*?)\};/g,
+        (match, body) => {
+          let next = body.replace(/inputPaths = \([\s\S]*?\);/, "inputPaths = (\n\t\t\t);");
+          if (!/alwaysOutOfDate/.test(next)) {
+            next = next.replace(
+              "isa = PBXShellScriptBuildPhase;",
+              "isa = PBXShellScriptBuildPhase;\n\t\t\talwaysOutOfDate = 1;"
+            );
+          }
+          return `/* [CP-User] [RNFB] Core Configuration */ = {${next}};`;
+        }
+      );
+      fs.writeFileSync(pbxproj, contents);
+      return cfg;
+    },
+  ]);
+}
+
+// The Mergn SDK is a separate pod (sdk/MergnSDK.podspec) rather than part of the
+// autolinked wrapper, because a vendored framework declared on an autolinked pod
+// does not produce link flags - the app builds with no -framework "mergn_ios"
+// and then fails with "Unable to resolve module dependency: 'mergn_ios'".
+//
+// Autolinking cannot add a second pod, so inject it here. :path works because
+// the framework is bundled in the package; it points at the DIRECTORY, and
+// CocoaPods matches the podspec filename to the pod name - which is why
+// MergnSDK.podspec sits alone in sdk/ with the framework.
+function withMergnSdkPod(config) {
+  return withDangerousMod(config, [
+    "ios",
+    (cfg) => {
+      const podfile = path.join(cfg.modRequest.platformProjectRoot, "Podfile");
+      if (!fs.existsSync(podfile)) return cfg;
+
+      let contents = fs.readFileSync(podfile, "utf8");
+      if (contents.includes("pod 'MergnSDK'")) return cfg;
+
+      // Resolve from this plugin's own location so npm, yarn workspaces and
+      // pnpm layouts all work.
+      const packageRoot = path.join(__dirname, "..");
+      const relative = path
+        .relative(cfg.modRequest.platformProjectRoot, path.join(packageRoot, "sdk"))
+        .split(path.sep)
+        .join("/");
+
+      const line = `  pod 'MergnSDK', :path => '${relative}'`;
+      const anchor = "  use_expo_modules!";
+      if (!contents.includes(anchor)) {
+        throw new Error(
+          "mergn-react-native: could not find 'use_expo_modules!' in the Podfile. " +
+            "Add this line inside your app target manually:\n" + line
+        );
+      }
+      contents = contents.replace(anchor, `${anchor}\n${line}`);
+      fs.writeFileSync(podfile, contents);
+      return cfg;
+    },
+  ]);
+}
+
+// mergn_ios.xcframework is built for iOS 14, but Expo's Podfile template
+// defaults to 13.4 — so `pod install` fails with "they required a higher minimum
+// deployment target". Raise the floor here so the client does not have to know
+// the SDK's minimum, and only ever raise it (never lower an app that already
+// targets something newer).
+const MIN_IOS = "14.0";
+
+function withMinimumIosVersion(config) {
+  return withDangerousMod(config, [
+    "ios",
+    (cfg) => {
+      const file = path.join(
+        cfg.modRequest.platformProjectRoot,
+        "Podfile.properties.json"
+      );
+      let props = {};
+      if (fs.existsSync(file)) {
+        try {
+          props = JSON.parse(fs.readFileSync(file, "utf8"));
+        } catch {
+          props = {};
+        }
+      }
+
+      let changed = false;
+
+      const current = parseFloat(props["ios.deploymentTarget"] ?? "0");
+      if (!(current >= parseFloat(MIN_IOS))) {
+        props["ios.deploymentTarget"] = MIN_IOS;
+        changed = true;
+      }
+
+      // mergn_ios ships as a Swift .xcframework with only a .swiftmodule (no
+      // ObjC headers). Without use_frameworks! the module is not importable and
+      // the build fails with "Unable to resolve module dependency: 'mergn_ios'".
+      // "static" is chosen over "dynamic" because it is also what Firebase needs
+      // (its Swift pods cannot build against non-modular GoogleUtilities as
+      // plain static libraries), and most RN apps using Mergn also use Firebase.
+      if (!props["ios.useFrameworks"]) {
+        props["ios.useFrameworks"] = "static";
+        changed = true;
+      }
+
+      if (changed) {
+        fs.writeFileSync(file, JSON.stringify(props, null, 2) + "\n");
+      }
+      return cfg;
+    },
+  ]);
+}
+
+module.exports = function withMergn(config, props = {}) {
+  let next = withMergnAndroid(config);
+  next = withMinimumIosVersion(next);
+  next = withMergnSdkPod(next);
+  next = withoutFirebaseScriptPhaseCycle(next);
+  next = withCocoaPodsCompatibleProject(next);
+  return next;
+};

package/react-native.config.js

@@ -0,0 +1,19 @@
+// Tells React Native autolinking where the native code lives, so both platforms
+// register themselves on install — no manual MainApplication or Podfile edits.
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: 'android',
+        packageImportPath: 'import com.mergn.reactnative.MergnPackage;',
+        packageInstance: 'new MergnPackage()',
+      },
+      ios: {
+        // Only the wrapper podspec is listed; it declares a dependency on
+        // MergnSDK, which CocoaPods resolves from the podspec in this package
+        // (see the podspec_repo note in README) or from the local path below.
+        podspecPath: __dirname + '/mergn-react-native.podspec',
+      },
+    },
+  },
+};

package/scripts/release-ios.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Publish the Mergn iOS xcframework to GitHub Releases and update the podspec's
+# checksum, so the binary does not have to ship inside the npm package.
+#
+#   ./scripts/release-ios.sh 19.0.0 /path/to/mergn_ios.xcframework
+#
+# Requires the `gh` CLI, authenticated (`gh auth login`).
+# Free: public GitHub repos have unlimited release-asset storage and bandwidth.
+set -euo pipefail
+
+VERSION="${1:?usage: release-ios.sh <version> <path-to-xcframework>}"
+FRAMEWORK="${2:?usage: release-ios.sh <version> <path-to-xcframework>}"
+REPO="${MERGN_IOS_REPO:-SHamzaHMergn/Mergn_sdk_ios}"
+
+[ -d "$FRAMEWORK" ] || { echo "not a directory: $FRAMEWORK" >&2; exit 1; }
+
+# The framework's own minimum iOS must match the podspec, or clients hit link
+# errors that point nowhere useful.
+IFACE=$(find "$FRAMEWORK" -name "*-apple-ios.swiftinterface" | head -1)
+if [ -n "$IFACE" ]; then
+  MIN=$(grep -o "target arm64-apple-ios[0-9.]*" "$IFACE" | head -1 | sed 's/.*ios//')
+  echo "framework minimum iOS: ${MIN:-unknown}"
+fi
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+# Zip from the framework's PARENT dir so the archive contains
+# mergn_ios.xcframework/... and not an absolute path prefix.
+cp -R "$FRAMEWORK" "$WORK/"
+NAME=$(basename "$FRAMEWORK")
+( cd "$WORK" && zip -qr "$WORK/mergn_ios.xcframework.zip" "$NAME" )
+
+ZIP="$WORK/mergn_ios.xcframework.zip"
+SHA=$(shasum -a 256 "$ZIP" | awk '{print $1}')
+echo "zip:    $(du -h "$ZIP" | cut -f1)"
+echo "sha256: $SHA"
+
+# The upload needs either the gh CLI or a manual step; the zip and digest are
+# already produced either way, so the podspec can be updated regardless.
+OUT_DIR="${MERGN_RELEASE_OUT:-$PWD/dist}"
+mkdir -p "$OUT_DIR"
+cp "$ZIP" "$OUT_DIR/"
+
+if command -v gh >/dev/null 2>&1; then
+  gh release view "$VERSION" --repo "$REPO" >/dev/null 2>&1 \
+    && gh release upload "$VERSION" "$ZIP" --repo "$REPO" --clobber \
+    || gh release create "$VERSION" "$ZIP" --repo "$REPO" \
+         --title "Mergn iOS SDK $VERSION" \
+         --notes "xcframework for CocoaPods. sha256: $SHA"
+  echo "uploaded to https://github.com/$REPO/releases/tag/$VERSION"
+else
+  cat <<MSG
+
+gh CLI not found - the zip is ready but was NOT uploaded.
+
+  zip: $OUT_DIR/mergn_ios.xcframework.zip
+
+Either install the CLI:
+  brew install gh && gh auth login
+
+or upload by hand:
+  1. https://github.com/$REPO/releases/new
+  2. Tag: $VERSION
+  3. Attach the zip above, publish.
+
+The podspec below has been updated with the digest either way, so once the
+asset is live at the release URL nothing else needs changing.
+MSG
+fi
+
+# Keep the podspec's version and digest in lockstep with what was uploaded.
+SPEC="$(cd "$(dirname "$0")/.." && pwd)/sdk/MergnSDK.podspec"
+/usr/bin/sed -i '' -E "s/  s\.version      = '.*'/  s.version      = '$VERSION'/" "$SPEC"
+/usr/bin/sed -i '' -E "s/:sha256 => '[a-f0-9]*'/:sha256 => '$SHA'/" "$SPEC"
+
+echo
+echo "Updated $SPEC"
+echo "Verify with: pod spec lint MergnSDK.podspec"