@drakkar.software/sunglasses-adapter-starfish 0.6.0 → 0.8.0

package/dist/index.d.mts

@@ -1,120 +1,161 @@
-import { IAnalyticsAdapter, StarfishAdapterConfig, SunglassesEvent, CleanupConfig } from '@drakkar.software/sunglasses-core';
-export { CleanupConfig, StarfishAdapterConfig } from '@drakkar.software/sunglasses-core';
+import { IAnalyticsAdapter, SunglassesEvent } from '@drakkar.software/sunglasses-core';
 
 /**
- * IAnalyticsAdapter that syncs events to a Starfish document-sync server.
+ * SunGlasses → Starfish analytics adapter.
  *
- * ## 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)
+ * Implements `IAnalyticsAdapter`: on each flush, maps the event batch to flat
+ * rows and pushes them as a JSON body to a Starfish events collection.
+ * The `starfish-events` server plugin intercepts the push and encodes Parquet
+ * on the server side — no Parquet dependency on the client.
  *
- * ## Push-only mode (`pushOnly: true`)
- * Skips the pull step entirely — events are pushed as a fresh document each time.
- * Use for Starfish collections with `queueOnly: true` where pull always returns
- * empty data and optimistic locking is not needed.
- * On failure the adapter throws, keeping events in the local queue for retry.
+ * ## Transport
  *
- * ## 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
+ * Uses an injected `StarfishPushClient` (structural type) so this package has
+ * **no runtime dependency on `@drakkar.software/starfish-client`** — avoiding
+ * an ESM-only/unpublished-alpha dep conflict. Construct a real `StarfishClient`
+ * externally and pass it in via `config.client`.
  *
- * The storage path template supports `{identity}` as a placeholder, replaced
- * with `distinctId ?? anonymousId` from the first event in the batch.
+ * ## At-least-once delivery
  *
- * @see https://github.com/Drakkar-Software/Starfish
+ * `send()` throws on failure. SunglassesCore treats an adapter throw as a
+ * transient error and keeps the batch in the local queue for the next flush
+ * cycle — equivalent to the old `pushOnly` semantics.
+ *
+ * ## Privacy
+ *
+ * The SDK's consent gate and PiiSanitizer have already run before `send()` is
+ * called. This adapter must never log `distinct_id`, `properties`, or `context`
+ * (log counts only).
  */
