@mukhy/mtn-telemetry-sdk 1.0.0 → 1.0.1

package/.github/workflows/node.js.yml

@@ -1,43 +1,29 @@
-name: Build, Test & Publish MTN Telemetry SDK
+name: Publish MTN Telemetry SDK to NPM
 
 on:
-  push:
-    branches: [ "master" ]
   release:
     types: [created]
 
 jobs:
   build:
     runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [20.19.4, 22.x]
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Remove package-lock.json (avoid warnings)
-        run: |
-          if [ -f package-lock.json ]; then
-            rm package-lock.json
-          fi
-
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'yarn'
+          node-version: 20
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: npm ci
 
       - name: Build SDK
-        run: yarn run clean && yarn run build
+        run: npm run build
 
       - name: Run tests
-        run: yarn run test
+        run: npm test
 
   publish:
     needs: build
@@ -50,32 +36,19 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Node.js for GitHub Packages
+      - name: Setup Node.js for NPM
         uses: actions/setup-node@v4
         with:
           node-version: 20
-          registry-url: https://npm.pkg.github.com/
-          scope: '@triplemcoder'
+          registry-url: https://registry.npmjs.org/
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: npm ci
 
       - name: Ensure package is public
         run: npm pkg set publishConfig.access=public
 
-      - name: Check if version is new
-        id: version-check
-        run: |
-          VERSION=$(node -p "require('./package.json').version")
-          echo "PACKAGE_VERSION=$VERSION" >> $GITHUB_ENV
-          # Attempt to fetch package info
-          if npm info @triplemcoder14/mtn-telemetry-sdk@$VERSION >/dev/null 2>&1; then
-            echo "Version $VERSION already exists, skipping publish"
-            exit 1
-          fi
-
-      - name: Publish to GitHub Packages
-        if: success()
+      - name: Publish to NPM
         run: npm publish
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,45 @@
+name: Build & Publish MTN Telemetry SDK to npm
+
+on:
+  release:
+    types: [created]
+  push:
+    branches:
+      - master
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: |
+          echo "Installing dependencies..."
+          npm install
+
+      - name: Build SDK
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Publish to npm
+        if: github.event_name == 'release'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          echo "Publishing version $(node -p "require('./package.json').version") to npm..."
+          npm publish --access public

package/README.md

