react-native-qpush 0.0.0-stage → 1.0.0

package/src/core/subscription.ts

@@ -0,0 +1,133 @@
+import type { PermissionStatus, SubscriptionPayload } from '../types';
+import { NotificationTypes, SDK_VERSION } from './constants';
+
+/** Mutable subscription fields that the SDK keeps in sync with the server. */
+export interface SubscriptionFields {
+  token?: string;
+  enabled: boolean;
+  notification_types: number;
+  device_model?: string;
+  device_os?: string;
+  sdk: string;
+  app_version?: string;
+  test_type?: number | null;
+  carrier?: string;
+  rooted?: boolean;
+  net_type?: number;
+}
+
+export type SubscriptionPatch = Partial<SubscriptionFields> & { badge_count?: number };
+
+/** Device information reported by the native module. */
+export interface DeviceInfo {
+  platform: 'ios' | 'android';
+  deviceModel?: string;
+  deviceOs?: string;
+  appVersion?: string;
+  /** IANA timezone id. */
+  timezone?: string;
+  /** BCP-47 locale tag (e.g. `pt-BR`). */
+  locale?: string;
+  /** ISO 639-1 language (e.g. `pt`). */
+  language?: string;
+  /** ISO 3166-1 alpha-2 country from the locale. */
+  country?: string;
+  carrier?: string;
+  rooted?: boolean;
+  netType?: number;
+  /** iOS only: 1 development, 2 ad-hoc, null App Store/TestFlight. */
+  testType?: number | null;
+}
+
+export interface SubscriptionInputs {
+  token?: string | null;
+  /** Negative `notification_types` reported by the native registration. */
+  tokenError?: number | null;
+  permission: PermissionStatus;
+  /** Developer intent (`optIn()` / `optOut()`), default `true`. */
+  optedIn: boolean;
+}
+
+export function isPermissionGranted(permission: PermissionStatus): boolean {
+  return permission === 'granted' || permission === 'provisional' || permission === 'ephemeral';
+}
+
+/**
+ * Computes `notification_types`:
+ * token errors (-3/-10) > opted out / denied (-2) > not asked (0) > subscribed (1).
+ */
+export function computeNotificationTypes(input: SubscriptionInputs): number {
+  if (typeof input.tokenError === 'number' && input.tokenError < 0) return input.tokenError;
+  if (!input.optedIn) return NotificationTypes.unsubscribed;
+  if (input.permission === 'denied') return NotificationTypes.unsubscribed;
+  if (input.permission === 'notDetermined') return NotificationTypes.notAsked;
+  if (!input.token) return NotificationTypes.notAsked;
+  return NotificationTypes.subscribed;
+}
+
+/** `enabled` is false when opted out or when the OS permission is not granted. */
+export function computeEnabled(input: SubscriptionInputs): boolean {
+  return input.optedIn && isPermissionGranted(input.permission);
+}
+
+/** What `pushSubscription.getOptedInAsync()` reports. */
+export function computeOptedIn(input: SubscriptionInputs): boolean {
+  return input.optedIn && isPermissionGranted(input.permission) && !!input.token && !input.tokenError;
+}
+
+/** Builds the full subscription field set from local state and device info. */
+export function buildSubscriptionFields(input: SubscriptionInputs, device: DeviceInfo | null): SubscriptionFields {
+  const fields: SubscriptionFields = {
+    enabled: computeEnabled(input),
+    notification_types: computeNotificationTypes(input),
+    sdk: SDK_VERSION,
+  };
+  if (input.token) fields.token = input.token;
+  if (device) {
+    if (device.deviceModel) fields.device_model = device.deviceModel;
+    if (device.deviceOs) fields.device_os = device.deviceOs;
+    if (device.appVersion) fields.app_version = device.appVersion;
+    if (device.carrier) fields.carrier = device.carrier;
+    if (typeof device.rooted === 'boolean') fields.rooted = device.rooted;
+    if (typeof device.netType === 'number') fields.net_type = device.netType;
+    if (device.platform === 'ios') fields.test_type = device.testType ?? null;
+  }
+  return fields;
+}
+
+export function subscriptionType(platform: 'ios' | 'android'): SubscriptionPayload['type'] {
+  return platform === 'ios' ? 'iOSPush' : 'AndroidPush';
+}
+
+/** Full payload for `POST /users` / `POST .../subscriptions`. */
+export function toSubscriptionPayload(
+  platform: 'ios' | 'android',
+  fields: SubscriptionFields,
+  id?: string,
+): SubscriptionPayload {
+  const payload: SubscriptionPayload = { type: subscriptionType(platform), ...fields };
+  if (id) payload.id = id;
+  return payload;
+}
+
+/**
+ * Returns the fields of `current` that differ from what the server last
+ * acknowledged (`synced`). `net_type` alone never triggers a PATCH, it is only
+ * sent along with other changes (it flips constantly).
+ */
+export function diffSubscription(
+  synced: Partial<SubscriptionFields> | undefined,
+  current: SubscriptionFields,
+): Partial<SubscriptionFields> {
+  const previous = synced ?? {};
+  const patch: Record<string, unknown> = {};
+  const keys = Object.keys(current) as (keyof SubscriptionFields)[];
+  for (const key of keys) {
+    const value = current[key];
+    if (value === undefined) continue;
+    if (previous[key] !== value) patch[key] = value;
+  }
+  const changedKeys = Object.keys(patch);
+  if (changedKeys.length === 1 && changedKeys[0] === 'net_type') return {};
+  return patch as Partial<SubscriptionFields>;
+}

