@drakkar.software/sunglasses-core 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -399,6 +399,20 @@ interface StarfishAdapterConfig {
      * Can be the same adapter as `SunglassesConfig.storage`.
      */
     pathStorage?: IStorageAdapter;
+    /**
+     * When `true`, events are pushed directly without a prior pull.
+     * No merge, no optimistic locking, no conflict detection.
+     *
+     * Use this for Starfish collections configured with `queueOnly: true` —
+     * the server ignores `baseHash` and returns no stored data on pull,
+     * so a pull round-trip is always wasted.
+     *
+     * On push failure the adapter **throws**, allowing SunglassesCore to keep
+     * events in the local queue and retry on the next flush interval.
+     *
+     * Cannot be combined with `rotatePathOnSuccess`.
+     */
+    pushOnly?: boolean;
 }
 /**
  * In-memory + persisted session state.
@@ -1087,6 +1101,58 @@ declare class LocalEventArchive {
  */
 declare function asTyped<T extends EventMap>(client: ISunglassesClient): ISunglassesTypedClient<T>;
 
+/**
+ * A typed analytics stub that is safe to use before the SDK initialises.
+ *
+ * All calls are silent no-ops (or safe defaults) until `init()` is called
+ * with the real `SunglassesCore` instance. After `init()`, every method
+ * delegates to the real client transparently.
+ *
+ * This is the recommended pattern for module-level analytics singletons:
+ *
+ * ```typescript
+ * // analytics.ts
+ * import { createLazyClient, SunglassesCore } from '@drakkar.software/sunglasses-core';
+ *
+ * type MyEvents = {
+ *   button_clicked: { buttonId: string };
+ *   page_viewed: undefined;
+ * };
+ *
+ * export const analytics = createLazyClient<MyEvents>();
+ *
+ * export async function initAnalytics() {
+ *   const client = await SunglassesCore.create({ ... });
+ *   analytics.init(client);
+ *   return client;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // anywhere else
+ * import { analytics } from './analytics';
+ *
+ * // Safe at import time — noop if called before init(), real event after:
+ * analytics.capture('button_clicked', { buttonId: 'cta' }); // ✓ typed
+ * analytics.capture('unknown_event', {});                   // ✗ TS error
+ * ```
+ *
+ * ### Why not `Object.assign(stub, asTyped(client))`?
+ *
+ * `asTyped` returns the client itself. `Object.assign` only copies own
+ * enumerable properties — class prototype methods like `capture()` are
+ * **not** own properties and are silently skipped. Using `createLazyClient`
+ * avoids this footgun entirely.
+ */
+declare function createLazyClient<T extends EventMap>(): ISunglassesTypedClient<T> & {
+    /**
+     * Wire up the real SDK client.
+     * Safe to call multiple times — last call wins.
+     * After calling, all subsequent analytics calls delegate to `client`.
+     */
+    init(client: ISunglassesClient): void;
+};
+
 /**
  * Generate a UUID v4 using the Web Crypto API.
  *
@@ -1107,4 +1173,4 @@ declare function sha256Hex(input: string): Promise<string>;
  */
 declare function nowISO(): string;
 
-export { type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type StarfishAdapterConfig, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, createLogger, generateUUID, nowISO, sha256Hex };
+export { type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type StarfishAdapterConfig, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };

package/dist/index.d.ts

@@ -399,6 +399,20 @@ interface StarfishAdapterConfig {
      * Can be the same adapter as `SunglassesConfig.storage`.
      */
     pathStorage?: IStorageAdapter;
+    /**
+     * When `true`, events are pushed directly without a prior pull.
+     * No merge, no optimistic locking, no conflict detection.
+     *
+     * Use this for Starfish collections configured with `queueOnly: true` —
+     * the server ignores `baseHash` and returns no stored data on pull,
+     * so a pull round-trip is always wasted.
+     *
+     * On push failure the adapter **throws**, allowing SunglassesCore to keep
+     * events in the local queue and retry on the next flush interval.
+     *
+     * Cannot be combined with `rotatePathOnSuccess`.
+     */
+    pushOnly?: boolean;
 }
 /**
  * In-memory + persisted session state.
@@ -1087,6 +1101,58 @@ declare class LocalEventArchive {
  */
 declare function asTyped<T extends EventMap>(client: ISunglassesClient): ISunglassesTypedClient<T>;
 
