wowsql-sdk 1.2.0 → 3.0.1

data/lib/wowmysql.rb

@@ -3,8 +3,9 @@ require_relative 'wowsql/exceptions'
 require_relative 'wowsql/client'
 require_relative 'wowsql/table'
 require_relative 'wowsql/query_builder'
+require_relative 'wowsql/auth'
+require_relative 'wowsql/storage'
+require_relative 'wowsql/schema'
 
 module WOWSQL
-  # Main module for WOWSQL SDK
 end
-

data/lib/wowsql/auth.rb

@@ -0,0 +1,533 @@
+require 'faraday'
+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
+  #   - Service Role Key (wowsql_service_...): For server-side auth operations
+  class ProjectAuthClient
+    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, 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, ssl: ssl_options) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+        f.options.timeout = timeout
+      end
+
+      @conn.headers['Authorization'] = "Bearer #{api_key}"
+      @conn.headers['Content-Type'] = 'application/json'
+    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 [AuthResponse]
+    def sign_up(email:, password:, full_name: nil, user_metadata: nil)
+      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)
+      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 [AuthResponse]
+    def sign_in(email:, password:)
+      payload = { email: email, password: password }
+      data = request('POST', '/login', nil, payload)
+      session = persist_session(data)
+      AuthResponse.new(session: session, user: nil)
+    end
+
+    # 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]
+    def get_oauth_authorization_url(provider:, redirect_uri: nil)
+      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 || ''
+        }
+      rescue WOWSQLError => e
+        if e.status_code == 502
+          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 WOWSQLError.new(
+            "Bad Request (400): #{e.message}. " \
+            "Ensure OAuth provider '#{provider}' is configured and enabled for this project.",
+            400, e.response
+          )
+        end
+        raise
+      end
+    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 [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)
+      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]
+    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'
+      }
+    end
+
+    # Reset password with token.
+    #
+    # @param token [String] Password reset token from email
+    # @param new_password [String] New password (minimum 8 characters)
+    # @return [Hash]
+    def reset_password(token:, 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'
+      }
+    end
+
+    # Send OTP code to user's email.
+    #
+    # @param email [String] User's email address
+    # @param purpose [String] 'login', 'signup', or 'password_reset'
+    # @return [Hash]
+    def send_otp(email:, purpose: 'login')
+      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 }
+      data = request('POST', '/otp/send', nil, payload)
+      {
+        '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] '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 %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 WOWSQLError.new('new_password is required for password_reset purpose')
+      end
+
+      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'
+        }
+      end
+
+      session = persist_session(data)
+      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] 'login', 'signup', or 'email_verification'
+    # @return [Hash]
+    def send_magic_link(email:, purpose: 'login')
+      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 }
+      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'
+      }
+    end
+
+    # Verify email using token.
+    #
+    # @param token [String] Verification token from email
+    # @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'] ? AuthUser.new(**normalize_user(data['user'])) : nil
+      }
+    end
+
+    # Resend verification email.
+    #
+    # @param email [String] User's email address
+    # @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'
+      }
+    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]
+    def get_session
+      {
+        '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
+
+    def build_auth_base_url(project_url, base_domain, secure)
+      normalized = project_url.strip
+
+      if normalized.start_with?('http://') || normalized.start_with?('https://')
+        normalized = normalized.chomp('/')
+        normalized = normalized[0...-4] if normalized.end_with?('/api')
+        return "#{normalized}/api/auth"
+      end
+
+      protocol = secure ? 'https' : 'http'
+      if normalized.include?(".#{base_domain}") || normalized.end_with?(base_domain)
+        normalized = "#{protocol}://#{normalized}"
+      else
+        normalized = "#{protocol}://#{normalized}.#{base_domain}"
+      end
+
+      normalized = normalized.chomp('/')
+      normalized = normalized[0...-4] if normalized.end_with?('/api')
+
+      "#{normalized}/api/auth"
+    end
+
+    def normalize_user(user)
+      return { id: '', email: '' } unless user
+
+      {
+        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]),
+        user_metadata: user['user_metadata'] || user['userMetadata'] || user[:user_metadata] || user[:userMetadata] || {},
+        app_metadata: user['app_metadata'] || user['appMetadata'] || user[:app_metadata] || user[:appMetadata] || {},
+        created_at: user['created_at'] || user['createdAt'] || user[:created_at] || user[:createdAt]
+      }
+    end
+
+    def persist_session(data)
+      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
+      @storage.set_access_token(session.access_token)
+      @storage.set_refresh_token(session.refresh_token)
+
+      session
+    end
+
+    def request(method, path, params = nil, json = nil)
+      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 WOWSQLError.new(error_msg, response.status, error_data)
+      end
+
+      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

