@drakkar.software/sunglasses-core 0.7.0 → 0.10.0

package/dist/index.d.mts

@@ -11,7 +11,7 @@ interface IStorageAdapter {
 }
 /**
  * Output destination that receives batches of sanitized, consented events.
- * Implementations: HttpStorageAdapter, StarfishAnalyticsAdapter, console (debug).
+ * Implementations include `HttpStorageAdapter` and any custom adapter.
  */
 interface IAnalyticsAdapter {
     /**
@@ -27,7 +27,7 @@ interface IAnalyticsAdapter {
     /**
      * Called after a successful flush with the events that were delivered.
      * Use this to archive or remove old events from the remote store.
-     * Implement this in adapters that accumulate data (e.g. StarfishAnalyticsAdapter).
+     * Implement in adapters that accumulate data and need post-flush pruning.
      */
     cleanupAfterFlush?(delivered: ReadonlyArray<SunglassesEvent>, config: CleanupConfig): Promise<void>;
 }
@@ -55,6 +55,39 @@ interface IMiddleware {
     process(event: SunglassesEvent, next: MiddlewareNext): Promise<SunglassesEvent | null>;
 }
 type EventType = 'capture' | 'screen' | 'identify' | 'alias' | 'group';
+/**
+ * Over-the-air (OTA) / app update information, e.g. an Expo EAS Update or a web
+ * deploy identifier. Useful for correlating events with a specific shipped bundle.
+ */
+interface AppUpdateInfo {
+    /** Unique identifier of the applied update (e.g. EAS update ID). */
+    id?: string;
+    /** Release channel the update was published to (e.g. 'production'). */
+    channel?: string;
+    /** Runtime/native version the update is compatible with. */
+    runtimeVersion?: string;
+    /** True when running the bundle shipped in the binary (no OTA applied). */
+    embedded?: boolean;
+    /** ISO-8601 timestamp of when the update was created/published. */
+    createdAt?: string;
+}
+/**
+ * Mutable global metadata attached to every event's `context`. Set via
+ * `SunglassesConfig` at init and updatable at runtime. In-memory only — the host
+ * app must re-supply these values on each boot.
+ */
+interface AppMetadata {
+    /** Deployment environment, e.g. 'production' | 'staging' | 'development'. */
+    environment?: string;
+    /** App variant / build flavor, e.g. 'pro' | 'lite' | 'beta'. */
+    appVariant?: string;
+    /** OTA / app update info for the currently running bundle. */
+    appUpdate?: AppUpdateInfo;
+    /** Enabled features / experiment variants (app-scoped). */
+    features?: string[];
+    /** Active user entitlements (user-scoped, cleared on reset()). */
+    entitlements?: string[];
+}
 interface EventContext {
     library: {
         name: string;
@@ -65,6 +98,8 @@ interface EventContext {
         name?: string;
         version?: string;
         build?: string;
+        variant?: string;
+        update?: AppUpdateInfo;
     };
     device?: {
         type?: string;
@@ -75,6 +110,12 @@ interface EventContext {
         height?: number;
     };
     locale?: string;
+    /** Deployment environment, e.g. 'production' | 'staging' | 'development'. */
+    environment?: string;
+    /** Enabled features / experiment variants (app-scoped). */
+    features?: string[];
+    /** Active user entitlements (user-scoped). */
+    entitlements?: string[];
     /** Current session ID. Present when enableSessionTracking is true. */
     sessionId?: string;
     /** Persisted user traits set via identify(). Forwarded to backends for segmentation. */
@@ -171,6 +212,16 @@ interface SunglassesConfig {
     appName?: string;
     appVersion?: string;
     appBuild?: string;
+    /** App variant / build flavor, e.g. 'pro' | 'lite' | 'beta'. Attached to context.app.variant. */
+    appVariant?: string;
+    /** OTA / app update info for the currently running bundle. Attached to context.app.update. */
+    appUpdate?: AppUpdateInfo;
+    /** Deployment environment, e.g. 'production' | 'staging'. Attached to context.environment. */
+    environment?: string;
+    /** Enabled features / experiment variants (app-scoped). Attached to context.features. */
+    features?: string[];
+    /** Active user entitlements (user-scoped). Attached to context.entitlements. */
+    entitlements?: string[];
     /** Enables verbose console logging. Never enable in production. */
     debug?: boolean;
     /** Hard-disables all tracking (e.g. CI environments, test suites). */
@@ -269,6 +320,34 @@ interface ISunglassesClient {
     unregister(...keys: string[]): void;
     /** Returns a snapshot of all currently registered super properties. */
     getRegisteredProperties(): Record<string, unknown>;
+    /**
+     * Set the deployment environment (e.g. 'production', 'staging'). Attached to
+     * every subsequent event's `context.environment`. In-memory only.
+     */
+    setEnvironment(environment: string): void;
+    /**
+     * Set OTA / app update info for the currently running bundle. Attached to
+     * every subsequent event's `context.app.update`. In-memory only.
+     */
+    setAppUpdate(update: AppUpdateInfo): void;
+    /**
+     * Set the list of enabled features / experiment variants (app-scoped).
+     * Attached to every subsequent event's `context.features`. In-memory only.
+     */
+    setFeatures(features: string[]): void;
+    /**
+     * Set the active user entitlements (user-scoped). Attached to every subsequent
+     * event's `context.entitlements`. Cleared by `reset()` and `deleteUserData()`.
+     * In-memory only.
+     */
+    setEntitlements(entitlements: string[]): void;
+    /**
+     * Merge a partial set of global app metadata. Only the provided keys are
+     * updated; omitted keys keep their current value. In-memory only.
+     */
+    setAppMetadata(meta: Partial<AppMetadata>): void;
+    /** Returns a snapshot of the current global app metadata. */
+    getAppMetadata(): AppMetadata;
     optIn(): Promise<void>;
     optOut(): Promise<void>;
     hasOptedIn(): boolean;
@@ -366,54 +445,6 @@ interface HttpAdapterConfig {
     /** Request timeout in ms. Default: 10_000. */
     timeout?: number;
 }
-interface StarfishAdapterConfig {
-    /** Base URL of the Starfish sync server, e.g. https://sync.example.com */
-    serverUrl: string;
-    /**
-     * Path template for the event document.
-     * Use `{identity}` as a placeholder — it is replaced with `distinctId ?? anonymousId`.
-     * Example: "analytics/{identity}/events"
-     */
-    storagePath: string;
-    /** Bearer token for Authorization header. */
-    authToken?: string;
-    /** Max retries on 409 Conflict (optimistic locking). Default: 3. */
-    maxRetries?: number;
-    /**
-     * When true, each successful push creates a **new** Starfish document using
-     * a rotating path suffix (e.g. `events-0001`, `events-0002`…).
-     *
-     * Benefits:
-     * - No pull step needed — each push is always a fresh document
-     * - No growing single document — each file stays small
-     * - Old documents accumulate on Starfish (combine with `cleanupAfterFlush` to prune)
-     *
-     * Requires `pathStorage` to persist the current path generation counter.
-     * Works best with `enableLocalArchive: true` in `SunglassesConfig` so the
-     * complete event history is kept locally even across many push generations.
-     */
-    rotatePathOnSuccess?: boolean;
-    /**
-     * Storage adapter used to persist the current path generation counter.
-     * Required when `rotatePathOnSuccess: true`.
-     * 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.
  * Session IDs are random UUIDs — they never contain PII.
@@ -546,6 +577,12 @@ declare class SunglassesCore implements ISunglassesClient {
     private readonly superProperties;
     /** In-memory group ID attached to every event's context after group() is called. */
     private groupId;
+    /** In-memory global app metadata attached to every event's context. */
+    private environment;
+    private appVariant;
+    private appUpdate;
+    private features;
+    private entitlements;
     private constructor();
     /**
      * Create and initialize a SunglassesCore instance.
@@ -560,6 +597,12 @@ declare class SunglassesCore implements ISunglassesClient {
     register(properties: Record<string, unknown>): void;
     unregister(...keys: string[]): void;
     getRegisteredProperties(): Record<string, unknown>;
+    setEnvironment(environment: string): void;
+    setAppUpdate(update: AppUpdateInfo): void;
+    setFeatures(features: string[]): void;
+    setEntitlements(entitlements: string[]): void;
+    setAppMetadata(meta: Partial<AppMetadata>): void;
+    getAppMetadata(): AppMetadata;
     reset(): Promise<void>;
     optIn(): Promise<void>;
     optOut(): Promise<void>;
@@ -1093,6 +1136,73 @@ declare class LocalEventArchive {
  */
 declare function asTyped<T extends EventMap>(client: ISunglassesClient): ISunglassesTypedClient<T>;
 
+/**
+ * Options for {@link captureException}. Mirrors the privacy-safe defaults used
+ * by the error-capturing adapters so behaviour is consistent everywhere.
+ */
+interface CaptureExceptionOptions {
+    /**
+     * Whether the error was handled (caught by an error boundary / try-catch) or
+     * unhandled (surfaced by a global error handler). Default: `true`.
+     */
+    handled?: boolean;
+    /** Sentry-compatible severity level. Default: `'error'`. */
+    level?: string;
+    /**
+     * Include the stack trace in `$error_stack`. Default: `false` (privacy-safe).
+     * Stack traces may expose internal file paths and function names.
+     */
+    includeStack?: boolean;
+    /**
+     * Maximum number of stack frames to include when `includeStack` is `true`.
+     * Default: `5`.
+     */
+    maxStackFrames?: number;
+    /**
+     * Truncate error messages to this many characters. Default: `200`.
+     * Error messages sometimes contain user data ("User foo@bar.com not found").
+     */
+    maxMessageLength?: number;
+    /**
+     * Skip errors whose message matches any of these patterns.
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /**
+     * Extra properties merged into the captured `$error` event. Lower precedence
+     * than the computed `$error_*` properties.
+     */
+    properties?: Record<string, unknown>;
+    /**
+     * Optional transform applied before `client.capture()`.
+     * Receives typed `ErrorEventProperties`; return a (possibly extended) props
+     * object to capture, or `null` to skip capture entirely.
+     */
+    beforeCapture?: (props: ErrorEventProperties) => Record<string, unknown> | null;
+}
+/**
+ * Normalize any thrown value into a SunGlasses `$error` event and capture it
+ * via `client.capture()`.
+ *
+ * This is the single source of error-event construction shared by the built-in
+ * error boundaries and the provider global error handlers. It never throws and
+ * respects consent automatically (capture is consent-gated in the core).
+ *
+ * @param client - SunGlasses client instance.
+ * @param error - The thrown value (an `Error`, string, or arbitrary object).
+ * @param options - Optional capture configuration.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   doRiskyThing();
+ * } catch (err) {
+ *   captureException(client, err); // $error_handled: true
+ * }
+ * ```
+ */
+declare function captureException(client: ISunglassesClient, error: unknown, options?: CaptureExceptionOptions): void;
+
 /**
  * A typed analytics stub that is safe to use before the SDK initialises.
  *
@@ -1165,4 +1275,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, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };
+export { type AppMetadata, type AppUpdateInfo, type CaptureExceptionOptions, 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 SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, captureException, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };

package/dist/index.d.ts

@@ -11,7 +11,7 @@ interface IStorageAdapter {
 }
 /**
  * Output destination that receives batches of sanitized, consented events.
- * Implementations: HttpStorageAdapter, StarfishAnalyticsAdapter, console (debug).
+ * Implementations include `HttpStorageAdapter` and any custom adapter.
  */
 interface IAnalyticsAdapter {
     /**
@@ -27,7 +27,7 @@ interface IAnalyticsAdapter {
     /**
      * Called after a successful flush with the events that were delivered.
      * Use this to archive or remove old events from the remote store.
-     * Implement this in adapters that accumulate data (e.g. StarfishAnalyticsAdapter).
+     * Implement in adapters that accumulate data and need post-flush pruning.
      */
     cleanupAfterFlush?(delivered: ReadonlyArray<SunglassesEvent>, config: CleanupConfig): Promise<void>;
 }
@@ -55,6 +55,39 @@ interface IMiddleware {
     process(event: SunglassesEvent, next: MiddlewareNext): Promise<SunglassesEvent | null>;
 }
 type EventType = 'capture' | 'screen' | 'identify' | 'alias' | 'group';
+/**
+ * Over-the-air (OTA) / app update information, e.g. an Expo EAS Update or a web
+ * deploy identifier. Useful for correlating events with a specific shipped bundle.
+ */
+interface AppUpdateInfo {
+    /** Unique identifier of the applied update (e.g. EAS update ID). */
+    id?: string;
+    /** Release channel the update was published to (e.g. 'production'). */
+    channel?: string;
+    /** Runtime/native version the update is compatible with. */
+    runtimeVersion?: string;
+    /** True when running the bundle shipped in the binary (no OTA applied). */
+    embedded?: boolean;
+    /** ISO-8601 timestamp of when the update was created/published. */
+    createdAt?: string;
+}
+/**
+ * Mutable global metadata attached to every event's `context`. Set via
+ * `SunglassesConfig` at init and updatable at runtime. In-memory only — the host
+ * app must re-supply these values on each boot.
+ */
+interface AppMetadata {
+    /** Deployment environment, e.g. 'production' | 'staging' | 'development'. */
+    environment?: string;
+    /** App variant / build flavor, e.g. 'pro' | 'lite' | 'beta'. */
+    appVariant?: string;
+    /** OTA / app update info for the currently running bundle. */
+    appUpdate?: AppUpdateInfo;
+    /** Enabled features / experiment variants (app-scoped). */
+    features?: string[];
+    /** Active user entitlements (user-scoped, cleared on reset()). */
+    entitlements?: string[];
+}
 interface EventContext {
     library: {
         name: string;
@@ -65,6 +98,8 @@ interface EventContext {
         name?: string;
         version?: string;
         build?: string;
+        variant?: string;
+        update?: AppUpdateInfo;
     };
     device?: {
         type?: string;
@@ -75,6 +110,12 @@ interface EventContext {
         height?: number;
     };
     locale?: string;
+    /** Deployment environment, e.g. 'production' | 'staging' | 'development'. */
+    environment?: string;
+    /** Enabled features / experiment variants (app-scoped). */
+    features?: string[];
+    /** Active user entitlements (user-scoped). */
+    entitlements?: string[];
     /** Current session ID. Present when enableSessionTracking is true. */
     sessionId?: string;
     /** Persisted user traits set via identify(). Forwarded to backends for segmentation. */
@@ -171,6 +212,16 @@ interface SunglassesConfig {
     appName?: string;
     appVersion?: string;
     appBuild?: string;
+    /** App variant / build flavor, e.g. 'pro' | 'lite' | 'beta'. Attached to context.app.variant. */
+    appVariant?: string;
+    /** OTA / app update info for the currently running bundle. Attached to context.app.update. */
+    appUpdate?: AppUpdateInfo;
+    /** Deployment environment, e.g. 'production' | 'staging'. Attached to context.environment. */
+    environment?: string;
+    /** Enabled features / experiment variants (app-scoped). Attached to context.features. */
+    features?: string[];
+    /** Active user entitlements (user-scoped). Attached to context.entitlements. */
+    entitlements?: string[];
     /** Enables verbose console logging. Never enable in production. */
     debug?: boolean;
     /** Hard-disables all tracking (e.g. CI environments, test suites). */
@@ -269,6 +320,34 @@ interface ISunglassesClient {
     unregister(...keys: string[]): void;
     /** Returns a snapshot of all currently registered super properties. */
     getRegisteredProperties(): Record<string, unknown>;
+    /**
+     * Set the deployment environment (e.g. 'production', 'staging'). Attached to
+     * every subsequent event's `context.environment`. In-memory only.
+     */
+    setEnvironment(environment: string): void;
+    /**
+     * Set OTA / app update info for the currently running bundle. Attached to
+     * every subsequent event's `context.app.update`. In-memory only.
+     */
+    setAppUpdate(update: AppUpdateInfo): void;
+    /**
+     * Set the list of enabled features / experiment variants (app-scoped).
+     * Attached to every subsequent event's `context.features`. In-memory only.
+     */
+    setFeatures(features: string[]): void;
+    /**
+     * Set the active user entitlements (user-scoped). Attached to every subsequent
+     * event's `context.entitlements`. Cleared by `reset()` and `deleteUserData()`.
+     * In-memory only.
+     */
+    setEntitlements(entitlements: string[]): void;
+    /**
+     * Merge a partial set of global app metadata. Only the provided keys are
+     * updated; omitted keys keep their current value. In-memory only.
+     */
+    setAppMetadata(meta: Partial<AppMetadata>): void;
+    /** Returns a snapshot of the current global app metadata. */
+    getAppMetadata(): AppMetadata;
     optIn(): Promise<void>;
     optOut(): Promise<void>;
     hasOptedIn(): boolean;
@@ -366,54 +445,6 @@ interface HttpAdapterConfig {
     /** Request timeout in ms. Default: 10_000. */
     timeout?: number;
 }
-interface StarfishAdapterConfig {
-    /** Base URL of the Starfish sync server, e.g. https://sync.example.com */
-    serverUrl: string;
-    /**
-     * Path template for the event document.
-     * Use `{identity}` as a placeholder — it is replaced with `distinctId ?? anonymousId`.
-     * Example: "analytics/{identity}/events"
-     */
-    storagePath: string;
-    /** Bearer token for Authorization header. */
-    authToken?: string;
-    /** Max retries on 409 Conflict (optimistic locking). Default: 3. */
-    maxRetries?: number;
-    /**
-     * When true, each successful push creates a **new** Starfish document using
-     * a rotating path suffix (e.g. `events-0001`, `events-0002`…).
-     *
-     * Benefits:
-     * - No pull step needed — each push is always a fresh document
-     * - No growing single document — each file stays small
-     * - Old documents accumulate on Starfish (combine with `cleanupAfterFlush` to prune)
-     *
-     * Requires `pathStorage` to persist the current path generation counter.
-     * Works best with `enableLocalArchive: true` in `SunglassesConfig` so the
-     * complete event history is kept locally even across many push generations.
-     */
-    rotatePathOnSuccess?: boolean;
-    /**
-     * Storage adapter used to persist the current path generation counter.
-     * Required when `rotatePathOnSuccess: true`.
-     * 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.
  * Session IDs are random UUIDs — they never contain PII.
@@ -546,6 +577,12 @@ declare class SunglassesCore implements ISunglassesClient {
     private readonly superProperties;
     /** In-memory group ID attached to every event's context after group() is called. */
     private groupId;
+    /** In-memory global app metadata attached to every event's context. */
+    private environment;
+    private appVariant;
+    private appUpdate;
+    private features;
+    private entitlements;
     private constructor();
     /**
      * Create and initialize a SunglassesCore instance.
@@ -560,6 +597,12 @@ declare class SunglassesCore implements ISunglassesClient {
     register(properties: Record<string, unknown>): void;
     unregister(...keys: string[]): void;
     getRegisteredProperties(): Record<string, unknown>;
+    setEnvironment(environment: string): void;
+    setAppUpdate(update: AppUpdateInfo): void;
+    setFeatures(features: string[]): void;
+    setEntitlements(entitlements: string[]): void;
+    setAppMetadata(meta: Partial<AppMetadata>): void;
+    getAppMetadata(): AppMetadata;
     reset(): Promise<void>;
     optIn(): Promise<void>;
     optOut(): Promise<void>;
@@ -1093,6 +1136,73 @@ declare class LocalEventArchive {
  */
 declare function asTyped<T extends EventMap>(client: ISunglassesClient): ISunglassesTypedClient<T>;
 
+/**
+ * Options for {@link captureException}. Mirrors the privacy-safe defaults used
+ * by the error-capturing adapters so behaviour is consistent everywhere.
+ */
+interface CaptureExceptionOptions {
+    /**
+     * Whether the error was handled (caught by an error boundary / try-catch) or
+     * unhandled (surfaced by a global error handler). Default: `true`.
+     */
+    handled?: boolean;
+    /** Sentry-compatible severity level. Default: `'error'`. */
+    level?: string;
+    /**
+     * Include the stack trace in `$error_stack`. Default: `false` (privacy-safe).
+     * Stack traces may expose internal file paths and function names.
+     */
+    includeStack?: boolean;
+    /**
+     * Maximum number of stack frames to include when `includeStack` is `true`.
+     * Default: `5`.
+     */
+    maxStackFrames?: number;
+    /**
+     * Truncate error messages to this many characters. Default: `200`.
+     * Error messages sometimes contain user data ("User foo@bar.com not found").
+     */
+    maxMessageLength?: number;
+    /**
+     * Skip errors whose message matches any of these patterns.
+     * Pattern is tested against the raw (pre-truncation) message.
+     */
+    ignorePatterns?: RegExp[];
+    /**
+     * Extra properties merged into the captured `$error` event. Lower precedence
+     * than the computed `$error_*` properties.
+     */
+    properties?: Record<string, unknown>;
+    /**
+     * Optional transform applied before `client.capture()`.
+     * Receives typed `ErrorEventProperties`; return a (possibly extended) props
+     * object to capture, or `null` to skip capture entirely.
+     */
+    beforeCapture?: (props: ErrorEventProperties) => Record<string, unknown> | null;
+}
+/**
+ * Normalize any thrown value into a SunGlasses `$error` event and capture it
+ * via `client.capture()`.
+ *
+ * This is the single source of error-event construction shared by the built-in
+ * error boundaries and the provider global error handlers. It never throws and
+ * respects consent automatically (capture is consent-gated in the core).
+ *
+ * @param client - SunGlasses client instance.
+ * @param error - The thrown value (an `Error`, string, or arbitrary object).
+ * @param options - Optional capture configuration.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   doRiskyThing();
+ * } catch (err) {
+ *   captureException(client, err); // $error_handled: true
+ * }
+ * ```
+ */
+declare function captureException(client: ISunglassesClient, error: unknown, options?: CaptureExceptionOptions): void;
+
 /**
  * A typed analytics stub that is safe to use before the SDK initialises.
  *
@@ -1165,4 +1275,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, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };
+export { type AppMetadata, type AppUpdateInfo, type CaptureExceptionOptions, 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 SunglassesConfig, SunglassesCore, type SunglassesEvent, TraitManager, type UserDataExport, asTyped, captureException, createLazyClient, createLogger, generateUUID, nowISO, sha256Hex };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   SunglassesCore: () => SunglassesCore,
   TraitManager: () => TraitManager,
   asTyped: () => asTyped,
+  captureException: () => captureException,
   createLazyClient: () => createLazyClient,
   createLogger: () => createLogger,
   generateUUID: () => generateUUID,
@@ -1013,6 +1014,11 @@ var SunglassesCore = class _SunglassesCore {
     this.sessionManager = sessionManager;
     this.traitManager = traitManager;
     this.localArchive = localArchive;
+    this.environment = config.environment;
+    this.appVariant = config.appVariant;
+    this.appUpdate = config.appUpdate;
+    this.features = config.features;
+    this.entitlements = config.entitlements;
   }
   /**
    * Create and initialize a SunglassesCore instance.
@@ -1145,11 +1151,41 @@ var SunglassesCore = class _SunglassesCore {
   getRegisteredProperties() {
     return Object.fromEntries(this.superProperties);
   }
+  // ── App metadata ───────────────────────────────────────────────────────────
+  setEnvironment(environment) {
+    this.environment = environment;
+  }
+  setAppUpdate(update) {
+    this.appUpdate = update;
+  }
+  setFeatures(features) {
+    this.features = features;
+  }
+  setEntitlements(entitlements) {
+    this.entitlements = entitlements;
+  }
+  setAppMetadata(meta) {
+    if ("environment" in meta) this.environment = meta.environment;
+    if ("appVariant" in meta) this.appVariant = meta.appVariant;
+    if ("appUpdate" in meta) this.appUpdate = meta.appUpdate;
+    if ("features" in meta) this.features = meta.features;
+    if ("entitlements" in meta) this.entitlements = meta.entitlements;
+  }
+  getAppMetadata() {
+    return {
+      environment: this.environment,
+      appVariant: this.appVariant,
+      appUpdate: this.appUpdate,
+      features: this.features,
+      entitlements: this.entitlements
+    };
+  }
   async reset() {
     await this.identity.reset();
     await this.queue.clear();
     await this.traitManager.clearTraits();
     this.groupId = null;
+    this.entitlements = void 0;
     if (this.sessionManager) {
       await this.sessionManager.end();
     }
@@ -1267,6 +1303,7 @@ var SunglassesCore = class _SunglassesCore {
     await this.identity.reset();
     this.groupId = null;
     this.superProperties.clear();
+    this.entitlements = void 0;
     if (options.resetConsent) {
       await this.consent.resetToUnknown(this.config.consentPolicyVersion);
       this.stopFlushTimer();
@@ -1352,13 +1389,24 @@ var SunglassesCore = class _SunglassesCore {
       library: { name: LIBRARY_NAME, version: LIBRARY_VERSION },
       platform: this.config.platform
     };
-    if (this.config.appName || this.config.appVersion) {
+    if (this.config.appName || this.config.appVersion || this.appVariant || this.appUpdate) {
       ctx.app = {
         name: this.config.appName || void 0,
         version: this.config.appVersion || void 0,
-        build: this.config.appBuild || void 0
+        build: this.config.appBuild || void 0,
+        variant: this.appVariant || void 0,
+        update: this.appUpdate || void 0
       };
     }
+    if (this.environment) {
+      ctx.environment = this.environment;
+    }
+    if (this.features && this.features.length > 0) {
+      ctx.features = this.features;
+    }
+    if (this.entitlements && this.entitlements.length > 0) {
+      ctx.entitlements = this.entitlements;
+    }
     if (sessionId !== void 0) {
       ctx.sessionId = sessionId;
     }
@@ -1532,6 +1580,71 @@ function asTyped(client) {
   return client;
 }
 
+// src/captureException.ts
+function normalizeError(error) {
+  if (error instanceof Error) {
+    return { message: error.message, name: error.name || "Error", stack: error.stack };
+  }
+  if (typeof error === "string") {
+    return { message: error, name: "Error" };
+  }
+  if (error && typeof error === "object") {
+    const maybe = error;
+    return {
+      message: typeof maybe.message === "string" ? maybe.message : String(error),
+      name: typeof maybe.name === "string" && maybe.name ? maybe.name : "Error",
+      stack: typeof maybe.stack === "string" ? maybe.stack : void 0
+    };
+  }
+  return { message: String(error), name: "Error" };
+}
+function extractStack(stack, maxFrames) {
+  if (!stack) return void 0;
+  const lines = stack.split("\n").map((l) => l.trim());
+  const v8Frames = lines.filter((l) => l.startsWith("at "));
+  if (v8Frames.length > 0) {
+    return v8Frames.slice(0, maxFrames).join("\n");
+  }
+  const rnFrames = lines.filter((l) => l.includes("@") && !l.includes(" "));
+  if (rnFrames.length > 0) {
+    return rnFrames.slice(0, maxFrames).join("\n");
+  }
+  return void 0;
+}
+function captureException(client, error, options = {}) {
+  const {
+    handled = true,
+    level = "error",
+    includeStack = false,
+    maxStackFrames = 5,
+    maxMessageLength = 200,
+    ignorePatterns = [],
+    properties,
+    beforeCapture
+  } = options;
+  const normalized = normalizeError(error);
+  const rawMessage = normalized.message;
+  if (ignorePatterns.some((p) => p.test(rawMessage))) return;
+  let props = {
+    ...properties,
+    $error_message: rawMessage.slice(0, maxMessageLength),
+    $error_type: normalized.name,
+    $error_handled: handled,
+    $error_level: level
+  };
+  if (includeStack) {
+    const frames = extractStack(normalized.stack, maxStackFrames);
+    if (frames) props = { ...props, $error_stack: frames };
+  }
+  if (beforeCapture) {
+    const transformed = beforeCapture(props);
+    if (!transformed) return;
+    client.capture("$error", transformed);
+  } else {
+    client.capture("$error", props);
+  }
+}
+
 // src/LazyClient.ts
 function createLazyClient() {
   let _inner = null;
@@ -1568,6 +1681,25 @@ function createLazyClient() {
     getRegisteredProperties() {
       return _inner?.getRegisteredProperties() ?? {};
     },
+    // ── App metadata ──────────────────────────────────────────────────────────
+    setEnvironment(environment) {
+      _inner?.setEnvironment(environment);
+    },
+    setAppUpdate(update) {
+      _inner?.setAppUpdate(update);
+    },
+    setFeatures(features) {
+      _inner?.setFeatures(features);
+    },
+    setEntitlements(entitlements) {
+      _inner?.setEntitlements(entitlements);
+    },
+    setAppMetadata(meta) {
+      _inner?.setAppMetadata(meta);
+    },
+    getAppMetadata() {
+      return _inner?.getAppMetadata() ?? {};
+    },
     // ── Consent ───────────────────────────────────────────────────────────────
     async optIn() {
       await _inner?.optIn();
@@ -1645,6 +1777,7 @@ function createLazyClient() {
   SunglassesCore,
   TraitManager,
   asTyped,
+  captureException,
   createLazyClient,
   createLogger,
   generateUUID,

package/dist/index.mjs

@@ -970,6 +970,11 @@ var SunglassesCore = class _SunglassesCore {
     this.sessionManager = sessionManager;
     this.traitManager = traitManager;
     this.localArchive = localArchive;
+    this.environment = config.environment;
+    this.appVariant = config.appVariant;
+    this.appUpdate = config.appUpdate;
+    this.features = config.features;
+    this.entitlements = config.entitlements;
   }
   /**
    * Create and initialize a SunglassesCore instance.
@@ -1102,11 +1107,41 @@ var SunglassesCore = class _SunglassesCore {
   getRegisteredProperties() {
     return Object.fromEntries(this.superProperties);
   }
+  // ── App metadata ───────────────────────────────────────────────────────────
+  setEnvironment(environment) {
+    this.environment = environment;
+  }
+  setAppUpdate(update) {
+    this.appUpdate = update;
+  }
+  setFeatures(features) {
+    this.features = features;
+  }
+  setEntitlements(entitlements) {
+    this.entitlements = entitlements;
+  }
+  setAppMetadata(meta) {
+    if ("environment" in meta) this.environment = meta.environment;
+    if ("appVariant" in meta) this.appVariant = meta.appVariant;
+    if ("appUpdate" in meta) this.appUpdate = meta.appUpdate;
+    if ("features" in meta) this.features = meta.features;
+    if ("entitlements" in meta) this.entitlements = meta.entitlements;
+  }
+  getAppMetadata() {
+    return {
+      environment: this.environment,
+      appVariant: this.appVariant,
+      appUpdate: this.appUpdate,
+      features: this.features,
+      entitlements: this.entitlements
+    };
+  }
   async reset() {
     await this.identity.reset();
     await this.queue.clear();
     await this.traitManager.clearTraits();
     this.groupId = null;
+    this.entitlements = void 0;
     if (this.sessionManager) {
       await this.sessionManager.end();
     }
@@ -1224,6 +1259,7 @@ var SunglassesCore = class _SunglassesCore {
     await this.identity.reset();
     this.groupId = null;
     this.superProperties.clear();
+    this.entitlements = void 0;
     if (options.resetConsent) {
       await this.consent.resetToUnknown(this.config.consentPolicyVersion);
       this.stopFlushTimer();
@@ -1309,13 +1345,24 @@ var SunglassesCore = class _SunglassesCore {
       library: { name: LIBRARY_NAME, version: LIBRARY_VERSION },
       platform: this.config.platform
     };
-    if (this.config.appName || this.config.appVersion) {
+    if (this.config.appName || this.config.appVersion || this.appVariant || this.appUpdate) {
       ctx.app = {
         name: this.config.appName || void 0,
         version: this.config.appVersion || void 0,
-        build: this.config.appBuild || void 0
+        build: this.config.appBuild || void 0,
+        variant: this.appVariant || void 0,
+        update: this.appUpdate || void 0
       };
     }
+    if (this.environment) {
+      ctx.environment = this.environment;
+    }
+    if (this.features && this.features.length > 0) {
+      ctx.features = this.features;
+    }
+    if (this.entitlements && this.entitlements.length > 0) {
+      ctx.entitlements = this.entitlements;
+    }
     if (sessionId !== void 0) {
       ctx.sessionId = sessionId;
     }
@@ -1489,6 +1536,71 @@ function asTyped(client) {
   return client;
 }
 
+// src/captureException.ts
+function normalizeError(error) {
+  if (error instanceof Error) {
+    return { message: error.message, name: error.name || "Error", stack: error.stack };
+  }
+  if (typeof error === "string") {
+    return { message: error, name: "Error" };
+  }
+  if (error && typeof error === "object") {
+    const maybe = error;
+    return {
+      message: typeof maybe.message === "string" ? maybe.message : String(error),
+      name: typeof maybe.name === "string" && maybe.name ? maybe.name : "Error",
+      stack: typeof maybe.stack === "string" ? maybe.stack : void 0
+    };
+  }
+  return { message: String(error), name: "Error" };
+}
+function extractStack(stack, maxFrames) {
+  if (!stack) return void 0;
+  const lines = stack.split("\n").map((l) => l.trim());
+  const v8Frames = lines.filter((l) => l.startsWith("at "));
+  if (v8Frames.length > 0) {
+    return v8Frames.slice(0, maxFrames).join("\n");
+  }
+  const rnFrames = lines.filter((l) => l.includes("@") && !l.includes(" "));
+  if (rnFrames.length > 0) {
+    return rnFrames.slice(0, maxFrames).join("\n");
+  }
+  return void 0;
+}
+function captureException(client, error, options = {}) {
+  const {
+    handled = true,
+    level = "error",
+    includeStack = false,
+    maxStackFrames = 5,
+    maxMessageLength = 200,
+    ignorePatterns = [],
+    properties,
+    beforeCapture
+  } = options;
+  const normalized = normalizeError(error);
+  const rawMessage = normalized.message;
+  if (ignorePatterns.some((p) => p.test(rawMessage))) return;
+  let props = {
+    ...properties,
+    $error_message: rawMessage.slice(0, maxMessageLength),
+    $error_type: normalized.name,
+    $error_handled: handled,
+    $error_level: level
+  };
+  if (includeStack) {
+    const frames = extractStack(normalized.stack, maxStackFrames);
+    if (frames) props = { ...props, $error_stack: frames };
+  }
+  if (beforeCapture) {
+    const transformed = beforeCapture(props);
+    if (!transformed) return;
+    client.capture("$error", transformed);
+  } else {
+    client.capture("$error", props);
+  }
+}
+
 // src/LazyClient.ts
 function createLazyClient() {
   let _inner = null;
@@ -1525,6 +1637,25 @@ function createLazyClient() {
     getRegisteredProperties() {
       return _inner?.getRegisteredProperties() ?? {};
     },
+    // ── App metadata ──────────────────────────────────────────────────────────
+    setEnvironment(environment) {
+      _inner?.setEnvironment(environment);
+    },
+    setAppUpdate(update) {
+      _inner?.setAppUpdate(update);
+    },
+    setFeatures(features) {
+      _inner?.setFeatures(features);
+    },
+    setEntitlements(entitlements) {
+      _inner?.setEntitlements(entitlements);
+    },
+    setAppMetadata(meta) {
+      _inner?.setAppMetadata(meta);
+    },
+    getAppMetadata() {
+      return _inner?.getAppMetadata() ?? {};
+    },
     // ── Consent ───────────────────────────────────────────────────────────────
     async optIn() {
       await _inner?.optIn();
@@ -1601,6 +1732,7 @@ export {
   SunglassesCore,
   TraitManager,
   asTyped,
+  captureException,
   createLazyClient,
   createLogger,
   generateUUID,

package/package.json

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