zixflow-reactnative 1.0.0

package/src/utils/native-bridge.ts

@@ -0,0 +1,30 @@
+import { Platform } from 'react-native';
+
+const LINKING_ERROR =
+  `The package 'customerio-reactnative' doesn't seem to be linked. Make sure: \n\n` +
+  Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
+  '- You rebuilt the app after installing the package\n' +
+  '- You are not using Expo managed workflow\n';
+
+/**
+ * Ensures the native module is available, otherwise throws a helpful linking error.
+ */
+export function ensureNativeModule<NativeModule>(
+  nativeModule: NativeModule | null
+): NativeModule {
+  if (!nativeModule) {
+    throw new Error(LINKING_ERROR);
+  }
+
+  return nativeModule;
+}
+
+/**
+ * Calls a method on a native module with type-safe access.
+ */
+export const callNativeModule = <Spec, Result>(
+  nativeModule: Spec,
+  fn: (native: Spec) => Result
+): Result => {
+  return fn(nativeModule);
+};

package/src/utils/param-validation.ts

@@ -0,0 +1,178 @@
+// Argument validation utilities for SDK internal use
+// Ensures input safety and throws clear errors when validation fails
+
+import type { CioConfig, CustomAttributes } from '../types';
+
+/**
+ * Builds a standardized error message for validation failures.
+ */
+function buildErrorMessage(
+  usage: string | undefined,
+  fieldName: string,
+  error: string
+): string {
+  const prefix = usage ? `${usage} ` : '';
+  return `${prefix}"${fieldName}" ${error}.`;
+}
+
+/**
+ * Returns true if the value is undefined or null.
+ */
+function isUndefined(value: unknown): boolean {
+  return value === undefined || value === null;
+}
+
+/**
+ * Throws an error if the condition is true.
+ * Use this to fail validation checks with cleaner syntax.
+ */
+function failIf(condition: boolean, message: () => string): void {
+  if (__DEV__ && condition) {
+    throw new Error(`[CustomerIO] ${message()}`);
+  }
+}
+
+/**
+ * Validates that a value is defined (not undefined or null).
+ * Useful for checking required fields.
+ */
+function failIfUndefined(
+  value: unknown,
+  fieldName: string,
+  usage?: string
+): void {
+  failIf(isUndefined(value), () =>
+    buildErrorMessage(usage, fieldName, 'is required')
+  );
+}
+
+/**
+ * Validates that a value is a string.
+ * Throws if the value is not a string, or if it's empty (unless allowEmpty is true).
+ */
+function validateString(
+  value: unknown,
+  fieldName: string,
+  options: {
+    allowEmpty?: boolean;
+    usage?: string;
+    optional?: boolean;
+  } = { allowEmpty: true }
+) {
+  const { allowEmpty, usage, optional } = options;
+  if (optional && isUndefined(value)) {
+    return; // Skip validation for optional fields
+  }
+
+  const prefix = usage ? `${usage} ` : '';
+
+  failIfUndefined(value, fieldName, usage);
+  failIf(
+    typeof value !== 'string',
+    () => `${prefix}"${fieldName}" must be a string.`
+  );
+  // Since typeof value is already checked to be a string,
+  // we can safely cast it here without additional checks.
+  const typedValue = value as string;
+  failIf(
+    !allowEmpty && typedValue.trim() === '',
+    () => `${prefix}"${fieldName}" must be a non-empty string.`
+  );
+}
+
+/**
+ * Validates that a value is a plain object (not null or an array).
+ */
+function validateRecord(
+  value: unknown,
+  fieldName: string,
+  options: {
+    usage?: string;
+    expectedType?: string;
+    optional?: boolean;
+  } = {}
+) {
+  const { usage, expectedType, optional } = options;
+  if (optional && isUndefined(value)) {
+    return; // Skip validation for optional fields
+  }
+
+  const prefix = usage ? `${usage} ` : '';
+  const typeName = expectedType ?? 'plain';
+
+  failIfUndefined(value, fieldName, usage);
+  failIf(
+    typeof value !== 'object' || Array.isArray(value),
+    () => `${prefix}"${fieldName}" must be a valid ${typeName} object.`
+  );
+}
+
+/**
+ * Validates that a value is a valid CustomAttributes object.
+ * Automatically converts Map objects to plain objects for compatibility.
+ * This is a specialized version of validateRecord optimized for attribute validation.
+ */
+function validateAttributes(
+  value: unknown,
+  fieldName: string,
+  options: {
+    usage?: string;
+    expectedType?: string;
+    optional?: boolean;
+  } = {}
+): CustomAttributes | undefined {
+  const exists = !isUndefined(value);
+  if (options.optional && !exists) {
+    return; // Skip validation for optional fields
+  }
+
+  let attributes: unknown;
+  if (exists && value instanceof Map) {
+    // Convert Map to plain object for native serialization
+    attributes = Object.fromEntries(value);
+  } else {
+    attributes = value;
+  }
+  validateRecord(attributes, fieldName, options);
+  return attributes as CustomAttributes;
+}
+
+/**
+ * Validates that the given value is a valid CioConfig object.
+ * Throws if required fields are missing or incorrectly typed.
+ */
+function validateConfig(value: unknown): asserts value is CioConfig {
+  const fieldName = 'config';
+  const usage = 'SDK';
+
+  validateRecord(value, fieldName, {
+    expectedType: 'CioConfig',
+    usage: usage,
+  });
+
+  const obj = value as CioConfig;
+  validateString(obj.cdpApiKey, `${fieldName}.cdpApiKey`, {
+    allowEmpty: false,
+    usage: usage,
+  });
+}
+
+// For type safety, we define a ConfigValidator type that asserts the value is a CioConfig
+// This allows us to use it in the assert object without needing to redefine the function signature
+type ConfigValidator = (value: unknown) => asserts value is CioConfig;
+
+export const assert: {
+  string: typeof validateString;
+  record: typeof validateRecord;
+  attributes: typeof validateAttributes;
+  config: ConfigValidator;
+} = {
+  string: validateString,
+  record: validateRecord,
+  attributes: validateAttributes,
+  config: validateConfig,
+};
+
+export const validate = {
+  isUndefined: isUndefined,
+};

