aha_builder_core 1.0.20 → 1.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04c418cb077b5736844ca605b1bb7e47dcc2782b9da7f4a54d68c1072837c278
-  data.tar.gz: 5a67d06975d93e91652cceef6d423fcd5aeb05392ceee206efff028245429768
+  metadata.gz: c2d2cf22937791f0b77aa3dec4abf17939b99877059b17f4a461423ddd34ce50
+  data.tar.gz: 7dc28c0a6703d842b2cd499d828fdc77fc0d63301cca1c0ccd9d77f92cafb347
 SHA512:
-  metadata.gz: 4328aebeeac2eb6c8418e41e4a80e1189c2a30056d5830b0838eb06dc492a7b72aeef7af82109588f5f2d8d8b932c8e279e3d31fdc2be05847a4b1b91487dcc0
-  data.tar.gz: af6a7898fb682ea7e23da60a29873871952ec7a753bf75eb1a73ac8083a4e329587328eab4a424648cc88f096a61dfc32d88ac1c98706a8b2c304bcf773b9c10
+  metadata.gz: b04a59fedd4924fa5ce10a2a3c6781cbb29607adaffa9ef2640f3af9c7842b28f6caae196ca5f9f70445d4aeffceeaebd91e89effef124b0ba11d3ddb1a7bc1c
+  data.tar.gz: 64f4f61aabc84bacb316f1aaeae4623087b83d5a941060fc2022a74f65d714a6633efd1c761e28f76339c3e7e7c20b4a159a65f0171073a4e8631a4e89aa9251

data/README.md

@@ -1,6 +1,10 @@
 # Aha Builder Core Client
 
-Ruby client for Aha! Builder core authentication services which provides login and signup using email/password, social logins (Google, Github, Microsoft), SAML SSO and password reset.
+Ruby client for Aha! Builder core which provides application services:
+
+* Authentication services for login and signup using email/password, social logins (Google, Github, Microsoft), SAML SSO and password reset.
+* Email sending API.
+* User guide content API.
 
 ## Installation
 
@@ -206,3 +210,20 @@ Each page hash contains:
 - `position` - Sort order (integer)
 - `children_count` - Number of child pages
 - `content_html` - HTML content (only in `load_page` response)
+
+## Email Sending
+
+Aha! Builder core provides a mail API that can be used as an ActionMailer delivery method.
+
+### ActionMailer Integration
+
+Configure your Rails application to send emails through Aha! Builder core:
+
+```ruby
+# config/initializers/action_mailer.rb
+ActionMailer::Base.add_delivery_method :aha_mail, Aha::Mail::DeliveryMethod
+
+# config/environments/production.rb
+config.action_mailer.delivery_method = :aha_mail
+```
+

