react-native-test-adx 0.1.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Ritesh Rana
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,333 @@
+# react-native-adaxon
+
+Adaxon React Native / Expo SDK for event tracking and offer recommendations.
+
+The SDK talks to the MTS tracker over HTTPS. The app does not call Kafka or MySQL.
+
+```text
+Mobile app  →  Adaxon SDK  →  HTTPS  →  MTS tracker  →  Kafka  →  MTS API  →  MySQL
+```
+
+## Install
+
+### Production apps
+
+```sh
+npm install react-native-adaxon
+# or
+yarn add react-native-adaxon
+# or
+npx expo install react-native-adaxon
+```
+
+```ts
+import { AdaxonProvider, useAdaxon } from 'react-native-adaxon';
+```
+
+### Testing / staging apps
+
+```sh
+npm install react-native-test-adx
+```
+
+```ts
+import { AdaxonProvider, useAdaxon } from 'react-native-test-adx';
+```
+
+Both packages expose the same API. Only the npm name differs.
+
+Recommended storage helper:
+
+```sh
+npx expo install expo-secure-store
+```
+
+## Quick start (React Native)
+
+Wrap the app in `AdaxonProvider`. Screens use `useAdaxon()`.
+
+Tracking does **not** write React state, so `logEvent` / `track` will not re-render the tree.
+
+### Configuration
+
+The SDK owns the tracker host and API paths (`/event/tracking`, `/api/mts/recommendations`, `/click/tracking`). The app only provides credentials.
+
+| Field | Required | Default |
+|---|---|---|
+| `appId` | **Yes** | None. MTS app id (`adx_…`). |
+| `sdkKey` | **Yes** | None. Sent as the `x-sdk-key` header. |
+| `storage` | No | In-memory. Queue and anonymous id are lost on app restart. |
+| `timeoutMs` | No | `10000` |
+| `testMode` | No | `false` (`sdk_version` gets a `-test` suffix when true) |
+| `externalUserId` | No | Unset |
+
+Pass `storage` in production so the anonymous id and queued events survive restart. The SDK detects the device platform and collects device/app fields automatically. Do **not** pass a tracker URL — requests go to the SDK `BASE_URL`.
+
+```tsx
+import {
+  AdaxonProvider,
+  AdxEvent,
+  useAdaxon,
+  type RecommendationOffer,
+} from 'react-native-adaxon';
+import * as SecureStore from 'expo-secure-store';
+import { Button, Text, View } from 'react-native';
+
+function App() {
+  return (
+    <AdaxonProvider
+      configuration={{
+        appId: 'adx_your_app_id',
+        sdkKey: 'your_sdk_key',
+        testMode: __DEV__,
+        storage: {
+          getItem: (key) => SecureStore.getItemAsync(key),
+          setItem: (key, value) => SecureStore.setItemAsync(key, value),
+          removeItem: (key) => SecureStore.deleteItemAsync(key),
+        },
+      }}
+    >
+      <HomeScreen />
+    </AdaxonProvider>
+  );
+}
+
+function HomeScreen() {
+  const {
+    isInitialized,
+    logEvent,
+    trackPurchase,
+    trackAddToCart,
+    loadRecommendations,
+    showOffer,
+  } = useAdaxon();
+
+  if (!isInitialized) {
+    return <Text>Initializing…</Text>;
+  }
+
+  return (
+    <View>
+      <Button
+        title="Custom event"
+        onPress={() =>
+          logEvent('level_completed', {
+            level_number: 10,
+            coins_used: 50,
+          })
+        }
+      />
+      <Button
+        title="Purchase"
+        onPress={() =>
+          trackPurchase({
+            order_id: 'ORD123',
+            amount: 999,
+            currency: 'INR',
+          })
+        }
+      />
+      <Button
+        title="Add to cart"
+        onPress={() =>
+          trackAddToCart({
+            product_id: 'P123',
+            price: 499,
+            currency: 'INR',
+          })
+        }
+      />
+      <Button
+        title="Load offers"
+        onPress={async () => {
+          const offers: RecommendationOffer[] = await loadRecommendations(
+            'recommendation_view',
+            { placement: 'home' }
+          );
+          if (offers[0]) {
+            await showOffer(offers[0]);
+          }
+        }}
+      />
+    </View>
+  );
+}
+```
+
+Do **not** pass device or app fields. The SDK attaches `device` and `app` automatically on every event.
+
+### Non-component boot
+
+`Adaxon.initialize()` is still available if you are not inside a React tree. Prefer the provider in React Native apps.
+
+```ts
+import { Adaxon } from 'react-native-adaxon';
+
+await Adaxon.initialize({
+  appId: 'adx_your_app_id',
+  sdkKey: 'your_sdk_key',
+});
+
+await Adaxon.logEvent('level_completed', { level_number: 10 });
+```
+
+## API
+
+| Method | What it does |
+|---|---|
+| `AdaxonProvider` | Starts the SDK once when the app mounts |
+| `useAdaxon()` | Hook for screens: track, recommendations, offers |
+| `logEvent(name, values)` | Custom or predefined event |
+| `trackPurchase(params)` | Sends `adx_purchase` |
+| `trackAddToCart(params)` | Sends `adx_add_to_cart` |
+| `trackLogin(params)` | Sends `adx_login` |
+| `trackCompleteRegistration(params)` | Sends `adx_complete_registration` |
+| `track` / `trackBatch` | Send immediately. `trackBatch` accepts 1–100 events |
+| `enqueueEvent(name, properties)` | Store an event locally; does not send yet |
+| `processPendingEvents()` | Send queued events in batches of up to 100 |
+| `loadRecommendations(eventName, properties)` | POST `/api/mts/recommendations` |
+| `showOffer(offer)` | Opens the offer URL and tracks `offer_opened` |
+| `setExternalUserId(id)` | Attaches `external_user_id` on later events |
+
+Predefined names: `AdxEvent.PURCHASE`, `AdxEvent.ADD_TO_CART`, `AdxEvent.LOGIN`, `AdxEvent.COMPLETE_REGISTRATION`.
+
+## Event queue and batch processing
+
+`track` and `trackBatch` send immediately. Use `enqueueEvent` / `processPendingEvents` when events should wait in the local queue.
+
+```ts
+const { enqueueEvent, processPendingEvents } = useAdaxon();
+
+await enqueueEvent('level_completed', { level_number: 10 });
+const result = await processPendingEvents();
+// result.status: 'completed' | 'stopped' | 'already_processing'
+```
+
+How it works:
+
+```text
+Persistent event queue
+        ↓
+Get next ≤ 100 events (FIFO)
+        ↓
+POST /event/tracking
+        ↓
+   Success → remove those events → next batch
+   Failure → keep events → stop (retry later)
+```
+
+Rules:
+
+- Pending events are stored through the `storage` adapter, so they survive app restart.
+- Events are processed in creation order (FIFO).
+- Each request contains at most **100** events. A queue of 250 is sent as 100 + 100 + 50.
+- Events are removed only after the API confirms success (`success: true`). On network, HTTP, or unknown errors they stay in the queue.
+- Only one processor runs at a time for the same app. A second `processPendingEvents()` call returns `already_processing`.
+- Large queues are read 100 events at a time. The SDK does not load the whole queue into memory.
+- On `Adaxon.initialize()` / `AdaxonProvider` mount, pending events start flushing in the background without blocking startup.
+- Pass `removeItem` on the storage adapter so successful events can be deleted. If it is omitted, the SDK writes an empty value instead.
+
+Expo SecureStore has a small per-key size limit. For a large event queue, use a storage backend that can hold JSON payloads (for example AsyncStorage) and keep SecureStore for the anonymous id if you want.
+
+## Automatic device information
+
+```json
+{
+  "device": {
+    "platform": "android",
+    "os_version": "14",
+    "brand": "Samsung",
+    "model": "S23",
+    "language": "en",
+    "timezone": "Asia/Kolkata"
+  }
+}
+```
+
+Values come from React Native `Platform` (`src/platform/reactNative.ts`). They are read **once** and cached. Missing optional fields are omitted and never block the request.
+
+## Automatic app information
+
+```json
+{
+  "app": {
+    "package_name": "com.example.app",
+    "app_version": "2.4.1",
+    "sdk_version": "0.1.1"
+  }
+}
+```
+
+`package_name` and `app_version` are read from native application APIs (Android package / iOS bundle). `sdk_version` is always set by the SDK. Do **not** pass these fields in `logEvent`, `track`, or `trackBatch` — every event, including each item in a batch, receives the same `app` object automatically. Missing optional fields are omitted and never block the request.
+
+## How the folders work
+
+```text
+App screen
+   │  useAdaxon().logEvent(...)  or  enqueueEvent(...) → processPendingEvents()
+   ▼
+components/ + hooks/ + state/     React layer (init only)
+   ▼
+AdaxonSdk.ts                      Public methods
+   ▼
+core/AdaxonClient.ts              Wires services
+   ▼
+services/                         Validate, build JSON, queue, batch, HTTPS
+   ▼
+MTS tracker
+```
+
+| Folder | Role |
+|---|---|
+| `src/index.ts` | Public exports (`Adaxon`, `AdaxonProvider`, `useAdaxon`) |
+| `src/AdaxonSdk.ts` | SDK facade (`initialize`, `logEvent`, queue, offers) |
+| `src/components/` | `AdaxonProvider` |
+| `src/hooks/` | `useAdaxon()` |
+| `src/state/` | Init status only — no event list in React state |
+| `src/core/` | `AdaxonClient` — connects auth, events, queue, HTTP |
+| `src/services/` | Auth, device, app, event build/send, batch processor, network |
+| `src/platform/` | Android/iOS fields. **Only `react-native` import** |
+| `src/config/` | Tracker host, API paths, timeouts, storage key rules |
+| `src/validation/` | Event name, property, and batch-size rules |
+| `src/storage/` | Anonymous user id and persistent event queue |
+| `example/src/` | Demo app: `App.tsx`, `screens/`, `components/` |
+
+Screens belong in the **host app**, not in the SDK.
+
+Longer walkthrough for managers and teammates: [ARCHITECTURE.md](./ARCHITECTURE.md).  
+Framework cost vs vanilla JS is checked by `src/__tests__/performance.framework.test.tsx`.
+
+## Android notes
+
+Credential `platform` in Adaxon must allow Android (`android` or `react_native`).
+
+## Local development (this repo)
+
+```sh
+cd adaxon-sdk
+corepack enable
+yarn
+yarn typecheck
+yarn test --watchman=false
+yarn prepare
+yarn example android:emulator
+```
+
+## Publish to npm
+
+```sh
+npm login
+yarn publish:test:dry    # dry-run testing package
+yarn publish:test        # publishes react-native-test-adx
+yarn publish:prod:dry    # dry-run production package
+yarn publish:prod        # publishes react-native-adaxon
+```
+
+| Environment | Install |
+|---|---|
+| Testing | `npm install react-native-test-adx` |
+| Production | `npm install react-native-adaxon` |
+
+## License
+
+MIT

