react-native-qpush 0.0.0-stage → 1.0.0

package/src/core/constants.ts

@@ -0,0 +1,42 @@
+export const SDK_NAME = 'qpush-react-native';
+export const SDK_VERSION_NUMBER = '1.0.0';
+/** Value of the `SDK-Version` header and of `subscription.sdk`. */
+export const SDK_VERSION = `${SDK_NAME}/${SDK_VERSION_NUMBER}`;
+
+/** Keys shared with native code (SharedPreferences / UserDefaults + App Group). */
+export const NativeKeys = {
+  appId: 'app_id',
+  serverUrl: 'server_url',
+  subscriptionId: 'subscription_id',
+} as const;
+
+/** Keys used by the TypeScript layer for its own persisted state. */
+export const StorageKeys = {
+  state: 'qpush_ts_state_v1',
+  queue: 'qpush_ts_queue_v1',
+} as const;
+
+/** Events emitted by the native module. */
+export const NativeEventNames = {
+  click: 'QPushPushClick',
+  foregroundWillDisplay: 'QPushPushForegroundWillDisplay',
+  pushToken: 'QPushPushToken',
+} as const;
+
+/** A new session starts after this much time in background. */
+export const SESSION_TIMEOUT_MS = 30_000;
+/** Max time to wait for the native token before syncing the subscription anyway. */
+export const PUSH_REGISTRATION_TIMEOUT_MS = 20_000;
+/** Max time to keep processing the queue after the app goes to background (iOS). */
+export const BACKGROUND_FLUSH_TIMEOUT_MS = 20_000;
+/** Max number of click events buffered until a listener is attached. */
+export const MAX_PENDING_CLICKS = 50;
+
+/** `notification_types` values from the protocol. */
+export const NotificationTypes = {
+  subscribed: 1,
+  notAsked: 0,
+  unsubscribed: -2,
+  missingPlayServices: -3,
+  apnsFailed: -10,
+} as const;

package/src/core/events.ts

@@ -0,0 +1,34 @@
+/** Minimal typed event hub (no dependency on Node's EventEmitter). */
+export class EventHub<Events extends { [K in keyof Events]: unknown }> {
+  private readonly listeners: { [K in keyof Events]?: Set<(payload: Events[K]) => void> } = {};
+
+  add<K extends keyof Events>(event: K, listener: (payload: Events[K]) => void): void {
+    let set = this.listeners[event];
+    if (!set) {
+      set = new Set();
+      this.listeners[event] = set;
+    }
+    set.add(listener);
+  }
+
+  remove<K extends keyof Events>(event: K, listener: (payload: Events[K]) => void): void {
+    this.listeners[event]?.delete(listener);
+  }
+
+  count<K extends keyof Events>(event: K): number {
+    return this.listeners[event]?.size ?? 0;
+  }
+
+  /** Calls every listener synchronously; a throwing listener does not stop the others. */
+  emit<K extends keyof Events>(event: K, payload: Events[K], onError?: (error: unknown) => void): void {
+    const set = this.listeners[event];
+    if (!set) return;
+    for (const listener of Array.from(set)) {
+      try {
+        listener(payload);
+      } catch (error) {
+        onError?.(error);
+      }
+    }
+  }
+}

package/src/core/http.ts

