feat: add flagsmith provider

.github/component_owners.yml

@@ -9,6 +9,8 @@ components:
     - thomaspoignant
   providers/openfeature-meta_provider:
     - maxveldink
+  providers/openfeature-flagsmith-provider:
+    - zaimwa9
 
 ignored-authors:
   - renovate-bot

.release-please-manifest.json

@@ -2,5 +2,6 @@
   "providers/openfeature-flagd-provider": "0.1.2",
   "providers/openfeature-flipt-provider": "0.0.2",
   "providers/openfeature-meta_provider": "0.0.5",
-  "providers/openfeature-go-feature-flag-provider": "0.1.7"
+  "providers/openfeature-go-feature-flag-provider": "0.1.7",
+  "providers/openfeature-flagsmith-provider": "0.1.0"
 }

providers/openfeature-flagsmith-provider/.context.md

@@ -0,0 +1,316 @@
+# Flagsmith OpenFeature Provider - Context
+
+**Started:** 2025-11-17
+**Full Design Doc:** `./FLAGSMITH_PROVIDER_DESIGN.md`
+
+---
+
+## Quick Facts
+
+**What we're building:** OpenFeature provider for Flagsmith Ruby SDK
+**Target Flagsmith version:** Upcoming release (TBD)
+
+---
+
+## Key Design Decisions ✅
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Evaluation mode | Remote (default) | Simpler, no polling. Local available via config |
+| No targeting_key | Fall back to environment flags | `get_environment_flags()` vs `get_identity_flags()` |
+| Analytics | Opt-in (disabled default) | Privacy-first approach |
+| Default values | Use OpenFeature's default_value | Match other providers, no custom handler |
+| Configuration | Options object pattern | Clear validation, like GO Feature Flag |
+
+---
+
+## Architecture Map
+
+### Directory Structure
+```
+openfeature-flagsmith-provider/
+├── lib/openfeature/flagsmith/
+│   ├── provider.rb           # Main provider class
+│   ├── configuration.rb      # Options/config with validation
+│   ├── error/errors.rb       # Custom exceptions → ErrorCode mapping
+│   └── version.rb           # VERSION constant
+├── spec/                     # RSpec tests with WebMock
+├── openfeature-flagsmith-provider.gemspec
+└── README.md
+```
+
+### Key Classes
+
+**Configuration** (lib/openfeature/flagsmith/configuration.rb):
+```ruby
+OpenFeature::Flagsmith::Configuration.new(
+  environment_key: "required",
+  api_url: "https://edge.api.flagsmith.com/api/v1/",
+  enable_local_evaluation: false,
+  request_timeout_seconds: 10,
+  enable_analytics: false
+)
+```
+
+**Provider** (lib/openfeature/flagsmith/provider.rb):
+```ruby
+class Provider
+  attr_reader :metadata
+
+  # Required methods:
+  def fetch_boolean_value(flag_key:, default_value:, evaluation_context:)
+  def fetch_string_value(flag_key:, default_value:, evaluation_context:)
+  def fetch_number_value(flag_key:, default_value:, evaluation_context:)
+  def fetch_integer_value(flag_key:, default_value:, evaluation_context:)
+  def fetch_float_value(flag_key:, default_value:, evaluation_context:)
+  def fetch_object_value(flag_key:, default_value:, evaluation_context:)
+end
+```
+
+---
+
+## Critical Mappings
+
+### 1. Context → Identity/Traits
+```ruby
+# OpenFeature → Flagsmith
+evaluation_context.targeting_key → identifier (for get_identity_flags)
+evaluation_context.fields       → traits (as keyword args)
+
+# If no targeting_key → use get_environment_flags()
+```
+
+### 2. Flag Types
+| Flagsmith | OpenFeature Method | Implementation |
+|-----------|-------------------|----------------|
+| `is_feature_enabled()` → Boolean | `fetch_boolean_value` | Direct mapping |
+| `get_feature_value()` → String | `fetch_string_value` | Direct return |
+| `get_feature_value()` → Number | `fetch_number_value` | Parse & validate type |
+| `get_feature_value()` → JSON | `fetch_object_value` | `JSON.parse()` |
+
+### 3. Reason Mapping
+| Situation | OpenFeature Reason |
+|-----------|-------------------|
+| Flag evaluated with identity | `TARGETING_MATCH` |
+| Flag evaluated at environment level | `STATIC` |
+| Flag not found | `DEFAULT` |
+| Flag exists but disabled | `DISABLED` |
+| Error occurred | `ERROR` |
+
+### 4. Error Handling
+```ruby
+# Pattern: Always return ResolutionDetails with default_value on error
+SDK::Provider::ResolutionDetails.new(
+  value: default_value,
+  error_code: <appropriate ErrorCode>,
+  error_message: "description",
+  reason: SDK::Provider::Reason::ERROR
+)
+```
+
+**ErrorCode mapping:**
+- Flag not found → `FLAG_NOT_FOUND`
+- Wrong type → `TYPE_MISMATCH`
+- Network error → `PROVIDER_NOT_READY` or `GENERAL`
+- Invalid context → `INVALID_CONTEXT`
+
+---
+
+## Flagsmith SDK API Reference
+
+### Initialization
+```ruby
+require "flagsmith"
+client = Flagsmith::Client.new(
+  environment_key: "key",
+  api_url: "url",
+  enable_local_evaluation: false,
+  request_timeout_seconds: 10,
+  enable_analytics: false
+)
+```
+
+### Evaluation Methods
+```ruby
+# Environment-level (no user)
+flags = client.get_environment_flags()
+flags.is_feature_enabled('flag_key')  # → Boolean
+flags.get_feature_value('flag_key')   # → String/value
+
+# Identity-specific (with user context)
+flags = client.get_identity_flags('user@example.com', trait1: 'value', age: 30)
+flags.is_feature_enabled('flag_key')
+flags.get_feature_value('flag_key')
+```
+
+---
+
+## OpenFeature Provider Contract
+
+### Required Interface
+```ruby
+# Metadata
+attr_reader :metadata  # ProviderMetadata.new(name: "Flagsmith Provider")
+
+# Lifecycle (optional)
+def init       # Optional initialization
+def shutdown   # Optional cleanup
+
+# Evaluation methods (required)
+def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+```
+
+### Return Type
+```ruby
+OpenFeature::SDK::Provider::ResolutionDetails.new(
+  value: <evaluated_value>,          # Required
+  reason: <Reason constant>,         # Required
+  variant: "variant_key",            # Optional
+  flag_metadata: {key: "value"},     # Optional
+  error_code: <ErrorCode constant>,  # If error
+  error_message: "details"           # If error
+)
+```
+
+---
+
+## Code Patterns to Follow
+
+### Type Validation Pattern
+```ruby
+def evaluate(flag_key:, default_value:, allowed_classes:, evaluation_context:)
+  # ... get value from Flagsmith ...
+
+  unless allowed_classes.include?(value.class)
+    return SDK::Provider::ResolutionDetails.new(
+      value: default_value,
+      error_code: SDK::Provider::ErrorCode::TYPE_MISMATCH,
+      error_message: "Expected #{allowed_classes}, got #{value.class}",
+      reason: SDK::Provider::Reason::ERROR
+    )
+  end
+
+  # return success ResolutionDetails
+end
+```
+
+### Error Rescue Pattern
+```ruby
+begin
+  # Flagsmith evaluation
+rescue SomeError => e
+  return SDK::Provider::ResolutionDetails.new(
+    value: default_value,
+    error_code: SDK::Provider::ErrorCode::GENERAL,
+    error_message: e.message,
+    reason: SDK::Provider::Reason::ERROR
+  )
+end
+```
+
+---
+
+## Dependencies
+
+### Runtime
+```ruby
+spec.add_runtime_dependency "openfeature-sdk", "~> 0.3.1"
+spec.add_runtime_dependency "flagsmith", "~> <VERSION_TBD>"
+```
+
+### Development
+```ruby
+spec.add_development_dependency "rake", "~> 13.0"
+spec.add_development_dependency "rspec", "~> 3.12.0"
+spec.add_development_dependency "webmock", "~> 3.0"  # Mock Flagsmith calls
+spec.add_development_dependency "standard"
+spec.add_development_dependency "rubocop"
+spec.add_development_dependency "simplecov"
+```
+
+---
+
+## Testing Strategy
+
+### Mock Flagsmith Responses
+```ruby
+# Use WebMock to stub Flagsmith API calls
+# OR stub Flagsmith::Client methods directly
+
+allow(flagsmith_client).to receive(:get_identity_flags).and_return(mock_flags)
+allow(mock_flags).to receive(:is_feature_enabled).and_return(true)
+allow(mock_flags).to receive(:get_feature_value).and_return("value")
+```
+
+### Test Coverage Areas
+- ✅ Metadata verification
+- ✅ Configuration validation
+- ✅ Each flag type evaluation (boolean, string, number, integer, float, object)
+- ✅ Type mismatches
+- ✅ Missing flags (return default)
+- ✅ Error handling
+- ✅ Context mapping (with/without targeting_key)
+- ✅ Environment vs Identity evaluation
+
+---
+
+## Implementation Checklist
+
+- [ ] Directory structure created
+- [ ] Gemspec with dependencies
+- [ ] Configuration class with validation
+- [ ] Provider skeleton with metadata
+- [ ] Context → Identity/Traits mapping helper
+- [ ] `fetch_boolean_value` implementation
+- [ ] `fetch_string_value` implementation
+- [ ] `fetch_number_value` implementation
+- [ ] `fetch_integer_value` implementation
+- [ ] `fetch_float_value` implementation
+- [ ] `fetch_object_value` implementation
+- [ ] Error handling and custom exceptions
+- [ ] Type validation
+- [ ] RSpec test suite
+- [ ] README with examples
+- [ ] Release configuration
+
+---
+
+## Open Items / Notes
+
+- **Flagsmith version**: Waiting for upcoming release - update gemspec when available
+- **Variant support**: Flagsmith doesn't have explicit variants - TBD how to handle
+- **Flag metadata**: Flagsmith has limited metadata - may need to extract from traits/response
+
+---
+
+## Quick Commands
+
+```bash
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Install locally for testing
+gem build openfeature-flagsmith-provider.gemspec
+gem install ./openfeature-flagsmith-provider-<version>.gem
+
+# Test with real Flagsmith
+# (add example script in spec/manual_test.rb)
+```
+
+---
+
+## References
+
+- Full design doc: `../FLAGSMITH_PROVIDER_DESIGN.md`
+- Flagsmith docs: https://docs.flagsmith.com/clients/server-side
+- OpenFeature spec: https://openfeature.dev/specification/
+- GO Feature Flag provider: `../openfeature-go-feature-flag-provider/`
+- flagd provider: `../openfeature-flagd-provider/`

providers/openfeature-flagsmith-provider/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

providers/openfeature-flagsmith-provider/.rspec

@@ -0,0 +1,4 @@
+-I lib
+--format documentation
+--color
+--require spec_helper

providers/openfeature-flagsmith-provider/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_from: ../../shared_config/.rubocop.yml
+
+inherit_mode:
+  merge:
+    - Exclude

providers/openfeature-flagsmith-provider/.ruby-version

@@ -0,0 +1 @@
+3.1.4

providers/openfeature-flagsmith-provider/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial implementation of Flagsmith OpenFeature provider
+- Support for all OpenFeature flag types (boolean, string, number, integer, float, object)
+- Remote and local evaluation modes
+- Environment-level and identity-specific flag evaluation
+- Comprehensive error handling and type validation