@oxyhq/core 10.2.0 → 11.0.0

package/src/logger/index.ts

@@ -0,0 +1,217 @@
+/**
+ * @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
+ */
+
+/* global __DEV__ */
+declare const __DEV__: boolean | undefined;
+
+/** 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'>;
+
+const LEVEL_WEIGHT: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+/**
+ * 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 function isDev(): boolean {
+  if (typeof __DEV__ !== 'undefined') return __DEV__ === true;
+  try {
+    return typeof process !== 'undefined' && process.env?.NODE_ENV === 'development';
+  } catch {
+    return false;
+  }
+}
+
+function formatPrefix(entry: LogEntry): string {
+  const parts = [entry.timestamp, entry.level.toUpperCase()];
+  if (entry.namespace) parts.push(`[${entry.namespace}]`);
+  return parts.join(' ');
+}
+
+/**
+ * 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 const consoleSink: LogSink = (entry) => {
+  const extras: unknown[] = [];
+  if (entry.context && Object.keys(entry.context).length > 0) extras.push(entry.context);
+  if (entry.error !== undefined) extras.push(entry.error);
+  if (entry.args.length > 0) extras.push(...entry.args);
+
+  const line = `${formatPrefix(entry)} ${entry.message}`;
+  if (entry.level === 'error') console.error(line, ...extras);
+  else if (entry.level === 'warn') console.warn(line, ...extras);
+  else console.log(line, ...extras);
+};
+
+function defaultLevel(): LogLevel {
+  return isDev() ? 'debug' : 'info';
+}
+
+const config: LoggerConfig = {
+  level: defaultLevel(),
+  sink: consoleSink,
+};
+
+/**
+ * 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 function configureLogger(partial: Partial<LoggerConfig>): void {
+  if (partial.level !== undefined) config.level = partial.level;
+  if (partial.sink !== undefined) config.sink = partial.sink;
+}
+
+/** Read a snapshot of the current global configuration. */
+export function getLoggerConfig(): Readonly<LoggerConfig> {
+  return { level: config.level, sink: config.sink };
+}
+
+/** Restore the default level (env-derived) and the console sink. */
+export function resetLoggerConfig(): void {
+  config.level = defaultLevel();
+  config.sink = consoleSink;
+}
+
+function mergeContext(base?: LogContext, extra?: LogContext): LogContext | undefined {
+  if (!base) return extra;
+  if (!extra) return base;
+  return { ...base, ...extra };
+}
+
+function emit(
+  level: EmittableLogLevel,
+  namespace: string | undefined,
+  baseContext: LogContext | undefined,
+  message: string,
+  error: unknown,
+  context: LogContext | undefined,
+  args: unknown[],
+): void {
+  if (LEVEL_WEIGHT[level] > LEVEL_WEIGHT[config.level]) return;
+  config.sink({
+    level,
+    message,
+    namespace,
+    context: mergeContext(baseContext, context),
+    error,
+    args,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+function makeLogger(namespace: string | undefined, baseContext: LogContext | undefined): Logger {
+  return {
+    namespace,
+    debug: (message, context, ...args) =>
+      emit('debug', namespace, baseContext, message, undefined, context, args),
+    info: (message, context, ...args) =>
+      emit('info', namespace, baseContext, message, undefined, context, args),
+    warn: (message, context, ...args) =>
+      emit('warn', namespace, baseContext, message, undefined, context, args),
+    error: (message, error, context, ...args) =>
+      emit('error', namespace, baseContext, message, error, context, args),
+    child: (childNamespace, childContext) =>
+      makeLogger(
+        namespace ? `${namespace}:${childNamespace}` : childNamespace,
+        mergeContext(baseContext, childContext),
+      ),
+  };
+}
+
+/** The shared root logger. Prefer a namespaced `createLogger(...)` in modules. */
+export const logger: Logger = makeLogger(undefined, undefined);
+
+/**
+ * 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 function createLogger(namespace?: string, context?: LogContext): Logger {
+  return makeLogger(namespace, context);
+}

package/src/mixins/OxyServices.assets.ts

@@ -1,7 +1,7 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxyhq/protocol';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
 
 /**
@@ -428,8 +428,8 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
 
         return response;
       } catch (error) {
-        console.error('File upload error:', error);
-        
+        logger.error('File upload error', error, { component: 'OxyServices.assets' });
+
         let errorMessage = 'File upload failed';
         
         if (error instanceof Error) {

package/src/mixins/OxyServices.auth.ts

@@ -13,7 +13,7 @@ import { OxyAuthenticationError } from '../OxyServices.errors';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { loadNodeCrypto } from '@oxyhq/protocol';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
 
 /**

package/src/mixins/OxyServices.language.ts

@@ -5,7 +5,7 @@ import { normalizeLocale, getPrimaryLanguage, getLanguageMetadata, getLanguageNa
 import type { SupportedLanguage } from '../utils/languageUtils';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadAsyncStorage } from '@oxyhq/protocol';
-import { isDev } from '../shared/utils/debugUtils';
+import { logger } from '../logger';
 
 /**
  * Cross-mixin surface consumed by the language methods. `getCurrentUser` is
@@ -48,7 +48,7 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
             removeItem: storage.removeItem.bind(storage),
           };
         } catch (error) {
-          console.error('AsyncStorage not available in React Native:', error);
+          logger.error('AsyncStorage not available in React Native', error, { component: 'OxyServices.language' });
           throw new Error('AsyncStorage is required in React Native environment');
         }
       } else {
@@ -103,9 +103,7 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
 
         return null;
       } catch (error) {
-        if (isDev()) {
-          console.warn('Failed to get current language:', error);
-        }
+        logger.warn('Failed to get current language', { component: 'OxyServices.language' }, error);
         return null;
       }
     }

package/src/mixins/OxyServices.privacy.ts

@@ -3,7 +3,7 @@
  */
 import type { BlockedUser, RestrictedUser } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
-import { isDev } from '../shared/utils/debugUtils';
+import { logger } from '../logger';
 
 export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -36,9 +36,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         });
       } catch (error) {
         // If there's an error, assume not in list to avoid breaking functionality
-        if (isDev()) {
-          console.warn('Error checking user list:', error);
-        }
+        logger.warn('Error checking user list', { component: 'OxyServices.privacy' }, error);
         return false;
       }
     }