@@ -0,0 +1,146 @@
+import { SDK_VERSION } from './constants';
+import { Logger } from './logger';
+import type { ExecutionResult } from './operationQueue';
+import type { FetchLike, Scheduler } from './platform';
+import { joinUrl } from './url';
+
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+
+export interface HttpResponse<T = unknown> {
+  ok: boolean;
+  /** HTTP status, `0` for network failures / timeouts. */
+  status: number;
+  data?: T;
+  /** First `errors[].code` of an error response. */
+  errorCode?: string;
+  /** First `errors[].title` of an error response. */
+  errorMessage?: string;
+  retryAfterMs?: number;
+  networkError?: boolean;
+}
+
+export interface HttpClientOptions {
+  fetch: FetchLike;
+  getBaseUrl: () => string | undefined;
+  getSubscriptionId: () => string | undefined;
+  scheduler: Scheduler;
+  logger: Logger;
+  now?: () => number;
+  timeoutMs?: number;
+  sdkVersion?: string;
+}
+
+/** 429 and 5xx are retryable (protocol), as are network failures (status 0). */
+export function isRetryableStatus(status: number): boolean {
+  return status === 0 || status === 429 || status >= 500;
+}
+
+/** Parses a `Retry-After` header (seconds or HTTP date). */
+export function parseRetryAfter(value: string | null | undefined, now: number = Date.now()): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (/^\d+(\.\d+)?$/.test(trimmed)) return Math.round(parseFloat(trimmed) * 1000);
+  const date = Date.parse(trimmed);
+  if (Number.isNaN(date)) return undefined;
+  return Math.max(0, date - now);
+}
+
+/** Maps a failed (or successful) response to a queue execution result. */
+export function classifyResponse(response: HttpResponse): ExecutionResult {
+  if (response.ok) return { type: 'success' };
+  if (response.status === 0) return { type: 'retry', countAttempt: false };
+  if (isRetryableStatus(response.status)) return { type: 'retry', retryAfterMs: response.retryAfterMs };
+  const detail = response.errorCode ?? response.errorMessage ?? '';
+  return { type: 'drop', reason: `HTTP ${response.status}${detail ? ` (${detail})` : ''}` };
+}
+
+interface ErrorBody {
+  errors?: { code?: string; title?: string }[];
+}
+
+export class HttpClient {
+  private readonly timeoutMs: number;
+  private readonly sdkVersion: string;
+  private readonly now: () => number;
+
+  constructor(private readonly options: HttpClientOptions) {
+    this.timeoutMs = options.timeoutMs ?? 30_000;
+    this.sdkVersion = options.sdkVersion ?? SDK_VERSION;
+    this.now = options.now ?? Date.now;
+  }
+
+  headers(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'SDK-Version': this.sdkVersion,
+    };
+    const subscriptionId = this.options.getSubscriptionId();
+    if (subscriptionId) headers['QPush-Subscription-Id'] = subscriptionId;
+    return headers;
+  }
+
+  async request<T = unknown>(method: HttpMethod, path: string, body?: unknown): Promise<HttpResponse<T>> {
+    const base = this.options.getBaseUrl();
+    if (!base) {
+      return { ok: false, status: 0, networkError: true, errorMessage: 'SDK not initialized' };
+    }
+    const url = joinUrl(base, path);
+    const init = {
+      method,
+      headers: this.headers(),
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: undefined as unknown,
+    };
+
+    let controller: AbortController | undefined;
+    if (typeof AbortController !== 'undefined') {
+      controller = new AbortController();
+      init.signal = controller.signal;
+    }
+    let timedOut = false;
+    const timer = this.options.scheduler.setTimeout(() => {
+      timedOut = true;
+      controller?.abort();
+    }, this.timeoutMs);
+
+    this.options.logger.verbose(`HTTP ${method} ${url}`, init.body ?? '');
+    try {
+      const response = await this.options.fetch(url, init);
+      const text = await response.text();
+      let parsed: unknown;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = undefined;
+        }
+      }
+      const ok = response.status >= 200 && response.status < 300;
+      const result: HttpResponse<T> = { ok, status: response.status };
+      if (ok) {
+        result.data = parsed as T;
+      } else {
+        const errors = (parsed as ErrorBody | undefined)?.errors;
+        if (Array.isArray(errors) && errors.length > 0) {
+          result.errorCode = errors[0]?.code;
+          result.errorMessage = errors[0]?.title;
+        }
+        result.retryAfterMs = parseRetryAfter(response.headers?.get?.('Retry-After') ?? null, this.now());
+        this.options.logger.debug(`HTTP ${method} ${path} -> ${response.status}`, text);
+      }
+      this.options.logger.verbose(`HTTP ${method} ${path} -> ${response.status}`);
+      return result;
+    } catch (error) {
+      this.options.logger.debug(`HTTP ${method} ${path} failed${timedOut ? ' (timeout)' : ''}`, error);
+      return {
+        ok: false,
+        status: 0,
+        networkError: true,
+        errorMessage: timedOut ? 'timeout' : String(error),
+      };
+    } finally {
+      this.options.scheduler.clearTimeout(timer);
+    }
+  }
+}

package/src/core/logger.ts

