appsonair-react-native-apppush 0.0.1-alpha

package/lib/commonjs/index.js

@@ -0,0 +1,686 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  initialize: true,
+  isInitialized: true,
+  getDeviceId: true,
+  getSubscriptionId: true,
+  getExternalId: true,
+  login: true,
+  logout: true,
+  setUserId: true,
+  getToken: true,
+  getDeviceToken: true,
+  requestPermission: true,
+  getPermission: true,
+  getPermissionStatus: true,
+  canRequestPermission: true,
+  registerForProvisionalAuthorization: true,
+  notifications: true,
+  badge: true,
+  user: true,
+  consent: true,
+  debug: true,
+  onNotificationReceived: true,
+  onNotificationOpened: true,
+  onNotificationWillDisplay: true,
+  onPermissionChanged: true,
+  onSubscriptionChanged: true,
+  onUserStateChanged: true,
+  onTokenUpdated: true,
+  onError: true,
+  onSilentNotification: true,
+  onInstallationIdUpdated: true
+};
+exports.badge = void 0;
+exports.canRequestPermission = canRequestPermission;
+exports.default = exports.debug = exports.consent = void 0;
+exports.getDeviceId = getDeviceId;
+exports.getDeviceToken = void 0;
+exports.getExternalId = getExternalId;
+exports.getPermission = getPermission;
+exports.getPermissionStatus = getPermissionStatus;
+exports.getSubscriptionId = getSubscriptionId;
+exports.getToken = getToken;
+exports.initialize = initialize;
+exports.isInitialized = isInitialized;
+exports.login = login;
+exports.logout = logout;
+exports.notifications = void 0;
+exports.onError = onError;
+exports.onInstallationIdUpdated = onInstallationIdUpdated;
+exports.onNotificationOpened = onNotificationOpened;
+exports.onNotificationReceived = onNotificationReceived;
+exports.onNotificationWillDisplay = onNotificationWillDisplay;
+exports.onPermissionChanged = onPermissionChanged;
+exports.onSilentNotification = onSilentNotification;
+exports.onSubscriptionChanged = onSubscriptionChanged;
+exports.onTokenUpdated = onTokenUpdated;
+exports.onUserStateChanged = onUserStateChanged;
+exports.registerForProvisionalAuthorization = registerForProvisionalAuthorization;
+exports.requestPermission = requestPermission;
+exports.user = exports.setUserId = void 0;
+var _reactNative = require("react-native");
+var _types = require("./types.js");
+Object.keys(_types).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _types[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _types[key];
+    }
+  });
+});
+const LINKING_ERROR = `The package 'appsonair-react-native-apppush' doesn't seem to be linked. Make sure: \n\n` + _reactNative.Platform.select({
+  ios: "- You have run 'pod install'\n",
+  default: ''
+}) + '- You rebuilt the app after installing the package\n' + '- You are not using Expo Go\n';
+
+/**
+ * Resolves the native module on both architectures.
+ *
+ * `TurboModuleRegistry.get` returns the TurboModule when the New Architecture is
+ * on and falls back to the legacy `NativeModules` entry when it is off, so one
+ * lookup covers both. The `NativeModules` read is the belt-and-braces path for
+ * hosts where the registry is unavailable; the Proxy then turns a missing module
+ * into an actionable message instead of `undefined is not an object`.
+ */
+const NativePush = _reactNative.TurboModuleRegistry.get('AppsonairReactNativeApppush') ?? _reactNative.NativeModules.AppsonairReactNativeApppush ?? new Proxy({}, {
+  get() {
+    throw new Error(LINKING_ERROR);
+  }
+});
+const emitter = new _reactNative.NativeEventEmitter(
+// The legacy bridge needs the module instance to route `addListener`;
+// the New Architecture ignores this argument entirely.
+_reactNative.NativeModules.AppsonairReactNativeApppush ?? undefined);
+
+// MARK: - Event names
+// Kept in one place because the native bridges hardcode these same strings — a
+// rename has to happen in four files at once: here,
+// AppsonairReactNativeApppushModuleImpl.kt, AppsonairReactNativeApppushImpl.swift and
+// the supportedEvents list in AppsonairReactNativeApppush.mm.
+
+const EVENT = {
+  notificationReceived: 'AppsonairPush:onNotificationReceived',
+  notificationOpened: 'AppsonairPush:onNotificationOpened',
+  notificationWillDisplay: 'AppsonairPush:onNotificationWillDisplay',
+  permissionChanged: 'AppsonairPush:onPermissionChanged',
+  subscriptionChanged: 'AppsonairPush:onSubscriptionChanged',
+  userStateChanged: 'AppsonairPush:onUserStateChanged',
+  tokenUpdated: 'AppsonairPush:onTokenUpdated',
+  silentNotification: 'AppsonairPush:onSilentNotification',
+  installationIdUpdated: 'AppsonairPush:onInstallationIdUpdated',
+  error: 'AppsonairPush:onError'
+};
+
+// MARK: - Initialization guard
+//
+// Parity I1: calling before `initialize()` emits a catchable error on iOS but
+// throws `IllegalStateException` on Android — a hard crash. The wrapper tracks
+// initialisation itself so the same misuse produces the same rejected promise
+// on both platforms and the Android `check()` never reaches the app.
+
+let initialized = false;
+class PushNotInitializedError extends Error {
+  code = 'notInitialized';
+  constructor(method) {
+    super(`AppPushService.${method}() was called before initialize(). ` + 'Await initialize() once at app start before using the SDK.');
+    this.name = 'PushNotInitializedError';
+  }
+}
+class PushArgumentError extends Error {
+  code = 'invalidArgument';
+  constructor(message) {
+    super(message);
+    this.name = 'PushArgumentError';
+  }
+}
+function guard(method, call) {
+  if (!initialized) {
+    return Promise.reject(new PushNotInitializedError(method));
+  }
+  return call();
+}
+
+/**
+ * Parity I2: `login("")` logs and returns on iOS but throws
+ * `IllegalArgumentException` on Android. Validated here so neither happens.
+ */
+function requireNonEmpty(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new PushArgumentError(`${label} must be a non-empty string.`);
+  }
+}
+
+// MARK: - Lifecycle
+
+/**
+ * Starts the SDK. Await this once, before any other call.
+ *
+ * On Android the wrapper supplies the `Context` itself; on iOS it resolves the
+ * App Group and enables AppDelegate swizzling. Neither detail is exposed here.
+ */
+async function initialize(config = {}) {
+  await NativePush.initialize({
+    debug: config.debug ?? false
+  });
+  initialized = true;
+}
+
+/** Whether {@link initialize} has completed in this JS context. */
+function isInitialized() {
+  return initialized;
+}
+
+// MARK: - Identity
+
+/** The AppsOnAir-assigned device id. */
+function getDeviceId() {
+  return guard('getDeviceId', () => NativePush.getDeviceId());
+}
+
+/** The backend-assigned subscription id. `null` until the device registers. */
+function getSubscriptionId() {
+  return guard('getSubscriptionId', () => NativePush.getSubscriptionId());
+}
+
+/** The external id linked via {@link login}. `null` while anonymous. */
+function getExternalId() {
+  return guard('getExternalId', () => NativePush.getExternalId());
+}
+
+/** Associates this device with your own user id. */
+function login(externalId) {
+  requireNonEmpty(externalId, 'externalId');
+  return guard('login', () => NativePush.login(externalId));
+}
+
+/** Unlinks the external id, returning the device to an anonymous subscription. */
+function logout() {
+  return guard('logout', () => NativePush.logout());
+}
+
+/** Alias of {@link login}, for teams that prefer the noun. */
+const setUserId = exports.setUserId = login;
+
+// MARK: - Token
+
+/** APNs hex token on iOS, FCM token on Android. `null` before registration. */
+function getToken() {
+  return guard('getToken', () => NativePush.getToken());
+}
+
+/** Alias of {@link getToken}. */
+const getDeviceToken = exports.getDeviceToken = getToken;
+
+// MARK: - Permissions
+
+/**
+ * Prompts for notification permission and resolves the resulting grant state.
+ *
+ * Parity E1: Android needs a live Activity. The bridge resolves the current one
+ * and rejects if none is attached rather than crashing.
+ */
+function requestPermission(options = {}) {
+  return guard('requestPermission', () => NativePush.requestPermission(options.fallbackToSettings ?? false));
+}
+
+/**
+ * Whether notifications are currently permitted.
+ *
+ * Parity E3/E4/E6: iOS reads a cache and Android reads live, so the iOS bridge
+ * refreshes first. The two native shapes (`async` vs sync, `permission` vs
+ * `isPermissionGranted`) are collapsed into this one promise.
+ */
+function getPermission() {
+  return guard('getPermission', () => NativePush.getPermission());
+}
+
+/**
+ * The granular permission state.
+ *
+ * Parity C7: iOS reports all five values. **Android reports only `authorized`
+ * or `denied`** — it never returns `notDetermined`, so do not gate a
+ * cross-platform pre-prompt on that value.
+ */
+function getPermissionStatus() {
+  return guard('getPermissionStatus', () => NativePush.getPermissionStatus());
+}
+
+/**
+ * Whether a permission prompt can still be shown.
+ *
+ * Parity E2 — **known divergence, not yet fixed in the native SDKs.** iOS
+ * returns `true` only before the user has ever been asked. Android returns
+ * `true` whenever permission is not granted, *including after a permanent
+ * denial*. Treat a `true` on Android as "not granted", not as "never asked".
+ */
+function canRequestPermission() {
+  return guard('canRequestPermission', () => NativePush.canRequestPermission());
+}
+
+/** Quiet iOS 12+ provisional authorization. **iOS only** — a no-op on Android. */
+function registerForProvisionalAuthorization() {
+  return guard('registerForProvisionalAuthorization', () => NativePush.registerForProvisionalAuthorization());
+}
+
+// MARK: - Notifications namespace
+
+const notifications = exports.notifications = {
+  /** Dismisses every notification this app has posted. */
+  clearAll() {
+    return guard('notifications.clearAll', () => NativePush.clearAllNotifications());
+  },
+  /**
+   * Dismisses one notification by its payload `notification_id`.
+   *
+   * Parity F2: on Android the id is hashed to find the posted notification, so
+   * two ids that hash alike could collide. iOS matches the request identifier
+   * exactly.
+   */
+  remove(notificationId) {
+    requireNonEmpty(notificationId, 'notificationId');
+    return guard('notifications.remove', () => NativePush.removeNotification(notificationId));
+  },
+  /** Dismisses several notifications. Android loops; iOS removes them in one call. */
+  removeMany(notificationIds) {
+    if (!Array.isArray(notificationIds)) {
+      throw new PushArgumentError('notificationIds must be an array of strings.');
+    }
+    return guard('notifications.removeMany', () => NativePush.removeNotifications(notificationIds));
+  },
+  /** Dismisses a notification group. **Android only** — a no-op on iOS. */
+  removeGroup(groupKey) {
+    requireNonEmpty(groupKey, 'groupKey');
+    return guard('notifications.removeGroup', () => NativePush.removeNotificationGroup(groupKey));
+  }
+};
+
+// MARK: - Badges
+
+const badge = exports.badge = {
+  /**
+   * The SDK's badge count.
+   *
+   * Parity G1/G3: iOS reads the OS badge. Android has no OS read API, so this
+   * returns the SDK's own persisted value, which can drift from what the
+   * launcher actually shows.
+   */
+  get() {
+    return guard('badge.get', () => NativePush.getBadgeCount());
+  },
+  /**
+   * Sets the badge count.
+   *
+   * Parity G3: reliable on iOS. On Android this is a best-effort launcher
+   * broadcast that silently does nothing outside Samsung / MIUI / ASUS — which
+   * is why nothing here reports success.
+   */
+  set(count) {
+    if (!Number.isFinite(count) || count < 0) {
+      throw new PushArgumentError('badge count must be a non-negative number.');
+    }
+    return guard('badge.set', () => NativePush.setBadgeCount(count));
+  },
+  /** Adds `delta` to the badge and resolves the new value, clamped at 0. */
+  increment(delta = 1) {
+    if (!Number.isFinite(delta)) {
+      throw new PushArgumentError('badge delta must be a number.');
+    }
+    return guard('badge.increment', () => NativePush.incrementBadgeCount(delta));
+  },
+  /** Clears the badge. */
+  clear() {
+    return guard('badge.clear', () => NativePush.clearBadgeCount());
+  },
+  /** Clears the badge whenever the app foregrounds. **iOS only.** */
+  setAutoClearOnForeground(enabled) {
+    return guard('badge.setAutoClearOnForeground', () => NativePush.setAutoClearBadgeOnForeground(enabled));
+  }
+};
+
+// MARK: - User namespace
+
+const user = exports.user = {
+  /** The AppsOnAir device id. */
+  getAppsOnAirId() {
+    return guard('user.getAppsOnAirId', () => NativePush.getDeviceId());
+  },
+  getExternalId,
+  addTag(key, value) {
+    requireNonEmpty(key, 'tag key');
+    return guard('user.addTag', () => NativePush.addTag(key, value));
+  },
+  addTags(tags) {
+    return guard('user.addTags', () => NativePush.addTags(tags));
+  },
+  removeTag(key) {
+    requireNonEmpty(key, 'tag key');
+    return guard('user.removeTag', () => NativePush.removeTag(key));
+  },
+  removeTags(keys) {
+    return guard('user.removeTags', () => NativePush.removeTags(keys));
+  },
+  /**
+   * The user's tags.
+   *
+   * **Android round-trips to the backend** once the device has a
+   * `subscriptionId`, replacing its local cache with the result; before
+   * registration it resolves the local cache without a network call. **iOS reads
+   * its local cache only.** So a tag set on another device shows up on Android
+   * and not on iOS, and the Android call can reject on a network failure where
+   * iOS cannot.
+   */
+  getTags() {
+    return guard('user.getTags', () => NativePush.getTags());
+  },
+  addAlias(label, id) {
+    requireNonEmpty(label, 'alias label');
+    requireNonEmpty(id, 'alias id');
+    return guard('user.addAlias', () => NativePush.addAlias(label, id));
+  },
+  addAliases(aliases) {
+    return guard('user.addAliases', () => NativePush.addAliases(aliases));
+  },
+  removeAlias(label) {
+    requireNonEmpty(label, 'alias label');
+    return guard('user.removeAlias', () => NativePush.removeAlias(label));
+  },
+  removeAliases(labels) {
+    return guard('user.removeAliases', () => NativePush.removeAliases(labels));
+  },
+  /**
+   * Adds an email identifier.
+   *
+   * Parity A5 — **known Android bug.** Android persists emails but never reads
+   * them back on restart, so an email added here silently vanishes when the app
+   * relaunches. The wrapper cannot work around it; it needs an SDK fix.
+   */
+  addEmail(address) {
+    requireNonEmpty(address, 'email address');
+    return guard('user.addEmail', () => NativePush.addEmail(address));
+  },
+  removeEmail(address) {
+    requireNonEmpty(address, 'email address');
+    return guard('user.removeEmail', () => NativePush.removeEmail(address));
+  },
+  setLanguage(languageCode) {
+    requireNonEmpty(languageCode, 'languageCode');
+    return guard('user.setLanguage', () => NativePush.setLanguage(languageCode));
+  },
+  /**
+   * The device language.
+   *
+   * Parity 1.5 — Android reads this live; iOS snapshots it once at init and
+   * never refreshes, so a mid-session language change is stale on iOS.
+   */
+  getLanguage() {
+    return guard('user.getLanguage', () => NativePush.getLanguage());
+  },
+  /** The current push subscription: `{ id, token, optedIn }`. */
+  getPushSubscription() {
+    return guard('user.getPushSubscription', () => NativePush.getPushSubscription());
+  },
+  /** Opts this device back in to push delivery. */
+  optIn() {
+    return guard('user.optIn', () => NativePush.optIn());
+  },
+  /** Opts this device out of push delivery without unregistering the token. */
+  optOut() {
+    return guard('user.optOut', () => NativePush.optOut());
+  },
+  /**
+   * The subscription's enabled state as the backend sees it.
+   *
+   * Distinct from `getPushSubscription().optedIn`, which is the purely local
+   * `!optedOut` flag on both platforms. The two derive it differently and
+   * converge only in steady state:
+   *
+   * - **Android** reads it back from `/subscriptions`, so it reflects what the
+   *   server actually stored. Before the device registers it falls back to the
+   *   local value without a network call.
+   * - **iOS** computes the same flag it would send: an APNs token exists, the
+   *   user has not opted out, *and* the OS currently grants permission. So
+   *   revoking permission in Settings flips this to `false` on iOS while
+   *   Android keeps reporting the server's stored value.
+   */
+  getOptedIn() {
+    return guard('user.getOptedIn', () => NativePush.getOptedIn());
+  }
+};
+
+// MARK: - Consent
+//
+// Parity I5: both SDKs store these flags but neither enforces them. They are
+// exposed because they round-trip, but they are not a compliance control yet —
+// setting `consentGiven` to false does not currently gate anything.
+
+const consent = exports.consent = {
+  setRequired(required) {
+    return guard('consent.setRequired', () => NativePush.setConsentRequired(required));
+  },
+  getRequired() {
+    return guard('consent.getRequired', () => NativePush.getConsentRequired());
+  },
+  setGiven(given) {
+    return guard('consent.setGiven', () => NativePush.setConsentGiven(given));
+  },
+  getGiven() {
+    return guard('consent.getGiven', () => NativePush.getConsentGiven());
+  }
+};
+
+// MARK: - Debug
+
+const debug = exports.debug = {
+  /** Sets SDK log verbosity. Safe to call before {@link initialize}. */
+  setLogLevel(level) {
+    return NativePush.setLogLevel(level);
+  }
+};
+
+// MARK: - Events
+
+function subscribe(eventName, callback) {
+  const sub = emitter.addListener(eventName, callback);
+  return {
+    remove: () => sub.remove()
+  };
+}
+
+/** Fires when a notification arrives while the app is in the foreground. */
+function onNotificationReceived(callback) {
+  return subscribe(EVENT.notificationReceived, callback);
+}
+
+/** Fires when the user taps a notification or one of its action buttons. */
+function onNotificationOpened(callback) {
+  return subscribe(EVENT.notificationOpened, callback);
+}
+
+/**
+ * Fires in the foreground *before* the notification is displayed, giving you a
+ * chance to suppress it.
+ *
+ * `preventDefault()` must be called synchronously inside the handler — the
+ * native side is holding the notification until this returns, and releases it
+ * anyway after a short timeout so a throwing handler cannot wedge delivery.
+ *
+ * All registered handlers run; the notification is suppressed if *any* of them
+ * calls `preventDefault()`.
+ *
+ * **`preventDefault()` is honoured on Android only.** iOS decides presentation
+ * synchronously and cannot wait for a JS answer — see
+ * {@link NotificationWillDisplayEvent.preventDefault}. The event itself fires on
+ * both platforms.
+ */
+function onNotificationWillDisplay(callback) {
+  willDisplayHandlers.add(callback);
+  ensureWillDisplayBridge();
+  return {
+    remove: () => {
+      willDisplayHandlers.delete(callback);
+      if (willDisplayHandlers.size === 0) {
+        willDisplayBridge?.remove();
+        willDisplayBridge = null;
+      }
+    }
+  };
+}
+const willDisplayHandlers = new Set();
+let willDisplayBridge = null;
+
+/**
+ * One emitter subscription fans out to every handler, so
+ * `completeNotificationWillDisplay` is called exactly once per notification no
+ * matter how many handlers are registered. Completing twice would release the
+ * same held notification twice on the native side.
+ */
+function ensureWillDisplayBridge() {
+  if (willDisplayBridge) return;
+  willDisplayBridge = emitter.addListener(EVENT.notificationWillDisplay, payload => {
+    let prevented = false;
+    const event = {
+      notification: payload.notification,
+      preventDefault: () => {
+        prevented = true;
+      }
+    };
+    for (const handler of willDisplayHandlers) {
+      try {
+        handler(event);
+      } catch (error) {
+        // A throwing handler must not stop the remaining handlers, and must
+        // not prevent the completion call below — otherwise the native side
+        // holds the notification until its timeout for no reason.
+        console.error('[AppPushService] onNotificationWillDisplay handler threw', error);
+      }
+    }
+    const id = payload.notification?.id;
+    if (id != null) {
+      NativePush.completeNotificationWillDisplay(id, !prevented).catch(() => {
+        // The native side falls back to displaying the notification when the
+        // completion never lands, so there is nothing to recover here.
+      });
+    }
+  });
+}
+
+/** Fires when the OS notification permission changes. */
+function onPermissionChanged(callback) {
+  return subscribe(EVENT.permissionChanged, callback);
+}
+
+/** Fires when the push subscription's token or opt-in state changes. */
+function onSubscriptionChanged(callback) {
+  return subscribe(EVENT.subscriptionChanged, callback);
+}
+
+/** Fires on {@link login} / {@link logout}. */
+function onUserStateChanged(callback) {
+  return subscribe(EVENT.userStateChanged, callback);
+}
+
+/**
+ * Fires when the device registration token is issued or refreshed.
+ *
+ * This is the push-side counterpart to {@link getToken}: the getter answers
+ * "what is the token now", this answers "the token just changed" — which is when
+ * your backend needs to hear about it. A token can rotate at any point in a
+ * session, so a one-shot `getToken()` at startup will eventually go stale.
+ *
+ * `environment` is the APNs endpoint the backend must send to. It is
+ * `'sandbox'` or `'production'` on iOS and always `null` on Android, where FCM
+ * routes for you.
+ *
+ * Events raised before the first subscriber exists are dropped rather than
+ * queued on both platforms, so read {@link getToken} once after subscribing if
+ * you need the current value too.
+ */
+function onTokenUpdated(callback) {
+  return subscribe(EVENT.tokenUpdated, callback);
+}
+
+/**
+ * Fires on an SDK-level failure — token registration, a denied permission, a
+ * missing Firebase config.
+ *
+ * These are conditions the SDK hits on its own schedule, outside any call you
+ * made, so they surface here rather than as a rejected promise. A promise
+ * rejection from a method you called carries the same `code` values.
+ *
+ * Without a subscriber these failures are silent, which is why this is worth
+ * wiring even if it only ever logs.
+ */
+function onError(callback) {
+  return subscribe(EVENT.error, callback);
+}
+
+/**
+ * Fires for a data-only push that is delivered without being displayed.
+ *
+ * Supported on both platforms, but they are triggered differently and your
+ * backend has to send for both: iOS uses the APNs `content-available` flag,
+ * while Android keys off a `silent: "true"` data entry, since FCM has no
+ * transport-level equivalent. See {@link SilentNotificationEvent}.
+ *
+ * iOS invokes the OS completion handler as soon as this event is emitted, so
+ * the handler cannot extend the app's background execution window: treat it as
+ * a notification that the payload arrived, not as a place to await work.
+ */
+function onSilentNotification(callback) {
+  return subscribe(EVENT.silentNotification, callback);
+}
+
+/**
+ * Fires when the Firebase Installation ID becomes available.
+ *
+ * **Android only** — the event name is registered on iOS so the two bridges
+ * stay diffable, but nothing ever emits it there.
+ */
+function onInstallationIdUpdated(callback) {
+  return subscribe(EVENT.installationIdUpdated, callback);
+}
+
+// MARK: - Default export
+
+const AppPushService = {
+  initialize,
+  isInitialized,
+  getDeviceId,
+  getSubscriptionId,
+  getExternalId,
+  login,
+  logout,
+  setUserId,
+  getToken,
+  getDeviceToken,
+  requestPermission,
+  getPermission,
+  getPermissionStatus,
+  canRequestPermission,
+  registerForProvisionalAuthorization,
+  notifications,
+  badge,
+  user,
+  consent,
+  debug,
+  onNotificationReceived,
+  onNotificationOpened,
+  onNotificationWillDisplay,
+  onPermissionChanged,
+  onSubscriptionChanged,
+  onUserStateChanged,
+  onTokenUpdated,
+  onError,
+  onSilentNotification,
+  onInstallationIdUpdated
+};
+var _default = exports.default = AppPushService;
+//# sourceMappingURL=index.js.map