blocks-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac08c590b7f3183166bf999b2854b33ef8c30153dabfaa55890342613857e145
+  data.tar.gz: cbbb32696c580610edbe7da2bb3ba5a61e2bc414d48e17d6d53ecf280dc94dbc
+SHA512:
+  metadata.gz: 91460d37d72ac5463aee39b8dea358c767ec6e7e45b18840dd5ddc8633b3f3069d07a840d464920e3a01162df27ff1420c6795b548faeffdcb7485a4b3d3e912
+  data.tar.gz: 80984e3cbd6a233bf434a6778f21aa0d1de25090736e20da5e2538a01e171248789b441578a28340c4265ec1ab5b17f15bdfea48403627a82f6ff16c535bfad5

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-24
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 bugloper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,197 @@
+# Blocks SDK
+
+A Ruby gem that provides clients for Blocks Services, including translations, with Rails integration, caching, and webhook support.
+
+## Features
+
+- **Service Clients**: Extensible client pattern for integrating with Blocks Services
+- **Translation Service**: UILM translation client with caching
+- **Rails Integration**: Automatic route setup and controller integration
+- **In-Memory Caching**: Thread-safe cache for service responses
+- **Webhook Support**: Cache invalidation via webhooks
+- **Boot-time Loading**: Preload translations on Rails boot
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "blocks-sdk"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Create an initializer file `config/initializers/blocks_sdk.rb`:
+
+```ruby
+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) # Optional
+  config.cache_enabled = true
+  config.logger = Rails.logger
+end
+```
+
+### Environment Variables
+
+- `UILM_BASE_URL`: Base URL for UILM translation service
+- `UILM_PROJECT_KEY`: Project key for authentication
+- `BLOCKS_WEBHOOK_SECRET`: Secret for webhook authentication (optional)
+- `BLOCKS_TRANSLATION_MODULES`: Comma-separated list of modules to preload (e.g., "module1,module2")
+- `BLOCKS_TRANSLATION_LANGUAGES`: Comma-separated list of languages to preload (e.g., "en,de")
+
+## Usage
+
+### Frontend API Endpoint
+
+The gem automatically creates a Rails API endpoint for fetching translations:
+
+```
+GET /blocks/api/translations?module_name=your_module&language=en
+```
+
+**Query Parameters:**
+- `module_name` (required): The module name to fetch translations for
+- `language` (optional): Language code (defaults to "en")
+
+**Response:**
+```json
+{
+  "key1": "translation1",
+  "key2": "translation2"
+}
+```
+
+### Backend Usage
+
+Fetch translations programmatically in your Rails application:
+
+```ruby
+# Fetch translations with caching
+result = Blocks::Sdk.service_manager.fetch(
+  service_name: "translations",
+  params: { module_name: "your_module", language: "en" },
+  config: {
+    base_url: ENV["UILM_BASE_URL"],
+    project_key: ENV["UILM_PROJECT_KEY"]
+  }
+)
+
+if result[:translations]
+  translations = result[:translations]
+  # Use translations...
+end
+```
+
+### Webhook Endpoint
+
+The gem exposes a webhook endpoint for cache invalidation:
+
+```
+POST /blocks/webhooks/translations
+```
+
+**Headers:**
+- `X-Blocks-Webhook-Secret`: Webhook secret (if configured)
+
+**Body:**
+```json
+{
+  "module_name": "your_module",
+  "language": "en"
+}
+```
+
+When a webhook is received, the cache for the specified module and language is automatically invalidated.
+
+### Preloading Translations on Boot
+
+To preload translations when Rails boots, set these environment variables:
+
+```bash
+BLOCKS_TRANSLATION_MODULES=module1,module2,module3
+BLOCKS_TRANSLATION_LANGUAGES=en,de
+```
+
+Translations will be fetched and cached during Rails initialization (production environment only).
+
+### I18n Integration (Optional)
+
+To use Blocks SDK translations with Rails I18n instead of YAML files, configure a custom I18n backend:
+
+```ruby
+# config/initializers/i18n.rb
+require "blocks/sdk/rails/i18n_backend"
+
+I18n.backend = Blocks::Sdk::Rails::I18nBackend.new(
+  service_manager: Blocks::Sdk.service_manager,
+  config: {
+    # Optional: default module name if not specified in scope
+    default_module_name: ENV["BLOCKS_DEFAULT_MODULE_NAME"]
+  }
+)
+```
+
+Then use I18n as usual:
+
+```ruby
+I18n.t("key", module_name: "your_module", locale: "en")
+```
+
+Then register it:
+
+```ruby
+Blocks::Sdk.service_manager.register_client("email", Blocks::Sdk::Clients::EmailClient)
+```
+
+## Architecture
+
+### Folder Structure
+
+```
+lib/blocks/sdk/
+├── clients/               # Service clients
+│   └── translations_client.rb
+├── cache/                 # Caching implementations
+│   └── memory_cache.rb
+├── rails/                 # Rails integration
+│   ├── controllers/       # API controllers
+│   │   ├── api/
+│   │   │   └── translations_controller.rb
+│   │   └── webhooks_controller.rb
+│   ├── route_mapper.rb    # Route definitions
+│   └── railtie.rb         # Rails initialization
+├── base_client.rb         # Base client class
+├── configuration.rb       # Configuration management
+├── service_manager.rb     # Client and cache manager
+└── sdk.rb                 # Main SDK module
+```
+
+### Key Components
+
+- **BaseClient**: Base class for all service clients
+- **ServiceManager**: Manages clients and caching
+- **MemoryCache**: Thread-safe in-memory cache
+- **Rails Controllers**: API endpoints for frontend and webhooks
+- **Railtie**: Rails integration and initialization
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/docs/ARCHITECTURE.md

