wowsql-sdk 1.3.0 → 3.0.1

data/lib/wowsql/auth.rb

@@ -3,23 +3,112 @@ require 'json'
 require_relative 'exceptions'
 
 module WOWSQL
+  # Represents an authenticated user.
+  AuthUser = Struct.new(
+    :id, :email, :full_name, :avatar_url, :email_verified,
+    :user_metadata, :app_metadata, :created_at,
+    keyword_init: true
+  ) do
+    def initialize(id: '', email: '', full_name: nil, avatar_url: nil,
+                   email_verified: false, user_metadata: nil,
+                   app_metadata: nil, created_at: nil)
+      super
+    end
+  end
+
+  # Session tokens returned by the auth service.
+  AuthSession = Struct.new(
+    :access_token, :refresh_token, :token_type, :expires_in,
+    keyword_init: true
+  ) do
+    def initialize(access_token: '', refresh_token: '', token_type: 'bearer', expires_in: 0)
+      super
+    end
+  end
+
+  # Response for signup/login requests.
+  AuthResponse = Struct.new(:session, :user, keyword_init: true) do
+    def initialize(session:, user: nil)
+      super
+    end
+  end
+
+  # Interface for persisting tokens.
+  module TokenStorage
+    def get_access_token
+      raise NotImplementedError
+    end
+
+    def set_access_token(_token)
+      raise NotImplementedError
+    end
+
+    def get_refresh_token
+      raise NotImplementedError
+    end
+
+    def set_refresh_token(_token)
+      raise NotImplementedError
+    end
+  end
+
+  # Default in-memory token storage.
+  class MemoryTokenStorage
+    include TokenStorage
+
+    def initialize
+      @access = nil
+      @refresh = nil
+    end
+
+    def get_access_token
+      @access
+    end
+
+    def set_access_token(token)
+      @access = token
+    end
+
+    def get_refresh_token
+      @refresh
+    end
+
+    def set_refresh_token(token)
+      @refresh = token
+    end
+  end
+
   # Project-level authentication client.
-  # 
+  #
   # UNIFIED AUTHENTICATION: Uses the same API keys (anon/service) as database operations.
   # One project = one set of keys for ALL operations (auth + database).
-  # 
+  #
   # Key Types:
-  #     - Anonymous Key (wowsql_anon_...): For client-side auth operations (signup, login, OAuth)
-  #     - Service Role Key (wowsql_service_...): For server-side auth operations (admin, full access)
+  #   - Anonymous Key (wowsql_anon_...): For client-side auth operations
+  #   - Service Role Key (wowsql_service_...): For server-side auth operations
   class ProjectAuthClient
-    def initialize(project_url, api_key, timeout = 30)
+    attr_reader :base_url
+
+    # @param project_url [String] Project subdomain or full URL
+    # @param api_key [String] API key for authentication
+    # @param base_domain [String] Base domain (default: "wowsql.com")
+    # @param secure [Boolean] Use HTTPS (default: true)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param verify_ssl [Boolean] Verify SSL certificates (default: true)
+    # @param token_storage [TokenStorage, nil] Optional token storage
+    def initialize(project_url, api_key, base_domain: 'wowsql.com', secure: true,
+                   timeout: 30, verify_ssl: true, token_storage: nil)
       @api_key = api_key
       @timeout = timeout
-      @base_url = build_auth_base_url(project_url)
-      @access_token = nil
-      @refresh_token = nil
+      @base_url = build_auth_base_url(project_url, base_domain, secure)
+
+      @storage = token_storage || MemoryTokenStorage.new
+      @access_token = @storage.get_access_token
+      @refresh_token = @storage.get_refresh_token
+
+      ssl_options = verify_ssl ? {} : { verify: false }
 
-      @conn = Faraday.new(url: @base_url) do |f|
+      @conn = Faraday.new(url: @base_url, ssl: ssl_options) do |f|
         f.request :json
         f.response :json
         f.adapter Faraday.default_adapter
@@ -31,81 +120,79 @@ module WOWSQL
     end
 
     # Sign up a new user.
