@drakkar.software/sunglasses-core 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -215,7 +215,7 @@ interface SunglassesConfig {
     consentExpiryMs?: number;
     /**
      * When true, every event that passes the middleware pipeline is also written
-     * to a permanent local archive (`sunglasses:archive` in IStorageAdapter).
+     * to a permanent local archive (`sg:archive` in IStorageAdapter).
      *
      * Unlike the EventQueue, the archive is **never cleared automatically** after
      * a flush — events persist until `client.clearLocalArchive()` is called.
@@ -654,7 +654,7 @@ declare class MiddlewarePipeline {
  * Persists per-event counts bucketed by time period (daily, weekly, monthly, all-time).
  *
  * Storage key format:
- *   `sunglasses:count:{period}:{bucket}:{eventName}`
+ *   `sg:count:{period}:{bucket}:{eventName}`
  *
  * where `bucket` is:
  *   - daily:    "2024-01-15"
@@ -1087,6 +1087,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 +1159,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

@@ -215,7 +215,7 @@ interface SunglassesConfig {
     consentExpiryMs?: number;
     /**
      * When true, every event that passes the middleware pipeline is also written
-     * to a permanent local archive (`sunglasses:archive` in IStorageAdapter).
+     * to a permanent local archive (`sg:archive` in IStorageAdapter).
      *
      * Unlike the EventQueue, the archive is **never cleared automatically** after
      * a flush — events persist until `client.clearLocalArchive()` is called.
@@ -654,7 +654,7 @@ declare class MiddlewarePipeline {
  * Persists per-event counts bucketed by time period (daily, weekly, monthly, all-time).
  *
  * Storage key format:
- *   `sunglasses:count:{period}:{bucket}:{eventName}`
+ *   `sg:count:{period}:{bucket}:{eventName}`
  *
  * where `bucket` is:
  *   - daily:    "2024-01-15"
@@ -1087,6 +1087,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 +1159,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,
@@ -46,7 +47,7 @@ function nowISO() {
 }
 
 // src/ConsentManager.ts
-var STORAGE_KEY = "sunglasses:consent";
+var STORAGE_KEY = "sg:consent";
 var MAX_HISTORY_LENGTH = 10;
 var ConsentManager = class {
   constructor(storage, logger) {
@@ -204,7 +205,7 @@ var ConsentManager = class {
 };
 
 // src/EventCounter.ts
-var KEY_PREFIX = "sunglasses:count";
+var KEY_PREFIX = "sg:count";
 var EventCounter = class {
   constructor(storage, logger) {
     this.storage = storage;
@@ -379,7 +380,7 @@ function toISOWeek(date) {
 }
 
 // src/EventQueue.ts
-var STORAGE_KEY2 = "sunglasses:queue";
+var STORAGE_KEY2 = "sg:queue";
 var EventQueue = class {
   constructor(storage, logger, maxSize) {
     this.storage = storage;
@@ -492,8 +493,8 @@ async function sha256Hex(input) {
 }
 
 // src/IdentityManager.ts
-var ANON_ID_KEY = "sunglasses:anon_id";
-var DISTINCT_ID_KEY = "sunglasses:distinct_id";
+var ANON_ID_KEY = "sg:anon_id";
+var DISTINCT_ID_KEY = "sg:distinct_id";
 var IdentityManager = class {
   constructor(storage, logger, anonymizeUserId) {
     this.storage = storage;
@@ -581,7 +582,7 @@ var IdentityManager = class {
 };
 
 // src/LocalEventArchive.ts
-var STORAGE_KEY3 = "sunglasses:archive";
+var STORAGE_KEY3 = "sg:archive";
 var LocalEventArchive = class {
   constructor(storage, logger) {
     this.storage = storage;
@@ -801,7 +802,7 @@ var PiiSanitizer = class {
 };
 
 // src/SessionManager.ts
-var STORAGE_KEY4 = "sunglasses:session";
+var STORAGE_KEY4 = "sg:session";
 var DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1e3;
 var SessionManager = class {
   constructor(storage, logger, idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS) {
@@ -914,7 +915,7 @@ var SessionManager = class {
 };
 
 // src/TraitManager.ts
-var STORAGE_KEY5 = "sunglasses:traits";
+var STORAGE_KEY5 = "sg:traits";
 var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
   "email",
   "phone",
@@ -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

@@ -4,7 +4,7 @@ function nowISO() {
 }
 
 // src/ConsentManager.ts
-var STORAGE_KEY = "sunglasses:consent";
+var STORAGE_KEY = "sg:consent";
 var MAX_HISTORY_LENGTH = 10;
 var ConsentManager = class {
   constructor(storage, logger) {
@@ -162,7 +162,7 @@ var ConsentManager = class {
 };
 
 // src/EventCounter.ts
-var KEY_PREFIX = "sunglasses:count";
+var KEY_PREFIX = "sg:count";
 var EventCounter = class {
   constructor(storage, logger) {
     this.storage = storage;
@@ -337,7 +337,7 @@ function toISOWeek(date) {
 }
 
 // src/EventQueue.ts
-var STORAGE_KEY2 = "sunglasses:queue";
+var STORAGE_KEY2 = "sg:queue";
 var EventQueue = class {
   constructor(storage, logger, maxSize) {
     this.storage = storage;
@@ -450,8 +450,8 @@ async function sha256Hex(input) {
 }
 
 // src/IdentityManager.ts
-var ANON_ID_KEY = "sunglasses:anon_id";
-var DISTINCT_ID_KEY = "sunglasses:distinct_id";
+var ANON_ID_KEY = "sg:anon_id";
+var DISTINCT_ID_KEY = "sg:distinct_id";
 var IdentityManager = class {
   constructor(storage, logger, anonymizeUserId) {
     this.storage = storage;
@@ -539,7 +539,7 @@ var IdentityManager = class {
 };
 
 // src/LocalEventArchive.ts
-var STORAGE_KEY3 = "sunglasses:archive";
+var STORAGE_KEY3 = "sg:archive";
 var LocalEventArchive = class {
   constructor(storage, logger) {
     this.storage = storage;
@@ -759,7 +759,7 @@ var PiiSanitizer = class {
 };
 
 // src/SessionManager.ts
-var STORAGE_KEY4 = "sunglasses:session";
+var STORAGE_KEY4 = "sg:session";
 var DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1e3;
 var SessionManager = class {
   constructor(storage, logger, idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS) {
@@ -872,7 +872,7 @@ var SessionManager = class {
 };
 
 // src/TraitManager.ts
-var STORAGE_KEY5 = "sunglasses:traits";
+var STORAGE_KEY5 = "sg:traits";
 var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
   "email",
   "phone",
@@ -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.3.0",
+  "version": "0.5.0",
   "description": "Platform-agnostic event tracking engine for SunGlasses",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",