@oxyhq/core 10.2.0 → 11.0.0

package/dist/types/index.d.ts

@@ -57,7 +57,7 @@ export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager'
 export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
-export type { TopicData, TopicTranslation } from './models/Topic';
+export type { TopicData, TopicTranslation, TopicListResult } from './models/Topic';
 export { SUPPORTED_LANGUAGES, FALLBACK_LOCALE, getBaseLanguage, normalizeLocale, isSupportedLocale, getLanguageMetadata, getLanguageName, getNativeLanguageName, isRTLLocale, getUserLanguages, getPrimaryLanguage, } from './utils/languageUtils';
 export type { SupportedLanguage } from './utils/languageUtils';
 export { getPlatformOS, setPlatformOS, isWeb, isNative, isIOS, isAndroid, isWebBrowser, } from './utils/platform';
@@ -68,7 +68,6 @@ export type { ThemeValue } from './shared/utils/themeUtils';
 export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './shared/utils/errorUtils';
 export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './shared/utils/networkUtils';
 export type { CircuitBreakerState, CircuitBreakerConfig } from './shared/utils/networkUtils';
-export { isDev, debugLog, debugWarn, debugError, createDebugLogger, } from './shared/utils/debugUtils';
 export { translate } from './i18n';
 export { buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils';
 export type { PaginationParams, ApiResponse, ErrorResponse, } from './utils/apiUtils';
@@ -76,8 +75,8 @@ export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, }
 export { retryAsync } from './utils/asyncUtils';
 export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils';
 export { normalizeInlineText, normalizeMultilineText, } from './utils/textNormalization';
-export { logger, LogLevel, logAuth, logApi, logSession, logUser, logDevice, logPayment, logPerformance, } from './utils/loggerUtils';
-export type { LogContext } from './utils/loggerUtils';
+export { logger, createLogger, configureLogger, getLoggerConfig, resetLoggerConfig, consoleSink, isDev, } from './logger';
+export type { Logger, LogLevel, EmittableLogLevel, LogContext, LogEntry, LogSink, LoggerConfig, } from './logger';
 export { updateAvatarVisibility } from './utils/avatarUtils';
 export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, getAccountColor, } from './utils/accountUtils';
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';

package/dist/types/logger/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @oxyhq/core/logger — the ecosystem-wide logging chokepoint.
+ *
+ * A tiny, dependency-free, universal logger that works unchanged in React
+ * Native, browsers, Node, and Bun. Every Oxy app and package should log
+ * through here instead of calling `console.*` directly, so that level,
+ * formatting, and transport are controlled in ONE place.
+ *
+ * Design goals:
+ *  - Zero dependencies. No Node-only imports, no `process.stdout` assumptions.
+ *  - Four levels (`debug` | `info` | `warn` | `error`) plus `silent`.
+ *  - Namespaced child loggers via `createLogger('mention:feed')` / `.child()`.
+ *  - Structured context objects carried through to the sink.
+ *  - A single pluggable sink so backends can pipe to pino / CloudWatch / etc.
+ *    without touching any call site.
+ *  - Debug is off in production by default (`__DEV__` on RN, `NODE_ENV`
+ *    elsewhere); override globally with `configureLogger({ level })`.
+ *
+ * @module logger
+ */
+/** Ordered severity levels. `silent` disables all output. */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/** The levels that actually emit an entry (everything but `silent`). */
+export type EmittableLogLevel = Exclude<LogLevel, 'silent'>;
+/**
+ * Structured, JSON-friendly context attached to a log line. The well-known
+ * keys are optional hints; arbitrary keys are allowed so callers can attach
+ * whatever structured fields their sink cares about.
+ */
+export interface LogContext {
+    component?: string;
+    method?: string;
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    [key: string]: unknown;
+}
+/** A single normalized log record handed to the active sink. */
+export interface LogEntry {
+    level: EmittableLogLevel;
+    message: string;
+    /** Colon-joined namespace, e.g. `mention:feed`. Absent for the root logger. */
+    namespace?: string;
+    /** Merged structured context (logger base context + per-call context). */
+    context?: LogContext;
+    /** The error value passed to `.error(message, error, …)`, if any. */
+    error?: unknown;
+    /** Extra variadic args passed after the context. */
+    args: unknown[];
+    /** ISO-8601 timestamp of when the entry was created. */
+    timestamp: string;
+}
+/** A transport that receives every emitted (level-passing) entry. */
+export type LogSink = (entry: LogEntry) => void;
+/** Global logger configuration. */
+export interface LoggerConfig {
+    level: LogLevel;
+    sink: LogSink;
+}
+/** A namespaced logger. Instances are cheap; derive children with `.child()`. */
+export interface Logger {
+    /** The logger's colon-joined namespace, if any. */
+    readonly namespace?: string;
+    debug(message: string, context?: LogContext, ...args: unknown[]): void;
+    info(message: string, context?: LogContext, ...args: unknown[]): void;
+    warn(message: string, context?: LogContext, ...args: unknown[]): void;
+    error(message: string, error?: unknown, context?: LogContext, ...args: unknown[]): void;
+    /** Derive a child logger with an extended namespace and merged base context. */
+    child(namespace: string, context?: LogContext): Logger;
+}
+/**
+ * True in development. Uses React Native's `__DEV__` when present, otherwise
+ * falls back to `process.env.NODE_ENV === 'development'`. Never throws.
+ */
+export declare function isDev(): boolean;
+/**
+ * Default sink: routes each entry to the matching `console` method. `info` and
+ * `debug` go to `console.log` (RN/browser-safe — `console.debug`/`console.info`
+ * are inconsistently surfaced across runtimes).
+ */
+export declare const consoleSink: LogSink;
+/**
+ * Update the global logger configuration. Affects every logger instance
+ * (root and children) immediately. Pass `{ level }` to gate output and/or
+ * `{ sink }` to redirect transport (pino, CloudWatch, a test capture, …).
+ */
+export declare function configureLogger(partial: Partial<LoggerConfig>): void;
+/** Read a snapshot of the current global configuration. */
+export declare function getLoggerConfig(): Readonly<LoggerConfig>;
+/** Restore the default level (env-derived) and the console sink. */
+export declare function resetLoggerConfig(): void;
+/** The shared root logger. Prefer a namespaced `createLogger(...)` in modules. */
+export declare const logger: Logger;
+/**
+ * Create a namespaced logger.
+ *
+ * @example
+ * ```ts
+ * const log = createLogger('mention:feed');
+ * log.info('loaded', { count: 20 });
+ * const sub = log.child('prefetch'); // namespace → 'mention:feed:prefetch'
+ * ```
+ */
+export declare function createLogger(namespace?: string, context?: LogContext): Logger;