-declare class StarfishAnalyticsAdapter implements IAnalyticsAdapter {
-    private readonly serverUrl;
-    private readonly storagePath;
-    private readonly authToken;
-    private readonly maxRetries;
-    private readonly timeoutMs;
-    private readonly pushOnly;
-    private readonly rotatePathOnSuccess;
-    private readonly pathStorage;
-    constructor(config: StarfishAdapterConfig & {
-        timeoutMs?: number;
-    });
-    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
-    reset(): Promise<void>;
-    shutdown(): Promise<void>;
+
+/**
+ * Minimal structural interface satisfied by `StarfishClient.push`.
+ * Declare it here so no import of `@drakkar.software/starfish-client` is needed.
+ */
+interface StarfishPushClient {
     /**
-     * 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.
+     * Push a JSON document to a Starfish collection path.
+     * Must throw (or reject) on non-2xx so SunglassesCore retries.
+     *
+     * @param path  Logical storage path (without the `/push/` prefix).
+     * @param data  Document body — `{ events: StarfishEventRow[] }`.
+     * @param baseHash  Pass `null` for "must not exist" (unique path per batch).
      */
-    cleanupAfterFlush(delivered: ReadonlyArray<SunglassesEvent>, config: CleanupConfig): Promise<void>;
-    private sendMerge;
+    push(path: string, data: unknown, baseHash: string | null): Promise<unknown>;
+}
+/** Configuration for {@link StarfishAnalyticsAdapter}. */
+interface StarfishAdapterConfig {
     /**
-     * Push a fresh document directly, no pull, no merge, no conflict detection.
-     * Throws on failure so SunglassesCore keeps events in queue for retry.
+     * A `StarfishClient` instance (or any object implementing `push`).
+     * Construct it with `{ baseUrl: "https://..." }` and no `capProvider` when
+     * targeting a `write: "public"` collection.
+     *
+     * @example
+     * ```ts
+     * import { StarfishClient } from "@drakkar.software/starfish-client"
+     * const client = new StarfishClient({ baseUrl: "https://sync.example.com/v1" })
+     * new StarfishAnalyticsAdapter({ client, app: "my-app" })
+     * ```
      */
-    private sendPushOnly;
+    client: StarfishPushClient;
     /**
-     * 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`
+     * Application/workspace identifier embedded in the storage path.
+     * Fills the `{app}` placeholder in `pathTemplate`.
+     * Keep it short and URL-safe (no `/` or spaces).
+     */
+    app: string;
+    /**
+     * Storage-path template. Defaults to `"events/{app}/{batchId}"`.
+     * `{app}` → `config.app`; `{batchId}` → a UUID v4 generated per flush.
      *
-     * The generation is persisted to `pathStorage` so it survives app restarts.
-     * On success: advance generation. On failure: keep current generation (retry next flush).
+     * The server plugin appends `.parquet` automatically, so omit it here.
      */
-    private sendRotating;
-    private loadGeneration;
-    private saveGeneration;
-    private pull;
-    private push;
-    private buildHeaders;
+    pathTemplate?: string;
 }
-
 /**
- * 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.
+ * SunGlasses analytics adapter that delivers event batches to a Starfish
+ * events collection, where the `starfish-events` plugin encodes them as
+ * Parquet and writes to S3.
+ *
+ * @example
+ * ```ts
+ * import { SunglassesCore } from "@drakkar.software/sunglasses-core"
+ * import { StarfishAnalyticsAdapter } from "@drakkar.software/sunglasses-adapter-starfish"
+ * import { StarfishClient } from "@drakkar.software/starfish-client"
+ *
+ * const sfClient = new StarfishClient({ baseUrl: "https://sync.example.com/v1" })
+ *
+ * const sg = await SunglassesCore.create({
+ *   storage: myStorage,
+ *   adapters: [
+ *     new StarfishAnalyticsAdapter({ client: sfClient, app: "my-app" }),
+ *   ],
+ * })
+ * ```
  */
-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';
+declare class StarfishAnalyticsAdapter implements IAnalyticsAdapter {
+    private readonly client;
+    private readonly app;
+    private readonly pathTemplate;
+    constructor(config: StarfishAdapterConfig);
+    private resolvePath;
+    /**
+     * Push a batch of events to the Starfish events collection.
+     *
+     * A unique `batchId` is generated per call, producing a unique storage path
+     * (one Parquet file per flush). `baseHash: null` signals "must not exist" to
+     * Starfish, ensuring no conflict on the unique path.
+     *
+     * Throws on failure — SunglassesCore keeps the batch in the local queue.
+     * Never logs event contents (distinct_id, properties, context).
+     */
+    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
 }
+
 /**
- * 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.
+ * Mapping utilities: SunglassesEvent → the flat EventRow shape that
+ * the starfish-events server plugin expects and encodes as Parquet columns.
+ *
+ * The column schema matches apps/ingest-server/src/schema.ts so a DuckDB
+ * query is identical regardless of which backend delivered the data.
+ *
+ * Privacy: distinct_id, properties, and context are mapped but must never
+ * be logged (they are opaque values that the SDK's PiiSanitizer already
+ * processed before the batch was handed to the adapter).
  */
-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'
+ * Flat row shape sent to the Starfish events collection.
+ * All fields are strings; properties and context are JSON-serialized.
  */
-declare function resolveStoragePath(template: string, identity: string): string;
+interface StarfishEventRow {
+    /** EventType: 'capture' | 'screen' | 'identify' | 'alias' | 'group' */
+    event_type: string;
+    /** Human-readable event name, e.g. 'button_clicked' or '$screen'. */
+    event: string;
+    /** Resolved user identifier (hashed if anonymizeUserId is set). */
+    distinct_id: string;
+    /** Stable device UUID — safe for DAU / retention analysis. */
+    anonymous_id: string;
+    /** ISO-8601 UTC event timestamp. */
+    ts: string;
+    /** UUID v4 — use for deduplication. */
+    message_id: string;
+    /** JSON-serialized event properties (already PII-sanitized by the SDK). */
+    properties: string;
+    /** JSON-serialized EventContext (library/platform/app metadata). */
+    context: string;
+    /** 'YYYY-MM-DD' derived from ts — matches the Parquet partition key. */
+    dt: 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.
+ * Map a single SunglassesEvent to the flat row format expected by the
+ * starfish-events plugin.
  *
- * Returns a new document — does not mutate the input.
+ * `received_at` is intentionally omitted — the server plugin stamps it at
+ * ingest time so it reflects when the event landed on the server, not when
+ * the client serialised the batch.
  */
-declare function pruneDocument(doc: StarfishEventDocument, config: CleanupConfig): StarfishEventDocument;
+declare function toStarfishRow(e: SunglassesEvent): StarfishEventRow;
 
-export { StarfishAnalyticsAdapter, type StarfishEventDocument, createEmptyDocument, mergeEvents, pruneDocument, resolveStoragePath };
+export { type StarfishAdapterConfig, StarfishAnalyticsAdapter, type StarfishEventRow, type StarfishPushClient, toStarfishRow };

package/dist/index.d.ts

@@ -1,120 +1,161 @@
-import { IAnalyticsAdapter, StarfishAdapterConfig, SunglassesEvent, CleanupConfig } from '@drakkar.software/sunglasses-core';
-export { CleanupConfig, StarfishAdapterConfig } from '@drakkar.software/sunglasses-core';
+import { IAnalyticsAdapter, SunglassesEvent } from '@drakkar.software/sunglasses-core';
 
 /**
- * IAnalyticsAdapter that syncs events to a Starfish document-sync server.
+ * SunGlasses → Starfish analytics adapter.
  *
- * ## 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)
+ * Implements `IAnalyticsAdapter`: on each flush, maps the event batch to flat
+ * rows and pushes them as a JSON body to a Starfish events collection.
+ * The `starfish-events` server plugin intercepts the push and encodes Parquet
+ * on the server side — no Parquet dependency on the client.
  *
- * ## Push-only mode (`pushOnly: true`)
- * Skips the pull step entirely — events are pushed as a fresh document each time.
- * Use for Starfish collections with `queueOnly: true` where pull always returns
- * empty data and optimistic locking is not needed.
- * On failure the adapter throws, keeping events in the local queue for retry.
+ * ## Transport
  *
- * ## 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
+ * Uses an injected `StarfishPushClient` (structural type) so this package has
+ * **no runtime dependency on `@drakkar.software/starfish-client`** — avoiding
+ * an ESM-only/unpublished-alpha dep conflict. Construct a real `StarfishClient`
+ * externally and pass it in via `config.client`.
  *
- * The storage path template supports `{identity}` as a placeholder, replaced
- * with `distinctId ?? anonymousId` from the first event in the batch.
+ * ## At-least-once delivery
  *
- * @see https://github.com/Drakkar-Software/Starfish
+ * `send()` throws on failure. SunglassesCore treats an adapter throw as a
+ * transient error and keeps the batch in the local queue for the next flush
+ * cycle — equivalent to the old `pushOnly` semantics.
+ *
+ * ## Privacy
+ *
+ * The SDK's consent gate and PiiSanitizer have already run before `send()` is
+ * called. This adapter must never log `distinct_id`, `properties`, or `context`
+ * (log counts only).
  */
-declare class StarfishAnalyticsAdapter implements IAnalyticsAdapter {
-    private readonly serverUrl;
-    private readonly storagePath;
-    private readonly authToken;
-    private readonly maxRetries;
-    private readonly timeoutMs;
-    private readonly pushOnly;
-    private readonly rotatePathOnSuccess;
-    private readonly pathStorage;
-    constructor(config: StarfishAdapterConfig & {
-        timeoutMs?: number;
-    });
-    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
-    reset(): Promise<void>;
-    shutdown(): Promise<void>;
+
+/**
+ * Minimal structural interface satisfied by `StarfishClient.push`.
+ * Declare it here so no import of `@drakkar.software/starfish-client` is needed.
+ */
+interface StarfishPushClient {
     /**
-     * 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.
+     * Push a JSON document to a Starfish collection path.
+     * Must throw (or reject) on non-2xx so SunglassesCore retries.
+     *
+     * @param path  Logical storage path (without the `/push/` prefix).
+     * @param data  Document body — `{ events: StarfishEventRow[] }`.
+     * @param baseHash  Pass `null` for "must not exist" (unique path per batch).
      */
-    cleanupAfterFlush(delivered: ReadonlyArray<SunglassesEvent>, config: CleanupConfig): Promise<void>;
-    private sendMerge;
+    push(path: string, data: unknown, baseHash: string | null): Promise<unknown>;
+}
+/** Configuration for {@link StarfishAnalyticsAdapter}. */
+interface StarfishAdapterConfig {
     /**
-     * Push a fresh document directly, no pull, no merge, no conflict detection.
-     * Throws on failure so SunglassesCore keeps events in queue for retry.
+     * A `StarfishClient` instance (or any object implementing `push`).
+     * Construct it with `{ baseUrl: "https://..." }` and no `capProvider` when
+     * targeting a `write: "public"` collection.
+     *
+     * @example
+     * ```ts
+     * import { StarfishClient } from "@drakkar.software/starfish-client"
+     * const client = new StarfishClient({ baseUrl: "https://sync.example.com/v1" })
+     * new StarfishAnalyticsAdapter({ client, app: "my-app" })
+     * ```
      */
-    private sendPushOnly;
+    client: StarfishPushClient;
     /**
-     * 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`
+     * Application/workspace identifier embedded in the storage path.
+     * Fills the `{app}` placeholder in `pathTemplate`.
+     * Keep it short and URL-safe (no `/` or spaces).
+     */
+    app: string;
+    /**
+     * Storage-path template. Defaults to `"events/{app}/{batchId}"`.
+     * `{app}` → `config.app`; `{batchId}` → a UUID v4 generated per flush.
      *
-     * The generation is persisted to `pathStorage` so it survives app restarts.
-     * On success: advance generation. On failure: keep current generation (retry next flush).
+     * The server plugin appends `.parquet` automatically, so omit it here.
      */
-    private sendRotating;
-    private loadGeneration;
-    private saveGeneration;
-    private pull;
-    private push;
-    private buildHeaders;
+    pathTemplate?: string;
 }
-
 /**
- * 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.
+ * SunGlasses analytics adapter that delivers event batches to a Starfish
+ * events collection, where the `starfish-events` plugin encodes them as
+ * Parquet and writes to S3.
+ *
+ * @example
+ * ```ts
+ * import { SunglassesCore } from "@drakkar.software/sunglasses-core"
+ * import { StarfishAnalyticsAdapter } from "@drakkar.software/sunglasses-adapter-starfish"
+ * import { StarfishClient } from "@drakkar.software/starfish-client"
+ *
+ * const sfClient = new StarfishClient({ baseUrl: "https://sync.example.com/v1" })
+ *
+ * const sg = await SunglassesCore.create({
+ *   storage: myStorage,
+ *   adapters: [
+ *     new StarfishAnalyticsAdapter({ client: sfClient, app: "my-app" }),
+ *   ],
+ * })
+ * ```
  */
-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';
+declare class StarfishAnalyticsAdapter implements IAnalyticsAdapter {
+    private readonly client;
+    private readonly app;
+    private readonly pathTemplate;
+    constructor(config: StarfishAdapterConfig);
+    private resolvePath;
+    /**
+     * Push a batch of events to the Starfish events collection.
+     *
+     * A unique `batchId` is generated per call, producing a unique storage path
+     * (one Parquet file per flush). `baseHash: null` signals "must not exist" to
+     * Starfish, ensuring no conflict on the unique path.
+     *
+     * Throws on failure — SunglassesCore keeps the batch in the local queue.
+     * Never logs event contents (distinct_id, properties, context).
+     */
+    send(batch: ReadonlyArray<SunglassesEvent>): Promise<void>;
 }
+
 /**
- * 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.
+ * Mapping utilities: SunglassesEvent → the flat EventRow shape that
+ * the starfish-events server plugin expects and encodes as Parquet columns.
+ *
+ * The column schema matches apps/ingest-server/src/schema.ts so a DuckDB
+ * query is identical regardless of which backend delivered the data.
+ *
+ * Privacy: distinct_id, properties, and context are mapped but must never
+ * be logged (they are opaque values that the SDK's PiiSanitizer already
+ * processed before the batch was handed to the adapter).
  */
-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'
+ * Flat row shape sent to the Starfish events collection.
+ * All fields are strings; properties and context are JSON-serialized.
  */
-declare function resolveStoragePath(template: string, identity: string): string;
+interface StarfishEventRow {
+    /** EventType: 'capture' | 'screen' | 'identify' | 'alias' | 'group' */
+    event_type: string;
+    /** Human-readable event name, e.g. 'button_clicked' or '$screen'. */
+    event: string;
+    /** Resolved user identifier (hashed if anonymizeUserId is set). */
+    distinct_id: string;
+    /** Stable device UUID — safe for DAU / retention analysis. */
+    anonymous_id: string;
+    /** ISO-8601 UTC event timestamp. */
+    ts: string;
+    /** UUID v4 — use for deduplication. */
+    message_id: string;
+    /** JSON-serialized event properties (already PII-sanitized by the SDK). */
+    properties: string;
+    /** JSON-serialized EventContext (library/platform/app metadata). */
+    context: string;
+    /** 'YYYY-MM-DD' derived from ts — matches the Parquet partition key. */
+    dt: 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.
+ * Map a single SunglassesEvent to the flat row format expected by the
+ * starfish-events plugin.
  *
- * Returns a new document — does not mutate the input.
+ * `received_at` is intentionally omitted — the server plugin stamps it at
+ * ingest time so it reflects when the event landed on the server, not when
+ * the client serialised the batch.
  */
-declare function pruneDocument(doc: StarfishEventDocument, config: CleanupConfig): StarfishEventDocument;
+declare function toStarfishRow(e: SunglassesEvent): StarfishEventRow;
 
-export { StarfishAnalyticsAdapter, type StarfishEventDocument, createEmptyDocument, mergeEvents, pruneDocument, resolveStoragePath };
+export { type StarfishAdapterConfig, StarfishAnalyticsAdapter, type StarfishEventRow, type StarfishPushClient, toStarfishRow };

package/dist/index.js

@@ -21,276 +21,59 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   StarfishAnalyticsAdapter: () => StarfishAnalyticsAdapter,
-  createEmptyDocument: () => createEmptyDocument,
-  mergeEvents: () => mergeEvents,
-  pruneDocument: () => pruneDocument,
-  resolveStoragePath: () => resolveStoragePath
+  toStarfishRow: () => toStarfishRow
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/StarfishAnalyticsAdapter.ts
+var import_sunglasses_core = require("@drakkar.software/sunglasses-core");
+
 // 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));
+function toStarfishRow(e) {
   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()
+    event_type: e.type,
+    event: e.event,
+    distinct_id: e.distinctId,
+    anonymous_id: e.anonymousId,
+    ts: e.timestamp,
+    message_id: e.messageId,
+    properties: JSON.stringify(e.properties),
+    context: JSON.stringify(e.context),
+    dt: e.timestamp.slice(0, 10)
   };
 }
 
 // src/StarfishAnalyticsAdapter.ts
-var DEFAULT_MAX_RETRIES = 3;
-var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
-var GEN_KEY_PREFIX = "sg:starfish:gen:";
+var DEFAULT_PATH_TEMPLATE = "events/{app}/{batchId}";
 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.pushOnly = config.pushOnly ?? false;
-    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.pushOnly) {
-      return this.sendPushOnly(batch, baseResolved);
-    }
-    if (this.rotatePathOnSuccess && this.pathStorage) {
-      return this.sendRotating(batch, identity, baseResolved);
-    }
-    return this.sendMerge(batch, baseResolved);
-  }
-  async reset() {
+    this.client = config.client;
+    this.app = config.app;
+    this.pathTemplate = config.pathTemplate ?? DEFAULT_PATH_TEMPLATE;
   }
-  async shutdown() {
+  resolvePath(batchId) {
+    return this.pathTemplate.replace("{app}", encodeURIComponent(this.app)).replace("{batchId}", batchId);
   }
   /**
-   * 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: push-only mode (queueOnly collections) ──────────────────────
-  /**
-   * Push a fresh document directly, no pull, no merge, no conflict detection.
-   * Throws on failure so SunglassesCore keeps events in queue for retry.
-   */
-  async sendPushOnly(batch, path) {
-    const doc = mergeEvents(createEmptyDocument(), batch);
-    const response = await this.push(path, doc, "");
-    if (!response.ok) {
-      throw new Error(
-        `[SunGlasses] StarfishAnalyticsAdapter: push-only push failed with status ${response.status} for path "${path}"`
-      );
-    }
-  }
-  // ── Private: rotating path mode ────────────────────────────────────────────
-  /**
-   * Push events to a new Starfish document each time.
+   * Push a batch of events to the Starfish events collection.
    *
-   * Path format: `{baseResolved}-{generation padded to 4 digits}`
-   * e.g. `analytics/user-1/events-0001`, `analytics/user-1/events-0002`
+   * A unique `batchId` is generated per call, producing a unique storage path
+   * (one Parquet file per flush). `baseHash: null` signals "must not exist" to
+   * Starfish, ensuring no conflict on the unique path.
    *
-   * The generation is persisted to `pathStorage` so it survives app restarts.
-   * On success: advance generation. On failure: keep current generation (retry next flush).
+   * Throws on failure — SunglassesCore keeps the batch in the local queue.
+   * Never logs event contents (distinct_id, properties, context).
    */
-  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;
+  async send(batch) {
+    if (batch.length === 0) return;
+    const batchId = (0, import_sunglasses_core.generateUUID)();
+    const path = this.resolvePath(batchId);
+    const rows = batch.map(toStarfishRow);
+    await this.client.push(path, { events: rows }, null);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   StarfishAnalyticsAdapter,
-  createEmptyDocument,
-  mergeEvents,
-  pruneDocument,
-  resolveStoragePath
+  toStarfishRow
 });

package/dist/index.mjs

@@ -1,265 +1,51 @@
+// src/StarfishAnalyticsAdapter.ts
+import { generateUUID } from "@drakkar.software/sunglasses-core";
+
 // 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));
+function toStarfishRow(e) {
   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()
+    event_type: e.type,
+    event: e.event,
+    distinct_id: e.distinctId,
+    anonymous_id: e.anonymousId,
+    ts: e.timestamp,
+    message_id: e.messageId,
+    properties: JSON.stringify(e.properties),
+    context: JSON.stringify(e.context),
+    dt: e.timestamp.slice(0, 10)
   };
 }
 
 // src/StarfishAnalyticsAdapter.ts