package/src/mixins/OxyServices.security.ts

@@ -3,7 +3,7 @@
  */
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { SecurityActivity, SecurityActivityResponse, SecurityEventType } from '../models/interfaces';
-import { isDev } from '../shared/utils/debugUtils';
+import { logger } from '../logger';
 
 export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -80,11 +80,9 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
           { cache: false }
         );
       } catch (error) {
-        // Don't throw - logging failures shouldn't break user flow
-        // But log for monitoring
-        if (isDev()) {
-          console.warn('[OxyServices] Failed to log private key exported event:', error);
-        }
+        // Don't throw - logging failures shouldn't break user flow, but surface
+        // for monitoring via the shared logger sink.
+        logger.warn('[OxyServices] Failed to log private key exported event', { component: 'OxyServices.security' }, error);
       }
     }
 
@@ -102,11 +100,9 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
           { cache: false }
         );
       } catch (error) {
-        // Don't throw - logging failures shouldn't break user flow
-        // But log for monitoring
-        if (isDev()) {
-          console.warn('[OxyServices] Failed to log backup created event:', error);
-        }
+        // Don't throw - logging failures shouldn't break user flow, but surface
+        // for monitoring via the shared logger sink.
+        logger.warn('[OxyServices] Failed to log backup created event', { component: 'OxyServices.security' }, error);
       }
     }
   };

package/src/mixins/OxyServices.topics.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';
 import { CACHE_TIMES } from './mixinHelpers';
 
 export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T) {
@@ -22,10 +22,15 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       try {
         const params: Record<string, string> = {};
         if (locale) params.locale = locale;
-        return await this.makeRequest('GET', '/topics/categories', params, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.EXTRA_LONG,
-        });
+        // `GET /topics/categories` returns `{ categories: TopicData[] }` — the
+        // SDK's `unwrapResponse` only unwraps `{ data }`, so unwrap here.
+        const response = await this.makeRequest<{ categories: TopicData[] }>(
+          'GET',
+          '/topics/categories',
+          params,
+          { cache: true, cacheTTL: CACHE_TIMES.EXTRA_LONG }
+        );
+        return response.categories ?? [];
       } catch (error) {
         throw this.handleError(error);
       }
@@ -41,9 +46,14 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       try {
         const params: Record<string, string | number> = { q: query };
         if (limit) params.limit = limit;
-        return await this.makeRequest('GET', '/topics/search', params, {
-          cache: false,
-        });
+        // `GET /topics/search` returns `{ topics: TopicData[] }` — unwrap it.
+        const response = await this.makeRequest<{ topics: TopicData[] }>(
+          'GET',
+          '/topics/search',
+          params,
+          { cache: false }
+        );
+        return response.topics ?? [];
       } catch (error) {
         throw this.handleError(error);
       }
