react-native-test-adx 0.1.13 → 0.1.14

package/README.md

@@ -75,9 +75,15 @@ Pass `configuration` to `AdaxonProvider`, or to `Adaxon.initialize()` when not u
 | `storage` | No | In-memory | Persists offline event queue and anonymous id |
 | `timeoutMs` | No | `10000` | HTTP timeout in ms |
 | `testMode` | No | `false` | Sets `sdk_version` to `{version}-test` when true |
+| `activityLogging` | No | `false` | When true, records SDK diagnostics to Sentry (testing/debugging) |
+| `sentryDsn` | No | — | Sentry DSN when `activityLogging` is true and the host app has not initialized Sentry |
 
 Only `appId` and `sdkKey` are required. Do not pass a tracker URL — the SDK owns the host and API paths.
 
+For Sentry activity logging, install the optional peer dependency `@sentry/react-native` in the host app.
+
+Activities are emitted primarily as **Sentry structured logs** (`enableLogs: true` when the SDK initializes Sentry). Breadcrumbs are added only for `warn`/`error` to enrich captured issues. If structured logging is unavailable (for example an older host Sentry client), a small set of milestone activities may use `captureMessage` instead so they still appear independently without flooding issue volume.
+
 The SDK attaches `device`, `app`, `user.anonymous_id`, and network fields automatically. Do not pass them in event calls.
 
 ### Persistent storage (optional)

package/lib/module/AdaxonSdk.js

@@ -7,6 +7,7 @@ import { AdaxonSdkError } from "./errors/AdaxonSdkError.js";
 import { detectReactNativePlatform, reactNativeAppInfoReader, reactNativeDeviceReader, reactNativeNetworkInfoReader, reactNativeNetworkStatusReader, reactNativeUrlOpener } from "./platform/reactNative.js";
 import { buildAddToCartProperties, buildPurchaseProperties, normalizeEventValues } from "./services/event/normalizeProperties.js";
 import { AdxEvent } from "./services/event/predefined.js";
+import { AdaxonLogger, logSdkActivity } from "./services/logging/AdaxonLogger.js";
 function openableOfferUrl(url) {
   return url.replace(/[{}]/g, brace => brace === '{' ? '%7B' : '%7D');
 }
