@oxyhq/core 1.10.0 → 1.11.1

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

@@ -0,0 +1,106 @@
+/**
+ * Topics Methods Mixin
+ *
+ * Provides methods for topic discovery and management
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { TopicData, TopicTranslation } from '../models/Topic';
+export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Get top-level topic categories
+         * @param locale - Optional locale for translated results
+         * @returns List of category topics
+         */
+        getTopicCategories(locale?: string): Promise<TopicData[]>;
+        /**
+         * Search topics by query string
+         * @param query - Search query
+         * @param limit - Optional result limit
+         * @returns Matching topics
+         */
+        searchTopics(query: string, limit?: number): Promise<TopicData[]>;
+        /**
+         * List topics with optional filters
+         * @param options - Filter and pagination options
+         * @returns List of topics
+         */
+        listTopics(options?: {
+            type?: string;
+            q?: string;
+            limit?: number;
+            offset?: number;
+            locale?: string;
+        }): Promise<TopicData[]>;
+        /**
+         * Get a single topic by slug
+         * @param slug - Topic slug
+         * @returns Topic data
+         */
+        getTopicBySlug(slug: string): Promise<TopicData>;
+        /**
+         * Resolve an array of topic names to existing or newly created topics
+         * @param names - Array of { name, type } objects to resolve
+         * @returns Resolved topic data
+         */
+        resolveTopicNames(names: Array<{
+            name: string;
+            type: string;
+        }>): Promise<TopicData[]>;
+        /**
+         * Update metadata for a topic
+         * @param slug - Topic slug
+         * @param data - Metadata fields to update
+         * @returns Updated topic data
+         */
+        updateTopicMetadata(slug: string, data: {
+            description?: string;
+            translations?: Record<string, TopicTranslation>;
+        }): Promise<TopicData>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string, refreshToken?: string): void;
+        clearTokens(): void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

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

@@ -15,9 +15,32 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         searchProfiles(query: string, pagination?: PaginationParams): Promise<SearchProfilesResponse>;
         /**
-         * Get profile recommendations
+         * Resolve a fediverse handle to an Oxy user profile.
+         * Performs WebFinger discovery and returns the user, or null if not found.
+         * @param handle - Fediverse handle (e.g. "@user@mastodon.social" or "user@domain")
          */