-    # 
+    #
     # @param email [String] User email
     # @param password [String] User password (minimum 8 characters)
     # @param full_name [String, nil] Optional full name
     # @param user_metadata [Hash, nil] Optional user metadata
-    # @return [Hash] Response with session and user data
+    # @return [AuthResponse]
     def sign_up(email:, password:, full_name: nil, user_metadata: nil)
-      payload = {
-        email: email,
-        password: password
-      }
+      payload = { email: email, password: password }
       payload[:full_name] = full_name if full_name
       payload[:user_metadata] = user_metadata if user_metadata
 
       data = request('POST', '/signup', nil, payload)
       session = persist_session(data)
-
-      {
-        session: session,
-        user: data['user'] ? normalize_user(data['user']) : nil
-      }
+      user = data['user'] ? AuthUser.new(**normalize_user(data['user'])) : nil
+      AuthResponse.new(session: session, user: user)
     end
 
     # Sign in an existing user.
-    # 
+    #
     # @param email [String] User email
     # @param password [String] User password
-    # @return [Hash] Response with session and user data
+    # @return [AuthResponse]
     def sign_in(email:, password:)
-      payload = {
-        email: email,
-        password: password
-      }
-
+      payload = { email: email, password: password }
       data = request('POST', '/login', nil, payload)
       session = persist_session(data)
+      AuthResponse.new(session: session, user: nil)
+    end
 
-      {
-        session: session,
-        user: data['user'] ? normalize_user(data['user']) : nil
-      }
+    # Get current authenticated user.
+    #
+    # @param access_token [String, nil] Override access token
+    # @return [AuthUser]
+    def get_user(access_token: nil)
+      token = access_token || @access_token || @storage.get_access_token
+      raise WOWSQLError.new('Access token is required. Call sign_in first.') unless token
+
+      data = request_with_headers('GET', '/me', nil, nil, 'Authorization' => "Bearer #{token}")
+      AuthUser.new(**normalize_user(data))
     end
 
     # Get OAuth authorization URL.
-    # 
+    #
     # @param provider [String] OAuth provider name (e.g., 'github', 'google')
     # @param redirect_uri [String, nil] Optional frontend redirect URI
-    # @return [Hash] Response with authorization_url and other OAuth details
+    # @return [Hash]
     def get_oauth_authorization_url(provider:, redirect_uri: nil)
-      raise WOWSQLException.new('provider is required and cannot be empty') if provider.nil? || provider.strip.empty?
+      raise WOWSQLError.new('provider is required and cannot be empty') if provider.nil? || provider.strip.empty?
 
+      provider = provider.strip
       params = {}
       params['frontend_redirect_uri'] = redirect_uri.strip if redirect_uri
 
       begin
         data = request('GET', "/oauth/#{provider}", params, nil)
-
         {
-          authorization_url: data['authorization_url'] || '',
-          provider: data['provider'] || provider,
-          backend_callback_url: data['backend_callback_url'] || '',
-          frontend_redirect_uri: data['frontend_redirect_uri'] || redirect_uri || ''
+          'authorization_url' => data['authorization_url'] || '',
+          'provider' => data['provider'] || provider,
+          'backend_callback_url' => data['backend_callback_url'] || '',
+          'frontend_redirect_uri' => data['frontend_redirect_uri'] || redirect_uri || ''
         }
-      rescue WOWSQLException => e
+      rescue WOWSQLError => e
         if e.status_code == 502
