react-native-qpush 0.0.0-stage → 1.0.0

package/src/core/operations.ts

@@ -0,0 +1,166 @@
+import { mergeTagChanges, type TagChanges } from './tags';
+
+/**
+ * Operations are persisted in the queue as plain JSON. Every user-scoped
+ * operation references the user by a *local id* generated on the device; the
+ * real `qpush_id` is resolved when the operation executes (the user may not
+ * exist on the server yet when the operation is enqueued). This keeps changes
+ * made before `login()`/`logout()` attached to the right user.
+ */
+
+/** `POST /apps/{app_id}/users` (cold start for a new device, and `logout()`). */
+export interface CreateUserOperation {
+  kind: 'createUser';
+  userLocalId: string;
+  identity: Record<string, string>;
+  /** Include the current subscription id so the server moves it (logout). */
+  transferSubscription: boolean;
+}
+
+/** `login(externalId)`: identify the anonymous user or switch users. */
+export interface LoginOperation {
+  kind: 'login';
+  userLocalId: string;
+  externalId: string;
+  previousLocalId: string;
+  previousWasAnonymous: boolean;
+}
+
+/** `PATCH /apps/{app_id}/users/by/qpush_id/{id}` */
+export interface UpdateUserOperation {
+  kind: 'updateUser';
+  userLocalId: string;
+  tags?: TagChanges;
+  properties?: {
+    language?: string;
+    timezone_id?: string;
+    country?: string;
+  };
+  deltas?: {
+    session_count?: number;
+    session_time?: number;
+  };
+}
+
+/** `PATCH .../identity` */
+export interface SetAliasOperation {
+  kind: 'setAlias';
+  userLocalId: string;
+  aliases: Record<string, string>;
+}
+
+/** `DELETE .../identity/{label}` */
+export interface RemoveAliasOperation {
+  kind: 'removeAlias';
+  userLocalId: string;
+  label: string;
+}
+
+/** `GET /apps/{app_id}/users/by/qpush_id/{id}` to refresh the local cache. */
+export interface FetchUserOperation {
+  kind: 'fetchUser';
+  userLocalId: string;
+}
+
+/**
+ * State based: computes the diff between the local subscription and what the
+ * server acknowledged at execution time, then `PATCH /subscriptions/{id}`.
+ */
+export interface SyncSubscriptionOperation {
+  kind: 'syncSubscription';
+}
+
+/** `POST .../users/by/qpush_id/{id}/subscriptions` (subscription lost server side). */
+export interface CreateSubscriptionOperation {
+  kind: 'createSubscription';
+  userLocalId: string;
+}
+
+export type Operation =
+  | CreateUserOperation
+  | LoginOperation
+  | UpdateUserOperation
+  | SetAliasOperation
+  | RemoveAliasOperation
+  | FetchUserOperation
+  | SyncSubscriptionOperation
+  | CreateSubscriptionOperation;
+
+export type OperationKind = Operation['kind'];
+
+function sumDelta(a: number | undefined, b: number | undefined): number | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return a + b;
+}
+
+function stripEmpty<T extends Record<string, unknown>>(value: T | undefined): T | undefined {
+  if (!value) return undefined;
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(value)) {
+    if (value[key] !== undefined) result[key] = value[key];
+  }
+  return Object.keys(result).length > 0 ? (result as T) : undefined;
+}
+
+/**
+ * Tries to merge `next` into `previous` (the tail of the queue). Returns the
+ * merged operation, or `null` when they cannot be merged.
+ */
+export function mergeOperations(previous: Operation, next: Operation): Operation | null {
+  if (previous.kind === 'updateUser' && next.kind === 'updateUser') {
+    if (previous.userLocalId !== next.userLocalId) return null;
+    const tags =
+      previous.tags || next.tags ? mergeTagChanges(previous.tags ?? {}, next.tags ?? {}) : undefined;
+    const properties = stripEmpty({ ...(previous.properties ?? {}), ...(next.properties ?? {}) });
+    const deltas = stripEmpty({
+      session_count: sumDelta(previous.deltas?.session_count, next.deltas?.session_count),
+      session_time: sumDelta(previous.deltas?.session_time, next.deltas?.session_time),
+    });
+    const merged: UpdateUserOperation = { kind: 'updateUser', userLocalId: next.userLocalId };
+    if (tags && Object.keys(tags).length > 0) merged.tags = tags;
+    if (properties) merged.properties = properties;
+    if (deltas) merged.deltas = deltas;
+    return merged;
+  }
+  if (previous.kind === 'setAlias' && next.kind === 'setAlias') {
+    if (previous.userLocalId !== next.userLocalId) return null;
+    return { kind: 'setAlias', userLocalId: next.userLocalId, aliases: { ...previous.aliases, ...next.aliases } };
+  }
+  if (previous.kind === 'syncSubscription' && next.kind === 'syncSubscription') {
+    return previous;
+  }
+  if (previous.kind === 'fetchUser' && next.kind === 'fetchUser' && previous.userLocalId === next.userLocalId) {
+    return previous;
+  }
+  return null;
+}
+
+/** Operations that (re)create the device subscription on the server. */
+export function createsSubscription(operation: Operation): boolean {
+  return operation.kind === 'createUser' || operation.kind === 'login' || operation.kind === 'createSubscription';
+}
+
+/** Returns the local user id an operation is scoped to, if any. */
+export function operationUserLocalId(operation: Operation): string | undefined {
+  return 'userLocalId' in operation ? operation.userLocalId : undefined;
+}
+
+export function isValidOperation(value: unknown): value is Operation {
+  if (typeof value !== 'object' || value === null) return false;
+  const kind = (value as { kind?: unknown }).kind;
+  switch (kind) {
+    case 'createUser':
+    case 'login':
+    case 'updateUser':
+    case 'setAlias':
+    case 'removeAlias':
+    case 'fetchUser':
+    case 'createSubscription':
+      return typeof (value as { userLocalId?: unknown }).userLocalId === 'string';
+    case 'syncSubscription':
+      return true;
+    default:
+      return false;
+  }
+}