data/lib/wowsql/client.rb

@@ -5,27 +5,54 @@ require_relative 'table'
 
 module WOWSQL
   # WOWSQL client for interacting with your database via REST API.
-  # 
+  #
   # This client is used for DATABASE OPERATIONS (CRUD on tables).
   # Use Service Role Key or Anonymous Key for authentication.
+  #
+  # Key Types:
+  #   - Service Role Key: Full access to all database operations (server-side)
+  #   - Anonymous Key: Public access with limited permissions (client-side)
+  #
+  # @example
+  #   client = WOWSQL::WOWSQLClient.new(
+  #     "myproject",
+  #     "wowbase_service_..."
+  #   )
+  #   users = client.table("users").get
   class WOWSQLClient
-    def initialize(project_url, api_key, timeout = 30)
+    attr_reader :api_url, :api_key, :timeout, :verify_ssl
+
+    # @param project_url [String] Project subdomain or full URL
+    # @param api_key [String] API key for database operations
+    # @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)
+    def initialize(project_url, api_key, base_domain: 'wowsql.com', secure: true, timeout: 30, verify_ssl: true)
       @api_key = api_key
       @timeout = timeout
+      @verify_ssl = verify_ssl
 
-      # Build API URL
       if project_url.start_with?('http://') || project_url.start_with?('https://')
         base_url = project_url.chomp('/')
         if base_url.include?('/api')
-          @api_url = base_url.sub('/api', '') + '/api/v2'
+          base_url = base_url.split('/api').first
+          @api_url = "#{base_url}/api/v2"
         else
-          @api_url = base_url + '/api/v2'
+          @api_url = "#{base_url}/api/v2"
         end
       else
-        @api_url = "https://#{project_url}.wowsql.com/api/v2"
+        protocol = secure ? 'https' : 'http'
+        if project_url.include?(".#{base_domain}") || project_url.end_with?(base_domain)
+          @api_url = "#{protocol}://#{project_url}/api/v2"
+        else
+          @api_url = "#{protocol}://#{project_url}.#{base_domain}/api/v2"
+        end
       end
 
-      @conn = Faraday.new(url: @api_url) do |f|
+      ssl_options = verify_ssl ? {} : { verify: false }
+
+      @conn = Faraday.new(url: @api_url, ssl: ssl_options) do |f|
         f.request :json
         f.response :json
         f.adapter Faraday.default_adapter
@@ -37,7 +64,7 @@ module WOWSQL
     end
 
     # Get a table interface for fluent API.
-    # 
+    #
     # @param table_name [String] Name of the table
     # @return [Table] Table instance for the specified table
     def table(table_name)
@@ -45,7 +72,7 @@ module WOWSQL
     end
 
     # List all tables in the database.
-    # 
+    #
     # @return [Array<String>] List of table names
     def list_tables
       response = request('GET', '/tables', nil, nil)
@@ -53,32 +80,34 @@ module WOWSQL
     end
 
     # Get table schema information.
-    # 
+    #
     # @param table_name [String] Name of the table
     # @return [Hash] Table schema with columns and primary key
     def get_table_schema(table_name)
       request('GET', "/tables/#{table_name}/schema", nil, nil)
     end
 
+    # Close the HTTP connection.
+    def close
+      @conn.close if @conn.respond_to?(:close)
+    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
-
-        if response.status >= 400
-          error_data = response.body.is_a?(Hash) ? response.body : {}
-          error_msg = error_data['detail'] || error_data['message'] || "Request failed with status #{response.status}"
-          raise WOWSQLException.new(error_msg, response.status, error_data)
-        end
+      response = @conn.public_send(method.downcase, path) do |req|
+        req.params = params if params
+        req.body = json if json
+      end
 
-        response.body
-      rescue Faraday::Error => e
-        raise WOWSQLException.new("Request failed: #{e.message}")
+      if response.status >= 400
+        error_data = response.body.is_a?(Hash) ? response.body : {}
+        error_msg = error_data['detail'] || error_data['message'] || "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
-