@drakkar.software/sunglasses-adapter-starfish 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,108 @@
+import { IAnalyticsAdapter, StarfishAdapterConfig, SunglassesEvent, CleanupConfig } from '@drakkar.software/sunglasses-core';
+export { CleanupConfig, StarfishAdapterConfig } from '@drakkar.software/sunglasses-core';
+
+/**
+ * IAnalyticsAdapter that syncs events to a Starfish document-sync server.
+ *
+ * ## Standard mode (default)
+ * Protocol: pull → merge → push with optimistic locking.
+ * 1. GET  /pull/{path}  → { data: StarfishEventDocument, hash: string }
+ * 2. Merge incoming events into the document (dedup by messageId)
+ * 3. POST /push/{path}  → { data: updatedDoc, baseHash: hash }
+ * 4. On 409 Conflict (optimistic locking): pull again, re-merge, re-push
+ *    (iterative, not recursive, to prevent stack overflow under high contention)
+ *
+ * ## Rotating path mode (`rotatePathOnSuccess: true`)
+ * Each successful push creates a **new** Starfish document with an
+ * auto-incrementing path suffix (e.g. `events-0001`, `events-0002`…).
+ * - No pull step needed — the new document only contains this batch's events
+ * - No growing single document — each file stays small
+ * - Requires `pathStorage` in config to persist the generation counter
+ * - Combine with `enableLocalArchive: true` to keep a local copy of all events
+ *
+ * The storage path template supports `{identity}` as a placeholder, replaced
+ * with `distinctId ?? anonymousId` from the first event in the batch.
+ *
+ * @see https://github.com/Drakkar-Software/Starfish
+ */
+declare class StarfishAnalyticsAdapter implements IAnalyticsAdapter {
+    private readonly serverUrl;
+    private readonly storagePath;
+    private readonly authToken;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    private readonly rotatePathOnSuccess;
+    private readonly pathStorage;
+    constructor(config: StarfishAdapterConfig & {
+        timeoutMs?: number;
+    });
+    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Prune old events from the Starfish document after a successful flush.
+     * Called by SunglassesCore when `cleanupAfterFlush` is configured.
+     * Only applicable in standard (non-rotating) mode.
+     */
+    cleanupAfterFlush(delivered: ReadonlyArray<SunglassesEvent>, config: CleanupConfig): Promise<void>;
+    private sendMerge;
+    /**
+     * Push events to a new Starfish document each time.
+     *
+     * Path format: `{baseResolved}-{generation padded to 4 digits}`
+     * e.g. `analytics/user-1/events-0001`, `analytics/user-1/events-0002`
+     *
+     * The generation is persisted to `pathStorage` so it survives app restarts.
+     * On success: advance generation. On failure: keep current generation (retry next flush).
+     */
+    private sendRotating;
+    private loadGeneration;
+    private saveGeneration;
+    private pull;
+    private push;
+    private buildHeaders;
+}
+
+/**
+ * The document structure stored at the Starfish path.
+ * Starfish is a document-sync system; we maintain a rolling JSON document
+ * that accumulates analytics events for each identity.
+ */
+interface StarfishEventDocument {
+    /** All events recorded for this identity, ordered by timestamp. */
+    events: SunglassesEvent[];
+    /** ISO-8601 timestamp of the last document update. */
+    lastUpdated: string;
+    /** Schema version for future migrations. */
+    version: '1';
+}
+/**
+ * Creates an empty Starfish event document.
+ */
+declare function createEmptyDocument(): StarfishEventDocument;
+/**
+ * Merge new events into an existing document, de-duplicating by messageId.
+ * Remote document takes precedence for metadata fields.
+ */
+declare function mergeEvents(remote: StarfishEventDocument, incoming: ReadonlyArray<SunglassesEvent>): StarfishEventDocument;
+/**
+ * Resolve the Starfish storage path for a given identity.
+ * Replaces `{identity}` in the template with the resolved identity value.
+ *
+ * @example
+ * resolveStoragePath('analytics/{identity}/events', 'user-123')
+ * // → 'analytics/user-123/events'
+ */
+declare function resolveStoragePath(template: string, identity: string): string;
+/**
+ * Prune a Starfish event document according to cleanup configuration.
+ *
+ * Applied rules (in order):
+ * 1. Remove events older than `maxAgeMs` milliseconds.
+ * 2. If `maxEventsPerIdentity` is set (> 0), keep only the most recent N events.
+ *
+ * Returns a new document — does not mutate the input.
+ */
+declare function pruneDocument(doc: StarfishEventDocument, config: CleanupConfig): StarfishEventDocument;
+
+export { StarfishAnalyticsAdapter, type StarfishEventDocument, createEmptyDocument, mergeEvents, pruneDocument, resolveStoragePath };

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import { IAnalyticsAdapter, StarfishAdapterConfig, SunglassesEvent, CleanupConfig } from '@drakkar.software/sunglasses-core';
+export { CleanupConfig, StarfishAdapterConfig } from '@drakkar.software/sunglasses-core';
+
+/**
+ * IAnalyticsAdapter that syncs events to a Starfish document-sync server.
+ *
+ * ## Standard mode (default)
+ * Protocol: pull → merge → push with optimistic locking.
+ * 1. GET  /pull/{path}  → { data: StarfishEventDocument, hash: string }
+ * 2. Merge incoming events into the document (dedup by messageId)
+ * 3. POST /push/{path}  → { data: updatedDoc, baseHash: hash }
+ * 4. On 409 Conflict (optimistic locking): pull again, re-merge, re-push
+ *    (iterative, not recursive, to prevent stack overflow under high contention)
+ *
+ * ## Rotating path mode (`rotatePathOnSuccess: true`)
+ * Each successful push creates a **new** Starfish document with an
+ * auto-incrementing path suffix (e.g. `events-0001`, `events-0002`…).
+ * - No pull step needed — the new document only contains this batch's events
+ * - No growing single document — each file stays small
+ * - Requires `pathStorage` in config to persist the generation counter
+ * - Combine with `enableLocalArchive: true` to keep a local copy of all events
+ *
+ * The storage path template supports `{identity}` as a placeholder, replaced
+ * with `distinctId ?? anonymousId` from the first event in the batch.
+ *
+ * @see https://github.com/Drakkar-Software/Starfish
+ */
+declare class StarfishAnalyticsAdapter implements IAnalyticsAdapter {
+    private readonly serverUrl;
+    private readonly storagePath;
+    private readonly authToken;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    private readonly rotatePathOnSuccess;
+    private readonly pathStorage;
+    constructor(config: StarfishAdapterConfig & {
+        timeoutMs?: number;
+    });
+    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Prune old events from the Starfish document after a successful flush.
+     * Called by SunglassesCore when `cleanupAfterFlush` is configured.
+     * Only applicable in standard (non-rotating) mode.
+     */
+    cleanupAfterFlush(delivered: ReadonlyArray<SunglassesEvent>, config: CleanupConfig): Promise<void>;
+    private sendMerge;
+    /**
+     * Push events to a new Starfish document each time.
+     *
+     * Path format: `{baseResolved}-{generation padded to 4 digits}`
+     * e.g. `analytics/user-1/events-0001`, `analytics/user-1/events-0002`
+     *
+     * The generation is persisted to `pathStorage` so it survives app restarts.
+     * On success: advance generation. On failure: keep current generation (retry next flush).
+     */
+    private sendRotating;
+    private loadGeneration;
+    private saveGeneration;
+    private pull;
+    private push;
+    private buildHeaders;
+}
+
+/**
+ * The document structure stored at the Starfish path.
+ * Starfish is a document-sync system; we maintain a rolling JSON document
+ * that accumulates analytics events for each identity.
+ */
+interface StarfishEventDocument {
+    /** All events recorded for this identity, ordered by timestamp. */
+    events: SunglassesEvent[];
+    /** ISO-8601 timestamp of the last document update. */
+    lastUpdated: string;
+    /** Schema version for future migrations. */
+    version: '1';
+}
+/**
+ * Creates an empty Starfish event document.
+ */
+declare function createEmptyDocument(): StarfishEventDocument;
+/**
+ * Merge new events into an existing document, de-duplicating by messageId.
+ * Remote document takes precedence for metadata fields.
+ */
+declare function mergeEvents(remote: StarfishEventDocument, incoming: ReadonlyArray<SunglassesEvent>): StarfishEventDocument;
+/**
+ * Resolve the Starfish storage path for a given identity.
+ * Replaces `{identity}` in the template with the resolved identity value.
+ *
+ * @example
+ * resolveStoragePath('analytics/{identity}/events', 'user-123')
+ * // → 'analytics/user-123/events'
+ */
+declare function resolveStoragePath(template: string, identity: string): string;
+/**
+ * Prune a Starfish event document according to cleanup configuration.
+ *
+ * Applied rules (in order):
+ * 1. Remove events older than `maxAgeMs` milliseconds.
+ * 2. If `maxEventsPerIdentity` is set (> 0), keep only the most recent N events.
+ *
+ * Returns a new document — does not mutate the input.
+ */
+declare function pruneDocument(doc: StarfishEventDocument, config: CleanupConfig): StarfishEventDocument;
+
+export { StarfishAnalyticsAdapter, type StarfishEventDocument, createEmptyDocument, mergeEvents, pruneDocument, resolveStoragePath };