package/dist/types/mixins/OxyServices.topics.d.ts

@@ -4,7 +4,7 @@
  * Provides methods for topic discovery and management
  */
 import type { OxyServicesBase } from '../OxyServices.base';
-import type { TopicData, TopicTranslation } from '../models/Topic';
+import type { TopicData, TopicListResult, TopicTranslation } from '../models/Topic';
 export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -23,7 +23,7 @@ export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>
         /**
          * List topics with optional filters
          * @param options - Filter and pagination options
-         * @returns List of topics
+         * @returns Paginated topics envelope (`topics` plus `total`/`limit`/`offset`)
          */
         listTopics(options?: {
             type?: string;
@@ -31,7 +31,7 @@ export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>
             limit?: number;
             offset?: number;
             locale?: string;
-        }): Promise<TopicData[]>;
+        }): Promise<TopicListResult>;
         /**
          * Get a single topic by slug
          * @param slug - Topic slug

package/dist/types/models/Topic.d.ts

@@ -30,3 +30,13 @@ export interface TopicData {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Paginated result of {@link OxyServices.listTopics}. Mirrors the `GET /topics`
+ * envelope so callers keep access to `total`/`offset` for pagination.
+ */
+export interface TopicListResult {
+    topics: TopicData[];
+    total: number;
+    limit: number;
+    offset: number;
+}

package/dist/types/utils/requestUtils.d.ts

@@ -93,7 +93,7 @@ export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
  * Simple logger with level support
  *
  * Lightweight logger for HTTP clients and utilities.
- * For more advanced logging, use loggerUtils.ts
+ * For structured, namespaced, level-gated logging, use `@oxyhq/core/logger`.
  *
  * @example
  * ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "10.2.0",
+  "version": "11.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -9,6 +9,9 @@
     "*": {
       "server": [
         "dist/types/server/index.d.ts"
+      ],
+      "logger": [
+        "dist/types/logger/index.d.ts"
       ]
     }
   },
@@ -41,6 +44,18 @@
       },
       "default": "./dist/esm/server/index.js"
     },
