blocks-sdk 0.1.0

data/lib/blocks/sdk/clients/translations_client.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "../base_client"
+
+module Blocks
+  module Sdk
+    module Clients
+      # Client for UILM Translation Service
+      class TranslationsClient < BaseClient
+        class << self
+          def service_name
+            "translations"
+          end
+        end
+
+        def initialize(config = {})
+          super(config)
+          @base_url    = config[:base_url] || ENV.fetch("UILM_BASE_URL")
+          @project_key = config[:project_key] || ENV.fetch("UILM_PROJECT_KEY")
+        end
+
+        def fetch(module_name:, language: "en")
+          conn = build_connection
+
+          request_params = {
+            ModuleName: module_name,
+            ProjectKey: @project_key,
+            Language: normalize_language(language)
+          }
+
+          response = conn.get(
+            @base_url,
+            request_params,
+            build_headers
+          )
+
+          handle_response(response)
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+          log_error("UILM API connection failed: #{e.message}")
+          { error: "Connection failed", status: :connection_error }
+        rescue StandardError => e
+          log_error("Unexpected error in TranslationsClient: #{e.message}")
+          { error: "Unexpected error occurred", status: :error }
+        end
+
+        def handle_webhook(payload)
+          # Extract cache invalidation parameters from webhook payload
+          # Expected payload structure: { module_name: "...", language: "..." }
+          module_name = payload[:module_name] || payload["module_name"]
+          language = payload[:language] || payload["language"] || "en"
+
+          {
+            service: service_name,
+            module_name: module_name,
+            language: language,
+            action: :invalidate_cache
+          }
+        end
+
+        private
+
+        def build_connection
+          Faraday.new do |f|
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        def build_headers
+          {
+            "Accept" => "application/json",
+            "Content-Type" => "application/json",
+            "x-blocks-key" => @project_key
+          }
+        end
+
+        def normalize_language(language)
+          case language.to_s.downcase
+          when "en"
+            "en-US"
+          when "de"
+            "de-DE"
+          else
+            language
+          end
+        end
+
+        def handle_response(response)
+          unless response.success?
+            return { error: "Failed to fetch translations", status: response.status }
+          end
+
+          if response.body.nil? || response.body.strip.empty?
+            return { error: "Empty response from UILM API", status: :empty_response }
+          end
+
+          begin
+            parsed_response = JSON.parse(response.body)
+            { translations: normalize(parsed_response), status: :success }
+          rescue JSON::ParserError => _e
+            { error: "Invalid JSON response from UILM API", status: :parse_error }
+          rescue StandardError => _e
+            { error: "Unexpected error occurred", status: :error }
+          end
+        end
+
+        # UILM ships {{var}} placeholders; I18n interpolates %{var}.
+        # Keys are also downcased so I18n.t resolves regardless of caller casing.
+        PLACEHOLDER_RE = /\{\{\s*([\w.]+)\s*\}\}/
+
+        def normalize(value)
+          case value
+          when String
+            value.gsub(PLACEHOLDER_RE) { "%{#{Regexp.last_match(1)}}" }
+          when Hash
+            value.each_with_object({}) { |(k, v), h| h[k.to_s.downcase] = normalize(v) }
+          when Array
+            value.map { |v| normalize(v) }
+          else
+            value
+          end
+        end
+
+        def log_error(message)
+          if defined?(Rails)
+            Rails.logger.error(message)
+          else
+            warn(message)
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/blocks/sdk/configuration.rb

@@ -0,0 +1,38 @@
+module Blocks
+  module Sdk
+    # Configuration for Blocks SDK
+    class Configuration
+      attr_accessor :uilm_base_url, :uilm_project_key
+      attr_accessor :webhook_secret, :webhook_path_prefix
+      attr_accessor :cache_enabled, :logger
+      attr_accessor :install_i18n_backend, :default_module_name
+      attr_accessor :translation_modules, :translation_languages
+
+      def initialize
+        @uilm_base_url        = ENV.fetch("UILM_BASE_URL", nil)
+        @uilm_project_key     = ENV.fetch("UILM_PROJECT_KEY", nil)
+        @webhook_secret       = ENV.fetch("BLOCKS_WEBHOOK_SECRET", nil)
+        @webhook_path_prefix  = "/blocks/webhooks"
+        @cache_enabled        = true
+        @logger               = nil
+        @install_i18n_backend = false
+        @default_module_name  = ENV.fetch("BLOCKS_DEFAULT_MODULE_NAME", nil)
+        @translation_modules  = nil
+        @translation_languages = nil
+      end
+
+      def to_h
+        {
+          uilm_base_url: @uilm_base_url,
+          uilm_project_key: @uilm_project_key,
+          webhook_secret: @webhook_secret,
+          webhook_path_prefix: @webhook_path_prefix,
+          cache_enabled: @cache_enabled,
+          install_i18n_backend: @install_i18n_backend,
+          default_module_name: @default_module_name
+        }
+      end
+    end
+  end
+end
+

