zixflow-reactnative 1.1.3 → 1.1.4

package/docs/cocoapods-deployment-target-normalization.md

@@ -0,0 +1,139 @@
+# CocoaPods deployment-target normalization
+
+Xcode validates the deployment target of every generated CocoaPods target, including dependency,
+aggregate, privacy-manifest, and resource-bundle targets. Xcode 27 rejects targets below the build
+range supported by its iOS SDK even when the dependency itself is source-compatible with your app.
+
+The `zixflow-reactnative` package includes an opt-in Podfile helper. It raises low or missing
+generated settings to the greater of React Native's current minimum and iOS 15.0. For React Native
+0.83 that value is iOS 15.1. It also covers integrated application, Notification Service
+Extension, and widget targets, while preserving higher numeric deployment targets. When a target
+setting is absent, the helper resolves its target xcconfig and then the same-named project build
+configuration, preserving a higher inherited app or extension floor. The helper changes local build
+settings in the generated Pods project and CocoaPods-integrated app or extension projects. It does
+not rewrite a podspec or change runtime API availability.
+
+The package owns and tests this copy of the helper because customer Podfiles must be able to load it
+from the installed npm package. When its behavior changes, update the helper, tests, and guidance
+together. It does not depend on a cross-repository source lock or require wrapper copies to remain
+byte-identical.
+
+Zixflow deliberately continues to publish native SDKs that support iOS versions below 15. A
+podspec can therefore correctly declare that lower library minimum even when React Native or the
+application consuming it requires a newer iOS version. CocoaPods carries deployment metadata from
+Zixflow and third-party podspecs into generated build targets, but Xcode 27 no longer accepts
+targets below the iOS SDK's supported build range. Raising every published podspec to iOS 15 would
+unnecessarily drop older applications and would not control metadata from transitive
+dependencies. The helper instead aligns the generated targets with the host application's chosen
+minimum while leaving the packages' published runtime compatibility unchanged.
+This is the supported integration policy for a React Native application that has moved its own
+minimum to the required iOS floor.
+
+> [!WARNING]
+> This is an opt-in build migration. Integrated app and extension targets below the computed floor
+> are raised to that floor. With React Native 0.83, shipping the resulting iOS 15.1 application
+> means users on iOS 15.0 and earlier cannot install subsequent app updates. Adopt the helper only
+> when your product has intentionally moved its application and extension deployment targets.
+
+Resolve the helper through Node so hoisted and monorepo installations work, then call it after
+`react_native_post_install` in the one existing `post_install` block:
+
+```ruby
+def node_resolve(script)
+  Pod::Executable.execute_command('node', ['-p',
+    "require.resolve('#{script}', {paths: [process.argv[1]]})",
+    __dir__
+  ]).strip
+end
+
+customer_io_package_root = File.dirname(node_resolve('zixflow-reactnative/package.json'))
+require File.join(customer_io_package_root, 'ios', 'cocoapods_deployment_target')
+
+customer_io_minimum_ios_version = Zixflow::CocoaPodsDeploymentTarget.maximum(
+  min_ios_version_supported,
+  '15.0'
+)
+
+post_install do |installer|
+  react_native_post_install(
+    installer,
+    config[:reactNativePath],
+    :mac_catalyst_enabled => false
+  )
+
+  Zixflow::CocoaPodsDeploymentTarget.normalize!(
+    installer,
+    minimum_ios_version: customer_io_minimum_ios_version
+  )
+end
+```
+
+Remove the generated `ios/Pods` directory and run `pod install` again. When a target build-setting
+key is absent, the helper resolves the target xcconfig and matching project configuration before
+adding an override. A present target key is authoritative, so lower-precedence xcconfig and project
+values are not inspected. This matches Xcode's treatment of an explicitly empty target value: it
+is missing and must be normalized, rather than inherited from a lower-precedence value. For each
+change, the helper prints a stable project, target, and configuration line with the original
+effective value and final value. It fails the install if the selected effective value is
+non-numeric, such as `$(CUSTOM_IOS_FLOOR)`, because the generated-project audit cannot prove its
+resolved value. A non-numeric value at a lower precedence does not fail when an explicit target
+setting already determines the effective value.
+SDK-, architecture-, or configuration-qualified keys such as
+`IPHONEOS_DEPLOYMENT_TARGET[sdk=iphoneos*]` also fail before mutation at the selected precedence.
+Xcode can choose a qualified key over an unconditional value, so adding a numeric override would
+not prove the effective floor and could lower a higher conditional project setting. Replace the
+selected conditional matrix with one numeric, unconditional deployment target before rerunning the
+helper.
+
+If the helper reports a non-numeric selected value, use the project, target, and configuration in
+the error to locate the authoritative `IPHONEOS_DEPLOYMENT_TARGET`. Replace the macro or inherited
+expression at that precedence with its intended numeric version, then run `pod install` again. For
+a generated Pods target, make that override durably in the Podfile's `post_install` hook before
+calling `Zixflow::CocoaPodsDeploymentTarget.normalize!`, or correct the podspec that supplies the
+expression; do not edit the generated project because the next install replaces it. Do not skip
+that target: continuing with an unresolved expression would leave the generated project outside
+the deterministic audit. The helper validates every selected value before changing any project,
+so this failure does not leave a partially normalized installation.
+
+If an error says a selected xcconfig cannot be read or parsed, repair or remove the reported base
+configuration file reference for the reported project, target, and configuration. Lower-precedence
+xcconfigs are not parsed when the target build-setting key is present. Run the helper in the
+CocoaPods Ruby environment so the public `Xcodeproj::Config` parser is available.
+Synchronized-group xcconfig references are not resolved by that public parser; if the helper
+reports one, replace it with a standard xcconfig file reference, then run `pod install` again.
+These cases fail before any project mutation.
+
+## When the helper is no longer needed
+
+Keep the helper while a supported dependency graph can validly include deployment metadata below
+the host application's minimum. This is expected while Zixflow supports older iOS versions or
+supported third-party pods continue to declare lower minimums. A `platform` declaration in the
+application's Podfile alone does not guarantee that every generated target uses the same value.
+
+The helper becomes unnecessary only when a clean install without it proves that every
+target/configuration in every supported React Native and push-provider graph declares an effective
+numeric deployment target at or above the host application's minimum. That state would normally
+follow an intentional platform-support change across the SDK, wrappers, and relevant dependencies;
+it is not a prerequisite for adopting Xcode 27. Keep the audit in CI after removing the helper so
+a later dependency update cannot silently reintroduce a lower target.
+
+Repository contributors also have a deterministic CI audit under `scripts/` that prints the target,
+matching project, and effective value for every generated target/configuration pair in stable
+order. That audit script is not part of the published npm package. It examines every target in each
+passed project, including non-integrated targets that the normalizer intentionally does not change;
+set those targets to the host minimum explicitly. Pass the `Pods` directory so the audit discovers
+every `.xcodeproj` directly under it, including CocoaPods multi-project output, while ignoring
+unrelated example projects vendored inside downloaded pod sources. It fails if a supplied path is
+missing or contains no projects.
+
+```sh
+cd example
+bundle exec ruby ../scripts/audit_cocoapods_deployment_targets.rb \
+  --minimum 15.1 \
+  ios/Pods \
+  ios/SampleApp.xcodeproj
+```
+
+Keep this audit next to the React Native simulator build and unsigned generic-device archive.
+Passing those checks does not prove real-device push delivery, signed archive export, or App Store
+submission.

