react-native-qpush 0.0.0-stage → 1.0.0

package/lib/core/constants.d.ts

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

package/lib/core/constants.js

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

package/lib/core/events.d.ts

@@ -0,0 +1,11 @@
+/** Minimal typed event hub (no dependency on Node's EventEmitter). */
+export declare class EventHub<Events extends {
+    [K in keyof Events]: unknown;
+}> {
+    private readonly listeners;
+    add<K extends keyof Events>(event: K, listener: (payload: Events[K]) => void): void;
+    remove<K extends keyof Events>(event: K, listener: (payload: Events[K]) => void): void;
+    count<K extends keyof Events>(event: K): number;
+    /** 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;
+}

package/lib/core/events.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventHub = void 0;
+/** Minimal typed event hub (no dependency on Node's EventEmitter). */
+class EventHub {
+    constructor() {
+        this.listeners = {};
+    }
+    add(event, listener) {
+        let set = this.listeners[event];
+        if (!set) {
+            set = new Set();
+            this.listeners[event] = set;
+        }
+        set.add(listener);
+    }
+    remove(event, listener) {
+        var _a;
+        (_a = this.listeners[event]) === null || _a === void 0 ? void 0 : _a.delete(listener);
+    }
+    count(event) {
+        var _a, _b;
+        return (_b = (_a = this.listeners[event]) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0;
+    }
+    /** Calls every listener synchronously; a throwing listener does not stop the others. */
+    emit(event, payload, onError) {
+        const set = this.listeners[event];
+        if (!set)
+            return;
+        for (const listener of Array.from(set)) {
+            try {
+                listener(payload);
+            }
+            catch (error) {
+                onError === null || onError === void 0 ? void 0 : onError(error);
+            }
+        }
+    }
+}
+exports.EventHub = EventHub;

package/lib/core/http.d.ts

@@ -0,0 +1,41 @@
+import { Logger } from './logger';
+import type { ExecutionResult } from './operationQueue';
+import type { FetchLike, Scheduler } from './platform';
+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 declare function isRetryableStatus(status: number): boolean;
+/** Parses a `Retry-After` header (seconds or HTTP date). */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/** Maps a failed (or successful) response to a queue execution result. */
+export declare function classifyResponse(response: HttpResponse): ExecutionResult;
+export declare class HttpClient {
+    private readonly options;
+    private readonly timeoutMs;
+    private readonly sdkVersion;
+    private readonly now;
+    constructor(options: HttpClientOptions);
+    headers(): Record<string, string>;
+    request<T = unknown>(method: HttpMethod, path: string, body?: unknown): Promise<HttpResponse<T>>;
+}

package/lib/core/http.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+exports.isRetryableStatus = isRetryableStatus;
+exports.parseRetryAfter = parseRetryAfter;
+exports.classifyResponse = classifyResponse;
+const constants_1 = require("./constants");
+const url_1 = require("./url");
+/** 429 and 5xx are retryable (protocol), as are network failures (status 0). */
+function isRetryableStatus(status) {
+    return status === 0 || status === 429 || status >= 500;
+}
+/** Parses a `Retry-After` header (seconds or HTTP date). */
+function parseRetryAfter(value, now = Date.now()) {
+    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. */
+function classifyResponse(response) {
+    var _a, _b;
+    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 = (_b = (_a = response.errorCode) !== null && _a !== void 0 ? _a : response.errorMessage) !== null && _b !== void 0 ? _b : '';
+    return { type: 'drop', reason: `HTTP ${response.status}${detail ? ` (${detail})` : ''}` };
+}
+class HttpClient {
+    constructor(options) {
+        var _a, _b, _c;
+        this.options = options;
+        this.timeoutMs = (_a = options.timeoutMs) !== null && _a !== void 0 ? _a : 30000;
+        this.sdkVersion = (_b = options.sdkVersion) !== null && _b !== void 0 ? _b : constants_1.SDK_VERSION;
+        this.now = (_c = options.now) !== null && _c !== void 0 ? _c : Date.now;
+    }
+    headers() {
+        const headers = {
+            '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(method, path, body) {
+        var _a, _b, _c, _d, _e, _f;
+        const base = this.options.getBaseUrl();
+        if (!base) {
+            return { ok: false, status: 0, networkError: true, errorMessage: 'SDK not initialized' };
+        }
+        const url = (0, url_1.joinUrl)(base, path);
+        const init = {
+            method,
+            headers: this.headers(),
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: undefined,
+        };
+        let controller;
+        if (typeof AbortController !== 'undefined') {
+            controller = new AbortController();
+            init.signal = controller.signal;
+        }
+        let timedOut = false;
+        const timer = this.options.scheduler.setTimeout(() => {
+            timedOut = true;
+            controller === null || controller === void 0 ? void 0 : controller.abort();
+        }, this.timeoutMs);
+        this.options.logger.verbose(`HTTP ${method} ${url}`, (_a = init.body) !== null && _a !== void 0 ? _a : '');
+        try {
+            const response = await this.options.fetch(url, init);
+            const text = await response.text();
+            let parsed;
+            if (text) {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = undefined;
+                }
+            }
+            const ok = response.status >= 200 && response.status < 300;
+            const result = { ok, status: response.status };
+            if (ok) {
+                result.data = parsed;
+            }
+            else {
+                const errors = parsed === null || parsed === void 0 ? void 0 : parsed.errors;
+                if (Array.isArray(errors) && errors.length > 0) {
+                    result.errorCode = (_b = errors[0]) === null || _b === void 0 ? void 0 : _b.code;
+                    result.errorMessage = (_c = errors[0]) === null || _c === void 0 ? void 0 : _c.title;
+                }
+                result.retryAfterMs = parseRetryAfter((_f = (_e = (_d = response.headers) === null || _d === void 0 ? void 0 : _d.get) === null || _e === void 0 ? void 0 : _e.call(_d, 'Retry-After')) !== null && _f !== void 0 ? _f : 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);
+        }
+    }
+}
+exports.HttpClient = HttpClient;

package/lib/core/logger.d.ts

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

package/lib/core/logger.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const types_1 = require("../types");
+/** Tiny leveled logger. Default level is `Warn`, like OneSignal. */
+class Logger {
+    constructor(sink = console, prefix = '[QPush]') {
+        this.sink = sink;
+        this.prefix = prefix;
+        this.level = types_1.LogLevel.Warn;
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    getLevel() {
+        return this.level;
+    }
+    fatal(message, ...args) {
+        if (this.level >= types_1.LogLevel.Fatal)
+            this.sink.error(`${this.prefix} ${message}`, ...args);
+    }
+    error(message, ...args) {
+        if (this.level >= types_1.LogLevel.Error)
+            this.sink.error(`${this.prefix} ${message}`, ...args);
+    }
+    warn(message, ...args) {
+        if (this.level >= types_1.LogLevel.Warn)
+            this.sink.warn(`${this.prefix} ${message}`, ...args);
+    }
+    info(message, ...args) {
+        if (this.level >= types_1.LogLevel.Info)
+            this.sink.info(`${this.prefix} ${message}`, ...args);
+    }
+    debug(message, ...args) {
+        if (this.level >= types_1.LogLevel.Debug)
+            this.sink.log(`${this.prefix} ${message}`, ...args);
+    }
+    verbose(message, ...args) {
+        if (this.level >= types_1.LogLevel.Verbose)
+            this.sink.log(`${this.prefix} ${message}`, ...args);
+    }
+}
+exports.Logger = Logger;

package/lib/core/operationQueue.d.ts

@@ -0,0 +1,117 @@
+import { Logger } from './logger';
+import { type Operation } from './operations';
+import { type Scheduler } from './platform';
+import { 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 declare function computeBackoffDelay(level: number, options: BackoffOptions): number;
+/**
+ * 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 declare class OperationQueue {
+    private readonly options;
+    private items;
+    private loaded;
+    private inFlightId;
+    private running;
+    private retryTimer;
+    private retryAt;
+    /** Consecutive failures of the head item (drives the backoff delay). */
+    private backoffLevel;
+    private sequence;
+    private readonly writer;
+    private readonly scheduler;
+    private readonly now;
+    private readonly random;
+    private readonly logger;
+    private readonly maxAttempts;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    constructor(options: OperationQueueOptions);
+    /** Loads persisted items. Items enqueued before `load()` are kept after them. */
+    load(): Promise<void>;
+    get isLoaded(): boolean;
+    /** Snapshot of pending items (head first). */
+    get pending(): readonly QueueItem[];
+    get size(): number;
+    /** Id of the item currently executing, if any. */
+    get inFlight(): string | null;
+    /** Time of the next scheduled retry, if the queue is backing off. */
+    get nextRetryAt(): number | null;
+    has(predicate: (operation: Operation, item: QueueItem) => boolean): boolean;
+    /** Adds an operation (merged into the tail when possible) and processes. */
+    enqueue(operation: Operation): void;
+    /** Removes pending (not in-flight) items matching the predicate. */
+    remove(predicate: (operation: Operation, item: QueueItem) => boolean): number;
+    /** Drops everything that is not in flight. */
+    clear(): void;
+    /** Cancels any backoff wait and processes immediately. */
+    kick(): void;
+    /** Resolves when the current processing run is over (empty, blocked or backing off). */
+    idle(): Promise<void>;
+    /** Resolves when all pending writes reached the store. */
+    persisted(): Promise<void>;
+    /** Starts a processing run if possible. Returns the run promise. */
+    process(): Promise<void>;
+    private afterRun;
+    private append;
+    private nextId;
+    private persist;
+    private runLoop;
+    private removeById;
+}