@@ -1,146 +1,174 @@
-### MTN Telemetry SDK
-
-#### MTN Telemetry SDK is a lightweight OpenTelemetry wrapper for React and React Native applications, designed to help developers collect traces, metrics, and logs with minimal configuration
-
-### Features
-
-* Easy initialization for React and React Native apps
-* Automatic instrumentation for:
-  * Navigation
-  * API requests / network calls
-* Supports custom spans and metrics
-* TypeScript-ready, with type definitions
-* Compatible with GitHub Packages for easy installation
-
-
-#### Installation
-
-Install via npm:
-
-``npm install @triplemcoder14/mtn-telemetry-sdk
-``
-
-or via yarn:
-
-``yarn add @triplemcoder14/mtn-telemetry-sdk
-``
-
-**Make sure your project uses React >=18.0.0 and React Native >=0.72.0.**
-
-#### Getting Started
-
-1.  Initialize the SDK
-
-Create a file like src/telemetry/initTelemetry.ts:
-
-```import { MTNOTel } from 'mtn-telemetry-sdk';
-import { OTELRNOptions } from 'mtn-telemetry-sdk/dist/types';
-
-export function initTelemetry() {
-  const options: OTELRNOptions = {
-    serviceName: 'demo-app',
-    // Optional: exporter endpoint, environment, etc.
-  };
-
-  MTNOTel.init(options);
-  console.log('Telemetry initialized');
-}
-```
-
-2. Integrate in React / React Native App
-In your root component (e.g., App.tsx):
-
-```import React, { useEffect } from 'react';
-import { initTelemetry } from './telemetry/initTelemetry';
-import { NavigationContainer } from '@react-navigation/native';
-import MainStack from './screens/MainStack';
-
-export default function App() {
-  useEffect(() => {
-    initTelemetry();
-  }, []);
-
-  return (
-    <NavigationContainer>
-      <MainStack />
-    </NavigationContainer>
-  );
-}
-```
-
-3. Creating Custom Spans
-
-You can measure the performance of any async operation:
-
-```import { startSpan, endSpan } from 'mtn-telemetry-sdk';
-
-async function fetchUserData() {
-  const span = startSpan('fetch_user_data', { url: '/users' });
-  try {
-    const response = await fetch('/users');
-    const data = await response.json();
-    return data;
-  } finally {
-    endSpan(span);
-  }
-}
-```
-
-4. Automatic Navigation Instrumentation (Optional)
-If using React Navigation:
-
-```const navigationRef = useNavigationContainerRef();
-
-<NavigationContainer
-  ref={navigationRef}
-  onStateChange={() => {
-    const span = startSpan('navigation_change');
-    endSpan(span);
-  }}
->
-  <MainStack />
-</NavigationContainer>
-```
-
-
-Configuration Options
-
-The ``OTELRNOptions`` object can include:
-
-| Option        | Type   | Description                                   |
-| ------------- | ------ | --------------------------------------------- |
-| `serviceName` | string | Name of the service/app                       |
-| `environment` | string | Optional environment (prod/dev)               |
-| `endpoint`    | string | Optional OTLP/collector endpoint              |
-| `exporter`    | string | Optional exporter type (OTLP HTTP/gRPC, etc.) |
-
-
-Publishing & Versioning
-* The SDK is hosted on GitHub Packages:
-``npm install @triplemcoder/mtn-telemetry-sdk``
-
-Always increment ``version`` in ``package.json`` before publishing.
-
-Contributing
-1. Fork the repo
-2. Create a feature branch:
-   ``git checkout -b feature/my-feature``
-3. Commit changes
-4. Push branch and open a PR
-
-Example Usage in React Native
-
-```import { MTNOTel } from 'mtn-telemetry-sdk';
-
-MTNOTel.init({
-  serviceName: 'chequebase',
-  environment: 'production'
-});
-
-// Custom span for API request
-const span = MTNOTel.startSpan('fetch_users');
-// ...fetch API
-MTNOTel.endSpan(span);
-```
-
-
+### MTN Telemetry SDK
+
+#### MTN Telemetry SDK is a lightweight OpenTelemetry wrapper for React and React Native applications, designed to help developers collect traces, metrics, and logs with minimal configuration
+
+### Features
+
+* Easy initialization for React and React Native apps
+* Automatic instrumentation for:
+  * Navigation
+  * API requests / network calls
+* Supports custom spans and metrics
+* TypeScript-ready, with type definitions
+* Compatible with GitHub Packages for easy installation
+
+
+### Installation
+
+Install via npm:
+
+``npm i @mukhy/mtn-telemetry-sdk
+``
+
+or via yarn:
+
+``yarn add @mukhy/mtn-telemetry-sdk
+``
+
+**Make sure your project uses React >=18.0.0 and React Native >=0.72.0.**
+
+#### Getting Started
+
+1.  Initialize the SDK
+
+Create a file like src/telemetry/initTelemetry.ts:
+
+```
+import { MTNOTel } from 'mtn-telemetry-sdk';
+import type { OTelRNOptions } from 'mtn-telemetry-sdk/dist/types';
+
+export async function initTelemetry(navigationRef?: any) {
+  const options: OTelRNOptions = {
+    serviceName: 'demo-app',
+    environment: 'production',
+    navigationRef,
+    otlp: {
+      tracesUrl: 'https://collector.example.com/v1/traces',
+      headers: {
+        Authorization: 'Bearer example-token',
+      },
+    },
+  };
+
+  await MTNOTel.init(options);
+  console.log('Telemetry initialized');
+}
+```
+
+2. Integrate in React / React Native App
+In your root component (e.g., App.tsx):
+
+```
+import React, { useEffect, useRef } from 'react';
+import { initTelemetry } from './telemetry/initTelemetry';
+import { NavigationContainer } from '@react-navigation/native';
+import MainStack from './screens/MainStack';
+
+export default function App() {
+  const navigationRef = useRef(null);
+
+  useEffect(() => {
+    initTelemetry(navigationRef.current);
+  }, []);
+
+  return (
+    <NavigationContainer ref={navigationRef}>
+      <MainStack />
+    </NavigationContainer>
+  );
+}
+```
+
+3. Creating Custom Spans
+
+You can measure the performance of any async operation:
+
+```
+import { startSpan, endSpan } from 'mtn-telemetry-sdk';
+
+async function fetchUserData() {
+  const span = startSpan('fetch_user_data', { url: '/users' });
+  try {
+    const response = await fetch('/users');
+    const data = await response.json();
+    return data;
+  } finally {
+    endSpan(span);
+  }
+}
+```
+
+4. Automatic Navigation Instrumentation (Optional)
+If using React Navigation:
+
+```
+import { useNavigationContainerRef } from '@react-navigation/native';
+import { MTNOTel } from 'mtn-telemetry-sdk';
+
+const navigationRef = useNavigationContainerRef();
+
+useEffect(() => {
+  MTNOTel.attachNavigation(navigationRef);
+  return () => MTNOTel.detachNavigation();
+}, [navigationRef]);
+
+return (
+  <NavigationContainer ref={navigationRef}>
+    <MainStack />
+  </NavigationContainer>
+);
+```
+
+
+Configuration Options
+
+The ``OTELRNOptions`` object can include:
+
+| Option             | Type                    | Description                                                                  |
+| ------------------ | ----------------------- | ---------------------------------------------------------------------------- |
+| `serviceName`      | string                  | Required service name passed to the OpenTelemetry resource.                  |
+| `environment`      | string                  | Optional deployment environment tag (`dev`, `staging`, `prod`, …).           |
+| `release`          | string                  | Optional release/build identifier; falls back to `react-native-device-info`. |
+| `otlp`             | object                  | Optional OTLP exporter configuration.                                        |
+| `otlp.tracesUrl`   | string                  | Custom OTLP HTTP traces endpoint (defaults to `http://localhost:4318`).      |
+| `otlp.metricsUrl`  | string                  | Custom OTLP HTTP metrics endpoint.                                           |
+| `otlp.headers`     | Record<string, string>  | Headers injected into every OTLP export request.                             |
+| `enableFetch`      | boolean                 | Toggle automatic fetch instrumentation (defaults to `true`).                 |
+| `enableNavigation` | boolean                 | Toggle React Navigation instrumentation (defaults to `true`).                |
+| `enableAppState`   | boolean                 | Toggle React Native AppState spans and metrics (defaults to `true`).         |
+| `navigationRef`    | NavigationContainerLike | Optional navigation container to attach automatically during init.          |
+| `attributes`       | Record<string, unknown> | Extra resource attributes merged into the default OpenTelemetry resource.    |
+| `samplingRatio`    | number                  | Root sampler trace-id ratio (defaults to `1.0`).                             |
+
+Publishing & Versioning
+* The SDK is hosted on GitHub Packages:
+``npm install @triplemcoder/mtn-telemetry-sdk``
+
+Always increment ``version`` in ``package.json`` before publishing.
+
+Contributing
+1. Fork the repo
+2. Create a feature branch:
+   ``git checkout -b feature/my-feature``
+3. Commit changes
+4. Push branch and open a PR
+
+Example Usage in React Native
+
+```
+import { MTNOTel } from 'mtn-telemetry-sdk';
+
+MTNOTel.init({
+  serviceName: 'demo-app',
+  environment: 'production'
+});
+
+// Custom span for API request
+const span = MTNOTel.startSpan('fetch_users');
+// ...fetch API
+MTNOTel.endSpan(span);
+```
+
+
+
+

