@avibra/pulse-core 1.0.0

package/dist/utils/queue.d.ts

@@ -0,0 +1,21 @@
+import type { StorageAdapter, NetworkAdapter } from '../platform';
+import { QueuedRequest } from '../types';
+export declare class OfflineQueue {
+    private queue;
+    private readonly maxSize;
+    private readonly storage;
+    private drainHandler;
+    private unsubscribeNetwork;
+    constructor(maxSize: number, storage: StorageAdapter, network: NetworkAdapter);
+    onDrain(handler: () => Promise<void>): void;
+    enqueue(item: QueuedRequest): void;
+    flush(): QueuedRequest[];
+    get size(): number;
+    get isEmpty(): boolean;
+    peek(): ReadonlyArray<QueuedRequest>;
+    clear(): void;
+    destroy(): void;
+    private persist;
+    private loadFromStorage;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/utils/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/utils/queue.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKzC,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,YAAY,CAAsC;IAC1D,OAAO,CAAC,kBAAkB,CAA6B;gBAE3C,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc;IAYtE,OAAO,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI3C,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAUlC,KAAK,IAAI,aAAa,EAAE;IAO/B,IAAW,IAAI,IAAI,MAAM,CAA8B;IACvD,IAAW,OAAO,IAAI,OAAO,CAAoC;IAC1D,IAAI,IAAI,aAAa,CAAC,aAAa,CAAC;IAEpC,KAAK,IAAI,IAAI;IAKb,OAAO,IAAI,IAAI;YAKR,OAAO;YAQP,eAAe;CAkBhC"}

package/dist/utils/queue.js

@@ -0,0 +1,81 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Pulse Core — Offline Event Queue
+// Uses StorageAdapter + NetworkAdapter instead of direct localStorage/NetInfo.
+// ─────────────────────────────────────────────────────────────────────────────
+import { logger } from './logger';
+const STORAGE_KEY = '__pulse_offline_queue__';
+export class OfflineQueue {
+    constructor(maxSize, storage, network) {
+        this.queue = [];
+        this.drainHandler = null;
+        this.unsubscribeNetwork = null;
+        this.maxSize = maxSize;
+        this.storage = storage;
+        void this.loadFromStorage();
+        this.unsubscribeNetwork = network.onOnline(() => {
+            logger.info('[OfflineQueue] Connection restored — draining queue');
+            if (this.drainHandler && !this.isEmpty) {
+                void this.drainHandler();
+            }
+        });
+    }
+    onDrain(handler) {
+        this.drainHandler = handler;
+    }
+    enqueue(item) {
+        if (this.queue.length >= this.maxSize) {
+            this.queue.shift();
+            logger.warn('[OfflineQueue] Queue full — dropping oldest event');
+        }
+        this.queue.push(item);
+        void this.persist();
+        logger.debug(`[OfflineQueue] Enqueued ${item.endpoint} (queue size: ${this.queue.length})`);
+    }
+    flush() {
+        const items = [...this.queue];
+        this.queue = [];
+        void this.persist();
+        return items;
+    }
+    get size() { return this.queue.length; }
+    get isEmpty() { return this.queue.length === 0; }
+    peek() { return this.queue; }
+    clear() {
+        this.queue = [];
+        void this.persist();
+    }
+    destroy() {
+        this.unsubscribeNetwork?.();
+        this.unsubscribeNetwork = null;
+    }
+    async persist() {
+        try {
+            await this.storage.setItem(STORAGE_KEY, JSON.stringify(this.queue));
+        }
+        catch {
+            logger.warn('[OfflineQueue] Failed to persist queue');
+        }
+    }
+    async loadFromStorage() {
+        try {
+            const raw = await this.storage.getItem(STORAGE_KEY);
+            if (!raw)
+                return;
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return;
+            const persisted = parsed;
+            const existingIds = new Set(this.queue.map((q) => q.id));
+            for (const item of persisted) {
+                if (!existingIds.has(item.id)) {
+                    this.queue.push(item);
+                }
+            }
+            logger.debug(`[OfflineQueue] Restored ${persisted.length} queued event(s)`);
+        }
+        catch {
+            // Corrupt storage — proceed with in-memory only
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/utils/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/utils/queue.ts"],"names":[],"mappings":"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"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,12 @@
+import { RetryConfig } from '../types';
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+export declare class RetryableError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class NonRetryableError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>, context?: string): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,eAAO,MAAM,oBAAoB,EAAE,WAKlC,CAAC;AAEF,qBAAa,cAAe,SAAQ,KAAK;aACQ,UAAU,CAAC,EAAE,MAAM;gBAApD,OAAO,EAAE,MAAM,EAAkB,UAAU,CAAC,EAAE,MAAM,YAAA;CAInE;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aACK,UAAU,CAAC,EAAE,MAAM;gBAApD,OAAO,EAAE,MAAM,EAAkB,UAAU,CAAC,EAAE,MAAM,YAAA;CAInE;AAYD,wBAAsB,SAAS,CAAC,CAAC,EAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EACjC,OAAO,SAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CAwCZ"}

package/dist/utils/retry.js

@@ -0,0 +1,66 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Pulse Core — Exponential Backoff Retry Utility
+// ─────────────────────────────────────────────────────────────────────────────
+import { logger } from './logger';
+export const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    baseDelayMs: 500,
+    maxDelayMs: 10000,
+    noRetryStatuses: [400, 401, 403, 404, 422],
+};
+export class RetryableError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'RetryableError';
+    }
+}
+export class NonRetryableError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'NonRetryableError';
+    }
+}
+function computeDelay(attempt, config) {
+    const exponential = config.baseDelayMs * Math.pow(2, attempt);
+    const capped = Math.min(config.maxDelayMs, exponential);
+    return Math.random() * capped;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function withRetry(fn, config = {}, context = 'request') {
+    const cfg = { ...DEFAULT_RETRY_CONFIG, ...config };
+    let lastError = new Error('Unknown error');
+    for (let attempt = 0; attempt < cfg.maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (error instanceof NonRetryableError) {
+                logger.warn(`[Retry] Non-retryable error for ${context}:`, error.message);
+                throw error;
+            }
+            if (error instanceof RetryableError && error.statusCode !== undefined) {
+                if (cfg.noRetryStatuses.includes(error.statusCode)) {
+                    logger.warn(`[Retry] Status ${error.statusCode} is non-retryable for ${context}`);
+                    throw error;
+                }
+            }
+            lastError = error;
+            const isLastAttempt = attempt === cfg.maxAttempts - 1;
+            if (isLastAttempt) {
+                logger.error(`[Retry] All ${cfg.maxAttempts} attempts failed for ${context}`);
+                break;
+            }
+            const delay = computeDelay(attempt, cfg);
+            logger.debug(`[Retry] Attempt ${attempt + 1}/${cfg.maxAttempts} failed for ${context}. ` +
+                `Retrying in ${Math.round(delay)}ms...`);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@avibra/pulse-core",
+  "version": "1.0.0",
+  "description": "Pulse shared core — platform adapters, API client, and utilities",
+  "author": "Pulse Engineering <engineering@pulse.io>",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}