@@ -0,0 +1,160 @@
+# Blocks SDK Architecture
+
+## Overview
+
+Blocks SDK is a Ruby gem that provides clients for Blocks Services. It follows a client pattern to allow easy integration with multiple services while maintaining a consistent API.
+
+## Folder Structure
+
+```
+lib/blocks/sdk/
+├── clients/                            # Service clients
+│   ├── translations_client.rb          # UILM translation service client
+│   └── example_client.rb               # Template for creating new clients
+├── cache/                              # Caching implementations
+│   └── memory_cache.rb                 # Thread-safe in-memory cache
+├── rails/                              # Rails integration
+│   ├── controllers/                    # API controllers
+│   │   ├── api/
+│   │   │   └── translations_controller.rb  # FE translation endpoint
+│   │   └── webhooks_controller.rb          # Webhook handler
+│   ├── i18n_backend.rb                # Optional I18n backend integration
+│   ├── initializer.rb                 # Initializer template
+│   ├── railtie.rb                     # Rails initialization
+│   ├── route_mapper.rb                # Route definitions
+│   └── routes.rb                      # Route helper (backward compat)
+├── base_client.rb                     # Base class for all clients
+├── configuration.rb                   # Configuration management
+├── service_manager.rb                 # Client and cache manager
+├── rails.rb                           # Rails module loader
+├── sdk.rb                             # Main SDK module
+└── version.rb                         # Gem version
+```
+
+## Component Details
+
+### BaseClient
+
+Base class for all service clients. Provides:
+- Service name registration
+- Configuration management
+- Interface definition (`fetch`, `handle_webhook`)
+
+### Clients
+
+Service-specific implementations:
+- **TranslationsClient**: Fetches translations from UILM API
+- Future clients: Email, Notification, etc.
+
+### ServiceManager
+
+Central manager for:
+- Registering clients
+- Fetching data with caching
+- Handling webhooks and cache invalidation
+
+### MemoryCache
+
+Thread-safe in-memory cache:
+- Key-based storage
+- Service/module/language invalidation
+- Thread-safe operations
+
+### Rails Integration
+
+- **Railtie**: Auto-loads routes and initializes on boot
+- **Controllers**: API endpoints for FE and webhooks
+- **RouteMapper**: Defines routes under `/blocks` namespace
+
+## Data Flow
+
+### Frontend Request Flow
+
+```
+Frontend Request
+  ↓
+GET /blocks/api/translations?module_name=X&language=en
+  ↓
+TranslationsController#index
+  ↓
+ServiceManager#fetch
+  ↓
+Check MemoryCache
+  ↓ (cache miss)
+TranslationsClient#fetch
+  ↓
+UILM API
+  ↓
+Cache result
+  ↓
+Return to Frontend
+```
+
+### Webhook Flow
+
+```
+Blocks Service Webhook
+  ↓
+POST /blocks/webhooks/translations
+  ↓
+WebhooksController#create
+  ↓
+ServiceManager#handle_webhook
+  ↓
+TranslationsClient#handle_webhook
+  ↓
+MemoryCache#invalidate
+  ↓
+Cache cleared for module/language
+```
+
+### Boot-time Loading Flow
+
+```
+Rails Boot
+  ↓
+Railtie initializer
+  ↓
+Blocks::Sdk.load_translations_on_boot
+  ↓
+For each module/language:
+  ServiceManager#fetch
+  ↓
+Cache translations
+```
+
+## Extension Points
+
+### Adding a New Client
+
+1. Create client class inheriting from `BaseClient`
+2. Implement `fetch` and `handle_webhook` methods
+3. Register with `ServiceManager.register_client`
+4. Add controller/route if needed
+
+### Adding a New Endpoint
+
+1. Create controller in `rails/controllers/`
+2. Add route in `route_mapper.rb`
+3. Controller uses `ServiceManager` to fetch data
+
+## Configuration
+
+Configuration is managed through:
+- Environment variables (primary)
+- `Blocks::Sdk.configure` block (secondary)
+- Defaults in `Configuration` class
+
+## Caching Strategy
+
+- **Cache Key Format**: `service:module_name:language`
+- **Cache Invalidation**: Via webhooks or manual deletion
+- **Cache Storage**: In-memory (thread-safe)
+- **Cache Lifetime**: Until invalidation or app restart
+
+## Thread Safety
+
+- `MemoryCache` uses `Mutex` for thread-safe operations
+- `ServiceManager` is singleton, shared across threads
+- Clients are stateless, can be instantiated per request
+