package/src/core/tags.ts

@@ -0,0 +1,116 @@
+/**
+ * Tag helpers. Tags are always strings on the wire; an empty string value in
+ * a PATCH removes the tag (protocol: "Tags are merged; an empty-string value
+ * removes the tag").
+ */
+
+export type TagMap = Record<string, string>;
+/** Changes to send: `value` sets, `''` removes. */
+export type TagChanges = Record<string, string>;
+
+/**
+ * Converts a developer supplied tag value to the wire string.
+ * Returns `undefined` for unsupported values (objects, arrays, functions).
+ * `null`/`undefined` map to `''` (removal).
+ */
+export function normalizeTagValue(value: unknown): string | undefined {
+  if (value === null || value === undefined) return '';
+  switch (typeof value) {
+    case 'string':
+      return value;
+    case 'number':
+      return Number.isFinite(value) ? String(value) : undefined;
+    case 'boolean':
+    case 'bigint':
+      return String(value);
+    default:
+      return undefined;
+  }
+}
+
+/** Returns `true` when the key can be used as a tag key. */
+export function isValidTagKey(key: unknown): key is string {
+  return typeof key === 'string' && key.trim().length > 0;
+}
+
+/**
+ * Normalizes a tag object, dropping invalid keys and values.
+ * The second element lists the keys that were rejected.
+ */
+export function normalizeTags(input: Record<string, unknown>): [TagChanges, string[]] {
+  const result: TagChanges = {};
+  const rejected: string[] = [];
+  if (!input || typeof input !== 'object') return [result, rejected];
+  for (const key of Object.keys(input)) {
+    const value = normalizeTagValue(input[key]);
+    if (!isValidTagKey(key) || value === undefined) {
+      rejected.push(key);
+      continue;
+    }
+    result[key] = value;
+  }
+  return [result, rejected];
+}
+
+/**
+ * Computes the changes that turn `previous` into `next`.
+ * Changed / added keys map to their new value, removed keys map to `''`.
+ */
+export function diffTags(previous: TagMap, next: TagMap): TagChanges {
+  const changes: TagChanges = {};
+  for (const key of Object.keys(next)) {
+    const value = next[key]!;
+    if (value === '') {
+      if (key in previous) changes[key] = '';
+    } else if (previous[key] !== value) {
+      changes[key] = value;
+    }
+  }
+  for (const key of Object.keys(previous)) {
+    if (!(key in next)) changes[key] = '';
+  }
+  return changes;
+}
+
+/** Applies changes to a tag map (returns a new object). */
+export function applyTagChanges(base: TagMap, changes: TagChanges): TagMap {
+  const result: TagMap = { ...base };
+  for (const key of Object.keys(changes)) {
+    const value = changes[key]!;
+    if (value === '') delete result[key];
+    else result[key] = value;
+  }
+  return result;
+}
+
+/** Merges two change sets; the later one wins per key. */
+export function mergeTagChanges(first: TagChanges, second: TagChanges): TagChanges {
+  return { ...first, ...second };
+}
+
+/**
+ * Computes what must be sent for an `addTags` call given the local cache:
+ * only values that differ from the cache are sent. Empty values are removals
+ * and are always sent (the local cache may not know every server tag).
+ */
+export function changesForAdd(current: TagMap, additions: TagChanges): TagChanges {
+  const changes: TagChanges = {};
+  for (const key of Object.keys(additions)) {
+    const value = additions[key]!;
+    if (value === '' || current[key] !== value) changes[key] = value;
+  }
+  return changes;
+}
+
+/** Computes the removal change set for `removeTags` (always sent). */
+export function changesForRemove(keys: readonly string[]): TagChanges {
+  const changes: TagChanges = {};
+  for (const key of keys) {
+    if (isValidTagKey(key)) changes[key] = '';
+  }
+  return changes;
+}
+
+export function isEmpty(changes: Record<string, unknown> | undefined | null): boolean {
+  return !changes || Object.keys(changes).length === 0;
+}