package/lib/module/AdaxonSdk.js

@@ -0,0 +1,120 @@
+"use strict";
+
+import { AdaxonClient } from "./core/AdaxonClient.js";
+import { MEDIATION_PROVIDER, OFFER_OPENED_EVENT } from "./config/ApiConstants.js";
+import { AdaxonSdkError } from "./errors/AdaxonSdkError.js";
+import { detectReactNativePlatform, reactNativeAppInfoReader, reactNativeDeviceReader, reactNativeNetworkInfoReader, reactNativeUrlOpener } from "./platform/reactNative.js";
+import { buildAddToCartProperties, buildPurchaseProperties, normalizeEventValues } from "./services/event/normalizeProperties.js";
+import { AdxEvent } from "./services/event/predefined.js";
+export class AdaxonSdk {
+  static sharedInstance = new AdaxonSdk();
+  client = null;
+  testMode = false;
+  static get shared() {
+    return AdaxonSdk.sharedInstance;
+  }
+  isInitialized() {
+    return this.client !== null;
+  }
+  async initialize(configuration, listener) {
+    try {
+      this.client = new AdaxonClient({
+        ...configuration,
+        platform: detectReactNativePlatform(),
+        deviceInfoReader: reactNativeDeviceReader,
+        appInfoReader: reactNativeAppInfoReader,
+        networkInfoReader: reactNativeNetworkInfoReader
+      });
+      this.testMode = Boolean(configuration.testMode);
+      listener?.onInitializationComplete();
+      this.client.processPendingEvents().catch(() => undefined);
+    } catch (error) {
+      this.reset();
+      const message = AdaxonSdkError.messageOf(error, 'Initialization failed.');
+      const code = error instanceof AdaxonSdkError && error.code === 'INVALID_CONFIG' ? 'INVALID_CONFIG' : 'UNKNOWN';
+      listener?.onInitializationFailed(code, message);
+      throw error;
+    }
+  }
+  async track(eventName, properties = {}, options = {}) {
+    return this.requireClient().track(eventName, properties, options);
+  }
+  async trackBatch(events) {
+    return this.requireClient().trackBatch(events);
+  }
+  async enqueueEvent(eventName, properties = {}, options = {}) {
+    await this.requireClient().enqueueEvent(eventName, properties, options);
+  }
+  async processPendingEvents() {
+    return this.requireClient().processPendingEvents();
+  }
+  async logEvent(eventName, values = {}, options = {}) {
+    return this.track(eventName, normalizeEventValues(values), options);
+  }
+  async trackPurchase(params, options = {}) {
+    return this.logEvent(AdxEvent.PURCHASE, buildPurchaseProperties(params), options);
+  }
+  async trackAddToCart(params, options = {}) {
+    return this.logEvent(AdxEvent.ADD_TO_CART, buildAddToCartProperties(params), options);
+  }
+  async trackLogin(params = {}, options = {}) {
+    return this.logEvent(AdxEvent.LOGIN, params, options);
+  }
+  async trackCompleteRegistration(params = {}, options = {}) {
+    return this.logEvent(AdxEvent.COMPLETE_REGISTRATION, params, options);
+  }
+  async loadRecommendations(eventName, properties = {}, listener) {
+    try {
+      const response = await this.requireClient().getRecommendations({
+        eventName,
+        properties: {
+          ...properties,
+          mediation_provider: MEDIATION_PROVIDER,
+          test_mode: this.testMode
+        }
+      });
+      listener?.onRecommendationsLoaded(response.offers);
+      return response.offers;
+    } catch (error) {
+      const message = AdaxonSdkError.messageOf(error, 'Failed to load recommendations.');
+      const code = error instanceof AdaxonSdkError ? error.code : undefined;
+      listener?.onRecommendationsFailedToLoad(message, code);
+      throw error;
+    }
+  }
+  async showOffer(offer, listener) {
+    try {
+      const client = this.requireClient();
+      const targetUrl = offer.offer_url;
+      const canOpen = await reactNativeUrlOpener.canOpenURL(targetUrl);
+      if (!canOpen) {
+        throw new AdaxonSdkError('VALIDATION_ERROR', `Cannot open offer URL: ${targetUrl}`);
+      }
+      await reactNativeUrlOpener.openURL(targetUrl);
+      await client.track(OFFER_OPENED_EVENT, {
+        offer_id: offer.offer_id,
+        offer_name: offer.offer_name,
+        ad_type: offer.ad_type,
+        mediation_provider: MEDIATION_PROVIDER
+      });
+      listener?.onOfferOpened(offer);
+    } catch (error) {
+      const message = AdaxonSdkError.messageOf(error, 'Failed to open offer.');
+      listener?.onOfferFailedToOpen(offer, message);
+      throw error;
+    }
+  }
+  setExternalUserId(externalUserId) {
+    this.requireClient().setExternalUserId(externalUserId);
+  }
+  requireClient() {
+    if (!this.client) {
+      throw new AdaxonSdkError('INVALID_CONFIG', 'Adaxon SDK is not initialized. Call Adaxon.initialize(...) first.');
+    }
+    return this.client;
+  }
+  reset() {
+    this.client = null;
+    this.testMode = false;
+  }
+}