data/lib/aha/auth/builder_discovery_service.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    # Discovers BuilderCore configuration via the secure.aha.io discovery endpoint.
+    # Resilient to account subdomain changes by resolving the current subdomain from account ID.
+    class BuilderDiscoveryService
+      CACHE_TTL = 300 # 5 minutes
+
+      def initialize(configuration)
+        @configuration = configuration
+        @cache = Concurrent::Atom.new({})
+        @refreshing = Concurrent::AtomicBoolean.new(false)
+      end
+
+      # Discover the server URL for the account.
+      # @param force [Boolean] Force refresh, bypassing cache
+      # @return [Hash] Discovery data with :server_url
+      def discover(force: false)
+        @cache.reset({}) if force
+
+        cached = @cache.value
+
+        # Return cached data if present, serving stale data while refreshing in the background if past threshold
+        if cached[:data]
+          schedule_background_refresh(cached) if should_refresh?(cached)
+          return cached[:data]
+        end
+
+        # Cache expired or empty - fetch synchronously with fallback
+        fetch_with_fallback
+      end
+
+      private
+
+      def should_refresh?(cached)
+        return true unless cached[:fetched_at]
+
+        Time.current > cached[:fetched_at] + CACHE_TTL
+      end
+
+      def schedule_background_refresh(cached)
+        return unless @refreshing.make_true
+
+        Concurrent::Future.execute do
+          data = fetch_discovery
+          @cache.reset(data: data, fetched_at: Time.current)
+        rescue StandardError => e
+          logger.warn { "[BuilderDiscovery] Background refresh failed: #{e.message}" }
+        ensure
+          @refreshing.make_false
+        end
+      end
+
+      def fetch_with_fallback
+        @refreshing.make_true
+        data = fetch_discovery
+        @refreshing.make_false
+        @cache.reset(data: data, fetched_at: Time.current)
+        data
+      rescue StandardError => e
+        logger.warn { "[BuilderDiscovery] Fetch failed: #{e.message}" }
+
+        fallback_data = build_fallback_data
+        if fallback_data
+          logger.warn { "[BuilderDiscovery] Using fallback from AHA_CORE_SERVER_URL" }
+          @cache.reset(data: fallback_data, fetched_at: Time.current)
+          return fallback_data
+        end
+
+        raise
+      end
+
+      def build_fallback_data
+        server_url = ENV.fetch("AHA_CORE_SERVER_URL", nil)
+        return nil if server_url.to_s.empty?
+
+        { server_url: server_url }
+      end
+
+      def fetch_discovery
+        account_id = @configuration.account_id
+        raise ConfigurationError, "account_id is required for discovery" if account_id.to_s.empty?
+
+        url = "#{@configuration.core_discovery_url}/.well-known/core-discovery/#{account_id}"
+        logger.debug { "[BuilderDiscovery] Fetching #{url}" }
+        response = http_client.get(url)
+        logger.debug { "[BuilderDiscovery] Response status: #{response.status}, body: #{response.body}" }
+        handle_response(response)
+      end
+
+      def logger
+        @logger ||= defined?(Rails) ? Rails.logger : Logger.new($stdout)
+      end
+
+      def http_client
+        @http_client ||= Faraday.new do |conn|
+          conn.request :retry, max: 2, interval: 0.5, backoff_factor: 2
+          conn.options.timeout = @configuration.timeout
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def handle_response(response)
+        case response.status
+        when 200
+          parsed = JSON.parse(response.body)
+          domain = parsed["domain"]
+          base_domain = @configuration.core_discovery_url.sub(%r{\Ahttps?://secure\.}, "")
+          { server_url: "https://#{domain}.#{base_domain}/api/core" }
+        when 400
+          raise BadRequestError.new("Invalid account ID", status: response.status)
+        when 404
+          raise NotFoundError.new("Account not found", status: response.status)
+        else
+          raise ApiError.new("Discovery failed (status: #{response.status})", status: response.status)
+        end
+      rescue Faraday::Error => e
+        raise NetworkError.new("Discovery network error", original_error: e)
+      end
+    end
+  end
+end

data/lib/aha/auth/client.rb

@@ -8,8 +8,11 @@ module Aha
     class Client
       ALGORITHM = "RS256"
 
-      def initialize(configuration)
+      # @param configuration [Configuration] The client configuration
+      # @param server_url [String, nil] Optional server URL override (used for discovery)
+      def initialize(configuration, server_url: nil)
         @configuration = configuration
+        @server_url = server_url || configuration.server_url
         @token_cache = TokenCache.new(ttl: configuration.jwks_cache_ttl)
       end
 
@@ -194,7 +197,7 @@ module Aha
       end
 
       def http_client
-        @http_client ||= Faraday.new(url: @configuration.server_url) do |conn|
+        @http_client ||= Faraday.new(url: @server_url) do |conn|
           if @configuration.enable_logging && @configuration.logger
             conn.response :logger, @configuration.logger, bodies: true
           end

data/lib/aha/auth/configuration.rb

@@ -3,7 +3,13 @@
 module Aha
   module Auth
     class Configuration
-      # The base URL of the BuilderCore auth server
+      # Account ID for discovery-based URL resolution
+      attr_accessor :account_id
+
+      # Base URL for builder discovery endpoint (e.g., https://secure.aha.io)
+      attr_accessor :core_discovery_url
+
+      # The base URL of the BuilderCore auth server (discovered or explicit)
       attr_accessor :server_url
 
       # API key for server-to-server authentication
@@ -29,7 +35,8 @@ module Aha
       attr_accessor :logger
 
       def initialize
-        @server_url = ENV.fetch("AHA_CORE_SERVER_URL", "https://secure.aha.io/api/core")
+        @account_id = ENV.fetch("AHA_ACCOUNT_ID", nil)
+        @core_discovery_url = ENV.fetch("AHA_SECURE_URL", "https://secure.aha.io")
         @api_key = ENV.fetch("AHA_CORE_API_KEY", nil)
         @client_id = ENV.fetch("APPLICATION_ID", nil)
         @jwks_cache_ttl = 3600 # 1 hour
@@ -40,7 +47,7 @@ module Aha
       end
 
       def validate!
-        raise ConfigurationError, "server_url is required" if server_url.nil? || server_url.to_s.empty?
+        raise ConfigurationError, "account_id is required" if account_id.nil? || account_id.to_s.empty?
         raise ConfigurationError, "client_id is required" if client_id.nil? || client_id.to_s.empty?
       end
     end

data/lib/aha/auth.rb

@@ -11,6 +11,7 @@ require_relative "version"
 require_relative "auth/errors"
 require_relative "auth/configuration"
 require_relative "auth/token_cache"
+require_relative "auth/builder_discovery_service"
 require_relative "auth/session"
 require_relative "auth/user"
 require_relative "auth/client"
@@ -20,6 +21,7 @@ require_relative "auth/sessions_resource"
 module Aha
   module Auth
     CONFIGURATION = Concurrent::Atom.new(Configuration.new)
+    DISCOVERY_SERVICE = Concurrent::Atom.new(nil)
     CLIENT = Concurrent::Atom.new(nil)
     USERS_RESOURCE = Concurrent::Atom.new(nil)
     SESSIONS_RESOURCE = Concurrent::Atom.new(nil)
@@ -35,11 +37,27 @@ module Aha
 
       def reset_configuration!
         CONFIGURATION.reset(Configuration.new)
+        DISCOVERY_SERVICE.reset(nil)
         CLIENT.reset(nil)
         USERS_RESOURCE.reset(nil)
         SESSIONS_RESOURCE.reset(nil)
       end
 
+      # Access the discovery service for resolving server URLs
+      #
+      # @return [BuilderDiscoveryService]
+      def discovery_service
+        DISCOVERY_SERVICE.compare_and_set(nil, BuilderDiscoveryService.new(configuration))
+        DISCOVERY_SERVICE.value
+      end
+
+      # Get the effective server URL (discovered or configured)
+      #
+      # @return [String] The server URL to use
+      def server_url
+        discovery_service.discover[:server_url]
+      end
+
       # Generate login URL for redirecting users to the auth server
       #
       # @param cookies [Hash] Cookies hash to store the nonce for CSRF verification
@@ -73,7 +91,7 @@ module Aha
         }
 
         query = URI.encode_www_form(params)
-        "#{configuration.server_url}/auth_ui/start?#{query}"
+        "#{server_url}/auth_ui/start?#{query}"
       end
 
       # Exchange an authorization code for tokens
@@ -84,12 +102,12 @@ module Aha
       def authenticate_with_code(code:, cookies:)
         # Split the code and nonce if present
         actual_code, nonce = code.split(".", 2)
-        
+
         raise "CSRF verification failed: unable to verify nonce" unless nonce
 
         cookie_nonce = cookies[:auth_nonce]
         cookies.delete(:auth_nonce)
-        raise "CSRF verification failed: nonce missing in cookie" if cookie_nonce.blank? 
+        raise "CSRF verification failed: nonce missing in cookie" if cookie_nonce.blank?
         raise "CSRF verification failed: nonce mismatch" if cookie_nonce != nonce
 
         client.authenticate_with_code(code: actual_code)
@@ -139,7 +157,7 @@ module Aha
       private
 
       def client
-        CLIENT.compare_and_set(nil, Client.new(configuration))
+        CLIENT.compare_and_set(nil, Client.new(configuration, server_url: server_url))
         CLIENT.value
       end
     end

data/lib/aha/mail/delivery_method.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Aha
+  module Mail
+    class DeliveryMethod
+      attr_accessor :settings
+
+      def initialize(settings = {})
+        @settings = settings
+      end
+
+      def deliver!(mail)
+        # Extract mail attributes
+        mail_params = {
+          from: format_addresses(mail.from).first,
+          to: format_addresses(mail.to),
+          cc: format_addresses(mail.cc),
+          bcc: format_addresses(mail.bcc),
+          reply_to: format_addresses(mail.reply_to),
+          subject: mail.subject,
+        }
+
+        # Determine content type and body
+        if mail.multipart?
+          # For multipart messages, prefer HTML over plain text
+          html_part = mail.html_part
+          text_part = mail.text_part
+
+          if html_part
+            mail_params[:body] = html_part.body.decoded
+            mail_params[:content_type] = "text/html"
+          elsif text_part
+            mail_params[:body] = text_part.body.decoded
+            mail_params[:content_type] = "text/plain"
+          else
+            mail_params[:body] = mail.body.decoded
+            mail_params[:content_type] = mail.content_type
+          end
+        else
+          mail_params[:body] = mail.body.decoded
+          mail_params[:content_type] = mail.content_type || "text/plain"
+        end
+
+        # Send via the Aha::Mail API
+        Aha::Mail.send_mail(mail_params)
+      rescue StandardError => e
+        # ActionMailer expects delivery methods to raise exceptions on failure
+        raise "Failed to deliver mail via Aha::Mail: #{e.message}"
+      end
+
+      private
+
+      def format_addresses(addresses)
+        return [] if addresses.nil?
+
+        Array(addresses).map do |address|
+          if address.is_a?(::Mail::Address)
+            address.address
+          else
+            address
+          end
+        end.compact
+      end
+    end
+  end
+end

data/lib/aha/mail.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "mail/delivery_method"
+
+module Aha
+  module Mail
+    class << self
+      def send_mail(mail_params)
+        client.send(:post, "/api/core/mail/send", mail: mail_params)
+      end
+
+      private
+
+      def client
+        Aha::Auth.send(:client)
+      end
+    end
+  end
+end

data/lib/aha/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Aha
-  VERSION = "1.0.20"
+  VERSION = "1.0.21"
 end

data/lib/aha_builder_core.rb

@@ -2,3 +2,4 @@
 
 require_relative "aha/auth"
 require_relative "aha/user_guide"
+require_relative "aha/mail"

data/lib/generators/aha_builder_core/email/USAGE

@@ -0,0 +1,5 @@
+Description:
+    Configure ActionMailer to deliver via Aha::Mail.
+
+Example:
+    bin/rails generate aha_builder_core:email

data/lib/generators/aha_builder_core/email/email_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module AhaBuilderCore
+  class EmailGenerator < Rails::Generators::Base
+    ACTION_MAILER_INITIALIZER_PATH = "config/initializers/action_mailer.rb"
+    DELIVERY_METHOD_REGISTRATION_LINE = "ActionMailer::Base.add_delivery_method :aha_mail, Aha::Mail::DeliveryMethod"
+    DELIVERY_METHOD_LINE = "config.action_mailer.delivery_method = :aha_mail"
+
+    def configure_action_mailer_initializer
+      if File.exist?(ACTION_MAILER_INITIALIZER_PATH)
+        ensure_line_present(ACTION_MAILER_INITIALIZER_PATH, DELIVERY_METHOD_REGISTRATION_LINE)
+      else
+        create_file ACTION_MAILER_INITIALIZER_PATH, <<~RUBY
+          # frozen_string_literal: true
+
+          #{DELIVERY_METHOD_REGISTRATION_LINE}
+        RUBY
+      end
+    end
+
+    def configure_environment_delivery_methods
+      environment "#{DELIVERY_METHOD_LINE}\n", env: %w[development production]
+    end
+
+    def display_instructions
+      say "\nActionMailer configured to use Aha::Mail delivery!", :green
+    end
+
+    private
+
+    def ensure_line_present(path, line)
+      contents = File.read(path)
+      return if contents.include?(line)
+
+      separator = contents.end_with?("\n") ? "" : "\n"
+      append_to_file path, "#{separator}#{line}\n"
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aha_builder_core
 version: !ruby/object:Gem::Version
-  version: 1.0.20
+  version: 1.0.21
 platform: ruby
 authors:
 - Aha! Labs Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 2026-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -115,6 +115,7 @@ files:
 - LICENSE
 - README.md
 - lib/aha/auth.rb
+- lib/aha/auth/builder_discovery_service.rb
 - lib/aha/auth/client.rb
 - lib/aha/auth/configuration.rb
 - lib/aha/auth/errors.rb
@@ -123,6 +124,8 @@ files:
 - lib/aha/auth/token_cache.rb
 - lib/aha/auth/user.rb
 - lib/aha/auth/users_resource.rb
+- lib/aha/mail.rb
+- lib/aha/mail/delivery_method.rb
 - lib/aha/user_guide.rb
 - lib/aha/version.rb
 - lib/aha_builder_core.rb
@@ -136,6 +139,8 @@ files:
 - lib/generators/aha_builder_core/blob_storage/USAGE
 - lib/generators/aha_builder_core/blob_storage/blob_storage_generator.rb
 - lib/generators/aha_builder_core/blob_storage/templates/storage.yml.tt
+- lib/generators/aha_builder_core/email/USAGE
+- lib/generators/aha_builder_core/email/email_generator.rb
 homepage: https://www.aha.io
 licenses:
 - MIT