react-native-qpush 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "react-native-qpush",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "React Native and Expo push notification SDK for qpush: OneSignal-style API, rich notifications, delivery and click reports, and the qpush cloud API.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "android/build.gradle",
+    "android/gradle.properties",
+    "android/src",
+    "android/proguard-rules.pro",
+    "ios/*.h",
+    "ios/*.m",
+    "ios/*.swift",
+    "ios/Extension",
+    "ios_nse_template",
+    "plugin",
+    "app.plugin.js",
+    "react-native.config.js",
+    "react-native-qpush.podspec",
+    "!**/__tests__",
+    "!android/build",
+    "!android/.gradle"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "react-native",
+    "push",
+    "notifications",
+    "fcm",
+    "apns",
+    "onesignal",
+    "qpush",
+    "expo"
+  ],
+  "license": "MIT",
+  "author": "qpush (https://qpush.dev)",
+  "homepage": "https://qpush.dev",
+  "peerDependencies": {
+    "expo": ">=50.0.0",
+    "react": "*",
+    "react-native": ">=0.71.0"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@expo/config-plugins": "^58.0.9",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.0",
+    "@types/react": "^19.1.4",
+    "jest": "^29.7.0",
+    "react": "^19.1.4",
+    "react-native": "0.81.6",
+    "ts-jest": "^29.4.5",
+    "typescript": "~5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/withQPush.js

@@ -0,0 +1,330 @@
+/**
+ * Expo config plugin for react-native-qpush (mirrors onesignal-expo-plugin).
+ *
+ * iOS:
+ *  - entitlements: aps-environment + App Group `group.{bundle_id}.qpush`
+ *  - Info.plist: UIBackgroundModes `remote-notification`
+ *  - Notification Service Extension target `QPushNotificationServiceExtension`
+ *    created from ios_nse_template/ (unless `disableNSE`), its Podfile entry and
+ *    the EAS credentials config for the extension.
+ * Android:
+ *  - optional default small icon (`smallIcon`) and accent color (`accentColor`).
+ *
+ * Usage (app.json):
+ *   "plugins": [["react-native-qpush", { "mode": "development" }]]
+ */
+const fs = require('fs');
+const path = require('path');
+
+let configPlugins;
+try {
+  configPlugins = require('expo/config-plugins');
+} catch (error) {
+  configPlugins = require('@expo/config-plugins');
+}
+
+const {
+  AndroidConfig,
+  createRunOncePlugin,
+  withAndroidManifest,
+  withDangerousMod,
+  withEntitlementsPlist,
+  withInfoPlist,
+  withXcodeProject,
+} = configPlugins;
+
+const pkg = require('../package.json');
+
+const NSE_TARGET_NAME = 'QPushNotificationServiceExtension';
+const NSE_SOURCE_FILE = 'NotificationService.swift';
+const NSE_INFO_PLIST = `${NSE_TARGET_NAME}-Info.plist`;
+const NSE_ENTITLEMENTS = `${NSE_TARGET_NAME}.entitlements`;
+const NSE_EXT_FILES = [NSE_SOURCE_FILE, NSE_INFO_PLIST, NSE_ENTITLEMENTS];
+const TEMPLATE_DIR = path.join(__dirname, '..', 'ios_nse_template');
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const DEFAULT_NSE_DEPLOYMENT_TARGET = '15.1';
+const PODFILE_MARKER = `target '${NSE_TARGET_NAME}' do`;
+const ANDROID_ICON_NAME = 'ic_stat_qpush_default';
+const ANDROID_ACCENT_META = 'com.qpush.NotificationAccentColor.DEFAULT';
+
+function log(message) {
+  console.log(`› [react-native-qpush] ${message}`);
+}
+
+function validateProps(props) {
+  const options = props || {};
+  const mode = options.mode || 'development';
+  if (mode !== 'development' && mode !== 'production') {
+    throw new Error(`react-native-qpush: "mode" must be "development" or "production" (got "${mode}")`);
+  }
+  return { ...options, mode };
+}
+
+function requireBundleId(config) {
+  const bundleId = config.ios && config.ios.bundleIdentifier;
+  if (!bundleId) {
+    throw new Error('react-native-qpush: "ios.bundleIdentifier" is required in your app config');
+  }
+  return bundleId;
+}
+
+function appGroupName(config, props) {
+  return props.appGroup || `group.${requireBundleId(config)}.qpush`;
+}
+
+// -----------------------------------------------------------------------------
+// iOS: entitlements & Info.plist
+// -----------------------------------------------------------------------------
+
+const withQPushEntitlements = (config, props) =>
+  withEntitlementsPlist(config, (cfg) => {
+    cfg.modResults['aps-environment'] = props.mode;
+    const key = 'com.apple.security.application-groups';
+    const groups = Array.isArray(cfg.modResults[key]) ? cfg.modResults[key] : [];
+    const group = appGroupName(cfg, props);
+    if (!groups.includes(group)) groups.push(group);
+    cfg.modResults[key] = groups;
+    return cfg;
+  });
+
+const withQPushInfoPlist = (config, props) =>
+  withInfoPlist(config, (cfg) => {
+    const modes = Array.isArray(cfg.modResults.UIBackgroundModes) ? cfg.modResults.UIBackgroundModes : [];
+    if (!modes.includes('remote-notification')) modes.push('remote-notification');
+    cfg.modResults.UIBackgroundModes = modes;
+    if (props.appGroup) cfg.modResults.QPushAppGroup = props.appGroup;
+    if (props.suppressLaunchUrls === true) cfg.modResults.QPush_suppress_launch_urls = true;
+    if (props.mode === 'development') {
+      // Development builds often talk to a plain-HTTP QPush server on the
+      // LAN (e.g. http://my-mac.local:8080). IP addresses are already exempt
+      // from App Transport Security; this also allows .local hostnames.
+      const ats = cfg.modResults.NSAppTransportSecurity && typeof cfg.modResults.NSAppTransportSecurity === 'object'
+        ? cfg.modResults.NSAppTransportSecurity
+        : {};
+      ats.NSAllowsLocalNetworking = true;
+      cfg.modResults.NSAppTransportSecurity = ats;
+    }
+    return cfg;
+  });
+
+// -----------------------------------------------------------------------------
+// iOS: Notification Service Extension
+// -----------------------------------------------------------------------------
+
+function nsePodfileSnippet(iosRoot) {
+  // The helper podspec is in ios/Extension/, not in the package root (see the podspec).
+  const podspecDir = path.join(fs.realpathSync(PACKAGE_ROOT), 'ios', 'Extension');
+  let podPath = path.relative(iosRoot, podspecDir).split(path.sep).join('/');
+  if (!podPath.startsWith('.')) podPath = `./${podPath}`;
+  return `
+${PODFILE_MARKER}
+  pod 'QPushPushExtension', :path => '${podPath}'
+end
+`;
+}
+
+function updatePodfile(iosRoot) {
+  const podfilePath = path.join(iosRoot, 'Podfile');
+  if (!fs.existsSync(podfilePath)) {
+    log('Podfile not found, skipping the Notification Service Extension pod');
+    return;
+  }
+  const podfile = fs.readFileSync(podfilePath, 'utf8');
+  if (podfile.includes(PODFILE_MARKER)) {
+    log(`Podfile already contains ${NSE_TARGET_NAME}, skipping`);
+    return;
+  }
+  fs.appendFileSync(podfilePath, nsePodfileSnippet(iosRoot));
+}
+
+function fillTemplate(text, values) {
+  return Object.keys(values).reduce((result, key) => result.split(`{{${key}}}`).join(values[key]), text);
+}
+
+const withQPushNseFiles = (config, props) =>
+  withDangerousMod(config, [
+    'ios',
+    async (cfg) => {
+      const iosRoot = cfg.modRequest.platformProjectRoot;
+      const targetDir = path.join(iosRoot, NSE_TARGET_NAME);
+      fs.mkdirSync(targetDir, { recursive: true });
+
+      const sourceFile = props.nseFilePath
+        ? path.resolve(cfg.modRequest.projectRoot, props.nseFilePath)
+        : path.join(TEMPLATE_DIR, NSE_SOURCE_FILE);
+      if (!fs.existsSync(sourceFile)) {
+        throw new Error(`react-native-qpush: NSE source file not found: ${sourceFile}`);
+      }
+      fs.copyFileSync(sourceFile, path.join(targetDir, NSE_SOURCE_FILE));
+
+      const values = {
+        VERSION: String(cfg.version || '1.0.0'),
+        BUILD_NUMBER: String((cfg.ios && cfg.ios.buildNumber) || '1'),
+        APP_GROUP: appGroupName(cfg, props),
+      };
+      const infoPlist = fs.readFileSync(path.join(TEMPLATE_DIR, 'Info.plist'), 'utf8');
+      fs.writeFileSync(path.join(targetDir, NSE_INFO_PLIST), fillTemplate(infoPlist, values));
+      const entitlements = fs.readFileSync(path.join(TEMPLATE_DIR, 'NotificationService.entitlements'), 'utf8');
+      fs.writeFileSync(path.join(targetDir, NSE_ENTITLEMENTS), fillTemplate(entitlements, values));
+
+      updatePodfile(iosRoot);
+      return cfg;
+    },
+  ]);
+
+const withQPushXcodeProject = (config, props) =>
+  withXcodeProject(config, (cfg) => {
+    const project = cfg.modResults;
+    const bundleId = requireBundleId(cfg);
+
+    // xcode stores names created by addTarget with quotes: check both forms.
+    if (project.pbxTargetByName(NSE_TARGET_NAME) || project.pbxTargetByName(`"${NSE_TARGET_NAME}"`)) {
+      log(`${NSE_TARGET_NAME} already exists in the Xcode project, skipping`);
+      return cfg;
+    }
+
+    // Group with the extension files, attached to the project's main group.
+    const extensionGroup = project.addPbxGroup(NSE_EXT_FILES, NSE_TARGET_NAME, NSE_TARGET_NAME);
+    const groups = project.hash.project.objects.PBXGroup;
+    Object.keys(groups).forEach((key) => {
+      const group = groups[key];
+      if (typeof group === 'object' && group.name === undefined && group.path === undefined) {
+        project.addToPbxGroup(extensionGroup.uuid, key);
+      }
+    });
+
+    // xcode's addTarget expects these sections to exist (missing in single-target projects).
+    const objects = project.hash.project.objects;
+    objects.PBXTargetDependency = objects.PBXTargetDependency || {};
+    objects.PBXContainerItemProxy = objects.PBXContainerItemProxy || {};
+
+    // Adds the target, its build configurations, the "embed" copy phase in the
+    // app target and the target dependency.
+    const target = project.addTarget(NSE_TARGET_NAME, 'app_extension', NSE_TARGET_NAME, `${bundleId}.${NSE_TARGET_NAME}`);
+    project.addBuildPhase([NSE_SOURCE_FILE], 'PBXSourcesBuildPhase', 'Sources', target.uuid);
+    project.addBuildPhase([], 'PBXResourcesBuildPhase', 'Resources', target.uuid);
+    project.addBuildPhase([], 'PBXFrameworksBuildPhase', 'Frameworks', target.uuid);
+
+    const configurations = project.pbxXCBuildConfigurationSection();
+    Object.keys(configurations).forEach((key) => {
+      const buildSettings = configurations[key].buildSettings;
+      if (!buildSettings || buildSettings.PRODUCT_NAME !== `"${NSE_TARGET_NAME}"`) return;
+      buildSettings.IPHONEOS_DEPLOYMENT_TARGET = props.iPhoneDeploymentTarget || DEFAULT_NSE_DEPLOYMENT_TARGET;
+      buildSettings.TARGETED_DEVICE_FAMILY = '"1,2"';
+      buildSettings.CODE_SIGN_ENTITLEMENTS = `${NSE_TARGET_NAME}/${NSE_ENTITLEMENTS}`;
+      buildSettings.CODE_SIGN_STYLE = 'Automatic';
+      buildSettings.SWIFT_VERSION = '5.0';
+      buildSettings.MARKETING_VERSION = String(cfg.version || '1.0.0');
+      buildSettings.CURRENT_PROJECT_VERSION = String((cfg.ios && cfg.ios.buildNumber) || '1');
+      if (props.devTeam) buildSettings.DEVELOPMENT_TEAM = props.devTeam;
+    });
+
+    if (props.devTeam) {
+      project.addTargetAttribute('DevelopmentTeam', props.devTeam, target);
+      project.addTargetAttribute('DevelopmentTeam', props.devTeam);
+    }
+    return cfg;
+  });
+
+/** Lets EAS Build manage credentials (provisioning profile) of the extension. */
+const withQPushEasCredentials = (config, props) => {
+  const bundleId = requireBundleId(config);
+  const extra = config.extra || {};
+  const eas = extra.eas || {};
+  const build = eas.build || {};
+  const experimental = build.experimental || {};
+  const ios = experimental.ios || {};
+  const appExtensions = Array.isArray(ios.appExtensions) ? ios.appExtensions : [];
+  if (!appExtensions.some((extension) => extension.targetName === NSE_TARGET_NAME)) {
+    appExtensions.push({
+      targetName: NSE_TARGET_NAME,
+      bundleIdentifier: `${bundleId}.${NSE_TARGET_NAME}`,
+      entitlements: {
+        'com.apple.security.application-groups': [appGroupName(config, props)],
+      },
+    });
+  }
+  config.extra = {
+    ...extra,
+    eas: {
+      ...eas,
+      build: {
+        ...build,
+        experimental: {
+          ...experimental,
+          ios: { ...ios, appExtensions },
+        },
+      },
+    },
+  };
+  return config;
+};
+
+// -----------------------------------------------------------------------------
+// Android (optional)
+// -----------------------------------------------------------------------------
+
+const withQPushAndroidIcon = (config, props) => {
+  if (!props.smallIcon) return config;
+  return withDangerousMod(config, [
+    'android',
+    async (cfg) => {
+      const source = path.resolve(cfg.modRequest.projectRoot, props.smallIcon);
+      if (!fs.existsSync(source)) {
+        throw new Error(`react-native-qpush: smallIcon not found: ${source}`);
+      }
+      const extension = path.extname(source).toLowerCase() || '.png';
+      const drawableDir = path.join(cfg.modRequest.platformProjectRoot, 'app', 'src', 'main', 'res', 'drawable');
+      fs.mkdirSync(drawableDir, { recursive: true });
+      fs.copyFileSync(source, path.join(drawableDir, `${ANDROID_ICON_NAME}${extension}`));
+      return cfg;
+    },
+  ]);
+};
+
+const withQPushAndroidAccentColor = (config, props) => {
+  if (!props.accentColor) return config;
+  return withAndroidManifest(config, (cfg) => {
+    const application = AndroidConfig.Manifest.getMainApplicationOrThrow(cfg.modResults);
+    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
+      application,
+      ANDROID_ACCENT_META,
+      String(props.accentColor).replace(/^#/, ''),
+    );
+    return cfg;
+  });
+};
+
+// -----------------------------------------------------------------------------
+
+/**
+ * @param {object} config Expo config
+ * @param {{
+ *   mode?: 'development' | 'production',
+ *   devTeam?: string,
+ *   iPhoneDeploymentTarget?: string,
+ *   disableNSE?: boolean,
+ *   nseFilePath?: string,
+ *   appGroup?: string,
+ *   suppressLaunchUrls?: boolean,
+ *   smallIcon?: string,
+ *   accentColor?: string,
+ * }} rawProps
+ */
+const withQPush = (config, rawProps) => {
+  const props = validateProps(rawProps);
+  config = withQPushEntitlements(config, props);
+  config = withQPushInfoPlist(config, props);
+  if (!props.disableNSE) {
+    config = withQPushNseFiles(config, props);
+    config = withQPushXcodeProject(config, props);
+    config = withQPushEasCredentials(config, props);
+  }
+  config = withQPushAndroidIcon(config, props);
+  config = withQPushAndroidAccentColor(config, props);
+  return config;
+};
+
+module.exports = createRunOncePlugin(withQPush, pkg.name, pkg.version);
+module.exports.withQPush = withQPush;
+module.exports.NSE_TARGET_NAME = NSE_TARGET_NAME;

package/react-native-qpush.podspec

@@ -0,0 +1,30 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "react-native-qpush"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "13.0" }
+  s.source       = { :git => package["repository"]["url"], :tag => "v#{s.version}" }
+
+  # The Notification Service Extension helper lives in its own pod
+  # (ios/Extension/QPushPushExtension.podspec) because extensions cannot link React Native.
+  s.source_files  = "ios/*.{h,m,mm,swift}"
+  s.public_header_files = "ios/QPushPushBridge.h"
+  s.swift_version = "5.0"
+  s.frameworks    = "UserNotifications", "UIKit"
+
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+  }
+
+  # Classic bridge module: works on the old architecture and, through React
+  # Native's interop layer, on the New Architecture / bridgeless mode.
+  s.dependency "React-Core"
+end