@@ -18,11 +19,26 @@ export class AdaxonSdk {
     return this.client !== null;
   }
   async initialize(configuration, listener) {
+    const platform = detectReactNativePlatform();
+    AdaxonLogger.configure({
+      enabled: Boolean(configuration.activityLogging),
+      dsn: configuration.sentryDsn,
+      platform,
+      testMode: Boolean(configuration.testMode)
+    });
+    logSdkActivity({
+      eventName: 'sdk.initialize.started',
+      level: 'info',
+      metadata: {
+        app_id: configuration.appId,
+        test_mode: Boolean(configuration.testMode)
+      }
+    });
     try {
       const previous = this.client;
       const client = new AdaxonClient({
         ...configuration,
-        platform: detectReactNativePlatform(),
+        platform,
         deviceInfoReader: reactNativeDeviceReader,
         appInfoReader: reactNativeAppInfoReader,
         networkInfoReader: reactNativeNetworkInfoReader,
@@ -32,15 +48,31 @@ export class AdaxonSdk {
       previous?.destroy();
       this.client = client;
       this.testMode = Boolean(configuration.testMode);
+      logSdkActivity({
+        eventName: 'sdk.initialize.completed',
+        level: 'info',
+        metadata: {
+          network_available: client.isNetworkAvailable()
+        }
+      });
       listener?.onInitializationComplete();
       if (client.isNetworkAvailable()) {
         client.processPendingEvents().catch(() => undefined);
       }
     } catch (error) {
-      this.destroy();
       const message = AdaxonSdkError.messageOf(error, 'Initialization failed.');
       const code = error instanceof AdaxonSdkError && error.code === 'INVALID_CONFIG' ? 'INVALID_CONFIG' : 'UNKNOWN';
+      logSdkActivity({
+        eventName: 'sdk.initialize.failed',
+        level: code === 'INVALID_CONFIG' ? 'warn' : 'error',
+        metadata: {
+          error_code: code
+        },
+        error,
+        captureAsEvent: code !== 'INVALID_CONFIG'
+      });
       listener?.onInitializationFailed(code, message);
+      this.destroy();
       throw error;
     }
   }
@@ -75,6 +107,10 @@ export class AdaxonSdk {
     return this.logEvent(AdxEvent.COMPLETE_REGISTRATION, params, options);
   }
   async showAd(options = {}) {
+    logSdkActivity({
+      eventName: 'ad.show.started',
+      level: 'info'
+    });
     try {
       const {
         offers,
@@ -82,6 +118,13 @@ export class AdaxonSdk {
       } = await this.loadRecommendations();
       if (offers.length === 0) {
         console.warn('[Adaxon] No offer available.');
+        logSdkActivity({
+          eventName: 'ad.show.failed',
+          level: 'info',
+          metadata: {
+            reason: 'no_offer'
+          }
+        });
         return {
           shown: false,
           reason: 'no_offer'
@@ -91,6 +134,13 @@ export class AdaxonSdk {
       const offer = offers.find(item => !excluded.has(item.offer_id));
       if (!offer) {
         console.warn('[Adaxon] No eligible offer available.');
+        logSdkActivity({
+          eventName: 'ad.show.failed',
+          level: 'info',
+          metadata: {
+            reason: 'no_eligible_offer'
+          }
+        });
         return {
           shown: false,
           reason: 'no_eligible_offer'
@@ -100,11 +150,34 @@ export class AdaxonSdk {
         const displayed = presentInterstitial({
           offer,
           interact: () => {
+            logSdkActivity({
+              eventName: 'ad.click',
+              level: 'info',
+              metadata: {
+                offer_id: offer.offer_id
+              }
+            });
             this.openOfferUrl(offer, requestEventId).then(() => options.onOfferClicked?.(offer.offer_id)).catch(error => {
               console.warn('[Adaxon] Failed to open offer URL.', AdaxonSdkError.messageOf(error, 'Failed to open offer.'));
+              logSdkActivity({
+                eventName: 'ad.click.failed',
+                level: 'warn',
+                metadata: {
+                  offer_id: offer.offer_id
+                },
+                error
+              });
             });
           },
           onDismiss: dismissReason => {
+            logSdkActivity({
+              eventName: 'ad.dismissed',
+              level: 'info',
+              metadata: {
+                offer_id: offer.offer_id,
+                dismiss_reason: dismissReason
+              }
+            });
             resolve({
               shown: true,
               offerId: offer.offer_id,
@@ -114,16 +187,38 @@ export class AdaxonSdk {
         });
         if (!displayed) {
           console.warn('[Adaxon] Interstitial host is not mounted. Wrap the app in AdaxonProvider.');
+          logSdkActivity({
+            eventName: 'ad.show.failed',
+            level: 'warn',
+            metadata: {
+              reason: 'not_mounted'
+            }
+          });
           resolve({
             shown: false,
             reason: 'not_mounted'
           });
           return;
         }
+        logSdkActivity({
+          eventName: 'ad.displayed',
+          level: 'info',
+          metadata: {
+            offer_id: offer.offer_id
+          }
+        });
         this.trackRecommendationEvent(CREATIVE_VIEW_EVENT, requestEventId).catch(() => undefined);
       });
     } catch (error) {
       console.warn('[Adaxon] Failed to show ad.', AdaxonSdkError.messageOf(error, 'Failed to show ad.'));
+      logSdkActivity({
+        eventName: 'ad.show.failed',
+        level: 'warn',
+        metadata: {
+          error_code: error instanceof AdaxonSdkError ? error.code : 'UNKNOWN'
+        },
+        error
+      });
       if (this.testMode) {
         throw error;
       }
@@ -137,11 +232,16 @@ export class AdaxonSdk {
     return this.client?.isNetworkAvailable() ?? false;
   }
   destroy() {
+    logSdkActivity({
+      eventName: 'sdk.destroyed',
+      level: 'debug'
+    });
     dismissInterstitial();
     dismissOfferBrowser();
     this.client?.destroy();
     this.client = null;
     this.testMode = false;
+    AdaxonLogger.reset();
   }
   loadRecommendations() {
     return this.requireClient().getRecommendations({
@@ -153,8 +253,22 @@ export class AdaxonSdk {
     await this.trackRecommendationEvent(CREATIVE_CLICK_EVENT, parentEventId);
     const offerUrl = openableOfferUrl(offer.offer_url);
     if (presentOfferBrowser(offerUrl)) {
+      logSdkActivity({
+        eventName: 'ad.offer_browser.opened',
+        level: 'debug',
+        metadata: {
+          offer_id: offer.offer_id
+        }
+      });
       return;
     }
+    logSdkActivity({
+      eventName: 'ad.offer_url.opened',
+      level: 'debug',
+      metadata: {
+        offer_id: offer.offer_id
+      }
+    });
     await reactNativeUrlOpener.openURL(offerUrl);
     dismissInterstitial('click');
   }
@@ -165,8 +279,23 @@ export class AdaxonSdk {
       }, {
         eventType: RECOMMENDATION_EVENT_TYPE
       });
+      logSdkActivity({
+        eventName: eventName === CREATIVE_VIEW_EVENT ? 'ad.impression.tracked' : 'ad.click.tracked',
+        level: 'debug',
+        metadata: {
+          parent_event_id: parentEventId
+        }
+      });
     } catch (error) {
       console.warn(`[Adaxon] Failed to log ${eventName}.`, AdaxonSdkError.messageOf(error, `Failed to log ${eventName}.`));
+      logSdkActivity({
+        eventName: 'tracking.recommendation_event.failed',
+        level: 'warn',
+        metadata: {
+          mts_event_name: eventName
+        },
+        error
+      });
     }
   }
   requireClient() {

package/lib/module/core/AdaxonClient.js

@@ -12,6 +12,7 @@ import { ApiClient } from "../services/network/ApiClient.js";
 import { NetworkInfoService } from "../services/network/NetworkInfoService.js";
 import { NetworkService } from "../services/network/NetworkService.js";
 import { EventQueueStorage } from "../storage/EventQueueStorage.js";
+import { logSdkActivity } from "../services/logging/AdaxonLogger.js";
 import { EventValidator } from "../validation/EventValidator.js";
 export class AdaxonClient {
   started = false;
@@ -73,6 +74,13 @@ export class AdaxonClient {
     }
     this.validator.validateBatch(events);
     const payloads = await Promise.all(events.map(event => this.builder.build(event)));
+    logSdkActivity({
+      eventName: 'tracking.events.queued_offline',
+      level: 'info',
+      metadata: {
+        event_count: payloads.length
+      }
+    });
     for (const payload of payloads) {
       await this.eventQueue.add(payload);
     }

package/lib/module/sdkVersion.js

@@ -1,4 +1,4 @@
 "use strict";
 
 /** Keep in sync with package.json "version" (published npm packages ship lib/ only). */
-export const SDK_VERSION = '0.1.13';
+export const SDK_VERSION = '0.1.14';

package/lib/module/services/authentication/AuthenticationService.js

@@ -2,6 +2,7 @@
 
 import { DEFAULT_TIMEOUT_MS } from "../../config/ApiConstants.js";
 import { AdaxonSdkError } from "../../errors/AdaxonSdkError.js";
+import { logSdkActivity } from "../logging/AdaxonLogger.js";
 export class AuthenticationService {
   constructor(config) {
     this.validateConfig(config);
@@ -21,6 +22,13 @@ export class AuthenticationService {
     }
   }
   fail(message) {
+    logSdkActivity({
+      eventName: 'sdk.config.invalid',
+      level: 'warn',
+      metadata: {
+        reason: message
+      }
+    });
     throw new AdaxonSdkError('INVALID_CONFIG', message);
   }
 }

package/lib/module/services/event/BatchProcessor.js

@@ -2,6 +2,7 @@
 
 import { MAX_BATCH_SIZE } from "../../config/ApiConstants.js";
 import { AdaxonSdkError } from "../../errors/AdaxonSdkError.js";
+import { logSdkActivity } from "../logging/AdaxonLogger.js";
 const TEMPORARY_FAILURE_CODES = new Set(['NETWORK_ERROR', 'TIMEOUT', 'HTTP_ERROR', 'AUTHENTICATION_ERROR']);
 export class BatchProcessor {
   constructor(config) {
@@ -10,14 +11,30 @@ export class BatchProcessor {
   }
   async process() {
     if (!this.queue.tryAcquireProcessorLock()) {
+      logSdkActivity({
+        eventName: 'tracking.queue.processor.busy',
+        level: 'debug'
+      });
       return this.result('already_processing');
     }
     let batchesSent = 0;
     let eventsProcessed = 0;
+    logSdkActivity({
+      eventName: 'tracking.queue.processor.started',
+      level: 'debug'
+    });
     try {
       while (true) {
         const events = await this.queue.getNextBatch(MAX_BATCH_SIZE);
         if (events.length === 0) {
+          logSdkActivity({
+            eventName: 'tracking.queue.processor.completed',
+            level: 'debug',
+            metadata: {
+              batches_sent: batchesSent,
+              events_processed: eventsProcessed
+            }
+          });
           return this.result('completed', {
             batchesSent,
             eventsProcessed
@@ -42,8 +59,26 @@ export class BatchProcessor {
     }
   }
   stopped(batchesSent, eventsProcessed, events, error) {
-    if (error !== undefined && !(error instanceof AdaxonSdkError && TEMPORARY_FAILURE_CODES.has(error.code))) {
-      console.error('[Adaxon] Batch processor failed unexpectedly', error);
+    if (error !== undefined) {
+      const temporaryFailure = error instanceof AdaxonSdkError && TEMPORARY_FAILURE_CODES.has(error.code);
+      if (!temporaryFailure) {
+        console.error('[Adaxon] Batch processor failed unexpectedly', error);
+      }
+      logSdkActivity({
+        eventName: temporaryFailure ? 'tracking.queue.processor.stopped' : 'tracking.queue.processor.failed',
+        level: temporaryFailure ? 'warn' : 'error',
+        metadata: {
+          batches_sent: batchesSent,
+          events_processed: eventsProcessed,
+          ...(temporaryFailure ? {
+            error_code: error instanceof AdaxonSdkError ? error.code : 'UNKNOWN'
+          } : {})
+        },
+        error,
+        ...(!temporaryFailure ? {
+          captureAsEvent: true
+        } : {})
+      });
     }
     return this.result('stopped', {
       batchesSent,

package/lib/module/services/event/EventService.js

@@ -2,6 +2,7 @@
 
 import { EVENT_TRACKING_PATH, RECOMMENDATION_EVENT_TYPE, RECOMMENDATION_REQUEST_EVENT, RECOMMENDATION_RESPONSE_EVENT, RECOMMENDATIONS_PATH } from "../../config/ApiConstants.js";
 import { AdaxonSdkError } from "../../errors/AdaxonSdkError.js";
+import { logSdkActivity } from "../logging/AdaxonLogger.js";
 export class EventService {
   constructor(config) {
     this.api = config.api;
@@ -10,14 +11,35 @@ export class EventService {
   }
   async trackBatch(events) {
     this.validator.validateBatch(events);
+    logSdkActivity({
+      eventName: 'tracking.batch.processing',
+      level: 'debug',
+      metadata: {
+        event_count: events.length
+      }
+    });
     const payloads = await Promise.all(events.map(event => this.builder.build(event)));
-    return this.postEvents(payloads);
+    const response = await this.postEvents(payloads);
+    logSdkActivity({
+      eventName: 'tracking.batch.completed',
+      level: 'debug',
+      metadata: {
+        event_count: events.length,
+        accepted: response.accepted,
+        rejected: response.rejected
+      }
+    });
+    return response;
   }
   sendPayloads(payloads) {
     this.validator.validateBatch(payloads);
     return this.postEvents(payloads);
   }
   async getRecommendations(properties = {}) {
+    logSdkActivity({
+      eventName: 'recommendation.request.started',
+      level: 'info'
+    });
     const requestEvent = await this.builder.build({
       eventName: RECOMMENDATION_REQUEST_EVENT,
       eventType: RECOMMENDATION_EVENT_TYPE,
@@ -31,8 +53,24 @@ export class EventService {
       }
     });
     if (!Array.isArray(response.offers)) {
-      throw new AdaxonSdkError('HTTP_ERROR', 'Adaxon recommendation response is missing the offers array.');
+      const error = new AdaxonSdkError('HTTP_ERROR', 'Adaxon recommendation response is missing the offers array.');
+      logSdkActivity({
+        eventName: 'recommendation.response.invalid',
+        level: 'warn',
+        metadata: {
+          error_code: error.code
+        },
+        error
+      });
+      throw error;
     }
+    logSdkActivity({
+      eventName: 'recommendation.response.received',
+      level: 'info',
+      metadata: {
+        offer_count: response.offers.length
+      }
+    });
     await this.postEvents([await this.builder.build({
       eventName: RECOMMENDATION_RESPONSE_EVENT,
       eventType: RECOMMENDATION_EVENT_TYPE,
@@ -40,6 +78,13 @@ export class EventService {
         parent_event_id: requestEvent.event_id
       }
     })]);
+    logSdkActivity({
+      eventName: 'recommendation.processing.completed',
+      level: 'debug',
+      metadata: {
+        offer_count: response.offers.length
+      }
+    });
     return {
       offers: response.offers,
       requestEventId: requestEvent.event_id

package/lib/module/services/logging/AdaxonLogger.js

@@ -0,0 +1,227 @@
+"use strict";
+
+import { SDK_VERSION } from "../../sdkVersion.js";
+import { AdaxonSdkError } from "../../errors/AdaxonSdkError.js";
+import { sanitizeLogMetadata } from "./sanitizeLogMetadata.js";
+const DEFAULT_LEVEL = 'info';
+
+/** Milestone events that fall back to captureMessage when structured logs are unavailable. */
+const MESSAGE_FALLBACK_EVENTS = new Set(['sdk.initialize.completed', 'sdk.initialize.failed', 'recommendation.response.received', 'ad.displayed', 'ad.show.failed']);
+/** undefined = not loaded yet; null = unavailable in this app bundle */
+let cachedSentryModule;
+let missingSentryPeerWarningShown = false;
+const SENTRY_UNAVAILABLE_HINT = 'Bundled @sentry/react-native could not be loaded. Reinstall react-native-adaxon dependencies and rebuild the native app.';
+function loadSentryModule() {
+  if (cachedSentryModule !== undefined) {
+    return cachedSentryModule;
+  }
+  try {
+    const loaded = require('@sentry/react-native');
+    cachedSentryModule = loaded && typeof loaded.init === 'function' ? loaded : loaded.default ?? null;
+  } catch {
+    cachedSentryModule = null;
+  }
+  return cachedSentryModule;
+}
+function warnSentryUnavailableOnce(hasDsn) {
+  if (!hasDsn || missingSentryPeerWarningShown || typeof __DEV__ === 'undefined' || !__DEV__) {
+    return;
+  }
+  if (loadSentryModule()) {
+    return;
+  }
+  missingSentryPeerWarningShown = true;
+  console.warn(`[Adaxon] Activity logging is on and Sentry DSN is set, but ${SENTRY_UNAVAILABLE_HINT} ` + 'Until then, events appear locally as [Adaxon activity] in Metro/logcat only.');
+}
+function sentryLevel(level, target) {
+  if (level === 'warn') {
+    return 'warning';
+  }
+  if (level === 'error') {
+    return 'error';
+  }
+  if (level === 'debug') {
+    return target === 'breadcrumb' ? 'debug' : 'info';
+  }
+  return 'info';
+}
+function shouldCaptureMessage(input, level, structuredLogsUsed) {
+  if (structuredLogsUsed || level === 'debug') {
+    return false;
+  }
+  if (input.captureAsEvent && input.error === undefined) {
+    return true;
+  }
+  return MESSAGE_FALLBACK_EVENTS.has(input.eventName);
+}
+function usesStructuredSentryLogs(platform) {
+  return platform === 'web';
+}
+function emitStructuredLog(sentry, level, eventName, metadata) {
+  const loggerFn = sentry.logger?.[level];
+  if (typeof loggerFn !== 'function') {
+    return false;
+  }
+  loggerFn.call(sentry.logger, eventName, {
+    ...metadata,
+    event_name: eventName
+  });
+  return true;
+}
+function emitNativeActivityBreadcrumb(sentry, level, eventName, metadata) {
+  sentry.addBreadcrumb({
+    category: 'adaxon.activity',
+    message: eventName,
+    level: sentryLevel(level, 'breadcrumb'),
+    data: metadata,
+    timestamp: Date.now() / 1000
+  });
+}
+function emitDevActivityFallback(level, eventName, metadata, deliveredToSentry) {
+  if (deliveredToSentry || typeof __DEV__ === 'undefined' || !__DEV__) {
+    return;
+  }
+  const consoleFn = level === 'error' ? console.error : level === 'warn' ? console.warn : console.info;
+  const write = () => {
+    consoleFn(`[Adaxon activity] ${eventName}`, metadata);
+  };
+  const sentry = loadSentryModule();
+  if (typeof sentry?.consoleSandbox === 'function') {
+    sentry.consoleSandbox(write);
+    return;
+  }
+  write();
+}
+function activityTags(eventName, platform) {
+  return {
+    adaxon_event: eventName,
+    adaxon_platform: platform,
+    adaxon_sdk_version: SDK_VERSION
+  };
+}
+class AdaxonLoggerService {
+  enabled = false;
+  platform = 'web';
+  sentryReady = false;
+  configure(input) {
+    this.enabled = Boolean(input.enabled);
+    this.platform = input.platform;
+    this.sentryReady = false;
+    if (!this.enabled) {
+      return;
+    }
+    warnSentryUnavailableOnce(Boolean(input.dsn?.trim()));
+    this.ensureSentry(input.dsn, Boolean(input.testMode));
+  }
+  reset() {
+    this.enabled = false;
+    this.sentryReady = false;
+    this.platform = 'web';
+    cachedSentryModule = undefined;
+    missingSentryPeerWarningShown = false;
+  }
+  logActivity(input) {
+    if (!this.enabled) {
+      return;
+    }
+    const level = input.level ?? DEFAULT_LEVEL;
+    const metadata = sanitizeLogMetadata({
+      ...input.metadata,
+      sdk_version: SDK_VERSION,
+      platform: this.platform,
+      timestamp: new Date().toISOString()
+    });
+    const tags = activityTags(input.eventName, this.platform);
+    let deliveredToSentry = false;
+    this.safe(() => {
+      const sentry = loadSentryModule();
+      if (!sentry || !this.sentryReady) {
+        return;
+      }
+      const structuredLogsUsed = usesStructuredSentryLogs(this.platform);
+      let structuredLogSent = false;
+      if (structuredLogsUsed) {
+        structuredLogSent = emitStructuredLog(sentry, level, input.eventName, metadata);
+        deliveredToSentry = structuredLogSent;
+        if (level === 'warn' || level === 'error') {
+          sentry.addBreadcrumb({
+            category: 'adaxon.sdk',
+            message: input.eventName,
+            level: sentryLevel(level, 'breadcrumb'),
+            data: metadata,
+            timestamp: Date.now() / 1000
+          });
+        }
+      } else {
+        emitNativeActivityBreadcrumb(sentry, level, input.eventName, metadata);
+        deliveredToSentry = true;
+      }
+      if (usesStructuredSentryLogs(this.platform) && shouldCaptureMessage(input, level, structuredLogSent) && typeof sentry.captureMessage === 'function') {
+        sentry.captureMessage(input.eventName, {
+          level: sentryLevel(level, 'message'),
+          tags,
+          extra: metadata
+        });
+        deliveredToSentry = true;
+      }
+      if (input.captureAsEvent && input.error !== undefined) {
+        const captureError = input.error instanceof Error ? input.error : new Error(AdaxonSdkError.messageOf(input.error, `Adaxon SDK activity: ${input.eventName}`));
+        sentry.captureException(captureError, {
+          tags,
+          extra: metadata
+        });
+        deliveredToSentry = true;
+      }
+    });
+    emitDevActivityFallback(level, input.eventName, metadata, deliveredToSentry);
+  }
+  ensureSentry(dsn, testMode) {
+    this.safe(() => {
+      const sentry = loadSentryModule();
+      if (!sentry) {
+        return;
+      }
+      if (!sentry.getClient()) {
+        if (!dsn?.trim()) {
+          return;
+        }
+        const structuredLogs = usesStructuredSentryLogs(this.platform);
+        sentry.init(structuredLogs ? {
+          dsn: dsn.trim(),
+          environment: testMode ? 'adaxon-sdk-test' : 'adaxon-sdk',
+          enableLogs: true,
+          enableAutoConsoleLogs: false,
+          tracesSampleRate: 0,
+          enableAutoSessionTracking: false,
+          sendDefaultPii: false
+        } : {
+          dsn: dsn.trim(),
+          environment: testMode ? 'adaxon-sdk-test' : 'adaxon-sdk',
+          enableLogs: false,
+          enableAutoConsoleLogs: false,
+          enableNative: false,
+          autoInitializeNativeSdk: false,
+          defaultIntegrations: false,
+          integrations: [],
+          tracesSampleRate: 0,
+          enableAutoSessionTracking: false,
+          sendDefaultPii: false
+        });
+      }
+      sentry.setTag('adaxon_sdk_version', SDK_VERSION);
+      sentry.setTag('adaxon_platform', this.platform);
+      this.sentryReady = true;
+    });
+  }
+  safe(run) {
+    try {
+      run();
+    } catch {
+      // Logging must never interrupt SDK behavior.
+    }
+  }
+}
+export const AdaxonLogger = new AdaxonLoggerService();
+export function logSdkActivity(input) {
+  AdaxonLogger.logActivity(input);
+}

package/lib/module/services/logging/sanitizeLogMetadata.js

@@ -0,0 +1,45 @@
+"use strict";
+
+const SENSITIVE_KEY = /^(sdk[_-]?key|api[_-]?key|authorization|x-sdk-key|password|secret|token|cookie|credentials?|dsn|sentry[_-]?dsn|headers)$/i;
+const MAX_STRING_LENGTH = 500;
+const MAX_NESTED_KEYS = 40;
+function truncate(value) {
+  return value.length <= MAX_STRING_LENGTH ? value : `${value.slice(0, MAX_STRING_LENGTH)}…`;
+}
+function sanitizeField(key, value) {
+  if (SENSITIVE_KEY.test(key)) {
+    return '[redacted]';
+  }
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    return truncate(value);
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => typeof item === 'string' ? truncate(item) : item);
+  }
+  if (typeof value === 'object') {
+    const nested = {};
+    for (const [nestedKey, nestedValue] of Object.entries(value).slice(0, MAX_NESTED_KEYS)) {
+      nested[nestedKey] = SENSITIVE_KEY.test(nestedKey) ? '[redacted]' : typeof nestedValue === 'string' ? truncate(nestedValue) : nestedValue;
+    }
+    return nested;
+  }
+  return String(value);
+}
+
+/** Redact secrets and cap string size before activity logs leave the SDK. */
+export function sanitizeLogMetadata(metadata) {
+  if (!metadata) {
+    return {};
+  }
+  const output = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    output[key] = sanitizeField(key, value);
+  }
+  return output;
+}

package/lib/module/services/network/ApiClient.js

@@ -2,6 +2,7 @@
 
 import { BASE_URL } from "../../config/ApiConstants.js";
 import { AdaxonSdkError } from "../../errors/AdaxonSdkError.js";
+import { logSdkActivity } from "../logging/AdaxonLogger.js";
 export class ApiClient {
   constructor(config) {
     this.config = config;
@@ -14,6 +15,15 @@ export class ApiClient {
   async post(path, body) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    const batchSize = Array.isArray(body) ? body.length : undefined;
+    logSdkActivity({
+      eventName: 'api.request.started',
+      level: 'debug',
+      metadata: {
+        path,
+        batch_size: batchSize
+      }
+    });
     try {
       const response = await this.fetchImplementation(`${BASE_URL}${path}`, {
         method: 'POST',
@@ -27,31 +37,70 @@ export class ApiClient {
       });
       const parsedBody = this.parseJson(await response.text());
       if (!response.ok) {
-        throw AdaxonSdkError.fromHttp(response.status, parsedBody);
+        const httpError = AdaxonSdkError.fromHttp(response.status, parsedBody);
+        this.logRequestFailed(path, httpError, response.status);
+        throw httpError;
       }
       if (parsedBody === null) {
-        throw new AdaxonSdkError('HTTP_ERROR', 'Adaxon returned an empty or invalid JSON response.', {
+        const invalidJsonError = new AdaxonSdkError('HTTP_ERROR', 'Adaxon returned an empty or invalid JSON response.', {
           status: response.status
         });
+        this.logRequestFailed(path, invalidJsonError, response.status);
+        throw invalidJsonError;
       }
+      logSdkActivity({
+        eventName: 'api.request.succeeded',
+        level: 'debug',
+        metadata: {
+          path,
+          status: response.status,
+          batch_size: batchSize
+        }
+      });
       return parsedBody;
     } catch (error) {
       if (error instanceof AdaxonSdkError) {
         throw error;
       }
       if (error instanceof Error && error.name === 'AbortError') {
-        throw new AdaxonSdkError('TIMEOUT', 'Adaxon request timed out.', {
+        const timeoutError = new AdaxonSdkError('TIMEOUT', 'Adaxon request timed out.', {
           cause: error
         });
+        logSdkActivity({
+          eventName: 'api.request.timeout',
+          level: 'warn',
+          metadata: {
+            path,
+            error_code: timeoutError.code
+          },
+          error: timeoutError
+        });
+        throw timeoutError;
       }
       const detail = AdaxonSdkError.messageOf(error, '');
-      throw new AdaxonSdkError('NETWORK_ERROR', `Unable to reach Adaxon at ${BASE_URL}.${detail ? ` ${detail}` : ''}`, {
+      const networkError = new AdaxonSdkError('NETWORK_ERROR', `Unable to reach Adaxon at ${BASE_URL}.${detail ? ` ${detail}` : ''}`, {
         cause: error
       });
+      this.logRequestFailed(path, networkError);
+      throw networkError;
     } finally {
       clearTimeout(timeout);
     }
   }
+  logRequestFailed(path, error, status) {
+    logSdkActivity({
+      eventName: 'api.request.failed',
+      level: 'warn',
+      metadata: {
+        path,
+        error_code: error.code,
+        ...(status !== undefined ? {
+          status
+        } : {})
+      },
+      error
+    });
+  }
   parseJson(rawBody) {
     try {
       return rawBody ? JSON.parse(rawBody) : null;

package/lib/typescript/src/sdkVersion.d.ts

@@ -1,3 +1,3 @@
 /** Keep in sync with package.json "version" (published npm packages ship lib/ only). */
-export declare const SDK_VERSION = "0.1.13";
+export declare const SDK_VERSION = "0.1.14";
 //# sourceMappingURL=sdkVersion.d.ts.map

package/lib/typescript/src/services/logging/AdaxonLogger.d.ts

@@ -0,0 +1,30 @@
+import type { AdaxonPlatform } from '../../types/EventTypes.js';
+export type AdaxonLogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type AdaxonActivityLogInput = {
+    eventName: string;
+    level?: AdaxonLogLevel;
+    metadata?: Record<string, unknown>;
+    error?: unknown;
+    /** Send a standalone Sentry issue (message or exception). Use sparingly. */
+    captureAsEvent?: boolean;
+};
+export type AdaxonLoggerConfigureInput = {
+    enabled: boolean;
+    dsn?: string;
+    platform: AdaxonPlatform;
+    testMode?: boolean;
+};
+declare class AdaxonLoggerService {
+    private enabled;
+    private platform;
+    private sentryReady;
+    configure(input: AdaxonLoggerConfigureInput): void;
+    reset(): void;
+    logActivity(input: AdaxonActivityLogInput): void;
+    private ensureSentry;
+    private safe;
+}
+export declare const AdaxonLogger: AdaxonLoggerService;
+export declare function logSdkActivity(input: AdaxonActivityLogInput): void;
+export {};
+//# sourceMappingURL=AdaxonLogger.d.ts.map

package/lib/typescript/src/services/logging/sanitizeLogMetadata.d.ts

@@ -0,0 +1,3 @@
+/** Redact secrets and cap string size before activity logs leave the SDK. */
+export declare function sanitizeLogMetadata(metadata: Record<string, unknown> | undefined): Record<string, unknown>;
+//# sourceMappingURL=sanitizeLogMetadata.d.ts.map

package/lib/typescript/src/services/network/ApiClient.d.ts

@@ -8,6 +8,7 @@ export declare class ApiClient {
     private readonly fetchImplementation;
     constructor(config: ApiClientConfig);
     post<TResponse>(path: string, body: unknown): Promise<TResponse>;
+    private logRequestFailed;
     private parseJson;
 }
 export {};

package/lib/typescript/src/types/AdaxonConfig.d.ts

@@ -10,6 +10,10 @@ export interface AdaxonSdkConfig {
     timeoutMs?: number;
     fetch?: typeof globalThis.fetch;
     testMode?: boolean;
+    /** When true, records SDK activity to Sentry for testing/debugging. Default false. */
+    activityLogging?: boolean;
+    /** Sentry DSN used when activity logging is enabled and the host app has not initialized Sentry. */
+    sentryDsn?: string;
 }
 export type AdaxonInitializationConfiguration = AdaxonSdkConfig;
 export type AdaxonInitializationErrorCode = 'INVALID_CONFIG' | 'UNKNOWN';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-test-adx",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Adaxon React Native / Expo SDK for event tracking and offer recommendations.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -56,6 +56,9 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "dependencies": {
+    "@sentry/react-native": "^8.31.0"
+  },
   "devDependencies": {
     "@eslint/compat": "^2.1.0",
     "@eslint/eslintrc": "^3.3.5",