+/**
+ * A typed analytics stub that is safe to use before the SDK initialises.
+ *
+ * All calls are silent no-ops (or safe defaults) until `init()` is called
+ * with the real `SunglassesCore` instance. After `init()`, every method
+ * delegates to the real client transparently.
+ *
+ * This is the recommended pattern for module-level analytics singletons:
+ *
+ * ```typescript
+ * // analytics.ts
+ * import { createLazyClient, SunglassesCore } from '@drakkar.software/sunglasses-core';
+ *
+ * type MyEvents = {
+ *   button_clicked: { buttonId: string };
+ *   page_viewed: undefined;
+ * };
+ *
+ * export const analytics = createLazyClient<MyEvents>();
+ *
+ * export async function initAnalytics() {
+ *   const client = await SunglassesCore.create({ ... });
+ *   analytics.init(client);
+ *   return client;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // anywhere else
+ * import { analytics } from './analytics';
+ *
+ * // Safe at import time — noop if called before init(), real event after:
+ * analytics.capture('button_clicked', { buttonId: 'cta' }); // ✓ typed
+ * analytics.capture('unknown_event', {});                   // ✗ TS error
+ * ```
+ *
+ * ### Why not `Object.assign(stub, asTyped(client))`?
+ *
+ * `asTyped` returns the client itself. `Object.assign` only copies own
+ * enumerable properties — class prototype methods like `capture()` are
+ * **not** own properties and are silently skipped. Using `createLazyClient`
+ * avoids this footgun entirely.
+ */
+declare function createLazyClient<T extends EventMap>(): ISunglassesTypedClient<T> & {
+    /**
+     * Wire up the real SDK client.
+     * Safe to call multiple times — last call wins.
+     * After calling, all subsequent analytics calls delegate to `client`.
+     */
+    init(client: ISunglassesClient): void;
+};
+
 /**
  * Generate a UUID v4 using the Web Crypto API.
  *
@@ -1107,4 +1173,4 @@ declare function sha256Hex(input: string): Promise<string>;
  */
 declare function nowISO(): string;
 
