@drakkar.software/sunglasses-storage-http 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,50 @@
+import { IAnalyticsAdapter, HttpAdapterConfig, SunglassesEvent } from '@drakkar.software/sunglasses-core';
+
+/**
+ * IAnalyticsAdapter that POSTs batches of events to an HTTP endpoint.
+ *
+ * Payload shape (POST body):
+ * ```json
+ * { "batch": SunglassesEvent[], "sentAt": "<ISO-8601>" }
+ * ```
+ *
+ * Retry policy:
+ * - 2xx: success
+ * - 4xx (except 429): non-retriable — batch discarded with warning
+ * - 5xx, 429, network errors, timeout: retry with exponential backoff
+ *
+ * Note: batching (how many events per call) is controlled by SunglassesCore
+ * via `maxBatchSize`. This adapter simply delivers whatever batch it receives.
+ */
+declare class HttpStorageAdapter implements IAnalyticsAdapter {
+    private readonly config;
+    constructor(config: HttpAdapterConfig);
+    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+    private postBatch;
+    private scheduleRetry;
+}
+
+interface RetryTask {
+    attempt: number;
+    execute: () => Promise<void>;
+    onExhausted: () => void;
+}
+interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+/**
+ * Schedules a task with exponential backoff + jitter.
+ *
+ * Retry delay: min(baseDelay * 2^attempt + jitter, maxDelay)
+ * Jitter: random value in [0, baseDelay)
+ *
+ * Non-retriable errors (HTTP 4xx except 429) must be handled by the caller
+ * by not enqueuing the task at all.
+ */
+declare function scheduleRetry(task: RetryTask, config: RetryConfig): void;
+
+export { HttpStorageAdapter, type RetryConfig, type RetryTask, scheduleRetry };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { IAnalyticsAdapter, HttpAdapterConfig, SunglassesEvent } from '@drakkar.software/sunglasses-core';
+
+/**
+ * IAnalyticsAdapter that POSTs batches of events to an HTTP endpoint.
+ *
+ * Payload shape (POST body):
+ * ```json
+ * { "batch": SunglassesEvent[], "sentAt": "<ISO-8601>" }
+ * ```
+ *
+ * Retry policy:
+ * - 2xx: success
+ * - 4xx (except 429): non-retriable — batch discarded with warning
+ * - 5xx, 429, network errors, timeout: retry with exponential backoff
+ *
+ * Note: batching (how many events per call) is controlled by SunglassesCore
+ * via `maxBatchSize`. This adapter simply delivers whatever batch it receives.
+ */
+declare class HttpStorageAdapter implements IAnalyticsAdapter {
+    private readonly config;
+    constructor(config: HttpAdapterConfig);
+    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+    private postBatch;
+    private scheduleRetry;
+}
+
+interface RetryTask {
+    attempt: number;
+    execute: () => Promise<void>;
+    onExhausted: () => void;
+}
+interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+/**
+ * Schedules a task with exponential backoff + jitter.
+ *
+ * Retry delay: min(baseDelay * 2^attempt + jitter, maxDelay)
+ * Jitter: random value in [0, baseDelay)
+ *
+ * Non-retriable errors (HTTP 4xx except 429) must be handled by the caller
+ * by not enqueuing the task at all.
+ */
+declare function scheduleRetry(task: RetryTask, config: RetryConfig): void;
+
+export { HttpStorageAdapter, type RetryConfig, type RetryTask, scheduleRetry };

package/dist/index.js

