react-native-qpush 0.0.0-stage → 1.0.0

package/src/QPush.ts

@@ -0,0 +1,292 @@
+import { QPushCore, type CoreEvents } from './core/QPushCore';
+import { Logger } from './core/logger';
+import type { PlatformAdapter } from './core/platform';
+import type { NotificationClickEvent, NotificationWillDisplayEvent } from './notification';
+import { createReactNativePlatform } from './reactNativePlatform';
+import type {
+  QPushInitOptions,
+  LogLevel,
+  NotificationPermission,
+  PushSubscriptionChangedState,
+  UserChangedState,
+} from './types';
+
+/** Events of `QPush.Notifications.addEventListener`. */
+export interface NotificationEventTypeMap {
+  click: NotificationClickEvent;
+  foregroundWillDisplay: NotificationWillDisplayEvent;
+  permissionChange: boolean;
+}
+
+export type NotificationEventName = keyof NotificationEventTypeMap;
+
+/** Events of `QPush.User.pushSubscription.addEventListener`. */
+export interface PushSubscriptionEventTypeMap {
+  change: PushSubscriptionChangedState;
+}
+
+/** Events of `QPush.User.addEventListener`. */
+export interface UserEventTypeMap {
+  change: UserChangedState;
+}
+
+let core: QPushCore | null = null;
+let platformFactory: () => PlatformAdapter = createReactNativePlatform;
+
+function getCore(): QPushCore {
+  if (!core) core = new QPushCore(platformFactory(), new Logger());
+  return core;
+}
+
+/** @internal Testing hook: replaces the platform used by the singleton. */
+export function __setPlatformFactoryForTests(factory: () => PlatformAdapter): QPushCore {
+  platformFactory = factory;
+  core = null;
+  return getCore();
+}
+
+const NOTIFICATION_EVENTS: Record<NotificationEventName, true> = {
+  click: true,
+  foregroundWillDisplay: true,
+  permissionChange: true,
+};
+
+const Debug = {
+  /** Sets the SDK log level (JS console and native logs). */
+  setLogLevel(level: LogLevel): void {
+    getCore().setLogLevel(level);
+  },
+};
+
+const Notifications = {
+  /**
+   * Shows the OS permission prompt (Android 13+ / iOS). With
+   * `fallbackToSettings`, opens the app notification settings when the
+   * prompt can no longer be shown (permission permanently denied).
+   */
+  requestPermission(fallbackToSettings: boolean = false): Promise<boolean> {
+    return getCore().requestPermission(fallbackToSettings);
+  },
+
+  /** `true` when the app can currently display notifications. */
+  getPermissionAsync(): Promise<boolean> {
+    return getCore().getPermission();
+  },
+
+  /** Detailed native permission state. */
+  permissionNative(): Promise<NotificationPermission> {
+    return getCore().permissionNative();
+  },
+
+  /** `true` when calling `requestPermission` would show the OS prompt. */
+  canRequestPermission(): Promise<boolean> {
+    return getCore().canRequestPermission();
+  },
+
+  /** iOS 12+: quiet "provisional" authorization without a prompt. Android: same as getPermissionAsync. */
+  registerForProvisionalAuthorization(): Promise<boolean> {
+    return getCore().registerForProvisionalAuthorization();
+  },
+
+  addEventListener<K extends NotificationEventName>(
+    event: K,
+    listener: (event: NotificationEventTypeMap[K]) => void,
+  ): void {
+    if (!NOTIFICATION_EVENTS[event]) throw new Error(`Unknown QPush notification event "${String(event)}"`);
+    getCore().addListener(event, listener as unknown as (payload: CoreEvents[K]) => void);
+  },
+
+  removeEventListener<K extends NotificationEventName>(
+    event: K,
+    listener: (event: NotificationEventTypeMap[K]) => void,
+  ): void {
+    if (!NOTIFICATION_EVENTS[event]) return;
+    getCore().removeListener(event, listener as unknown as (payload: CoreEvents[K]) => void);
+  },
+
+  /** Removes every QPush notification from the notification center and clears the badge. */
+  clearAll(): void {
+    getCore().clearAll();
+  },
+
+  /** Removes a single notification by its QPush notification id. */
+  removeNotification(notificationId: string): void {
+    getCore().removeNotification(notificationId);
+  },
+
+  /** Removes the notifications of a group (Android group / iOS thread-id). */
+  removeGroupedNotifications(groupKey: string): void {
+    getCore().removeGroupedNotifications(groupKey);
+  },
+
+  /**
+   * Enables / disables opening the notification URL on tap (default enabled).
+   * Persisted natively, so it also applies to cold-start taps on next launches.
+   * Build-time switch: Android manifest meta-data `com.qpush.suppressLaunchURLs`
+   * / iOS Info.plist `QPush_suppress_launch_urls`.
+   */
+  setAutoOpenUrls(enabled: boolean): void {
+    getCore().setAutoOpenUrls(enabled);
+  },
+};
+
+const pushSubscription = {
+  /** Subscription id of this device, `null` until the server created it. */
+  getIdAsync(): Promise<string | null> {
+    return getCore().getSubscriptionId();
+  },
+
+  /** FCM token (Android) / hex APNs token (iOS). */
+  getTokenAsync(): Promise<string | null> {
+    return getCore().getSubscriptionToken();
+  },
+
+  /** `true` when the device can receive pushes (permission + token + not opted out). */
+  getOptedInAsync(): Promise<boolean> {
+    return getCore().getOptedIn();
+  },
+
+  /** Re-enables pushes; prompts for permission when it was never asked. */
+  optIn(): void {
+    getCore().optIn();
+  },
+
+  /** Disables pushes for this device without touching the OS permission. */
+  optOut(): void {
+    getCore().optOut();
+  },
+
+  addEventListener<K extends keyof PushSubscriptionEventTypeMap>(
+    _event: K,
+    listener: (event: PushSubscriptionEventTypeMap[K]) => void,
+  ): void {
+    getCore().addListener('pushSubscriptionChange', listener);
+  },
+
+  removeEventListener<K extends keyof PushSubscriptionEventTypeMap>(
+    _event: K,
+    listener: (event: PushSubscriptionEventTypeMap[K]) => void,
+  ): void {
+    getCore().removeListener('pushSubscriptionChange', listener);
+  },
+};
+
+const User = {
+  pushSubscription,
+
+  /** Adds or updates a tag. Values are stored as strings. */
+  addTag(key: string, value: string | number | boolean): void {
+    getCore().addTags({ [key]: value });
+  },
+
+  addTags(tags: Record<string, string | number | boolean>): void {
+    getCore().addTags(tags);
+  },
+
+  removeTag(key: string): void {
+    getCore().removeTags([key]);
+  },
+
+  removeTags(keys: string[]): void {
+    getCore().removeTags(keys);
+  },
+
+  /** Local copy of the user's tags (refreshed from the server on app start and login). */
+  getTags(): Promise<Record<string, string>> {
+    return getCore().getTags();
+  },
+
+  /** Adds a custom alias (e.g. `crm_id`). Use `QPush.login` for `external_id`. */
+  addAlias(label: string, id: string): void {
+    getCore().addAliases({ [label]: id });
+  },
+
+  addAliases(aliases: Record<string, string>): void {
+    getCore().addAliases(aliases);
+  },
+
+  removeAlias(label: string): void {
+    getCore().removeAliases([label]);
+  },
+
+  removeAliases(labels: string[]): void {
+    getCore().removeAliases(labels);
+  },
+
+  /** ISO 639-1 language code, e.g. `pt`. Defaults to the device language. */
+  setLanguage(language: string): void {
+    getCore().setLanguage(language);
+  },
+
+  /** QPush user id (`qpush_id`), `null` until the server created the user. */
+  getQPushId(): Promise<string | null> {
+    return getCore().getQPushId();
+  },
+
+  /** Alias of `getQPushId` for code migrated from OneSignal. */
+  getOnesignalId(): Promise<string | null> {
+    return getCore().getQPushId();
+  },
+
+  getExternalId(): Promise<string | null> {
+    return getCore().getExternalId();
+  },
+
+  addEventListener<K extends keyof UserEventTypeMap>(
+    _event: K,
+    listener: (event: UserEventTypeMap[K]) => void,
+  ): void {
+    getCore().addListener('userChange', listener);
+  },
+
+  removeEventListener<K extends keyof UserEventTypeMap>(
+    _event: K,
+    listener: (event: UserEventTypeMap[K]) => void,
+  ): void {
+    getCore().removeListener('userChange', listener);
+  },
+};
+
+/**
+ * QPush SDK entry point.
+ *
+ * ```ts
+ * QPush.initialize('APP_ID'); // qpush cloud: https://qpush.dev/api/v1
+ * await QPush.Notifications.requestPermission(true);
+ * QPush.login('user-123');
+ * ```
+ */
+export const QPush = {
+  /**
+   * Initializes the SDK. Call once, as early as possible (e.g. in index.js or
+   * your root component). Safe to call API methods right after it.
+   */
+  initialize(appId: string, options?: QPushInitOptions): void {
+    getCore().initialize(appId, options);
+  },
+
+  /** Identifies the current user with your user id (`external_id`). */
+  login(externalId: string): void {
+    getCore().login(externalId);
+  },
+
+  /** Detaches the device from the identified user (a new anonymous user is created). */
+  logout(): void {
+    getCore().logout();
+  },
+
+  /** When `true`, nothing is sent until `setConsentGiven(true)`. Call before `initialize`. */
+  setConsentRequired(required: boolean): void {
+    getCore().setConsentRequired(required);
+  },
+
+  setConsentGiven(given: boolean): void {
+    getCore().setConsentGiven(given);
+  },
+
+  Debug,
+  Notifications,
+  User,
+};
+
+export type QPushType = typeof QPush;