package/ios/cocoapods_deployment_target.rb

@@ -0,0 +1,432 @@
+# frozen_string_literal: true
+
+# This packaged copy is owned by zixflow-reactnative and covered by its local test suite.
+
+require "rubygems/version"
+
+module Zixflow
+  # Normalizes every CocoaPods-generated target and every integrated application or extension
+  # target to a numeric iOS deployment target that the selected Xcode toolchain supports.
+  module CocoaPodsDeploymentTarget
+    BUILD_SETTING = "IPHONEOS_DEPLOYMENT_TARGET"
+    VERSION_PATTERN = /\A\d+(?:\.\d+){0,2}\z/.freeze
+
+    Record = Struct.new(
+      :project,
+      :target,
+      :configuration,
+      :original_effective,
+      :target_configuration_value,
+      :project_value,
+      :current,
+      :changed,
+      :configuration_object,
+      keyword_init: true
+    )
+
+    class AuditError < StandardError; end
+
+    module_function
+
+    # Raises low effective deployment settings to +minimum_ios_version+. A missing target setting
+    # resolves through its xcconfig and then the same-named project configuration. Numeric effective
+    # settings above the minimum are preserved. A selected non-numeric effective setting fails
+    # closed because its resolved value cannot be audited deterministically from the project.
+    def normalize!(installer, minimum_ios_version:, io: $stdout)
+      minimum = parse_version!(minimum_ios_version, context: "minimum iOS version")
+      targets = installer_targets(installer)
+      records = records_for(targets)
+      ensure_records!(records)
+      validate_numeric_settings!(records)
+
+      records = records.map do |record|
+        normalize_record!(record, minimum)
+      end
+
+      audit_records!(records, minimum)
+      save_integrated_user_projects!(installer, records)
+      write_changes(io, records)
+      write_summary(io, records, minimum)
+      records
+    end
+
+    # Audits an installer without modifying it. This is useful from a second post-install check.
+    def audit!(installer, minimum_ios_version:, io: $stdout)
+      minimum = parse_version!(minimum_ios_version, context: "minimum iOS version")
+      records = records_for(installer_targets(installer))
+      ensure_records!(records)
+
+      audit_records!(records, minimum)
+      write_summary(io, records, minimum)
+      records
+    end
+
+    # Audits projects loaded by Xcodeproj. The caller owns loading the projects so this helper does
+    # not add a runtime dependency on Xcodeproj to the normal Podfile integration path.
+    def audit_projects!(projects, minimum_ios_version:, io: $stdout)
+      minimum = parse_version!(minimum_ios_version, context: "minimum iOS version")
+      targets = projects.flat_map { |project| project.targets }
+      records = records_for(targets)
+      ensure_records!(records)
+
+      audit_records!(records, minimum)
+      write_records(io, records, minimum)
+      records
+    end
+
+    # Returns the greater of two numeric iOS deployment targets. React Native integrations use
+    # this to preserve React Native's own floor when it is higher than Zixflow's floor.
+    def maximum(first, second)
+      first_version = parse_version!(first, context: "iOS version")
+      second_version = parse_version!(second, context: "iOS version")
+      [first_version, second_version].max.to_s
+    end
+
+    def installer_targets(installer)
+      generated_projects = if installer.respond_to?(:generated_projects)
+                             Array(installer.generated_projects).compact
+                           else
+                             []
+                           end
+      if generated_projects.empty? && installer.respond_to?(:pods_project)
+        generated_projects = [installer.pods_project].compact
+      end
+
+      pod_targets = generated_projects.flat_map { |project| project.targets }
+      user_targets = if installer.respond_to?(:aggregate_targets)
+                       Array(installer.aggregate_targets).flat_map do |aggregate_target|
+                         aggregate_target.respond_to?(:user_targets) ? Array(aggregate_target.user_targets) : []
+                       end
+                     else
+                       []
+                     end
+
+      deduplicate_targets(pod_targets + user_targets)
+    end
+    private_class_method :installer_targets
+
+    def save_integrated_user_projects!(installer, records)
+      return unless installer.respond_to?(:aggregate_targets)
+
+      changed_project_paths = records.select(&:changed).map(&:project).uniq
+      return if changed_project_paths.empty?
+
+      projects = Array(installer.aggregate_targets).each_with_object([]) do |aggregate_target, result|
+        if aggregate_target.respond_to?(:user_project)
+          user_project = aggregate_target.user_project
+          result << user_project unless user_project.nil?
+        end
+        next unless aggregate_target.respond_to?(:user_targets)
+
+        Array(aggregate_target.user_targets).each do |target|
+          result << target.project if target.respond_to?(:project) && !target.project.nil?
+        end
+      end.compact
+
+      projects.select { |project| changed_project_paths.include?(project_path(project)) }
+              .uniq { |project| project_path(project) }
+              .each do |project|
+        unless project.respond_to?(:save)
+          raise AuditError, "Cannot save integrated user project #{project_path(project)}"
+        end
+
+        project.save
+      end
+    end
+    private_class_method :save_integrated_user_projects!
+
+    def deduplicate_targets(targets)
+      targets.each_with_object({}) do |target, unique|
+        project = target.respond_to?(:project) ? target.project : nil
+        project_key = project_path(project)
+        target_key = target.respond_to?(:uuid) ? target.uuid : target.object_id
+        unique[[project_key, target_key]] ||= target
+      end.values
+    end
+    private_class_method :deduplicate_targets
+
+    def normalize_record!(record, minimum)
+      current = record.current
+      current_version = current.nil? ? nil : parse_version!(current, context: record_context(record))
+      return record if current_version && current_version >= minimum
+
+      record.configuration_object.build_settings[BUILD_SETTING] = minimum.to_s
+      record.current = minimum.to_s
+      record.changed = true
+      record
+    end
+    private_class_method :normalize_record!
+
+    def records_for(targets)
+      targets.flat_map do |target|
+        project = target.respond_to?(:project) ? target.project : nil
+        target.build_configurations.map do |configuration|
+          context = configuration_context(project, target, configuration)
+          validate_no_conditional_settings!(configuration.build_settings, context: context)
+          target_setting_present = configuration.build_settings.key?(BUILD_SETTING)
+          target_value = normalized_setting(configuration.build_settings[BUILD_SETTING])
+          if target_setting_present
+            target_configuration_value = nil
+            project_value = nil
+            effective_value = target_value
+          else
+            target_configuration_present, target_configuration_value = configuration_file_setting(
+              configuration,
+              context: context
+            )
+            if target_configuration_present
+              project_value = nil
+              effective_value = target_configuration_value
+            else
+              project_configuration = matching_project_configuration(project, configuration.name)
+              project_value = effective_configuration_value(
+                project_configuration,
+                context: context
+              )
+              effective_value = project_value
+            end
+          end
+          Record.new(
+            project: project_path(project),
+            target: target.name.to_s,
+            configuration: configuration.name.to_s,
+            original_effective: effective_value,
+            target_configuration_value: target_configuration_value,
+            project_value: project_value,
+            current: effective_value,
+            changed: false,
+            configuration_object: configuration
+          )
+        end
+      end.sort_by { |record| [record.project, record.target, record.configuration] }
+    end
+    private_class_method :records_for
+
+    def effective_configuration_value(configuration, context:)
+      return nil if configuration.nil?
+
+      validate_no_conditional_settings!(configuration.build_settings, context: context)
+
+      if configuration.build_settings.key?(BUILD_SETTING)
+        return normalized_setting(configuration.build_settings[BUILD_SETTING])
+      end
+
+      _present, value = configuration_file_setting(configuration, context: context)
+      value
+    end
+    private_class_method :effective_configuration_value
+
+    def configuration_file_setting(configuration, context:)
+      synchronized_anchor = if configuration.respond_to?(:base_configuration_reference_anchor)
+                              configuration.base_configuration_reference_anchor
+                            end
+      synchronized_relative_path = if configuration.respond_to?(:base_configuration_reference_relative_path)
+                                     configuration.base_configuration_reference_relative_path
+                                   end
+      if synchronized_anchor || synchronized_relative_path
+        raise AuditError,
+              "#{context}: Cannot inspect synchronized-group xcconfig " \
+              "#{rendered_synchronized_path(synchronized_anchor, synchronized_relative_path)}. " \
+              "Use a standard xcconfig file reference before rerunning CocoaPods."
+      end
+
+      base_configuration_reference = if configuration.respond_to?(:base_configuration_reference)
+                                       configuration.base_configuration_reference
+                                     end
+      if base_configuration_reference
+        xcconfig_path = if base_configuration_reference.respond_to?(:real_path)
+                          base_configuration_reference.real_path
+                        end
+        unless xcconfig_path.respond_to?(:exist?) && xcconfig_path.exist? &&
+               xcconfig_path.respond_to?(:readable?) && xcconfig_path.readable?
+          rendered_path = xcconfig_path.nil? ? "(unresolved path)" : xcconfig_path.to_s
+          raise AuditError, "#{context}: Cannot read xcconfig #{rendered_path}"
+        end
+
+        unless defined?(::Xcodeproj::Config)
+          raise AuditError,
+                "#{context}: Cannot parse xcconfig #{xcconfig_path}; Xcodeproj::Config is unavailable"
+        end
+
+        begin
+          settings = ::Xcodeproj::Config.new(xcconfig_path).to_hash
+        rescue StandardError => error
+          raise AuditError,
+                "#{context}: Cannot parse xcconfig #{xcconfig_path}: " \
+                "#{error.class}: #{error.message}"
+        end
+
+        unless settings.respond_to?(:key?)
+          raise AuditError, "#{context}: Cannot inspect xcconfig #{xcconfig_path}"
+        end
+        validate_no_conditional_settings!(
+          settings,
+          context: "#{context}, xcconfig #{xcconfig_path}"
+        )
+        return [false, nil] unless settings.key?(BUILD_SETTING)
+
+        return [true, normalized_setting(settings[BUILD_SETTING])]
+      end
+
+      [false, nil]
+    end
+    private_class_method :configuration_file_setting
+
+    def validate_no_conditional_settings!(settings, context:)
+      conditional_setting_pattern = /\A#{Regexp.escape(BUILD_SETTING)}[[:space:]]*\[/
+      conditional_keys = settings.keys.map(&:to_s).select do |key|
+        key.match?(conditional_setting_pattern)
+      end.sort
+      return if conditional_keys.empty?
+
+      raise AuditError,
+            "#{context} has conditional #{BUILD_SETTING} settings that cannot be audited deterministically: " \
+            "#{conditional_keys.join(', ')}. Replace them with one numeric, unconditional #{BUILD_SETTING} " \
+            "before running this helper."
+    end
+    private_class_method :validate_no_conditional_settings!
+
+    def rendered_synchronized_path(anchor, relative_path)
+      anchor_path = if anchor.respond_to?(:path)
+                      anchor.path
+                    elsif anchor.respond_to?(:display_name)
+                      anchor.display_name
+                    else
+                      "(unknown anchor)"
+                    end
+      [anchor_path, relative_path].compact.map(&:to_s).reject(&:empty?).join("/")
+    end
+    private_class_method :rendered_synchronized_path
+
+    def matching_project_configuration(project, configuration_name)
+      return nil if project.nil? || !project.respond_to?(:build_configurations)
+
+      Array(project.build_configurations).find do |configuration|
+        configuration.name.to_s == configuration_name.to_s
+      end
+    end
+    private_class_method :matching_project_configuration
+
+    def ensure_records!(records)
+      return unless records.empty?
+
+      raise AuditError, "CocoaPods iOS deployment-target audit found no target configurations"
+    end
+    private_class_method :ensure_records!
+
+    def validate_numeric_settings!(records)
+      records.each do |record|
+        parse_version!(record.current, context: record_context(record)) unless record.current.nil?
+      end
+    end
+    private_class_method :validate_numeric_settings!
+
+    def audit_records!(records, minimum)
+      violations = records.each_with_object([]) do |record, result|
+        current = record.current
+        if current.nil?
+          result << "#{record_context(record)} is missing #{BUILD_SETTING}"
+        else
+          begin
+            version = parse_version!(current, context: record_context(record))
+            if version < minimum
+              result << "#{record_context(record)} is #{current}, below #{minimum}"
+            end
+          rescue AuditError => error
+            result << error.message
+          end
+        end
+      end
+
+      return if violations.empty?
+
+      raise AuditError, "CocoaPods iOS deployment-target audit failed:\n- #{violations.join("\n- ")}"
+    end
+    private_class_method :audit_records!
+
+    def write_summary(io, records, minimum)
+      return if io.nil?
+
+      changed = records.count(&:changed)
+      io.puts(
+        "Zixflow CocoaPods deployment-target audit passed: " \
+        "#{records.length} target configurations at iOS #{minimum} or newer (#{changed} normalized)."
+      )
+    end
+    private_class_method :write_summary
+
+    def write_changes(io, records)
+      return if io.nil?
+
+      records.select(&:changed).each do |record|
+        original = record.original_effective.nil? ? "missing" : record.original_effective
+        io.puts(
+          "Zixflow CocoaPods deployment target normalized: " \
+          "#{record_context(record)}: #{original} -> #{record.current}"
+        )
+      end
+    end
+    private_class_method :write_changes
+
+    def write_records(io, records, minimum)
+      return if io.nil?
+
+      io.puts(
+        "project\ttarget\tconfiguration\ttarget_#{BUILD_SETTING}\t" \
+        "target_xcconfig_#{BUILD_SETTING}\t" \
+        "project_#{BUILD_SETTING}\teffective_#{BUILD_SETTING}"
+      )
+      records.each do |record|
+        target_value = normalized_setting(record.configuration_object.build_settings[BUILD_SETTING])
+        io.puts(
+          [
+            record.project,
+            record.target,
+            record.configuration,
+            target_value,
+            record.target_configuration_value,
+            record.project_value,
+            record.current
+          ].join("\t")
+        )
+      end
+      write_summary(io, records, minimum)
+    end
+    private_class_method :write_records
+
+    def parse_version!(value, context:)
+      normalized = normalized_setting(value)
+      unless normalized&.match?(VERSION_PATTERN)
+        rendered = normalized.nil? ? "missing" : normalized.inspect
+        raise AuditError, "#{context} has non-numeric #{BUILD_SETTING}: #{rendered}"
+      end
+
+      Gem::Version.new(normalized)
+    end
+    private_class_method :parse_version!
+
+    def normalized_setting(value)
+      normalized = value.nil? ? nil : value.to_s.strip
+      normalized.nil? || normalized.empty? ? nil : normalized
+    end
+    private_class_method :normalized_setting
+
+    def record_context(record)
+      "#{record.project}: target #{record.target}, configuration #{record.configuration}"
+    end
+    private_class_method :record_context
+
+    def configuration_context(project, target, configuration)
+      "#{project_path(project)}: target #{target.name}, configuration #{configuration.name}"
+    end
+    private_class_method :configuration_context
+
+    def project_path(project)
+      return "unknown-project" if project.nil?
+      return project.path.to_s if project.respond_to?(:path) && project.path
+
+      project.to_s
+    end
+    private_class_method :project_path
+  end
+end