data/lib/blocks/sdk/rails/controllers/api/translations_controller.rb

@@ -0,0 +1,53 @@
+module Blocks
+  module Sdk
+    module Rails
+      module Controllers
+        module Api
+          # API controller for fetching translations
+          class TranslationsController < ActionController::API
+            before_action :set_service_manager
+
+            # GET /blocks/api/translations
+            # Query params: module_name, language (optional, defaults to "en")
+            def index
+              module_name = params[:module_name] || params[:moduleName]
+              language    = params[:language] || params[:Language] || "en"
+
+              unless module_name
+                return render json: { error: "module_name is required" }, status: :bad_request
+              end
+
+              result = @service_manager.fetch(
+                service_name: "translations",
+                params: { module_name: module_name, language: language },
+                config: client_config
+              )
+
+              if result[:error]
+                status = result[:status] == :connection_error ? :service_unavailable : :bad_gateway
+                render json: result, status: status
+              else
+                render json: result[:translations] || result, status: :ok
+              end
+            end
+
+            private
+
+            def set_service_manager
+              @service_manager = Blocks::Sdk.service_manager
+            end
+
+            def client_config
+              {
+                base_url: Blocks::Sdk.config.uilm_base_url || ENV.fetch("UILM_BASE_URL"),
+                project_key: Blocks::Sdk.config.uilm_project_key || ENV.fetch("UILM_PROJECT_KEY")
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+

data/lib/blocks/sdk/rails/controllers/translations_webhooks_controller.rb

@@ -0,0 +1,62 @@
+module Blocks
+  module Sdk
+    module Rails
+      module Controllers
+        # Webhook controller specifically for Translations service
+        # Other services should implement their own webhook controllers
+        class TranslationsWebhooksController < ActionController::API
+          before_action :set_service_manager
+          before_action :verify_webhook_secret, if: -> { webhook_secret_configured? }
+
+          # POST /blocks/webhooks/translations
+          # Handles webhook callbacks for translations cache invalidation
+          def create
+            result = @service_manager.handle_webhook(
+              service_name: "translations",
+              payload: webhook_params,
+              config: client_config
+            )
+
+            if result[:success]
+              render json: result, status: :ok
+            else
+              render json: result, status: :unprocessable_entity
+            end
+          end
+
+          private
+
+          def set_service_manager
+            @service_manager = Blocks::Sdk.service_manager
+          end
+
+          def webhook_params
+            params.except(:controller, :action).permit!.to_h
+          end
+
+          def client_config
+            {
+              base_url: Blocks::Sdk.config.uilm_base_url,
+              project_key: Blocks::Sdk.config.uilm_project_key
+            }
+          end
+
+          def verify_webhook_secret
+            provided_secret = request.headers["X-Blocks-Webhook-Secret"] || request.headers["x-blocks-webhook-secret"]
+            expected_secret = Blocks::Sdk.config.webhook_secret
+
+            unless provided_secret == expected_secret
+              render json: { error: "Invalid webhook secret" }, status: :unauthorized
+            end
+          end
+
+          def webhook_secret_configured?
+            secret = Blocks::Sdk.config.webhook_secret
+            !secret.nil? && !secret.to_s.strip.empty?
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/blocks/sdk/rails/i18n_backend.rb

@@ -0,0 +1,79 @@
+# I18n backend for Blocks SDK translations.
+#
+# Reads through ServiceManager so the same MemoryCache that holds boot-time
+# preloads and webhook-invalidated entries is the single source of truth.
+# Falls back to the Simple backend (YAML files) when a key is not found in
+# UILM, so existing app translations keep working.
+module Blocks
+  module Sdk
+    module Rails
+      class I18nBackend < ::I18n::Backend::Simple
+        def initialize(service_manager: nil, config: {})
+          super()
+          @service_manager     = service_manager || Blocks::Sdk.service_manager
+          @config              = config
+          @default_module_name = config[:default_module_name] ||
+                                 Blocks::Sdk.config.default_module_name
+        end
+
+        protected
+
+        def lookup(locale, key, scope = [], options = {})
+          module_name, scope_consumed = extract_module_name(scope, options)
+          return super unless module_name
+
+          translations = fetch_module_translations(module_name, locale)
+          return super unless translations.is_a?(Hash)
+
+          remaining_scope = scope_consumed ? [] : scope
+          path = ::I18n.normalize_keys(nil, key, remaining_scope, options[:separator])
+
+          navigate(translations, path) || super
+        end
+
+        private
+
+        def fetch_module_translations(module_name, locale)
+          result = @service_manager.fetch(
+            service_name: "translations",
+            params: { module_name: module_name.to_s, language: locale.to_s },
+            config: {
+              base_url: Blocks::Sdk.config.uilm_base_url,
+              project_key: Blocks::Sdk.config.uilm_project_key
+            }
+          )
+
+          result.is_a?(Hash) ? result[:translations] : nil
+        end
+
+        # Returns [module_name, scope_consumed?]. scope_consumed signals that
+        # the caller used scope.first as the module, so the navigator should
+        # skip it when walking the translations hash.
+        def extract_module_name(scope, options)
+          return [options[:module_name], false] if options[:module_name]
+          return [scope.first, true] if scope.is_a?(Array) && scope.any?
+
+          [@default_module_name, false]
+        end
+
+        # Walks the translations hash for nested payloads, then falls back to
+        # a dot-joined flat key (UILM payloads in this project are flat).
+        # Cache keys are stored downcased, so the lookup downcases too.
+        def navigate(translations, keys)
+          return nil if keys.nil? || keys.empty?
+
+          downcased = keys.map { |k| k.to_s.downcase }
+
+          nested = downcased.inject(translations) do |hash, k|
+            break nil unless hash.is_a?(Hash)
+            hash[k] || hash[k.to_sym]
+          end
+          return nested unless nested.nil?
+
+          flat_key = downcased.join(".")
+          translations[flat_key] || translations[flat_key.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/blocks/sdk/rails/initializer.rb

@@ -0,0 +1,25 @@
+# Rails initializer template
+# Copy this to config/initializers/blocks_sdk.rb in your Rails app
+
+# Blocks::Sdk.configure do |config|
+#   config.uilm_base_url    = ENV.fetch("UILM_BASE_URL")
+#   config.uilm_project_key = ENV.fetch("UILM_PROJECT_KEY")
+#   config.webhook_secret   = ENV.fetch("BLOCKS_WEBHOOK_SECRET", nil)
+#   config.cache_enabled    = true
+#   config.logger           = Rails.logger
+#
+#   # Make UILM the data source for I18n.t. The backend reads through
+#   # the SDK's MemoryCache, so boot-time preloads and webhook
+#   # invalidations are visible to I18n immediately.
+#   config.install_i18n_backend = true
+#   config.default_module_name  = "your_module"
+#
+#   # Modules to preload at boot. Languages default to
+#   # I18n.available_locales + I18n.locale + I18n.default_locale.
+#   config.translation_modules  = ["auth", "users"]
+#   # config.translation_languages = ["en", "de"] # override if needed
+# end
+#
+# Or via env vars:
+#   BLOCKS_TRANSLATION_MODULES=module1,module2
+#   BLOCKS_TRANSLATION_LANGUAGES=en,de   # optional; defaults to I18n locales

data/lib/blocks/sdk/rails/railtie.rb

@@ -0,0 +1,33 @@
+require "rails"
+
+module Blocks
+  module Sdk
+    module Rails
+      class Railtie < ::Rails::Railtie
+        initializer "blocks_sdk.initialize" do |app|
+          Blocks::Sdk.configure do |config|
+            config.logger = app.config.logger if app.config.respond_to?(:logger)
+          end
+
+          app.config.after_initialize do
+            if Blocks::Sdk.config.install_i18n_backend
+              require_relative "i18n_backend"
+              ::I18n.backend = Blocks::Sdk::Rails::I18nBackend.new
+            end
+
+            Blocks::Sdk.load_translations_on_boot
+          end
+        end
+
+        initializer "blocks_sdk.routes", after: :set_routes_reloader do |app|
+          app.routes.append do
+            # Register routes for translations service
+            # Other services should register their own routes in their own initializers
+            Blocks::Sdk::Rails::TranslationsRouteMapper.draw(self)
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/blocks/sdk/rails/routes.rb

@@ -0,0 +1,17 @@
+require_relative "translations_route_mapper"
+
+# This module is kept for backward compatibility
+# Routes are now handled by TranslationsRouteMapper
+# Other services should implement their own route mappers
+module Blocks
+  module Sdk
+    module Rails
+      module Routes
+        def self.draw(router)
+          TranslationsRouteMapper.draw(router)
+        end
+      end
+    end
+  end
+end
+

data/lib/blocks/sdk/rails/translations_route_mapper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Blocks
+  module Sdk
+    module Rails
+      # Maps routes specifically for Translations service
+      # Other services should implement their own route mappers
+      class TranslationsRouteMapper
+        def self.draw(router)
+          router.scope path: "blocks" do
+            # API endpoints for frontend - translations service only
+            router.get "api/translations", to: "blocks/sdk/rails/controllers/api/translations#index", as: :api_translations
+
+            # Webhook endpoint for translations service cache invalidation
+            router.post "webhooks/translations", to: "blocks/sdk/rails/controllers/translations_webhooks#create", as: :webhooks_translations
+          end
+        end
+      end
+    end
+  end
+end

data/lib/blocks/sdk/rails.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Rails integration module
+# This file ensures Rails controllers are properly loaded for translations service
+# Other services should require their own controllers in their own integration files
+
+if defined?(Rails)
+  require_relative "rails/translations_route_mapper"
+  require_relative "rails/controllers/api/translations_controller"
+  require_relative "rails/controllers/translations_webhooks_controller"
+end
+

data/lib/blocks/sdk/service_manager.rb

@@ -0,0 +1,93 @@
+require_relative "cache/memory_cache"
+require_relative "clients/translations_client"
+
+module Blocks
+  module Sdk
+    # Manages all Blocks Service clients and their caching
+    class ServiceManager
+      attr_reader :cache, :clients
+
+      def initialize
+        @cache   = Cache::MemoryCache.new
+        @clients = {}
+        register_default_clients
+      end
+
+      # Register a client for a service
+      # @param service_name [String] Name of the service
+      # @param client_class [Class] Client class
+      def register_client(service_name, client_class)
+        @clients[service_name.to_s] = client_class
+      end
+
+      # Get client instance for a service
+      # @param service_name [String] Name of the service
+      # @param config [Hash] Configuration for the client
+      # @return [BaseClient] Client instance
+      def client(service_name, config = {})
+        client_class = @clients[service_name.to_s]
+        raise ArgumentError, "Client not found for service: #{service_name}" unless client_class
+
+        client_class.new(config)
+      end
+
+      # Fetch data from a service with caching
+      # @param service_name [String] Name of the service
+      # @param params [Hash] Parameters for fetching
+      # @param config [Hash] Client configuration
+      # @return [Hash] Service response
+      def fetch(service_name:, params:, config: {})
+        cache_key = build_cache_key(service_name, params)
+        cached_value = @cache.get(cache_key)
+
+        return cached_value if cached_value
+
+        client_instance = client(service_name, config)
+        result = client_instance.fetch(**params)
+
+        # Cache successful responses
+        if result[:status] == :success || result[:translations]
+          @cache.set(cache_key, result)
+        end
+
+        result
+      end
+
+      # Handle webhook callback and invalidate cache
+      # @param service_name [String] Name of the service
+      # @param payload [Hash] Webhook payload
+      # @param config [Hash] Client configuration
+      # @return [Hash] Webhook handling result
+      def handle_webhook(service_name:, payload:, config: {})
+        client_instance = client(service_name, config)
+        webhook_result = client_instance.handle_webhook(payload)
+
+        # Invalidate cache based on webhook result
+        if webhook_result[:action] == :invalidate_cache
+          @cache.invalidate(
+            service: service_name,
+            module_name: webhook_result[:module_name],
+            language: webhook_result[:language]
+          )
+        end
+
+        { success: true, service: service_name, webhook_result: webhook_result }
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      private
+
+      def register_default_clients
+        register_client("translations", Clients::TranslationsClient)
+      end
+
+      def build_cache_key(service_name, params)
+        module_name = params[:module_name] || params["module_name"]
+        language = params[:language] || params["language"] || "en"
+        "#{service_name}:#{module_name}:#{language}"
+      end
+    end
+  end
+end
+

data/lib/blocks/sdk/version.rb

@@ -0,0 +1,5 @@
+module Blocks
+  module Sdk
+    VERSION = "0.1.0"
+  end
+end