wowsql-sdk 1.3.0 → 3.0.1

data/lib/wowsql/storage.rb

@@ -3,20 +3,136 @@ require 'faraday/multipart'
 require 'json'
 require 'stringio'
 require 'uri'
+require 'fileutils'
 require_relative 'exceptions'
 
 module WOWSQL
-  # WOWSQL Storage Client - Manage S3 storage with automatic quota validation.
+  # Bucket information.
+  class StorageBucket
+    attr_reader :id, :name, :public, :file_size_limit,
+                :allowed_mime_types, :created_at, :object_count, :total_size
+
+    def initialize(data)
+      @id = data['id'] || data[:id] || ''
+      @name = data['name'] || data[:name] || ''
+      @public = !!(data['public'] || data[:public])
+      @file_size_limit = data['file_size_limit'] || data[:file_size_limit]
+      @allowed_mime_types = data['allowed_mime_types'] || data[:allowed_mime_types]
+      @created_at = data['created_at'] || data[:created_at]
+      @object_count = data['object_count'] || data[:object_count] || 0
+      @total_size = data['total_size'] || data[:total_size] || 0
+    end
+
+    def to_s
+      "StorageBucket(name=#{@name.inspect}, public=#{@public})"
+    end
+    alias inspect to_s
+  end
+
+  # Storage file/object information.
+  class StorageFile
+    attr_reader :id, :bucket_id, :name, :path, :mime_type,
+                :size, :metadata, :created_at, :public_url
+
+    def initialize(data)
+      @id = data['id'] || data[:id] || ''
+      @bucket_id = data['bucket_id'] || data[:bucket_id] || ''
+      @name = data['name'] || data[:name] || ''
+      @path = data['path'] || data[:path] || ''
+      @mime_type = data['mime_type'] || data[:mime_type]
+      @size = data['size'] || data[:size] || 0
+      @metadata = data['metadata'] || data[:metadata] || {}
+      @created_at = data['created_at'] || data[:created_at]
+      @public_url = data['public_url'] || data[:public_url]
+    end
+
+    def size_mb
+      @size / (1024.0 * 1024.0)
+    end
+
+    def size_gb
+      @size / (1024.0 ** 3)
+    end
+
+    def to_s
+      "StorageFile(path=#{@path.inspect}, size=#{'%.2f' % size_mb}MB)"
+    end
+    alias inspect to_s
+  end
+
+  # Storage quota / statistics information.
+  class StorageQuota
+    attr_reader :total_files, :total_size_bytes, :total_size_gb, :file_types
+
+    def initialize(data)
+      @total_files = data['total_files'] || data[:total_files] || 0
+      @total_size_bytes = data['total_size_bytes'] || data[:total_size_bytes] || 0
+      @total_size_gb = data['total_size_gb'] || data[:total_size_gb] || 0
+      @file_types = data['file_types'] || data[:file_types] || {}
+    end
+
+    def to_s
+      "StorageQuota(files=#{@total_files}, size=#{'%.4f' % @total_size_gb}GB)"
+    end
+    alias inspect to_s
+  end
+
+  # WowSQL Storage Client — PostgreSQL-native file storage.
+  #
+  # Files are stored as BYTEA inside each project's storage schema.
+  # No external S3 dependency — everything lives in PostgreSQL.
+  #
+  # @example
+  #   storage = WOWSQL::WOWSQLStorage.new(
+  #     "https://myproject.wowsql.com",
+  #     "wowsql_anon_..."
+  #   )
+  #   bucket = storage.create_bucket("avatars", public: true)
+  #   File.open("photo.jpg", "rb") { |f| storage.upload("avatars", f, path: "users/profile.jpg") }
+  #   files = storage.list_files("avatars", prefix: "users/")
+  #   url = storage.get_public_url("avatars", "users/profile.jpg")
   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('/')
+    attr_reader :base_url, :project_slug
+
+    # @param project_url [String] Project subdomain or full URL
+    # @param api_key [String] API key for authentication
+    # @param project_slug [String] Explicit slug (used with base_url)
+    # @param base_url [String] Explicit base URL (used with project_slug)
+    # @param base_domain [String] Base domain (default: "wowsql.com")
+    # @param secure [Boolean] Use HTTPS (default: true)
+    # @param timeout [Integer] Request timeout in seconds (default: 60)
+    # @param verify_ssl [Boolean] Verify SSL certificates (default: true)
+    def initialize(project_url = '', api_key = '', project_slug: '', base_url: '',
+                   base_domain: 'wowsql.com', secure: true, timeout: 60, verify_ssl: true)
+      if !project_slug.empty? && !base_url.empty?
+        @base_url = base_url.chomp('/')
+        @project_slug = project_slug
+      elsif !project_url.empty?
+        url = project_url.strip
+        if url.start_with?('http://') || url.start_with?('https://')
+          @base_url = url.chomp('/')
+          @base_url = @base_url.split('/api').first if @base_url.include?('/api')
+        else
+          protocol = secure ? 'https' : 'http'
+          if url.include?(".#{base_domain}") || url.end_with?(base_domain)
+            @base_url = "#{protocol}://#{url}"
+          else
+            @base_url = "#{protocol}://#{url}.#{base_domain}"
+          end
+        end
+        @project_slug = url.split('.').first
+                            .sub('https://', '')
+                            .sub('http://', '')
+      else
+        raise ArgumentError, 'Either project_url or (project_slug + base_url) must be provided'
+      end
+
       @timeout = timeout