-          raise WOWSQLException.new(
-            "Bad Gateway (502): The backend server may be down or unreachable. Check if the backend is running and accessible at #{@base_url}",
-            502,
-            e.response
+          raise WOWSQLError.new(
+            "Bad Gateway (502): The backend server may be down or unreachable. " \
+            "Check if the backend is running and accessible at #{@base_url}",
+            502, e.response
           )
         elsif e.status_code == 400
-          raise WOWSQLException.new(
-            "Bad Request (400): #{e.message}. Ensure OAuth provider '#{provider}' is configured and enabled for this project.",
-            400,
-            e.response
+          raise WOWSQLError.new(
+            "Bad Request (400): #{e.message}. " \
+            "Ensure OAuth provider '#{provider}' is configured and enabled for this project.",
+            400, e.response
           )
         end
         raise
@@ -113,229 +200,274 @@ module WOWSQL
     end
 
     # Exchange OAuth callback code for access tokens.
-    # 
+    #
     # @param provider [String] OAuth provider name
     # @param code [String] Authorization code from OAuth provider callback
     # @param redirect_uri [String, nil] Optional redirect URI
-    # @return [Hash] Response with session and user data
+    # @return [AuthResponse]
     def exchange_oauth_callback(provider:, code:, redirect_uri: nil)
       payload = { code: code }
       payload[:redirect_uri] = redirect_uri if redirect_uri
 
       data = request('POST', "/oauth/#{provider}/callback", nil, payload)
       session = persist_session(data)
-
-      {
-        session: session,
-        user: data['user'] ? normalize_user(data['user']) : nil
-      }
+      user = data['user'] ? AuthUser.new(**normalize_user(data['user'])) : nil
+      AuthResponse.new(session: session, user: user)
     end
 
     # Request password reset.
-    # 
+    #
     # @param email [String] User's email address
-    # @return [Hash] Response with success status and message
+    # @return [Hash]
     def forgot_password(email:)
       payload = { email: email }
       data = request('POST', '/forgot-password', nil, payload)
-
       {
-        success: data['success'] != false,
-        message: data['message'] || 'If that email exists, a password reset link has been sent'
+        'success' => data['success'] != false,
+        'message' => data['message'] || 'If that email exists, a password reset link has been sent'
       }
     end
 
     # Reset password with token.
-    # 
+    #
     # @param token [String] Password reset token from email
     # @param new_password [String] New password (minimum 8 characters)
-    # @return [Hash] Response with success status and message
+    # @return [Hash]
     def reset_password(token:, new_password:)
-      payload = {
-        token: token,
-        new_password: new_password
-      }
-
+      payload = { token: token, new_password: new_password }
       data = request('POST', '/reset-password', nil, payload)
-
       {
-        success: data['success'] != false,
-        message: data['message'] || 'Password reset successfully! You can now login with your new password'
+        'success' => data['success'] != false,
+        'message' => data['message'] || 'Password reset successfully! You can now login with your new password'
       }
     end
 
     # Send OTP code to user's email.
-    # 
+    #
     # @param email [String] User's email address
-    # @param purpose [String] Purpose of OTP - 'login', 'signup', or 'password_reset' (default: 'login')
-    # @return [Hash] Response with success status and message
+    # @param purpose [String] 'login', 'signup', or 'password_reset'
+    # @return [Hash]
     def send_otp(email:, purpose: 'login')
-      unless ['login', 'signup', 'password_reset'].include?(purpose)
-        raise WOWSQLException.new("Purpose must be 'login', 'signup', or 'password_reset'")
+      unless %w[login signup password_reset].include?(purpose)
+        raise WOWSQLError.new("Purpose must be 'login', 'signup', or 'password_reset'")
       end
 
-      payload = {
-        email: email,
-        purpose: purpose
-      }
-
+      payload = { email: email, purpose: purpose }
       data = request('POST', '/otp/send', nil, payload)
-
       {
-        success: data['success'] != false,
-        message: data['message'] || 'If that email exists, an OTP code has been sent'
+        'success' => data['success'] != false,
+        'message' => data['message'] || 'If that email exists, an OTP code has been sent'
       }
     end
 
     # Verify OTP and complete authentication.
-    # 
+    #
     # @param email [String] User's email address
     # @param otp [String] 6-digit OTP code
-    # @param purpose [String] Purpose of OTP - 'login', 'signup', or 'password_reset' (default: 'login')
-    # @param new_password [String, nil] Required for password_reset purpose, new password (minimum 8 characters)
-    # @return [Hash] Response with session and user data (for login/signup) or success message (for password_reset)
+    # @param purpose [String] 'login', 'signup', or 'password_reset'
+    # @param new_password [String, nil] Required for password_reset purpose
+    # @return [AuthResponse, Hash]
     def verify_otp(email:, otp:, purpose: 'login', new_password: nil)
-      unless ['login', 'signup', 'password_reset'].include?(purpose)
-        raise WOWSQLException.new("Purpose must be 'login', 'signup', or 'password_reset'")
+      unless %w[login signup password_reset].include?(purpose)
+        raise WOWSQLError.new("Purpose must be 'login', 'signup', or 'password_reset'")
       end
 
       if purpose == 'password_reset' && new_password.nil?
-        raise WOWSQLException.new('new_password is required for password_reset purpose')
+        raise WOWSQLError.new('new_password is required for password_reset purpose')
       end
 
-      payload = {
-        email: email,
-        otp: otp,
-        purpose: purpose
-      }
+      payload = { email: email, otp: otp, purpose: purpose }
       payload[:new_password] = new_password if new_password
 
       data = request('POST', '/otp/verify', nil, payload)
 
       if purpose == 'password_reset'
         return {
-          success: data['success'] != false,
-          message: data['message'] || 'Password reset successfully! You can now login with your new password'
+          'success' => data['success'] != false,
+          'message' => data['message'] || 'Password reset successfully! You can now login with your new password'
         }
       end
 
       session = persist_session(data)
-
-      {
-        session: session,
-        user: data['user'] ? normalize_user(data['user']) : nil
-      }
+      user = data['user'] ? AuthUser.new(**normalize_user(data['user'])) : nil
+      AuthResponse.new(session: session, user: user)
     end
 
     # Send magic link to user's email.
-    # 
+    #
     # @param email [String] User's email address
-    # @param purpose [String] Purpose of magic link - 'login', 'signup', or 'email_verification' (default: 'login')
-    # @return [Hash] Response with success status and message
+    # @param purpose [String] 'login', 'signup', or 'email_verification'
+    # @return [Hash]
     def send_magic_link(email:, purpose: 'login')
-      unless ['login', 'signup', 'email_verification'].include?(purpose)
-        raise WOWSQLException.new("Purpose must be 'login', 'signup', or 'email_verification'")
+      unless %w[login signup email_verification].include?(purpose)
+        raise WOWSQLError.new("Purpose must be 'login', 'signup', or 'email_verification'")
       end
 
-      payload = {
-        email: email,
-        purpose: purpose
-      }
-
+      payload = { email: email, purpose: purpose }
       data = request('POST', '/magic-link/send', nil, payload)
-
       {
-        success: data['success'] != false,
-        message: data['message'] || 'If that email exists, a magic link has been sent'
+        'success' => data['success'] != false,
+        'message' => data['message'] || 'If that email exists, a magic link has been sent'
       }
     end
 
     # Verify email using token.
-    # 
+    #
     # @param token [String] Verification token from email
-    # @return [Hash] Response with success status, message, and user info
+    # @return [Hash]
     def verify_email(token:)
       payload = { token: token }
       data = request('POST', '/verify-email', nil, payload)
-
       {
-        success: data['success'] != false,
-        message: data['message'] || 'Email verified successfully!',
-        user: data['user'] ? normalize_user(data['user']) : nil
+        'success' => data['success'] != false,
+        'message' => data['message'] || 'Email verified successfully!',
+        'user' => data['user'] ? AuthUser.new(**normalize_user(data['user'])) : nil
       }
     end
 
     # Resend verification email.
-    # 
+    #
     # @param email [String] User's email address
-    # @return [Hash] Response with success status and message
+    # @return [Hash]
     def resend_verification(email:)
       payload = { email: email }
       data = request('POST', '/resend-verification', nil, payload)
-
       {
-        success: data['success'] != false,
-        message: data['message'] || 'If that email exists, a verification email has been sent'
+        'success' => data['success'] != false,
+        'message' => data['message'] || 'If that email exists, a verification email has been sent'
       }
     end
 
+    # Logout the current user by invalidating their session.
+    #
+    # @param access_token [String, nil] Override access token
+    # @return [Hash]
+    def logout(access_token: nil)
+      token = access_token || @access_token || @storage.get_access_token
+      raise WOWSQLError.new('Access token is required. Call sign_in first.') unless token
+
+      data = request_with_headers('POST', '/logout', nil, nil, 'Authorization' => "Bearer #{token}")
+      clear_session
+      data
+    end
+
+    # Exchange a refresh token for new access + refresh tokens.
+    #
+    # @param refresh_token [String, nil] Override refresh token
+    # @return [AuthResponse]
+    def refresh_token(refresh_token: nil)
+      token = refresh_token || @refresh_token || @storage.get_refresh_token
+      raise WOWSQLError.new('Refresh token is required. Call sign_in first.') unless token
+
+      data = request('POST', '/refresh-token', nil, { refresh_token: token })
+      session = persist_session(data)
+      AuthResponse.new(session: session, user: nil)
+    end
+
+    # Change the authenticated user's password.
+    #
+    # @param current_password [String] Current password
+    # @param new_password [String] New password (minimum 8 characters)
+    # @param access_token [String, nil] Override access token
+    # @return [Hash]
+    def change_password(current_password:, new_password:, access_token: nil)
+      token = access_token || @access_token || @storage.get_access_token
+      raise WOWSQLError.new('Access token is required. Call sign_in first.') unless token
+
+      request_with_headers(
+        'POST', '/change-password', nil,
+        { current_password: current_password, new_password: new_password },
+        'Authorization' => "Bearer #{token}"
+      )
+    end
+
+    # Update the authenticated user's profile.
+    #
+    # @param full_name [String, nil] Updated full name
+    # @param avatar_url [String, nil] Updated avatar URL
+    # @param username [String, nil] Updated username
+    # @param user_metadata [Hash, nil] Updated metadata
+    # @param access_token [String, nil] Override access token
+    # @return [AuthUser]
+    def update_user(full_name: nil, avatar_url: nil, username: nil, user_metadata: nil, access_token: nil)
+      token = access_token || @access_token || @storage.get_access_token
+      raise WOWSQLError.new('Access token is required. Call sign_in first.') unless token
+
+      payload = {}
+      payload[:full_name] = full_name unless full_name.nil?
+      payload[:avatar_url] = avatar_url unless avatar_url.nil?
+      payload[:username] = username unless username.nil?
+      payload[:user_metadata] = user_metadata unless user_metadata.nil?
+      raise WOWSQLError.new('At least one field to update is required') if payload.empty?
+
+      data = request_with_headers('PATCH', '/me', nil, payload, 'Authorization' => "Bearer #{token}")
+      AuthUser.new(**normalize_user(data))
+    end
+
     # Get current session tokens.
-    # 
-    # @return [Hash] Current access_token and refresh_token
+    #
+    # @return [Hash]
     def get_session
       {
-        access_token: @access_token,
-        refresh_token: @refresh_token
+        'access_token' => @access_token || @storage.get_access_token,
+        'refresh_token' => @refresh_token || @storage.get_refresh_token
       }
     end
 
     # Set session tokens.
-    # 
+    #
     # @param access_token [String] Access token
     # @param refresh_token [String, nil] Optional refresh token
     def set_session(access_token:, refresh_token: nil)
       @access_token = access_token
       @refresh_token = refresh_token
+      @storage.set_access_token(access_token)
+      @storage.set_refresh_token(refresh_token)
     end
 
     # Clear session tokens.
     def clear_session
       @access_token = nil
       @refresh_token = nil
+      @storage.set_access_token(nil)
+      @storage.set_refresh_token(nil)
+    end
+
+    # Close the HTTP connection.
+    def close
+      @conn.close if @conn.respond_to?(:close)
     end
 
     private
 
-    # Build authentication base URL from project URL.
-    def build_auth_base_url(project_url)
+    def build_auth_base_url(project_url, base_domain, secure)
       normalized = project_url.strip
 
-      # If it's already a full URL, use it as-is
       if normalized.start_with?('http://') || normalized.start_with?('https://')
         normalized = normalized.chomp('/')
-        normalized = normalized[0..-5] if normalized.end_with?('/api')
+        normalized = normalized[0...-4] if normalized.end_with?('/api')
         return "#{normalized}/api/auth"
       end
 
-      # If it already contains the base domain, don't append it again
-      if normalized.include?('.wowsql.com') || normalized.end_with?('wowsql.com')
-        normalized = "https://#{normalized}"
+      protocol = secure ? 'https' : 'http'
+      if normalized.include?(".#{base_domain}") || normalized.end_with?(base_domain)
+        normalized = "#{protocol}://#{normalized}"
       else
-        # Just a project slug, append domain
-        normalized = "https://#{normalized}.wowsql.com"
+        normalized = "#{protocol}://#{normalized}.#{base_domain}"
       end
 
       normalized = normalized.chomp('/')
-      normalized = normalized[0..-5] if normalized.end_with?('/api')
+      normalized = normalized[0...-4] if normalized.end_with?('/api')
 
       "#{normalized}/api/auth"
     end
 
-    # Normalize user data from API response.
     def normalize_user(user)
+      return { id: '', email: '' } unless user
+
       {
-        id: user['id'] || user[:id],
-        email: user['email'] || user[:email],
+        id: user['id'] || user[:id] || '',
+        email: user['email'] || user[:email] || '',
         full_name: user['full_name'] || user['fullName'] || user[:full_name] || user[:fullName],
         avatar_url: user['avatar_url'] || user['avatarUrl'] || user[:avatar_url] || user[:avatarUrl],
         email_verified: !!(user['email_verified'] || user['emailVerified'] || user[:email_verified] || user[:emailVerified]),
@@ -345,40 +477,57 @@ module WOWSQL
       }
     end
 
-    # Persist session tokens from API response.
     def persist_session(data)
-      session = {
+      session = AuthSession.new(
         access_token: data['access_token'] || data[:access_token] || '',
         refresh_token: data['refresh_token'] || data[:refresh_token] || '',
         token_type: data['token_type'] || data[:token_type] || 'bearer',
         expires_in: data['expires_in'] || data[:expires_in] || 0
-      }
+      )
 
-      @access_token = session[:access_token]
-      @refresh_token = session[:refresh_token]
+      @access_token = session.access_token
+      @refresh_token = session.refresh_token
+      @storage.set_access_token(session.access_token)
+      @storage.set_refresh_token(session.refresh_token)
 
       session
     end
 
-    # Make HTTP request to API.
     def request(method, path, params = nil, json = nil)
-      begin
-        response = @conn.public_send(method.downcase, path) do |req|
-          req.params = params if params
-          req.body = json if json
-        end
+      response = @conn.public_send(method.downcase, path) do |req|
+        req.params = params if params
+        req.body = json if json
+      end
 
-        if response.status >= 400
-          error_data = response.body.is_a?(Hash) ? response.body : {}
-          error_msg = error_data['detail'] || error_data['message'] || error_data['error'] || "Request failed with status #{response.status}"
-          raise WOWSQLException.new(error_msg, response.status, error_data)
-        end
+      if response.status >= 400
+        error_data = response.body.is_a?(Hash) ? response.body : {}
+        error_msg = error_data['detail'] || error_data['message'] || error_data['error'] ||
+                    "Request failed with status #{response.status}"
+        raise WOWSQLError.new(error_msg, response.status, error_data)
+      end
 
-        response.body || {}
-      rescue Faraday::Error => e
-        raise WOWSQLException.new("Request failed: #{e.message}")
+      response.body || {}
+    rescue Faraday::Error => e
+      raise WOWSQLError.new("Request failed: #{e.message}")
+    end
+
+    def request_with_headers(method, path, params, json, extra_headers)
+      response = @conn.public_send(method.downcase, path) do |req|
+        req.params = params if params
+        req.body = json if json
+        extra_headers.each { |k, v| req.headers[k] = v } if extra_headers
+      end
+
+      if response.status >= 400
+        error_data = response.body.is_a?(Hash) ? response.body : {}
+        error_msg = error_data['detail'] || error_data['message'] || error_data['error'] ||
+                    "Request failed with status #{response.status}"
+        raise WOWSQLError.new(error_msg, response.status, error_data)
       end
+
+      response.body || {}
+    rescue Faraday::Error => e
+      raise WOWSQLError.new("Request failed: #{e.message}")
     end
   end
 end
-