react-native-qpush 0.0.0-stage → 1.0.0

package/lib/QPush.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QPush = void 0;
+exports.__setPlatformFactoryForTests = __setPlatformFactoryForTests;
+const QPushCore_1 = require("./core/QPushCore");
+const logger_1 = require("./core/logger");
+const reactNativePlatform_1 = require("./reactNativePlatform");
+let core = null;
+let platformFactory = reactNativePlatform_1.createReactNativePlatform;
+function getCore() {
+    if (!core)
+        core = new QPushCore_1.QPushCore(platformFactory(), new logger_1.Logger());
+    return core;
+}
+/** @internal Testing hook: replaces the platform used by the singleton. */
+function __setPlatformFactoryForTests(factory) {
+    platformFactory = factory;
+    core = null;
+    return getCore();
+}
+const NOTIFICATION_EVENTS = {
+    click: true,
+    foregroundWillDisplay: true,
+    permissionChange: true,
+};
+const Debug = {
+    /** Sets the SDK log level (JS console and native logs). */
+    setLogLevel(level) {
+        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 = false) {
+        return getCore().requestPermission(fallbackToSettings);
+    },
+    /** `true` when the app can currently display notifications. */
+    getPermissionAsync() {
+        return getCore().getPermission();
+    },
+    /** Detailed native permission state. */
+    permissionNative() {
+        return getCore().permissionNative();
+    },
+    /** `true` when calling `requestPermission` would show the OS prompt. */
+    canRequestPermission() {
+        return getCore().canRequestPermission();
+    },
+    /** iOS 12+: quiet "provisional" authorization without a prompt. Android: same as getPermissionAsync. */
+    registerForProvisionalAuthorization() {
+        return getCore().registerForProvisionalAuthorization();
+    },
+    addEventListener(event, listener) {
+        if (!NOTIFICATION_EVENTS[event])
+            throw new Error(`Unknown QPush notification event "${String(event)}"`);
+        getCore().addListener(event, listener);
+    },
+    removeEventListener(event, listener) {
+        if (!NOTIFICATION_EVENTS[event])
+            return;
+        getCore().removeListener(event, listener);
+    },
+    /** Removes every QPush notification from the notification center and clears the badge. */
+    clearAll() {
+        getCore().clearAll();
+    },
+    /** Removes a single notification by its QPush notification id. */
+    removeNotification(notificationId) {
+        getCore().removeNotification(notificationId);
+    },
+    /** Removes the notifications of a group (Android group / iOS thread-id). */
+    removeGroupedNotifications(groupKey) {
+        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) {
+        getCore().setAutoOpenUrls(enabled);
+    },
+};
+const pushSubscription = {
+    /** Subscription id of this device, `null` until the server created it. */
+    getIdAsync() {
+        return getCore().getSubscriptionId();
+    },
+    /** FCM token (Android) / hex APNs token (iOS). */
+    getTokenAsync() {
+        return getCore().getSubscriptionToken();
+    },
+    /** `true` when the device can receive pushes (permission + token + not opted out). */
+    getOptedInAsync() {
+        return getCore().getOptedIn();
+    },
+    /** Re-enables pushes; prompts for permission when it was never asked. */
+    optIn() {
+        getCore().optIn();
+    },
+    /** Disables pushes for this device without touching the OS permission. */
+    optOut() {
+        getCore().optOut();
+    },
+    addEventListener(_event, listener) {
+        getCore().addListener('pushSubscriptionChange', listener);
+    },
+    removeEventListener(_event, listener) {
+        getCore().removeListener('pushSubscriptionChange', listener);
+    },
+};
+const User = {
+    pushSubscription,
+    /** Adds or updates a tag. Values are stored as strings. */
+    addTag(key, value) {
+        getCore().addTags({ [key]: value });
+    },
+    addTags(tags) {
+        getCore().addTags(tags);
+    },
+    removeTag(key) {
+        getCore().removeTags([key]);
+    },
+    removeTags(keys) {
+        getCore().removeTags(keys);
+    },
+    /** Local copy of the user's tags (refreshed from the server on app start and login). */
+    getTags() {
+        return getCore().getTags();
+    },
+    /** Adds a custom alias (e.g. `crm_id`). Use `QPush.login` for `external_id`. */
+    addAlias(label, id) {
+        getCore().addAliases({ [label]: id });
+    },
+    addAliases(aliases) {
+        getCore().addAliases(aliases);
+    },
+    removeAlias(label) {
+        getCore().removeAliases([label]);
+    },
+    removeAliases(labels) {
+        getCore().removeAliases(labels);
+    },
+    /** ISO 639-1 language code, e.g. `pt`. Defaults to the device language. */
+    setLanguage(language) {
+        getCore().setLanguage(language);
+    },
+    /** QPush user id (`qpush_id`), `null` until the server created the user. */
+    getQPushId() {
+        return getCore().getQPushId();
+    },
+    /** Alias of `getQPushId` for code migrated from OneSignal. */
+    getOnesignalId() {
+        return getCore().getQPushId();
+    },
+    getExternalId() {
+        return getCore().getExternalId();
+    },
+    addEventListener(_event, listener) {
+        getCore().addListener('userChange', listener);
+    },
+    removeEventListener(_event, listener) {
+        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');
+ * ```
+ */
+exports.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, options) {
+        getCore().initialize(appId, options);
+    },
+    /** Identifies the current user with your user id (`external_id`). */
+    login(externalId) {
+        getCore().login(externalId);
+    },
+    /** Detaches the device from the identified user (a new anonymous user is created). */
+    logout() {
+        getCore().logout();
+    },
+    /** When `true`, nothing is sent until `setConsentGiven(true)`. Call before `initialize`. */
+    setConsentRequired(required) {
+        getCore().setConsentRequired(required);
+    },
+    setConsentGiven(given) {
+        getCore().setConsentGiven(given);
+    },
+    Debug,
+    Notifications,
+    User,
+};

package/lib/core/QPushCore.d.ts

@@ -0,0 +1,148 @@
+import { NotificationWillDisplayEvent, type NotificationClickEvent } from '../notification';
+import { LogLevel, NotificationPermission, type QPushInitOptions, type PermissionStatus, type PushSubscriptionChangedState, type UserChangedState } from '../types';
+import { EventHub } from './events';
+import { Logger } from './logger';
+import { OperationQueue } from './operationQueue';
+import type { PlatformAdapter } from './platform';
+export interface CoreEvents {
+    click: NotificationClickEvent;
+    foregroundWillDisplay: NotificationWillDisplayEvent;
+    permissionChange: boolean;
+    pushSubscriptionChange: PushSubscriptionChangedState;
+    userChange: UserChangedState;
+}
+/** Language code from a locale (`pt-BR` -> `pt`, `iw` -> `he`). */
+export declare function languageFromLocale(locale: string | undefined): string | undefined;
+/**
+ * The single implementation of the QPush user / subscription / HTTP state
+ * machine. Platform specifics are injected through {@link PlatformAdapter}.
+ */
+export declare class QPushCore {
+    private readonly platform;
+    readonly logger: Logger;
+    readonly events: EventHub<CoreEvents>;
+    readonly queue: OperationQueue;
+    private readonly http;
+    private readonly stateWriter;
+    private state;
+    private loadPromise;
+    private commandChain;
+    private device;
+    private initializeCalled;
+    private started;
+    private registrationSettled;
+    private registering;
+    private halted;
+    private foregroundAt;
+    private backgroundAt;
+    private pendingColdSession;
+    private appStateSubscription;
+    private nativeSubscriptions;
+    private pendingClicks;
+    private clickFlushScheduled;
+    constructor(platform: PlatformAdapter, logger?: Logger);
+    private uuid;
+    private ensureLoaded;
+    private load;
+    /** Enqueues `createUser` for the current user unless it exists or is being created. */
+    private ensureUserCreation;
+    /** Runs `fn` after state is loaded, serialized with every other command. */
+    private command;
+    /** Reads state after every previously issued command ran. */
+    private read;
+    private save;
+    private canProcess;
+    private hasConsent;
+    private sleep;
+    private get appId();
+    /** Waits for pending commands, queue processing and storage writes (tests). */
+    flush(): Promise<void>;
+    setLogLevel(level: LogLevel): void;
+    initialize(appId: string, options?: QPushInitOptions): void;
+    private resetForNewApp;
+    private writeNative;
+    setConsentRequired(required: boolean): void;
+    setConsentGiven(given: boolean): void;
+    private maybeStart;
+    private start;
+    /** Retries push registration when the app comes back without a token (offline start, FCM params added later). */
+    private retryRegistrationIfNeeded;
+    private fetchParams;
+    private registerPush;
+    private applyRegistration;
+    private applyToken;
+    /** Reads the OS permission and updates the subscription when it changed. */
+    refreshPermission(emit: boolean): Promise<PermissionStatus>;
+    requestPermission(fallbackToSettings: boolean): Promise<boolean>;
+    registerForProvisionalAuthorization(): Promise<boolean>;
+    getPermission(): Promise<boolean>;
+    permissionNative(): Promise<NotificationPermission>;
+    canRequestPermission(): Promise<boolean>;
+    private subscriptionInputs;
+    private currentFields;
+    private pushState;
+    /** Applies a subscription change, emits `change` and schedules a sync. */
+    private mutateSubscription;
+    private scheduleSyncIfDirty;
+    private setSubscriptionId;
+    optIn(): void;
+    optOut(): void;
+    getSubscriptionId(): Promise<string | null>;
+    getSubscriptionToken(): Promise<string | null>;
+    getOptedIn(): Promise<boolean>;
+    private userState;
+    private mutateUser;
+    login(externalId: string): void;
+    logout(): void;
+    addTags(tags: Record<string, unknown>): void;
+    removeTags(keys: string[]): void;
+    private applyLocalTagChanges;
+    getTags(): Promise<Record<string, string>>;
+    addAliases(aliases: Record<string, string>): void;
+    removeAliases(labels: string[]): void;
+    setLanguage(language: string): void;
+    getQPushId(): Promise<string | null>;
+    getExternalId(): Promise<string | null>;
+    private attachAppState;
+    private startSession;
+    private onAppStateChange;
+    private flushInBackground;
+    private clearBadge;
+    /** Subscribes to native events and tells native that JS is ready. Idempotent. */
+    attachNativeEvents(): void;
+    private handleNativeClick;
+    private emitClick;
+    private handleNativeForeground;
+    addListener<K extends keyof CoreEvents>(event: K, listener: (payload: CoreEvents[K]) => void): void;
+    removeListener<K extends keyof CoreEvents>(event: K, listener: (payload: CoreEvents[K]) => void): void;
+    clearAll(): void;
+    removeNotification(notificationId: string): void;
+    removeGroupedNotifications(groupKey: string): void;
+    setAutoOpenUrls(enabled: boolean): void;
+    private execute;
+    private userPath;
+    private userProperties;
+    /** Tag changes still waiting in the queue for a user (to re-apply over server data). */
+    private pendingTagChanges;
+    private pendingAliasChanges;
+    private mapUser;
+    /** Keeps only ids still referenced by the current user or pending operations. */
+    private pruneIdMap;
+    /** Picks this device's subscription in a user response. */
+    private findOwnSubscription;
+    /** Applies a `POST /users` response (createUser, login fallback). */
+    private applyCreatedUser;
+    private postUser;
+    private execCreateUser;
+    private execLogin;
+    private handleMissingUser;
+    private resolveQPushId;
+    private execUpdateUser;
+    private execSetAlias;
+    private execRemoveAlias;
+    private execFetchUser;
+    private execSyncSubscription;
+    private execCreateSubscription;
+    /** @internal Used by the facade to know whether `initialize` was called. */
+    get isInitialized(): boolean;
+}