supabase-rb 2.0.0

data/lib/supabase/realtime/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Realtime
+    VERSION = "0.1.0"
+  end
+end

data/lib/supabase/realtime.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "realtime/version"
+require_relative "realtime/errors"
+require_relative "realtime/types"
+require_relative "realtime/transformers"
+require_relative "realtime/message"
+require_relative "realtime/presence"
+require_relative "realtime/push"
+require_relative "realtime/socket"
+require_relative "realtime/channel"
+require_relative "realtime/client"
+require_relative "realtime/test_socket"
+
+module Supabase
+  module Realtime
+  end
+end

data/lib/supabase/storage/README.md

@@ -0,0 +1,108 @@
+# `supabase-storage`
+
+Ruby client for [Supabase Storage](https://supabase.com/docs/guides/storage).
+Bucket management, file upload/download, signed URLs, plus the Iceberg
+(`analytics`) and vector bucket APIs. Mirrors the public surface of
+[`storage3`](https://github.com/supabase/supabase-py/tree/main/src/storage)
+in Python.
+
+- Source: [github.com/supabase-rb/client](https://github.com/supabase-rb/client)
+
+## Installation
+
+```ruby
+gem "supabase-storage"
+```
+
+Then `bundle install`. (Requires Ruby >= 3.0.)
+
+## Usage
+
+```ruby
+require "supabase/storage"
+
+storage = Supabase::Storage::Client.new(
+  base_url: "https://your-project.supabase.co/storage/v1",
+  headers:  { "apikey" => key, "Authorization" => "Bearer #{token}" }
+)
+```
+
+### Bucket management
+
+```ruby
+storage.create_bucket("avatars", public: true)
+storage.list_buckets
+storage.get_bucket("avatars")
+storage.update_bucket("avatars", public: false)
+storage.empty_bucket("avatars")
+storage.delete_bucket("avatars")
+```
+
+### File operations
+
+Scoped to one bucket via `.from`:
+
+```ruby
+bucket = storage.from("avatars")
+bucket.upload("user1.png", File.binread("user1.png"), content_type: "image/png")
+bucket.download("user1.png")    # => bytes
+bucket.list("folder/")
+bucket.list_v2(prefix: "folder/", limit: 50, cursor: "abc", with_delimiter: true)
+bucket.remove(["user1.png"])
+bucket.move("user1.png", "archive/user1.png")
+bucket.copy("user1.png", "backups/user1.png")
+bucket.exists?("user1.png")
+```
+
+Upload accepts `String` (raw bytes), any `IO`, `StringIO`, or `Pathname`.
+Multipart encoding is handled by `faraday-multipart`. Metadata Hashes are
+base64-encoded into the `x-metadata` header automatically.
+
+### Signed URLs
+
+```ruby
+bucket.create_signed_url("user1.png", expires_in: 3600)
+bucket.create_signed_urls(["user1.png", "user2.png"], expires_in: 3600)
+bucket.get_public_url("user1.png")
+
+# Signed upload URL — so a browser can upload directly to Storage
+signed = bucket.create_signed_upload_url("user1.png")
+bucket.upload_to_signed_url("user1.png", token: signed.token, file: bytes)
+```
+
+### Analytics (Iceberg) buckets
+
+```ruby
+storage.analytics.create("warehouse")
+storage.analytics.list
+storage.analytics.delete("warehouse")
+cfg = storage.analytics.catalog("warehouse",
+                                access_key_id: "AKIA", secret_access_key: "...")
+```
+
+### Vector buckets
+
+```ruby
+storage.vectors.create_bucket("embeddings")
+storage.vectors.bucket("embeddings").create_index(
+  index_name: "docs", dimension: 1536, distance_metric: "cosine"
+)
+storage.vectors.bucket("embeddings").index("docs").put(records)
+storage.vectors.bucket("embeddings").index("docs").query(vector, top_k: 10)
+```
+
+## Async variant
+
+```ruby
+require "supabase/storage/async"
+
+async = Supabase::Storage::Async::Client.new(
+  base_url: ENV["SUPABASE_URL"] + "/storage/v1",
+  headers:  { "apikey" => key, "Authorization" => "Bearer #{token}" }
+)
+
+Async do
+  bucket = async.from("avatars")
+  data   = bucket.download("user1.png")
+end
+```

data/lib/supabase/storage/analytics.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "request"
+require_relative "types"
+
+module Supabase
+  module Storage
+    # Analytics (iceberg) bucket management. Mirrors storage3's
+    # `SyncStorageAnalyticsClient` — talks to `{storage_url}/iceberg/bucket`.
+    #
+    #   client.analytics.create("my-iceberg")
+    #   client.analytics.list(limit: 50, sort_column: "name", sort_order: "asc")
+    #   client.analytics.delete("my-iceberg")
+    class AnalyticsClient
+      include Request
+
+      # @param session  [Faraday::Connection]
+      # @param base_url [String] storage REST root (".../storage/v1/")
+      # @param headers  [Hash]
+      def initialize(session, base_url, headers)
+        @session  = session
+        normalized = base_url.end_with?("/") ? base_url : "#{base_url}/"
+        @base_url = "#{normalized}iceberg/"
+        @headers  = headers
+      end
+
+      def create(bucket_name)
+        body = _request(:post, ["bucket"], json: { "name" => bucket_name })
+        Types::AnalyticsBucket.from_hash(body)
+      end
+
+      # Mirrors py's optional sort/search/pagination params. Nil values are
+      # dropped server-side; we also drop them client-side so the URL stays clean.
+      def list(limit: nil, offset: nil, sort_column: nil, sort_order: nil, search: nil)
+        params = { "limit" => limit, "offset" => offset,
+                   "sort_column" => sort_column, "sort_order" => sort_order,
+                   "search" => search }.compact
+        body = _request(:get, ["bucket"], query: params.empty? ? nil : params)
+        Array(body).map { |b| Types::AnalyticsBucket.from_hash(b) }
+      end
+
+      def delete(bucket_name)
+        body = _request(:delete, ["bucket", bucket_name])
+        Types::AnalyticsBucketDeleteResponse.from_hash(body)
+      end
+
+      # Python returns a `pyiceberg.RestCatalog`. There is no equivalent Iceberg
+      # client in the Ruby ecosystem, so we return the catalog configuration as
+      # a plain Hash that a downstream iceberg-ruby (when one exists) can consume.
+      # Keeping the public method present mirrors the API surface.
+      def catalog(catalog_name, access_key_id:, secret_access_key:)
+        service_key = @headers["apiKey"]
+        raise Errors::StorageApiError.new("apiKey must be passed in the headers.") if service_key.to_s.empty?
+
+        s3_endpoint = @base_url.sub(%r{iceberg/?\z}, "s3")
+        {
+          "name"                       => catalog_name,
+          "warehouse"                  => catalog_name,
+          "uri"                        => @base_url,
+          "token"                      => service_key,
+          "s3.endpoint"                => s3_endpoint,
+          "s3.access-key-id"           => access_key_id,
+          "s3.secret-access-key"       => secret_access_key,
+          "s3.force-virtual-addressing" => "False"
+        }
+      end
+    end
+  end
+end

data/lib/supabase/storage/async/client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "async/http/faraday"
+require_relative "../client"
+
+module Supabase
+  module Storage
+    module Async
+      # Async counterpart to {Supabase::Storage::Client}.
+      #
+      # Inherits the full public surface (list_buckets, get_bucket, create_bucket,
+      # update_bucket, empty_bucket, delete_bucket, from/bucket → FileApi) and
+      # rewires only the Faraday adapter to async-http-faraday so HTTP I/O yields
+      # back to the {::Async} reactor instead of blocking the thread.
+      #
+      # BucketApi and FileApi are transport-agnostic — they speak to whatever
+      # Faraday connection the client hands them, so neither has an async twin.
+      #
+      # Call sites must run inside an `Async do ... end` block; outside one, the
+      # adapter still works but loses the concurrency win.
+      #
+      #   require "supabase/storage/async"
+      #   require "async"
+      #
+      #   storage = Supabase::Storage::Async::Client.new(
+      #     base_url: "https://project.supabase.co/storage/v1",
+      #     headers:  { "apikey" => key }
+      #   )
+      #
+      #   Async do |task|
+      #     uploads = files.map do |f|
+      #       task.async { storage.from("avatars").upload(f.name, f.bytes) }
+      #     end
+      #     uploads.map(&:wait)
+      #   end
+      class Client < Supabase::Storage::Client
+        private
+
+        def build_session(base_url)
+          Faraday.new(url: base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+            f.request :multipart
+            if @timeout
+              f.options.timeout = @timeout
+              f.options.open_timeout = @timeout
+            end
+            f.adapter :async_http
+          end
+        end
+      end
+    end
+  end
+end

data/lib/supabase/storage/async.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Convenience requirer for the async tree, mirroring lib/supabase/postgrest/async.rb.
+# Plain `require "supabase/storage"` stays free of async-http-faraday so sync-only
+# consumers don't pay for the fiber stack.
+
+require_relative "../storage"
+require_relative "async/client"

data/lib/supabase/storage/bucket_api.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "request"
+require_relative "types"
+require_relative "utils"
+
+module Supabase
+  module Storage
+    # The bucket-management half of the storage client — list / get / create / update /
+    # empty / delete on bucket records. Mirrors storage3's SyncStorageBucketAPI.
+    #
+    # {Client} inherits from this; callers don't construct BucketApi directly.
+    class BucketApi
+      include Request
+
+      # @param session  [Faraday::Connection]
+      # @param base_url [String] storage REST endpoint, e.g. "https://x.supabase.co/storage/v1/"
+      # @param headers  [Hash] static request headers (apikey, Authorization, etc.)
+      def initialize(session, base_url, headers)
+        @session  = session
+        @base_url = base_url.end_with?("/") ? base_url : "#{base_url}/"
+        @headers  = headers
+      end
+
+      def list_buckets
+        body = _request(:get, ["bucket"])
+        Array(body).map { |b| Types::Bucket.from_hash(b) }
+      end
+
+      def get_bucket(id)
+        Types::Bucket.from_hash(_request(:get, ["bucket", id]))
+      end
+
+      # @param id [String]
+      # @param name [String, nil] defaults to id
+      # @param public [Boolean, nil]
+      # @param file_size_limit [Integer, nil]
+      # @param allowed_mime_types [Array<String>, nil]
+      # @return [Hash] the raw response body
+      def create_bucket(id, name: nil, public: nil, file_size_limit: nil, allowed_mime_types: nil)
+        json = { "id" => id, "name" => name || id }
+        json["public"]             = public             unless public.nil?
+        json["file_size_limit"]    = file_size_limit    unless file_size_limit.nil?
+        json["allowed_mime_types"] = allowed_mime_types unless allowed_mime_types.nil?
+        _request(:post, ["bucket"], json: json)
+      end
+
+      def update_bucket(id, public: nil, file_size_limit: nil, allowed_mime_types: nil)
+        json = { "id" => id, "name" => id }
+        json["public"]             = public             unless public.nil?
+        json["file_size_limit"]    = file_size_limit    unless file_size_limit.nil?
+        json["allowed_mime_types"] = allowed_mime_types unless allowed_mime_types.nil?
+        _request(:put, ["bucket", id], json: json)
+      end
+
+      def empty_bucket(id)
+        _request(:post, ["bucket", id, "empty"], json: {})
+      end
+
+      def delete_bucket(id)
+        _request(:delete, ["bucket", id], json: {})
+      end
+    end
+  end
+end

data/lib/supabase/storage/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+
+require_relative "bucket_api"
+require_relative "file_api"
+require_relative "analytics"
+require_relative "vectors"
+require_relative "version"
+
+module Supabase
+  module Storage
+    # Sync Storage client. Constructed once per project; reused across requests.
+    #
+    #   client = Supabase::Storage::Client.new(
+    #     base_url: "https://project.supabase.co/storage/v1",
+    #     headers:  { "apikey" => key, "Authorization" => "Bearer #{token}" }
+    #   )
+    #
+    #   client.list_buckets               # bucket-management surface
+    #   client.from("avatars").upload(...) # file-level surface, scoped to one bucket
+    class Client < BucketApi
+      attr_reader :base_url, :headers
+
+      # @param base_url [String] storage REST endpoint (e.g. ".../storage/v1")
+      # @param headers  [Hash] static request headers (apikey, Authorization)
+      # @param http_client [Faraday::Connection, nil] inject a pre-built Faraday for tests
+      # @param verify [Boolean] TLS cert verification
+      # @param proxy [String, nil]
+      # @param timeout [Numeric, nil]
+      def initialize(base_url:, headers: {}, http_client: nil, verify: true, proxy: nil, timeout: nil)
+        @verify  = verify
+        @proxy   = proxy
+        @timeout = timeout
+        @http_client = http_client
+        normalized = base_url.to_s
+        normalized = "#{normalized}/" unless normalized.end_with?("/")
+
+        default_headers = {
+          "X-Client-Info" => "supabase-rb/storage-rb v#{VERSION}"
+        }.merge(headers)
+
+        super(http_client || build_session(normalized), normalized, default_headers)
+      end
+
+      # Return a {FileApi} scoped to the given bucket.
+      def from(bucket_id)
+        FileApi.new(bucket_id, @base_url, @headers, @session)
+      end
+
+      alias bucket from
+
+      # Iceberg / analytics bucket management. Mirrors storage3's
+      # `SyncStorageClient#analytics`.
+      def analytics
+        @analytics ||= AnalyticsClient.new(@session, @base_url, @headers)
+      end
+
+      # Vector bucket / index / record management. Mirrors storage3's
+      # `SyncStorageClient#vectors`.
+      def vectors
+        @vectors ||= VectorsClient.new(@session, @base_url, @headers)
+      end
+
+      private
+
+      def build_session(base_url)
+        Faraday.new(url: base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+          f.request :multipart
+          if @timeout
+            f.options.timeout = @timeout
+            f.options.open_timeout = @timeout
+          end
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/supabase/storage/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Storage
+    module Errors
+      # Base class for any failure raised by the storage gem.
+      class StorageError < StandardError; end
+
+      # Raised when the Storage REST API returns a non-2xx response.
+      # Mirrors supabase-py's StorageApiError contract — exposes :message, :code (the
+      # API's `error` field, e.g. "InvalidKey"), and :status (HTTP status).
+      class StorageApiError < StorageError
+        attr_reader :code, :status
+
+        def initialize(message, code: nil, status: nil)
+          @code = code
+          @status = status
+          super(message.to_s)
+        end
+
+        def to_h
+          { "name" => "StorageApiError", "message" => message, "code" => @code, "status" => @status }
+        end
+      end
+
+      # Raised by the vectors client for client-side validation (e.g. batch size
+      # bounds). Mirrors storage3's VectorBucketException, which intentionally
+      # does NOT inherit from StorageError.
+      class VectorBucketException < StandardError; end
+    end
+  end
+end