-var DEFAULT_MAX_RETRIES = 3;
-var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
-var GEN_KEY_PREFIX = "sg:starfish:gen:";
+var DEFAULT_PATH_TEMPLATE = "events/{app}/{batchId}";
 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.pushOnly = config.pushOnly ?? false;
-    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.pushOnly) {
-      return this.sendPushOnly(batch, baseResolved);
-    }
-    if (this.rotatePathOnSuccess && this.pathStorage) {
-      return this.sendRotating(batch, identity, baseResolved);
-    }
-    return this.sendMerge(batch, baseResolved);
-  }
-  async reset() {
+    this.client = config.client;
+    this.app = config.app;
+    this.pathTemplate = config.pathTemplate ?? DEFAULT_PATH_TEMPLATE;
   }
-  async shutdown() {
+  resolvePath(batchId) {
+    return this.pathTemplate.replace("{app}", encodeURIComponent(this.app)).replace("{batchId}", batchId);
   }
   /**
-   * 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: push-only mode (queueOnly collections) ──────────────────────
-  /**
-   * Push a fresh document directly, no pull, no merge, no conflict detection.
-   * Throws on failure so SunglassesCore keeps events in queue for retry.
-   */
-  async sendPushOnly(batch, path) {
-    const doc = mergeEvents(createEmptyDocument(), batch);
-    const response = await this.push(path, doc, "");
-    if (!response.ok) {
-      throw new Error(
-        `[SunGlasses] StarfishAnalyticsAdapter: push-only push failed with status ${response.status} for path "${path}"`
-      );
-    }
-  }
-  // ── Private: rotating path mode ────────────────────────────────────────────
-  /**
-   * Push events to a new Starfish document each time.
+   * Push a batch of events to the Starfish events collection.
    *
-   * Path format: `{baseResolved}-{generation padded to 4 digits}`
-   * e.g. `analytics/user-1/events-0001`, `analytics/user-1/events-0002`
+   * A unique `batchId` is generated per call, producing a unique storage path
+   * (one Parquet file per flush). `baseHash: null` signals "must not exist" to
+   * Starfish, ensuring no conflict on the unique path.
    *
-   * The generation is persisted to `pathStorage` so it survives app restarts.
-   * On success: advance generation. On failure: keep current generation (retry next flush).
+   * Throws on failure — SunglassesCore keeps the batch in the local queue.
+   * Never logs event contents (distinct_id, properties, context).
    */
-  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;
+  async send(batch) {
+    if (batch.length === 0) return;
+    const batchId = generateUUID();
+    const path = this.resolvePath(batchId);
+    const rows = batch.map(toStarfishRow);
+    await this.client.push(path, { events: rows }, null);
   }
 };
 export {
   StarfishAnalyticsAdapter,
-  createEmptyDocument,
-  mergeEvents,
-  pruneDocument,
-  resolveStoragePath
+  toStarfishRow
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@drakkar.software/sunglasses-adapter-starfish",
-  "version": "0.6.0",
-  "description": "Starfish document-sync adapter for SunGlasses (Drakkar-Software/Starfish)",
+  "version": "0.8.0",
+  "description": "Starfish adapter for SunGlasses — pushes event batches as JSON to a Starfish events collection (server encodes to Parquet)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@drakkar.software/sunglasses-core": "0.6.0"
+    "@drakkar.software/sunglasses-core": "0.8.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",