react-native-qpush 0.0.0-stage → 1.0.0

package/lib/core/operationQueue.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationQueue = void 0;
+exports.computeBackoffDelay = computeBackoffDelay;
+const logger_1 = require("./logger");
+const operations_1 = require("./operations");
+const platform_1 = require("./platform");
+const storage_1 = require("./storage");
+/**
+ * Exponential backoff: base * 2^(level-1), capped at max, ±25% jitter.
+ * A server provided `Retry-After` wins when it is larger.
+ */
+function computeBackoffDelay(level, options) {
+    var _a;
+    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, (_a = options.retryAfterMs) !== null && _a !== void 0 ? _a : 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.
+ */
+class OperationQueue {
+    constructor(options) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        this.options = options;
+        this.items = [];
+        this.loaded = false;
+        this.inFlightId = null;
+        this.running = null;
+        this.retryTimer = null;
+        this.retryAt = null;
+        /** Consecutive failures of the head item (drives the backoff delay). */
+        this.backoffLevel = 0;
+        this.sequence = 0;
+        this.scheduler = (_a = options.scheduler) !== null && _a !== void 0 ? _a : platform_1.defaultScheduler;
+        this.now = (_b = options.now) !== null && _b !== void 0 ? _b : Date.now;
+        this.random = (_c = options.random) !== null && _c !== void 0 ? _c : Math.random;
+        this.logger = (_d = options.logger) !== null && _d !== void 0 ? _d : new logger_1.Logger();
+        this.maxAttempts = (_e = options.maxAttempts) !== null && _e !== void 0 ? _e : 5;
+        this.baseDelayMs = (_f = options.baseDelayMs) !== null && _f !== void 0 ? _f : 1000;
+        this.maxDelayMs = (_g = options.maxDelayMs) !== null && _g !== void 0 ? _g : 5 * 60000;
+        this.writer = new storage_1.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() {
+        if (this.loaded)
+            return;
+        const persisted = await (0, storage_1.readJson)(this.options.store, this.options.storageKey);
+        const restored = [];
+        if (Array.isArray(persisted)) {
+            for (const entry of persisted) {
+                if (entry &&
+                    typeof entry === 'object' &&
+                    typeof entry.id === 'string' &&
+                    (0, operations_1.isValidOperation)(entry.operation)) {
+                    const item = entry;
+                    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() {
+        return this.loaded;
+    }
+    /** Snapshot of pending items (head first). */
+    get pending() {
+        return this.items.slice();
+    }
+    get size() {
+        return this.items.length;
+    }
+    /** Id of the item currently executing, if any. */
+    get inFlight() {
+        return this.inFlightId;
+    }
+    /** Time of the next scheduled retry, if the queue is backing off. */
+    get nextRetryAt() {
+        return this.retryAt;
+    }
+    has(predicate) {
+        return this.items.some((item) => predicate(item.operation, item));
+    }
+    /** Adds an operation (merged into the tail when possible) and processes. */
+    enqueue(operation) {
+        this.append(operation, true);
+        this.process();
+    }
+    /** Removes pending (not in-flight) items matching the predicate. */
+    remove(predicate) {
+        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() {
+        this.remove(() => true);
+    }
+    /** Cancels any backoff wait and processes immediately. */
+    kick() {
+        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() {
+        while (this.running)
+            await this.running;
+    }
+    /** Resolves when all pending writes reached the store. */
+    persisted() {
+        return this.writer.flush();
+    }
+    /** Starts a processing run if possible. Returns the run promise. */
+    process() {
+        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 = this.runLoop().then(() => this.afterRun(run), (error) => {
+            this.logger.error('Operation queue run failed', error);
+            this.afterRun(run);
+        });
+        this.running = run;
+        return run;
+    }
+    afterRun(run) {
+        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();
+        }
+    }
+    append(operation, persist) {
+        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 = (0, operations_1.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();
+    }
+    nextId() {
+        this.sequence += 1;
+        return `${this.now().toString(36)}-${this.sequence.toString(36)}-${Math.floor(this.random() * 1e9).toString(36)}`;
+    }
+    persist() {
+        if (!this.loaded)
+            return;
+        void this.writer.write(JSON.stringify(this.items));
+    }
+    async runLoop() {
+        var _a, _b, _c, _d, _e;
+        while (this.items.length > 0) {
+            if (this.options.canProcess && !this.options.canProcess())
+                return;
+            const item = this.items[0];
+            this.inFlightId = item.id;
+            let result;
+            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 = (_a = result.reason) !== null && _a !== void 0 ? _a : 'not retryable';
+                    this.logger.warn(`Dropped operation ${item.operation.kind}: ${reason}`);
+                    (_c = (_b = this.options).onDrop) === null || _c === void 0 ? void 0 : _c.call(_b, 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}`);
+                (_e = (_d = this.options).onDrop) === null || _e === void 0 ? void 0 : _e.call(_d, 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;
+        }
+    }
+    removeById(id) {
+        const index = this.items.findIndex((entry) => entry.id === id);
+        if (index >= 0)
+            this.items.splice(index, 1);
+    }
+}
+exports.OperationQueue = OperationQueue;

package/lib/core/operations.d.ts

@@ -0,0 +1,80 @@
+import { type TagChanges } from './tags';
+/**
+ * Operations are persisted in the queue as plain JSON. Every user-scoped
+ * operation references the user by a *local id* generated on the device; the
+ * real `qpush_id` is resolved when the operation executes (the user may not
+ * exist on the server yet when the operation is enqueued). This keeps changes
+ * made before `login()`/`logout()` attached to the right user.
+ */
+/** `POST /apps/{app_id}/users` (cold start for a new device, and `logout()`). */
+export interface CreateUserOperation {
+    kind: 'createUser';
+    userLocalId: string;
+    identity: Record<string, string>;
+    /** Include the current subscription id so the server moves it (logout). */
+    transferSubscription: boolean;
+}
+/** `login(externalId)`: identify the anonymous user or switch users. */
+export interface LoginOperation {
+    kind: 'login';
+    userLocalId: string;
+    externalId: string;
+    previousLocalId: string;
+    previousWasAnonymous: boolean;
+}
+/** `PATCH /apps/{app_id}/users/by/qpush_id/{id}` */
+export interface UpdateUserOperation {
+    kind: 'updateUser';
+    userLocalId: string;
+    tags?: TagChanges;
+    properties?: {
+        language?: string;
+        timezone_id?: string;
+        country?: string;
+    };
+    deltas?: {
+        session_count?: number;
+        session_time?: number;
+    };
+}
+/** `PATCH .../identity` */
+export interface SetAliasOperation {
+    kind: 'setAlias';
+    userLocalId: string;
+    aliases: Record<string, string>;
+}
+/** `DELETE .../identity/{label}` */
+export interface RemoveAliasOperation {
+    kind: 'removeAlias';
+    userLocalId: string;
+    label: string;
+}
+/** `GET /apps/{app_id}/users/by/qpush_id/{id}` to refresh the local cache. */
+export interface FetchUserOperation {
+    kind: 'fetchUser';
+    userLocalId: string;
+}
+/**
+ * State based: computes the diff between the local subscription and what the
+ * server acknowledged at execution time, then `PATCH /subscriptions/{id}`.
+ */
+export interface SyncSubscriptionOperation {
+    kind: 'syncSubscription';
+}
+/** `POST .../users/by/qpush_id/{id}/subscriptions` (subscription lost server side). */
+export interface CreateSubscriptionOperation {
+    kind: 'createSubscription';
+    userLocalId: string;
+}
+export type Operation = CreateUserOperation | LoginOperation | UpdateUserOperation | SetAliasOperation | RemoveAliasOperation | FetchUserOperation | SyncSubscriptionOperation | CreateSubscriptionOperation;
+export type OperationKind = Operation['kind'];
+/**
+ * Tries to merge `next` into `previous` (the tail of the queue). Returns the
+ * merged operation, or `null` when they cannot be merged.
+ */
+export declare function mergeOperations(previous: Operation, next: Operation): Operation | null;
+/** Operations that (re)create the device subscription on the server. */
+export declare function createsSubscription(operation: Operation): boolean;
+/** Returns the local user id an operation is scoped to, if any. */
+export declare function operationUserLocalId(operation: Operation): string | undefined;
+export declare function isValidOperation(value: unknown): value is Operation;

package/lib/core/operations.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeOperations = mergeOperations;
+exports.createsSubscription = createsSubscription;
+exports.operationUserLocalId = operationUserLocalId;
+exports.isValidOperation = isValidOperation;
+const tags_1 = require("./tags");
+function sumDelta(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return a + b;
+}
+function stripEmpty(value) {
+    if (!value)
+        return undefined;
+    const result = {};
+    for (const key of Object.keys(value)) {
+        if (value[key] !== undefined)
+            result[key] = value[key];
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Tries to merge `next` into `previous` (the tail of the queue). Returns the
+ * merged operation, or `null` when they cannot be merged.
+ */
+function mergeOperations(previous, next) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    if (previous.kind === 'updateUser' && next.kind === 'updateUser') {
+        if (previous.userLocalId !== next.userLocalId)
+            return null;
+        const tags = previous.tags || next.tags ? (0, tags_1.mergeTagChanges)((_a = previous.tags) !== null && _a !== void 0 ? _a : {}, (_b = next.tags) !== null && _b !== void 0 ? _b : {}) : undefined;
+        const properties = stripEmpty({ ...((_c = previous.properties) !== null && _c !== void 0 ? _c : {}), ...((_d = next.properties) !== null && _d !== void 0 ? _d : {}) });
+        const deltas = stripEmpty({
+            session_count: sumDelta((_e = previous.deltas) === null || _e === void 0 ? void 0 : _e.session_count, (_f = next.deltas) === null || _f === void 0 ? void 0 : _f.session_count),
+            session_time: sumDelta((_g = previous.deltas) === null || _g === void 0 ? void 0 : _g.session_time, (_h = next.deltas) === null || _h === void 0 ? void 0 : _h.session_time),
+        });
+        const merged = { kind: 'updateUser', userLocalId: next.userLocalId };
+        if (tags && Object.keys(tags).length > 0)
+            merged.tags = tags;
+        if (properties)
+            merged.properties = properties;
+        if (deltas)
+            merged.deltas = deltas;
+        return merged;
+    }
+    if (previous.kind === 'setAlias' && next.kind === 'setAlias') {
+        if (previous.userLocalId !== next.userLocalId)
+            return null;
+        return { kind: 'setAlias', userLocalId: next.userLocalId, aliases: { ...previous.aliases, ...next.aliases } };
+    }
+    if (previous.kind === 'syncSubscription' && next.kind === 'syncSubscription') {
+        return previous;
+    }
+    if (previous.kind === 'fetchUser' && next.kind === 'fetchUser' && previous.userLocalId === next.userLocalId) {
+        return previous;
+    }
+    return null;
+}
+/** Operations that (re)create the device subscription on the server. */
+function createsSubscription(operation) {
+    return operation.kind === 'createUser' || operation.kind === 'login' || operation.kind === 'createSubscription';
+}
+/** Returns the local user id an operation is scoped to, if any. */
+function operationUserLocalId(operation) {
+    return 'userLocalId' in operation ? operation.userLocalId : undefined;
+}
+function isValidOperation(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const kind = value.kind;
+    switch (kind) {
+        case 'createUser':
+        case 'login':
+        case 'updateUser':
+        case 'setAlias':
+        case 'removeAlias':
+        case 'fetchUser':
+        case 'createSubscription':
+            return typeof value.userLocalId === 'string';
+        case 'syncSubscription':
+            return true;
+        default:
+            return false;
+    }
+}

package/lib/core/payload.d.ts

@@ -0,0 +1,20 @@
+import type { ActionButton, QPushNotificationData } from '../types';
+type JsonObject = Record<string, unknown>;
+export declare function parseButtons(value: unknown): ActionButton[] | undefined;
+/**
+ * Parses the Android `data["qpush"]` JSON (already decoded) into the
+ * normalized notification shape.
+ */
+export declare function parseAndroidPayload(qpush: JsonObject, raw?: JsonObject): QPushNotificationData | null;
+/** Parses an iOS `userInfo` dictionary (`aps` + `qpush`). */
+export declare function parseIosPayload(userInfo: JsonObject): QPushNotificationData | null;
+/**
+ * Parses whatever the native layer forwarded:
+ *  - Android: the `data["qpush"]` JSON string, the decoded object, or the
+ *    whole FCM data map (`{ qpush: "<json>" }`)
+ *  - iOS: the notification `userInfo` (`{ aps, qpush }`)
+ *
+ * Returns `null` when the payload is not a QPush notification.
+ */
+export declare function parseNotificationPayload(raw: unknown): QPushNotificationData | null;
+export {};

package/lib/core/payload.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseButtons = parseButtons;
+exports.parseAndroidPayload = parseAndroidPayload;
+exports.parseIosPayload = parseIosPayload;
+exports.parseNotificationPayload = parseNotificationPayload;
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    if (typeof value === 'string')
+        return value.length > 0 ? value : undefined;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+function asNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function tryParseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `data` is normally an object but tolerate a JSON string. */
+function asDataObject(value) {
+    if (isObject(value))
+        return value;
+    if (typeof value === 'string') {
+        const parsed = tryParseJson(value);
+        if (isObject(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function parseButtons(value) {
+    let list = value;
+    if (typeof list === 'string')
+        list = tryParseJson(list);
+    if (!Array.isArray(list))
+        return undefined;
+    const buttons = [];
+    for (const entry of list) {
+        if (!isObject(entry))
+            continue;
+        const id = asString(entry.id);
+        const text = asString(entry.text);
+        if (!id || !text)
+            continue;
+        const button = { id, text };
+        const icon = asString(entry.icon);
+        const url = asString(entry.url);
+        if (icon)
+            button.icon = icon;
+        if (url)
+            button.url = url;
+        buttons.push(button);
+    }
+    return buttons.length > 0 ? buttons : undefined;
+}
+function stripUndefined(value) {
+    const result = { ...value };
+    for (const key of Object.keys(result)) {
+        if (result[key] === undefined)
+            delete result[key];
+    }
+    return result;
+}
+/**
+ * Parses the Android `data["qpush"]` JSON (already decoded) into the
+ * normalized notification shape.
+ */
+function parseAndroidPayload(qpush, raw = qpush) {
+    const notificationId = asString(qpush.id);
+    if (!notificationId)
+        return null;
+    return stripUndefined({
+        notificationId,
+        title: asString(qpush.title),
+        body: asString(qpush.body),
+        launchURL: asString(qpush.url),
+        additionalData: asDataObject(qpush.data),
+        bigPicture: asString(qpush.image),
+        largeIcon: asString(qpush.large_icon),
+        smallIcon: asString(qpush.small_icon),
+        accentColor: asString(qpush.accent_color),
+        sound: asString(qpush.sound),
+        channelId: asString(qpush.channel_id),
+        priority: asNumber(qpush.priority),
+        groupKey: asString(qpush.group),
+        collapseId: asString(qpush.collapse_id),
+        visibility: asNumber(qpush.visibility),
+        actionButtons: parseButtons(qpush.buttons),
+        rawPayload: raw,
+    });
+}
+/** Parses an iOS `userInfo` dictionary (`aps` + `qpush`). */
+function parseIosPayload(userInfo) {
+    let qpush = userInfo.qpush;
+    if (typeof qpush === 'string')
+        qpush = tryParseJson(qpush);
+    if (!isObject(qpush))
+        return null;
+    const notificationId = asString(qpush.id);
+    if (!notificationId)
+        return null;
+    const aps = isObject(userInfo.aps) ? userInfo.aps : {};
+    let title;
+    let subtitle;
+    let body;
+    const alert = aps.alert;
+    if (typeof alert === 'string') {
+        body = asString(alert);
+    }
+    else if (isObject(alert)) {
+        title = asString(alert.title);
+        subtitle = asString(alert.subtitle);
+        body = asString(alert.body);
+    }
+    let sound;
+    if (typeof aps.sound === 'string')
+        sound = asString(aps.sound);
+    else if (isObject(aps.sound))
+        sound = asString(aps.sound.name);
+    const contentAvailable = asNumber(aps['content-available']);
+    return stripUndefined({
+        notificationId,
+        title,
+        subtitle,
+        body,
+        launchURL: asString(qpush.url),
+        additionalData: asDataObject(qpush.data),
+        bigPicture: asString(qpush.image),
+        sound,
+        badge: asNumber(aps.badge),
+        category: asString(aps.category),
+        groupKey: asString(aps['thread-id']),
+        interruptionLevel: asString(aps['interruption-level']),
+        relevanceScore: asNumber(aps['relevance-score']),
+        contentAvailable: contentAvailable === 1 ? true : undefined,
+        actionButtons: parseButtons(qpush.buttons),
+        rawPayload: userInfo,
+    });
+}
+/**
+ * Parses whatever the native layer forwarded:
+ *  - Android: the `data["qpush"]` JSON string, the decoded object, or the
+ *    whole FCM data map (`{ qpush: "<json>" }`)
+ *  - iOS: the notification `userInfo` (`{ aps, qpush }`)
+ *
+ * Returns `null` when the payload is not a QPush notification.
+ */
+function parseNotificationPayload(raw) {
+    let value = raw;
+    if (typeof value === 'string')
+        value = tryParseJson(value);
+    if (!isObject(value))
+        return null;
+    // iOS userInfo (always carries `aps`).
+    if (isObject(value.aps))
+        return parseIosPayload(value);
+    // A data map whose `qpush` entry was already decoded. The iOS `qpush`
+    // keys (id/url/data/image/buttons) are a subset of the Android ones.
+    if (isObject(value.qpush))
+        return parseAndroidPayload(value.qpush, value);
+    // Android FCM data map: { qpush: "<json string>" }
+    if (typeof value.qpush === 'string') {
+        const inner = tryParseJson(value.qpush);
+        if (!isObject(inner))
+            return null;
+        return parseAndroidPayload(inner, inner);
+    }
+    // Android `qpush` object itself.
+    if ('id' in value)
+        return parseAndroidPayload(value);
+    return null;
+}