@oxyhq/core 1.0.0

package/src/mixins/OxyServices.auth.ts

@@ -0,0 +1,358 @@
+/**
+ * Authentication Methods Mixin
+ * 
+ * Supports password-based login (email/username) and public key challenge-response.
+ */
+import type { User } from '../models/interfaces';
+import type { SessionLoginResponse } from '../models/session';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { OxyAuthenticationError } from '../OxyServices.errors';
+
+export interface ChallengeResponse {
+  challenge: string;
+  expiresAt: string;
+}
+
+export interface RegistrationRequest {
+  publicKey: string;
+  username: string;
+  email?: string;
+  signature: string;
+  timestamp: number;
+}
+
+export interface ChallengeVerifyRequest {
+  publicKey: string;
+  challenge: string;
+  signature: string;
+  timestamp: number;
+  deviceName?: string;
+  deviceFingerprint?: string;
+}
+
+export interface PublicKeyCheckResponse {
+  registered: boolean;
+  message: string;
+}
+
+export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Register a new identity with public key authentication
+     * Identity is purely cryptographic - username and profile data are optional
+     * 
+     * @param publicKey - The user's ECDSA public key (hex)
+     * @param signature - Signature of the registration request
+     * @param timestamp - Timestamp when the signature was created
+     */
+    async register(
+      publicKey: string,
+      signature: string,
+      timestamp: number
+    ): Promise<{ message: string; user: User }> {
+      try {
+        const res = await this.makeRequest<{ message: string; user: User }>('POST', '/api/auth/register', {
+          publicKey,
+          signature,
+          timestamp,
+        }, { cache: false });
+
+        if (!res || (typeof res === 'object' && Object.keys(res).length === 0)) {
+          throw new OxyAuthenticationError('Registration failed', 'REGISTER_FAILED', 400);
+        }
+
+        return res;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Request an authentication challenge
+     * The client must sign this challenge with their private key
+     * 
+     * @param publicKey - The user's public key
+     */
+    async requestChallenge(publicKey: string): Promise<ChallengeResponse> {
+      try {
+        return await this.makeRequest<ChallengeResponse>('POST', '/api/auth/challenge', {
+          publicKey,
+        }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Verify a signed challenge and create a session
+     * 
+     * @param publicKey - The user's public key
+     * @param challenge - The challenge string from requestChallenge
+     * @param signature - Signature of the auth message
+     * @param timestamp - Timestamp when the signature was created
+     * @param deviceName - Optional device name
+     * @param deviceFingerprint - Optional device fingerprint
+     */
+    async verifyChallenge(
+      publicKey: string,
+      challenge: string,
+      signature: string,
+      timestamp: number,
+      deviceName?: string,
+      deviceFingerprint?: string
+    ): Promise<SessionLoginResponse> {
+      try {
+        return await this.makeRequest<SessionLoginResponse>('POST', '/api/auth/verify', {
+          publicKey,
+          challenge,
+          signature,
+          timestamp,
+          deviceName,
+          deviceFingerprint,
+        }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Check if a public key is already registered
+     */
+    async checkPublicKeyRegistered(publicKey: string): Promise<PublicKeyCheckResponse> {
+      try {
+        return await this.makeRequest<PublicKeyCheckResponse>(
+          'GET',
+          `/api/auth/check-publickey/${encodeURIComponent(publicKey)}`,
+          undefined,
+          { cache: false }
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get user by public key
+     */
+    async getUserByPublicKey(publicKey: string): Promise<User> {
+      try {
+        return await this.makeRequest<User>(
+          'GET',
+          `/api/auth/user/${encodeURIComponent(publicKey)}`,
+          undefined,
+          { cache: true, cacheTTL: 2 * 60 * 1000 }
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get user by session ID
+     */
+    async getUserBySession(sessionId: string): Promise<User> {
+      try {
+        return await this.makeRequest<User>('GET', `/api/session/user/${sessionId}`, undefined, {
+          cache: true,
+          cacheTTL: 2 * 60 * 1000,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Batch get multiple user profiles by session IDs
+     */
+    async getUsersBySessions(sessionIds: string[]): Promise<Array<{ sessionId: string; user: User | null }>> {
+      try {
+        if (!Array.isArray(sessionIds) || sessionIds.length === 0) {
+          return [];
+        }
+        
+        const uniqueSessionIds = Array.from(new Set(sessionIds)).sort();
+        
+        return await this.makeRequest<Array<{ sessionId: string; user: User | null }>>(
+          'POST',
+          '/api/session/users/batch',
+          { sessionIds: uniqueSessionIds },
+          {
+            cache: true,
+            cacheTTL: 2 * 60 * 1000,
+            deduplicate: true,
+          }
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get access token by session ID
+     */
+    async getTokenBySession(sessionId: string): Promise<{ accessToken: string; expiresAt: string }> {
+      try {
+        const res = await this.makeRequest<{ accessToken: string; expiresAt: string }>(
+          'GET',
+          `/api/session/token/${sessionId}`,
+          undefined,
+          { cache: false, retry: false }
+        );
+        
+        this.setTokens(res.accessToken);
+        
+        return res;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get sessions by session ID
+     */
+    async getSessionsBySessionId(sessionId: string): Promise<any[]> {
+      try {
+        return await this.makeRequest('GET', `/api/session/sessions/${sessionId}`, undefined, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Logout from a specific session
+     */
+    async logoutSession(sessionId: string, targetSessionId?: string): Promise<void> {
+      try {
+        const url = targetSessionId 
+          ? `/api/session/logout/${sessionId}/${targetSessionId}`
+          : `/api/session/logout/${sessionId}`;
+        
+        await this.makeRequest('POST', url, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Logout from all sessions
+     */
+    async logoutAllSessions(sessionId: string): Promise<void> {
+      try {
+        await this.makeRequest('POST', `/api/session/logout-all/${sessionId}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Validate session
+     */
+    async validateSession(
+      sessionId: string, 
+      options: {
+        deviceFingerprint?: string;
+        useHeaderValidation?: boolean;
+      } = {}
+    ): Promise<{ 
+      valid: boolean; 
+      expiresAt: string; 
+      lastActivity: string; 
+      user: User;
+      sessionId?: string;
+      source?: string;
+    }> {
+      try {
+        const urlParams: any = {};
+        if (options.deviceFingerprint) urlParams.deviceFingerprint = options.deviceFingerprint;
+        if (options.useHeaderValidation) urlParams.useHeaderValidation = 'true';
+        return await this.makeRequest('GET', `/api/session/validate/${sessionId}`, urlParams, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Check username availability
+     */
+    async checkUsernameAvailability(username: string): Promise<{ available: boolean; message: string }> {
+      try {
+        return await this.makeRequest('GET', `/api/auth/check-username/${username}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Check email availability
+     */
+    async checkEmailAvailability(email: string): Promise<{ available: boolean; message: string }> {
+      try {
+        return await this.makeRequest('GET', `/api/auth/check-email/${email}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Register a new user with email/username and password
+     */
+    async signUp(
+      username: string,
+      email: string,
+      password: string,
+      deviceName?: string,
+      deviceFingerprint?: any
+    ): Promise<SessionLoginResponse> {
+      try {
+        return await this.makeRequest<SessionLoginResponse>('POST', '/api/auth/signup', {
+          username,
+          email,
+          password,
+          deviceName,
+          deviceFingerprint,
+        }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Sign in with email or username and password
+     */
+    async signIn(
+      identifier: string,
+      password: string,
+      deviceName?: string,
+      deviceFingerprint?: any
+    ): Promise<SessionLoginResponse> {
+      try {
+        return await this.makeRequest<SessionLoginResponse>('POST', '/api/auth/login', {
+          identifier,
+          password,
+          deviceName,
+          deviceFingerprint,
+        }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Convenience helper for email sign-in
+     */
+    async signInWithEmail(
+      email: string,
+      password: string,
+      deviceName?: string,
+      deviceFingerprint?: any
+    ): Promise<SessionLoginResponse> {
+      return this.signIn(email, password, deviceName, deviceFingerprint);
+    }
+  };
+}

package/src/mixins/OxyServices.developer.ts

@@ -0,0 +1,114 @@
+/**
+ * Developer API Methods Mixin
+ * 
+ * Provides methods for managing developer applications and API keys
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import { CACHE_TIMES } from './mixinHelpers';
+
+export function OxyServicesDeveloperMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Get developer apps for the current user
+     * @returns Array of developer apps
+     */
+    async getDeveloperApps(): Promise<any[]> {
+      try {
+        const res = await this.makeRequest<{ apps?: any[] }>('GET', '/api/developer/apps', undefined, {
+          cache: true,
+          cacheTTL: CACHE_TIMES.MEDIUM,
+        });
+        return res.apps || [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create a new developer app
+     * @param data - Developer app configuration
+     * @returns Created developer app
+     */
+    async createDeveloperApp(data: {
+      name: string;
+      description?: string;
+      webhookUrl: string;
+      devWebhookUrl?: string;
+      scopes?: string[];
+    }): Promise<any> {
+      try {
+        const res = await this.makeRequest<{ app: any }>('POST', '/api/developer/apps', data, { cache: false });
+        return res.app;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get a specific developer app
+     */
+    async getDeveloperApp(appId: string): Promise<any> {
+      try {
+      const res = await this.makeRequest<{ app: any }>('GET', `/api/developer/apps/${appId}`, undefined, {
+        cache: true,
+        cacheTTL: CACHE_TIMES.LONG,
+      });
+        return res.app;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Update a developer app
+     * @param appId - The developer app ID
+     * @param data - Updated app configuration
+     * @returns Updated developer app
+     */
+    async updateDeveloperApp(appId: string, data: {
+      name?: string;
+      description?: string;
+      webhookUrl?: string;
+      devWebhookUrl?: string;
+      scopes?: string[];
+    }): Promise<any> {
+      try {
+        const res = await this.makeRequest<{ app: any }>('PATCH', `/api/developer/apps/${appId}`, data, { cache: false });
+        return res.app;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Regenerate API secret for a developer app
+     * @param appId - The developer app ID
+     * @returns App with new secret
+     */
+    async regenerateDeveloperAppSecret(appId: string): Promise<any> {
+      try {
+        return await this.makeRequest('POST', `/api/developer/apps/${appId}/regenerate-secret`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Delete a developer app
+     * @param appId - The developer app ID
+     * @returns Deletion result
+     */
+    async deleteDeveloperApp(appId: string): Promise<any> {
+      try {
+        return await this.makeRequest('DELETE', `/api/developer/apps/${appId}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}
+

package/src/mixins/OxyServices.devices.ts

@@ -0,0 +1,119 @@
+/**
+ * Device Methods Mixin
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+
+export function OxyServicesDevicesMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Register a new device
+     * @param deviceData - Device information
+     * @returns Registered device object
+     */
+    async registerDevice(deviceData: any): Promise<any> {
+      try {
+        return await this.makeRequest('POST', '/api/devices', deviceData, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get all devices for the current user
+     * @returns Array of user devices
+     */
+    async getUserDevices(): Promise<any[]> {
+      try {
+        return await this.makeRequest('GET', '/api/devices', undefined, {
+          cache: false, // Don't cache device list - always get fresh data
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Remove a device
+     * @param deviceId - The device ID to remove
+     */
+    async removeDevice(deviceId: string): Promise<void> {
+      try {
+        await this.makeRequest('DELETE', `/api/devices/${deviceId}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get device sessions for a given session ID
+     * Note: Not cached by default to ensure fresh data
+     * @param sessionId - The session ID
+     * @returns Array of device sessions
+     */
+    async getDeviceSessions(sessionId: string): Promise<any[]> {
+      try {
+        // Use makeRequest for consistent error handling and optional caching
+        // Cache disabled by default to ensure fresh session data
+        return await this.makeRequest<any[]>('GET', `/api/session/device/sessions/${sessionId}`, undefined, {
+          cache: false, // Don't cache sessions - always get fresh data
+          deduplicate: true, // Deduplicate concurrent requests for same sessionId
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Logout all device sessions
+     * @param sessionId - The session ID
+     * @param deviceId - Optional device ID to target
+     * @param excludeCurrent - Whether to exclude the current session
+     * @returns Logout result
+     */
+    async logoutAllDeviceSessions(sessionId: string, deviceId?: string, excludeCurrent?: boolean): Promise<any> {
+      try {
+        const urlParams: any = {};
+        if (deviceId) urlParams.deviceId = deviceId;
+        if (excludeCurrent) urlParams.excludeCurrent = 'true';
+        return await this.makeRequest('POST', `/api/session/device/logout-all/${sessionId}`, urlParams, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Update device name
+     * @param sessionId - The session ID
+     * @param deviceName - New device name
+     * @returns Updated device object
+     */
+    async updateDeviceName(sessionId: string, deviceName: string): Promise<any> {
+      try {
+        return await this.makeRequest('PUT', `/api/session/device/name/${sessionId}`, { deviceName }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get security information
+     * @returns Security information object
+     */
+    async getSecurityInfo(): Promise<{
+      recoveryEmail: string | null;
+    }> {
+      try {
+        return await this.makeRequest('GET', '/api/devices/security', undefined, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}
+