supabase-rb 2.0.0

data/lib/supabase/client.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "auth"
+require_relative "postgrest"
+require_relative "storage"
+require_relative "functions"
+require_relative "realtime"
+
+module Supabase
+  # Top-level client that combines every sub-library behind one object, mirroring
+  # supabase-py's `supabase.create_client()`.
+  #
+  #   client = Supabase.create_client(
+  #     supabase_url: "https://project.supabase.co",
+  #     supabase_key: ENV["SUPABASE_ANON_KEY"]
+  #   )
+  #
+  #   client.auth.sign_in_with_password(email:, password:)
+  #   users = client.from("users").select("*").execute
+  #   client.storage.from("avatars").upload("a.png", bytes)
+  #   client.functions.invoke("hello-world", body: { name: "Ada" })
+  #   ch = client.realtime.channel("realtime:public:users")
+  #
+  # Sub-clients are built lazily and memoized. Pass `async: true` to swap in the
+  # async-http-faraday variants for Auth / Postgrest / Storage / Functions; the
+  # Realtime client is transport-agnostic and ships sync regardless (a real WS
+  # transport is wired in by the caller — see lib/supabase/realtime/socket.rb).
+  class Client
+    attr_reader :supabase_url, :supabase_key, :options, :headers
+
+    def initialize(supabase_url:, supabase_key:, options: {}, async: false)
+      # Use Supabase::SupabaseException once defined; fall back to ArgumentError
+      # during early require cycles. Matches supabase-py's contract.
+      err = defined?(Supabase::SupabaseException) ? Supabase::SupabaseException : ArgumentError
+      raise err, "supabase_url is required" if supabase_url.to_s.empty?
+      raise err, "supabase_key is required" if supabase_key.to_s.empty?
+      raise err, "Invalid URL" unless supabase_url.to_s.match?(%r{^https?://.+})
+
+      @supabase_url = supabase_url.to_s.chomp("/")
+      @supabase_key = supabase_key
+      @options      = options || {}
+      @async        = async
+
+      configured_headers =
+        if @options.is_a?(Supabase::ClientOptions)
+          @options.headers
+        else
+          @options[:global]&.dig(:headers) || @options.dig("global", "headers") || {}
+        end
+
+      @headers = {
+        "apikey"        => @supabase_key,
+        "Authorization" => "Bearer #{@supabase_key}"
+      }.merge(configured_headers || {})
+    end
+
+    def async?
+      @async
+    end
+
+    # --- Sub-clients ---------------------------------------------------------
+
+    def auth
+      @auth ||= auth_class.new(url: rest_url_for("auth/v1"), headers: @headers, **sub_options(:auth))
+    end
+
+    def storage
+      @storage ||= storage_class.new(base_url: rest_url_for("storage/v1"), headers: @headers,
+                                     **sub_options(:storage))
+    end
+
+    def functions
+      @functions ||= functions_class.new(base_url: rest_url_for("functions/v1"), headers: @headers,
+                                         **sub_options(:functions))
+    end
+
+    def realtime
+      @realtime ||= Realtime::Client.new(
+        url:    realtime_url,
+        params: { "apikey" => @supabase_key, "access_token" => @supabase_key },
+        **sub_options(:realtime)
+      )
+    end
+
+    # PostgREST is the only sub-library where the public API is reached via a
+    # bare method on the umbrella (`client.from('users')`) rather than a named
+    # accessor. We expose both for explicitness.
+    def postgrest
+      @postgrest ||= postgrest_class.new(base_url: rest_url_for("rest/v1"), headers: @headers,
+                                         **sub_options(:postgrest))
+    end
+
+    def from(table)
+      postgrest.from(table)
+    end
+
+    def rpc(func, params = {}, **opts)
+      postgrest.rpc(func, params, **opts)
+    end
+
+    def schema(name)
+      @postgrest = postgrest.schema(name)
+      self
+    end
+
+    # --- Shared auth context -------------------------------------------------
+
+    # Update the Authorization header used by every sub-client. Useful after
+    # auth.sign_in returns a fresh JWT — the apikey stays the same but the
+    # bearer token becomes the user's access token.
+    def set_auth(token)
+      @headers["Authorization"] = "Bearer #{token || @supabase_key}"
+      # Reset memoized sub-clients so they pick up the new header on next access.
+      # Realtime gets its own pathway (set_auth pushes access_token frames).
+      @auth      = nil
+      @storage   = nil
+      @functions = nil
+      @postgrest = nil
+      @realtime&.set_auth(token)
+      self
+    end
+
+    private
+
+    def auth_class
+      @async ? require_async_class("auth", "Async::Client") : Auth::Client
+    end
+
+    def postgrest_class
+      @async ? require_async_class("postgrest", "Async::Client") : Postgrest::Client
+    end
+
+    def storage_class
+      @async ? require_async_class("storage", "Async::Client") : Storage::Client
+    end
+
+    def functions_class
+      @async ? require_async_class("functions", "Async::Client") : Functions::Client
+    end
+
+    # Loads e.g. "supabase/postgrest/async" only when async: true so sync users
+    # never pull in async-http-faraday.
+    def require_async_class(sub, class_name)
+      require "supabase/#{sub}/async"
+      mod = const_get_from_string("Supabase::#{sub.capitalize}::#{class_name}")
+      mod
+    end
+
+    def const_get_from_string(path)
+      path.split("::").reduce(Object) { |m, name| m.const_get(name) }
+    end
+
+    def rest_url_for(suffix)
+      "#{@supabase_url}/#{suffix}"
+    end
+
+    # Realtime uses wss:// against the project host. The realtime path is /realtime/v1.
+    def realtime_url
+      uri = URI.parse(@supabase_url)
+      scheme = uri.scheme == "https" ? "wss" : "ws"
+      port = uri.port && uri.port != uri.default_port ? ":#{uri.port}" : ""
+      "#{scheme}://#{uri.host}#{port}/realtime/v1"
+    end
+
+    def sub_options(key)
+      return options_from_struct(key) if @options.is_a?(Supabase::ClientOptions)
+
+      (@options[key] || @options[key.to_s] || {}).transform_keys(&:to_sym)
+    end
+
+    # Translate a ClientOptions struct into the per-sub kwargs each sub-client
+    # accepts. We don't try to surface every field — only the ones the existing
+    # sub-clients actually take today.
+    def options_from_struct(key)
+      o = @options
+      case key
+      when :auth
+        { auto_refresh_token: o.auto_refresh_token, persist_session: o.persist_session,
+          storage: o.storage, flow_type: o.flow_type }.compact
+      when :postgrest
+        { schema: o.schema, timeout: o.postgrest_client_timeout, http_client: o.http_client }.compact
+      when :storage
+        { timeout: o.storage_client_timeout, http_client: o.http_client }.compact
+      when :functions
+        { timeout: o.function_client_timeout, http_client: o.http_client }.compact
+      when :realtime
+        o.realtime.is_a?(Hash) ? o.realtime.transform_keys(&:to_sym) : {}
+      else
+        {}
+      end
+    end
+  end
+
+  # Factory that matches supabase-py's `supabase.create_client()` signature.
+  def self.create_client(supabase_url:, supabase_key:, options: {}, async: false)
+    Client.new(supabase_url: supabase_url, supabase_key: supabase_key, options: options, async: async)
+  end
+end

data/lib/supabase/client_options.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+module Supabase
+  # Structured options passed to {Supabase.create_client} / {Supabase::Client}.
+  # Mirrors supabase-py's `SyncClientOptions` / `AsyncClientOptions`. The Ruby
+  # port uses one class because the sync/async split is decided at runtime via
+  # the `async:` flag on the umbrella client.
+  #
+  #   opts = Supabase::ClientOptions.new(
+  #     schema: "public",
+  #     headers: { "X-Tenant" => "acme" },
+  #     auto_refresh_token: true,
+  #     persist_session: true,
+  #     postgrest_client_timeout: 30,
+  #     storage_client_timeout: 20,
+  #     function_client_timeout: 10,
+  #     flow_type: "pkce"
+  #   )
+  #
+  #   Supabase.create_client(supabase_url: url, supabase_key: key, options: opts)
+  class ClientOptions
+    DEFAULT_POSTGREST_TIMEOUT = 120
+    DEFAULT_STORAGE_TIMEOUT   = 20
+    DEFAULT_FUNCTIONS_TIMEOUT = 60
+
+    DEFAULT_HEADERS = { "X-Client-Info" => "supabase-rb/#{Supabase::VERSION}" }.freeze
+
+    attr_accessor :schema, :headers, :auto_refresh_token, :persist_session,
+                  :realtime, :postgrest_client_timeout, :storage_client_timeout,
+                  :function_client_timeout, :flow_type, :storage, :http_client
+
+    def initialize(schema: "public",
+                   headers: nil,
+                   auto_refresh_token: true,
+                   persist_session: true,
+                   realtime: nil,
+                   postgrest_client_timeout: DEFAULT_POSTGREST_TIMEOUT,
+                   storage_client_timeout: DEFAULT_STORAGE_TIMEOUT,
+                   function_client_timeout: DEFAULT_FUNCTIONS_TIMEOUT,
+                   flow_type: "pkce",
+                   storage: nil,
+                   http_client: nil)
+      @schema                   = schema
+      @headers                  = DEFAULT_HEADERS.merge(headers || {})
+      @auto_refresh_token       = auto_refresh_token
+      @persist_session          = persist_session
+      @realtime                 = realtime
+      @postgrest_client_timeout = postgrest_client_timeout
+      @storage_client_timeout   = storage_client_timeout
+      @function_client_timeout  = function_client_timeout
+      @flow_type                = flow_type
+      @storage                  = storage
+      @http_client              = http_client
+    end
+
+    # Returns a new ClientOptions with the given fields overridden. Mirrors
+    # supabase-py's `replace()` — handy because dataclasses there are frozen
+    # at the field-level and we want the same "build then derive" ergonomics.
+    def replace(**overrides)
+      attrs = to_h.merge(overrides)
+      self.class.new(**attrs)
+    end
+
+    def to_h
+      {
+        schema:                   @schema,
+        headers:                  @headers,
+        auto_refresh_token:       @auto_refresh_token,
+        persist_session:          @persist_session,
+        realtime:                 @realtime,
+        postgrest_client_timeout: @postgrest_client_timeout,
+        storage_client_timeout:   @storage_client_timeout,
+        function_client_timeout:  @function_client_timeout,
+        flow_type:                @flow_type,
+        storage:                  @storage,
+        http_client:              @http_client
+      }
+    end
+  end
+end

data/lib/supabase/functions/README.md

@@ -0,0 +1,71 @@
+# `supabase-functions`
+
+Ruby client for [Supabase Edge Functions](https://supabase.com/docs/guides/functions).
+Per-call control over body, headers, HTTP method, region routing, and
+response parsing. Mirrors the public surface of
+[`supabase_functions`](https://github.com/supabase/supabase-py/tree/main/src/functions)
+in Python.
+
+- Source: [github.com/supabase-rb/client](https://github.com/supabase-rb/client)
+
+## Installation
+
+```ruby
+gem "supabase-functions"
+```
+
+Then `bundle install`. (Requires Ruby >= 3.0.)
+
+## Usage
+
+```ruby
+require "supabase/functions"
+
+functions = Supabase::Functions::Client.new(
+  base_url: "https://your-project.supabase.co/functions/v1",
+  headers:  { "Authorization" => "Bearer #{key}" }
+)
+
+# Simple invoke (POST + JSON body)
+response = functions.invoke("hello", body: { name: "Ada" })
+response.data    # => parsed JSON or raw bytes
+response.status
+response.headers
+```
+
+### Custom method / headers / query / region
+
+```ruby
+functions.invoke(
+  "ingest",
+  method:  "PUT",
+  headers: { "X-Trace-Id" => "abc" },
+  query:   { tenant: "x" },
+  region:  Supabase::Functions::Types::FunctionRegion::US_EAST_1,
+  body:    payload_hash
+)
+```
+
+`response.data` is auto-parsed when the response `Content-Type` is JSON,
+otherwise the raw body. Force parsing with `response_type: :json`.
+
+### Errors
+
+`FunctionsHttpError` is raised on a function-side error response.
+`FunctionsRelayError` is raised when the server's `x-relay-header` signals a
+relay failure.
+
+## Async variant
+
+```ruby
+require "supabase/functions/async"
+
+async = Supabase::Functions::Async::Client.new(
+  base_url: ENV["SUPABASE_URL"] + "/functions/v1",
+  headers:  { "Authorization" => "Bearer #{key}" }
+)
+
+Async do
+  response = async.invoke("hello", body: { name: "Ada" })
+end
+```

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "async/http/faraday"
+require_relative "../client"
+
+module Supabase
+  module Functions
+    module Async
+      # Async counterpart to {Supabase::Functions::Client}.
+      #
+      # Inherits the full public surface (invoke, set_auth) 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.
+      #
+      # Call sites must run inside an `Async do ... end` block; outside one, the
+      # adapter still works but loses the concurrency win.
+      #
+      #   require "supabase/functions/async"
+      #   require "async"
+      #
+      #   functions = Supabase::Functions::Async::Client.new(
+      #     base_url: "https://project.supabase.co/functions/v1",
+      #     headers:  { "Authorization" => "Bearer #{key}" }
+      #   )
+      #
+      #   Async do |task|
+      #     calls = function_names.map do |name|
+      #       task.async { functions.invoke(name, body: { id: 1 }) }
+      #     end
+      #     calls.map(&:wait)
+      #   end
+      class Client < Supabase::Functions::Client
+        private
+
+        def build_session
+          Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+            f.options.timeout = @timeout
+            f.options.open_timeout = @timeout
+            f.adapter :async_http
+          end
+        end
+      end
+    end
+  end
+end

data/lib/supabase/functions/async.rb

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

data/lib/supabase/functions/client.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "uri"
+
+require_relative "errors"
+require_relative "types"
+require_relative "version"
+
+module Supabase
+  module Functions
+    # Sync Edge Functions client. Constructed once per project; reused across invocations.
+    #
+    #   functions = Supabase::Functions::Client.new(
+    #     base_url: "https://project.supabase.co/functions/v1",
+    #     headers:  { "Authorization" => "Bearer #{key}" }
+    #   )
+    #
+    #   response = functions.invoke("hello-world", body: { name: "Ada" })
+    #   response.data    # => parsed JSON or raw bytes
+    #   response.status  # => 200
+    #   response.headers # => { "content-type" => "application/json", ... }
+    class Client
+      VALID_METHODS = %w[GET OPTIONS HEAD POST PUT PATCH DELETE].freeze
+
+      attr_reader :base_url, :headers
+
+      # @param base_url [String] full URL to the Edge Functions endpoint
+      # @param headers  [Hash] static headers attached to every invocation
+      # @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] per-request timeout (seconds), default 60
+      def initialize(base_url:, headers: {}, http_client: nil, verify: true, proxy: nil, timeout: nil)
+        raise ArgumentError, "base_url must be an http(s) URL" unless http_url?(base_url)
+
+        @base_url = base_url.chomp("/")
+        @verify   = verify
+        @proxy    = proxy
+        @timeout  = timeout || 60
+
+        @headers = {
+          "X-Client-Info" => "supabase-rb/functions-rb v#{VERSION}"
+        }.merge(headers)
+
+        @session = http_client || build_session
+      end
+
+      # Replace the Authorization header (e.g. when a user signs in / out).
+      def set_auth(token)
+        @headers["Authorization"] = "Bearer #{token}"
+      end
+
+      # Invoke an Edge Function by name.
+      #
+      # @param function_name [String]
+      # @param body [Hash, String, nil] JSON-encoded if Hash, sent as-is if String
+      # @param headers [Hash] per-invocation headers (merged over the client defaults)
+      # @param method [String, Symbol] HTTP method, defaults to "POST"
+      # @param region [String, nil] one of {Types::FunctionRegion}::ALL
+      # @param response_type [Symbol, String] :json to parse JSON, anything else returns raw bytes
+      # @param query [Hash, nil] extra query-string params
+      # @return [Types::Response]
+      def invoke(function_name, body: nil, headers: {}, method: "POST", region: nil, response_type: :text, query: nil)
+        validate_function_name!(function_name)
+
+        http_method = method.to_s.upcase
+        unless VALID_METHODS.include?(http_method)
+          raise ArgumentError, "method must be one of #{VALID_METHODS.join(', ')}"
+        end
+
+        merged_headers = @headers.merge(headers)
+        merged_query   = (query || {}).transform_keys(&:to_s)
+
+        if region && region != Types::FunctionRegion::ANY
+          merged_headers["x-region"] = region
+          merged_query["forceFunctionRegion"] = region
+        end
+
+        encoded_body =
+          case body
+          when nil
+            nil
+          when String
+            merged_headers["Content-Type"] ||= "text/plain"
+            body
+          when Hash, Array
+            merged_headers["Content-Type"] ||= "application/json"
+            JSON.generate(body)
+          else
+            raise ArgumentError, "body must be a String, Hash, Array, or nil (got #{body.class})"
+          end
+
+        response = @session.run_request(
+          http_method.downcase.to_sym,
+          "#{@base_url}/#{function_name}",
+          encoded_body,
+          merged_headers
+        ) do |req|
+          req.params.update(merged_query) unless merged_query.empty?
+        end
+
+        raise_for_relay!(response)
+        raise_for_status!(response)
+
+        Types::Response.new(
+          data:    parse_body(response, response_type),
+          status:  response.status,
+          headers: response.headers
+        )
+      end
+
+      private
+
+      def build_session
+        Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+          f.options.timeout = @timeout
+          f.options.open_timeout = @timeout
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def http_url?(url)
+        scheme = URI.parse(url.to_s).scheme
+        %w[http https].include?(scheme)
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def validate_function_name!(name)
+        return if name.is_a?(String) && !name.strip.empty?
+
+        raise ArgumentError, "function_name must be a non-empty String"
+      end
+
+      def raise_for_relay!(response)
+        # The relay layer signals its own errors via this response header (set to
+        # "true"). The function itself doesn't set this — only the relay.
+        relay = response.headers["x-relay-header"] || response.headers["X-Relay-Header"]
+        return unless relay == "true"
+
+        parsed = parse_json_safe(response.body) || {}
+        raise Errors::FunctionsRelayError.new(parsed["error"] || "Relay error", status: response.status)
+      end
+
+      def raise_for_status!(response)
+        return if (200..299).include?(response.status)
+
+        parsed = parse_json_safe(response.body) || {}
+        message = parsed["error"] || "An error occurred while requesting the edge function"
+        raise Errors::FunctionsHttpError.new(message, status: response.status)
+      end
+
+      def parse_body(response, response_type)
+        return response.body if response.body.nil? || response.body.empty?
+
+        if response_type.to_s == "json"
+          parse_json_safe(response.body) || response.body
+        else
+          # Auto-detect JSON: if the server says application/json, parse it.
+          content_type = response.headers["content-type"] || response.headers["Content-Type"] || ""
+          content_type.include?("application/json") ? (parse_json_safe(response.body) || response.body) : response.body
+        end
+      end
+
+      def parse_json_safe(body)
+        JSON.parse(body) if body && !body.empty?
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/supabase/functions/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Functions
+    module Errors
+      # Base class — rescue this to catch any Functions-API failure.
+      class FunctionsError < StandardError
+        attr_reader :name, :status
+
+        def initialize(message, name:, status:)
+          @name = name
+          @status = status
+          super(message.to_s)
+        end
+
+        def to_h
+          { "name" => @name, "message" => message, "status" => @status }
+        end
+      end
+
+      # Raised when the edge function returns a non-2xx HTTP response.
+      class FunctionsHttpError < FunctionsError
+        def initialize(message, status: nil)
+          super(message, name: "FunctionsHttpError", status: status || 400)
+        end
+      end
+
+      # Raised when the Supabase relay (the layer in front of the function) reports
+      # an error — distinguishable from a function-side error via the x-relay-header
+      # response header.
+      class FunctionsRelayError < FunctionsError
+        def initialize(message, status: nil)
+          super(message, name: "FunctionsRelayError", status: status || 400)
+        end
+      end
+    end
+  end
+end

data/lib/supabase/functions/types.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Functions
+    module Types
+      # Returned by Client#invoke. `data` is parsed JSON when response_type: :json
+      # (or auto-detected from a JSON Content-Type), otherwise the raw response body.
+      Response = Struct.new(:data, :status, :headers, keyword_init: true)
+
+      # Supabase Edge Function regions. Use FunctionRegion::US_EAST_1 etc., or pass
+      # the bare string ("us-east-1") to Client#invoke — both are accepted.
+      module FunctionRegion
+        ANY              = "any"
+        AP_NORTHEAST_1   = "ap-northeast-1"
+        AP_NORTHEAST_2   = "ap-northeast-2"
+        AP_SOUTH_1       = "ap-south-1"
+        AP_SOUTHEAST_1   = "ap-southeast-1"
+        AP_SOUTHEAST_2   = "ap-southeast-2"
+        CA_CENTRAL_1     = "ca-central-1"
+        EU_CENTRAL_1     = "eu-central-1"
+        EU_WEST_1        = "eu-west-1"
+        EU_WEST_2        = "eu-west-2"
+        EU_WEST_3        = "eu-west-3"
+        SA_EAST_1        = "sa-east-1"
+        US_EAST_1        = "us-east-1"
+        US_WEST_1        = "us-west-1"
+        US_WEST_2        = "us-west-2"
+
+        ALL = [
+          ANY, AP_NORTHEAST_1, AP_NORTHEAST_2, AP_SOUTH_1, AP_SOUTHEAST_1, AP_SOUTHEAST_2,
+          CA_CENTRAL_1, EU_CENTRAL_1, EU_WEST_1, EU_WEST_2, EU_WEST_3,
+          SA_EAST_1, US_EAST_1, US_WEST_1, US_WEST_2
+        ].freeze
+      end
+    end
+  end
+end

data/lib/supabase/functions/version.rb

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

data/lib/supabase/functions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "functions/version"
+require_relative "functions/errors"
+require_relative "functions/types"
+require_relative "functions/client"
+
+module Supabase
+  module Functions
+  end
+end