-      @auto_check_quota = auto_check_quota
-      @quota_cache = nil
+      @verify_ssl = verify_ssl
 
-      @conn = Faraday.new(url: @base_url) do |f|
+      ssl_options = verify_ssl ? {} : { verify: false }
+
+      @conn = Faraday.new(url: @base_url, ssl: ssl_options) do |f|
         f.request :multipart
         f.request :json
         f.response :json
@@ -27,203 +143,238 @@ module WOWSQL
       @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
+    # ── Buckets ──────────────────────────────────────────────────
+
+    # Create a new storage bucket.
+    #
+    # @param name [String] Bucket name
+    # @param public [Boolean] Whether the bucket is public
+    # @param file_size_limit [Integer, nil] Max file size in bytes
+    # @param allowed_mime_types [Array<String>, nil] Allowed MIME types
+    # @return [StorageBucket]
+    def create_bucket(name, public: false, file_size_limit: nil, allowed_mime_types: nil)
+      data = request('POST', "/api/v1/storage/projects/#{@project_slug}/buckets", nil, {
+        name: name,
+        public: public,
+        file_size_limit: file_size_limit,
+        allowed_mime_types: allowed_mime_types
+      })
+      StorageBucket.new(data)
+    end
+
+    # List all buckets in the project.
+    #
+    # @return [Array<StorageBucket>]
+    def list_buckets
+      data = request('GET', "/api/v1/storage/projects/#{@project_slug}/buckets", nil, nil)
+      Array(data).map { |b| StorageBucket.new(b) }
+    end
 
-      response = request('GET', "/api/v1/storage/s3/projects/#{@project_slug}/quota", nil, nil)
-      @quota_cache = response
-      response
+    # Get a specific bucket by name.
+    #
+    # @param name [String] Bucket name
+    # @return [StorageBucket]
+    def get_bucket(name)
+      data = request('GET', "/api/v1/storage/projects/#{@project_slug}/buckets/#{name}", nil, nil)
+      StorageBucket.new(data)
     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}")
+    # Update bucket settings.
+    #
+    # @param name [String] Bucket name
+    # @param options [Hash] Settings to update
+    # @return [StorageBucket]
+    def update_bucket(name, **options)
+      data = request('PATCH', "/api/v1/storage/projects/#{@project_slug}/buckets/#{name}", nil, options)
+      StorageBucket.new(data)
+    end
+
+    # Delete a bucket and all its files.
+    #
+    # @param name [String] Bucket name
+    # @return [Hash]
+    def delete_bucket(name)
+      request('DELETE', "/api/v1/storage/projects/#{@project_slug}/buckets/#{name}", nil, nil)
+    end
+
+    # ── Files ────────────────────────────────────────────────────
+
+    # Upload a file to a bucket.
+    #
+    # @param bucket_name [String] Target bucket
+    # @param file_data [IO] File-like object (opened in binary mode)
+    # @param path [String, nil] File path within bucket
+    # @param file_name [String, nil] Override filename
+    # @return [StorageFile]
+    def upload(bucket_name, file_data, path: nil, file_name: nil)
+      content = file_data.respond_to?(:read) ? file_data.read : file_data
+      name = file_name || (file_data.respond_to?(:path) ? File.basename(file_data.path) : nil) || path || 'file'
+      name = name.split('/').last if name.include?('/')
+
+      folder = ''
+      if path && path.include?('/')
+        folder = path.rpartition('/').first
       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
+      params = {}
+      params['folder'] = folder unless folder.empty?
+
+      upload_io = Faraday::Multipart::FilePart.new(
+        StringIO.new(content.is_a?(String) ? content : content.to_s),
+        'application/octet-stream',
+        name
+      )
+
+      response = @conn.post("/api/v1/storage/projects/#{@project_slug}/buckets/#{bucket_name}/files") do |req|
+        req.params = params unless params.empty?
+        req.body = { file: upload_io }
       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
 
-        if response.status >= 400
-          handle_error(response)
-        end
+      StorageFile.new(response.body)
+    rescue Faraday::Error => e
+      raise StorageError.new("Upload failed: #{e.message}")
+    end
 