data/lib/blocks/sdk/base_client.rb

@@ -0,0 +1,43 @@
+module Blocks
+  module Sdk
+    # Base class for all Blocks Service clients
+    # Subclasses should implement the service-specific logic
+    class BaseClient
+      class << self
+        attr_accessor :service_name
+
+        def inherited(subclass)
+          super
+          # Extract service name from class name (e.g., "TranslationsClient" -> "translations")
+          class_name            = subclass.name.split("::").last
+          subclass.service_name = class_name.gsub(/Client$/, "").gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                                            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                                            .downcase
+        end
+      end
+
+      attr_reader :config
+
+      def initialize(config = {})
+        @config = config
+      end
+
+      # Override in subclasses to fetch data from the service
+      def fetch
+        raise NotImplementedError, "#{self.class} must implement #fetch"
+      end
+
+      # Override in subclasses to handle webhook callbacks
+      def handle_webhook(payload)
+        raise NotImplementedError, "#{self.class} must implement #handle_webhook"
+      end
+
+      protected
+
+      def service_name
+        self.class.service_name
+      end
+    end
+  end
+end
+

data/lib/blocks/sdk/cache/memory_cache.rb

@@ -0,0 +1,92 @@
+require "thread"
+
+module Blocks
+  module Sdk
+    module Cache
+      # Thread-safe in-memory cache for Blocks Service data
+      class MemoryCache
+        def initialize
+          @cache = {}
+          @mutex = Mutex.new
+        end
+
+        # Get cached value for a key
+        # @param key [String] Cache key
+        # @return [Object, nil] Cached value or nil if not found
+        def get(key)
+          @mutex.synchronize do
+            @cache[key]
+          end
+        end
+
+        # Set a value in cache
+        # @param key [String] Cache key
+        # @param value [Object] Value to cache
+        def set(key, value)
+          @mutex.synchronize do
+            @cache[key] = value
+          end
+        end
+
+        # Delete a specific key from cache
+        # @param key [String] Cache key to delete
+        def delete(key)
+          @mutex.synchronize do
+            @cache.delete(key)
+          end
+        end
+
+        # Invalidate cache for a service/module/language combination
+        # @param service [String] Service name (e.g., "translations")
+        # @param module_name [String] Module name
+        # @param language [String] Language code
+        def invalidate(service:, module_name:, language: nil)
+          @mutex.synchronize do
+            if language
+              # Invalidate specific language
+              key = build_key(service, module_name, language)
+              @cache.delete(key)
+            else
+              # Invalidate all languages for this module
+              @cache.keys.each do |key|
+                if key.start_with?("#{service}:#{module_name}:")
+                  @cache.delete(key)
+                end
+              end
+            end
+          end
+        end
+
+        # Clear all cache
+        def clear
+          @mutex.synchronize do
+            @cache.clear
+          end
+        end
+
+        # Get all cache keys (useful for debugging)
+        def keys
+          @mutex.synchronize do
+            @cache.keys.dup
+          end
+        end
+
+        # Check if a key exists in cache
+        # @param key [String] Cache key
+        # @return [Boolean]
+        def exists?(key)
+          @mutex.synchronize do
+            @cache.key?(key)
+          end
+        end
+
+        private
+
+        def build_key(service, module_name, language)
+          "#{service}:#{module_name}:#{language}"
+        end
+      end
+    end
+  end
+end
+