supabase-rb 2.0.0

data/lib/supabase/storage/file_api.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "pathname"
+require "uri"
+
+require_relative "request"
+require_relative "types"
+require_relative "utils"
+
+module Supabase
+  module Storage
+    # All file-level operations scoped to one bucket — upload / download / list /
+    # remove / move / copy / info / exists, plus signed/public URL helpers.
+    # Mirrors storage3's SyncBucketActionsMixin + SyncBucketProxy.
+    #
+    # Constructed via {Client#from(bucket_id)}.
+    class FileApi
+      include Request
+
+      attr_reader :id
+
+      def initialize(id, base_url, headers, session)
+        @id       = id
+        @base_url = base_url.end_with?("/") ? base_url : "#{base_url}/"
+        @headers  = headers
+        @session  = session
+      end
+
+      # ----- Upload -----
+
+      # @param path [String] destination path within the bucket (e.g. "folder/avatar.png")
+      # @param file [String, IO, Pathname] bytes / file-like object / path on disk
+      # @param content_type [String, nil]
+      # @param cache_control [String, Integer, nil] becomes "max-age=<n>"
+      # @param upsert [Boolean]
+      # @param metadata [Hash, nil] base64-encoded into the x-metadata header
+      # @param headers [Hash, nil] extra HTTP headers to send
+      # @return [Types::UploadResponse]
+      def upload(path, file, content_type: nil, cache_control: nil, upsert: false, metadata: nil, headers: nil)
+        upload_or_update(:post, path, file,
+                         content_type: content_type, cache_control: cache_control,
+                         upsert: upsert, metadata: metadata, headers: headers)
+      end
+
+      def update(path, file, content_type: nil, cache_control: nil, metadata: nil, headers: nil)
+        # Per Python: PUT never sends x-upsert.
+        upload_or_update(:put, path, file,
+                         content_type: content_type, cache_control: cache_control,
+                         upsert: false, metadata: metadata, headers: headers, omit_upsert: true)
+      end
+
+      # ----- Download -----
+
+      def download(path)
+        parts = Utils.relative_path_to_parts(path)
+        response = _request(:get, ["object", @id, *parts], raw_response: true)
+        response.body
+      end
+
+      # ----- List -----
+
+      # @param prefix [String, nil] folder path to list under
+      # @param limit  [Integer]
+      # @param offset [Integer]
+      # @param sort_by [Hash] {column:, order:}
+      # @param search [String, nil]
+      def list(prefix = nil, limit: nil, offset: nil, sort_by: nil, search: nil)
+        body = Types::DEFAULT_SEARCH_OPTIONS.dup
+        body["limit"]  = limit  unless limit.nil?
+        body["offset"] = offset unless offset.nil?
+        body["sortBy"] = stringify_sort_by(sort_by) if sort_by
+        body["search"] = search unless search.nil?
+        body["prefix"] = prefix || ""
+        _request(:post, ["object", "list", @id], json: body, headers: { "Content-Type" => "application/json" })
+      end
+
+      # Cursor-paginated list. Mirrors storage3's list_v2 — only sends the keys the
+      # caller passed (no DEFAULT_SEARCH_OPTIONS merge).
+      # @param prefix [String, nil]
+      # @param limit  [Integer, nil]
+      # @param cursor [String, nil] opaque cursor returned by a previous call
+      # @param with_delimiter [Boolean, nil] if true, server groups by "/" into folders
+      # @param sort_by [Hash, nil] {column:, order:}
+      # @return [Types::SearchV2Result]
+      def list_v2(prefix: nil, limit: nil, cursor: nil, with_delimiter: nil, sort_by: nil)
+        body = {}
+        body["prefix"]         = prefix         unless prefix.nil?
+        body["limit"]          = limit          unless limit.nil?
+        body["cursor"]         = cursor         unless cursor.nil?
+        body["with_delimiter"] = with_delimiter unless with_delimiter.nil?
+        body["sortBy"]         = stringify_sort_by(sort_by) if sort_by
+        data = _request(:post, ["object", "list-v2", @id], json: body,
+                                                           headers: { "Content-Type" => "application/json" })
+        Types::SearchV2Result.from_hash(data)
+      end
+
+      # ----- Remove / Move / Copy / Info / Exists -----
+
+      def remove(paths)
+        _request(:delete, ["object", @id], json: { "prefixes" => Array(paths) })
+      end
+
+      def move(from_path, to_path)
+        _request(:post, ["object", "move"],
+                 json: { "bucketId" => @id, "sourceKey" => from_path, "destinationKey" => to_path })
+      end
+
+      def copy(from_path, to_path)
+        _request(:post, ["object", "copy"],
+                 json: { "bucketId" => @id, "sourceKey" => from_path, "destinationKey" => to_path })
+      end
+
+      def info(path)
+        parts = Utils.relative_path_to_parts(path)
+        _request(:get, ["object", "info", @id, *parts])
+      end
+
+      def exists?(path)
+        parts = Utils.relative_path_to_parts(path)
+        response = _request(:head, ["object", @id, *parts], raw_response: true)
+        response.status == 200
+      rescue Errors::StorageApiError
+        false
+      end
+
+      # ----- Signed URLs -----
+
+      # @param expires_in [Integer] seconds until the URL expires
+      # @param download [Boolean, String, nil] `true` to force browser download with the
+      #   original filename, a String to override the filename, or nil to leave inline
+      # @return [Hash] { "signedURL" => "...", "signedUrl" => "..." }
+      def create_signed_url(path, expires_in:, download: nil, transform: nil)
+        json = { "expiresIn" => expires_in.to_s }
+        download_query = {}
+        if download
+          json["download"] = download
+          download_query["download"] = download == true ? "" : download
+        end
+        json["transform"] = transform if transform
+
+        parts = Utils.relative_path_to_parts(path)
+        body  = _request(:post, ["object", "sign", @id, *parts], json: json)
+        wrap_signed_url(body["signedURL"] || body["signedUrl"], download_query)
+      end
+
+      def create_signed_urls(paths, expires_in:, download: nil)
+        json = { "paths" => Array(paths), "expiresIn" => expires_in.to_s }
+        download_query = {}
+        if download
+          json["download"] = download
+          download_query["download"] = download == true ? "" : download
+        end
+
+        items = _request(:post, ["object", "sign", @id], json: json)
+        Array(items).map do |item|
+          wrapped = wrap_signed_url(item["signedURL"] || item["signedUrl"], download_query)
+          {
+            "error"     => item["error"],
+            "path"      => item["path"],
+            "signedURL" => wrapped["signedURL"],
+            "signedUrl" => wrapped["signedURL"]
+          }
+        end
+      end
+
+      def get_public_url(path, download: nil, transform: nil)
+        download_query = {}
+        if download
+          download_query["download"] = download == true ? "" : download
+        end
+
+        render_path = transform ? %w[render image] : %w[object]
+        transform_query = transform ? transform.transform_keys(&:to_s).transform_values(&:to_s) : {}
+        query = download_query.merge(transform_query)
+
+        parts = Utils.relative_path_to_parts(path)
+        Utils.join_url(@base_url, [*render_path, "public", @id, *parts], query)
+      end
+
+      def create_signed_upload_url(path, upsert: nil)
+        headers = upsert.nil? ? {} : { "x-upsert" => upsert.to_s }
+        parts   = Utils.relative_path_to_parts(path)
+        body    = _request(:post, ["object", "upload", "sign", @id, *parts], headers: headers)
+
+        signed_url = "#{@base_url.chomp('/')}#{body['url']}"
+        token = URI.decode_www_form(URI.parse(signed_url).query.to_s).to_h["token"]
+        raise Errors::StorageError, "No token sent by the API" if token.nil? || token.empty?
+
+        Types::SignedUploadURL.new(signed_url: signed_url, token: token, path: path)
+      end
+
+      def upload_to_signed_url(path, token:, file:, content_type: nil, cache_control: nil, metadata: nil, headers: nil)
+        parts = Utils.relative_path_to_parts(path)
+        send_multipart(:put, ["object", "upload", "sign", @id, *parts],
+                       file: file, filename: parts.last, content_type: content_type,
+                       cache_control: cache_control, upsert: nil, metadata: metadata,
+                       extra_headers: headers, query: { "token" => token })
+      end
+
+      private
+
+      def upload_or_update(method, path, file, content_type:, cache_control:, upsert:, metadata:, headers:, omit_upsert: false)
+        parts = Utils.relative_path_to_parts(path)
+        send_multipart(method, ["object", @id, *parts],
+                       file: file, filename: parts.last,
+                       content_type: content_type, cache_control: cache_control,
+                       upsert: omit_upsert ? nil : upsert,
+                       metadata: metadata, extra_headers: headers)
+      end
+
+      def send_multipart(method, segments, file:, filename:, content_type:, cache_control:, upsert:, metadata:, extra_headers:, query: nil)
+        request_headers = {}
+        request_headers["cache-control"] = "max-age=#{cache_control}" if cache_control
+        request_headers["x-upsert"]      = upsert.to_s unless upsert.nil?
+        request_headers.merge!(extra_headers) if extra_headers
+
+        if metadata
+          metadata_json = JSON.generate(metadata)
+          request_headers["x-metadata"] = [metadata_json].pack("m0")
+        end
+
+        ctype = content_type || Types::DEFAULT_FILE_OPTIONS["content-type"]
+        upload_io = build_upload_io(file, filename, ctype)
+
+        url = Utils.join_url(@base_url, segments, query)
+        merged_headers = @headers.merge(request_headers)
+        # Faraday Multipart writes its own multipart Content-Type with boundary; drop ours
+        # so it can be regenerated.
+        merged_headers.delete("Content-Type")
+        merged_headers.delete("content-type")
+
+        form = { file: upload_io }
+        form[:cacheControl] = cache_control.to_s if cache_control
+        form[:metadata]     = JSON.generate(metadata) if metadata
+
+        # @session is built by Client with `f.request :multipart`, so handing it a
+        # Hash body lets the middleware multipart-encode and add the boundary header.
+        response = @session.run_request(method, url, form, merged_headers)
+        raise_for_status(response)
+        parsed = parse_json(response.body) || {}
+        Types::UploadResponse.from_hash(path: segments[2..].join("/"), key: parsed["Key"])
+      end
+
+      def build_upload_io(file, filename, content_type)
+        case file
+        when String
+          # Treat as raw bytes/text, not a path — call sites that want path semantics
+          # pass a Pathname or open the File themselves (matches storage3's bytes/IO contract).
+          Faraday::Multipart::FilePart.new(StringIO.new(file), content_type, filename)
+        when Pathname
+          Faraday::Multipart::FilePart.new(file.to_s, content_type, filename)
+        when IO, StringIO
+          Faraday::Multipart::FilePart.new(file, content_type, filename)
+        else
+          if file.respond_to?(:read)
+            Faraday::Multipart::FilePart.new(file, content_type, filename)
+          else
+            raise ArgumentError, "upload `file` must be a String, IO, or Pathname (got #{file.class})"
+          end
+        end
+      end
+
+      def wrap_signed_url(signed_url, download_query)
+        return { "signedURL" => nil, "signedUrl" => nil } if signed_url.nil?
+
+        # storage3 strips the leading "/" before joining; we mirror that.
+        cleaned = signed_url.sub(%r{^/}, "")
+        full = "#{@base_url.chomp('/')}/#{cleaned}"
+        full = "#{full}#{full.include?('?') ? '&' : '?'}#{URI.encode_www_form(download_query)}" unless download_query.empty?
+        { "signedURL" => full, "signedUrl" => full }
+      end
+
+      def stringify_sort_by(sort_by)
+        h = sort_by.transform_keys(&:to_s)
+        { "column" => h["column"], "order" => h["order"] }
+      end
+    end
+  end
+end