@@ -0,0 +1,42 @@
+import { LogLevel } from '../types';
+
+type ConsoleLike = Pick<Console, 'error' | 'warn' | 'info' | 'log'>;
+
+/** Tiny leveled logger. Default level is `Warn`, like OneSignal. */
+export class Logger {
+  private level: LogLevel = LogLevel.Warn;
+
+  constructor(private readonly sink: ConsoleLike = console, private readonly prefix = '[QPush]') {}
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  getLevel(): LogLevel {
+    return this.level;
+  }
+
+  fatal(message: string, ...args: unknown[]): void {
+    if (this.level >= LogLevel.Fatal) this.sink.error(`${this.prefix} ${message}`, ...args);
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    if (this.level >= LogLevel.Error) this.sink.error(`${this.prefix} ${message}`, ...args);
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    if (this.level >= LogLevel.Warn) this.sink.warn(`${this.prefix} ${message}`, ...args);
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    if (this.level >= LogLevel.Info) this.sink.info(`${this.prefix} ${message}`, ...args);
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    if (this.level >= LogLevel.Debug) this.sink.log(`${this.prefix} ${message}`, ...args);
+  }
+
+  verbose(message: string, ...args: unknown[]): void {
+    if (this.level >= LogLevel.Verbose) this.sink.log(`${this.prefix} ${message}`, ...args);
+  }
+}

package/src/core/operationQueue.ts