package/dist/context-manager/stack.d.ts

@@ -0,0 +1,10 @@
+import { Context, ContextManager } from '@opentelemetry/api';
+export declare class StackContextManager implements ContextManager {
+    private _stack;
+    private _enabled;
+    active(): Context;
+    with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(context: Context, fn: F, thisArg?: ThisParameterType<F>, ...args: A): ReturnType<F>;
+    bind<T>(context: Context, target: T): T;
+    enable(): this;
+    disable(): this;
+}

package/dist/context-manager/stack.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StackContextManager = void 0;
+const api_1 = require("@opentelemetry/api");
+class StackContextManager {
+    constructor() {
+        this._stack = [];
+        this._enabled = false;
+    }
+    active() {
+        return this._stack.length > 0 ? this._stack[this._stack.length - 1] : api_1.ROOT_CONTEXT;
+    }
+    with(context, fn, thisArg, ...args) {
+        if (!this._enabled) {
+            return fn.apply(thisArg, args);
+        }
+        this._stack.push(context);
+        try {
+            return fn.apply(thisArg, args);
+        }
+        finally {
+            this._stack.pop();
+        }
+    }
+    bind(context, target) {
+        if (!this._enabled) {
+            return target;
+        }
+        if (typeof target === 'function') {
+            const boundContextManager = this;
+            const boundFn = function bound(...args) {
+                return boundContextManager.with(context, target, this, ...args);
+            };
+            return boundFn;
+        }
+        return target;
+    }
+    enable() {
+        this._enabled = true;
+        return this;
+    }
+    disable() {
+        this._enabled = false;
+        this._stack = [];
+        return this;
+    }
+}
+exports.StackContextManager = StackContextManager;

package/dist/index.d.ts

@@ -1,7 +1,14 @@
-import type { OTelRNOptions } from './types';
+import type { NavigationContainerLike, OTelRNOptions } from './types';
 export declare class MTNOTel {
     private static _instance;
     private shutdownFns;
+    private navigation?;
+    private options;
     static init(opts: OTelRNOptions): Promise<MTNOTel>;
+    attachNavigation(ref: NavigationContainerLike | null): void;
+    detachNavigation(): void;
+    static attachNavigation(ref: NavigationContainerLike | null): void;
+    static detachNavigation(): void;
     flushAndShutdown(): Promise<void>;
 }