-export { type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type StarfishAdapterConfig, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, createLogger, generateUUID, nowISO, sha256Hex };
+export { type CleanupConfig, type ConsentHistoryEntry, ConsentManager, type ConsentState, type ConsentStatus, type ErrorEventProperties, type EventContext, type EventCountPeriod, EventCounter, type EventMap, EventQueue, type EventType, FrequencyMiddleware, type FrequencyMiddlewareOptions, type HttpAdapterConfig, type IAnalyticsAdapter, type IEventCounter, type IMiddleware, type IStorageAdapter, type ISunglassesClient, type ISunglassesTypedClient, IdentityManager, type IdentityState, LocalEventArchive, type Logger, type MiddlewareNext, MiddlewarePipeline, PiiSanitizer, SamplingMiddleware, type SamplingMiddlewareOptions, type ScreenTrackingOptions, SessionManager, type SessionState, type StarfishAdapterConfig, type SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   SunglassesCore: () => SunglassesCore,
   TraitManager: () => TraitManager,
   asTyped: () => asTyped,
+  createLazyClient: () => createLazyClient,
   createLogger: () => createLogger,
   generateUUID: () => generateUUID,
   nowISO: () => nowISO,
@@ -1590,6 +1591,105 @@ var SamplingMiddleware = class {
 function asTyped(client) {
   return client;
 }
+
+// src/LazyClient.ts
+function createLazyClient() {
+  let _inner = null;
+  const lazy = {
+    init(client) {
+      _inner = client;
+    },
+    // ── Event tracking ────────────────────────────────────────────────────────
+    capture(eventName, properties, options) {
+      _inner?.capture(eventName, properties, options);
+    },
+    screen(screenName, properties) {
+      _inner?.screen(screenName, properties);
+    },
+    identify(userId, traits) {
+      _inner?.identify(userId, traits);
+    },
+    alias(newId, existingId) {
+      _inner?.alias(newId, existingId);
+    },
+    group(groupId, groupTraits) {
+      _inner?.group(groupId, groupTraits);
+    },
+    async reset() {
+      await _inner?.reset();
+    },
+    // ── Super properties ──────────────────────────────────────────────────────
+    register(properties) {
+      _inner?.register(properties);
+    },
+    unregister(...keys) {
+      _inner?.unregister(...keys);
+    },
+    getRegisteredProperties() {
+      return _inner?.getRegisteredProperties() ?? {};
+    },
+    // ── Consent ───────────────────────────────────────────────────────────────
+    async optIn() {
+      await _inner?.optIn();
+    },
+    async optOut() {
+      await _inner?.optOut();
+    },
+    hasOptedIn() {
+      return _inner?.hasOptedIn() ?? false;
+    },
+    hasOptedOut() {
+      return _inner?.hasOptedOut() ?? false;
+    },
+    getConsentStatus() {
+      return _inner?.getConsentStatus() ?? "unknown";
+    },
+    getConsentHistory() {
+      return _inner?.getConsentHistory() ?? [];
+    },
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+    async flush() {
+      await _inner?.flush();
+    },
+    async shutdown() {
+      await _inner?.shutdown();
+    },
+    // ── Event counting ────────────────────────────────────────────────────────
+    async getEventCount(eventName, period, date) {
+      return _inner?.getEventCount(eventName, period, date) ?? Promise.resolve(0);
+    },
+    async resetEventCount(eventName) {
+      await _inner?.resetEventCount(eventName);
+    },
+    get eventCounter() {
+      return _inner?.eventCounter ?? null;
+    },
+    getQueuedEventCount() {
+      return _inner?.getQueuedEventCount() ?? 0;
+    },
+    // ── Local archive / data portability ─────────────────────────────────────
+    async clearLocalArchive(config) {
+      await _inner?.clearLocalArchive(config);
+    },
+    async exportUserData() {
+      return _inner?.exportUserData() ?? {
+        exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        anonymousId: "",
+        distinctId: null,
+        traits: {},
+        consentStatus: "unknown",
+        consentHistory: [],
+        queuedEvents: [],
+        archivedEvents: [],
+        eventCountSummary: {}
+      };
+    },
+    async deleteUserData(options) {
+      await _inner?.deleteUserData(options);
+    }
+  };
+  return lazy;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConsentManager,
@@ -1605,6 +1705,7 @@ function asTyped(client) {
   SunglassesCore,
   TraitManager,
   asTyped,
+  createLazyClient,
   createLogger,
   generateUUID,
   nowISO,

package/dist/index.mjs

@@ -1548,6 +1548,105 @@ var SamplingMiddleware = class {
 function asTyped(client) {
   return client;
 }
+
+// src/LazyClient.ts
+function createLazyClient() {
+  let _inner = null;
+  const lazy = {
+    init(client) {
+      _inner = client;
+    },
+    // ── Event tracking ────────────────────────────────────────────────────────
+    capture(eventName, properties, options) {
+      _inner?.capture(eventName, properties, options);
+    },
+    screen(screenName, properties) {
+      _inner?.screen(screenName, properties);
+    },
+    identify(userId, traits) {
+      _inner?.identify(userId, traits);
+    },
+    alias(newId, existingId) {
+      _inner?.alias(newId, existingId);
+    },
+    group(groupId, groupTraits) {
+      _inner?.group(groupId, groupTraits);
+    },
+    async reset() {
+      await _inner?.reset();
+    },
+    // ── Super properties ──────────────────────────────────────────────────────
+    register(properties) {
+      _inner?.register(properties);
+    },
+    unregister(...keys) {
+      _inner?.unregister(...keys);
+    },
+    getRegisteredProperties() {
+      return _inner?.getRegisteredProperties() ?? {};
+    },
+    // ── Consent ───────────────────────────────────────────────────────────────
+    async optIn() {
+      await _inner?.optIn();
+    },
+    async optOut() {
+      await _inner?.optOut();
+    },
+    hasOptedIn() {
+      return _inner?.hasOptedIn() ?? false;
+    },
+    hasOptedOut() {
+      return _inner?.hasOptedOut() ?? false;
+    },
+    getConsentStatus() {
+      return _inner?.getConsentStatus() ?? "unknown";
+    },
+    getConsentHistory() {
+      return _inner?.getConsentHistory() ?? [];
+    },
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+    async flush() {
+      await _inner?.flush();
+    },
+    async shutdown() {
+      await _inner?.shutdown();
+    },
+    // ── Event counting ────────────────────────────────────────────────────────
+    async getEventCount(eventName, period, date) {
+      return _inner?.getEventCount(eventName, period, date) ?? Promise.resolve(0);
+    },
+    async resetEventCount(eventName) {
+      await _inner?.resetEventCount(eventName);
+    },
+    get eventCounter() {
+      return _inner?.eventCounter ?? null;
+    },
+    getQueuedEventCount() {
+      return _inner?.getQueuedEventCount() ?? 0;
+    },
+    // ── Local archive / data portability ─────────────────────────────────────
+    async clearLocalArchive(config) {
+      await _inner?.clearLocalArchive(config);
+    },
+    async exportUserData() {
+      return _inner?.exportUserData() ?? {
+        exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        anonymousId: "",
+        distinctId: null,
+        traits: {},
+        consentStatus: "unknown",
+        consentHistory: [],
+        queuedEvents: [],
+        archivedEvents: [],
+        eventCountSummary: {}
+      };
+    },
+    async deleteUserData(options) {
+      await _inner?.deleteUserData(options);
+    }
+  };
+  return lazy;
+}
 export {
   ConsentManager,
   EventCounter,
@@ -1562,6 +1661,7 @@ export {
   SunglassesCore,
   TraitManager,
   asTyped,
+  createLazyClient,
   createLogger,
   generateUUID,
   nowISO,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/sunglasses-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Platform-agnostic event tracking engine for SunGlasses",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",