wowsql-sdk 1.2.0 → 3.0.1

data/lib/wowsql/schema.rb

@@ -0,0 +1,250 @@
+require 'faraday'
+require 'json'
+require_relative 'exceptions'
+
+module WOWSQL
+  # Schema management client for PostgreSQL.
+  #
+  # Requires a SERVICE ROLE key (wowsql_service_...), not an anonymous key.
+  #
+  # @example
+  #   schema = WOWSQL::WOWSQLSchema.new(
+  #     "myproject",
+  #     "wowsql_service_..."
+  #   )
+  #   schema.create_table("users", [
+  #     { "name" => "id", "type" => "SERIAL", "auto_increment" => true },
+  #     { "name" => "email", "type" => "VARCHAR(255)", "unique" => true, "nullable" => false },
+  #     { "name" => "name", "type" => "VARCHAR(255)" },
+  #     { "name" => "metadata", "type" => "JSONB", "default" => "'{}'" },
+  #     { "name" => "created_at", "type" => "TIMESTAMPTZ", "default" => "CURRENT_TIMESTAMP" },
+  #   ], primary_key: "id", indexes: ["email"])
+  class WOWSQLSchema
+    attr_reader :base_url
+
+    # @param project_url [String] Project subdomain or full URL
+    # @param service_key [String] Service role key (wowsql_service_...)
+    # @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, service_key, base_domain: 'wowsql.com', secure: true,
+                   timeout: 30, verify_ssl: true)
+      if project_url.start_with?('http://') || project_url.start_with?('https://')
+        base = project_url.chomp('/')
+        base = base.split('/api').first if base.include?('/api')
+        @base_url = base
+      else
+        protocol = secure ? 'https' : 'http'
+        if project_url.include?(".#{base_domain}") || project_url.end_with?(base_domain)
+          @base_url = "#{protocol}://#{project_url}"
+        else
+          @base_url = "#{protocol}://#{project_url}.#{base_domain}"
+        end
+      end
+
+      @timeout = timeout
+
+      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 #{service_key}"
+      @conn.headers['Content-Type'] = 'application/json'
+    end
+
+    # ── Table operations ─────────────────────────────────────────
+
+    # Create a new table.
+    #
+    # @param table_name [String] Name of the table
+    # @param columns [Array<Hash>] Column definitions (name, type, auto_increment, unique, nullable, default)
+    # @param primary_key [String, nil] Primary key column name
+    # @param indexes [Array<String>, nil] Columns to create indexes on
+    # @return [Hash]
+    def create_table(table_name, columns, primary_key: nil, indexes: nil)
+      request('POST', '/api/v2/schema/tables', nil, {
+        table_name: table_name,
+        columns: columns,
+        primary_key: primary_key,
+        indexes: indexes
+      })
+    end
+
+    # Alter an existing table.
+    #
+    # Operations: add_column, drop_column, modify_column, rename_column
+    #
+    # @param table_name [String] Table name
+    # @param operation [String] Operation type
+    # @param column_name [String, nil] Column name
+    # @param column_type [String, nil] Column type
+    # @param new_column_name [String, nil] New column name (for rename)
+    # @param nullable [Boolean] Whether column is nullable
+    # @param default [String, nil] Default value
+    # @return [Hash]
+    def alter_table(table_name, operation, column_name: nil, column_type: nil,
+                    new_column_name: nil, nullable: true, default: nil)
+      request('PATCH', "/api/v2/schema/tables/#{table_name}", nil, {
+        table_name: table_name,
+        operation: operation,
+        column_name: column_name,
+        column_type: column_type,
+        new_column_name: new_column_name,
+        nullable: nullable,
+        default: default
+      })
+    end
+
+    # Drop a table. WARNING: This cannot be undone!
+    #
+    # @param table_name [String] Table to drop
+    # @param cascade [Boolean] Also drop dependent objects
+    # @return [Hash]
+    def drop_table(table_name, cascade: false)
+      request('DELETE', "/api/v2/schema/tables/#{table_name}", { 'cascade' => cascade }, nil)
+    end
+
+    # Execute raw DDL SQL.
+    #
+    # Only schema statements are allowed: CREATE TABLE, ALTER TABLE,
+    # DROP TABLE, CREATE INDEX, DROP INDEX, etc.
+    #
+    # @param sql [String] DDL SQL statement
+    # @return [Hash]
+    def execute_sql(sql)
+      request('POST', '/api/v2/schema/execute', nil, { sql: sql })
+    end
+
+    # ── Convenience methods ──────────────────────────────────────
+
+    # Add a column to an existing table.
+    #
+    # @param table_name [String] Table name
+    # @param column_name [String] Column name
+    # @param column_type [String] Column type
+    # @param nullable [Boolean] Whether column is nullable
+    # @param default [String, nil] Default value
+    # @return [Hash]
+    def add_column(table_name, column_name, column_type, nullable: true, default: nil)
+      alter_table(
+        table_name, 'add_column',
+        column_name: column_name,
+        column_type: column_type,
+        nullable: nullable,
+        default: default
+      )
+    end
+
+    # Drop a column from a table.
+    #
+    # @param table_name [String] Table name
+    # @param column_name [String] Column name
+    # @return [Hash]
+    def drop_column(table_name, column_name)
+      alter_table(table_name, 'drop_column', column_name: column_name)
+    end
+
+    # Rename a column.
+    #
+    # @param table_name [String] Table name
+    # @param old_name [String] Current column name
+    # @param new_name [String] New column name
+    # @return [Hash]
+    def rename_column(table_name, old_name, new_name)
+      alter_table(
+        table_name, 'rename_column',
+        column_name: old_name,
+        new_column_name: new_name
+      )
+    end
+
+    # Change column type, nullability, or default value.
+    #
+    # @param table_name [String] Table name
+    # @param column_name [String] Column name
+    # @param column_type [String, nil] New column type
+    # @param nullable [Boolean, nil] New nullability
+    # @param default [String, nil] New default value
+    # @return [Hash]
+    def modify_column(table_name, column_name, column_type: nil, nullable: nil, default: nil)
+      kwargs = { column_name: column_name }
+      kwargs[:column_type] = column_type unless column_type.nil?
+      kwargs[:nullable] = nullable unless nullable.nil?
+      kwargs[:default] = default unless default.nil?
+      alter_table(table_name, 'modify_column', **kwargs)
+    end
+
+    # Create an index.
+    #
+    # @param table_name [String] Table to index
+    # @param columns [String, Array<String>] Column(s)
+    # @param unique [Boolean] Create a UNIQUE index
+    # @param name [String, nil] Custom index name
+    # @param using [String, nil] Index method (btree, hash, gin, gist)
+    # @return [Hash]
+    def create_index(table_name, columns, unique: false, name: nil, using: nil)
+      cols = columns.is_a?(Array) ? columns : [columns]
+      idx_name = name || "idx_#{table_name}_#{cols.join('_')}"
+      unique_kw = unique ? 'UNIQUE ' : ''
+      using_kw = using ? " USING #{using}" : ''
+      col_list = cols.map { |c| "\"#{c}\"" }.join(', ')
+      sql = "CREATE #{unique_kw}INDEX IF NOT EXISTS \"#{idx_name}\" ON \"#{table_name}\"#{using_kw} (#{col_list})"
+      execute_sql(sql)
+    end
+
+    # List all tables via the v2 REST API.
+    #
+    # @return [Array<String>]
+    def list_tables
+      resp = request('GET', '/api/v2/tables', nil, nil)
+      resp['tables'] || []
+    end
+
+    # Get column-level schema information for a table.
+    #
+    # @param table_name [String] Table name
+    # @return [Hash]
+    def get_table_schema(table_name)
+      request('GET', "/api/v2/tables/#{table_name}/schema", nil, nil)
+    end
+
+    # Close the HTTP connection.
+    def close
+      @conn.close if @conn.respond_to?(:close)
+    end
+
+    private
+
+    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 == 403
+        raise SchemaPermissionError.new(
+          'Schema operations require a SERVICE ROLE key. ' \
+          'You are using an anonymous key which cannot modify database schema.',
+          403
+        )
+      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 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/storage.rb

