@jammysunshine/astrology-api-client 1.0.0

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@jammysunshine/astrology-api-client",
+  "version": "1.0.0",
+  "description": "Unified API Client for Astrology Services",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node ../../node_modules/.bin/jest"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "uuid": "^9.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/AstrologyApiClient.js

@@ -0,0 +1,254 @@
+const { v4: uuid } = require('uuid');
+const axios = require('axios');
+const http = require('http');
+const https = require('https');
+const retry = require('./utils/retry');
+const breaker = new (require('./utils/CircuitBreaker'))();
+const monitor = require('./utils/NetworkMonitor');
+const detective = require('./utils/ResponseDetective');
+const diagnostics = require('./utils/DiagnosticsTracker');
+const ContextStore = require('./utils/ContextStore');
+const SDK_CONFIG = require('./config');
+
+class AstrologyApiClient {
+  constructor(config = {}) {
+    this.config = {
+      baseUrl: config.baseUrl || SDK_CONFIG.DEFAULT_BASE_URL,
+      apiKey: config.apiKey || '', // SDK Sec 5: SECURITY: Ensure apiKey is managed via secure environment variables
+      platform: config.platform || 'api',
+      clientType: config.clientType || 'api-client',
+      clientVersion: config.clientVersion || '1.0.0',
+      apiVersion: config.apiVersion || 'v1', // API versioning support
+      timeout: config.timeout || SDK_CONFIG.DEFAULT_TIMEOUT,
+      lockTtl: SDK_CONFIG.LOCK_TTL,
+      services: config.services || {},
+      onMetrics: config.onMetrics || (() => {}),
+      ...config
+    };
+
+    const agentOptions = SDK_CONFIG.AGENT_OPTIONS;
+    this.axios = axios.create({
+      timeout: this.config.timeout,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.config.apiKey}`, // SDK Sec 5
+        'X-API-Version': this.config.apiVersion // API versioning header
+      },
+      httpAgent: new http.Agent(agentOptions),
+      httpsAgent: new https.Agent(agentOptions)
+    });
+
+    this.breaker = breaker; // Expose for BotEngine (Design Sec 3.7)
+    this.monitor = monitor;
+    this.diagnostics = diagnostics;
+    this.contextStore = new ContextStore(config.memory);
+    this.requestBatcher = new (require('./utils/RequestBatcher'))(this);
+    this.interceptors = new (require('./utils/Interceptors'))();
+    this.shimMap = SDK_CONFIG.COMPATIBILITY_MAP;
+
+    return new Proxy(this, {
+      get: (target, key) => {
+        if (key in target) return target[key];
+        if (/^v\d+$/.test(key)) return new Proxy({}, { get: (_, s) => target._createServiceProxy(s, key) });
+        
+        // Only proxy service names that are expected
+        if (typeof key === 'string' && !key.startsWith('_')) {
+          return target._createServiceProxy(key, 'v1');
+        }
+        
+        return undefined;
+      }
+    });
+  }
+
+  async batch(calls) {
+    return this.requestBatcher.batch(calls);
+  }
+
+  _createServiceProxy(service, version) {
+    return new Proxy({}, {
+      get: (_, method) => async (params = {}) => {
+        const shimmed = this._resolveShim(service, method);
+        return this._executeRequest(shimmed.service, shimmed.method, params, version);
+      }
+    });
+  }
+
+  _resolveShim(s, m) {
+    const mapped = this.shimMap[`${s}.${m}`];
+    return mapped ? { service: mapped.split('.')[0], method: mapped.split('.')[1] } : { service: s, method: m };
+  }
+
+  asUser(platformUserId) {
+    const client = this;
+    const ensureIdentity = async () => {
+      let ctx = await client.contextStore.get(platformUserId);
+      if (!ctx || !ctx.unifiedUserId) {
+        const res = await client._executeRequest('userMapping', 'mapPlatformToUnified', { platform: client.config.platform, platformUserId, initialProfileData: {} });
+        ctx = { unifiedUserId: res.unifiedUserId, sessionId: res.sessionId };
+        await client.contextStore.set(platformUserId, ctx);
+      }
+      return ctx;
+    };
+
+    return {
+      observability: {
+        incrementCounter: (name, tags) => client._executeRequest('observability', 'recordMetric', { type: 'counter', name, tags: { ...tags, platform: client.config.platform, platformUserId } }),
+        recordHistogram: (name, value, tags) => client._executeRequest('observability', 'recordMetric', { type: 'histogram', name, value, tags: { ...tags, platform: client.config.platform, platformUserId } })
+      },
+      // Media lifecycle management (Design Sec 16.2)
+      media: {
+        getMediaId: async (hash) => client._executeRequest('mediaManager', 'getMediaId', { hash }),
+        recordMediaId: async (hash, mediaId, ttl) => client._executeRequest('mediaManager', 'recordMediaId', { hash, mediaId, ttl })
+      },
+      acquireSessionLock: async () => retry(async () => client._executeRequest('sessionManager', 'acquireSessionLock', { unifiedUserId: (await ensureIdentity()).unifiedUserId, ttl: client.config.lockTtl }), { maxAttempts: 5 }),
+      getSession: async () => {
+        const ctx = await ensureIdentity();
+        const res = await client._executeRequest('sessionManager', 'getSessionState', { unifiedUserId: ctx.unifiedUserId });
+        ctx.sessionId = res.sessionId;
+        await client.contextStore.set(platformUserId, ctx);
+        return res;
+      },
+      save: async (state) => {
+        const ctx = await ensureIdentity();
+        const res = await client._executeRequest('sessionManager', 'updateSessionState', { unifiedUserId: ctx.unifiedUserId, sessionId: ctx.sessionId, partialState: state });
+        await client._executeRequest('sessionManager', 'releaseSessionLock', { unifiedUserId: ctx.unifiedUserId });
+        return res;
+      },
+      call: async (s, m, p) => {
+        const ctx = await ensureIdentity();
+        try {
+          return await client._executeRequest(s, m, { ...p, unifiedUserId: ctx.unifiedUserId, platform: client.config.platform, platformUserId });
+        } catch (error) {
+          if (error.status === 401) {
+            await client.contextStore.set(platformUserId, { unifiedUserId: null });
+            const newCtx = await ensureIdentity();
+            return await client._executeRequest(s, m, { ...p, unifiedUserId: newCtx.unifiedUserId, platform: client.config.platform, platformUserId });
+          }
+          throw error;
+        }
+      }
+    };
+  }
+
+  async _executeRequest(service, method, params = {}, version = 'v1') {
+    const startTime = Date.now();
+    // SDK Sec 9.A: Intelligent Request Caching
+    const cacheKey = `req:${service}:${method}:${JSON.stringify(params)}`;
+    const cached = await this.contextStore.get(cacheKey);
+    if (cached && (service === 'birthchart' || service === 'dasha')) {
+      return cached;
+    }
+
+    const t0 = Date.now(); // Prep end
+    const requestId = uuid();
+    
+    // Hard Request Ceiling enforcement
+    const baseTimeout = this.monitor.status === 'flaky' ? SDK_CONFIG.FLAKY_TIMEOUT : this.config.timeout;
+    const timeout = Math.min(baseTimeout, SDK_CONFIG.MAX_TIMEOUT_CEILING);
+    
+    const serviceBase = this.config.services[service] || this.config.baseUrl;
+
+    this.interceptors.onRequest({ requestId, service, method, params });
+
+    // Define failure criteria for Circuit Breaker: 5xx errors or Timeouts/Network issues
+    const isCircuitBreakerFailure = (error) => {
+      if (!error.status) return true; // Network/Timeout/Unknown
+      return error.status >= 500; // Server Error
+    };
+
+    return this.breaker.execute(() => retry(async () => {
+      let t1 = Date.now();
+      let responseData = null;
+      let responseStatus = null;
+      let responseContentType = null;
+
+      try {
+        const response = await this.axios.post(`${serviceBase}/api/${version}/${service}/${method}`, 
+          { requestId, timestamp: new Date().toISOString(), ...params }, { timeout, responseType: 'arraybuffer' }
+        );
+        responseData = response.data;
+        responseStatus = response.status;
+        responseContentType = response.headers['content-type'];
+        
+        const t2 = Date.now();
+        const duration = t2 - t1;
+        this.monitor.record(duration, true);
+        this.diagnostics.recordRequest(JSON.stringify(params).length, responseData.length);
+        
+        let resultData;
+        try {
+          const format = detective.detect({ data: responseData, headers: { 'content-type': responseContentType } });
+
+          if (format === 'JSON') {
+            const json = JSON.parse(responseData.toString());
+            if (json.status === 'error') throw this._wrapError(json.error, requestId);
+            resultData = json.data;
+            // SDK Sec 1: Smart Unwrapping
+            if (resultData && typeof resultData === 'object') {
+              Object.defineProperty(resultData, 'metadata', { value: json.metadata || { requestId }, enumerable: false });
+            }
+          } else if (format === 'TEXT') {
+            resultData = responseData.toString();
+          } else {
+            resultData = responseData; 
+          }
+        } catch (parseError) {
+          if (parseError instanceof ApiClientError) throw parseError;
+          const { ApiParseError } = require('./utils/ApiClientError');
+          throw new ApiParseError(`Failed to parse ${responseContentType} response: ${parseError.message}`, { 
+            requestId, 
+            rawData: responseData ? responseData.toString().substring(0, 1000) : null 
+          });
+        }
+
+        this.interceptors.onResponse({ status: responseStatus, headers: { 'content-type': responseContentType } }, resultData);
+
+        // Cache successful immutable requests
+        if (service === 'birthchart' || service === 'dasha') {
+          await this.contextStore.set(cacheKey, resultData);
+        }
+
+        const t3 = Date.now();
+        this.config.onMetrics({
+          requestId, 
+          prep_time: t0 - startTime, // SDK Sec 9.D
+          total_duration: t3 - startTime,
+          latency_ttfb: t2 - t1, 
+          transfer_time: t3 - t2
+        });
+
+        return resultData;
+      } catch (error) {
+        this.monitor.record(Date.now() - (t1 || t0), false);
+        this.diagnostics.trackError(error.name || error.code || 'UNKNOWN', requestId);
+        throw this.interceptors.onError(error);
+      }
+    }, { shouldRetry: (err) => SDK_CONFIG.RETRYABLE_STATUSES.includes(err.status) }), isCircuitBreakerFailure);
+  }
+
+  _wrapError(apiError, requestId) {
+    const errorClasses = require('./utils/ApiClientError');
+    const { code, message, details, statusCode } = apiError;
+    
+    let ErrorClass = errorClasses.ApiClientError;
+    
+    switch (code) {
+      case 'VALIDATION_ERROR': ErrorClass = errorClasses.ApiValidationError; break;
+      case 'INVALID_BIRTH_DATA': ErrorClass = errorClasses.ApiInvalidBirthDataError; break;
+      case 'RATE_LIMIT_EXCEEDED': ErrorClass = errorClasses.ApiRateLimitError; break;
+      case 'EPHEMERIS_UNAVAILABLE': ErrorClass = errorClasses.ApiEphemerisError; break;
+      case 'AI_SERVICE_ERROR': ErrorClass = errorClasses.ApiAIServiceError; break;
+      case 'TIMEOUT_ERROR': ErrorClass = errorClasses.ApiTimeoutError; break;
+      case 'CALCULATION_ERROR': ErrorClass = errorClasses.ApiCalculationError; break;
+      case 'DATABASE_ERROR': ErrorClass = errorClasses.ApiDatabaseError; break;
+      case 'INTERNAL_ERROR': ErrorClass = errorClasses.ApiInternalError; break;
+    }
+
+    const err = new ErrorClass(message, { ...details, requestId });
+    err.status = statusCode;
+    return err;
+  }
+}
+
+module.exports = AstrologyApiClient;

package/src/config.js

@@ -0,0 +1,27 @@
+/**
+ * Global Configuration for Astrology API Client (SDK Sec 2)
+ */
+module.exports = {
+  DEFAULT_BASE_URL: process.env.ASTROLOGY_API_BASE_URL || 'http://localhost:10000',
+  DEFAULT_TIMEOUT: Math.max(1000, Math.min(parseInt(process.env.ASTROLOGY_API_TIMEOUT, 10) || 15000, 60000)),
+  MAX_TIMEOUT_CEILING: 60000,
+  FLAKY_TIMEOUT: parseInt(process.env.ASTROLOGY_FLAKY_TIMEOUT, 10) || 60000,
+  MEMORY_HWM: parseFloat(process.env.ASTROLOGY_MEMORY_HWM) || 0.8, // High Water Mark for Aggressive Mode
+  IDLE_TIMEOUT: parseInt(process.env.ASTROLOGY_IDLE_TIMEOUT, 10) || 15 * 60 * 1000, // 15 Minutes
+  LOCK_TTL: parseInt(process.env.ASTROLOGY_LOCK_TTL, 10) || 5000,
+  
+  // Connection Pooling (SDK Sec 9.C)
+   AGENT_OPTIONS: {
+     keepAlive: true,
+     maxSockets: parseInt(process.env.ASTROLOGY_MAX_SOCKETS, 10) || 100,
+     freeSocketTimeout: parseInt(process.env.ASTROLOGY_FREE_SOCKET_TIMEOUT, 10) || 30000
+   },
+  
+  // Compatibility Mapping (Shim Layer - SDK Sec 13.B)
+  COMPATIBILITY_MAP: {
+    'dasha.calculateDasha': 'dasha.getDashaPredictiveAnalysis',
+    'birthchart.getSummary': 'birthchart.getBirthChartSummary'
+  },
+
+  RETRYABLE_STATUSES: [408, 500, 502, 503, 504]
+};

package/src/index.js

@@ -0,0 +1,7 @@
+const AstrologyApiClient = require('./AstrologyApiClient');
+const ApiClientError = require('./utils/ApiClientError');
+
+module.exports = {
+  AstrologyApiClient,
+  ...ApiClientError
+};

package/src/utils/ApiClientError.js

@@ -0,0 +1,73 @@
+class ApiClientError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code || 'API_ERROR';
+    this.details = details;
+    this.requestId = details.requestId;
+  }
+}
+
+class ApiValidationError extends ApiClientError {
+  constructor(message, details = {}) {
+    super(message || 'Validation Failed', 'VALIDATION_ERROR', details);
+    this.mappedErrors = this._mapValidationErrors(details.validationErrors);
+  }
+
+  /**
+   * Translates raw AJV paths (e.g., "/birthData/time") into clean UI-friendly nested objects (SDK Sec 7.A)
+   */
+  _mapValidationErrors(errors) {
+    if (!Array.isArray(errors)) return {};
+    const mapped = {};
+    
+    errors.forEach(err => {
+      // Translates "/birthData/time" -> ['birthData', 'time']
+      const path = (err.field || err.instancePath || '').split('/').filter(Boolean);
+      if (path.length === 0) {
+        mapped.general = err.message;
+        return;
+      }
+
+      let current = mapped;
+      // Navigate/build nested object structure
+      for (let i = 0; i < path.length - 1; i++) {
+        current[path[i]] = current[path[i]] || {};
+        current = current[path[i]];
+      }
+      // Assign message: { birthData: { time: "Required field missing" } }
+      current[path[path.length - 1]] = err.message;
+    });
+
+    return mapped;
+  }
+}
+
+class ApiInvalidBirthDataError extends ApiClientError { constructor(msg, details) { super(msg || "Invalid birth data", "INVALID_BIRTH_DATA", details); } }
+class ApiRateLimitError extends ApiClientError { constructor(msg, details) { super(msg || "Rate limit exceeded", "RATE_LIMIT_EXCEEDED", details); } }
+class ApiEphemerisError extends ApiClientError { constructor(msg, details) { super(msg || "Ephemeris service unavailable", "EPHEMERIS_UNAVAILABLE", details); } }
+class ApiAIServiceError extends ApiClientError { constructor(msg, details) { super(msg || "AI service unavailable", "AI_SERVICE_ERROR", details); } }
+class ApiTimeoutError extends ApiClientError { constructor(msg, details) { super(msg || "Operation timed out", "TIMEOUT_ERROR", details); } }
+class ApiCalculationError extends ApiClientError { constructor(msg, details) { super(msg || "Calculation failed", "CALCULATION_ERROR", details); } }
+class ApiDatabaseError extends ApiClientError { constructor(msg, details) { super(msg || "Database error", "DATABASE_ERROR", details); } }
+class ApiInternalError extends ApiClientError { constructor(msg, details) { super(msg || "Internal server error", "INTERNAL_ERROR", details); } }
+class ApiParseError extends ApiClientError { 
+  constructor(msg, details) { 
+    super(msg || "Failed to parse API response", "PARSE_ERROR", details); 
+    this.rawData = details.rawData;
+  } 
+}
+
+module.exports = {
+  ApiClientError,
+  ApiValidationError,
+  ApiInvalidBirthDataError,
+  ApiRateLimitError,
+  ApiEphemerisError,
+  ApiAIServiceError,
+  ApiTimeoutError,
+  ApiCalculationError,
+  ApiDatabaseError,
+  ApiInternalError,
+  ApiParseError
+};

package/src/utils/CircuitBreaker.js

@@ -0,0 +1,48 @@
+/**
+ * Circuit Breaker Pattern for service resilience
+ */
+class CircuitBreaker {
+  constructor(options = {}) {
+    this.failureThreshold = options.failureThreshold || 5;
+    this.resetTimeout = options.resetTimeout || 30000;
+    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
+    this.failures = 0;
+    this.nextAttempt = 0;
+  }
+
+  async execute(fn, isFailure = () => true) {
+    if (this.state === 'OPEN') {
+      if (Date.now() > this.nextAttempt) {
+        this.state = 'HALF_OPEN';
+      } else {
+        throw new Error('Circuit Breaker is OPEN');
+      }
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      if (isFailure(error)) {
+        this.onFailure();
+      }
+      throw error;
+    }
+  }
+
+  onSuccess() {
+    this.failures = 0;
+    this.state = 'CLOSED';
+  }
+
+  onFailure() {
+    this.failures++;
+    if (this.failures >= this.failureThreshold) {
+      this.state = 'OPEN';
+      this.nextAttempt = Date.now() + this.resetTimeout;
+    }
+  }
+}
+
+module.exports = CircuitBreaker;

package/src/utils/ContextStore.js

@@ -0,0 +1,107 @@
+const EventEmitter = require('events');
+
+/**
+ * In-memory LRU Cache for immutable astrology data (SDK Sec 8)
+ */
+class ContextStore extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.maxSize = options.maxSize || 1000;
+    this.ttl = options.ttl || 3600 * 1000;
+    this.idleTimeout = options.idleTimeout || 15 * 60 * 1000; 
+    
+    // SDK Sec 8.A: O(1) LRU using Doubly Linked List
+    this.cache = new Map(); // key -> node
+    this.head = null; // Most Recent
+    this.tail = null; // Least Recent
+    
+    // SDK Sec 8.B: Aggressive Mode
+    this._startMemoryMonitor();
+    // SDK Sec 8.C: Sweep Cycle
+    this._startSweepCycle();
+  }
+
+  async set(key, value) {
+    if (this.cache.has(key)) {
+      this._remove(this.cache.get(key));
+    } else if (this.cache.size >= this.maxSize && this.tail) {
+      // Evict Least Recently Used
+      this.cache.delete(this.tail.key);
+      this._remove(this.tail);
+    }
+
+    const node = { key, value, expiry: Date.now() + this.ttl };
+    this._add(node);
+    this.cache.set(key, node);
+  }
+
+  async get(key) {
+    const node = this.cache.get(key);
+    if (!node) return null;
+    
+    if (Date.now() > node.expiry) {
+      this.cache.delete(key);
+      this._remove(node);
+      return null;
+    }
+
+    // Move to front (Most Recently Used)
+    this._remove(node);
+    this._add(node);
+    
+    return node.value;
+  }
+
+  _add(node) {
+    node.next = this.head;
+    node.prev = null;
+    if (this.head) this.head.prev = node;
+    this.head = node;
+    if (!this.tail) this.tail = node;
+  }
+
+  _remove(node) {
+    if (node.prev) node.prev.next = node.next;
+    else this.head = node.next;
+    
+    if (node.next) node.next.prev = node.prev;
+    else this.tail = node.prev;
+
+    // Clean up node references to avoid memory leaks
+    node.next = null;
+    node.prev = null;
+  }
+
+  _startMemoryMonitor() {
+    setInterval(() => {
+      const { heapUsed, heapTotal } = process.memoryUsage();
+      const usageRatio = heapUsed / heapTotal;
+      if (usageRatio > 0.8) {
+        this.emit('alert', 'Memory pressure detected. Entering Aggressive Mode.');
+        // SDK Sec 8.B: Halve inactivity timeout (minimum 1 minute)
+        this.idleTimeout = Math.max(60000, this.idleTimeout / 2);
+        this.clear();
+      }
+    }, 30000);
+  }
+
+  _startSweepCycle() {
+    setInterval(() => {
+      const now = Date.now();
+      for (const [key, node] of this.cache.entries()) {
+        if (now > node.expiry) {
+          this.cache.delete(key);
+          this._remove(node);
+        }
+      }
+    }, 300000); 
+  }
+
+  clear() { 
+    this.cache.clear(); 
+    this.head = null;
+    this.tail = null;
+  }
+}
+
+module.exports = ContextStore;

package/src/utils/DiagnosticsTracker.js

@@ -0,0 +1,52 @@
+/**
+ * Aggregates SDK-level errors and diagnostics (SDK Sec 9.E)
+ */
+class DiagnosticsTracker {
+  constructor() {
+    this.stats = {
+      errors: {},
+      recent_failures: [],
+      total_requests: 0,
+      total_bytes_sent: 0,
+      total_bytes_received: 0
+    };
+  }
+
+  recordRequest(sent, received) {
+    this.stats.total_requests++;
+    this.stats.total_bytes_sent += sent || 0;
+    this.stats.total_bytes_received += received || 0;
+  }
+
+  trackError(type, requestId) {
+    const category = this._mapToCategory(type);
+    this.stats.errors[category] = (this.stats.errors[category] || 0) + 1;
+    this.stats.recent_failures.push({ category, requestId, timestamp: Date.now() });
+    
+    if (this.stats.recent_failures.length > 50) this.stats.recent_failures.shift();
+  }
+
+  _mapToCategory(type) {
+    if (['ECONNREFUSED', 'ETIMEDOUT', 'ApiNetworkError'].includes(type)) return 'CONNECTION';
+    if (['ApiValidationError'].includes(type)) return 'VALIDATION';
+    if (['ApiUnauthorizedError'].includes(type)) return 'IDENTITY';
+    return 'SERVER';
+  }
+
+  getHealthReport() {
+    const NetworkMonitor = require('./NetworkMonitor');
+    return {
+      uptime: process.uptime(),
+      error_distribution: this.stats.errors,
+      avg_latency: NetworkMonitor.getAverageLatency(),
+      network_status: NetworkMonitor.status,
+      usage: {
+        total_requests: this.stats.total_requests,
+        total_bytes_sent: this.stats.total_bytes_sent,
+        total_bytes_received: this.stats.total_bytes_received
+      }
+    };
+  }
+}
+
+module.exports = new DiagnosticsTracker();

package/src/utils/Interceptors.js

@@ -0,0 +1,50 @@
+const { getLogger } = require('@astrology/shared/logger');
+const logger = getLogger('api-client-interceptors');
+
+/**
+ * Global Interceptors for API lifecycle events (SDK Sec 11.B)
+ */
+class Interceptors {
+  constructor() {
+    this.requestHooks = [];
+    this.responseHooks = [];
+    this.errorHooks = [];
+  }
+
+  onRequest(config) {
+    // Log the transition state before sending (SDK Sec 7.D Telemetry)
+    logger.info({
+      msg: 'API Request Started',
+      requestId: config.requestId,
+      service: config.service,
+      method: config.method,
+      dropoff_marker: 'REQUEST_INIT'
+    });
+
+    this.requestHooks.forEach(hook => hook(config));
+    return config;
+  }
+
+  onResponse(response, result) {
+    this.responseHooks.forEach(hook => hook(response, result));
+    return result;
+  }
+
+  onError(error) {
+    logger.error({
+      msg: 'API Request Failed',
+      requestId: error.requestId,
+      code: error.code,
+      message: error.message
+    });
+
+    this.errorHooks.forEach(hook => hook(error));
+    return error;
+  }
+
+  addRequestHook(hook) { this.requestHooks.push(hook); }
+  addResponseHook(hook) { this.responseHooks.push(hook); }
+  addErrorHook(hook) { this.errorHooks.push(hook); }
+}
+
+module.exports = Interceptors;

package/src/utils/NetworkMonitor.js

@@ -0,0 +1,41 @@
+/**
+ * Monitors backend connection health and latency (SDK Sec 10.A)
+ */
+class NetworkMonitor {
+  constructor() {
+    this.history = [];
+    this.status = 'stable';
+  }
+
+  record(latency, success = true) {
+    this.history.push({ latency, timestamp: Date.now(), success });
+    if (this.history.length > 10) this.history.shift(); // SDK uses 10 for window
+
+    this._updateStatus();
+  }
+
+  _updateStatus() {
+    if (this.history.length === 0) {
+      this.status = 'stable';
+      return;
+    }
+
+    const avgLatency = this.getAverageLatency();
+    const failureCount = this.history.filter(h => !h.success).length;
+
+    // SDK Sec 10.A Logic: High avg latency or recent failures trigger flaky status
+    if (avgLatency > 5000 || failureCount > 2) {
+      this.status = 'flaky';
+    } else {
+      this.status = 'stable';
+    }
+  }
+
+  getAverageLatency() {
+    if (this.history.length === 0) return 0;
+    const sum = this.history.reduce((a, b) => a + b.latency, 0);
+    return sum / this.history.length;
+  }
+}
+
+module.exports = new NetworkMonitor();