+export type { OTelRNOptions, NavigationContainerLike } from './types';

package/dist/index.js

@@ -1,44 +1,75 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MTNOTel = void 0;
+const api_1 = require("@opentelemetry/api");
 const providers_1 = require("./providers");
 const resource_1 = require("./resource");
+const app_state_1 = require("./instrumentations/app-state");
 const fetch_1 = require("./instrumentations/fetch");
 const react_nav_1 = require("./instrumentations/react-nav");
-const app_state_1 = require("./instrumentations/app-state");
-const api_1 = require("@opentelemetry/api");
 class MTNOTel {
     constructor() {
         this.shutdownFns = [];
     }
     static async init(opts) {
-        if (MTNOTel._instance)
+        var _a, _b, _c;
+        if (MTNOTel._instance) {
+            if (opts.navigationRef) {
+                MTNOTel._instance.attachNavigation(opts.navigationRef);
+            }
             return MTNOTel._instance;
+        }
+        const normalizedOptions = {
+            enableFetch: (_a = opts.enableFetch) !== null && _a !== void 0 ? _a : true,
+            enableNavigation: (_b = opts.enableNavigation) !== null && _b !== void 0 ? _b : true,
+            enableAppState: (_c = opts.enableAppState) !== null && _c !== void 0 ? _c : true,
+        };
         //  await and async resource builder
         const resource = await (0, resource_1.buildResource)(opts);
-        const { sdk, shutdown } = (0, providers_1.buildProviders)({ ...opts, resource });
+        const { shutdown } = (0, providers_1.buildProviders)({ ...opts, resource });
         const instance = new MTNOTel();
+        instance.options = normalizedOptions;
         instance.shutdownFns.push(shutdown);
         //  using otel api to get global tracer and meter
-        const tracer = api_1.trace.getTracer(opts.serviceName);
+        api_1.trace.getTracer(opts.serviceName);
         const meter = api_1.metrics.getMeter(opts.serviceName);
         // conditionally install instrumentation
-        if (opts.enableFetch) {
-            instance.shutdownFns.push((0, fetch_1.installFetchInstrumentation)(tracer));
+        if (normalizedOptions.enableFetch) {
+            instance.shutdownFns.push((0, fetch_1.installFetchInstrumentation)());
         }
-        if (opts.enableNavigation) {
-            instance.shutdownFns.push((0, react_nav_1.installReactNavigationInstrumentation)(tracer));
+        if (normalizedOptions.enableNavigation) {
+            instance.navigation = (0, react_nav_1.installReactNavigationInstrumentation)(opts.navigationRef);
+            instance.shutdownFns.push(instance.navigation.shutdown);
         }
-        if (opts.enableAppState) {
-            instance.shutdownFns.push((0, app_state_1.installAppStateInstrumentation)(tracer, meter));
+        if (normalizedOptions.enableAppState) {
+            instance.shutdownFns.push((0, app_state_1.installAppStateInstrumentation)(meter));
         }
         MTNOTel._instance = instance;
         return instance;
     }
+    attachNavigation(ref) {
+        var _a;
+        if (!this.options.enableNavigation)
+            return;
+        (_a = this.navigation) === null || _a === void 0 ? void 0 : _a.attach(ref);
+    }
+    detachNavigation() {
+        var _a;
+        (_a = this.navigation) === null || _a === void 0 ? void 0 : _a.detach();
+    }
+    static attachNavigation(ref) {
+        var _a;
+        (_a = MTNOTel._instance) === null || _a === void 0 ? void 0 : _a.attachNavigation(ref);
+    }
+    static detachNavigation() {
+        var _a;
+        (_a = MTNOTel._instance) === null || _a === void 0 ? void 0 : _a.detachNavigation();
+    }
     async flushAndShutdown() {
         for (const fn of this.shutdownFns) {
             await fn();
         }
+        MTNOTel._instance = null;
     }
 }
 exports.MTNOTel = MTNOTel;

package/dist/instrumentations/app-state.d.ts

@@ -4,4 +4,4 @@ import { type Meter } from '@opentelemetry/api';
  * triplemcoder14
  * enters foreground/background and emits spans + metrics.
  */
-export declare function installAppStateInstrumentation(_tracerProvider: any, meter: Meter): () => Promise<void>;
+export declare function installAppStateInstrumentation(meter: Meter): () => Promise<void>;