+    "./logger": {
+      "react-native": "./dist/esm/logger/index.js",
+      "import": {
+        "types": "./dist/types/logger/index.d.ts",
+        "default": "./dist/esm/logger/index.js"
+      },
+      "require": {
+        "types": "./dist/types/logger/index.d.ts",
+        "default": "./dist/cjs/logger/index.js"
+      },
+      "default": "./dist/esm/logger/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/src/boot/sessionColdBoot.ts

@@ -22,7 +22,7 @@
  */
 import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/coldBoot';
 import { isNative as detectNative } from '../utils/platform';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';

package/src/crypto/keyManager.ts

@@ -9,8 +9,7 @@ import { ec as EC } from 'elliptic';
 import type { ECKeyPair } from 'elliptic';
 import { isWeb, isIOS, isAndroid } from '../utils/platform';
 import { type ExpoCryptoLike, type ExpoSecureStoreLike, isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
-import { logger } from '../utils/loggerUtils';
-import { isDev } from '../shared/utils/debugUtils';
+import { isDev, logger } from '../logger';
 
 /**
  * Options for expo-secure-store calls made by KeyManager.

package/src/crypto/signatureService.ts

@@ -20,7 +20,7 @@ import {
   isNodeJS,
 } from '@oxyhq/protocol';
 import { KeyManager } from './keyManager';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 
 export interface SignedMessage {
   message: string;

package/src/index.ts

@@ -317,7 +317,7 @@ export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 
 // Topic enums + type
 export { TopicType, TopicSource } from './models/Topic';
-export type { TopicData, TopicTranslation } from './models/Topic';
+export type { TopicData, TopicTranslation, TopicListResult } from './models/Topic';
 
 // ---------------------------------------------------------------------------
 // Languages
@@ -402,14 +402,6 @@ export {
 } from './shared/utils/networkUtils';
 export type { CircuitBreakerState, CircuitBreakerConfig } from './shared/utils/networkUtils';
 
-export {
-    isDev,
-    debugLog,
-    debugWarn,
-    debugError,
-    createDebugLogger,
-} from './shared/utils/debugUtils';
-
 // ---------------------------------------------------------------------------
 // i18n
 // ---------------------------------------------------------------------------
@@ -475,20 +467,26 @@ export {
 } from './utils/textNormalization';
 
 // ---------------------------------------------------------------------------
-// Logging
+// Logging — the ecosystem-wide chokepoint (also at subpath `@oxyhq/core/logger`)
 // ---------------------------------------------------------------------------
 export {
     logger,
+    createLogger,
+    configureLogger,
+    getLoggerConfig,
+    resetLoggerConfig,
+    consoleSink,
+    isDev,
+} from './logger';
+export type {
+    Logger,
     LogLevel,
-    logAuth,
-    logApi,
-    logSession,
-    logUser,
-    logDevice,
-    logPayment,
-    logPerformance,
-} from './utils/loggerUtils';
-export type { LogContext } from './utils/loggerUtils';
+    EmittableLogLevel,
+    LogContext,
+    LogEntry,
+    LogSink,
+    LoggerConfig,
+} from './logger';
 
 // ---------------------------------------------------------------------------
 // Avatars

package/src/logger/__tests__/logger.test.ts

@@ -0,0 +1,207 @@
+import {
+  configureLogger,
+  consoleSink,
+  createLogger,
+  getLoggerConfig,
+  isDev,
+  logger,
+  resetLoggerConfig,
+  type LogEntry,
+} from '../index';
+
+/** Install a capturing sink and return the collected entries. */
+function captureEntries(): LogEntry[] {
+  const entries: LogEntry[] = [];
+  configureLogger({ sink: (entry) => entries.push(entry) });
+  return entries;
+}
+
+describe('logger', () => {
+  afterEach(() => {
+    resetLoggerConfig();
+  });
+
+  describe('level gating', () => {
+    it('emits only levels at or below the configured level', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'warn' });
+
+      logger.debug('d');
+      logger.info('i');
+      logger.warn('w');
+      logger.error('e');
+
+      expect(entries.map((entry) => entry.level)).toEqual(['warn', 'error']);
+    });
+
+    it('emits everything at debug level', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+
+      logger.debug('d');
+      logger.info('i');
+      logger.warn('w');
+      logger.error('e');
+
+      expect(entries.map((entry) => entry.level)).toEqual(['debug', 'info', 'warn', 'error']);
+    });
+
+    it('emits nothing at silent level', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'silent' });
+
+      logger.debug('d');
+      logger.info('i');
+      logger.warn('w');
+      logger.error('e');
+
+      expect(entries).toHaveLength(0);
+    });
+  });
+
+  describe('namespacing', () => {
+    it('root logger has no namespace', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+
+      logger.info('hello');
+
+      expect(entries[0].namespace).toBeUndefined();
+    });
+
+    it('createLogger sets the namespace', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+
+      createLogger('mention:feed').info('loaded');
+
+      expect(entries[0].namespace).toBe('mention:feed');
+    });
+
+    it('child() colon-joins nested namespaces', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+
+      createLogger('mention:feed').child('prefetch').info('done');
+
+      expect(entries[0].namespace).toBe('mention:feed:prefetch');
+    });
+  });
+
+  describe('structured context', () => {
+    it('passes per-call context through to the sink', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+
+      logger.info('hi', { userId: 'u1', requestId: 'r1' });
+
+      expect(entries[0].context).toEqual({ userId: 'u1', requestId: 'r1' });
+    });
+
+    it('merges base context with per-call context (per-call wins)', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+
+      createLogger('svc', { component: 'Svc', userId: 'base' }).warn('x', { userId: 'call', method: 'm' });
+
+      expect(entries[0].context).toEqual({ component: 'Svc', userId: 'call', method: 'm' });
+    });
+
+    it('captures the error value on error()', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+      const boom = new Error('boom');
+
+      logger.error('failed', boom, { component: 'Svc' });
+
+      expect(entries[0].error).toBe(boom);
+      expect(entries[0].context).toEqual({ component: 'Svc' });
+    });
+
+    it('forwards trailing variadic args', () => {
+      const entries = captureEntries();
+      configureLogger({ level: 'debug' });
+
+      logger.warn('x', { component: 'Svc' }, 1, 'two');
+
+      expect(entries[0].args).toEqual([1, 'two']);
+    });
+  });
+
+  describe('sink override', () => {
+    it('routes all output through the configured sink', () => {
+      const sink = jest.fn();
+      configureLogger({ level: 'debug', sink });
+
+      logger.info('routed');
+
+      expect(sink).toHaveBeenCalledTimes(1);
+      expect(sink.mock.calls[0][0]).toMatchObject({ level: 'info', message: 'routed' });
+    });
+
+    it('resetLoggerConfig restores the console sink', () => {
+      configureLogger({ sink: jest.fn() });
+      resetLoggerConfig();
+      expect(getLoggerConfig().sink).toBe(consoleSink);
+    });
+  });
+
+  describe('consoleSink', () => {
+    it('routes error to console.error and warn to console.warn', () => {
+      const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+      const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+      const now = new Date().toISOString();
+
+      consoleSink({ level: 'error', message: 'e', args: [], timestamp: now });
+      consoleSink({ level: 'warn', message: 'w', args: [], timestamp: now });
+      consoleSink({ level: 'info', message: 'i', args: [], timestamp: now });
+
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(logSpy).toHaveBeenCalledTimes(1);
+
+      errorSpy.mockRestore();
+      warnSpy.mockRestore();
+      logSpy.mockRestore();
+    });
+  });
+
+  describe('isDev', () => {
+    // `isDev` reads the RN-injected global `__DEV__` first; model it as an
+    // optional global so we can exercise the NODE_ENV fallback without `as any`.
+    const globalWithDev = globalThis as typeof globalThis & { __DEV__?: boolean };
+    const originalDev = globalWithDev.__DEV__;
+    const originalNodeEnv = process.env.NODE_ENV;
+
+    afterEach(() => {
+      // Setting to `undefined` makes `typeof __DEV__` read as 'undefined', the
+      // same signal `isDev` keys off — no need for the `delete` operator.
+      globalWithDev.__DEV__ = originalDev;
+      process.env.NODE_ENV = originalNodeEnv;
+    });
+
+    it('returns true when __DEV__ is true (React Native)', () => {
+      globalWithDev.__DEV__ = true;
+      expect(isDev()).toBe(true);
+    });
+
+    it('returns false when __DEV__ is false regardless of NODE_ENV', () => {
+      globalWithDev.__DEV__ = false;
+      process.env.NODE_ENV = 'development';
+      expect(isDev()).toBe(false);
+    });
+
+    it('falls back to NODE_ENV=development when __DEV__ is undefined', () => {
+      globalWithDev.__DEV__ = undefined;
+      process.env.NODE_ENV = 'development';
+      expect(isDev()).toBe(true);
+    });
+
+    it('returns false when NODE_ENV is production and __DEV__ is undefined', () => {
+      globalWithDev.__DEV__ = undefined;
+      process.env.NODE_ENV = 'production';
+      expect(isDev()).toBe(false);
+    });
+  });
+});