@oxyhq/core 1.11.0 → 1.11.2

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

@@ -21,9 +21,26 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         resolveProfile(handle: string): Promise<User | null>;
         /**
-         * Get profile recommendations
+         * 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.
          */
-        getProfileRecommendations(): Promise<Array<{
+        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.11.0",
+  "version": "1.11.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/i18n/locales/en-US.json

@@ -444,6 +444,34 @@
         "title": "Why Karma?",
         "text": "Karma unlocks special features and recognition in the Oxy Ecosystem. The more you contribute, the more you earn!"
       }
+    },
+    "achievements": {
+      "unlocked": "Unlocked Achievements",
+      "locked": "Locked Achievements",
+      "firstStep": "First Step",
+      "firstStepDesc": "Earned your first karma point",
+      "novice": "Novice",
+      "noviceDesc": "Reached 10 karma points",
+      "contributor": "Contributor",
+      "contributorDesc": "Reached 50 karma points",
+      "risingStar": "Rising Star",
+      "risingStarDesc": "Reached 100 karma points",
+      "earlyAdopter": "Early Adopter",
+      "earlyAdopterDesc": "Been part of the community from the start",
+      "communityHero": "Community Hero",
+      "communityHeroDesc": "Reached 500 karma points",
+      "legend": "Legend",
+      "legendDesc": "Reached 1000 karma points",
+      "phoenix": "Phoenix",
+      "phoenixDesc": "Reached 2500 karma points",
+      "unstoppable": "Unstoppable",
+      "unstoppableDesc": "Reached 5000 karma points",
+      "bugHunter": "Bug Hunter",
+      "bugHunterDesc": "Reported helpful bugs",
+      "helper": "Helper",
+      "helperDesc": "Helped 10 users",
+      "streakMaster": "Streak Master",
+      "streakMasterDesc": "7 day activity streak"
     }
   },
   "premium": {
@@ -533,6 +561,7 @@
   },
   "editProfile": {
     "title": "Edit Profile",
+    "subtitle": "Manage your profile and preferences",
     "sections": {
       "profilePicture": "Profile Picture",
       "basicInfo": "Basic Information",
@@ -543,29 +572,69 @@
     "items": {
       "displayName": {
         "title": "Display Name",
-        "add": "Add your display name"
+        "subtitle": "This is how your name will appear to others",
+        "add": "Add your display name",
+        "firstName": "First Name",
+        "firstNamePlaceholder": "Enter first name",
+        "lastName": "Last Name",
+        "lastNamePlaceholder": "Enter last name (optional)"
       },
       "username": {
         "title": "Username",
-        "choose": "Choose a username"
+        "subtitle": "Your unique identifier on the platform",
+        "label": "Username",
+        "placeholder": "Choose a username",
+        "choose": "Choose a username",
+        "required": "Username is required",
+        "tooShort": "Username must be at least 3 characters"
       },
       "email": {
         "title": "Email",
-        "add": "Add your email address"
+        "subtitle": "Your primary email address",
+        "label": "Email Address",
+        "placeholder": "Enter your email address",
+        "add": "Add your email address",
+        "invalid": "Please enter a valid email address"
       },
       "bio": {
         "title": "Bio",
+        "subtitle": "Tell people a bit about yourself",
+        "label": "Bio",
         "placeholder": "Tell people about yourself"
       },
+      "phone": {
+        "title": "Phone Number",
+        "subtitle": "Your contact phone number",
+        "label": "Phone Number",
+        "placeholder": "Enter your phone number"
+      },
+      "address": {
+        "title": "Address",
+        "subtitle": "Your physical address",
+        "label": "Address",
+        "placeholder": "Enter your address"
+      },
+      "birthday": {
+        "title": "Birthday",
+        "subtitle": "Your date of birth",
+        "label": "Birthday",
+        "placeholder": "YYYY-MM-DD"
+      },
       "locations": {
         "title": "Locations",
+        "subtitle": "Places you've been or live",
         "add": "Add your locations",
+        "placeholder": "Enter location name",
+        "yourLocations": "Your Locations",
         "count": "{{count}} location added",
         "count_plural": "{{count}} locations added"
       },
       "links": {
         "title": "Links",
+        "subtitle": "Share your website, social profiles, etc.",
         "add": "Add your links",
+        "placeholder": "Enter URL",
+        "yourLinks": "Your Links",
         "count": "{{count}} link added",
         "count_plural": "{{count}} links added"
       },
@@ -798,8 +867,19 @@
       "account": "ACCOUNT PRIVACY",
       "interactions": "INTERACTIONS",
       "activity": "ACTIVITY & DATA",
-      "content": "CONTENT & SAFETY"
-    },
+      "content": "CONTENT & SAFETY",
+      "blockedUsers": "BLOCKED USERS",
+      "restrictedUsers": "RESTRICTED USERS"
+    },
+    "noBlockedUsers": "No blocked users",
+    "noRestrictedUsers": "No restricted users",
+    "unblock": "Unblock",
+    "unblockError": "Failed to unblock user",
+    "unrestrict": "Unrestrict",
+    "unrestrictError": "Failed to unrestrict user",
+    "restrictedDescription": "Limited interactions",
+    "userUnblocked": "User unblocked",
+    "userUnrestricted": "User unrestricted",
     "isPrivateAccount": "Private Account",
     "isPrivateAccountDesc": "Only approved followers can see your posts",
     "profileVisibility": "Profile Visibility",
@@ -920,6 +1000,23 @@
       "subtitle": "How we use cookies and similar technologies"
     }
   },