package/lib/module/components/AdaxonProvider.js

@@ -0,0 +1,46 @@
+"use strict";
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { AdaxonSdk } from "../AdaxonSdk.js";
+import { AdaxonSdkError } from "../errors/AdaxonSdkError.js";
+import { AdaxonContext } from "../state/AdaxonContext.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export function AdaxonProvider({
+  configuration,
+  listener,
+  sdk = AdaxonSdk.shared,
+  children
+}) {
+  const [isInitialized, setIsInitialized] = useState(sdk.isInitialized());
+  const [initializationError, setInitializationError] = useState(null);
+  const configurationRef = useRef(configuration);
+  const listenerRef = useRef(listener);
+  configurationRef.current = configuration;
+  listenerRef.current = listener;
+  useEffect(() => {
+    let cancelled = false;
+    sdk.initialize(configurationRef.current, listenerRef.current).then(() => {
+      if (!cancelled) {
+        setIsInitialized(true);
+        setInitializationError(null);
+      }
+    }).catch(error => {
+      if (!cancelled) {
+        setIsInitialized(false);
+        setInitializationError(AdaxonSdkError.messageOf(error, 'Initialization failed.'));
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [sdk]);
+  const value = useMemo(() => ({
+    isInitialized,
+    initializationError,
+    sdk
+  }), [initializationError, isInitialized, sdk]);
+  return /*#__PURE__*/_jsx(AdaxonContext.Provider, {
+    value: value,
+    children: children
+  });
+}

package/lib/module/config/ApiConstants.js

@@ -0,0 +1,18 @@
+"use strict";
+
+export const SDK_VERSION = '0.1.1';
+export const MEDIATION_PROVIDER = 'mts';
+export const BASE_URL = 'http://localhost:3002';
+export const EVENT_TRACKING_PATH = '/event/tracking';
+export const RECOMMENDATIONS_PATH = '/api/mts/recommendations';
+export const CLICK_TRACKING_PATH = '/click/tracking';
+export const OFFER_OPENED_EVENT = 'offer_opened';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+export const PUBLIC_IP_LOOKUP_URL = 'https://api.ipify.org?format=json';
+export const PUBLIC_IP_LOOKUP_TIMEOUT_MS = 2_000;
+export const MAX_BATCH_SIZE = 100;
+export const MAX_EVENT_NAME_LENGTH = 100;
+export const MAX_PROPERTIES = 50;
+export const MAX_PROPERTY_KEY_LENGTH = 100;
+export const MAX_PROPERTY_VALUE_LENGTH = 1000;
+export const EVENT_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;

package/lib/module/config/StorageKeys.js

@@ -0,0 +1,12 @@
+"use strict";
+
+export const ANONYMOUS_ID_KEY_PREFIX = 'adaxon_sdk.anonymous_id.';
+export const EVENT_QUEUE_META_KEY_PREFIX = 'adaxon_sdk.event_queue.meta.';
+export const EVENT_QUEUE_ITEM_KEY_PREFIX = 'adaxon_sdk.event_queue.item.';
+
+// Expo SecureStore and Keychain-backed adapters only accept alphanumerics
+// plus `.`, `-` and `_`, so app ids are sanitized before use as a key.
+const UNSAFE_STORAGE_KEY_CHARS = /[^A-Za-z0-9._-]/g;
+export function sanitizeStorageId(appId) {
+  return appId.replace(UNSAFE_STORAGE_KEY_CHARS, '_');
+}

package/lib/module/core/AdaxonClient.js

@@ -0,0 +1,88 @@
+"use strict";
+
+import { BASE_URL, CLICK_TRACKING_PATH } from "../config/ApiConstants.js";
+import { AuthenticationService } from "../services/authentication/AuthenticationService.js";
+import { AppInfoService } from "../services/app/AppInfoService.js";
+import { DeviceInfoService } from "../services/device/DeviceInfoService.js";
+import { BatchProcessor } from "../services/event/BatchProcessor.js";
+import { EventBuilder } from "../services/event/EventBuilder.js";
+import { EventQueueService } from "../services/event/EventQueueService.js";
+import { EventService } from "../services/event/EventService.js";
+import { ApiClient } from "../services/network/ApiClient.js";
+import { NetworkInfoService } from "../services/network/NetworkInfoService.js";
+import { AnonymousIdService } from "../storage/AnonymousIdService.js";
+import { EventQueueStorage } from "../storage/EventQueueStorage.js";
+import { EventValidator } from "../validation/EventValidator.js";
+export class AdaxonClient {
+  constructor(config) {
+    const auth = new AuthenticationService(config);
+    this.validator = new EventValidator();
+    const api = new ApiClient({
+      sdkKey: auth.sdkKey,
+      timeoutMs: auth.timeoutMs,
+      fetch: config.fetch
+    });
+    const networkInfo = new NetworkInfoService(config.networkInfoReader);
+    this.builder = new EventBuilder({
+      appId: auth.appId,
+      deviceInfo: new DeviceInfoService(config.platform ?? 'web', config.deviceInfoReader),
+      appInfo: new AppInfoService(Boolean(config.testMode), config.appInfoReader),
+      networkInfo,
+      anonymousId: new AnonymousIdService(auth.appId, config.storage),
+      validator: this.validator,
+      externalUserId: config.externalUserId
+    });
+    this.events = new EventService({
+      api,
+      builder: this.builder,
+      validator: this.validator
+    });
+    this.eventQueue = new EventQueueService(new EventQueueStorage(auth.appId, config.storage));
+    this.batchProcessor = new BatchProcessor({
+      queue: this.eventQueue,
+      sendBatch: payloads => this.events.sendPayloads(payloads)
+    });
+  }
+  track(eventName, properties = {}, options = {}) {
+    return this.events.track(eventName, properties, options);
+  }
+  trackBatch(events) {
+    return this.events.trackBatch(events);
+  }
+  async enqueueEvent(eventName, properties = {}, options = {}) {
+    const payload = await this.builder.build({
+      eventName,
+      properties,
+      ...options
+    });
+    await this.eventQueue.add(payload);
+  }
+  processPendingEvents() {
+    return this.batchProcessor.process();
+  }
+  getRecommendations(input) {
+    return this.events.getRecommendations(input);
+  }
+  createClickUrl(attribution) {
+    this.validator.validateClickAttribution(attribution);
+    const query = this.toQueryString({
+      offer_id: attribution.offerId,
+      affiliate_id: attribution.affiliateId,
+      advertiser_id: attribution.advertiserId,
+      aff_click_id: attribution.affClickId,
+      source: attribution.source,
+      aff_sub: attribution.affSub,
+      aff_sub2: attribution.affSub2,
+      aff_sub3: attribution.affSub3,
+      aff_sub4: attribution.affSub4,
+      aff_sub5: attribution.affSub5
+    });
+    return `${BASE_URL}${CLICK_TRACKING_PATH}?${query}`;
+  }
+  setExternalUserId(externalUserId) {
+    this.builder.setExternalUserId(externalUserId);
+  }
+  toQueryString(params) {
+    return Object.entries(params).filter(([, value]) => value !== undefined).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`).join('&');
+  }
+}

package/lib/module/errors/AdaxonSdkError.js

@@ -0,0 +1,23 @@
+"use strict";
+
+export class AdaxonSdkError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, {
+      cause: options.cause
+    });
+    this.name = 'AdaxonSdkError';
+    this.code = code;
+    this.status = options.status;
+    this.details = options.details;
+  }
+  static messageOf(error, fallback) {
+    return error instanceof Error ? error.message : fallback;
+  }
+  static fromHttp(status, body) {
+    const code = status === 401 ? 'AUTHENTICATION_ERROR' : 'HTTP_ERROR';
+    return new AdaxonSdkError(code, body?.message || `Adaxon request failed with HTTP ${status}.`, {
+      status,
+      details: body?.errors ?? body
+    });
+  }
+}