react-native-qpush 0.0.0-stage → 1.0.0

package/src/core/QPushCore.ts

@@ -0,0 +1,1515 @@
+import {
+  QPushNotification,
+  NotificationWillDisplayEvent,
+  type NotificationClickEvent,
+} from '../notification';
+import {
+  LogLevel,
+  NotificationPermission,
+  type AndroidParams,
+  type QPushInitOptions,
+  QPUSH_CLOUD_API_URL,
+  type PermissionStatus,
+  type PushSubscriptionChangedState,
+  type PushSubscriptionState,
+  type SubscriptionPayload,
+  type UserChangedState,
+  type UserPayload,
+  type UserState,
+} from '../types';
+import {
+  BACKGROUND_FLUSH_TIMEOUT_MS,
+  MAX_PENDING_CLICKS,
+  NativeEventNames,
+  NativeKeys,
+  PUSH_REGISTRATION_TIMEOUT_MS,
+  SESSION_TIMEOUT_MS,
+  StorageKeys,
+} from './constants';
+import { EventHub } from './events';
+import { classifyResponse, HttpClient, isRetryableStatus, type HttpResponse } from './http';
+import { Logger } from './logger';
+import { OperationQueue, type ExecutionResult, type QueueItem } from './operationQueue';
+import {
+  createsSubscription,
+  type CreateSubscriptionOperation,
+  type CreateUserOperation,
+  type FetchUserOperation,
+  type LoginOperation,
+  type Operation,
+  type RemoveAliasOperation,
+  type SetAliasOperation,
+  type UpdateUserOperation,
+} from './operations';
+import { parseNotificationPayload } from './payload';
+import type { NativePushRegistration, PlatformAdapter, Subscription } from './platform';
+import { createDefaultState, createUser, sanitizeState, type PersistedState, type PersistedUser } from './state';
+import { readJson, SerialWriter } from './storage';
+import {
+  buildSubscriptionFields,
+  computeOptedIn,
+  diffSubscription,
+  isPermissionGranted,
+  subscriptionType,
+  toSubscriptionPayload,
+  type DeviceInfo,
+  type SubscriptionFields,
+  type SubscriptionInputs,
+  type SubscriptionPatch,
+} from './subscription';
+import {
+  applyTagChanges,
+  changesForAdd,
+  changesForRemove,
+  isEmpty,
+  mergeTagChanges,
+  normalizeTags,
+  type TagChanges,
+} from './tags';
+import { encodeSegment, normalizeServerUrl } from './url';
+import { generateUuid } from './uuid';
+
+export interface CoreEvents {
+  click: NotificationClickEvent;
+  foregroundWillDisplay: NotificationWillDisplayEvent;
+  permissionChange: boolean;
+  pushSubscriptionChange: PushSubscriptionChangedState;
+  userChange: UserChangedState;
+}
+
+/** Aliases that cannot be set / removed through `addAlias` / `removeAlias`. */
+const RESERVED_ALIASES = ['qpush_id', 'onesignal_id', 'external_id'];
+
+interface NativeClickPayload {
+  rawPayload: unknown;
+  actionId?: string | null;
+  url?: string | null;
+}
+
+interface NativeForegroundPayload {
+  displayId: string;
+  rawPayload: unknown;
+}
+
+function identityQPushId(identity: Record<string, unknown> | undefined): string | undefined {
+  if (!identity) return undefined;
+  const id = identity.qpush_id ?? identity.onesignal_id;
+  return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+
+function aliasesFromIdentity(identity: Record<string, unknown>): Record<string, string> {
+  const aliases: Record<string, string> = {};
+  for (const key of Object.keys(identity)) {
+    const value = identity[key];
+    if (key === 'qpush_id' || key === 'onesignal_id') continue;
+    if (typeof value === 'string') aliases[key] = value;
+  }
+  return aliases;
+}
+
+function stringTags(tags: unknown): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (typeof tags !== 'object' || tags === null) return result;
+  for (const [key, value] of Object.entries(tags as Record<string, unknown>)) {
+    if (value === null || value === undefined || value === '') continue;
+    result[key] = typeof value === 'string' ? value : String(value);
+  }
+  return result;
+}
+
+function samePushState(a: PushSubscriptionState, b: PushSubscriptionState): boolean {
+  return a.id === b.id && a.token === b.token && a.optedIn === b.optedIn;
+}
+
+function permissionToEnum(status: PermissionStatus): NotificationPermission {
+  switch (status) {
+    case 'granted':
+      return NotificationPermission.Authorized;
+    case 'denied':
+      return NotificationPermission.Denied;
+    case 'provisional':
+      return NotificationPermission.Provisional;
+    case 'ephemeral':
+      return NotificationPermission.Ephemeral;
+    default:
+      return NotificationPermission.NotDetermined;
+  }
+}
+
+/** Language code from a locale (`pt-BR` -> `pt`, `iw` -> `he`). */
+export function languageFromLocale(locale: string | undefined): string | undefined {
+  if (!locale) return undefined;
+  const code = locale.split(/[-_]/)[0]?.toLowerCase();
+  if (!code) return undefined;
+  const legacy: Record<string, string> = { iw: 'he', in: 'id', ji: 'yi' };
+  return legacy[code] ?? code;
+}
+
+/**
+ * The single implementation of the QPush user / subscription / HTTP state
+ * machine. Platform specifics are injected through {@link PlatformAdapter}.
+ */
+export class QPushCore {
+  readonly logger: Logger;
+  readonly events = new EventHub<CoreEvents>();
+  readonly queue: OperationQueue;
+
+  private readonly http: HttpClient;
+  private readonly stateWriter: SerialWriter;
+  private state: PersistedState;
+  private loadPromise: Promise<void> | null = null;
+  private commandChain: Promise<void> = Promise.resolve();
+
+  private device: DeviceInfo | null = null;
+  private initializeCalled = false;
+  private started = false;
+  private registrationSettled = false;
+  private registering = false;
+  private halted = false;
+
+  private foregroundAt: number | null = null;
+  private backgroundAt: number | null = null;
+  private pendingColdSession = false;
+  private appStateSubscription: Subscription | null = null;
+  private nativeSubscriptions: Subscription[] = [];
+  private pendingClicks: NotificationClickEvent[] = [];
+  private clickFlushScheduled = false;
+
+  constructor(private readonly platform: PlatformAdapter, logger: Logger = new Logger()) {
+    this.logger = logger;
+    this.state = createDefaultState(this.uuid());
+    this.stateWriter = new SerialWriter(platform.native, StorageKeys.state, (error) =>
+      this.logger.error('Failed to persist state', error),
+    );
+    this.http = new HttpClient({
+      fetch: platform.fetch,
+      getBaseUrl: () => this.state.config?.serverUrl,
+      getSubscriptionId: () => this.state.subscription.id,
+      scheduler: platform.scheduler,
+      logger: this.logger,
+      now: () => platform.now(),
+    });
+    this.queue = new OperationQueue({
+      store: platform.native,
+      storageKey: StorageKeys.queue,
+      execute: (operation, item) => this.execute(operation, item),
+      canProcess: () => this.canProcess(),
+      scheduler: platform.scheduler,
+      now: () => platform.now(),
+      random: () => platform.random(),
+      logger: this.logger,
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Plumbing
+  // ---------------------------------------------------------------------------
+
+  private uuid(): string {
+    return generateUuid(() => this.platform.random());
+  }
+
+  private ensureLoaded(): Promise<void> {
+    if (!this.loadPromise) this.loadPromise = this.load();
+    return this.loadPromise;
+  }
+
+  private async load(): Promise<void> {
+    const saved = await readJson<unknown>(this.platform.native, StorageKeys.state);
+    this.state = sanitizeState(saved, () => this.uuid());
+    await this.queue.load();
+    // Must be enqueued before any operation of this user (tags set before
+    // initialize, consent, ...). Execution waits until the SDK started.
+    this.ensureUserCreation();
+  }
+
+  /** Enqueues `createUser` for the current user unless it exists or is being created. */
+  private ensureUserCreation(): void {
+    const user = this.state.user;
+    if (user.qpushId) return;
+    const pending = this.queue.has(
+      (operation) =>
+        (operation.kind === 'createUser' || operation.kind === 'login') && operation.userLocalId === user.localId,
+    );
+    if (pending) return;
+    this.queue.enqueue({
+      kind: 'createUser',
+      userLocalId: user.localId,
+      identity: user.externalId ? { external_id: user.externalId } : {},
+      transferSubscription: !!this.state.subscription.id,
+    });
+  }
+
+  /** Runs `fn` after state is loaded, serialized with every other command. */
+  private command(fn: () => void | Promise<void>): Promise<void> {
+    const next = this.commandChain
+      .then(() => this.ensureLoaded())
+      .then(fn)
+      .catch((error) => this.logger.error('Unexpected error', error));
+    this.commandChain = next;
+    return next;
+  }
+
+  /** Reads state after every previously issued command ran. */
+  private async read<T>(fn: () => T): Promise<T> {
+    let result!: T;
+    await this.command(() => {
+      result = fn();
+    });
+    return result;
+  }
+
+  private save(): void {
+    void this.stateWriter.write(JSON.stringify(this.state));
+  }
+
+  private canProcess(): boolean {
+    return this.started && this.registrationSettled && !this.halted && this.hasConsent();
+  }
+
+  private hasConsent(): boolean {
+    return !this.state.consentRequired || this.state.consentGiven;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => this.platform.scheduler.setTimeout(resolve, ms));
+  }
+
+  private get appId(): string {
+    return encodeSegment(this.state.config?.appId ?? '');
+  }
+
+  /** Waits for pending commands, queue processing and storage writes (tests). */
+  async flush(): Promise<void> {
+    await this.commandChain;
+    await this.queue.process();
+    await this.queue.idle();
+    await this.commandChain;
+    await this.queue.persisted();
+    await this.stateWriter.flush();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Initialization & consent
+  // ---------------------------------------------------------------------------
+
+  setLogLevel(level: LogLevel): void {
+    this.logger.setLevel(level);
+    try {
+      this.platform.native.setLogLevel(level);
+    } catch {
+      // ignore
+    }
+  }
+
+  initialize(appId: string, options?: QPushInitOptions): void {
+    if (options && typeof options.logLevel === 'number') this.setLogLevel(options.logLevel);
+    if (typeof appId !== 'string' || appId.trim() === '') {
+      this.logger.error('initialize: appId is required');
+      return;
+    }
+    const serverUrl = normalizeServerUrl(options?.serverUrl ?? QPUSH_CLOUD_API_URL);
+    if (!serverUrl) {
+      this.logger.error(`initialize: invalid serverUrl "${String(options?.serverUrl)}"`);
+      return;
+    }
+    const trimmedAppId = appId.trim();
+    if (serverUrl.startsWith('http://')) {
+      this.logger.warn(
+        'initialize: serverUrl uses plain HTTP. Use HTTPS in production. Release builds on Android block ' +
+          'cleartext traffic (delivery receipts and click reports are sent by native code); on iOS use an IP ' +
+          'address, or NSAllowsLocalNetworking for .local hostnames.',
+      );
+    }
+    this.initializeCalled = true;
+    this.attachNativeEvents();
+
+    void this.command(async () => {
+      const previous = this.state.config;
+      if (previous && previous.appId === trimmedAppId && previous.serverUrl === serverUrl && this.started) {
+        this.logger.debug('initialize: already initialized');
+        return;
+      }
+      if (previous && (previous.appId !== trimmedAppId || previous.serverUrl !== serverUrl)) {
+        this.logger.info('initialize: app id or server changed, resetting local user and subscription');
+        this.resetForNewApp();
+      }
+      this.state.config = { appId: trimmedAppId, serverUrl };
+      this.save();
+      await this.writeNative(NativeKeys.appId, trimmedAppId);
+      await this.writeNative(NativeKeys.serverUrl, serverUrl);
+      await this.writeNative(NativeKeys.subscriptionId, this.state.subscription.id ?? null);
+      this.maybeStart();
+    });
+  }
+
+  private resetForNewApp(): void {
+    const { consentRequired, consentGiven } = this.state;
+    const subscription = this.state.subscription;
+    this.queue.clear();
+    this.state = createDefaultState(this.uuid());
+    this.state.consentRequired = consentRequired;
+    this.state.consentGiven = consentGiven;
+    // Keep what belongs to the device, drop what belongs to the old app.
+    this.state.subscription = {
+      optedIn: subscription.optedIn,
+      permission: subscription.permission,
+      token: subscription.token,
+      tokenError: subscription.tokenError,
+    };
+    this.started = false;
+    this.registrationSettled = false;
+    this.halted = false;
+    this.ensureUserCreation();
+  }
+
+  private async writeNative(key: string, value: string | null): Promise<void> {
+    try {
+      if (value === null) await this.platform.native.removeItem(key);
+      else await this.platform.native.setItem(key, value);
+    } catch (error) {
+      this.logger.warn(`Could not persist ${key} natively`, error);
+    }
+  }
+
+  setConsentRequired(required: boolean): void {
+    void this.command(() => {
+      this.state.consentRequired = !!required;
+      this.save();
+      this.maybeStart();
+    });
+  }
+
+  setConsentGiven(given: boolean): void {
+    void this.command(() => {
+      this.state.consentGiven = !!given;
+      this.save();
+      this.maybeStart();
+      if (this.canProcess()) this.queue.kick();
+    });
+  }
+
+  private maybeStart(): void {
+    if (!this.state.config || this.started) return;
+    if (!this.hasConsent()) {
+      this.logger.info('Waiting for privacy consent (setConsentGiven(true)) before starting');
+      return;
+    }
+    this.started = true;
+    void this.start().catch((error) => this.logger.error('Start failed', error));
+  }
+
+  private async start(): Promise<void> {
+    try {
+      this.device = await this.platform.native.getDeviceInfo();
+      if (this.device && !this.device.language) this.device.language = languageFromLocale(this.device.locale);
+    } catch (error) {
+      this.logger.warn('Could not read device info', error);
+      this.device = { platform: this.platform.os };
+    }
+
+    await this.refreshPermission(true);
+
+    await this.command(() => {
+      this.ensureUserCreation();
+      // Pushes changed device fields (app version, OS version...) if any.
+      this.mutateSubscription(() => {});
+    });
+
+    this.attachAppState();
+    const appState = this.platform.appState.currentState;
+    if (appState === 'active' || appState == null || appState === 'unknown') {
+      await this.command(() => this.startSession());
+    } else {
+      this.pendingColdSession = true;
+    }
+
+    await this.command(() => {
+      if (this.state.user.qpushId) {
+        this.queue.enqueue({ kind: 'fetchUser', userLocalId: this.state.user.localId });
+      }
+    });
+
+    await this.registerPush();
+    this.registrationSettled = true;
+    this.queue.kick();
+  }
+
+  /** Retries push registration when the app comes back without a token (offline start, FCM params added later). */
+  private retryRegistrationIfNeeded(): void {
+    const sub = this.state.subscription;
+    if (!this.registrationSettled || this.registering || this.halted || sub.token) return;
+    this.registering = true;
+    void this.registerPush()
+      .catch((error) => this.logger.warn('Push registration retry failed', error))
+      .finally(() => {
+        this.registering = false;
+      });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Push registration & permission
+  // ---------------------------------------------------------------------------
+
+  private async fetchParams(): Promise<'ok' | 'not_found' | 'unavailable'> {
+    const file = this.platform.os === 'android' ? 'android_params.js' : 'ios_params.js';
+    const path = `/apps/${this.appId}/${file}`;
+    for (let attempt = 1; attempt <= 3; attempt++) {
+      const response = await this.http.request<AndroidParams>('GET', path);
+      if (response.ok) {
+        if (this.platform.os === 'android') {
+          const fcm = response.data && 'fcm' in response.data ? response.data.fcm ?? null : null;
+          await this.command(() => {
+            this.state.fcmParams = fcm;
+            this.save();
+          });
+        }
+        return 'ok';
+      }
+      if (response.status === 404) return 'not_found';
+      if (!isRetryableStatus(response.status)) return 'unavailable';
+      if (attempt < 3) await this.sleep(1000 * Math.pow(2, attempt - 1));
+    }
+    return 'unavailable';
+  }
+
+  private async registerPush(): Promise<void> {
+    const params = await this.fetchParams();
+    if (params === 'not_found') {
+      this.halted = true;
+      this.logger.error(
+        `App "${this.state.config?.appId}" was not found on ${this.state.config?.serverUrl}. ` +
+          'Check the app id and serverUrl; the SDK will not sync until the app restarts.',
+      );
+      return;
+    }
+    if (params === 'unavailable') this.logger.warn('Could not fetch app params, using cached values');
+
+    const fcm = this.platform.os === 'android' ? this.state.fcmParams ?? null : null;
+    let registration: Promise<void>;
+    try {
+      registration = this.platform.native.registerForPush(fcm).then(
+        (result) => this.applyRegistration(result),
+        (error) => this.logger.warn('Push registration failed', error),
+      );
+    } catch (error) {
+      this.logger.warn('Push registration failed', error);
+      return;
+    }
+    let timer: unknown;
+    const timeout = new Promise<void>((resolve) => {
+      timer = this.platform.scheduler.setTimeout(() => {
+        this.logger.warn('Push token not received yet, continuing without it');
+        resolve();
+      }, PUSH_REGISTRATION_TIMEOUT_MS);
+    });
+    await Promise.race([registration, timeout]);
+    this.platform.scheduler.clearTimeout(timer);
+  }
+
+  private applyRegistration(result: NativePushRegistration | null | undefined): Promise<void> {
+    return this.command(() => {
+      if (!result) return;
+      this.mutateSubscription(() => {
+        const sub = this.state.subscription;
+        if (result.token) {
+          sub.token = result.token;
+          sub.tokenError = undefined;
+        } else if (typeof result.notificationTypes === 'number' && result.notificationTypes < 0) {
+          // A transient failure (e.g. offline) must not unsubscribe a device
+          // that already has a valid token.
+          if (!sub.token) sub.tokenError = result.notificationTypes;
+          this.logger.warn(`Push registration error (${result.notificationTypes}): ${result.error ?? 'unknown'}`);
+        } else if (result.error) {
+          this.logger.warn(`Push registration error: ${result.error}`);
+        }
+      });
+    });
+  }
+
+  private applyToken(token: string): void {
+    if (!token) return;
+    void this.command(() => {
+      this.mutateSubscription(() => {
+        this.state.subscription.token = token;
+        this.state.subscription.tokenError = undefined;
+      });
+    });
+  }
+
+  /** Reads the OS permission and updates the subscription when it changed. */
+  async refreshPermission(emit: boolean): Promise<PermissionStatus> {
+    let status: PermissionStatus;
+    try {
+      status = await this.platform.native.getPermissionStatus();
+    } catch (error) {
+      this.logger.warn('Could not read notification permission', error);
+      return this.read(() => this.state.subscription.permission);
+    }
+    await this.command(() => {
+      const previous = this.state.subscription.permission;
+      if (previous === status) return;
+      this.mutateSubscription(() => {
+        this.state.subscription.permission = status;
+      });
+      const wasGranted = isPermissionGranted(previous);
+      const isGranted = isPermissionGranted(status);
+      if (emit && wasGranted !== isGranted) {
+        this.events.emit('permissionChange', isGranted, (error) =>
+          this.logger.error('permissionChange listener threw', error),
+        );
+      }
+    });
+    return status;
+  }
+
+  async requestPermission(fallbackToSettings: boolean): Promise<boolean> {
+    await this.ensureLoaded();
+    let granted = false;
+    try {
+      granted = await this.platform.native.requestPermission(!!fallbackToSettings);
+    } catch (error) {
+      this.logger.error('requestPermission failed', error);
+    }
+    const status = await this.refreshPermission(true);
+    return granted || isPermissionGranted(status);
+  }
+
+  async registerForProvisionalAuthorization(): Promise<boolean> {
+    await this.ensureLoaded();
+    let accepted = false;
+    try {
+      accepted = await this.platform.native.registerForProvisionalAuthorization();
+    } catch (error) {
+      this.logger.error('registerForProvisionalAuthorization failed', error);
+    }
+    await this.refreshPermission(true);
+    return accepted;
+  }
+
+  async getPermission(): Promise<boolean> {
+    await this.ensureLoaded();
+    return isPermissionGranted(await this.refreshPermission(true));
+  }
+
+  async permissionNative(): Promise<NotificationPermission> {
+    await this.ensureLoaded();
+    return permissionToEnum(await this.refreshPermission(true));
+  }
+
+  async canRequestPermission(): Promise<boolean> {
+    try {
+      return await this.platform.native.canRequestPermission();
+    } catch {
+      return false;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Subscription
+  // ---------------------------------------------------------------------------
+
+  private subscriptionInputs(): SubscriptionInputs {
+    const sub = this.state.subscription;
+    return { token: sub.token, tokenError: sub.tokenError, permission: sub.permission, optedIn: sub.optedIn };
+  }
+
+  private currentFields(): SubscriptionFields {
+    return buildSubscriptionFields(this.subscriptionInputs(), this.device);
+  }
+
+  private pushState(): PushSubscriptionState {
+    const sub = this.state.subscription;
+    return { id: sub.id ?? null, token: sub.token ?? null, optedIn: computeOptedIn(this.subscriptionInputs()) };
+  }
+
+  /** Applies a subscription change, emits `change` and schedules a sync. */
+  private mutateSubscription(fn: () => void): void {
+    const before = this.pushState();
+    fn();
+    const after = this.pushState();
+    this.save();
+    this.scheduleSyncIfDirty();
+    if (!samePushState(before, after)) {
+      this.events.emit('pushSubscriptionChange', { previous: before, current: after }, (error) =>
+        this.logger.error('pushSubscription change listener threw', error),
+      );
+    }
+  }
+
+  private scheduleSyncIfDirty(): void {
+    const sub = this.state.subscription;
+    // A pending create sends the live subscription snapshot anyway.
+    if (!sub.id && this.queue.has((operation, item) => item.id !== this.queue.inFlight && createsSubscription(operation))) {
+      return;
+    }
+    const dirty = sub.badgeResetPending || !isEmpty(diffSubscription(sub.synced, this.currentFields()));
+    if (dirty) this.queue.enqueue({ kind: 'syncSubscription' });
+  }
+
+  private setSubscriptionId(id: string | undefined): void {
+    if (this.state.subscription.id === id) return;
+    this.mutateSubscription(() => {
+      this.state.subscription.id = id;
+    });
+    void this.writeNative(NativeKeys.subscriptionId, id ?? null);
+  }
+
+  optIn(): void {
+    void this.command(async () => {
+      this.mutateSubscription(() => {
+        this.state.subscription.optedIn = true;
+      });
+      if (this.state.subscription.permission === 'notDetermined') {
+        void this.requestPermission(false);
+      }
+    });
+  }
+
+  optOut(): void {
+    void this.command(() => {
+      this.mutateSubscription(() => {
+        this.state.subscription.optedIn = false;
+      });
+    });
+  }
+
+  getSubscriptionId(): Promise<string | null> {
+    return this.read(() => this.state.subscription.id ?? null);
+  }
+
+  getSubscriptionToken(): Promise<string | null> {
+    return this.read(() => this.state.subscription.token ?? null);
+  }
+
+  getOptedIn(): Promise<boolean> {
+    return this.read(() => computeOptedIn(this.subscriptionInputs()));
+  }
+
+  // ---------------------------------------------------------------------------
+  // User
+  // ---------------------------------------------------------------------------
+
+  private userState(): UserState {
+    return { qpushId: this.state.user.qpushId ?? null, externalId: this.state.user.externalId ?? null };
+  }
+
+  private mutateUser(fn: () => void): void {
+    const before = this.userState();
+    fn();
+    const after = this.userState();
+    this.save();
+    if (before.qpushId !== after.qpushId || before.externalId !== after.externalId) {
+      this.events.emit('userChange', { current: after }, (error) =>
+        this.logger.error('User change listener threw', error),
+      );
+    }
+  }
+
+  login(externalId: string): void {
+    void this.command(() => {
+      if (typeof externalId !== 'string' || externalId.trim() === '') {
+        this.logger.error('login: externalId must be a non-empty string');
+        return;
+      }
+      const previous = this.state.user;
+      if (previous.externalId === externalId) {
+        this.logger.debug('login: already logged in with this external id');
+        return;
+      }
+      const anonymous = !previous.externalId;
+      const next: PersistedUser = {
+        ...createUser(this.uuid()),
+        externalId,
+        // Identifying an anonymous user keeps its data (OneSignal semantics).
+        aliases: anonymous ? { ...previous.aliases, external_id: externalId } : { external_id: externalId },
+        tags: anonymous ? { ...previous.tags } : {},
+        language: previous.language,
+        languageExplicit: previous.languageExplicit,
+        timezone: previous.timezone,
+      };
+      this.mutateUser(() => {
+        this.state.user = next;
+      });
+      this.queue.enqueue({
+        kind: 'login',
+        userLocalId: next.localId,
+        externalId,
+        previousLocalId: previous.localId,
+        previousWasAnonymous: anonymous,
+      });
+    });
+  }
+
+  logout(): void {
+    void this.command(() => {
+      const previous = this.state.user;
+      if (!previous.externalId) {
+        this.logger.debug('logout: no user is logged in');
+        return;
+      }
+      const next: PersistedUser = {
+        ...createUser(this.uuid()),
+        language: previous.language,
+        languageExplicit: previous.languageExplicit,
+        timezone: previous.timezone,
+      };
+      this.mutateUser(() => {
+        this.state.user = next;
+      });
+      this.queue.enqueue({
+        kind: 'createUser',
+        userLocalId: next.localId,
+        identity: {},
+        transferSubscription: true,
+      });
+    });
+  }
+
+  addTags(tags: Record<string, unknown>): void {
+    void this.command(() => {
+      if (!tags || typeof tags !== 'object') {
+        this.logger.error('addTags: expected an object');
+        return;
+      }
+      const [normalized, rejected] = normalizeTags(tags);
+      if (rejected.length > 0) {
+        this.logger.warn(`addTags: ignored invalid tags: ${rejected.join(', ')} (values must be strings or numbers)`);
+      }
+      const changes = changesForAdd(this.state.user.tags, normalized);
+      this.applyLocalTagChanges(changes);
+    });
+  }
+
+  removeTags(keys: string[]): void {
+    void this.command(() => {
+      if (!Array.isArray(keys)) {
+        this.logger.error('removeTags: expected an array of keys');
+        return;
+      }
+      this.applyLocalTagChanges(changesForRemove(keys));
+    });
+  }
+
+  private applyLocalTagChanges(changes: TagChanges): void {
+    if (isEmpty(changes)) return;
+    this.state.user.tags = applyTagChanges(this.state.user.tags, changes);
+    this.save();
+    this.queue.enqueue({ kind: 'updateUser', userLocalId: this.state.user.localId, tags: changes });
+  }
+
+  getTags(): Promise<Record<string, string>> {
+    return this.read(() => ({ ...this.state.user.tags }));
+  }
+
+  addAliases(aliases: Record<string, string>): void {
+    void this.command(() => {
+      if (!aliases || typeof aliases !== 'object') {
+        this.logger.error('addAliases: expected an object');
+        return;
+      }
+      const valid: Record<string, string> = {};
+      for (const [label, id] of Object.entries(aliases)) {
+        if (typeof label !== 'string' || label.trim() === '' || RESERVED_ALIASES.includes(label)) {
+          this.logger.error(`addAlias: "${label}" cannot be used as an alias label (use login() for external_id)`);
+          continue;
+        }
+        if (typeof id !== 'string' || id === '') {
+          this.logger.error(`addAlias: the id for "${label}" must be a non-empty string`);
+          continue;
+        }
+        valid[label] = id;
+      }
+      if (isEmpty(valid)) return;
+      this.state.user.aliases = { ...this.state.user.aliases, ...valid };
+      this.save();
+      this.queue.enqueue({ kind: 'setAlias', userLocalId: this.state.user.localId, aliases: valid });
+    });
+  }
+
+  removeAliases(labels: string[]): void {
+    void this.command(() => {
+      if (!Array.isArray(labels)) return;
+      for (const label of labels) {
+        if (typeof label !== 'string' || label === '' || RESERVED_ALIASES.includes(label)) {
+          this.logger.error(`removeAlias: "${String(label)}" cannot be removed`);
+          continue;
+        }
+        const aliases = { ...this.state.user.aliases };
+        delete aliases[label];
+        this.state.user.aliases = aliases;
+        this.queue.enqueue({ kind: 'removeAlias', userLocalId: this.state.user.localId, label });
+      }
+      this.save();
+    });
+  }
+
+  setLanguage(language: string): void {
+    void this.command(() => {
+      if (typeof language !== 'string' || language.trim() === '') {
+        this.logger.error('setLanguage: language must be a non-empty string');
+        return;
+      }
+      this.state.user.language = language;
+      this.state.user.languageExplicit = true;
+      this.save();
+      this.queue.enqueue({
+        kind: 'updateUser',
+        userLocalId: this.state.user.localId,
+        properties: { language },
+      });
+    });
+  }
+
+  getQPushId(): Promise<string | null> {
+    return this.read(() => this.state.user.qpushId ?? null);
+  }
+
+  getExternalId(): Promise<string | null> {
+    return this.read(() => this.state.user.externalId ?? null);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Sessions (AppState)
+  // ---------------------------------------------------------------------------
+
+  private attachAppState(): void {
+    if (this.appStateSubscription) return;
+    try {
+      this.appStateSubscription = this.platform.appState.addEventListener('change', (next) =>
+        this.onAppStateChange(next),
+      );
+    } catch (error) {
+      this.logger.warn('Could not observe AppState', error);
+    }
+  }
+
+  private startSession(): void {
+    const now = this.platform.now();
+    this.foregroundAt = now;
+    this.backgroundAt = null;
+    const user = this.state.user;
+    const properties: UpdateUserOperation['properties'] = {};
+    const timezone = this.device?.timezone;
+    if (timezone && timezone !== user.timezone) {
+      properties.timezone_id = timezone;
+      user.timezone = timezone;
+    }
+    const language = this.device?.language;
+    if (!user.languageExplicit && language && language !== user.language) {
+      properties.language = language;
+      user.language = language;
+    }
+    const operation: UpdateUserOperation = {
+      kind: 'updateUser',
+      userLocalId: user.localId,
+      deltas: { session_count: 1 },
+    };
+    if (!isEmpty(properties)) operation.properties = properties;
+    this.save();
+    this.queue.enqueue(operation);
+    this.logger.debug('New session');
+    void this.clearBadge(true);
+  }
+
+  private onAppStateChange(next: string): void {
+    if (next === 'active') {
+      void this.command(() => {
+        const now = this.platform.now();
+        if (this.pendingColdSession) {
+          this.pendingColdSession = false;
+          this.startSession();
+        } else if (this.backgroundAt !== null && now - this.backgroundAt >= SESSION_TIMEOUT_MS) {
+          this.startSession();
+        } else if (this.backgroundAt !== null) {
+          this.foregroundAt = now;
+          this.backgroundAt = null;
+          void this.clearBadge(false);
+        }
+      });
+      void this.refreshPermission(true);
+      this.retryRegistrationIfNeeded();
+      this.queue.kick();
+    } else if (next === 'background') {
+      void this.command(() => {
+        const now = this.platform.now();
+        if (this.foregroundAt !== null) {
+          const seconds = Math.round((now - this.foregroundAt) / 1000);
+          this.foregroundAt = null;
+          if (seconds > 0) {
+            this.queue.enqueue({
+              kind: 'updateUser',
+              userLocalId: this.state.user.localId,
+              deltas: { session_time: seconds },
+            });
+          }
+        }
+        if (this.backgroundAt === null) this.backgroundAt = now;
+      }).then(() => this.flushInBackground());
+    }
+  }
+
+  private async flushInBackground(): Promise<void> {
+    if (!this.canProcess() || this.queue.size === 0) return;
+    let taskId = -1;
+    try {
+      taskId = await this.platform.native.beginBackgroundTask();
+    } catch {
+      taskId = -1;
+    }
+    let timer: unknown;
+    try {
+      await Promise.race([
+        this.queue.process().then(() => this.queue.idle()),
+        new Promise<void>((resolve) => {
+          timer = this.platform.scheduler.setTimeout(resolve, BACKGROUND_FLUSH_TIMEOUT_MS);
+        }),
+      ]);
+    } finally {
+      this.platform.scheduler.clearTimeout(timer);
+      if (taskId >= 0) {
+        try {
+          this.platform.native.endBackgroundTask(taskId);
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  private async clearBadge(newSession: boolean): Promise<void> {
+    if (this.platform.os !== 'ios') return;
+    let previous = 0;
+    try {
+      previous = await this.platform.native.clearBadge();
+    } catch {
+      previous = 0;
+    }
+    if (previous > 0 || newSession) {
+      await this.command(() => {
+        this.mutateSubscription(() => {
+          this.state.subscription.badgeResetPending = true;
+        });
+      });
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Notifications (native events)
+  // ---------------------------------------------------------------------------
+
+  /** Subscribes to native events and tells native that JS is ready. Idempotent. */
+  attachNativeEvents(): void {
+    if (this.nativeSubscriptions.length > 0) return;
+    const source = this.platform.nativeEvents;
+    try {
+      this.nativeSubscriptions = [
+        source.addListener(NativeEventNames.click, (payload: NativeClickPayload) => this.handleNativeClick(payload)),
+        source.addListener(NativeEventNames.foregroundWillDisplay, (payload: NativeForegroundPayload) =>
+          this.handleNativeForeground(payload),
+        ),
+        source.addListener(NativeEventNames.pushToken, (payload: { token?: string }) => {
+          if (payload && typeof payload.token === 'string') this.applyToken(payload.token);
+        }),
+      ];
+      this.platform.native.setJsReady();
+    } catch (error) {
+      this.logger.error('Could not subscribe to native events', error);
+    }
+  }
+
+  private handleNativeClick(payload: NativeClickPayload): void {
+    const data = parseNotificationPayload(payload?.rawPayload);
+    if (!data) {
+      this.logger.debug('Ignoring click on a non-QPush notification');
+      return;
+    }
+    const event: NotificationClickEvent = {
+      result: {},
+      notification: new QPushNotification(data),
+    };
+    if (payload.actionId) event.result.actionId = payload.actionId;
+    const url = payload.url ?? undefined;
+    if (url) event.result.url = url;
+    if (this.events.count('click') > 0) {
+      this.emitClick(event);
+    } else {
+      this.pendingClicks.push(event);
+      if (this.pendingClicks.length > MAX_PENDING_CLICKS) this.pendingClicks.shift();
+    }
+  }
+
+  private emitClick(event: NotificationClickEvent): void {
+    this.events.emit('click', event, (error) => this.logger.error('click listener threw', error));
+  }
+
+  private handleNativeForeground(payload: NativeForegroundPayload): void {
+    if (!payload || typeof payload.displayId !== 'string') return;
+    const displayId = payload.displayId;
+    const data = parseNotificationPayload(payload.rawPayload);
+    if (!data) {
+      this.platform.native.displayForegroundNotification(displayId);
+      return;
+    }
+    const event = new NotificationWillDisplayEvent(data, () =>
+      this.platform.native.displayForegroundNotification(displayId),
+    );
+    this.events.emit('foregroundWillDisplay', event, (error) =>
+      this.logger.error('foregroundWillDisplay listener threw', error),
+    );
+    if (event.settle() === 'prevented') {
+      this.platform.native.preventForegroundDisplay(displayId);
+    }
+  }
+
+  addListener<K extends keyof CoreEvents>(event: K, listener: (payload: CoreEvents[K]) => void): void {
+    this.attachNativeEvents();
+    this.events.add(event, listener);
+    if (event === 'click' && this.pendingClicks.length > 0 && !this.clickFlushScheduled) {
+      // Deliver after the caller finished registering (cold start clicks).
+      this.clickFlushScheduled = true;
+      this.platform.scheduler.setTimeout(() => {
+        this.clickFlushScheduled = false;
+        const pending = this.pendingClicks;
+        this.pendingClicks = [];
+        for (const click of pending) this.emitClick(click);
+      }, 0);
+    }
+  }
+
+  removeListener<K extends keyof CoreEvents>(event: K, listener: (payload: CoreEvents[K]) => void): void {
+    this.events.remove(event, listener);
+  }
+
+  clearAll(): void {
+    try {
+      this.platform.native.clearAll();
+    } catch (error) {
+      this.logger.error('clearAll failed', error);
+    }
+    void this.clearBadge(false);
+  }
+
+  removeNotification(notificationId: string): void {
+    try {
+      this.platform.native.removeNotification(notificationId);
+    } catch (error) {
+      this.logger.error('removeNotification failed', error);
+    }
+  }
+
+  removeGroupedNotifications(groupKey: string): void {
+    try {
+      this.platform.native.removeGroupedNotifications(groupKey);
+    } catch (error) {
+      this.logger.error('removeGroupedNotifications failed', error);
+    }
+  }
+
+  setAutoOpenUrls(enabled: boolean): void {
+    try {
+      this.platform.native.setAutoOpenUrls(!!enabled);
+    } catch (error) {
+      this.logger.error('setAutoOpenUrls failed', error);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Operation execution
+  // ---------------------------------------------------------------------------
+
+  private async execute(operation: Operation, item: QueueItem): Promise<ExecutionResult> {
+    if (!this.state.config) return { type: 'retry', countAttempt: false };
+    switch (operation.kind) {
+      case 'createUser':
+        return this.execCreateUser(operation);
+      case 'login':
+        return this.execLogin(operation);
+      case 'updateUser':
+        return this.execUpdateUser(operation);
+      case 'setAlias':
+        return this.execSetAlias(operation);
+      case 'removeAlias':
+        return this.execRemoveAlias(operation);
+      case 'fetchUser':
+        return this.execFetchUser(operation);
+      case 'syncSubscription':
+        return this.execSyncSubscription(item);
+      case 'createSubscription':
+        return this.execCreateSubscription(operation);
+      default:
+        return { type: 'drop', reason: 'unknown operation' };
+    }
+  }
+
+  private userPath(qpushId: string): string {
+    return `/apps/${this.appId}/users/by/qpush_id/${encodeSegment(qpushId)}`;
+  }
+
+  private userProperties(localId: string): NonNullable<UserPayload['properties']> {
+    const user = this.state.user.localId === localId ? this.state.user : undefined;
+    const properties: NonNullable<UserPayload['properties']> = {};
+    const language = user?.language ?? this.device?.language;
+    if (language) properties.language = language;
+    if (this.device?.timezone) properties.timezone_id = this.device.timezone;
+    if (this.device?.country) properties.country = this.device.country;
+    return properties;
+  }
+
+  /** Tag changes still waiting in the queue for a user (to re-apply over server data). */
+  private pendingTagChanges(localId: string): TagChanges {
+    let changes: TagChanges = {};
+    for (const item of this.queue.pending) {
+      if (item.id === this.queue.inFlight) continue;
+      const operation = item.operation;
+      if (operation.kind === 'updateUser' && operation.userLocalId === localId && operation.tags) {
+        changes = mergeTagChanges(changes, operation.tags);
+      }
+    }
+    return changes;
+  }
+
+  private pendingAliasChanges(localId: string, base: Record<string, string>): Record<string, string> {
+    const aliases = { ...base };
+    for (const item of this.queue.pending) {
+      if (item.id === this.queue.inFlight) continue;
+      const operation = item.operation;
+      if (operation.kind === 'setAlias' && operation.userLocalId === localId) Object.assign(aliases, operation.aliases);
+      if (operation.kind === 'removeAlias' && operation.userLocalId === localId) delete aliases[operation.label];
+    }
+    return aliases;
+  }
+
+  private mapUser(localId: string, qpushId: string, identity?: Record<string, unknown>): void {
+    this.state.idMap[localId] = qpushId;
+    if (this.state.user.localId === localId) {
+      this.mutateUser(() => {
+        const user = this.state.user;
+        user.qpushId = qpushId;
+        if (identity) {
+          user.aliases = this.pendingAliasChanges(localId, aliasesFromIdentity(identity));
+          const externalId = identity.external_id;
+          if (typeof externalId === 'string' && externalId) user.externalId = externalId;
+        }
+      });
+    }
+    this.pruneIdMap();
+    this.save();
+  }
+
+  /** Keeps only ids still referenced by the current user or pending operations. */
+  private pruneIdMap(): void {
+    const referenced = new Set<string>([this.state.user.localId]);
+    for (const item of this.queue.pending) {
+      const operation = item.operation;
+      if ('userLocalId' in operation) referenced.add(operation.userLocalId);
+      if (operation.kind === 'login') referenced.add(operation.previousLocalId);
+    }
+    for (const key of Object.keys(this.state.idMap)) {
+      if (!referenced.has(key)) delete this.state.idMap[key];
+    }
+  }
+
+  /** Picks this device's subscription in a user response. */
+  private findOwnSubscription(
+    subscriptions: SubscriptionPayload[] | undefined,
+    sent: { id?: string; token?: string },
+  ): SubscriptionPayload | undefined {
+    if (!Array.isArray(subscriptions) || subscriptions.length === 0) return undefined;
+    const type = subscriptionType(this.platform.os);
+    if (sent.id) {
+      const byId = subscriptions.find((sub) => sub.id === sent.id);
+      if (byId) return byId;
+    }
+    if (sent.token) {
+      const byToken = subscriptions.find((sub) => sub.token === sent.token);
+      if (byToken) return byToken;
+    } else {
+      const tokenless = subscriptions.filter((sub) => sub.type === type && !sub.token);
+      if (tokenless.length === 1) return tokenless[0];
+    }
+    return subscriptions.length === 1 ? subscriptions[0] : undefined;
+  }
+
+  /** Applies a `POST /users` response (createUser, login fallback). */
+  private applyCreatedUser(
+    localId: string,
+    data: UserPayload | undefined,
+    sentFields: SubscriptionFields,
+    sentId: string | undefined,
+    repushLocalTags: boolean,
+  ): ExecutionResult {
+    const identity = (data?.identity ?? {}) as Record<string, unknown>;
+    const qpushId = identityQPushId(identity);
+    if (!qpushId) return { type: 'drop', reason: 'response without qpush_id' };
+    this.mapUser(localId, qpushId, identity);
+
+    if (this.state.user.localId === localId) {
+      const serverTags = stringTags(data?.properties?.tags);
+      const pending = this.pendingTagChanges(localId);
+      const local = this.state.user.tags;
+      // Re-push local tags the server does not have (never removals: a fresh
+      // install must not wipe the tags of a user it was re-attached to).
+      const missing: TagChanges = {};
+      if (repushLocalTags) {
+        for (const [key, value] of Object.entries(local)) {
+          if (serverTags[key] !== value && !(key in pending)) missing[key] = value;
+        }
+      }
+      this.state.user.tags = applyTagChanges(applyTagChanges(serverTags, missing), pending);
+      if (this.device?.timezone) this.state.user.timezone = this.device.timezone;
+      if (!isEmpty(missing)) {
+        this.queue.enqueue({ kind: 'updateUser', userLocalId: localId, tags: missing });
+      }
+    }
+
+    const own = this.findOwnSubscription(data?.subscriptions, { id: sentId, token: sentFields.token });
+    if (own?.id) {
+      this.state.subscription.synced = { ...sentFields };
+      this.setSubscriptionId(own.id);
+    } else {
+      this.logger.warn('Could not identify this device subscription in the server response');
+    }
+    this.save();
+    this.scheduleSyncIfDirty();
+    return { type: 'success' };
+  }
+
+  private async postUser(
+    localId: string,
+    identity: Record<string, string>,
+    transferSubscription: boolean,
+    repushLocalTags: boolean,
+  ): Promise<ExecutionResult> {
+    const fields = this.currentFields();
+    const sentId = transferSubscription ? this.state.subscription.id : undefined;
+    const body: UserPayload = {
+      identity,
+      properties: this.userProperties(localId),
+      subscriptions: [toSubscriptionPayload(this.platform.os, fields, sentId)],
+    };
+    const response = await this.http.request<UserPayload>('POST', `/apps/${this.appId}/users`, body);
+    if (!response.ok) return classifyResponse(response);
+    return this.applyCreatedUser(localId, response.data, fields, sentId, repushLocalTags);
+  }
+
+  private execCreateUser(operation: CreateUserOperation): Promise<ExecutionResult> {
+    return this.postUser(operation.userLocalId, operation.identity, operation.transferSubscription, true);
+  }
+
+  private async execLogin(operation: LoginOperation): Promise<ExecutionResult> {
+    const identity = { external_id: operation.externalId };
+
+    // 1. Identify the anonymous user (keeps its tags), like OneSignal.
+    const previousQPushId = this.state.idMap[operation.previousLocalId];
+    // Anonymous data carries over only when the anonymous user is identified
+    // (or never reached the server); it is discarded when switching users.
+    let carryAnonymousData = operation.previousWasAnonymous;
+    if (operation.previousWasAnonymous && previousQPushId) {
+      const response = await this.http.request<{ identity?: Record<string, string> }>(
+        'PATCH',
+        `${this.userPath(previousQPushId)}/identity`,
+        { identity },
+      );
+      if (response.ok) {
+        this.mapUser(operation.userLocalId, previousQPushId, response.data?.identity ?? identity);
+        return { type: 'success' };
+      }
+      if (response.status !== 409 && response.status !== 404) return classifyResponse(response);
+      carryAnonymousData = false;
+      this.logger.debug(`login: external id belongs to another user (${response.status}), switching user`);
+    }
+
+    // 2. Move this device's subscription to the user owning the external id.
+    const subscriptionId = this.state.subscription.id;
+    if (subscriptionId) {
+      const response = await this.http.request<{ identity?: Record<string, string> }>(
+        'PATCH',
+        `/apps/${this.appId}/subscriptions/${encodeSegment(subscriptionId)}/owner`,
+        { identity },
+      );
+      if (response.ok) {
+        const qpushId = identityQPushId(response.data?.identity);
+        if (!qpushId) return { type: 'drop', reason: 'owner response without qpush_id' };
+        this.mapUser(operation.userLocalId, qpushId, response.data?.identity ?? identity);
+        // The device switched to an existing user: refresh tags & aliases.
+        this.queue.enqueue({ kind: 'fetchUser', userLocalId: operation.userLocalId });
+        return { type: 'success' };
+      }
+      if (response.status !== 404) return classifyResponse(response);
+      this.setSubscriptionId(undefined);
+      this.state.subscription.synced = undefined;
+    }
+
+    // 3. No subscription on the server yet: create the user with it.
+    return this.postUser(operation.userLocalId, identity, false, carryAnonymousData);
+  }
+
+  private handleMissingUser(localId: string): void {
+    delete this.state.idMap[localId];
+    if (this.state.user.localId !== localId) return;
+    this.logger.warn('The current user no longer exists on the server, creating it again');
+    const previous = this.state.user;
+    const next: PersistedUser = { ...previous, localId: this.uuid(), qpushId: undefined };
+    this.mutateUser(() => {
+      this.state.user = next;
+    });
+    this.queue.enqueue({
+      kind: 'createUser',
+      userLocalId: next.localId,
+      identity: next.externalId ? { external_id: next.externalId } : {},
+      transferSubscription: true,
+    });
+  }
+
+  private resolveQPushId(localId: string): string | undefined {
+    return this.state.idMap[localId] ?? (this.state.user.localId === localId ? this.state.user.qpushId : undefined);
+  }
+
+  private async execUpdateUser(operation: UpdateUserOperation): Promise<ExecutionResult> {
+    const qpushId = this.resolveQPushId(operation.userLocalId);
+    if (!qpushId) return { type: 'drop', reason: 'user was never created on the server' };
+    const properties: Record<string, unknown> = { ...(operation.properties ?? {}) };
+    if (!isEmpty(operation.tags)) properties.tags = operation.tags;
+    const body: Record<string, unknown> = {};
+    if (!isEmpty(properties)) body.properties = properties;
+    if (!isEmpty(operation.deltas)) body.deltas = operation.deltas;
+    if (isEmpty(body)) return { type: 'success' };
+    const response = await this.http.request('PATCH', this.userPath(qpushId), body);
+    if (response.status === 404) {
+      this.handleMissingUser(operation.userLocalId);
+      return { type: 'drop', reason: 'user not found' };
+    }
+    return classifyResponse(response);
+  }
+
+  private async execSetAlias(operation: SetAliasOperation): Promise<ExecutionResult> {
+    const qpushId = this.resolveQPushId(operation.userLocalId);
+    if (!qpushId) return { type: 'drop', reason: 'user was never created on the server' };
+    const response = await this.http.request<{ identity?: Record<string, string> }>(
+      'PATCH',
+      `${this.userPath(qpushId)}/identity`,
+      { identity: operation.aliases },
+    );
+    if (response.ok) {
+      if (response.data?.identity && this.state.user.localId === operation.userLocalId) {
+        this.mapUser(operation.userLocalId, qpushId, response.data.identity);
+      }
+      return { type: 'success' };
+    }
+    if (response.status === 409) {
+      this.logger.error(`addAlias: alias already claimed by another user (${Object.keys(operation.aliases).join(', ')})`);
+      if (this.state.user.localId === operation.userLocalId) {
+        const aliases = { ...this.state.user.aliases };
+        for (const [label, id] of Object.entries(operation.aliases)) if (aliases[label] === id) delete aliases[label];
+        this.state.user.aliases = aliases;
+        this.save();
+      }
+      return { type: 'drop', reason: 'alias_claimed' };
+    }
+    if (response.status === 404) {
+      this.handleMissingUser(operation.userLocalId);
+      return { type: 'drop', reason: 'user not found' };
+    }
+    return classifyResponse(response);
+  }
+
+  private async execRemoveAlias(operation: RemoveAliasOperation): Promise<ExecutionResult> {
+    const qpushId = this.resolveQPushId(operation.userLocalId);
+    if (!qpushId) return { type: 'drop', reason: 'user was never created on the server' };
+    const response = await this.http.request(
+      'DELETE',
+      `${this.userPath(qpushId)}/identity/${encodeSegment(operation.label)}`,
+    );
+    return classifyResponse(response);
+  }
+
+  private async execFetchUser(operation: FetchUserOperation): Promise<ExecutionResult> {
+    const qpushId = this.resolveQPushId(operation.userLocalId);
+    if (!qpushId) return { type: 'drop', reason: 'user was never created on the server' };
+    const response = await this.http.request<UserPayload>('GET', this.userPath(qpushId));
+    if (response.status === 404) {
+      this.handleMissingUser(operation.userLocalId);
+      return { type: 'drop', reason: 'user not found' };
+    }
+    if (!response.ok) return classifyResponse(response);
+    if (this.state.user.localId === operation.userLocalId && response.data) {
+      const identity = (response.data.identity ?? {}) as Record<string, unknown>;
+      this.mapUser(operation.userLocalId, identityQPushId(identity) ?? qpushId, identity);
+      const serverTags = stringTags(response.data.properties?.tags);
+      this.state.user.tags = applyTagChanges(serverTags, this.pendingTagChanges(operation.userLocalId));
+      this.save();
+    }
+    return { type: 'success' };
+  }
+
+  private async execSyncSubscription(item: QueueItem): Promise<ExecutionResult> {
+    const sub = this.state.subscription;
+    if (!sub.id) {
+      // A pending create carries the live snapshot; nothing to do now.
+      if (this.queue.has((operation, other) => other.id !== item.id && createsSubscription(operation))) {
+        return { type: 'success' };
+      }
+      if (!this.state.user.qpushId) return { type: 'success' };
+      return this.execCreateSubscription({ kind: 'createSubscription', userLocalId: this.state.user.localId });
+    }
+    const fields = this.currentFields();
+    const patch: SubscriptionPatch = diffSubscription(sub.synced, fields);
+    const resetBadge = !!sub.badgeResetPending;
+    if (resetBadge) patch.badge_count = 0;
+    if (isEmpty(patch)) return { type: 'success' };
+
+    const response: HttpResponse = await this.http.request(
+      'PATCH',
+      `/apps/${this.appId}/subscriptions/${encodeSegment(sub.id)}`,
+      { subscription: patch },
+    );
+    if (response.ok) {
+      const { badge_count: _ignored, ...sent } = patch;
+      void _ignored;
+      sub.synced = { ...(sub.synced ?? {}), ...sent };
+      if (resetBadge) sub.badgeResetPending = false;
+      this.save();
+      this.scheduleSyncIfDirty();
+      return { type: 'success' };
+    }
+    if (response.status === 404) {
+      this.logger.warn('Subscription not found on the server, creating it again');
+      sub.synced = undefined;
+      this.setSubscriptionId(undefined);
+      this.queue.enqueue({ kind: 'createSubscription', userLocalId: this.state.user.localId });
+      return { type: 'drop', reason: 'subscription not found' };
+    }
+    return classifyResponse(response);
+  }
+
+  private async execCreateSubscription(operation: CreateSubscriptionOperation): Promise<ExecutionResult> {
+    if (this.state.subscription.id) return { type: 'success' };
+    const qpushId = this.resolveQPushId(operation.userLocalId);
+    if (!qpushId) return { type: 'drop', reason: 'user was never created on the server' };
+    const fields = this.currentFields();
+    const response = await this.http.request<{ subscription?: SubscriptionPayload }>(
+      'POST',
+      `${this.userPath(qpushId)}/subscriptions`,
+      { subscription: toSubscriptionPayload(this.platform.os, fields) },
+    );
+    if (response.ok) {
+      const id = response.data?.subscription?.id;
+      if (!id) return { type: 'drop', reason: 'response without subscription id' };
+      this.state.subscription.synced = { ...fields };
+      this.setSubscriptionId(id);
+      this.scheduleSyncIfDirty();
+      return { type: 'success' };
+    }
+    if (response.status === 404) {
+      this.handleMissingUser(operation.userLocalId);
+      return { type: 'drop', reason: 'user not found' };
+    }
+    return classifyResponse(response);
+  }
+
+  /** @internal Used by the facade to know whether `initialize` was called. */
+  get isInitialized(): boolean {
+    return this.initializeCalled;
+  }
+}