package/src/core/url.ts

@@ -0,0 +1,58 @@
+/**
+ * URL helpers. React Native's `URL` polyfill is incomplete (several getters
+ * throw "not implemented"), so everything here is plain string handling.
+ */
+
+const API_SUFFIX = '/api/v1';
+
+/**
+ * Normalizes the server URL given to `QPush.initialize`:
+ *  - trims whitespace, drops query string / fragment and trailing slashes
+ *  - prepends `https://` when no scheme is given
+ *  - appends `/api/v1` when the path does not already end with it
+ *
+ * Returns `null` when the value cannot be used.
+ */
+export function normalizeServerUrl(input: string | null | undefined): string | null {
+  if (typeof input !== 'string') return null;
+  let url = input.trim();
+  if (url.length === 0) return null;
+
+  // Strip fragment and query string.
+  const hashIndex = url.indexOf('#');
+  if (hashIndex >= 0) url = url.slice(0, hashIndex);
+  const queryIndex = url.indexOf('?');
+  if (queryIndex >= 0) url = url.slice(0, queryIndex);
+
+  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(url)) {
+    if (url.startsWith('//')) url = url.slice(2);
+    url = `https://${url}`;
+  }
+
+  const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^/]*)(\/.*)?$/.exec(url);
+  if (!match) return null;
+  const scheme = match[1]!.toLowerCase();
+  const host = match[2]!;
+  if (scheme !== 'http' && scheme !== 'https') return null;
+  if (host.length === 0 || /\s/.test(host)) return null;
+
+  let path = (match[3] ?? '').replace(/\/+$/, '');
+  // Collapse duplicated slashes inside the path.
+  path = path.replace(/\/{2,}/g, '/');
+  if (!path.toLowerCase().endsWith(API_SUFFIX)) {
+    path = `${path}${API_SUFFIX}`;
+  }
+  return `${scheme}://${host}${path}`;
+}
+
+/** Joins the API base URL with an absolute API path (`/apps/...`). */
+export function joinUrl(base: string, path: string): string {
+  const trimmedBase = base.replace(/\/+$/, '');
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${trimmedBase}${normalizedPath}`;
+}
+
+/** Encodes a single path segment (alias ids, labels, ids). */
+export function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment);
+}

package/src/core/uuid.ts

@@ -0,0 +1,13 @@
+/** RFC 4122 v4 UUID (used for local ids only, not security sensitive). */
+export function generateUuid(random: () => number = Math.random): string {
+  const hex: string[] = [];
+  for (let i = 0; i < 16; i++) {
+    let byte = Math.floor(random() * 256) & 0xff;
+    if (i === 6) byte = (byte & 0x0f) | 0x40;
+    if (i === 8) byte = (byte & 0x3f) | 0x80;
+    hex.push(byte.toString(16).padStart(2, '0'));
+  }
+  return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex.slice(6, 8).join('')}-${hex
+    .slice(8, 10)
+    .join('')}-${hex.slice(10, 16).join('')}`;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { QPush, QPush as default } from './QPush';
+export type {
+  QPushType,
+  NotificationEventName,
+  NotificationEventTypeMap,
+  PushSubscriptionEventTypeMap,
+  UserEventTypeMap,
+} from './QPush';
+export { QPushNotification, NotificationWillDisplayEvent } from './notification';
+export type { NotificationClickEvent } from './notification';
+export { LogLevel, NotificationPermission, QPUSH_CLOUD_API_URL } from './types';
+export type {
+  ActionButton,
+  QPushInitOptions,
+  QPushNotificationData,
+  NotificationClickResult,
+  PermissionStatus,
+  PushSubscriptionChangedState,
+  PushSubscriptionState,
+  UserChangedState,
+  UserState,
+} from './types';
+export { SDK_VERSION } from './core/constants';

package/src/notification.ts

@@ -0,0 +1,113 @@
+import type { ActionButton, QPushNotificationData, NotificationClickResult } from './types';
+
+/**
+ * A received notification. Same idea as OneSignal's `OSNotification`:
+ * read-only content plus `display()` for foreground notifications whose
+ * default display was prevented.
+ */
+export class QPushNotification implements QPushNotificationData {
+  readonly notificationId!: string;
+  readonly title?: string;
+  readonly subtitle?: string;
+  readonly body?: string;
+  readonly launchURL?: string;
+  readonly additionalData?: Record<string, unknown>;
+  readonly bigPicture?: string;
+  readonly largeIcon?: string;
+  readonly smallIcon?: string;
+  readonly accentColor?: string;
+  readonly sound?: string;
+  readonly channelId?: string;
+  readonly priority?: number;
+  readonly groupKey?: string;
+  readonly collapseId?: string;
+  readonly visibility?: number;
+  readonly badge?: number;
+  readonly category?: string;
+  readonly interruptionLevel?: string;
+  readonly relevanceScore?: number;
+  readonly contentAvailable?: boolean;
+  readonly actionButtons?: ActionButton[];
+  readonly rawPayload!: Record<string, unknown>;
+
+  private readonly displayHandler?: () => void;
+
+  constructor(data: QPushNotificationData, displayHandler?: () => void) {
+    Object.assign(this, data);
+    Object.defineProperty(this, 'displayHandler', { value: displayHandler, enumerable: false });
+  }
+
+  /**
+   * Displays the notification. Only meaningful inside a
+   * `foregroundWillDisplay` listener after `event.preventDefault()`; a no-op
+   * otherwise.
+   */
+  display(): void {
+    this.displayHandler?.();
+  }
+
+  /** Plain object copy (safe to serialize / store in React state). */
+  toJSON(): QPushNotificationData {
+    const copy: Record<string, unknown> = {};
+    for (const key of Object.keys(this)) {
+      copy[key] = (this as unknown as Record<string, unknown>)[key];
+    }
+    return copy as unknown as QPushNotificationData;
+  }
+}
+
+/** Payload of the `click` event (mirrors OneSignal's `NotificationClickEvent`). */
+export interface NotificationClickEvent {
+  result: NotificationClickResult;
+  notification: QPushNotification;
+}
+
+type DisplayState = 'pending' | 'prevented' | 'displayed';
+
+/**
+ * Payload of the `foregroundWillDisplay` event. Call `preventDefault()`
+ * synchronously inside the listener to stop the notification from being
+ * shown; call `getNotification().display()` later to show it anyway.
+ */
+export class NotificationWillDisplayEvent {
+  private state: DisplayState = 'pending';
+  private readonly notification: QPushNotification;
+
+  constructor(
+    data: QPushNotificationData,
+    private readonly onDisplay: () => void,
+  ) {
+    this.notification = new QPushNotification(data, () => this.display());
+  }
+
+  /** Prevents the default display. Must be called synchronously in the listener. */
+  preventDefault(): void {
+    if (this.state === 'pending') this.state = 'prevented';
+  }
+
+  getNotification(): QPushNotification {
+    return this.notification;
+  }
+
+  /** @internal */
+  get isPrevented(): boolean {
+    return this.state === 'prevented';
+  }
+
+  /** @internal */
+  get isDisplayed(): boolean {
+    return this.state === 'displayed';
+  }
+
+  private display(): void {
+    if (this.state === 'displayed') return;
+    this.state = 'displayed';
+    this.onDisplay();
+  }
+
+  /** @internal Called after all listeners ran: displays unless prevented. */
+  settle(): 'displayed' | 'prevented' {
+    if (this.state === 'pending') this.display();
+    return this.state === 'displayed' ? 'displayed' : 'prevented';
+  }
+}

package/src/reactNativePlatform.ts

@@ -0,0 +1,172 @@
+import { AppState, NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import NativeQPushPush, { type Spec } from './NativeQPushPush';
+import type {
+  FetchLike,
+  NativeBridge,
+  NativeEventSource,
+  NativePushRegistration,
+  PlatformAdapter,
+} from './core/platform';
+import { defaultScheduler } from './core/platform';
+import { MemoryStore } from './core/storage';
+import type { DeviceInfo } from './core/subscription';
+import type { FcmParams, PermissionStatus } from './types';
+
+const LINKING_ERROR =
+  "react-native-qpush: the native module 'QPushPush' is not available. " +
+  'Make sure you rebuilt the app after installing the package (pod install on iOS) ' +
+  'and that you are not running in Expo Go (use a development build).';
+
+const PERMISSIONS: PermissionStatus[] = ['notDetermined', 'denied', 'granted', 'provisional', 'ephemeral'];
+
+function resolveNativeModule(): Spec | null {
+  let module: Spec | null = null;
+  try {
+    module = NativeQPushPush ?? null;
+  } catch {
+    module = null;
+  }
+  if (!module) module = (NativeModules.QPushPush as Spec | undefined) ?? null;
+  return module;
+}
+
+/** In-memory stand-in so JS keeps working (and logs) when the module is missing. */
+function createFallbackBridge(os: 'ios' | 'android'): NativeBridge {
+  const store = new MemoryStore();
+  let warned = false;
+  const warn = () => {
+    if (!warned) {
+      warned = true;
+      console.error(`[QPush] ${LINKING_ERROR}`);
+    }
+  };
+  return {
+    getItem: (key) => store.getItem(key),
+    setItem: (key, value) => store.setItem(key, value),
+    removeItem: (key) => store.removeItem(key),
+    getDeviceInfo: async () => ({ platform: os }),
+    registerForPush: async () => {
+      warn();
+      return { token: null, error: 'native_module_missing' };
+    },
+    getPermissionStatus: async () => 'notDetermined',
+    requestPermission: async () => {
+      warn();
+      return false;
+    },
+    registerForProvisionalAuthorization: async () => false,
+    canRequestPermission: async () => false,
+    clearAll: warn,
+    removeNotification: warn,
+    removeGroupedNotifications: warn,
+    clearBadge: async () => 0,
+    setJsReady: () => {},
+    displayForegroundNotification: () => {},
+    preventForegroundDisplay: () => {},
+    setAutoOpenUrls: () => {},
+    setLogLevel: () => {},
+    beginBackgroundTask: async () => -1,
+    endBackgroundTask: () => {},
+  };
+}
+
+function toDeviceInfo(raw: unknown, os: 'ios' | 'android'): DeviceInfo {
+  const value = (raw ?? {}) as Record<string, unknown>;
+  const str = (key: string) => (typeof value[key] === 'string' && value[key] !== '' ? (value[key] as string) : undefined);
+  const info: DeviceInfo = { platform: os };
+  info.deviceModel = str('deviceModel');
+  info.deviceOs = str('deviceOs');
+  info.appVersion = str('appVersion');
+  info.timezone = str('timezone');
+  info.locale = str('locale');
+  info.language = str('language');
+  info.country = str('country');
+  info.carrier = str('carrier');
+  if (typeof value.rooted === 'boolean') info.rooted = value.rooted;
+  if (typeof value.netType === 'number' && value.netType >= 0) info.netType = value.netType;
+  if (os === 'ios') info.testType = typeof value.testType === 'number' ? value.testType : null;
+  return info;
+}
+
+function toRegistration(raw: unknown): NativePushRegistration {
+  const value = (raw ?? {}) as Record<string, unknown>;
+  const result: NativePushRegistration = {
+    token: typeof value.token === 'string' && value.token !== '' ? value.token : null,
+  };
+  if (typeof value.notificationTypes === 'number') result.notificationTypes = value.notificationTypes;
+  if (typeof value.error === 'string') result.error = value.error;
+  return result;
+}
+
+function wrapNative(module: Spec, os: 'ios' | 'android'): NativeBridge {
+  return {
+    getItem: (key) => module.getItem(key),
+    setItem: (key, value) => module.setItem(key, value),
+    removeItem: (key) => module.removeItem(key),
+    getDeviceInfo: async () => toDeviceInfo(await module.getDeviceInfo(), os),
+    registerForPush: async (fcm: FcmParams | null) =>
+      toRegistration(await module.registerForPush(fcm ? { ...fcm } : null)),
+    getPermissionStatus: async () => {
+      const status = await module.getPermissionStatus();
+      return PERMISSIONS.includes(status as PermissionStatus) ? (status as PermissionStatus) : 'notDetermined';
+    },
+    requestPermission: (fallback) => module.requestPermission(fallback),
+    registerForProvisionalAuthorization: () => module.registerForProvisionalAuthorization(),
+    canRequestPermission: () => module.canRequestPermission(),
+    clearAll: () => module.clearAll(),
+    removeNotification: (id) => module.removeNotification(id),
+    removeGroupedNotifications: (group) => module.removeGroupedNotifications(group),
+    clearBadge: async () => {
+      const previous = await module.clearBadge();
+      return typeof previous === 'number' ? previous : 0;
+    },
+    setJsReady: () => module.setJsReady(),
+    displayForegroundNotification: (id) => module.displayForegroundNotification(id),
+    preventForegroundDisplay: (id) => module.preventForegroundDisplay(id),
+    setAutoOpenUrls: (enabled) => module.setAutoOpenUrls(enabled),
+    setLogLevel: (level) => module.setLogLevel(level),
+    beginBackgroundTask: async () => {
+      const id = await module.beginBackgroundTask();
+      return typeof id === 'number' ? id : -1;
+    },
+    endBackgroundTask: (id) => module.endBackgroundTask(id),
+  };
+}
+
+/** Builds the platform adapter for a real React Native app. */
+export function createReactNativePlatform(): PlatformAdapter {
+  const os: 'ios' | 'android' = Platform.OS === 'ios' ? 'ios' : 'android';
+  const module = resolveNativeModule();
+  const native = module ? wrapNative(module, os) : createFallbackBridge(os);
+
+  let nativeEvents: NativeEventSource;
+  if (module) {
+    // iOS requires the module instance; on Android it lets the emitter call
+    // addListener/removeListeners on the module.
+    const emitter = new NativeEventEmitter(module as unknown as ConstructorParameters<typeof NativeEventEmitter>[0]);
+    nativeEvents = {
+      addListener: (eventName, listener) => emitter.addListener(eventName, listener),
+    };
+  } else {
+    nativeEvents = { addListener: () => ({ remove: () => {} }) };
+  }
+
+  const fetchImpl: FetchLike = (url, init) =>
+    fetch(url, init as RequestInit) as unknown as ReturnType<FetchLike>;
+
+  return {
+    os,
+    native,
+    nativeEvents,
+    appState: {
+      get currentState() {
+        return AppState.currentState;
+      },
+      addEventListener: (type, listener) => AppState.addEventListener(type, listener),
+    },
+    fetch: fetchImpl,
+    scheduler: defaultScheduler,
+    now: () => Date.now(),
+    random: () => Math.random(),
+  };
+}