+  "faq": {
+    "title": "FAQ",
+    "searchPlaceholder": "Search FAQs...",
+    "allCategories": "All",
+    "loading": "Loading FAQs...",
+    "noResults": "No FAQs match your search",
+    "empty": "No FAQs available",
+    "loadError": "Failed to load FAQs"
+  },
+  "userList": {
+    "followers": "Followers",
+    "following": "Following",
+    "noFollowers": "No followers yet",
+    "noFollowersDesc": "When people follow this user, they will appear here.",
+    "noFollowing": "Not following anyone",
+    "noFollowingDesc": "When this user follows people, they will appear here."
+  },
   "common": {
     "errors": {
       "signOutFailed": "There was a problem signing you out. Please try again."
@@ -939,9 +1036,15 @@
       "getStarted": "Get Started",
       "createAccount": "Create Account",
       "signIn": "Sign In",
+      "signOut": "Sign Out",
       "verify": "Verify",
       "resetPassword": "Reset Password"
     },
+    "cancel": "Cancel",
+    "retry": "Retry",
+    "save": "Save",
+    "saved": "Saved successfully",
+    "saving": "Saving...",
     "links": {
       "recoverAccount": "Recover your account",
       "signUp": "Sign Up"

package/src/i18n/locales/es-ES.json

@@ -147,6 +147,7 @@
   },
   "editProfile": {
     "title": "Editar perfil",
+    "subtitle": "Gestiona tu perfil y preferencias",
     "sections": {
       "profilePicture": "Foto de perfil",
       "basicInfo": "Información básica",
@@ -157,29 +158,69 @@
     "items": {
       "displayName": {
         "title": "Nombre para mostrar",
-        "add": "Añade tu nombre para mostrar"
+        "subtitle": "Así aparecerá tu nombre para los demás",
+        "add": "Añade tu nombre para mostrar",
+        "firstName": "Nombre",
+        "firstNamePlaceholder": "Introduce tu nombre",
+        "lastName": "Apellido",
+        "lastNamePlaceholder": "Introduce tu apellido (opcional)"
       },
       "username": {
         "title": "Usuario",
-        "choose": "Elige un usuario"
+        "subtitle": "Tu identificador único en la plataforma",
+        "label": "Usuario",
+        "placeholder": "Elige un usuario",
+        "choose": "Elige un usuario",
+        "required": "El usuario es obligatorio",
+        "tooShort": "El usuario debe tener al menos 3 caracteres"
       },
       "email": {
         "title": "Correo electrónico",
-        "add": "Añade tu correo electrónico"
+        "subtitle": "Tu dirección de correo principal",
+        "label": "Correo electrónico",
+        "placeholder": "Introduce tu correo electrónico",
+        "add": "Añade tu correo electrónico",
+        "invalid": "Introduce una dirección de correo válida"
       },
       "bio": {
         "title": "Biografía",
+        "subtitle": "Cuenta algo sobre ti",
+        "label": "Biografía",
         "placeholder": "Cuenta algo sobre ti"
       },
+      "phone": {
+        "title": "Número de teléfono",
+        "subtitle": "Tu número de teléfono de contacto",
+        "label": "Número de teléfono",
+        "placeholder": "Introduce tu número de teléfono"
+      },
+      "address": {
+        "title": "Dirección",
+        "subtitle": "Tu dirección física",
+        "label": "Dirección",
+        "placeholder": "Introduce tu dirección"
+      },
+      "birthday": {
+        "title": "Fecha de nacimiento",
+        "subtitle": "Tu fecha de nacimiento",
+        "label": "Fecha de nacimiento",
+        "placeholder": "AAAA-MM-DD"
+      },
       "locations": {
         "title": "Ubicaciones",
+        "subtitle": "Lugares donde has estado o vives",
         "add": "Añade tus ubicaciones",
+        "placeholder": "Introduce el nombre del lugar",
+        "yourLocations": "Tus ubicaciones",
         "count": "{{count}} ubicación añadida",
         "count_plural": "{{count}} ubicaciones añadidas"
       },
       "links": {
         "title": "Enlaces",
+        "subtitle": "Comparte tu web, perfiles sociales, etc.",
         "add": "Añade tus enlaces",
+        "placeholder": "Introduce la URL",
+        "yourLinks": "Tus enlaces",
         "count": "{{count}} enlace añadido",
         "count_plural": "{{count}} enlaces añadidos"
       },
@@ -219,9 +260,15 @@
       "getStarted": "Comenzar",
       "createAccount": "Crear cuenta",
       "signIn": "Entrar",
+      "signOut": "Cerrar sesión",
       "verify": "Verificar",
       "resetPassword": "Restablecer contraseña"
     },
+    "cancel": "Cancelar",
+    "retry": "Reintentar",
+    "save": "Guardar",
+    "saved": "Guardado correctamente",
+    "saving": "Guardando...",
     "links": {
       "recoverAccount": "Recuperar tu cuenta",
       "signUp": "Registrarse"
@@ -623,6 +670,34 @@
         "title": "¿Por qué el karma?",
         "text": "El karma desbloquea funciones especiales y reconocimiento en el ecosistema de Oxy. ¡Cuanto más contribuyas, más ganarás!"
       }
+    },
+    "achievements": {
+      "unlocked": "Logros desbloqueados",
+      "locked": "Logros bloqueados",
+      "firstStep": "Primer paso",
+      "firstStepDesc": "Ganaste tu primer punto de karma",
+      "novice": "Novato",
+      "noviceDesc": "Alcanzaste 10 puntos de karma",
+      "contributor": "Contribuidor",
+      "contributorDesc": "Alcanzaste 50 puntos de karma",
+      "risingStar": "Estrella en ascenso",
+      "risingStarDesc": "Alcanzaste 100 puntos de karma",
+      "earlyAdopter": "Pionero",
+      "earlyAdopterDesc": "Parte de la comunidad desde el inicio",
+      "communityHero": "Héroe de la comunidad",
+      "communityHeroDesc": "Alcanzaste 500 puntos de karma",
+      "legend": "Leyenda",
+      "legendDesc": "Alcanzaste 1000 puntos de karma",
+      "phoenix": "Fénix",
+      "phoenixDesc": "Alcanzaste 2500 puntos de karma",
+      "unstoppable": "Imparable",
+      "unstoppableDesc": "Alcanzaste 5000 puntos de karma",
+      "bugHunter": "Cazador de errores",
+      "bugHunterDesc": "Reportaste errores útiles",
+      "helper": "Ayudante",
+      "helperDesc": "Ayudaste a 10 usuarios",
+      "streakMaster": "Maestro de rachas",
+      "streakMasterDesc": "Racha de actividad de 7 días"
     }
   },
   "premium": {
@@ -819,8 +894,19 @@
       "account": "PRIVACIDAD DE LA CUENTA",
       "interactions": "INTERACCIONES",
       "activity": "ACTIVIDAD Y DATOS",
-      "content": "CONTENIDO Y SEGURIDAD"
-    },
+      "content": "CONTENIDO Y SEGURIDAD",
+      "blockedUsers": "USUARIOS BLOQUEADOS",
+      "restrictedUsers": "USUARIOS RESTRINGIDOS"
+    },
+    "noBlockedUsers": "No hay usuarios bloqueados",
+    "noRestrictedUsers": "No hay usuarios restringidos",
+    "unblock": "Desbloquear",
+    "unblockError": "Error al desbloquear al usuario",
+    "unrestrict": "Quitar restricción",
+    "unrestrictError": "Error al quitar la restricción del usuario",
+    "restrictedDescription": "Interacciones limitadas",
+    "userUnblocked": "Usuario desbloqueado",
+    "userUnrestricted": "Restricción del usuario eliminada",
     "isPrivateAccount": "Cuenta privada",
     "isPrivateAccountDesc": "Solo los seguidores aprobados pueden ver tus publicaciones",
     "profileVisibility": "Visibilidad del perfil",
@@ -940,5 +1026,22 @@
       "title": "Política de cookies",
       "subtitle": "Cómo usamos cookies y tecnologías similares"
     }
+  },
+  "faq": {
+    "title": "Preguntas frecuentes",
+    "searchPlaceholder": "Buscar en las FAQ...",
+    "allCategories": "Todas",
+    "loading": "Cargando preguntas frecuentes...",
+    "noResults": "No se encontraron preguntas que coincidan con tu búsqueda",
+    "empty": "No hay preguntas frecuentes disponibles",
+    "loadError": "Error al cargar las preguntas frecuentes"
+  },
+  "userList": {
+    "followers": "Seguidores",
+    "following": "Siguiendo",
+    "noFollowers": "Aún no hay seguidores",
+    "noFollowersDesc": "Cuando alguien siga a este usuario, aparecerá aquí.",
+    "noFollowing": "No sigue a nadie",
+    "noFollowingDesc": "Cuando este usuario siga a alguien, aparecerá aquí."
   }
 }

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

@@ -105,9 +105,29 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get profile recommendations
+     * 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 getProfileRecommendations(): Promise<Array<{
+    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 };
@@ -121,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;
+}