@@ -0,0 +1,324 @@
+import { Logger } from './logger';
+import { isValidOperation, mergeOperations, type Operation } from './operations';
+import { defaultScheduler, type Scheduler } from './platform';
+import { readJson, SerialWriter, type KeyValueStore } from './storage';
+
+export interface QueueItem {
+  id: string;
+  operation: Operation;
+  /** Failed attempts that count towards `maxAttempts` (429 / 5xx). */
+  attempts: number;
+  createdAt: number;
+}
+
+export type ExecutionResult =
+  | { type: 'success' }
+  /**
+   * Retry later with exponential backoff. `countAttempt: false` is used for
+   * network failures (offline): they are retried forever with backoff so
+   * offline changes are delivered later, instead of being dropped.
+   */
+  | { type: 'retry'; retryAfterMs?: number; countAttempt?: boolean }
+  | { type: 'drop'; reason?: string };
+
+export interface OperationQueueOptions {
+  store: KeyValueStore;
+  storageKey: string;
+  execute: (operation: Operation, item: QueueItem) => Promise<ExecutionResult>;
+  /** Max counted attempts before an operation is dropped (default 5). */
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  /** Processing only happens while this returns true. */
+  canProcess?: () => boolean;
+  onDrop?: (item: QueueItem, reason: string) => void;
+  scheduler?: Scheduler;
+  now?: () => number;
+  random?: () => number;
+  logger?: Logger;
+}
+
+export interface BackoffOptions {
+  baseDelayMs: number;
+  maxDelayMs: number;
+  /** 0..1, adds up to ±25% jitter. Pass 0.5 for no jitter. */
+  random: number;
+  retryAfterMs?: number;
+}
+
+/**
+ * Exponential backoff: base * 2^(level-1), capped at max, ±25% jitter.
+ * A server provided `Retry-After` wins when it is larger.
+ */
+export function computeBackoffDelay(level: number, options: BackoffOptions): number {
+  const exponent = Math.max(0, level - 1);
+  const raw = Math.min(options.maxDelayMs, options.baseDelayMs * Math.pow(2, exponent));
+  const jitterFactor = 0.75 + Math.min(1, Math.max(0, options.random)) * 0.5;
+  let delay = Math.round(raw * jitterFactor);
+  if (options.retryAfterMs !== undefined && options.retryAfterMs > delay) {
+    delay = options.retryAfterMs;
+  }
+  return Math.min(Math.max(delay, 0), Math.max(options.maxDelayMs, options.retryAfterMs ?? 0));
+}
+
+/**
+ * Persisted, ordered operation queue.
+ *
+ *  - Operations run strictly one at a time, in order (head-of-line blocking is
+ *    intended: later operations may depend on earlier ones).
+ *  - Every change is persisted, so pending operations survive restarts.
+ *  - Adjacent compatible operations are merged (see `mergeOperations`).
+ *  - 429 / 5xx are retried with exponential backoff up to `maxAttempts`;
+ *    network failures are retried without limit; other errors drop the item.
+ */
+export class OperationQueue {
+  private items: QueueItem[] = [];
+  private loaded = false;
+  private inFlightId: string | null = null;
+  private running: Promise<void> | null = null;
+  private retryTimer: unknown = null;
+  private retryAt: number | null = null;
+  /** Consecutive failures of the head item (drives the backoff delay). */
+  private backoffLevel = 0;
+  private sequence = 0;
+  private readonly writer: SerialWriter;
+  private readonly scheduler: Scheduler;
+  private readonly now: () => number;
+  private readonly random: () => number;
+  private readonly logger: Logger;
+  private readonly maxAttempts: number;
+  private readonly baseDelayMs: number;
+  private readonly maxDelayMs: number;
+
+  constructor(private readonly options: OperationQueueOptions) {
+    this.scheduler = options.scheduler ?? defaultScheduler;
+    this.now = options.now ?? Date.now;
+    this.random = options.random ?? Math.random;
+    this.logger = options.logger ?? new Logger();
+    this.maxAttempts = options.maxAttempts ?? 5;
+    this.baseDelayMs = options.baseDelayMs ?? 1000;
+    this.maxDelayMs = options.maxDelayMs ?? 5 * 60_000;
+    this.writer = new SerialWriter(options.store, options.storageKey, (error) =>
+      this.logger.error('Failed to persist the operation queue', error),
+    );
+  }
+
+  /** Loads persisted items. Items enqueued before `load()` are kept after them. */
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    const persisted = await readJson<unknown>(this.options.store, this.options.storageKey);
+    const restored: QueueItem[] = [];
+    if (Array.isArray(persisted)) {
+      for (const entry of persisted) {
+        if (
+          entry &&
+          typeof entry === 'object' &&
+          typeof (entry as QueueItem).id === 'string' &&
+          isValidOperation((entry as QueueItem).operation)
+        ) {
+          const item = entry as QueueItem;
+          restored.push({
+            id: item.id,
+            operation: item.operation,
+            attempts: typeof item.attempts === 'number' ? item.attempts : 0,
+            createdAt: typeof item.createdAt === 'number' ? item.createdAt : this.now(),
+          });
+        }
+      }
+    }
+    const early = this.items;
+    this.items = restored;
+    this.loaded = true;
+    for (const item of early) this.append(item.operation, false);
+    if (restored.length > 0) this.logger.debug(`Restored ${restored.length} pending operation(s)`);
+    this.persist();
+  }
+
+  get isLoaded(): boolean {
+    return this.loaded;
+  }
+
+  /** Snapshot of pending items (head first). */
+  get pending(): readonly QueueItem[] {
+    return this.items.slice();
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  /** Id of the item currently executing, if any. */
+  get inFlight(): string | null {
+    return this.inFlightId;
+  }
+
+  /** Time of the next scheduled retry, if the queue is backing off. */
+  get nextRetryAt(): number | null {
+    return this.retryAt;
+  }
+
+  has(predicate: (operation: Operation, item: QueueItem) => boolean): boolean {
+    return this.items.some((item) => predicate(item.operation, item));
+  }
+
+  /** Adds an operation (merged into the tail when possible) and processes. */
+  enqueue(operation: Operation): void {
+    this.append(operation, true);
+    this.process();
+  }
+
+  /** Removes pending (not in-flight) items matching the predicate. */
+  remove(predicate: (operation: Operation, item: QueueItem) => boolean): number {
+    const before = this.items.length;
+    this.items = this.items.filter((item) => item.id === this.inFlightId || !predicate(item.operation, item));
+    const removed = before - this.items.length;
+    if (removed > 0) this.persist();
+    return removed;
+  }
+
+  /** Drops everything that is not in flight. */
+  clear(): void {
+    this.remove(() => true);
+  }
+
+  /** Cancels any backoff wait and processes immediately. */
+  kick(): void {
+    if (this.retryTimer !== null) {
+      this.scheduler.clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+      this.retryAt = null;
+    }
+    this.process();
+  }
+
+  /** Resolves when the current processing run is over (empty, blocked or backing off). */
+  async idle(): Promise<void> {
+    while (this.running) await this.running;
+  }
+
+  /** Resolves when all pending writes reached the store. */
+  persisted(): Promise<void> {
+    return this.writer.flush();
+  }
+
+  /** Starts a processing run if possible. Returns the run promise. */
+  process(): Promise<void> {
+    if (this.running) return this.running;
+    if (!this.loaded || this.retryTimer !== null || this.items.length === 0) return Promise.resolve();
+    if (this.options.canProcess && !this.options.canProcess()) return Promise.resolve();
+    const run: Promise<void> = this.runLoop().then(
+      () => this.afterRun(run),
+      (error) => {
+        this.logger.error('Operation queue run failed', error);
+        this.afterRun(run);
+      },
+    );
+    this.running = run;
+    return run;
+  }
+
+  private afterRun(run: Promise<void>): void {
+    if (this.running === run) this.running = null;
+    // Items enqueued while the loop was finishing must not be stranded.
+    if (
+      this.items.length > 0 &&
+      this.retryTimer === null &&
+      (!this.options.canProcess || this.options.canProcess())
+    ) {
+      void this.process();
+    }
+  }
+
+  private append(operation: Operation, persist: boolean): void {
+    const tail = this.items[this.items.length - 1];
+    if (operation.kind === 'syncSubscription') {
+      // State based: one pending (not in-flight) sync is always enough.
+      const pendingSync = this.items.some(
+        (item) => item.operation.kind === 'syncSubscription' && item.id !== this.inFlightId,
+      );
+      if (pendingSync) return;
+    }
+    if (tail && this.loaded && tail.id !== this.inFlightId) {
+      const merged = mergeOperations(tail.operation, operation);
+      if (merged) {
+        tail.operation = merged;
+        if (persist) this.persist();
+        return;
+      }
+    }
+    this.items.push({ id: this.nextId(), operation, attempts: 0, createdAt: this.now() });
+    if (persist && this.loaded) this.persist();
+  }
+
+  private nextId(): string {
+    this.sequence += 1;
+    return `${this.now().toString(36)}-${this.sequence.toString(36)}-${Math.floor(this.random() * 1e9).toString(36)}`;
+  }
+
+  private persist(): void {
+    if (!this.loaded) return;
+    void this.writer.write(JSON.stringify(this.items));
+  }
+
+  private async runLoop(): Promise<void> {
+    while (this.items.length > 0) {
+      if (this.options.canProcess && !this.options.canProcess()) return;
+      const item = this.items[0]!;
+      this.inFlightId = item.id;
+      let result: ExecutionResult;
+      try {
+        result = await this.options.execute(item.operation, item);
+      } catch (error) {
+        this.logger.error(`Operation ${item.operation.kind} threw, dropping it`, error);
+        result = { type: 'drop', reason: 'exception' };
+      } finally {
+        this.inFlightId = null;
+      }
+
+      if (result.type === 'success' || result.type === 'drop') {
+        this.removeById(item.id);
+        this.backoffLevel = 0;
+        if (result.type === 'drop') {
+          const reason = result.reason ?? 'not retryable';
+          this.logger.warn(`Dropped operation ${item.operation.kind}: ${reason}`);
+          this.options.onDrop?.(item, reason);
+        }
+        this.persist();
+        continue;
+      }
+
+      // Retry.
+      if (result.countAttempt !== false) item.attempts += 1;
+      if (item.attempts >= this.maxAttempts) {
+        this.removeById(item.id);
+        this.backoffLevel = 0;
+        const reason = `gave up after ${item.attempts} attempts`;
+        this.logger.warn(`Dropped operation ${item.operation.kind}: ${reason}`);
+        this.options.onDrop?.(item, reason);
+        this.persist();
+        continue;
+      }
+      this.backoffLevel += 1;
+      this.persist();
+      const delay = computeBackoffDelay(this.backoffLevel, {
+        baseDelayMs: this.baseDelayMs,
+        maxDelayMs: this.maxDelayMs,
+        random: this.random(),
+        retryAfterMs: result.retryAfterMs,
+      });
+      this.logger.debug(`Retrying ${item.operation.kind} in ${delay}ms`);
+      this.retryAt = this.now() + delay;
+      this.retryTimer = this.scheduler.setTimeout(() => {
+        this.retryTimer = null;
+        this.retryAt = null;
+        void this.process();
+      }, delay);
+      return;
+    }
+  }
+
+  private removeById(id: string): void {
+    const index = this.items.findIndex((entry) => entry.id === id);
+    if (index >= 0) this.items.splice(index, 1);
+  }
+}