package/ios/wrappers/NativeZixflow.mm

@@ -1,7 +1,12 @@
 #import "utils/RCTZixflowUtils.h"
 #import <React/RCTBridgeModule.h>
+#import <React/RCTInvalidating.h>
 #import <RNZixflowSpec/RNZixflowSpec.h>
 
+@protocol NativeZixflowBridge <NativeZixflowSpec, RCTInvalidating>
+- (void)setEventEmitter:(id)emitter;
+@end
+
 // Objective-C wrapper for new architecture TurboModule implementation
 @interface RCTNativeZixflow : NSObject <NativeZixflowSpec>
 // Bridge to Swift implementation for cross-language compatibility
@@ -30,6 +35,7 @@ RCT_EXPORT_MODULE()
     RCT_ASSERT_NOT_NIL(swiftClass, @"NativeZixflow Swift class", @"during runtime lookup");
     _swiftBridge = [[swiftClass alloc] init];
     [self assertBridgeAvailable:@"creating NativeZixflow Swift instance"];
+    [_swiftBridge setEventEmitter:self];
   }
   return self;
 }
@@ -47,6 +53,37 @@ RCT_EXPORT_MODULE()
   [_swiftBridge initialize:config args:args resolve:resolve reject:reject];
 }
 
+- (void)setDeepLinkRoutingReady {
+  [self assertBridgeAvailable:@"during setDeepLinkRoutingReady"];
+  [_swiftBridge setDeepLinkRoutingReady];
+}
+
+- (void)registerDeepLinkHandler {
+  [self assertBridgeAvailable:@"during registerDeepLinkHandler"];
+  [_swiftBridge registerDeepLinkHandler];
+}
+
+- (void)unregisterDeepLinkHandler {
+  [self assertBridgeAvailable:@"during unregisterDeepLinkHandler"];
+  [_swiftBridge unregisterDeepLinkHandler];
+}
+
+- (void)acknowledgeDeepLink:(NSString *)id handled:(BOOL)handled {
+  [self assertBridgeAvailable:@"during acknowledgeDeepLink"];
+  [_swiftBridge acknowledgeDeepLink:id handled:handled];
+}
+
+- (void)invalidate {
+  [self assertBridgeAvailable:@"during invalidate"];
+  [_swiftBridge invalidate];
+}
+
+// Pins the Codegen event name at compile time. Keep this in sync with the TypeScript spec and the
+// runtime selector in NativeZixflow.swift.
+- (void)emitOnDeepLinkReceived:(NSDictionary *)value {
+  [super emitOnDeepLinkReceived:value];
+}
+
 - (void)identify:(NSDictionary *)params {
   [self assertBridgeAvailable:@"during identify"];
   [_swiftBridge identify:params];