package/src/zixflow.ts

@@ -0,0 +1,24 @@
+/**
+ * Zixflow SDK - Main entry point
+ *
+ * This provides the Zixflow-branded API that wraps the underlying Customer.io implementation.
+ */
+
+import { CustomerIO } from './customerio-cdp';
+import { CustomerIOInAppMessaging } from './customerio-inapp';
+import { CustomerIOLocation } from './customerio-location';
+import { CustomerIOPushMessaging } from './customerio-push';
+
+// Re-export the CustomerIO class as Zixflow for branding
+export const Zixflow = CustomerIO;
+
+// Re-export all types and utilities
+export * from './types';
+export * from './notification-inbox';
+
+// Export sub-modules with their original names (they work with the main Zixflow class)
+export {
+  CustomerIOInAppMessaging,
+  CustomerIOLocation,
+  CustomerIOPushMessaging,
+};

package/zixflow-reactnative-richpush.podspec

@@ -0,0 +1,42 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+# Used by customers to install native iOS dependencies inside their Notification Service Extension (NSE) target to setup rich push.
+# Note: We need a unique podspec for rich push because the other podspecs in this project install too many dependencies that should not be installed inside of a NSE target. We need this podspec which installs minimal dependencies that are only included in the NSE target.
+Pod::Spec.new do |s|
+  s.name         = "zixflow-reactnative-richpush"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+  s.platforms    = { :ios => min_ios_version_supported }
+
+  s.source       = { :git => "https://github.com/zixflow/zixflow-reactnative.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+
+  # Note: Zixflow iOS SDK dependencies need to be added to NSE target via CocoaPods
+  # Add these pods to your NotificationServiceExtension target in your Podfile:
+  # pod "ZixflowMessagingPushAPN", "= 1.0.0" (or ZixflowMessagingPushFCM for FCM)
+  # pod "ZixflowMessagingPush", "= 1.0.0"
+  # pod "ZixflowDataPipelines", "= 1.0.0"
+  # pod "ZixflowCommon", "= 1.0.0"
+
+  # Subspecs allow customers to choose between multiple options of what type of version of this rich push package they would like to install.
+  # Set default subspec to 'apn' to prevent both APN and FCM dependencies from being installed by default.
+  #
+  # To override the default subspec, specify the desired subspec in your Podfile. For example:
+  # pod 'zixflow-reactnative-richpush/fcm'
+
+  s.default_subspec = 'apn'
+
+  s.subspec 'apn' do |ss|
+    # ZixflowMessagingPushAPN linked via SPM
+  end
+
+  s.subspec 'fcm' do |ss|
+    # ZixflowMessagingPushFCM linked via SPM
+  end
+end

package/zixflow-reactnative.podspec

@@ -0,0 +1,66 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+# Zixflow React Native wrapper podspec
+# Uses Zixflow iOS SDK via CocoaPods
+Pod::Spec.new do |s|
+  s.name         = "zixflow-reactnative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/zixflow/zixflow-reactnative.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/wrappers/**/*.{h,m,mm,swift}"
+
+  # Use install_modules_dependencies helper to install the dependencies if React Native version >=0.71.0.
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+  end
+
+  # Zixflow iOS SDK dependencies via CocoaPods
+  # Using `= X.X.X` for exact version matching
+  s.dependency "ZixflowDataPipelines", package["zixflowNativeiOSSdkVersion"]
+  s.dependency "ZixflowMessagingInApp", package["zixflowNativeiOSSdkVersion"]
+  s.dependency "ZixflowCommon", package["zixflowNativeiOSSdkVersion"]
+  s.dependency "ZixflowTrackingMigration", package["zixflowNativeiOSSdkVersion"]
+
+  # Transitive dependencies (required for explicit module builds)
+  s.dependency "AnalyticsSwiftZixflow", "1.7.3+zixflow.1"
+  s.dependency "JSONSafeEncoding", "~> 2.0"
+  s.dependency "Sovran", "~> 1.1"
+  s.dependency "LDSwiftEventSource", "~> 3.3"
+
+  # If we do not specify a default_subspec, then *all* dependencies inside of *all* the subspecs will be downloaded by cocoapods.
+  # We want customers to opt into push dependencies especially because the FCM subspec downloads Firebase dependencies. APN customers should not install Firebase dependencies at all.
+  s.default_subspec = "nopush"
+
+  s.subspec "nopush" do |ss|
+    # This is the default subspec designed to not install any push dependencies. Customer should choose APN or FCM.
+    # The SDK at runtime currently requires the MessagingPush module so we do include it here.
+    ss.dependency "ZixflowMessagingPush", package["zixflowNativeiOSSdkVersion"]
+  end
+
+  # Note: Subspecs inherit all dependencies specified the parent spec (this file).
+  s.subspec "apn" do |ss|
+    ss.dependency "ZixflowMessagingPushAPN", package["zixflowNativeiOSSdkVersion"]
+  end
+
+  s.subspec "fcm" do |ss|
+    ss.dependency "ZixflowMessagingPushFCM", package["zixflowNativeiOSSdkVersion"]
+  end
+
+  # Location module is optional - customers must opt in by adding this subspec.
+  s.subspec "location" do |ss|
+    ss.dependency "ZixflowLocation", package["zixflowNativeiOSSdkVersion"]
+    ss.pod_target_xcconfig = {
+      'OTHER_SWIFT_FLAGS' => '$(inherited) -DCIO_LOCATION_ENABLED'
+    }
+  end
+end