@drakkar.software/dk-spaces-analytics-sdk 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @drakkar.software/dk-spaces-analytics-sdk
+
+Generic telemetry client setup for dk-spaces apps — detailed error catching/upload and manually-triggered event capture, via [SunGlasses](https://github.com/Drakkar-Software/SunGlasses) wired to a Starfish transport. Not headless — ships React provider + error boundary.
+
+## Installation
+
+```bash
+pnpm add @drakkar.software/dk-spaces-analytics-sdk
+```
+
+Optional native peer deps (Expo / React Native only):
+
+```bash
+npx expo install @drakkar.software/sunglasses-react-native @drakkar.software/sunglasses-storage-async-storage
+```
+
+Metro resolves `.native.ts`/`.native.tsx` automatically — no conditional imports needed in app code.
+
+## Setup
+
+```ts
+import { createTelemetry, createTelemetryClient } from '@drakkar.software/dk-spaces-analytics-sdk';
+
+// Module-level lazy singleton — safe to call capture()/captureException() before init() resolves.
+export const telemetry = createTelemetryClient();
+
+const client = await createTelemetry({
+  syncBaseUrl: process.env.EXPO_PUBLIC_STARFISH_URL, // base host, NOT including /v1
+  app: 'octochat',
+  environment: process.env.NODE_ENV,
+});
+telemetry.init(client);
+```
+
+## Manual capture
+
+```ts
+import { captureException } from '@drakkar.software/dk-spaces-analytics-sdk';
+
+telemetry.capture('message_sent', { threadId });
+
+try {
+  risky();
+} catch (err) {
+  captureException(telemetry, err, { handled: true });
+}
+```
+
+Unhandled errors and render-phase crashes don't need `captureException` — `<TelemetryProvider>` captures those automatically.
+
+## React wiring
+
+```tsx
+import { TelemetryProvider } from '@drakkar.software/dk-spaces-analytics-sdk';
+
+export default function App({ children }) {
+  return (
+    <TelemetryProvider client={client} fallback={<CrashScreen />}>
+      {children}
+    </TelemetryProvider>
+  );
+}
+```
+
+`TelemetryProvider` composes SunGlasses' `<SunglassesProvider>` (global `error`/`unhandledrejection` handlers + console patching) with `<SunglassesGlobalErrorBoundary>` (render-phase fallback UI) — no double-capture.
+
+Screen tracking:
+
+```ts
+import { useTelemetryScreenTracking } from '@drakkar.software/dk-spaces-analytics-sdk';
+
+useTelemetryScreenTracking(client); // History API (web) / Expo Router pathname (native)
+```
+
+## `TelemetryConfig`
+
+| Field | Default | Notes |
+|---|---|---|
+| `syncBaseUrl` | — | Starfish base host. Must **not** include `/v1` — `StarfishClient` prepends it. |
+| `app` | — | Embedded in the Starfish storage path. |
+| `namespace` | `'analytics'` | Starfish namespace for the analytics silo. |
+| `pathTemplate` | `'/push/events/{app}/{batchId}'` | Must keep the `/push/` prefix — `push()` only auto-prepends `/v1/{namespace}`. |
+| `defaultOptIn` | `true` | Events flow immediately, no consent gate. |
+| `debug` | `false` | Verbose console logging — never enable in production. |
+
+## Peer dependencies
+
+```
+react                                          >=18.0.0
+@drakkar.software/starfish-client              >=3.0.0-alpha.43
+@drakkar.software/sunglasses-react-native       >=0.14.0  (optional, native only)
+@drakkar.software/sunglasses-storage-async-storage >=0.9.1  (optional, native only)
+react-native                                    >=0.73.0  (optional, native only)
+```
+
+## ESM only
+
+This package ships ESM only. Requires a bundler (Vite, Metro, etc.).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { ISunglassesClient, CaptureExceptionOptions, EventMap, ISunglassesTypedClient } from '@drakkar.software/sunglasses-core';
+export { CaptureExceptionOptions, ISunglassesClient, SunglassesEvent } from '@drakkar.software/sunglasses-core';
+import React from 'react';
+export { useSunglasses as useTelemetry } from '@drakkar.software/sunglasses-react';
+
+/**
+ * Shared, platform-agnostic telemetry surface — no React, no storage/transport
+ * wiring. Re-exported by both `index.ts` (web) and `index.native.ts` (native).
+ */
+
+/** Config accepted by `createTelemetry()` (web) / `createTelemetry()` (native). */
+interface TelemetryConfig {
+    /** Starfish sync base URL, e.g. `https://sync.example.com/v1`. */
+    syncBaseUrl: string;
+    /** App/workspace identifier embedded in the Starfish storage path. Keep short and URL-safe. */
+    app: string;
+    /** Starfish namespace for the analytics silo. Default: `'analytics'`. */
+    namespace?: string;
+    /**
+     * Starfish storage-path template. Default: `'/push/events/{app}/{batchId}'`.
+     * Must keep the `/push/` prefix — `StarfishClient.push()` does not add it, only
+     * `/v1/{namespace}` is prepended automatically.
+     */
+    pathTemplate?: string;
+    appName?: string;
+    appVersion?: string;
+    /** Deployment environment, e.g. `'production'` | `'staging'`. */
+    environment?: string;
+    /** Default: `true` — events flow immediately with no consent gate. */
+    defaultOptIn?: boolean;
+    /** Enables verbose console logging. Never enable in production. Default: `false`. */
+    debug?: boolean;
+}
+/**
+ * Module-level telemetry singleton factory. Every method is a safe no-op until
+ * `.init(client)` is called with the client returned by `createTelemetry()` —
+ * so call-sites can `capture()` / `captureException()` at any time, including
+ * before initialization resolves.
+ */
+declare function createTelemetryClient<T extends EventMap = Record<string, Record<string, unknown> | undefined>>(): ISunglassesTypedClient<T> & {
+    init(client: ISunglassesClient): void;
+};
+/**
+ * Manually capture a handled exception as a `$error` event (detailed error
+ * catching + upload). Thin wrapper over SunGlasses' `captureException` —
+ * defaults `handled: true`. Safe to call on a not-yet-initialized lazy client
+ * (from `createTelemetryClient()`), which silently no-ops.
+ *
+ * Unhandled errors and render-phase crashes don't need this call — they're
+ * captured automatically by `<TelemetryProvider>`.
+ */
+declare function captureException(client: ISunglassesClient, error: unknown, options?: CaptureExceptionOptions): void;
+
+/**
+ * Build an initialized SunGlasses client wired to Starfish + `localStorage`.
+ *
+ * Pair with `createTelemetryClient()` + `.init(client)` for the module-level
+ * lazy-singleton pattern (safe to call `capture()` before this resolves).
+ */
+declare function createTelemetry(config: TelemetryConfig): Promise<ISunglassesClient>;
+
+/**
+ * Web telemetry provider — composes SunGlasses' `<SunglassesProvider>`
+ * (auto error capture + auto screen tracking) with
+ * `<SunglassesGlobalErrorBoundary>` (render-phase + fatal global error
+ * fallback UI), mirroring the pattern used in OctoChat's `app/_layout.tsx`.
+ * Mirrors `provider.native.tsx` — same props, same behavior, native swaps in
+ * `@drakkar.software/sunglasses-react-native`.
+ */
+
+interface TelemetryProviderProps {
+    /** An initialized client — from `createTelemetry()` (after `.init()` on the lazy client). */
+    client: ISunglassesClient;
+    /** Rendered instead of the crashed tree on an uncaught render or fatal global error. */
+    fallback?: React.ReactNode;
+    children: React.ReactNode;
+}
+/**
+ * Wrap the app root. Enables automatic capture + upload of unhandled errors
+ * (global handlers + `console.error`) and renders `fallback` on a fatal
+ * crash. For manually-triggered captures, use `captureException()` or a
+ * typed `.capture()` call on the client from `createTelemetry()`.
+ */
+declare function TelemetryProvider({ client, fallback, children, }: TelemetryProviderProps): React.ReactElement;
+
+/** Automatic screen-view tracking via the browser History API. */
+declare function useTelemetryScreenTracking(client: ISunglassesClient): void;
+
+export { type TelemetryConfig, TelemetryProvider, type TelemetryProviderProps, captureException, createTelemetry, createTelemetryClient, useTelemetryScreenTracking };

package/dist/index.js

@@ -0,0 +1,70 @@
+// src/telemetry.ts
+import { SunglassesCore } from "@drakkar.software/sunglasses-core";
+import { LocalStorageAdapter } from "@drakkar.software/sunglasses-storage-localstorage";
+import { StarfishAnalyticsAdapter } from "@drakkar.software/sunglasses-adapter-starfish";
+import { StarfishClient } from "@drakkar.software/starfish-client";
+var DEFAULT_NAMESPACE = "analytics";
+var DEFAULT_PATH_TEMPLATE = "/push/events/{app}/{batchId}";
+async function createTelemetry(config) {
+  const syncClient = new StarfishClient({
+    baseUrl: config.syncBaseUrl,
+    namespace: config.namespace ?? DEFAULT_NAMESPACE
+  });
+  return SunglassesCore.create({
+    storage: new LocalStorageAdapter(),
+    adapters: [
+      new StarfishAnalyticsAdapter({
+        client: syncClient,
+        app: config.app,
+        pathTemplate: config.pathTemplate ?? DEFAULT_PATH_TEMPLATE
+      })
+    ],
+    platform: "web",
+    appName: config.appName,
+    appVersion: config.appVersion,
+    environment: config.environment,
+    defaultOptIn: config.defaultOptIn ?? true,
+    enableSessionTracking: true,
+    debug: config.debug ?? false
+  });
+}
+
+// src/events.ts
+import {
+  createLazyClient,
+  captureException as sgCaptureException
+} from "@drakkar.software/sunglasses-core";
+function createTelemetryClient() {
+  return createLazyClient();
+}
+function captureException(client, error, options) {
+  sgCaptureException(client, error, options);
+}
+
+// src/provider.tsx
+import React from "react";
+import {
+  SunglassesProvider,
+  SunglassesGlobalErrorBoundary,
+  useSunglasses,
+  useScreenTracking
+} from "@drakkar.software/sunglasses-react";
+function TelemetryProvider({
+  client,
+  fallback,
+  children
+}) {
+  return /* @__PURE__ */ React.createElement(SunglassesProvider, { client, autoCaptureErrors: { globalHandlers: true, console: true } }, /* @__PURE__ */ React.createElement(SunglassesGlobalErrorBoundary, { fallback, includeNonFatalGlobalErrors: true }, children));
+}
+function useTelemetryScreenTracking(client) {
+  useScreenTracking(client);
+}
+export {
+  TelemetryProvider,
+  captureException,
+  createTelemetry,
+  createTelemetryClient,
+  useSunglasses as useTelemetry,
+  useTelemetryScreenTracking
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/telemetry.ts","../src/events.ts","../src/provider.tsx"],"sourcesContent":["/**\n * Web telemetry client factory — SunGlasses core wired to a Starfish\n * event-push transport and `localStorage` persistence. Mirrors\n * `telemetry.native.ts` (native swaps in `AsyncStorage`) — storage is the\n * only real web/native difference; everything else is shared.\n */\nimport { SunglassesCore } from '@drakkar.software/sunglasses-core';\nimport type { ISunglassesClient } from '@drakkar.software/sunglasses-core';\nimport { LocalStorageAdapter } from '@drakkar.software/sunglasses-storage-localstorage';\nimport { StarfishAnalyticsAdapter } from '@drakkar.software/sunglasses-adapter-starfish';\nimport { StarfishClient } from '@drakkar.software/starfish-client';\nimport type { TelemetryConfig } from './events.js';\n\nconst DEFAULT_NAMESPACE = 'analytics';\n// StarfishClient.push() does NOT add the /push/ prefix; only /v1/{namespace} is\n// prepended by applyNamespace(). Keep /push/ explicit to reach the events collection.\nconst DEFAULT_PATH_TEMPLATE = '/push/events/{app}/{batchId}';\n\n/**\n * Build an initialized SunGlasses client wired to Starfish + `localStorage`.\n *\n * Pair with `createTelemetryClient()` + `.init(client)` for the module-level\n * lazy-singleton pattern (safe to call `capture()` before this resolves).\n */\nexport async function createTelemetry(config: TelemetryConfig): Promise<ISunglassesClient> {\n  const syncClient = new StarfishClient({\n    baseUrl: config.syncBaseUrl,\n    namespace: config.namespace ?? DEFAULT_NAMESPACE,\n  });\n\n  return SunglassesCore.create({\n    storage: new LocalStorageAdapter(),\n    adapters: [\n      new StarfishAnalyticsAdapter({\n        client: syncClient,\n        app: config.app,\n        pathTemplate: config.pathTemplate ?? DEFAULT_PATH_TEMPLATE,\n      }),\n    ],\n    platform: 'web',\n    appName: config.appName,\n    appVersion: config.appVersion,\n    environment: config.environment,\n    defaultOptIn: config.defaultOptIn ?? true,\n    enableSessionTracking: true,\n    debug: config.debug ?? false,\n  });\n}\n","/**\n * Shared, platform-agnostic telemetry surface — no React, no storage/transport\n * wiring. Re-exported by both `index.ts` (web) and `index.native.ts` (native).\n */\nimport {\n  createLazyClient,\n  captureException as sgCaptureException,\n  type CaptureExceptionOptions,\n  type ISunglassesClient,\n  type ISunglassesTypedClient,\n  type EventMap,\n  type SunglassesEvent,\n} from '@drakkar.software/sunglasses-core';\n\nexport type { CaptureExceptionOptions, ISunglassesClient, SunglassesEvent };\n\n/** Config accepted by `createTelemetry()` (web) / `createTelemetry()` (native). */\nexport interface TelemetryConfig {\n  /** Starfish sync base URL, e.g. `https://sync.example.com/v1`. */\n  syncBaseUrl: string;\n  /** App/workspace identifier embedded in the Starfish storage path. Keep short and URL-safe. */\n  app: string;\n  /** Starfish namespace for the analytics silo. Default: `'analytics'`. */\n  namespace?: string;\n  /**\n   * Starfish storage-path template. Default: `'/push/events/{app}/{batchId}'`.\n   * Must keep the `/push/` prefix — `StarfishClient.push()` does not add it, only\n   * `/v1/{namespace}` is prepended automatically.\n   */\n  pathTemplate?: string;\n  appName?: string;\n  appVersion?: string;\n  /** Deployment environment, e.g. `'production'` | `'staging'`. */\n  environment?: string;\n  /** Default: `true` — events flow immediately with no consent gate. */\n  defaultOptIn?: boolean;\n  /** Enables verbose console logging. Never enable in production. Default: `false`. */\n  debug?: boolean;\n}\n\n/**\n * Module-level telemetry singleton factory. Every method is a safe no-op until\n * `.init(client)` is called with the client returned by `createTelemetry()` —\n * so call-sites can `capture()` / `captureException()` at any time, including\n * before initialization resolves.\n */\nexport function createTelemetryClient<\n  T extends EventMap = Record<string, Record<string, unknown> | undefined>,\n>(): ISunglassesTypedClient<T> & { init(client: ISunglassesClient): void } {\n  return createLazyClient<T>();\n}\n\n/**\n * Manually capture a handled exception as a `$error` event (detailed error\n * catching + upload). Thin wrapper over SunGlasses' `captureException` —\n * defaults `handled: true`. Safe to call on a not-yet-initialized lazy client\n * (from `createTelemetryClient()`), which silently no-ops.\n *\n * Unhandled errors and render-phase crashes don't need this call — they're\n * captured automatically by `<TelemetryProvider>`.\n */\nexport function captureException(\n  client: ISunglassesClient,\n  error: unknown,\n  options?: CaptureExceptionOptions,\n): void {\n  sgCaptureException(client, error, options);\n}\n","/**\n * Web telemetry provider — composes SunGlasses' `<SunglassesProvider>`\n * (auto error capture + auto screen tracking) with\n * `<SunglassesGlobalErrorBoundary>` (render-phase + fatal global error\n * fallback UI), mirroring the pattern used in OctoChat's `app/_layout.tsx`.\n * Mirrors `provider.native.tsx` — same props, same behavior, native swaps in\n * `@drakkar.software/sunglasses-react-native`.\n */\nimport React from 'react';\nimport {\n  SunglassesProvider,\n  SunglassesGlobalErrorBoundary,\n  useSunglasses,\n  useScreenTracking,\n} from '@drakkar.software/sunglasses-react';\nimport type { ISunglassesClient } from '@drakkar.software/sunglasses-core';\n\nexport interface TelemetryProviderProps {\n  /** An initialized client — from `createTelemetry()` (after `.init()` on the lazy client). */\n  client: ISunglassesClient;\n  /** Rendered instead of the crashed tree on an uncaught render or fatal global error. */\n  fallback?: React.ReactNode;\n  children: React.ReactNode;\n}\n\n/**\n * Wrap the app root. Enables automatic capture + upload of unhandled errors\n * (global handlers + `console.error`) and renders `fallback` on a fatal\n * crash. For manually-triggered captures, use `captureException()` or a\n * typed `.capture()` call on the client from `createTelemetry()`.\n */\nexport function TelemetryProvider({\n  client,\n  fallback,\n  children,\n}: TelemetryProviderProps): React.ReactElement {\n  return (\n    <SunglassesProvider client={client} autoCaptureErrors={{ globalHandlers: true, console: true }}>\n      <SunglassesGlobalErrorBoundary fallback={fallback} includeNonFatalGlobalErrors>\n        {children}\n      </SunglassesGlobalErrorBoundary>\n    </SunglassesProvider>\n  );\n}\n\n/** Access the telemetry client provided by the nearest `<TelemetryProvider>`. */\nexport { useSunglasses as useTelemetry };\n\n/** Automatic screen-view tracking via the browser History API. */\nexport function useTelemetryScreenTracking(client: ISunglassesClient): void {\n  useScreenTracking(client);\n}\n"],"mappings":";AAMA,SAAS,sBAAsB;AAE/B,SAAS,2BAA2B;AACpC,SAAS,gCAAgC;AACzC,SAAS,sBAAsB;AAG/B,IAAM,oBAAoB;AAG1B,IAAM,wBAAwB;AAQ9B,eAAsB,gBAAgB,QAAqD;AACzF,QAAM,aAAa,IAAI,eAAe;AAAA,IACpC,SAAS,OAAO;AAAA,IAChB,WAAW,OAAO,aAAa;AAAA,EACjC,CAAC;AAED,SAAO,eAAe,OAAO;AAAA,IAC3B,SAAS,IAAI,oBAAoB;AAAA,IACjC,UAAU;AAAA,MACR,IAAI,yBAAyB;AAAA,QAC3B,QAAQ;AAAA,QACR,KAAK,OAAO;AAAA,QACZ,cAAc,OAAO,gBAAgB;AAAA,MACvC,CAAC;AAAA,IACH;AAAA,IACA,UAAU;AAAA,IACV,SAAS,OAAO;AAAA,IAChB,YAAY,OAAO;AAAA,IACnB,aAAa,OAAO;AAAA,IACpB,cAAc,OAAO,gBAAgB;AAAA,IACrC,uBAAuB;AAAA,IACvB,OAAO,OAAO,SAAS;AAAA,EACzB,CAAC;AACH;;;AC3CA;AAAA,EACE;AAAA,EACA,oBAAoB;AAAA,OAMf;AAkCA,SAAS,wBAE2D;AACzE,SAAO,iBAAoB;AAC7B;AAWO,SAAS,iBACd,QACA,OACA,SACM;AACN,qBAAmB,QAAQ,OAAO,OAAO;AAC3C;;;AC3DA,OAAO,WAAW;AAClB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAiBA,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AACF,GAA+C;AAC7C,SACE,oCAAC,sBAAmB,QAAgB,mBAAmB,EAAE,gBAAgB,MAAM,SAAS,KAAK,KAC3F,oCAAC,iCAA8B,UAAoB,6BAA2B,QAC3E,QACH,CACF;AAEJ;AAMO,SAAS,2BAA2B,QAAiC;AAC1E,oBAAkB,MAAM;AAC1B;","names":[]}

package/dist/index.native.d.ts

@@ -0,0 +1,87 @@
+import { ISunglassesClient, CaptureExceptionOptions, EventMap, ISunglassesTypedClient } from '@drakkar.software/sunglasses-core';
+export { CaptureExceptionOptions, ISunglassesClient, SunglassesEvent } from '@drakkar.software/sunglasses-core';
+import React from 'react';
+export { useSunglasses as useTelemetry } from '@drakkar.software/sunglasses-react-native';
+
+/**
+ * Shared, platform-agnostic telemetry surface — no React, no storage/transport
+ * wiring. Re-exported by both `index.ts` (web) and `index.native.ts` (native).
+ */
+
+/** Config accepted by `createTelemetry()` (web) / `createTelemetry()` (native). */
+interface TelemetryConfig {
+    /** Starfish sync base URL, e.g. `https://sync.example.com/v1`. */
+    syncBaseUrl: string;
+    /** App/workspace identifier embedded in the Starfish storage path. Keep short and URL-safe. */
+    app: string;
+    /** Starfish namespace for the analytics silo. Default: `'analytics'`. */
+    namespace?: string;
+    /**
+     * Starfish storage-path template. Default: `'/push/events/{app}/{batchId}'`.
+     * Must keep the `/push/` prefix — `StarfishClient.push()` does not add it, only
+     * `/v1/{namespace}` is prepended automatically.
+     */
+    pathTemplate?: string;
+    appName?: string;
+    appVersion?: string;
+    /** Deployment environment, e.g. `'production'` | `'staging'`. */
+    environment?: string;
+    /** Default: `true` — events flow immediately with no consent gate. */
+    defaultOptIn?: boolean;
+    /** Enables verbose console logging. Never enable in production. Default: `false`. */
+    debug?: boolean;
+}
+/**
+ * Module-level telemetry singleton factory. Every method is a safe no-op until
+ * `.init(client)` is called with the client returned by `createTelemetry()` —
+ * so call-sites can `capture()` / `captureException()` at any time, including
+ * before initialization resolves.
+ */
+declare function createTelemetryClient<T extends EventMap = Record<string, Record<string, unknown> | undefined>>(): ISunglassesTypedClient<T> & {
+    init(client: ISunglassesClient): void;
+};
+/**
+ * Manually capture a handled exception as a `$error` event (detailed error
+ * catching + upload). Thin wrapper over SunGlasses' `captureException` —
+ * defaults `handled: true`. Safe to call on a not-yet-initialized lazy client
+ * (from `createTelemetryClient()`), which silently no-ops.
+ *
+ * Unhandled errors and render-phase crashes don't need this call — they're
+ * captured automatically by `<TelemetryProvider>`.
+ */
+declare function captureException(client: ISunglassesClient, error: unknown, options?: CaptureExceptionOptions): void;
+
+/**
+ * Build an initialized SunGlasses client wired to Starfish + `AsyncStorage`.
+ *
+ * Pair with `createTelemetryClient()` + `.init(client)` for the module-level
+ * lazy-singleton pattern (safe to call `capture()` before this resolves).
+ */
+declare function createTelemetry(config: TelemetryConfig): Promise<ISunglassesClient>;
+
+/**
+ * Native telemetry provider. Mirrors `provider.tsx` — swaps in
+ * `@drakkar.software/sunglasses-react-native`'s provider/boundary. Screen
+ * tracking uses Expo Router's pathname instead of the History API.
+ */
+
+interface TelemetryProviderProps {
+    /** An initialized client — from `createTelemetry()` (after `.init()` on the lazy client). */
+    client: ISunglassesClient;
+    /** Rendered instead of the crashed tree on an uncaught render or fatal global error. */
+    fallback?: React.ReactNode;
+    children: React.ReactNode;
+}
+/**
+ * Wrap the app root (typically `app/_layout.tsx`). Enables automatic capture
+ * + upload of unhandled errors (global handlers + `console.error`) and
+ * renders `fallback` on a fatal crash. For manually-triggered captures, use
+ * `captureException()` or a typed `.capture()` call on the client from
+ * `createTelemetry()`.
+ */
+declare function TelemetryProvider({ client, fallback, children, }: TelemetryProviderProps): React.ReactElement;
+
+/** Requires `expo-router`. Call once, inside your root `_layout.tsx`. */
+declare function useTelemetryScreenTracking(client: ISunglassesClient): void;
+
+export { type TelemetryConfig, TelemetryProvider, type TelemetryProviderProps, captureException, createTelemetry, createTelemetryClient, useTelemetryScreenTracking };

package/dist/index.native.js

@@ -0,0 +1,70 @@
+// src/telemetry.native.ts
+import { SunglassesCore } from "@drakkar.software/sunglasses-core";
+import { AsyncStorageAdapter } from "@drakkar.software/sunglasses-storage-async-storage";
+import { StarfishAnalyticsAdapter } from "@drakkar.software/sunglasses-adapter-starfish";
+import { StarfishClient } from "@drakkar.software/starfish-client";
+var DEFAULT_NAMESPACE = "analytics";
+var DEFAULT_PATH_TEMPLATE = "/push/events/{app}/{batchId}";
+async function createTelemetry(config) {
+  const syncClient = new StarfishClient({
+    baseUrl: config.syncBaseUrl,
+    namespace: config.namespace ?? DEFAULT_NAMESPACE
+  });
+  return SunglassesCore.create({
+    storage: new AsyncStorageAdapter(),
+    adapters: [
+      new StarfishAnalyticsAdapter({
+        client: syncClient,
+        app: config.app,
+        pathTemplate: config.pathTemplate ?? DEFAULT_PATH_TEMPLATE
+      })
+    ],
+    platform: "react-native",
+    appName: config.appName,
+    appVersion: config.appVersion,
+    environment: config.environment,
+    defaultOptIn: config.defaultOptIn ?? true,
+    enableSessionTracking: true,
+    debug: config.debug ?? false
+  });
+}
+
+// src/events.ts
+import {
+  createLazyClient,
+  captureException as sgCaptureException
+} from "@drakkar.software/sunglasses-core";
+function createTelemetryClient() {
+  return createLazyClient();
+}
+function captureException(client, error, options) {
+  sgCaptureException(client, error, options);
+}
+
+// src/provider.native.tsx
+import React from "react";
+import {
+  SunglassesProvider,
+  SunglassesGlobalErrorBoundary,
+  useSunglasses,
+  useExpoRouterScreenTracking
+} from "@drakkar.software/sunglasses-react-native";
+function TelemetryProvider({
+  client,
+  fallback,
+  children
+}) {
+  return /* @__PURE__ */ React.createElement(SunglassesProvider, { client, autoCaptureErrors: { globalHandlers: true, console: true } }, /* @__PURE__ */ React.createElement(SunglassesGlobalErrorBoundary, { fallback, includeNonFatalGlobalErrors: true }, children));
+}
+function useTelemetryScreenTracking(client) {
+  useExpoRouterScreenTracking(client);
+}
+export {
+  TelemetryProvider,
+  captureException,
+  createTelemetry,
+  createTelemetryClient,
+  useSunglasses as useTelemetry,
+  useTelemetryScreenTracking
+};
+//# sourceMappingURL=index.native.js.map

package/dist/index.native.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/telemetry.native.ts","../src/events.ts","../src/provider.native.tsx"],"sourcesContent":["/**\n * Native telemetry client factory — SunGlasses core wired to a Starfish\n * event-push transport and `AsyncStorage` persistence. Mirrors `telemetry.ts`\n * (web uses `localStorage`) — storage is the only real web/native difference;\n * everything else is shared.\n */\nimport { SunglassesCore } from '@drakkar.software/sunglasses-core';\nimport type { ISunglassesClient } from '@drakkar.software/sunglasses-core';\n// @ts-ignore — optional peer dep; only present in native builds\nimport { AsyncStorageAdapter } from '@drakkar.software/sunglasses-storage-async-storage';\nimport { StarfishAnalyticsAdapter } from '@drakkar.software/sunglasses-adapter-starfish';\nimport { StarfishClient } from '@drakkar.software/starfish-client';\nimport type { TelemetryConfig } from './events.js';\n\nconst DEFAULT_NAMESPACE = 'analytics';\n// StarfishClient.push() does NOT add the /push/ prefix; only /v1/{namespace} is\n// prepended by applyNamespace(). Keep /push/ explicit to reach the events collection.\nconst DEFAULT_PATH_TEMPLATE = '/push/events/{app}/{batchId}';\n\n/**\n * Build an initialized SunGlasses client wired to Starfish + `AsyncStorage`.\n *\n * Pair with `createTelemetryClient()` + `.init(client)` for the module-level\n * lazy-singleton pattern (safe to call `capture()` before this resolves).\n */\nexport async function createTelemetry(config: TelemetryConfig): Promise<ISunglassesClient> {\n  const syncClient = new StarfishClient({\n    baseUrl: config.syncBaseUrl,\n    namespace: config.namespace ?? DEFAULT_NAMESPACE,\n  });\n\n  return SunglassesCore.create({\n    storage: new AsyncStorageAdapter(),\n    adapters: [\n      new StarfishAnalyticsAdapter({\n        client: syncClient,\n        app: config.app,\n        pathTemplate: config.pathTemplate ?? DEFAULT_PATH_TEMPLATE,\n      }),\n    ],\n    platform: 'react-native',\n    appName: config.appName,\n    appVersion: config.appVersion,\n    environment: config.environment,\n    defaultOptIn: config.defaultOptIn ?? true,\n    enableSessionTracking: true,\n    debug: config.debug ?? false,\n  });\n}\n","/**\n * Shared, platform-agnostic telemetry surface — no React, no storage/transport\n * wiring. Re-exported by both `index.ts` (web) and `index.native.ts` (native).\n */\nimport {\n  createLazyClient,\n  captureException as sgCaptureException,\n  type CaptureExceptionOptions,\n  type ISunglassesClient,\n  type ISunglassesTypedClient,\n  type EventMap,\n  type SunglassesEvent,\n} from '@drakkar.software/sunglasses-core';\n\nexport type { CaptureExceptionOptions, ISunglassesClient, SunglassesEvent };\n\n/** Config accepted by `createTelemetry()` (web) / `createTelemetry()` (native). */\nexport interface TelemetryConfig {\n  /** Starfish sync base URL, e.g. `https://sync.example.com/v1`. */\n  syncBaseUrl: string;\n  /** App/workspace identifier embedded in the Starfish storage path. Keep short and URL-safe. */\n  app: string;\n  /** Starfish namespace for the analytics silo. Default: `'analytics'`. */\n  namespace?: string;\n  /**\n   * Starfish storage-path template. Default: `'/push/events/{app}/{batchId}'`.\n   * Must keep the `/push/` prefix — `StarfishClient.push()` does not add it, only\n   * `/v1/{namespace}` is prepended automatically.\n   */\n  pathTemplate?: string;\n  appName?: string;\n  appVersion?: string;\n  /** Deployment environment, e.g. `'production'` | `'staging'`. */\n  environment?: string;\n  /** Default: `true` — events flow immediately with no consent gate. */\n  defaultOptIn?: boolean;\n  /** Enables verbose console logging. Never enable in production. Default: `false`. */\n  debug?: boolean;\n}\n\n/**\n * Module-level telemetry singleton factory. Every method is a safe no-op until\n * `.init(client)` is called with the client returned by `createTelemetry()` —\n * so call-sites can `capture()` / `captureException()` at any time, including\n * before initialization resolves.\n */\nexport function createTelemetryClient<\n  T extends EventMap = Record<string, Record<string, unknown> | undefined>,\n>(): ISunglassesTypedClient<T> & { init(client: ISunglassesClient): void } {\n  return createLazyClient<T>();\n}\n\n/**\n * Manually capture a handled exception as a `$error` event (detailed error\n * catching + upload). Thin wrapper over SunGlasses' `captureException` —\n * defaults `handled: true`. Safe to call on a not-yet-initialized lazy client\n * (from `createTelemetryClient()`), which silently no-ops.\n *\n * Unhandled errors and render-phase crashes don't need this call — they're\n * captured automatically by `<TelemetryProvider>`.\n */\nexport function captureException(\n  client: ISunglassesClient,\n  error: unknown,\n  options?: CaptureExceptionOptions,\n): void {\n  sgCaptureException(client, error, options);\n}\n","/**\n * Native telemetry provider. Mirrors `provider.tsx` — swaps in\n * `@drakkar.software/sunglasses-react-native`'s provider/boundary. Screen\n * tracking uses Expo Router's pathname instead of the History API.\n */\nimport React from 'react';\nimport {\n  SunglassesProvider,\n  SunglassesGlobalErrorBoundary,\n  useSunglasses,\n  useExpoRouterScreenTracking,\n} from '@drakkar.software/sunglasses-react-native';\nimport type { ISunglassesClient } from '@drakkar.software/sunglasses-core';\n\nexport interface TelemetryProviderProps {\n  /** An initialized client — from `createTelemetry()` (after `.init()` on the lazy client). */\n  client: ISunglassesClient;\n  /** Rendered instead of the crashed tree on an uncaught render or fatal global error. */\n  fallback?: React.ReactNode;\n  children: React.ReactNode;\n}\n\n/**\n * Wrap the app root (typically `app/_layout.tsx`). Enables automatic capture\n * + upload of unhandled errors (global handlers + `console.error`) and\n * renders `fallback` on a fatal crash. For manually-triggered captures, use\n * `captureException()` or a typed `.capture()` call on the client from\n * `createTelemetry()`.\n */\nexport function TelemetryProvider({\n  client,\n  fallback,\n  children,\n}: TelemetryProviderProps): React.ReactElement {\n  return (\n    <SunglassesProvider client={client} autoCaptureErrors={{ globalHandlers: true, console: true }}>\n      <SunglassesGlobalErrorBoundary fallback={fallback} includeNonFatalGlobalErrors>\n        {children}\n      </SunglassesGlobalErrorBoundary>\n    </SunglassesProvider>\n  );\n}\n\n/** Access the telemetry client provided by the nearest `<TelemetryProvider>`. */\nexport { useSunglasses as useTelemetry };\n\n/** Requires `expo-router`. Call once, inside your root `_layout.tsx`. */\nexport function useTelemetryScreenTracking(client: ISunglassesClient): void {\n  useExpoRouterScreenTracking(client);\n}\n"],"mappings":";AAMA,SAAS,sBAAsB;AAG/B,SAAS,2BAA2B;AACpC,SAAS,gCAAgC;AACzC,SAAS,sBAAsB;AAG/B,IAAM,oBAAoB;AAG1B,IAAM,wBAAwB;AAQ9B,eAAsB,gBAAgB,QAAqD;AACzF,QAAM,aAAa,IAAI,eAAe;AAAA,IACpC,SAAS,OAAO;AAAA,IAChB,WAAW,OAAO,aAAa;AAAA,EACjC,CAAC;AAED,SAAO,eAAe,OAAO;AAAA,IAC3B,SAAS,IAAI,oBAAoB;AAAA,IACjC,UAAU;AAAA,MACR,IAAI,yBAAyB;AAAA,QAC3B,QAAQ;AAAA,QACR,KAAK,OAAO;AAAA,QACZ,cAAc,OAAO,gBAAgB;AAAA,MACvC,CAAC;AAAA,IACH;AAAA,IACA,UAAU;AAAA,IACV,SAAS,OAAO;AAAA,IAChB,YAAY,OAAO;AAAA,IACnB,aAAa,OAAO;AAAA,IACpB,cAAc,OAAO,gBAAgB;AAAA,IACrC,uBAAuB;AAAA,IACvB,OAAO,OAAO,SAAS;AAAA,EACzB,CAAC;AACH;;;AC5CA;AAAA,EACE;AAAA,EACA,oBAAoB;AAAA,OAMf;AAkCA,SAAS,wBAE2D;AACzE,SAAO,iBAAoB;AAC7B;AAWO,SAAS,iBACd,QACA,OACA,SACM;AACN,qBAAmB,QAAQ,OAAO,OAAO;AAC3C;;;AC9DA,OAAO,WAAW;AAClB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAkBA,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AACF,GAA+C;AAC7C,SACE,oCAAC,sBAAmB,QAAgB,mBAAmB,EAAE,gBAAgB,MAAM,SAAS,KAAK,KAC3F,oCAAC,iCAA8B,UAAoB,6BAA2B,QAC3E,QACH,CACF;AAEJ;AAMO,SAAS,2BAA2B,QAAiC;AAC1E,8BAA4B,MAAM;AACpC;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@drakkar.software/dk-spaces-analytics-sdk",
+  "version": "0.1.0",
+  "description": "Generic telemetry client setup for dk-spaces apps — detailed error catching/upload and manually-triggered event capture, via SunGlasses wired to a Starfish transport.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "react-native": {
+        "types": "./dist/index.native.d.ts",
+        "import": "./dist/index.native.js"
+      },
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@drakkar.software/sunglasses-core": "^0.14.0",
+    "@drakkar.software/sunglasses-adapter-starfish": "^0.9.2",
+    "@drakkar.software/sunglasses-storage-localstorage": "^0.9.1",
+    "@drakkar.software/sunglasses-react": "^0.14.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "@drakkar.software/starfish-client": ">=3.0.0-alpha.43",
+    "@drakkar.software/sunglasses-react-native": ">=0.14.0",
+    "@drakkar.software/sunglasses-storage-async-storage": ">=0.9.1",
+    "react-native": ">=0.73.0"
+  },
+  "peerDependenciesMeta": {
+    "@drakkar.software/sunglasses-react-native": {
+      "optional": true
+    },
+    "@drakkar.software/sunglasses-storage-async-storage": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@drakkar.software/starfish-client": "3.0.0-alpha.65",
+    "@drakkar.software/sunglasses-react-native": "0.14.0",
+    "@drakkar.software/sunglasses-storage-async-storage": "0.9.1",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.0.0",
+    "react": "19.2.7",
+    "tsup": "^8.3.0",
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}