@mukhy/mtn-telemetry-sdk 1.0.0

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

@@ -0,0 +1,81 @@
+name: Build, Test & Publish MTN Telemetry SDK
+
+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'
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build SDK
+        run: yarn run clean && yarn run build
+
+      - name: Run tests
+        run: yarn run test
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js for GitHub Packages
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://npm.pkg.github.com/
+          scope: '@triplemcoder'
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - 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()
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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

@@ -0,0 +1,53 @@
+name: Publish MTN Telemetry SDK to GitHub Packages
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js for GitHub Packages
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://npm.pkg.github.com/
+          scope: '@triplemcoder14'   # Replace with your GitHub username or org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Make package public
+        run: |
+          # Ensure package.json has a valid public package
+          npm pkg set publishConfig.access=public
+
+      - name: Publish to GitHub Packages
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -0,0 +1,146 @@
+### 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);
+```
+
+

package/__test__/demo-test.js

@@ -0,0 +1,3 @@
+import { MTNOTel } from '@triplemcoder14/mtn-telemetry-sdk';
+
+MTNOTel.init({ serviceName: 'demo-app' });

package/__test__/test-runner.js

@@ -0,0 +1,54 @@
+// --- this mocks react-native-device-info ---
+require.cache[require.resolve('react-native-device-info')] = {
+  exports: {
+    getVersion: () => '1.0.0',
+    getManufacturerSync: () => 'MockBrand',
+    getModel: () => 'MockPhone',
+    getSystemName: () => 'MockOS',
+    getSystemVersion: () => '1.0',
+    getBundleId: () => 'com.mock.app',
+    getBuildNumber: () => '100',
+    isEmulatorSync: () => true,
+  },
+};
+
+require.cache[require.resolve('react-native')] = {
+  exports: {
+    Platform: { OS: 'ios', Version: '1.0.0', select: (obj) => obj.ios },
+    NativeModules: {},
+  },
+};
+
+// --- import the built sdk ---
+const { MTNOTel } = require('../dist/index');
+
+// --- Run the SDK init + shutdown test ---
+(async () => {
+  try {
+    const sdk = MTNOTel.init({
+      serviceName: 'mtn-test-service',
+      otlp: {
+        tracesUrl: 'http://localhost:4318/v1/traces',
+        metricsUrl: 'http://localhost:4318/v1/metrics',
+        headers: {},
+      },
+      environment: 'dev',
+      release: '1.0.0',
+      enableFetch: true,
+      enableNavigation: false,
+      enableAppState: true,
+      samplingRatio: 1.0,
+    });
+
+    console.log(' MTNOTel SDK initialized successfully.');
+
+    // simulate app running
+    await new Promise((r) => setTimeout(r, 5000));
+
+    await sdk.flushAndShutdown();
+    console.log(' SDK flushed and shut down gracefully.');
+  } catch (err) {
+    console.error(' Test  failed:', err);
+  }
+})();
+

package/__test__/test.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+
+const src_1 = require("./src"); //
+console.log('SDK test output:', (0, src_1.someFunction)());

package/apps/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Mon Oct 13 14:19:15 WAT 2025
+gradle.version=8.9

package/apps/build.gradle

@@ -0,0 +1,14 @@
+android {
+    namespace "com.mtntelemetrydemo"
+    compileSdkVersion rootProject.ext.compileSdkVersion
+
+    defaultConfig {
+        applicationId "com.mtntelemetrydemo"
+        minSdkVersion rootProject.ext.minSdkVersion
+        targetSdkVersion rootProject.ext.targetSdkVersion
+        versionCode 1
+        versionName "1.0"
+    }
+    ...
+}
+

package/dist/business.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import { PressableProps } from 'react-native';
+/**
+ * BusinessTracer — captures business journeys and steps
+ */
+export declare class BusinessTracer {
+    private static currentJourney?;
+    /**
+     * Start a business journey (e.g. "UserOnboarding", "PurchaseFlow")
+     */
+    static start(journeyName: string, attrs?: Record<string, any>): void;
+    /**
+     * Record a business step within a journey (e.g. "PaymentAuthorized")
+     */
+    static step(stepName: string, attrs?: Record<string, any>): void;
+    /**
+     * Complete a business journey
+     */
+    static complete(attrs?: Record<string, any>): void;
+}
+/**
+ * TrackedPressable — wraps a Pressable and records user interactions as steps
+ */
+export declare function TrackedPressable({ onPress, accessibilityLabel, children, ...rest }: PressableProps & {
+    children?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/business.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BusinessTracer = void 0;
+exports.TrackedPressable = TrackedPressable;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_native_1 = require("react-native");
+const api_1 = require("@opentelemetry/api");
+/**
+ * BusinessTracer — captures business journeys and steps
+ */
+class BusinessTracer {
+    /**
+     * Start a business journey (e.g. "UserOnboarding", "PurchaseFlow")
+     */
+    static start(journeyName, attrs = {}) {
+        const tracer = api_1.trace.getTracer('mtn-sdk:business');
+        const span = tracer.startSpan(`Journey ${journeyName}`, {
+            kind: api_1.SpanKind.INTERNAL,
+            attributes: {
+                'business.journey': journeyName,
+                ...attrs,
+            },
+        });
+        this.currentJourney = { name: journeyName, startTime: Date.now() };
+        span.end(); // parent marker span; steps are separate child spans
+    }
+    /**
+     * Record a business step within a journey (e.g. "PaymentAuthorized")
+     */
+    static step(stepName, attrs = {}) {
+        var _a, _b;
+        const tracer = api_1.trace.getTracer('mtn-sdk:business');
+        const journey = (_b = (_a = this.currentJourney) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : 'unknown';
+        const span = tracer.startSpan(`Step ${stepName}`, {
+            kind: api_1.SpanKind.INTERNAL,
+            attributes: {
+                'business.journey': journey,
+                'business.step': stepName,
+                ...attrs,
+            },
+        });
+        span.end();
+    }
+    /**
+     * Complete a business journey
+     */
+    static complete(attrs = {}) {
+        var _a, _b;
+        const tracer = api_1.trace.getTracer('mtn-sdk:business');
+        const journey = (_b = (_a = this.currentJourney) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : 'unknown';
+        const dur = this.currentJourney
+            ? Date.now() - this.currentJourney.startTime
+            : undefined;
+        const span = tracer.startSpan(`Journey ${journey} Complete`, {
+            kind: api_1.SpanKind.INTERNAL,
+            attributes: {
+                'business.journey': journey,
+                'business.completed': true,
+                'business.duration_ms': dur,
+                ...attrs,
+            },
+        });
+        span.end();
+        this.currentJourney = undefined;
+    }
+}
+exports.BusinessTracer = BusinessTracer;
+/**
+ * TrackedPressable — wraps a Pressable and records user interactions as steps
+ */
+function TrackedPressable({ onPress, accessibilityLabel, children, ...rest }) {
+    const label = accessibilityLabel ||
+        (typeof children === 'string' ? children : 'pressable');
+    const handlePress = (e) => {
+        BusinessTracer.step(`tap:${label}`);
+        onPress === null || onPress === void 0 ? void 0 : onPress(e);
+    };
+    return ((0, jsx_runtime_1.jsx)(react_native_1.Pressable, { ...rest, onPress: handlePress, children: children }));
+}

package/dist/context.d.ts

@@ -0,0 +1,3 @@
+import { SpanKind } from '@opentelemetry/api';
+export declare function startActiveSpan<T>(name: string, fn: (span: any) => Promise<T> | T, kind?: SpanKind): Promise<T>;
+export declare function withParent<T>(parentContext: import("@opentelemetry/api").Context | undefined, fn: () => T): T;

package/dist/context.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startActiveSpan = startActiveSpan;
+exports.withParent = withParent;
+const api_1 = require("@opentelemetry/api");
+function startActiveSpan(name, fn, kind = api_1.SpanKind.INTERNAL) {
+    const tracer = api_1.trace.getTracer('mtn-sdk');
+    return tracer.startActiveSpan(name, { kind }, async (span) => {
+        var _a, _b;
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            (_a = span.recordException) === null || _a === void 0 ? void 0 : _a.call(span, err);
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: String((_b = err === null || err === void 0 ? void 0 : err.message) !== null && _b !== void 0 ? _b : err) });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+function withParent(parentContext = api_1.context.active(), fn) {
+    return api_1.context.with(parentContext, fn);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { OTelRNOptions } from './types';
+export declare class MTNOTel {
+    private static _instance;
+    private shutdownFns;
+    static init(opts: OTelRNOptions): Promise<MTNOTel>;
+    flushAndShutdown(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MTNOTel = void 0;
+const providers_1 = require("./providers");
+const resource_1 = require("./resource");
+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)
+            return MTNOTel._instance;
+        //  await and async resource builder
+        const resource = await (0, resource_1.buildResource)(opts);
+        const { sdk, shutdown } = (0, providers_1.buildProviders)({ ...opts, resource });
+        const instance = new MTNOTel();
+        instance.shutdownFns.push(shutdown);
+        //  using otel api to get global tracer and meter
+        const tracer = 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 (opts.enableNavigation) {
+            instance.shutdownFns.push((0, react_nav_1.installReactNavigationInstrumentation)(tracer));
+        }
+        if (opts.enableAppState) {
+            instance.shutdownFns.push((0, app_state_1.installAppStateInstrumentation)(tracer, meter));
+        }
+        MTNOTel._instance = instance;
+        return instance;
+    }
+    async flushAndShutdown() {
+        for (const fn of this.shutdownFns) {
+            await fn();
+        }
+    }
+}
+exports.MTNOTel = MTNOTel;
+MTNOTel._instance = null;

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

@@ -0,0 +1,7 @@
+import { type Meter } from '@opentelemetry/api';
+/**
+ * instruments react native appstate to record when the app
+ * triplemcoder14
+ * enters foreground/background and emits spans + metrics.
+ */
+export declare function installAppStateInstrumentation(_tracerProvider: any, meter: Meter): () => Promise<void>;

package/dist/instrumentations/app-state.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installAppStateInstrumentation = installAppStateInstrumentation;
+const react_native_1 = require("react-native");
+const api_1 = require("@opentelemetry/api");
+/**
+ * instruments react native appstate to record when the app
+ * triplemcoder14
+ * enters foreground/background and emits spans + metrics.
+ */
+function installAppStateInstrumentation(_tracerProvider, meter) {
+    const tracer = api_1.trace.getTracer('mtn-sdk:appstate');
+    const fgCounter = meter.createCounter('app.foreground.count');
+    const bgCounter = meter.createCounter('app.background.count');
+    let lastState = react_native_1.AppState.currentState;
+    const sub = react_native_1.AppState.addEventListener('change', (state) => {
+        if (state === 'active' && lastState !== 'active') {
+            fgCounter.add(1);
+            tracer.startActiveSpan('App Foreground', { kind: api_1.SpanKind.INTERNAL }, (span) => span.end());
+        }
+        else if ((state === 'background' || state === 'inactive') && lastState === 'active') {
+            bgCounter.add(1);
+            tracer.startActiveSpan('App Background', { kind: api_1.SpanKind.INTERNAL }, (span) => span.end());
+        }
+        lastState = state;
+    });
+    // return a cleanup function
+    return async () => {
+        sub.remove();
+    };
+}
+// import { AppState } from 'react-native';
+// import { trace, SpanKind } from '@opentelemetry/api';
+// import type { MeterProvider } from '@opentelemetry/sdk-metrics';
+//
+//
+// export function installAppStateInstrumentation(_tracerProvider: any, meterProvider: MeterProvider) {
+// const tracer = trace.getTracer('mtn-sdk:appstate');
+// const meter = meterProvider.getMeter('mtn-sdk:appstate');
+// const fgCounter = meter.createCounter('app.foreground.count');
+// const bgCounter = meter.createCounter('app.background.count');
+//
+//
+// let lastState = AppState.currentState;
+// const sub = AppState.addEventListener('change', (state) => {
+// if (state === 'active' && lastState !== 'active') {
+// fgCounter.add(1);
+// tracer.startActiveSpan('App Foreground', { kind: SpanKind.INTERNAL }, (span) => span.end());
+// } else if ((state === 'background' || state === 'inactive') && lastState === 'active') {
+// bgCounter.add(1);
+// tracer.startActiveSpan('App Background', { kind: SpanKind.INTERNAL }, (span) => span.end());
+// }
+// lastState = state as any;
+// });
+//
+//
+// return async () => { sub.remove(); };
+// }

package/dist/instrumentations/fetch.d.ts

@@ -0,0 +1 @@
+export declare function installFetchInstrumentation(_tracerProvider: any): () => Promise<void>;