@@ -52,7 +62,7 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
     /**
      * List topics with optional filters
      * @param options - Filter and pagination options
-     * @returns List of topics
+     * @returns Paginated topics envelope (`topics` plus `total`/`limit`/`offset`)
      */
     async listTopics(options?: {
       type?: string;
@@ -60,7 +70,7 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       limit?: number;
       offset?: number;
       locale?: string;
-    }): Promise<TopicData[]> {
+    }): Promise<TopicListResult> {
       try {
         const params: Record<string, string | number> = {};
         if (options?.type) params.type = options.type;
@@ -68,10 +78,23 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
         if (options?.limit) params.limit = options.limit;
         if (options?.offset) params.offset = options.offset;
         if (options?.locale) params.locale = options.locale;
-        return await this.makeRequest('GET', '/topics', params, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.SHORT,
-        });
+        // `GET /topics` returns `{ topics, total, limit, offset }`. The pagination
+        // fields matter to callers, so return the whole envelope (typed) rather
+        // than throwing them away.
+        const response = await this.makeRequest<Partial<TopicListResult>>(
+          'GET',
+          '/topics',
+          params,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT }
+        );
+        const requestedLimit = typeof params.limit === 'number' ? params.limit : 0;
+        const requestedOffset = typeof params.offset === 'number' ? params.offset : 0;
+        return {
+          topics: response.topics ?? [],
+          total: response.total ?? response.topics?.length ?? 0,
+          limit: response.limit ?? requestedLimit,
+          offset: response.offset ?? requestedOffset,
+        };
       } catch (error) {
         throw this.handleError(error);
       }