package/dist/index.js

@@ -0,0 +1,278 @@
+"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, {
+  StarfishAnalyticsAdapter: () => StarfishAnalyticsAdapter,
+  createEmptyDocument: () => createEmptyDocument,
+  mergeEvents: () => mergeEvents,
+  pruneDocument: () => pruneDocument,
+  resolveStoragePath: () => resolveStoragePath
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/StarfishEventMapper.ts
+function createEmptyDocument() {
+  return {
+    events: [],
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+    version: "1"
+  };
+}
+function mergeEvents(remote, incoming) {
+  const existingIds = new Set(remote.events.map((e) => e.messageId));
+  const newEvents = incoming.filter((e) => !existingIds.has(e.messageId));
+  return {
+    ...remote,
+    events: [...remote.events, ...newEvents],
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function resolveStoragePath(template, identity) {
+  return template.replace("{identity}", encodeURIComponent(identity));
+}
+function pruneDocument(doc, config) {
+  let events = [...doc.events];
+  if (config.maxAgeMs !== void 0 && config.maxAgeMs > 0) {
+    const cutoff = Date.now() - config.maxAgeMs;
+    events = events.filter((e) => {
+      const ts = new Date(e.timestamp).getTime();
+      return !Number.isNaN(ts) && ts >= cutoff;
+    });
+  }
+  const maxN = config.maxEventsPerIdentity ?? 0;
+  if (maxN > 0 && events.length > maxN) {
+    events = events.slice(events.length - maxN);
+  }
+  return {
+    ...doc,
+    events,
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/StarfishAnalyticsAdapter.ts
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+var GEN_KEY_PREFIX = "sunglasses:starfish:gen:";
+var StarfishAnalyticsAdapter = class {
+  constructor(config) {
+    this.serverUrl = config.serverUrl.replace(/\/$/, "");
+    this.storagePath = config.storagePath;
+    this.authToken = config.authToken ?? "";
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.rotatePathOnSuccess = config.rotatePathOnSuccess ?? false;
+    this.pathStorage = config.pathStorage ?? null;
+    if (this.rotatePathOnSuccess && !this.pathStorage) {
+      console.warn(
+        "[SunGlasses] StarfishAnalyticsAdapter: rotatePathOnSuccess requires pathStorage \u2014 falling back to standard mode"
+      );
+    }
+  }
+  async send(batch) {
+    if (batch.length === 0) return;
+    const identity = batch[0].distinctId || batch[0].anonymousId;
+    if (batch.some((e) => (e.distinctId || e.anonymousId) !== identity)) {
+      console.warn(
+        "[SunGlasses] StarfishAnalyticsAdapter: batch contains events from multiple identities \u2014 all events will be written to the document for the first identity. This is unexpected."
+      );
+    }
+    const baseResolved = resolveStoragePath(this.storagePath, identity);
+    if (this.rotatePathOnSuccess && this.pathStorage) {
+      return this.sendRotating(batch, identity, baseResolved);
+    }
+    return this.sendMerge(batch, baseResolved);
+  }
+  async reset() {
+  }
+  async shutdown() {
+  }
+  /**
+   * Prune old events from the Starfish document after a successful flush.
+   * Called by SunglassesCore when `cleanupAfterFlush` is configured.
+   * Only applicable in standard (non-rotating) mode.
+   */
+  async cleanupAfterFlush(delivered, config) {
+    if (delivered.length === 0) return;
+    if (this.rotatePathOnSuccess) return;
+    const identity = delivered[0].distinctId || delivered[0].anonymousId;
+    const path = resolveStoragePath(this.storagePath, identity);
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const pulled = await this.pull(path);
+        if (!pulled) return;
+        const pruned = pruneDocument(pulled.data, config);
+        const pushResponse = await this.push(path, pruned, pulled.hash);
+        if (pushResponse.status === 409) {
+          continue;
+        }
+        return;
+      } catch {
+        if (attempt === this.maxRetries - 1) {
+          console.warn(
+            "[SunGlasses] StarfishAnalyticsAdapter: cleanup failed \u2014 will retry on next flush"
+          );
+        }
+      }
+    }
+  }
+  // ── Private: standard pull-merge-push ──────────────────────────────────────
+  async sendMerge(batch, path) {
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const pulled = await this.pull(path);
+        const currentDoc = pulled?.data ?? createEmptyDocument();
+        const baseHash = pulled?.hash ?? "";
+        const updatedDoc = mergeEvents(currentDoc, batch);
+        const pushResponse = await this.push(path, updatedDoc, baseHash);
+        if (pushResponse.status === 409) {
+          continue;
+        }
+        if (!pushResponse.ok) {
+          console.warn(
+            `[SunGlasses] StarfishAnalyticsAdapter: push failed with status ${pushResponse.status} \u2014 batch discarded`
+          );
+        }
+        return;
+      } catch (err) {
+        const isLastAttempt = attempt === this.maxRetries - 1;
+        if (isLastAttempt) {
+          console.warn(
+            `[SunGlasses] StarfishAnalyticsAdapter: network error after ${this.maxRetries} attempts \u2014 batch discarded`,
+            err
+          );
+          return;
+        }
+      }
+    }
+    console.warn(
+      `[SunGlasses] StarfishAnalyticsAdapter: max retries (${this.maxRetries}) exceeded for path "${path}" \u2014 batch discarded`
+    );
+  }
+  // ── Private: rotating path mode ────────────────────────────────────────────
+  /**
+   * Push events to a new Starfish document each time.
+   *
+   * Path format: `{baseResolved}-{generation padded to 4 digits}`
+   * e.g. `analytics/user-1/events-0001`, `analytics/user-1/events-0002`
+   *
+   * The generation is persisted to `pathStorage` so it survives app restarts.
+   * On success: advance generation. On failure: keep current generation (retry next flush).
+   */
+  async sendRotating(batch, identity, baseResolved) {
+    const gen = await this.loadGeneration(identity);
+    const path = `${baseResolved}-${String(gen).padStart(4, "0")}`;
+    const doc = mergeEvents(createEmptyDocument(), batch);
+    try {
+      const response = await this.push(path, doc, "");
+      if (response.ok) {
+        await this.saveGeneration(identity, gen + 1);
+      } else if (response.status === 409) {
+        await this.saveGeneration(identity, gen + 1);
+        throw new Error(
+          `[SunGlasses] StarfishAnalyticsAdapter: 409 conflict at rotating path "${path}" \u2014 generation advanced, will retry`
+        );
+      } else {
+        console.warn(
+          `[SunGlasses] StarfishAnalyticsAdapter: rotating push failed with status ${response.status} for path "${path}"`
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `[SunGlasses] StarfishAnalyticsAdapter: rotating push network error for path "${path}"`,
+        err
+      );
+    }
+  }
+  async loadGeneration(identity) {
+    if (!this.pathStorage) return 0;
+    try {
+      const raw = await this.pathStorage.read(`${GEN_KEY_PREFIX}${identity}`);
+      return raw !== null ? parseInt(raw, 10) : 0;
+    } catch {
+      return 0;
+    }
+  }
+  async saveGeneration(identity, gen) {
+    if (!this.pathStorage) return;
+    try {
+      await this.pathStorage.write(`${GEN_KEY_PREFIX}${identity}`, String(gen));
+    } catch (err) {
+      console.warn("[SunGlasses] StarfishAnalyticsAdapter: failed to save generation counter", err);
+    }
+  }
+  // ── Private: HTTP helpers ──────────────────────────────────────────────────
+  async pull(path) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await fetch(`${this.serverUrl}/pull/${path}`, {
+        method: "GET",
+        headers: this.buildHeaders(),
+        signal: controller.signal
+      });
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        throw new Error(`Starfish pull failed: ${response.status}`);
+      }
+      return response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async push(path, doc, baseHash) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(`${this.serverUrl}/push/${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.buildHeaders()
+        },
+        body: JSON.stringify({
+          data: doc,
+          baseHash: baseHash || void 0
+        }),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  buildHeaders() {
+    const headers = {};
+    if (this.authToken) {
+      headers["Authorization"] = `Bearer ${this.authToken}`;
+    }
+    return headers;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StarfishAnalyticsAdapter,
+  createEmptyDocument,
+  mergeEvents,
+  pruneDocument,
+  resolveStoragePath
+});

package/dist/index.mjs

@@ -0,0 +1,247 @@
+// src/StarfishEventMapper.ts
+function createEmptyDocument() {
+  return {
+    events: [],
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+    version: "1"
+  };
+}
+function mergeEvents(remote, incoming) {
+  const existingIds = new Set(remote.events.map((e) => e.messageId));
+  const newEvents = incoming.filter((e) => !existingIds.has(e.messageId));
+  return {
+    ...remote,
+    events: [...remote.events, ...newEvents],
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function resolveStoragePath(template, identity) {
+  return template.replace("{identity}", encodeURIComponent(identity));
+}
+function pruneDocument(doc, config) {
+  let events = [...doc.events];
+  if (config.maxAgeMs !== void 0 && config.maxAgeMs > 0) {
+    const cutoff = Date.now() - config.maxAgeMs;
+    events = events.filter((e) => {
+      const ts = new Date(e.timestamp).getTime();
+      return !Number.isNaN(ts) && ts >= cutoff;
+    });
+  }
+  const maxN = config.maxEventsPerIdentity ?? 0;
+  if (maxN > 0 && events.length > maxN) {
+    events = events.slice(events.length - maxN);
+  }
+  return {
+    ...doc,
+    events,
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/StarfishAnalyticsAdapter.ts
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+var GEN_KEY_PREFIX = "sunglasses:starfish:gen:";
+var StarfishAnalyticsAdapter = class {
+  constructor(config) {
+    this.serverUrl = config.serverUrl.replace(/\/$/, "");
+    this.storagePath = config.storagePath;
+    this.authToken = config.authToken ?? "";
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.rotatePathOnSuccess = config.rotatePathOnSuccess ?? false;
+    this.pathStorage = config.pathStorage ?? null;
+    if (this.rotatePathOnSuccess && !this.pathStorage) {
+      console.warn(
+        "[SunGlasses] StarfishAnalyticsAdapter: rotatePathOnSuccess requires pathStorage \u2014 falling back to standard mode"
+      );
+    }
+  }
+  async send(batch) {
+    if (batch.length === 0) return;
+    const identity = batch[0].distinctId || batch[0].anonymousId;
+    if (batch.some((e) => (e.distinctId || e.anonymousId) !== identity)) {
+      console.warn(
+        "[SunGlasses] StarfishAnalyticsAdapter: batch contains events from multiple identities \u2014 all events will be written to the document for the first identity. This is unexpected."
+      );
+    }
+    const baseResolved = resolveStoragePath(this.storagePath, identity);
+    if (this.rotatePathOnSuccess && this.pathStorage) {
+      return this.sendRotating(batch, identity, baseResolved);
+    }
+    return this.sendMerge(batch, baseResolved);
+  }
+  async reset() {
+  }
+  async shutdown() {
+  }
+  /**
+   * Prune old events from the Starfish document after a successful flush.
+   * Called by SunglassesCore when `cleanupAfterFlush` is configured.
+   * Only applicable in standard (non-rotating) mode.
+   */
+  async cleanupAfterFlush(delivered, config) {
+    if (delivered.length === 0) return;
+    if (this.rotatePathOnSuccess) return;
+    const identity = delivered[0].distinctId || delivered[0].anonymousId;
+    const path = resolveStoragePath(this.storagePath, identity);
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const pulled = await this.pull(path);
+        if (!pulled) return;
+        const pruned = pruneDocument(pulled.data, config);
+        const pushResponse = await this.push(path, pruned, pulled.hash);
+        if (pushResponse.status === 409) {
+          continue;
+        }
+        return;
+      } catch {
+        if (attempt === this.maxRetries - 1) {
+          console.warn(
+            "[SunGlasses] StarfishAnalyticsAdapter: cleanup failed \u2014 will retry on next flush"
+          );
+        }
+      }
+    }
+  }
+  // ── Private: standard pull-merge-push ──────────────────────────────────────
+  async sendMerge(batch, path) {
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const pulled = await this.pull(path);
+        const currentDoc = pulled?.data ?? createEmptyDocument();
+        const baseHash = pulled?.hash ?? "";
+        const updatedDoc = mergeEvents(currentDoc, batch);
+        const pushResponse = await this.push(path, updatedDoc, baseHash);
+        if (pushResponse.status === 409) {
+          continue;
+        }
+        if (!pushResponse.ok) {
+          console.warn(
+            `[SunGlasses] StarfishAnalyticsAdapter: push failed with status ${pushResponse.status} \u2014 batch discarded`
+          );
+        }
+        return;
+      } catch (err) {
+        const isLastAttempt = attempt === this.maxRetries - 1;
+        if (isLastAttempt) {
+          console.warn(
+            `[SunGlasses] StarfishAnalyticsAdapter: network error after ${this.maxRetries} attempts \u2014 batch discarded`,
+            err
+          );
+          return;
+        }
+      }
+    }
+    console.warn(
+      `[SunGlasses] StarfishAnalyticsAdapter: max retries (${this.maxRetries}) exceeded for path "${path}" \u2014 batch discarded`
+    );
+  }
+  // ── Private: rotating path mode ────────────────────────────────────────────
+  /**
+   * Push events to a new Starfish document each time.
+   *
+   * Path format: `{baseResolved}-{generation padded to 4 digits}`
+   * e.g. `analytics/user-1/events-0001`, `analytics/user-1/events-0002`
+   *
+   * The generation is persisted to `pathStorage` so it survives app restarts.
+   * On success: advance generation. On failure: keep current generation (retry next flush).
+   */
+  async sendRotating(batch, identity, baseResolved) {
+    const gen = await this.loadGeneration(identity);
+    const path = `${baseResolved}-${String(gen).padStart(4, "0")}`;
+    const doc = mergeEvents(createEmptyDocument(), batch);
+    try {
+      const response = await this.push(path, doc, "");
+      if (response.ok) {
+        await this.saveGeneration(identity, gen + 1);
+      } else if (response.status === 409) {
+        await this.saveGeneration(identity, gen + 1);
+        throw new Error(
+          `[SunGlasses] StarfishAnalyticsAdapter: 409 conflict at rotating path "${path}" \u2014 generation advanced, will retry`
+        );
+      } else {
+        console.warn(
+          `[SunGlasses] StarfishAnalyticsAdapter: rotating push failed with status ${response.status} for path "${path}"`
+        );
+      }
+    } catch (err) {
+      console.warn(
+        `[SunGlasses] StarfishAnalyticsAdapter: rotating push network error for path "${path}"`,
+        err
+      );
+    }
+  }
+  async loadGeneration(identity) {
+    if (!this.pathStorage) return 0;
+    try {
+      const raw = await this.pathStorage.read(`${GEN_KEY_PREFIX}${identity}`);
+      return raw !== null ? parseInt(raw, 10) : 0;
+    } catch {
+      return 0;
+    }
+  }
+  async saveGeneration(identity, gen) {
+    if (!this.pathStorage) return;
+    try {
+      await this.pathStorage.write(`${GEN_KEY_PREFIX}${identity}`, String(gen));
+    } catch (err) {
+      console.warn("[SunGlasses] StarfishAnalyticsAdapter: failed to save generation counter", err);
+    }
+  }
+  // ── Private: HTTP helpers ──────────────────────────────────────────────────
+  async pull(path) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await fetch(`${this.serverUrl}/pull/${path}`, {
+        method: "GET",
+        headers: this.buildHeaders(),
+        signal: controller.signal
+      });
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        throw new Error(`Starfish pull failed: ${response.status}`);
+      }
+      return response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async push(path, doc, baseHash) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(`${this.serverUrl}/push/${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.buildHeaders()
+        },
+        body: JSON.stringify({
+          data: doc,
+          baseHash: baseHash || void 0
+        }),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  buildHeaders() {
+    const headers = {};
+    if (this.authToken) {
+      headers["Authorization"] = `Bearer ${this.authToken}`;
+    }
+    return headers;
+  }
+};
+export {
+  StarfishAnalyticsAdapter,
+  createEmptyDocument,
+  mergeEvents,
+  pruneDocument,
+  resolveStoragePath
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@drakkar.software/sunglasses-adapter-starfish",
+  "version": "0.1.0",
+  "description": "Starfish document-sync adapter for SunGlasses (Drakkar-Software/Starfish)",
+  "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"
+  }
+}