data/lib/supabase/storage/request.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+require_relative "errors"
+
+module Supabase
+  module Storage
+    # Mixin used by BucketApi and FileApi. Holds the shared HTTP wiring: build a Faraday
+    # request, raise StorageApiError on non-2xx, and parse JSON bodies.
+    #
+    # Including classes must expose @session (Faraday::Connection), @base_url (String
+    # ending in "/"), and @headers (Hash).
+    module Request
+      private
+
+      def _request(method, segments, json: nil, headers: nil, query: nil, body: nil, raw_response: false)
+        url = Utils.join_url(@base_url, segments, query)
+        merged_headers = @headers.merge(headers || {})
+
+        response = @session.run_request(method.to_s.downcase.to_sym, url, nil, merged_headers) do |req|
+          if json
+            req.headers["Content-Type"] ||= "application/json"
+            req.body = JSON.generate(json)
+          elsif body
+            req.body = body
+          end
+        end
+
+        raise_for_status(response)
+        return response if raw_response
+
+        parse_json(response.body)
+      end
+
+      def raise_for_status(response)
+        return if (200..299).include?(response.status)
+
+        parsed = parse_json_safe(response.body) || {}
+        raise Errors::StorageApiError.new(
+          parsed["message"] || "HTTP #{response.status}",
+          code:   parsed["error"]      || "InternalError",
+          status: parsed["statusCode"] || response.status
+        )
+      end
+
+      def parse_json(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+
+      def parse_json_safe(body)
+        JSON.parse(body) if body && !body.empty?
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/supabase/storage/types.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Storage
+    module Types
+      # Matches storage3's DEFAULT_SEARCH_OPTIONS — sent in the list() body when the
+      # caller doesn't override individual fields.
+      DEFAULT_SEARCH_OPTIONS = {
+        "limit"  => 100,
+        "offset" => 0,
+        "sortBy" => { "column" => "name", "order" => "asc" }
+      }.freeze
+
+      # Matches storage3's DEFAULT_FILE_OPTIONS — base headers/form fields for upload.
+      DEFAULT_FILE_OPTIONS = {
+        "cache-control" => "3600",
+        "content-type"  => "text/plain;charset=UTF-8",
+        "x-upsert"      => "false"
+      }.freeze
+
+      # Returned by list_buckets / get_bucket. Mirrors storage3's BaseBucket fields.
+      Bucket = Struct.new(
+        :id, :name, :owner, :public, :file_size_limit, :allowed_mime_types,
+        :created_at, :updated_at, :type,
+        keyword_init: true
+      ) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(
+            id:                 h["id"],
+            name:               h["name"],
+            owner:              h["owner"],
+            public:             h["public"],
+            file_size_limit:    h["file_size_limit"],
+            allowed_mime_types: h["allowed_mime_types"],
+            created_at:         h["created_at"],
+            updated_at:         h["updated_at"],
+            type:               h["type"]
+          )
+        end
+      end
+
+      # Returned by upload/update. Python exposes :path/:full_path/:fullPath; we keep
+      # both snake_case and camelCase aliases so call sites that follow Python docs work.
+      UploadResponse = Struct.new(:path, :full_path, :key, keyword_init: true) do
+        alias_method :fullPath, :full_path # rubocop:disable Naming/MethodName
+
+        def self.from_hash(path:, key:)
+          new(path: path, full_path: key, key: key)
+        end
+      end
+
+      # Returned by create_signed_upload_url.
+      SignedUploadURL = Struct.new(:signed_url, :token, :path, keyword_init: true) do
+        alias_method :signedUrl, :signed_url # rubocop:disable Naming/MethodName
+      end
+
+      # --- list_v2 -----------------------------------------------------------
+
+      SearchV2Object = Struct.new(:id, :name, :updated_at, :created_at, :metadata, :key, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(id: h["id"], name: h["name"],
+              updated_at: h["updated_at"], created_at: h["created_at"],
+              metadata: h["metadata"], key: h["key"])
+        end
+      end
+
+      SearchV2Folder = Struct.new(:key, :name, :created_at, :updated_at, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(key: h["key"], name: h["name"],
+              created_at: h["created_at"], updated_at: h["updated_at"])
+        end
+      end
+
+      SearchV2Result = Struct.new(:has_next, :folders, :objects, :next_cursor, keyword_init: true) do
+        alias_method :hasNext, :has_next       # rubocop:disable Naming/MethodName
+        alias_method :nextCursor, :next_cursor # rubocop:disable Naming/MethodName
+
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(
+            has_next:    h["hasNext"],
+            folders:     Array(h["folders"]).map { |f| SearchV2Folder.from_hash(f) },
+            objects:     Array(h["objects"]).map { |o| SearchV2Object.from_hash(o) },
+            next_cursor: h["nextCursor"]
+          )
+        end
+      end
+
+      # --- Analytics ---------------------------------------------------------
+
+      # Returned by analytics.create / analytics.list. Mirrors storage3's
+      # `AnalyticsBucket` pydantic model.
+      AnalyticsBucket = Struct.new(:name, :type, :format, :created_at, :updated_at, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(name: h["name"], type: h["type"], format: h["format"],
+              created_at: h["created_at"], updated_at: h["updated_at"])
+        end
+      end
+
+      AnalyticsBucketDeleteResponse = Struct.new(:message, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          new(message: hash.transform_keys(&:to_s)["message"])
+        end
+      end
+
+      # --- Vectors -----------------------------------------------------------
+
+      VectorBucketEncryptionConfiguration = Struct.new(:kms_key_arn, :sse_type, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(kms_key_arn: h["kmsKeyArn"], sse_type: h["sseType"])
+        end
+      end
+
+      VectorBucket = Struct.new(:vector_bucket_name, :creation_time, :encryption_configuration, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(
+            vector_bucket_name:       h["vectorBucketName"],
+            creation_time:            h["creationTime"],
+            encryption_configuration: VectorBucketEncryptionConfiguration.from_hash(h["encryptionConfiguration"])
+          )
+        end
+      end
+
+      GetVectorBucketResponse = Struct.new(:vector_bucket, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          new(vector_bucket: VectorBucket.from_hash(hash.transform_keys(&:to_s)["vectorBucket"]))
+        end
+      end
+
+      ListVectorBucketsResponse = Struct.new(:vector_buckets, :next_token, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          items = Array(h["vectorBuckets"]).map { |b| { name: b["vectorBucketName"] } }
+          new(vector_buckets: items, next_token: h["nextToken"])
+        end
+      end
+
+      VectorIndex = Struct.new(:index_name, :bucket_name, :data_type, :dimension,
+                               :distance_metric, :metadata, :creation_time, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(
+            index_name:       h["indexName"],
+            bucket_name:      h["vectorBucketName"],
+            data_type:        h["dataType"],
+            dimension:        h["dimension"],
+            distance_metric:  h["distanceMetric"],
+            metadata:         h["metadataConfiguration"],
+            creation_time:    h["creationTime"]
+          )
+        end
+      end
+
+      GetVectorIndexResponse = Struct.new(:index, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          new(index: VectorIndex.from_hash(hash.transform_keys(&:to_s)["index"]))
+        end
+      end
+
+      ListVectorIndexesResponse = Struct.new(:indexes, :next_token, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          indexes = Array(h["indexes"]).map { |i| { index_name: i["indexName"] } }
+          new(indexes: indexes, next_token: h["nextToken"])
+        end
+      end
+
+      # Matched/returned vector. Mirrors `VectorMatch` in storage3.
+      VectorMatch = Struct.new(:key, :data, :distance, :metadata, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(key: h["key"], data: h["data"], distance: h["distance"], metadata: h["metadata"])
+        end
+      end
+
+      GetVectorsResponse = Struct.new(:vectors, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          new(vectors: Array(hash.transform_keys(&:to_s)["vectors"]).map { |v| VectorMatch.from_hash(v) })
+        end
+      end
+
+      ListVectorsResponse = Struct.new(:vectors, :next_token, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          h = hash.transform_keys(&:to_s)
+          new(vectors: Array(h["vectors"]).map { |v| VectorMatch.from_hash(v) }, next_token: h["nextToken"])
+        end
+      end
+
+      QueryVectorsResponse = Struct.new(:vectors, keyword_init: true) do
+        def self.from_hash(hash)
+          return nil if hash.nil?
+
+          new(vectors: Array(hash.transform_keys(&:to_s)["vectors"]).map { |v| VectorMatch.from_hash(v) })
+        end
+      end
+    end
+  end
+end

data/lib/supabase/storage/utils.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Supabase
+  module Storage
+    module Utils
+      module_function
+
+      # Splits a relative storage path into its path segments, dropping a leading
+      # `/` if the caller supplied one. Mirrors storage3.utils.relative_path_to_parts.
+      #
+      #   relative_path_to_parts("folder/avatar.png") # => ["folder", "avatar.png"]
+      #   relative_path_to_parts("/folder/x.png")     # => ["folder", "x.png"]
+      def relative_path_to_parts(path)
+        path.to_s.split("/").reject(&:empty?)
+      end
+
+      # URL-encode each path segment so user-supplied filenames don't break the URL.
+      def encode_segments(parts)
+        parts.map { |p| URI.encode_www_form_component(p) }
+      end
+
+      # Join the (already-trailing-slashed) base URL with the given path segments and
+      # an optional query Hash. Used so `_request` never has to concat strings by hand.
+      def join_url(base_url, segments, query = nil)
+        path = encode_segments(segments).join("/")
+        url = "#{base_url.chomp('/')}/#{path}"
+        return url if query.nil? || query.empty?
+
+        "#{url}?#{URI.encode_www_form(query)}"
+      end
+    end
+  end
+end