wowsql-sdk 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad880e2257d4f66eb09d166676bb673d10fdc77d40e8649d9d21dd752c5b116d
-  data.tar.gz: f592669e6b04a84cee0c541447d1f7124e114386647c608c940af69b6c6fbe8b
+  metadata.gz: 9f59248127728b52972504dd30e3f03ce86f0edaa2070f3988bf01ca9ee6485d
+  data.tar.gz: 1475a5cf06884e86dd4aeee607d16969ed02688383401cea40c59f8228cf5d8f
 SHA512:
-  metadata.gz: 980b656e45ad73330ce5b87e6405013b00bc38a60a7d55ff33612c0157ae599a10721480cf018ba21903740e07c5d178d2b28b39591ea16704896fe39a3de258
-  data.tar.gz: a621bd63b4f1c0c803dd5bf27216968aaba137b24d25a23473e290ca445eb4f9f24e50d72cfa8bf5cba442e03aa76be62add3d8e07d3177cc010d0ae0a3035c6
+  metadata.gz: fc0f99522a2d2c1753a72faed398a8bafee6336ab3be65a275829db58ce100bf62b55b6a36e2519537b21173cf72f0b49b9ca2fdf2a87bd79ba74834e7f788bf
+  data.tar.gz: 76b3cc58a7587f4ca3ad16aa2e5bd09a031cfdafdb46763d346d38122a45a4b128db4bb3b36498c50b8c3d44e14d55771513d92eb89d959fdbfda576b30d0bc4

data/lib/wowsql/auth.rb