@@ -0,0 +1,380 @@
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+require 'stringio'
+require 'uri'
+require 'fileutils'
+require_relative 'exceptions'
+
+module WOWSQL
+  # 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
+    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
+      @verify_ssl = verify_ssl
+
+      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
+        f.adapter Faraday.default_adapter
+        f.options.timeout = timeout
+      end
+
+      @conn.headers['Authorization'] = "Bearer #{api_key}"
+    end
+
+    # ── 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
+
+    # 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
+
+    # 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
+
+      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
+
+      if response.status >= 400
+        handle_error(response)
+      end
+
+      StorageFile.new(response.body)
+    rescue Faraday::Error => e
+      raise StorageError.new("Upload failed: #{e.message}")
+    end
+
+    # 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 a bucket.
+    #
+    # @param bucket_name [String] Bucket name
+    # @param prefix [String, nil] Filter by prefix/folder
+    # @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
+
+    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
+        req.headers['Content-Type'] = 'application/json' if json
+      end
+
+      if response.status >= 400
+        handle_error(response)
+      end
+
+      response.body
+    rescue Faraday::Error => e
+      raise StorageError.new("Request failed: #{e.message}")
+    end
+
+    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 StorageLimitExceededError.new(error_msg, 413, error_data)
+      end
+
+      raise StorageError.new(error_msg, response.status, error_data)
+    end
+  end
+end