@@ -102,9 +125,16 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       names: Array<{ name: string; type: string }>
     ): Promise<TopicData[]> {
       try {
-        return await this.makeRequest('POST', '/topics/resolve', { names }, {
-          cache: false,
-        });
+        // `POST /topics/resolve` returns `{ topics: Record<name, TopicData> }`
+        // (a name-keyed map, not an array). Unwrap and flatten to the resolved
+        // topics; each TopicData carries its own `name` for re-keying.
+        const response = await this.makeRequest<{ topics: Record<string, TopicData> }>(
+          'POST',
+          '/topics/resolve',
+          { names },
+          { cache: false }
+        );
+        return Object.values(response.topics ?? {});
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.user.ts

@@ -22,7 +22,7 @@ import { buildSearchParams, buildPaginationParams, type PaginationParams } from
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
 
 /**

package/src/mixins/OxyServices.utility.ts

@@ -10,7 +10,7 @@ import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadNodeCrypto } from '@oxyhq/protocol';
 import { buildUrl } from '../utils/apiUtils';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { CACHE_TIMES } from './mixinHelpers';
 
 interface JwtPayload {

package/src/mixins/__tests__/discoveryErrorHandling.test.ts

@@ -13,7 +13,7 @@
  */
 
 import { OxyServices } from '../../OxyServices';
-import { logger } from '../../utils/loggerUtils';
+import { logger } from '../../logger';
 
 /** A JSON success `Response` mimicking the API's `{ data: ... }` envelope. */
 function jsonResponse(data: unknown): Response {

package/src/mixins/__tests__/topics.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Topics mixin envelope-unwrapping tests.
+ *
+ * oxy-api returns ENVELOPES for the list/collection topic routes
+ * (`{ topics, total, limit, offset }`, `{ categories }`, `{ topics }`,
+ * `{ topics: <name-keyed map> }`), while the SDK's `unwrapResponse` only unwraps
+ * the `{ data }` success shape. These tests pin the mixin's own unwrapping so the
+ * public methods genuinely return `TopicData[]` / the pagination envelope — not a
+ * raw wrapper that a caller would `.map` over and crash on.
+ *
+ * They drive the REAL `makeRequest` path by mocking `globalThis.fetch`, so the
+ * `unwrapResponse` pass-through (no `data` key) is exercised end to end.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/** A raw JSON `Response` — the body is exactly what the topic routes return. */
+function rawResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/**
+ * A non-verified JWT whose payload decodes to the given claims. Puts the SDK in
+ * an authenticated state so the `POST /topics/resolve` carries a bearer header
+ * and skips the CSRF-token pre-fetch (which would otherwise consume a mock).
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+const topic = (id: string, name: string, extra: Record<string, unknown> = {}) => ({
+  _id: id,
+  name,
+  slug: name,
+  displayName: name,
+  description: '',
+  type: 'topic',
+  source: 'ai',
+  aliases: [],
+  isActive: true,
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-01T00:00:00.000Z',
+  ...extra,
+});
+
+describe('topics mixin envelope unwrapping', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid', enableRetry: false });
+    // Authenticate so the resolve POST skips the CSRF pre-fetch. Harmless for GETs.
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  describe('getTopicCategories', () => {
+    it('unwraps { categories } into a TopicData[]', async () => {
+      fetchMock.mockResolvedValueOnce(
+        rawResponse({ categories: [topic('c1', 'tech', { type: 'category' }), topic('c2', 'sports', { type: 'category' })] }),
+      );
+      const result = await oxy.getTopicCategories();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.map((t) => t._id)).toEqual(['c1', 'c2']);
+    });
+
+    it('returns [] when the envelope omits categories', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({}));
+      await expect(oxy.getTopicCategories()).resolves.toEqual([]);
+    });
+  });
+
+  describe('searchTopics', () => {
+    it('unwraps { topics } into a TopicData[]', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({ topics: [topic('t1', 'react'), topic('t2', 'reactivity')] }));
+      const result = await oxy.searchTopics('react');
+      expect(result.map((t) => t.name)).toEqual(['react', 'reactivity']);
+    });
+
+    it('returns [] when the envelope omits topics', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({}));
+      await expect(oxy.searchTopics('nothing')).resolves.toEqual([]);
+    });
+  });
+
+  describe('listTopics', () => {
+    it('returns the full pagination envelope', async () => {
+      fetchMock.mockResolvedValueOnce(
+        rawResponse({ topics: [topic('t1', 'a'), topic('t2', 'b')], total: 42, limit: 2, offset: 10 }),
+      );
+      const result = await oxy.listTopics({ limit: 2, offset: 10 });
+      expect(result.topics.map((t) => t._id)).toEqual(['t1', 't2']);
+      expect(result.total).toBe(42);
+      expect(result.limit).toBe(2);
+      expect(result.offset).toBe(10);
+    });
+
+    it('falls back to the requested limit/offset and topics.length when the server omits them', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({ topics: [topic('t1', 'a')] }));
+      const result = await oxy.listTopics({ limit: 5, offset: 3 });
+      expect(result.topics).toHaveLength(1);
+      expect(result.total).toBe(1);
+      expect(result.limit).toBe(5);
+      expect(result.offset).toBe(3);
+    });
+
+    it('returns an empty envelope when the server returns nothing useful', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({}));
+      const result = await oxy.listTopics();
+      expect(result).toEqual({ topics: [], total: 0, limit: 0, offset: 0 });
+    });
+  });
+
+  describe('resolveTopicNames', () => {
+    it('flattens the name-keyed { topics } map into a TopicData[]', async () => {
+      // POST /topics/resolve returns a Record keyed by lowercased name, NOT an array.
+      fetchMock.mockResolvedValueOnce(
+        rawResponse({ topics: { react: topic('t1', 'react'), vue: topic('t2', 'vue') } }),
+      );
+      const result = await oxy.resolveTopicNames([
+        { name: 'react', type: 'topic' },
+        { name: 'vue', type: 'topic' },
+      ]);
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.map((t) => t.name).sort()).toEqual(['react', 'vue']);
+    });
+
+    it('returns [] when the map is empty or missing', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({ topics: {} }));
+      await expect(oxy.resolveTopicNames([])).resolves.toEqual([]);
+    });
+  });
+
+  describe('getTopicBySlug (single, no envelope)', () => {
+    it('returns the raw TopicData unchanged', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse(topic('t1', 'react')));
+      const result = await oxy.getTopicBySlug('react');
+      expect(result._id).toBe('t1');
+      expect(result.name).toBe('react');
+    });
+  });
+});

package/src/models/Topic.ts

@@ -33,3 +33,14 @@ 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/src/session/SessionClient.ts

@@ -6,7 +6,7 @@ import {
   sessionAccountsChangedEventSchema,
   type DeviceSessionState,
 } from '@oxyhq/contracts';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { getSocketIO } from './socketLoader';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 

package/src/session/__tests__/SessionClient.diagnostics.test.ts

@@ -1,6 +1,6 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
 import { SessionClient, type SessionClientHost } from '../SessionClient';
-import { logger } from '../../utils/loggerUtils';
+import { logger } from '../../logger';
 
 const STATE = (rev: number): DeviceSessionState => ({
   deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000,