@@ -0,0 +1,384 @@
+require 'faraday'
+require 'json'
+require_relative 'exceptions'
+
+module WOWSQL
+  # 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)
+  class ProjectAuthClient
+    def initialize(project_url, api_key, timeout = 30)
+      @api_key = api_key
+      @timeout = timeout
+      @base_url = build_auth_base_url(project_url)
+      @access_token = nil
+      @refresh_token = nil
+
+      @conn = Faraday.new(url: @base_url) 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 [Hash] Response with session and user data
+    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)
+
+      {
+        session: session,
+        user: data['user'] ? normalize_user(data['user']) : nil
+      }
+    end
+
+    # Sign in an existing user.
+    # 
+    # @param email [String] User email
+    # @param password [String] User password
+    # @return [Hash] Response with session and user data
+    def sign_in(email:, password:)
+      payload = {
+        email: email,
+        password: password
+      }
+
+      data = request('POST', '/login', nil, payload)
+      session = persist_session(data)
+
+      {
+        session: session,
+        user: data['user'] ? normalize_user(data['user']) : nil
+      }
+    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
+    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?
+
+      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 WOWSQLException => 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
+          )
+        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
+          )
+        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 [Hash] Response with session and user data
+    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
+      }
+    end
+
+    # Request password reset.
+    # 
+    # @param email [String] User's email address
+    # @return [Hash] Response with success status and message
+    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] Response with success status and message
+    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] Purpose of OTP - 'login', 'signup', or 'password_reset' (default: 'login')
+    # @return [Hash] Response with success status and message
+    def send_otp(email:, purpose: 'login')
+      unless ['login', 'signup', 'password_reset'].include?(purpose)
+        raise WOWSQLException.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] 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)
+    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'")
+      end
+
+      if purpose == 'password_reset' && new_password.nil?
+        raise WOWSQLException.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)
+
+      {
+        session: session,
+        user: data['user'] ? normalize_user(data['user']) : nil
+      }
+    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
+    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'")
+      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] Response with success status, message, and user info
+    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
+      }
+    end
+
+    # Resend verification email.
+    # 
+    # @param email [String] User's email address
+    # @return [Hash] Response with success status and message
+    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
+
+    # Get current session tokens.
+    # 
+    # @return [Hash] Current access_token and refresh_token
+    def get_session
+      {
+        access_token: @access_token,
+        refresh_token: @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
+    end
+
+    # Clear session tokens.
+    def clear_session
+      @access_token = nil
+      @refresh_token = nil
+    end
+
+    private
+
+    # Build authentication base URL from project URL.
+    def build_auth_base_url(project_url)
+      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')
+        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}"
+      else
+        # Just a project slug, append domain
+        normalized = "https://#{normalized}.wowsql.com"
+      end
+
+      normalized = normalized.chomp('/')
+      normalized = normalized[0..-5] if normalized.end_with?('/api')
+
+      "#{normalized}/api/auth"
+    end
+
+    # Normalize user data from API response.
+    def normalize_user(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
+
+    # Persist session tokens from API response.
+    def persist_session(data)
+      session = {
+        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]
+
+      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
+
+        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
+
+        response.body || {}
+      rescue Faraday::Error => e
+        raise WOWSQLException.new("Request failed: #{e.message}")
+      end
+    end
+  end
+end
+

data/lib/wowsql/query_builder.rb

@@ -5,14 +5,26 @@ module WOWSQL
       @client = client
       @table_name = table_name
       @params = {}
+      @select_columns = nil
+      @filters = []
+      @group_by = nil
+      @having = []
+      @order_items = nil
     end
 
     def select(*columns)
-      if columns.length == 1 && columns[0] == '*'
-        @params['select'] = '*'
-      else
-        @params['select'] = columns.join(',')
-      end
+      @select_columns = columns
+      self
+    end
+
+    # Add a filter condition (generic method).
+    # 
+    # @param column [String] Column name
+    # @param operator [String] Operator (eq, neq, gt, gte, lt, lte, like, in, not_in, between, not_between, is, is_not)
+    # @param value [Object] Filter value
+    # @param logical_op [String] Logical operator for combining with previous filters ("AND" or "OR")
+    def filter(column, operator, value, logical_op = 'AND')
+      add_filter(column, operator, value, logical_op)
       self
     end
 
@@ -52,7 +64,52 @@ module WOWSQL
     end
 
     def is_null(column)
-      add_filter(column, 'is', nil)
+      @filters << { column: column, operator: 'is', value: nil, logical_op: 'AND' }
+      self
+    end
+
+    def is_not_null(column)
+      @filters << { column: column, operator: 'is_not', value: nil, logical_op: 'AND' }
+      self
+    end
+
+    def in(column, values)
+      @filters << { column: column, operator: 'in', value: values, logical_op: 'AND' }
+      self
+    end
+
+    def not_in(column, values)
+      @filters << { column: column, operator: 'not_in', value: values, logical_op: 'AND' }
+      self
+    end
+
+    def between(column, min, max)
+      @filters << { column: column, operator: 'between', value: [min, max], logical_op: 'AND' }
+      self
+    end
+
+    def not_between(column, min, max)
+      @filters << { column: column, operator: 'not_between', value: [min, max], logical_op: 'AND' }
+      self
+    end
+
+    def or(column, operator, value)
+      @filters << { column: column, operator: operator, value: value, logical_op: 'OR' }
+      self
+    end
+
+    def group_by(*columns)
+      @group_by = columns
+      self
+    end
+
+    def having(column, operator, value)
+      @having << { column: column, operator: operator, value: value }
+      self
+    end
+
+    def order_by_multiple(*items)
+      @order_items = items
       self
     end
 
@@ -62,6 +119,11 @@ module WOWSQL
       self
     end
 
+    # Order results by column (alias for order_by, backward compatibility).
+    def order(column, direction = 'asc')
+      order_by(column, desc: direction.downcase == 'desc')
+    end
+
     def limit(limit)
       @params['limit'] = limit.to_s
       self
@@ -73,7 +135,27 @@ module WOWSQL
     end
 
     def get
-      @client.request('GET', "/#{@table_name}", @params, nil)
+      # Check if we need POST endpoint (advanced features)
+      has_advanced_features = 
+        (@group_by && !@group_by.empty?) ||
+        !@having.empty? ||
+        (@order_items && !@order_items.empty?) ||
+        @filters.any? { |f| ['in', 'not_in', 'between', 'not_between'].include?(f[:operator]) }
+
+      if has_advanced_features
+        # Use POST endpoint for advanced queries
+        body = build_query_body
+        @client.request('POST', "/#{@table_name}/query", nil, body)
+      else
+        # Use GET endpoint for simple queries (backward compatibility)
+        build_get_params
+        @client.request('GET', "/#{@table_name}", @params, nil)
+      end
+    end
+
+    # Execute the query (alias for get).
+    def execute
+      get
     end
 
     def first
@@ -84,12 +166,49 @@ module WOWSQL
     private
 
     def add_filter(column, op, value)
-      filter_value = "#{column}.#{op}.#{value || 'null'}"
-      
-      if @params['filter']
-        @params['filter'] += ",#{filter_value}"
-      else
-        @params['filter'] = filter_value
+      @filters << { column: column, operator: op, value: value, logical_op: 'AND' }
+    end
+
+    def build_query_body
+      body = {}
+
+      body['select'] = @select_columns if @select_columns && !@select_columns.empty?
+
+      body['filters'] = @filters if !@filters.empty?
+
+      body['group_by'] = @group_by if @group_by && !@group_by.empty?
+
+      body['having'] = @having if !@having.empty?
+
+      if @order_items && !@order_items.empty?
+        body['order_by'] = @order_items.map do |item|
+          if item.is_a?(Hash)
+            item
+          else
+            { column: item[0], direction: item[1] }
+          end
+        end
+      elsif @params['order']
+        body['order_by'] = @params['order']
+        body['order_direction'] = @params['order_direction'] || 'asc'
+      end
+
+      body['limit'] = @params['limit'].to_i if @params['limit']
+      body['offset'] = @params['offset'].to_i if @params['offset']
+
+      body
+    end
+
+    def build_get_params
+      @params['select'] = @select_columns.join(',') if @select_columns && !@select_columns.empty?
+
+      simple_filters = @filters.reject { |f| ['in', 'not_in', 'between', 'not_between'].include?(f[:operator]) }
+      if !simple_filters.empty?
+        filter_strings = simple_filters.map do |f|
+          value_str = f[:value] || 'null'
+          "#{f[:column]}.#{f[:operator]}.#{value_str}"
+        end
+        @params['filter'] = filter_strings.join(',')
       end
     end
   end

data/lib/wowsql/storage.rb

@@ -0,0 +1,229 @@
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+require 'stringio'
+require 'uri'
+require_relative 'exceptions'
+
+module WOWSQL
+  # WOWSQL Storage Client - Manage S3 storage with automatic quota validation.
+  class WOWSQLStorage
+    def initialize(project_slug, api_key, base_url = 'https://api.wowsql.com', timeout = 60, auto_check_quota = true)
+      @project_slug = project_slug
+      @api_key = api_key
+      @base_url = base_url.chomp('/')
+      @timeout = timeout
+      @auto_check_quota = auto_check_quota
+      @quota_cache = nil
+
+      @conn = Faraday.new(url: @base_url) do |f|
+        f.request :multipart
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+        f.options.timeout = timeout
+      end
+
+      @conn.headers['Authorization'] = "Bearer #{api_key}"
+    end
+
+    # Get storage quota information.
+    # 
+    # @param force_refresh [Boolean] Force refresh quota from server
+    # @return [Hash] Storage quota details
+    def get_quota(force_refresh = false)
+      return @quota_cache if @quota_cache && !force_refresh
+
+      response = request('GET', "/api/v1/storage/s3/projects/#{@project_slug}/quota", nil, nil)
+      @quota_cache = response
+      response
+    end
+
+    # Upload file from local filesystem path.
+    # 
+    # @param file_path [String] Path to local file
+    # @param file_key [String] File name or path in bucket
+    # @param folder [String, nil] Optional folder path
+    # @param content_type [String, nil] Optional content type
+    # @param check_quota [Boolean, nil] Override auto quota checking
+    # @return [Hash] Upload result
+    def upload_from_path(file_path, file_key = nil, folder = nil, content_type = nil, check_quota = nil)
+      unless File.exist?(file_path)
+        raise StorageException.new("File not found: #{file_path}")
+      end
+
+      file_key ||= File.basename(file_path)
+      upload_file(File.open(file_path, 'rb'), file_key, folder, content_type, check_quota)
+    end
+
+    # Upload file from file object or IO stream.
+    # 
+    # @param file_data [IO, String] File object or file path
+    # @param file_key [String] File name or path in bucket
+    # @param folder [String, nil] Optional folder path
+    # @param content_type [String, nil] Optional content type
+    # @param check_quota [Boolean, nil] Override auto quota checking
+    # @return [Hash] Upload result
+    def upload_file(file_data, file_key, folder = nil, content_type = nil, check_quota = nil)
+      should_check = check_quota.nil? ? @auto_check_quota : check_quota
+
+      # Read file data
+      file_bytes = file_data.respond_to?(:read) ? file_data.read : File.read(file_data)
+      file_size = file_bytes.bytesize
+
+      # Check quota if enabled
+      if should_check
+        quota = get_quota(true)
+        file_size_gb = file_size / (1024.0 * 1024.0 * 1024.0)
+        if file_size_gb > quota['storage_available_gb']
+          raise StorageLimitExceededException.new(
+            "Storage limit exceeded! File size: #{format('%.4f', file_size_gb)} GB, " \
+            "Available: #{format('%.4f', quota['storage_available_gb'])} GB."
+          )
+        end
+      end
+
+      # Build URL
+      url = "/api/v1/storage/s3/projects/#{@project_slug}/upload"
+      url += "?folder=#{URI.encode_www_form_component(folder)}" if folder
+
+      begin
+        # Create multipart form
+        payload = {
+          file: Faraday::Multipart::FilePart.new(
+            StringIO.new(file_bytes),
+            content_type || 'application/octet-stream',
+            file_key
+          ),
+          key: file_key
+        }
+        payload[:content_type] = content_type if content_type
+
+        response = @conn.post(url) do |req|
+          req.body = payload
+        end
+
+        if response.status >= 400
+          handle_error(response)
+        end
+
+        @quota_cache = nil # Refresh quota cache
+        response.body
+      rescue Faraday::Error => e
+        raise StorageException.new("Upload failed: #{e.message}")
+      end
+    end
+
+    # List files in S3 bucket.
+    # 
+    # @param prefix [String, nil] Filter by prefix/folder
+    # @param max_keys [Integer] Maximum files to return
+    # @return [Array<Hash>] List of file objects
+    def list_files(prefix = nil, max_keys = 1000)
+      params = { max_keys: max_keys }
+      params[:prefix] = prefix if prefix
+
+      response = request('GET', "/api/v1/storage/s3/projects/#{@project_slug}/files", params, nil)
+      response['files'] || []
+    end
+
+    # Delete a file from S3 bucket.
+    # 
+    # @param file_key [String] Path to file in bucket
+    # @return [Hash] Deletion result
+    def delete_file(file_key)
+      response = request('DELETE', "/api/v1/storage/s3/projects/#{@project_slug}/files/#{file_key}", nil, nil)
+      @quota_cache = nil # Refresh quota cache
+      response
+    end
+
+    # Get presigned URL for file access with full metadata.
+    # 
+    # @param file_key [String] Path to file in bucket
+    # @param expires_in [Integer] URL validity in seconds (default: 3600 = 1 hour)
+    # @return [Hash] Dict with file URL and metadata
+    def get_file_url(file_key, expires_in = 3600)
+      params = { expires_in: expires_in }
+      request('GET', "/api/v1/storage/s3/projects/#{@project_slug}/files/#{file_key}/url", params, nil)
+    end
+
+    # Generate presigned URL for file operations.
+    # 
+    # @param file_key [String] Path to file in bucket
+    # @param expires_in [Integer] URL validity in seconds (default: 3600)
+    # @param operation [String] 'get_object' (download) or 'put_object' (upload)
+    # @return [String] Presigned URL string
+    def get_presigned_url(file_key, expires_in = 3600, operation = 'get_object')
+      payload = {
+        file_key: file_key,
+        expires_in: expires_in,
+        operation: operation
+      }
+
+      response = request('POST', "/api/v1/storage/s3/projects/#{@project_slug}/presigned-url", nil, payload)
+      response['url'] || ''
+    end
+
+    # Get S3 storage information for the project.
+    # 
+    # @return [Hash] Dict with storage info
+    def get_storage_info
+      request('GET', "/api/v1/storage/s3/projects/#{@project_slug}/info", nil, nil)
+    end
+
+    # Provision S3 storage for the project.
+    # ⚠️ IMPORTANT: Save the credentials returned! They're only shown once.
+    # 
+    # @param region [String] AWS region (default: 'us-east-1')
+    # @return [Hash] Dict with provisioning result including credentials
+    def provision_storage(region = 'us-east-1')
+      payload = { region: region }
+      request('POST', "/api/v1/storage/s3/projects/#{@project_slug}/provision", nil, payload)
+    end
+
+    # Get list of available S3 regions with pricing.
+    # 
+    # @return [Array<Hash>] List of region dictionaries with pricing info
+    def get_available_regions
+      response = request('GET', '/api/v1/storage/s3/regions', nil, nil)
+      
+      # Handle both list and map responses
+      return response if response.is_a?(Array)
+      return response['regions'] if response.is_a?(Hash) && response['regions']
+      [response]
+    end
+
+    private
+
+    # Make HTTP request to Storage 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
+          handle_error(response)
+        end
+
+        response.body
+      rescue Faraday::Error => e
+        raise StorageException.new("Request failed: #{e.message}")
+      end
+    end
+
+    # Handle HTTP errors
+    def handle_error(response)
+      error_data = response.body.is_a?(Hash) ? response.body : {}
+      error_msg = error_data['detail'] || error_data['message'] || "Request failed with status #{response.status}"
+
+      if response.status == 413
+        raise StorageLimitExceededException.new(error_msg, response.status, error_data)
+      end
+
+      raise StorageException.new(error_msg, response.status, error_data)
+    end
+  end
+end
+

data/lib/wowsql/table.rb

@@ -39,6 +39,14 @@ module WOWSQL
       @client.request('POST', "/#{@table_name}", nil, data)
     end
 
+    # Insert a new record (alias for create).
+    # 
+    # @param data [Hash] Record data
+    # @return [Hash] Create response with new record ID
+    def insert(data)
+      create(data)
+    end
+
     # Update a record by ID.
     # 
     # @param record_id [Object] Record ID

data/lib/wowsql.rb

@@ -3,6 +3,7 @@ require_relative 'wowsql/exceptions'
 require_relative 'wowsql/client'
 require_relative 'wowsql/table'
 require_relative 'wowsql/query_builder'
+require_relative 'wowsql/auth'
 
 module WOWSQL
   # Main module for WOWSQL SDK

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wowsql-sdk
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - WOWSQL Team
@@ -77,9 +77,11 @@ files:
 - README.md
 - lib/wowmysql.rb
 - lib/wowsql.rb
+- lib/wowsql/auth.rb
 - lib/wowsql/client.rb
 - lib/wowsql/exceptions.rb
 - lib/wowsql/query_builder.rb
+- lib/wowsql/storage.rb
 - lib/wowsql/table.rb
 - lib/wowsql/version.rb
 homepage: https://github.com/wowsql/wowsql-sdk-ruby
@@ -100,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.2
 specification_version: 4
 summary: Official Ruby client library for WOWSQL - MySQL Backend-as-a-Service with
   S3 Storage