-        getProfileRecommendations(): Promise<Array<{
+        resolveProfile(handle: string): Promise<User | null>;
+        /**
+         * Resolve (find or create) a non-local user. All user creation for
+         * external accounts (federated, agent, automated) goes through this
+         * method — calling services never write user data directly.
+         */
+        resolveExternalUser(data: {
+            type: "federated" | "agent" | "automated";
+            username: string;
+            actorUri?: string;
+            domain?: string;
+            displayName?: string;
+            avatar?: string;
+            bio?: string;
+            ownerId?: string;
+        }): Promise<User>;
+        /**
+         * Get profile recommendations, optionally filtering out specific user types.
+         */
+        getProfileRecommendations(options?: {
+            excludeTypes?: Array<"federated" | "agent" | "automated">;
+        }): Promise<Array<{
             id: string;
             username: string;
             name?: {

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

@@ -0,0 +1,32 @@
+export declare enum TopicType {
+    CATEGORY = "category",
+    TOPIC = "topic",
+    ENTITY = "entity"
+}
+export declare enum TopicSource {
+    SEED = "seed",
+    AI = "ai",
+    MANUAL = "manual",
+    SYSTEM = "system"
+}
+export interface TopicTranslation {
+    displayName: string;
+    description?: string;
+}
+export interface TopicData {
+    _id: string;
+    name: string;
+    slug: string;
+    displayName: string;
+    description: string;
+    type: TopicType;
+    source: TopicSource;
+    aliases: string[];
+    parentTopicId?: string;
+    icon?: string;
+    image?: string;
+    isActive: boolean;
+    translations?: Record<string, TopicTranslation>;
+    createdAt: string;
+    updatedAt: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -40,6 +40,8 @@ export type { KeyPair, SignedMessage, AuthChallenge, RecoveryPhraseResult } from
 // --- Models & Types ---
 export * from './models/interfaces';
 export * from './models/session';
+export type { TopicData, TopicTranslation } from './models/Topic';
+export { TopicType, TopicSource } from './models/Topic';
 
 // --- Device Management ---
 export { DeviceManager } from './utils/deviceManager';

package/src/mixins/OxyServices.topics.ts

@@ -0,0 +1,135 @@
+/**
+ * Topics Methods Mixin
+ *
+ * Provides methods for topic discovery and management
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { TopicData, TopicTranslation } from '../models/Topic';
+import { CACHE_TIMES } from './mixinHelpers';
+
+export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Get top-level topic categories
+     * @param locale - Optional locale for translated results
+     * @returns List of category topics
+     */
+    async getTopicCategories(locale?: string): Promise<TopicData[]> {
+      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,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Search topics by query string
+     * @param query - Search query
+     * @param limit - Optional result limit
+     * @returns Matching topics
+     */
+    async searchTopics(query: string, limit?: number): Promise<TopicData[]> {
+      try {
+        const params: Record<string, string | number> = { q: query };
+        if (limit) params.limit = limit;
+        return await this.makeRequest('GET', '/topics/search', params, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * List topics with optional filters
+     * @param options - Filter and pagination options
+     * @returns List of topics
+     */
+    async listTopics(options?: {
+      type?: string;
+      q?: string;
+      limit?: number;
+      offset?: number;
+      locale?: string;
+    }): Promise<TopicData[]> {
+      try {
+        const params: Record<string, string | number> = {};
+        if (options?.type) params.type = options.type;
+        if (options?.q) params.q = options.q;
+        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,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get a single topic by slug
+     * @param slug - Topic slug
+     * @returns Topic data
+     */
+    async getTopicBySlug(slug: string): Promise<TopicData> {
+      try {
+        return await this.makeRequest('GET', `/topics/${slug}`, undefined, {
+          cache: true,
+          cacheTTL: CACHE_TIMES.LONG,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Resolve an array of topic names to existing or newly created topics
+     * @param names - Array of { name, type } objects to resolve
+     * @returns Resolved topic data
+     */
+    async resolveTopicNames(
+      names: Array<{ name: string; type: string }>
+    ): Promise<TopicData[]> {
+      try {
+        return await this.makeRequest('POST', '/topics/resolve', { names }, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Update metadata for a topic
+     * @param slug - Topic slug
+     * @param data - Metadata fields to update
+     * @returns Updated topic data
+     */
+    async updateTopicMetadata(
+      slug: string,
+      data: {
+        description?: string;
+        translations?: Record<string, TopicTranslation>;
+      }
+    ): Promise<TopicData> {
+      try {
+        return await this.makeRequest('PATCH', `/topics/${slug}`, data, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.user.ts

@@ -86,9 +86,48 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get profile recommendations
+     * Resolve a fediverse handle to an Oxy user profile.
+     * Performs WebFinger discovery and returns the user, or null if not found.
+     * @param handle - Fediverse handle (e.g. "@user@mastodon.social" or "user@domain")
      */
-    async getProfileRecommendations(): Promise<Array<{
+    async resolveProfile(handle: string): Promise<User | null> {
+      try {
+        const result = await this.makeRequest<{ data: User | null }>('GET', '/profiles/resolve', {
+          handle,
+        }, {
+          cache: true,
+          cacheTTL: 24 * 60 * 60 * 1000, // 24h cache — matches server-side staleness window
+        });
+        return result.data ?? null;
+      } catch {
+        return null;
+      }
+    }
+
+    /**
+     * Resolve (find or create) a non-local user. All user creation for
+     * external accounts (federated, agent, automated) goes through this
+     * method — calling services never write user data directly.
+     */
+    async resolveExternalUser(data: {
+      type: 'federated' | 'agent' | 'automated';
+      username: string;
+      actorUri?: string;
+      domain?: string;
+      displayName?: string;
+      avatar?: string;
+      bio?: string;
+      ownerId?: string;
+    }): Promise<User> {
+      return this.makeRequest<User>('PUT', '/users/resolve', data);
+    }
+
+    /**
+     * Get profile recommendations, optionally filtering out specific user types.
+     */
+    async getProfileRecommendations(options?: {
+      excludeTypes?: Array<'federated' | 'agent' | 'automated'>;
+    }): Promise<Array<{
       id: string;
       username: string;
       name?: { first?: string; last?: string; full?: string };
@@ -102,8 +141,11 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       _count?: { followers: number; following: number };
       [key: string]: unknown;
     }>> {
+      const params = options?.excludeTypes?.length
+        ? { excludeTypes: options.excludeTypes.join(',') }
+        : undefined;
       return this.withAuthRetry(async () => {
-        return await this.makeRequest('GET', '/profiles/recommendations', undefined, { cache: true });
+        return await this.makeRequest('GET', '/profiles/recommendations', params, { cache: true });
       }, 'getProfileRecommendations');
     }
 

package/src/mixins/index.ts

@@ -23,6 +23,7 @@ import { OxyServicesDevicesMixin } from './OxyServices.devices';
 import { OxyServicesSecurityMixin } from './OxyServices.security';
 import { OxyServicesUtilityMixin } from './OxyServices.utility';
 import { OxyServicesFeaturesMixin } from './OxyServices.features';
+import { OxyServicesTopicsMixin } from './OxyServices.topics';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type MixinFunction = (Base: any) => any;
@@ -66,6 +67,7 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesDevicesMixin,
     OxyServicesSecurityMixin,
     OxyServicesFeaturesMixin,
+    OxyServicesTopicsMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,

package/src/models/Topic.ts

@@ -0,0 +1,35 @@
+export enum TopicType {
+  CATEGORY = 'category',
+  TOPIC = 'topic',
+  ENTITY = 'entity',
+}
+
+export enum TopicSource {
+  SEED = 'seed',
+  AI = 'ai',
+  MANUAL = 'manual',
+  SYSTEM = 'system',
+}
+
+export interface TopicTranslation {
+  displayName: string;
+  description?: string;
+}
+
+export interface TopicData {
+  _id: string;
+  name: string;
+  slug: string;
+  displayName: string;
+  description: string;
+  type: TopicType;
+  source: TopicSource;
+  aliases: string[];
+  parentTopicId?: string;
+  icon?: string;
+  image?: string;
+  isActive: boolean;
+  translations?: Record<string, TopicTranslation>;
+  createdAt: string;
+  updatedAt: string;
+}