package/react-native.config.js

@@ -0,0 +1,18 @@
+/**
+ * React Native CLI autolinking config.
+ * The NSE helper pod (QPushPushExtension) is not autolinked: it belongs to the
+ * extension target (added by the Expo plugin or manually, see README).
+ */
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        packageImportPath: 'import com.qpush.reactnative.QPushPushPackage;',
+        packageInstance: 'new QPushPushPackage()',
+      },
+      ios: {
+        podspecPath: require('path').join(__dirname, 'react-native-qpush.podspec'),
+      },
+    },
+  },
+};

package/src/NativeQPushPush.ts

@@ -0,0 +1,57 @@
+/**
+ * TurboModule spec of the native module `QPushPush`.
+ *
+ * The native implementations are classic bridge modules
+ * (`ReactContextBaseJavaModule` / `RCTEventEmitter`). They work on the old
+ * architecture and, through React Native's interop layer, on the New
+ * Architecture / bridgeless mode. This spec documents the contract and gives
+ * typed access through `TurboModuleRegistry` (which falls back to
+ * `NativeModules` on the old architecture). Codegen is intentionally not
+ * configured in package.json, so no generated code is required at build time.
+ */
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // Key/value storage (SharedPreferences / UserDefaults). `app_id`,
+  // `server_url` and `subscription_id` are also read by native code and, on
+  // iOS, mirrored into the App Group `group.{bundle_id}.qpush`.
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+
+  /** DeviceInfo (see src/core/subscription.ts). */
+  getDeviceInfo(): Promise<Object>;
+
+  /**
+   * Android: FCM params from android_params.js (or null for the default
+   * FirebaseApp). iOS: ignored. Resolves `{ token, notificationTypes?, error? }`.
+   */
+  registerForPush(fcmParams: Object | null): Promise<Object>;
+
+  /** 'notDetermined' | 'denied' | 'granted' | 'provisional' | 'ephemeral' */
+  getPermissionStatus(): Promise<string>;
+  requestPermission(fallbackToSettings: boolean): Promise<boolean>;
+  registerForProvisionalAuthorization(): Promise<boolean>;
+  canRequestPermission(): Promise<boolean>;
+
+  clearAll(): void;
+  removeNotification(notificationId: string): void;
+  removeGroupedNotifications(groupKey: string): void;
+  clearBadge(): Promise<number>;
+
+  setJsReady(): void;
+  displayForegroundNotification(displayId: string): void;
+  preventForegroundDisplay(displayId: string): void;
+  setAutoOpenUrls(enabled: boolean): void;
+  setLogLevel(level: number): void;
+
+  beginBackgroundTask(): Promise<number>;
+  endBackgroundTask(taskId: number): void;
+
+  // NativeEventEmitter plumbing.
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('QPushPush');