@@ -0,0 +1,128 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HttpStorageAdapter: () => HttpStorageAdapter,
+  scheduleRetry: () => scheduleRetry
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/RetryQueue.ts
+function scheduleRetry(task, config) {
+  if (task.attempt >= config.maxRetries) {
+    task.onExhausted();
+    return;
+  }
+  const delay = computeDelay(task.attempt, config);
+  setTimeout(() => {
+    task.execute().catch(() => {
+      scheduleRetry(
+        { ...task, attempt: task.attempt + 1 },
+        config
+      );
+    });
+  }, delay);
+}
+function computeDelay(attempt, config) {
+  const safeAttempt = Math.min(attempt, 30);
+  const exponential = config.baseDelayMs * Math.pow(2, safeAttempt);
+  const jitter = Math.random() * config.baseDelayMs;
+  return Math.min(exponential + jitter, config.maxDelayMs);
+}
+
+// src/HttpStorageAdapter.ts
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_DELAY_MS = 1e3;
+var DEFAULT_RETRY_MAX_DELAY_MS = 3e4;
+var DEFAULT_TIMEOUT_MS = 1e4;
+var HttpStorageAdapter = class {
+  constructor(config) {
+    this.config = {
+      endpoint: config.endpoint,
+      headers: config.headers ?? {},
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      retryBaseDelayMs: config.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS,
+      retryMaxDelayMs: config.retryMaxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT_MS
+    };
+  }
+  async send(batch) {
+    if (batch.length === 0) return;
+    await this.postBatch(batch, 0);
+  }
+  async reset() {
+  }
+  async shutdown() {
+  }
+  async postBatch(batch, attempt) {
+    const controller = typeof AbortController !== "undefined" ? new AbortController() : null;
+    const timeoutId = controller ? setTimeout(() => controller.abort(), this.config.timeout) : null;
+    try {
+      const response = await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        },
+        body: JSON.stringify({
+          batch,
+          sentAt: (/* @__PURE__ */ new Date()).toISOString()
+        }),
+        signal: controller?.signal
+      });
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      if (response.ok) return;
+      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+        console.warn(
+          `[SunGlasses] HttpStorageAdapter: non-retriable error ${response.status} \u2014 batch discarded`
+        );
+        return;
+      }
+      this.scheduleRetry(batch, attempt);
+    } catch {
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      this.scheduleRetry(batch, attempt);
+    }
+  }
+  scheduleRetry(batch, attempt) {
+    scheduleRetry(
+      {
+        attempt,
+        execute: () => this.postBatch(batch, attempt + 1),
+        onExhausted: () => {
+          console.warn(
+            `[SunGlasses] HttpStorageAdapter: max retries (${this.config.maxRetries}) exceeded \u2014 batch of ${batch.length} events discarded`
+          );
+        }
+      },
+      {
+        maxRetries: this.config.maxRetries,
+        baseDelayMs: this.config.retryBaseDelayMs,
+        maxDelayMs: this.config.retryMaxDelayMs
+      }
+    );
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HttpStorageAdapter,
+  scheduleRetry
+});

package/dist/index.mjs

@@ -0,0 +1,100 @@
+// src/RetryQueue.ts
+function scheduleRetry(task, config) {
+  if (task.attempt >= config.maxRetries) {
+    task.onExhausted();
+    return;
+  }
+  const delay = computeDelay(task.attempt, config);
+  setTimeout(() => {
+    task.execute().catch(() => {
+      scheduleRetry(
+        { ...task, attempt: task.attempt + 1 },
+        config
+      );
+    });
+  }, delay);
+}
+function computeDelay(attempt, config) {
+  const safeAttempt = Math.min(attempt, 30);
+  const exponential = config.baseDelayMs * Math.pow(2, safeAttempt);
+  const jitter = Math.random() * config.baseDelayMs;
+  return Math.min(exponential + jitter, config.maxDelayMs);
+}
+
+// src/HttpStorageAdapter.ts
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_DELAY_MS = 1e3;
+var DEFAULT_RETRY_MAX_DELAY_MS = 3e4;
+var DEFAULT_TIMEOUT_MS = 1e4;
+var HttpStorageAdapter = class {
+  constructor(config) {
+    this.config = {
+      endpoint: config.endpoint,
+      headers: config.headers ?? {},
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      retryBaseDelayMs: config.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS,
+      retryMaxDelayMs: config.retryMaxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT_MS
+    };
+  }
+  async send(batch) {
+    if (batch.length === 0) return;
+    await this.postBatch(batch, 0);
+  }
+  async reset() {
+  }
+  async shutdown() {
+  }
+  async postBatch(batch, attempt) {
+    const controller = typeof AbortController !== "undefined" ? new AbortController() : null;
+    const timeoutId = controller ? setTimeout(() => controller.abort(), this.config.timeout) : null;
+    try {
+      const response = await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        },
+        body: JSON.stringify({
+          batch,
+          sentAt: (/* @__PURE__ */ new Date()).toISOString()
+        }),
+        signal: controller?.signal
+      });
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      if (response.ok) return;
+      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+        console.warn(
+          `[SunGlasses] HttpStorageAdapter: non-retriable error ${response.status} \u2014 batch discarded`
+        );
+        return;
+      }
+      this.scheduleRetry(batch, attempt);
+    } catch {
+      if (timeoutId !== null) clearTimeout(timeoutId);
+      this.scheduleRetry(batch, attempt);
+    }
+  }
+  scheduleRetry(batch, attempt) {
+    scheduleRetry(
+      {
+        attempt,
+        execute: () => this.postBatch(batch, attempt + 1),
+        onExhausted: () => {
+          console.warn(
+            `[SunGlasses] HttpStorageAdapter: max retries (${this.config.maxRetries}) exceeded \u2014 batch of ${batch.length} events discarded`
+          );
+        }
+      },
+      {
+        maxRetries: this.config.maxRetries,
+        baseDelayMs: this.config.retryBaseDelayMs,
+        maxDelayMs: this.config.retryMaxDelayMs
+      }
+    );
+  }
+};
+export {
+  HttpStorageAdapter,
+  scheduleRetry
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@drakkar.software/sunglasses-storage-http",
+  "version": "0.1.0",
+  "description": "Batched HTTP push analytics adapter for SunGlasses",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@drakkar.software/sunglasses-core": "0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@drakkar.software/sunglasses-tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "clean": "rm -rf dist .tsbuildinfo"
+  }
+}