-        @quota_cache = nil # Refresh quota cache
-        response.body
-      rescue Faraday::Error => e
-        raise StorageException.new("Upload failed: #{e.message}")
+    # Upload a file from a local filesystem path.
+    #
+    # @param file_path [String] Path to local file
+    # @param bucket_name [String] Target bucket
+    # @param path [String, nil] File path within bucket
+    # @return [StorageFile]
+    def upload_from_path(file_path, bucket_name: 'default', path: nil)
+      raise StorageError.new("File not found: #{file_path}") unless File.exist?(file_path)
+
+      file_name = File.basename(file_path)
+      File.open(file_path, 'rb') do |f|
+        upload(bucket_name, f, path: path || file_name, file_name: file_name)
       end
     end
 
-    # List files in S3 bucket.
-    # 
+    # List files in a bucket.
+    #
+    # @param bucket_name [String] Bucket name
     # @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]
+    # @param limit [Integer] Maximum files to return
+    # @param offset [Integer] Offset for pagination
+    # @return [Array<StorageFile>]
+    def list_files(bucket_name, prefix: nil, limit: 100, offset: 0)
+      params = { 'limit' => limit, 'offset' => offset }
+      params['prefix'] = prefix if prefix
+
+      data = request('GET', "/api/v1/storage/projects/#{@project_slug}/buckets/#{bucket_name}/files", params, nil)
+      items = data.is_a?(Array) ? data : (data['files'] || data['data'] || [])
+      items.map { |f| StorageFile.new(f) }
+    end
+
+    # Download a file and return its binary contents.
+    #
+    # @param bucket_name [String] Bucket name
+    # @param file_path [String] File path within bucket
+    # @return [String] Binary file contents
+    def download(bucket_name, file_path)
+      url = "/api/v1/storage/projects/#{@project_slug}/files/#{bucket_name}/#{file_path}"
+
+      response = @conn.get(url)
+      if response.status >= 400
+        handle_error(response)
+      end
+      response.body
+    rescue Faraday::Error => e
+      raise StorageError.new("Download failed: #{e.message}")
+    end
+
+    # Download a file and save it to a local path.
+    #
+    # @param bucket_name [String] Bucket name
+    # @param file_path [String] File path within bucket
+    # @param local_path [String] Local destination path
+    # @return [String] The local path
+    def download_to_file(bucket_name, file_path, local_path)
+      content = download(bucket_name, file_path)
+      dir = File.dirname(local_path)
+      FileUtils.mkdir_p(dir) unless dir == '.'
+      File.open(local_path, 'wb') { |f| f.write(content) }
+      local_path
+    end
+
+    # Delete a file from a bucket.
+    #
+    # @param bucket_name [String] Bucket name
+    # @param file_path [String] File path within bucket
+    # @return [Hash]
+    def delete_file(bucket_name, file_path)
+      request('DELETE', "/api/v1/storage/projects/#{@project_slug}/files/#{bucket_name}/#{file_path}", nil, nil)
+    end
+
+    # ── Utilities ────────────────────────────────────────────────
+
+    # Get the public URL for a file in a public bucket (no auth required).
+    #
+    # @param bucket_name [String] Bucket name
+    # @param file_path [String] File path within bucket
+    # @return [String]
+    def get_public_url(bucket_name, file_path)
+      "#{@base_url}/api/v1/storage/projects/#{@project_slug}/files/#{bucket_name}/#{file_path}"
+    end
+
+    # Get storage statistics for the project.
+    #
+    # @return [StorageQuota]
+    def get_stats
+      data = request('GET', "/api/v1/storage/projects/#{@project_slug}/stats", nil, nil)
+      StorageQuota.new(data)
+    end
+
+    # Get storage quota (alias for get_stats).
+    #
+    # @return [StorageQuota]
+    def get_quota(force_refresh: false)
+      get_stats
+    end
+
+    # ── Lifecycle ────────────────────────────────────────────────
+
+    # Close the HTTP connection.
+    def close
+      @conn.close if @conn.respond_to?(:close)
     end
 
+    def to_s
+      "WOWSQLStorage(project=#{@project_slug.inspect})"
+    end
+    alias inspect to_s
+
     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 = @conn.public_send(method.downcase, path) do |req|
+        req.params = params if params
+        req.body = json if json
+        req.headers['Content-Type'] = 'application/json' if json
+      end
 
-        response.body
-      rescue Faraday::Error => e
-        raise StorageException.new("Request failed: #{e.message}")
+      if response.status >= 400
+        handle_error(response)
       end
+
+      response.body
+    rescue Faraday::Error => e
+      raise StorageError.new("Request failed: #{e.message}")
     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)
+        raise StorageLimitExceededError.new(error_msg, 413, error_data)
       end
 
-      raise StorageException.new(error_msg, response.status, error_data)
+      raise StorageError.new(error_msg, response.status, error_data)
     end
   end
 end
-