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:

gem "blocks-sdk"

And then execute:

bundle install

Configuration

Create an initializer file config/initializers/blocks_sdk.rb:

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:

{
  "key1": "translation1",
  "key2": "translation2"
}

Backend Usage

Fetch translations programmatically in your Rails application:

# 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:

{
  "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:

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:

# 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:

I18n.t("key", module_name: "your_module", locale: "en")

Then register it:

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.