package/src/core/payload.ts

@@ -0,0 +1,175 @@
+import type { ActionButton, QPushNotificationData } from '../types';
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown): string | undefined {
+  if (typeof value === 'string') return value.length > 0 ? value : undefined;
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function tryParseJson(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return undefined;
+  }
+}
+
+/** `data` is normally an object but tolerate a JSON string. */
+function asDataObject(value: unknown): Record<string, unknown> | undefined {
+  if (isObject(value)) return value;
+  if (typeof value === 'string') {
+    const parsed = tryParseJson(value);
+    if (isObject(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+export function parseButtons(value: unknown): ActionButton[] | undefined {
+  let list = value;
+  if (typeof list === 'string') list = tryParseJson(list);
+  if (!Array.isArray(list)) return undefined;
+  const buttons: ActionButton[] = [];
+  for (const entry of list) {
+    if (!isObject(entry)) continue;
+    const id = asString(entry.id);
+    const text = asString(entry.text);
+    if (!id || !text) continue;
+    const button: ActionButton = { id, text };
+    const icon = asString(entry.icon);
+    const url = asString(entry.url);
+    if (icon) button.icon = icon;
+    if (url) button.url = url;
+    buttons.push(button);
+  }
+  return buttons.length > 0 ? buttons : undefined;
+}
+
+function stripUndefined<T extends object>(value: T): T {
+  const result = { ...value } as Record<string, unknown>;
+  for (const key of Object.keys(result)) {
+    if (result[key] === undefined) delete result[key];
+  }
+  return result as T;
+}
+
+/**
+ * Parses the Android `data["qpush"]` JSON (already decoded) into the
+ * normalized notification shape.
+ */
+export function parseAndroidPayload(qpush: JsonObject, raw: JsonObject = qpush): QPushNotificationData | null {
+  const notificationId = asString(qpush.id);
+  if (!notificationId) return null;
+  return stripUndefined<QPushNotificationData>({
+    notificationId,
+    title: asString(qpush.title),
+    body: asString(qpush.body),
+    launchURL: asString(qpush.url),
+    additionalData: asDataObject(qpush.data),
+    bigPicture: asString(qpush.image),
+    largeIcon: asString(qpush.large_icon),
+    smallIcon: asString(qpush.small_icon),
+    accentColor: asString(qpush.accent_color),
+    sound: asString(qpush.sound),
+    channelId: asString(qpush.channel_id),
+    priority: asNumber(qpush.priority),
+    groupKey: asString(qpush.group),
+    collapseId: asString(qpush.collapse_id),
+    visibility: asNumber(qpush.visibility),
+    actionButtons: parseButtons(qpush.buttons),
+    rawPayload: raw,
+  });
+}
+
+/** Parses an iOS `userInfo` dictionary (`aps` + `qpush`). */
+export function parseIosPayload(userInfo: JsonObject): QPushNotificationData | null {
+  let qpush: unknown = userInfo.qpush;
+  if (typeof qpush === 'string') qpush = tryParseJson(qpush);
+  if (!isObject(qpush)) return null;
+  const notificationId = asString(qpush.id);
+  if (!notificationId) return null;
+
+  const aps = isObject(userInfo.aps) ? userInfo.aps : {};
+  let title: string | undefined;
+  let subtitle: string | undefined;
+  let body: string | undefined;
+  const alert = aps.alert;
+  if (typeof alert === 'string') {
+    body = asString(alert);
+  } else if (isObject(alert)) {
+    title = asString(alert.title);
+    subtitle = asString(alert.subtitle);
+    body = asString(alert.body);
+  }
+
+  let sound: string | undefined;
+  if (typeof aps.sound === 'string') sound = asString(aps.sound);
+  else if (isObject(aps.sound)) sound = asString(aps.sound.name);
+
+  const contentAvailable = asNumber(aps['content-available']);
+
+  return stripUndefined<QPushNotificationData>({
+    notificationId,
+    title,
+    subtitle,
+    body,
+    launchURL: asString(qpush.url),
+    additionalData: asDataObject(qpush.data),
+    bigPicture: asString(qpush.image),
+    sound,
+    badge: asNumber(aps.badge),
+    category: asString(aps.category),
+    groupKey: asString(aps['thread-id']),
+    interruptionLevel: asString(aps['interruption-level']),
+    relevanceScore: asNumber(aps['relevance-score']),
+    contentAvailable: contentAvailable === 1 ? true : undefined,
+    actionButtons: parseButtons(qpush.buttons),
+    rawPayload: userInfo,
+  });
+}
+
+/**
+ * Parses whatever the native layer forwarded:
+ *  - Android: the `data["qpush"]` JSON string, the decoded object, or the
+ *    whole FCM data map (`{ qpush: "<json>" }`)
+ *  - iOS: the notification `userInfo` (`{ aps, qpush }`)
+ *
+ * Returns `null` when the payload is not a QPush notification.
+ */
+export function parseNotificationPayload(raw: unknown): QPushNotificationData | null {
+  let value: unknown = raw;
+  if (typeof value === 'string') value = tryParseJson(value);
+  if (!isObject(value)) return null;
+
+  // iOS userInfo (always carries `aps`).
+  if (isObject(value.aps)) return parseIosPayload(value);
+
+  // A data map whose `qpush` entry was already decoded. The iOS `qpush`
+  // keys (id/url/data/image/buttons) are a subset of the Android ones.
+  if (isObject(value.qpush)) return parseAndroidPayload(value.qpush, value);
+
+  // Android FCM data map: { qpush: "<json string>" }
+  if (typeof value.qpush === 'string') {
+    const inner = tryParseJson(value.qpush);
+    if (!isObject(inner)) return null;
+    return parseAndroidPayload(inner, inner);
+  }
+
+  // Android `qpush` object itself.
+  if ('id' in value) return parseAndroidPayload(value);
+  return null;
+}

package/src/core/platform.ts

@@ -0,0 +1,84 @@
+import type { FcmParams, PermissionStatus } from '../types';
+import type { KeyValueStore } from './storage';
+import type { DeviceInfo } from './subscription';
+
+export interface Scheduler {
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export interface Subscription {
+  remove(): void;
+}
+
+export interface FetchResponseLike {
+  status: number;
+  headers: { get(name: string): string | null };
+  text(): Promise<string>;
+}
+
+export interface FetchInit {
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  signal?: unknown;
+}
+
+export type FetchLike = (url: string, init: FetchInit) => Promise<FetchResponseLike>;
+
+export interface AppStateLike {
+  readonly currentState: string | null | undefined;
+  addEventListener(type: 'change', listener: (state: string) => void): Subscription;
+}
+
+export interface NativeEventSource {
+  addListener(eventName: string, listener: (payload: any) => void): Subscription;
+}
+
+/** Result of `registerForPush`. */
+export interface NativePushRegistration {
+  token: string | null;
+  /** Negative `notification_types` value when registration failed. */
+  notificationTypes?: number;
+  error?: string;
+}
+
+/** Typed facade over the native module (see `NativeQPushPush.ts`). */
+export interface NativeBridge extends KeyValueStore {
+  getDeviceInfo(): Promise<DeviceInfo>;
+  registerForPush(fcmParams: FcmParams | null): Promise<NativePushRegistration>;
+  getPermissionStatus(): Promise<PermissionStatus>;
+  requestPermission(fallbackToSettings: boolean): Promise<boolean>;
+  registerForProvisionalAuthorization(): Promise<boolean>;
+  canRequestPermission(): Promise<boolean>;
+  clearAll(): void;
+  removeNotification(notificationId: string): void;
+  removeGroupedNotifications(groupKey: string): void;
+  /** Clears the app badge and returns the previous value (iOS; 0 on Android). */
+  clearBadge(): Promise<number>;
+  /** Tells native that JS subscribed to events: queued native events are flushed. */
+  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;
+}
+
+/** Everything the core needs from the host environment (injected for tests). */
+export interface PlatformAdapter {
+  os: 'ios' | 'android';
+  native: NativeBridge;
+  nativeEvents: NativeEventSource;
+  appState: AppStateLike;
+  fetch: FetchLike;
+  scheduler: Scheduler;
+  now(): number;
+  random(): number;
+}
+
+export const defaultScheduler: Scheduler = {
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};

package/src/core/state.ts

@@ -0,0 +1,127 @@
+import type { FcmParams, PermissionStatus } from '../types';
+import type { SubscriptionFields } from './subscription';
+
+/** Local model of the current user. */
+export interface PersistedUser {
+  /** Device-generated id; operations reference users by it. */
+  localId: string;
+  qpushId?: string;
+  externalId?: string;
+  /** Aliases except `qpush_id` / `onesignal_id` (includes `external_id`). */
+  aliases: Record<string, string>;
+  tags: Record<string, string>;
+  language?: string;
+  /** `true` once the developer called `setLanguage()`. */
+  languageExplicit?: boolean;
+  /** Last timezone sent to the server. */
+  timezone?: string;
+}
+
+/** Local model of this device's push subscription. */
+export interface PersistedSubscription {
+  id?: string;
+  token?: string;
+  /** Negative notification_types from a failed native registration. */
+  tokenError?: number;
+  /** Developer intent: `optIn()` / `optOut()`. */
+  optedIn: boolean;
+  permission: PermissionStatus;
+  /** Fields last acknowledged by the server. */
+  synced?: Partial<SubscriptionFields>;
+  /** Send `badge_count: 0` with the next subscription PATCH. */
+  badgeResetPending?: boolean;
+}
+
+export interface PersistedConfig {
+  appId: string;
+  serverUrl: string;
+}
+
+export interface PersistedState {
+  version: 1;
+  config?: PersistedConfig;
+  user: PersistedUser;
+  subscription: PersistedSubscription;
+  /** local user id -> qpush_id, for users referenced by pending operations. */
+  idMap: Record<string, string>;
+  consentRequired: boolean;
+  consentGiven: boolean;
+  /** Last FCM params from android_params.js (`null` = server has none). */
+  fcmParams?: FcmParams | null;
+}
+
+export function createUser(localId: string): PersistedUser {
+  return { localId, aliases: {}, tags: {} };
+}
+
+export function createDefaultState(localId: string): PersistedState {
+  return {
+    version: 1,
+    user: createUser(localId),
+    subscription: { optedIn: true, permission: 'notDetermined' },
+    idMap: {},
+    consentRequired: false,
+    consentGiven: false,
+  };
+}
+
+function isRecordOfStrings(value: unknown): value is Record<string, string> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  return Object.values(value as Record<string, unknown>).every((entry) => typeof entry === 'string');
+}
+
+const PERMISSIONS: PermissionStatus[] = ['notDetermined', 'denied', 'granted', 'provisional', 'ephemeral'];
+
+/** Validates persisted JSON, falling back to defaults for broken parts. */
+export function sanitizeState(raw: unknown, newLocalId: () => string): PersistedState {
+  const fallback = createDefaultState(newLocalId());
+  if (typeof raw !== 'object' || raw === null) return fallback;
+  const value = raw as Partial<PersistedState>;
+  if (value.version !== 1) return fallback;
+
+  const state: PersistedState = { ...fallback };
+  if (
+    value.config &&
+    typeof value.config.appId === 'string' &&
+    typeof value.config.serverUrl === 'string'
+  ) {
+    state.config = { appId: value.config.appId, serverUrl: value.config.serverUrl };
+  }
+
+  const user = value.user;
+  if (user && typeof user.localId === 'string') {
+    state.user = {
+      localId: user.localId,
+      qpushId: typeof user.qpushId === 'string' ? user.qpushId : undefined,
+      externalId: typeof user.externalId === 'string' ? user.externalId : undefined,
+      aliases: isRecordOfStrings(user.aliases) ? user.aliases : {},
+      tags: isRecordOfStrings(user.tags) ? user.tags : {},
+      language: typeof user.language === 'string' ? user.language : undefined,
+      languageExplicit: user.languageExplicit === true,
+      timezone: typeof user.timezone === 'string' ? user.timezone : undefined,
+    };
+  }
+
+  const subscription = value.subscription;
+  if (subscription && typeof subscription === 'object') {
+    state.subscription = {
+      id: typeof subscription.id === 'string' ? subscription.id : undefined,
+      token: typeof subscription.token === 'string' ? subscription.token : undefined,
+      tokenError: typeof subscription.tokenError === 'number' ? subscription.tokenError : undefined,
+      optedIn: subscription.optedIn !== false,
+      permission: PERMISSIONS.includes(subscription.permission as PermissionStatus)
+        ? (subscription.permission as PermissionStatus)
+        : 'notDetermined',
+      synced:
+        typeof subscription.synced === 'object' && subscription.synced !== null ? subscription.synced : undefined,
+      badgeResetPending: subscription.badgeResetPending === true,
+    };
+  }
+
+  state.idMap = isRecordOfStrings(value.idMap) ? value.idMap : {};
+  state.consentRequired = value.consentRequired === true;
+  state.consentGiven = value.consentGiven === true;
+  if (value.fcmParams === null) state.fcmParams = null;
+  else if (value.fcmParams && typeof value.fcmParams === 'object') state.fcmParams = value.fcmParams;
+  return state;
+}

package/src/core/storage.ts

@@ -0,0 +1,76 @@
+/**
+ * Minimal async key/value store. In the app it is backed by the native module
+ * (SharedPreferences on Android, UserDefaults on iOS) so native code can read
+ * the same values; tests use {@link MemoryStore}.
+ */
+export interface KeyValueStore {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+export class MemoryStore implements KeyValueStore {
+  readonly data = new Map<string, string>();
+
+  async getItem(key: string): Promise<string | null> {
+    return this.data.has(key) ? (this.data.get(key) as string) : null;
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    this.data.set(key, value);
+  }
+
+  async removeItem(key: string): Promise<void> {
+    this.data.delete(key);
+  }
+}
+
+/** Reads and parses a JSON value, returning `null` on any failure. */
+export async function readJson<T>(store: KeyValueStore, key: string): Promise<T | null> {
+  try {
+    const raw = await store.getItem(key);
+    if (raw == null || raw === '') return null;
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Serializes writes for one key: only the latest value matters, writes never
+ * overlap and a failed write does not break the chain.
+ */
+export class SerialWriter {
+  private chain: Promise<void> = Promise.resolve();
+  private latest: string | null = null;
+  private scheduled = false;
+
+  constructor(
+    private readonly store: KeyValueStore,
+    private readonly key: string,
+    private readonly onError: (error: unknown) => void = () => {},
+  ) {}
+
+  write(value: string): Promise<void> {
+    this.latest = value;
+    if (!this.scheduled) {
+      this.scheduled = true;
+      this.chain = this.chain
+        .then(async () => {
+          this.scheduled = false;
+          const toWrite = this.latest;
+          if (toWrite !== null) await this.store.setItem(this.key, toWrite);
+        })
+        .catch((error) => {
+          this.scheduled = false;
+          this.onError(error);
+        });
+    }
+    return this.chain;
+  }
+
+  /** Resolves when every pending write finished. */
+  flush(): Promise<void> {
+    return this.chain;
+  }
+}