flagdash 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3fdf5074eeb7ba8c22b3a292be35ddd6fd8cabd0e6e81205d3da171435363534
+  data.tar.gz: 36dd77ce355adba2e9d4d1efb20e8301372789f09dd91e3cf6e44230e572e1a4
+SHA512:
+  metadata.gz: 9beb6ee3cd7499008d39b34bf4fe54e7481664bd2eec5805b15dfd317020114a1da3373b032c6450ac191b1fdd954031bbb63a77c96af4c71ed5758c8a4a5da5
+  data.tar.gz: 4d963f879cd9650135a689dfed75f5f1f018b7edd6a7d5bfe8d60b722d1523ecf7120f40c8d313d17ce9ba82435fe883c4788b6afaf5fdb06344d121a71ecd03

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 FlagDash
+
+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,187 @@
+# FlagDash Ruby SDK
+
+Feature flags, remote config, AI configs, translations and experiments for
+Ruby 3.1+.
+
+Standard library only — no runtime dependencies.
+
+## Installation
+
+```ruby
+gem "flagdash"
+```
+
+Or straight from GitHub, pinned to an immutable tag:
+
+```ruby
+gem "flagdash", github: "flagdash/flagdash-ruby", tag: "v0.1.0"
+```
+
+## Quick start
+
+```ruby
+require "flagdash"
+
+client = FlagDash::Client.new(sdk_key: ENV.fetch("FLAGDASH_SDK_KEY"))
+
+if client.flag("checkout-v2", default: false, context: {user_id: "alice"})
+  # new checkout
+end
+
+client.close
+```
+
+## API key tiers
+
+The key decides which project and environment you read, and what you may
+reach. There is no `environment` argument anywhere in this SDK — the key
+carries it.
+
+| Key | Prefix | Reaches |
+|---|---|---|
+| Client | `pk_` | Flag values and configs. Safe in a browser or mobile app. |
+| Server | `sk_` | The above, plus targeting rules, translations and experiments. Keep it server-side. |
+
+## Configuration
+
+```ruby
+client = FlagDash::Client.new(
+  sdk_key:   ENV.fetch("FLAGDASH_SDK_KEY"),
+  base_url:  "https://flagdash.io",  # self-hosted? point it here
+  timeout:   5,                      # seconds per request
+  cache_ttl: 60,                     # seconds; 0 disables caching
+  region:    "eu-west-1",            # omit to auto-detect
+  transport: nil                     # inject for tests
+)
+```
+
+`region` is detected from `FLY_REGION`, `AWS_REGION` and friends when omitted,
+so region-scoped targeting works with no wiring.
+
+## Feature flags
+
+```ruby
+# One flag, with the fallback used whenever FlagDash cannot be reached.
+client.flag("checkout-v2", default: false, context: {user_id: "alice"})
+
+# Every flag for this context in one request.
+client.all_flags(context: {user_id: "alice", country: "GB"})
+
+# Why did it resolve that way?
+detail = client.flag_detail("checkout-v2", context: {user_id: "alice"})
+detail.value      # => true
+detail.reason     # => "rule_match"
+detail.variation  # => "treatment"
+
+# Flag metadata without evaluating anything.
+client.list_flags
+```
+
+### Context
+
+Both shapes work. A nested `user:` hash is flattened — `id` becomes `user_id`
+and every other key becomes `user_<key>`:
+
+```ruby
+client.flag("beta", context: {user_id: "alice", country: "GB"})
+client.flag("beta", context: {user: {id: "alice", plan: "premium"}})
+```
+
+**Send an identifier** (`user_id`, `unit_id`, or `user: {id:}`) whenever you
+want a stable answer. Percentage rollouts and A/B variations hash it, so an
+anonymous context re-rolls on every call by design.
+
+Note that `flag` without a context serves from the cached `all_flags` payload;
+with a context it asks for a fresh evaluation.
+
+## Remote config
+
+```ruby
+client.config("rate_limit", default: 100)
+client.get_config("rate_limit")   # full record, not just the value
+client.list_configs
+```
+
+## AI configs
+
+Prompts, agents, skills and rules, versioned per environment and editable
+without a deploy.
+
+```ruby
+client.ai_config("support-agent.md")
+client.list_ai_configs(file_type: "agent")
+client.list_ai_configs(folder: "support")   # :any for every folder
+```
+
+## Translations
+
+```ruby
+client.translation("checkout.greeting", locale: "fr", default: "Hello",
+                   variables: {name: "Alice"})
+```
+
+The key is `namespace.message`. `{placeholders}` come from `variables`, and the
+default is returned whenever the catalogue, namespace or message is missing — a
+lookup never raises.
+
+## Experiments
+
+```ruby
+assignment = client.experiment("checkout-redesign", context: {user_id: "alice"})
+
+if assignment && assignment["variant"] == "treatment"
+  # ...
+end
+
+client.track_experiment_metric(
+  experiment_key: "checkout-redesign",
+  event_name:     "purchase",
+  user_id:        "alice",
+  value:          42.50,
+  properties:     {currency: "GBP"}
+)
+```
+
+`experiment` returns `nil` for a context with no identifier — an assignment
+that cannot be stable is worse than none.
+
+Metrics are buffered in memory and only touch the network on `flush` or
+`close`:
+
+```ruby
+client.flush  # send now
+client.close  # flush and release the connection
+```
+
+In a long-running process call `flush` periodically; in a request/response
+cycle, `close` at the end is enough.
+
+## Caching
+
+Reads are cached in memory for `cache_ttl` seconds (60 by default), so a burst
+of `flag` calls costs one request.
+
+```ruby
+client.clear_cache
+```
+
+## Failure behaviour
+
+This SDK deliberately splits the two cases:
+
+- **Evaluation reads return your default.** `flag`, `config` and `translation`
+  degrade to the fallback rather than raising, so an outage cannot take a
+  request path down with it.
+- **Metadata lists raise.** `list_flags`, `list_configs` and `list_ai_configs`
+  are operational calls, and swallowing their failure would hide a bad key or a
+  wrong base URL behind an empty array.
+
+## Security
+
+Keep the server key out of anything you ship to a browser or a phone. Grant a
+key only the read scopes it needs; a client key never receives targeting rules,
+so the client cannot see who else you are targeting.
+
+## License
+
+MIT

data/lib/flagdash/version.rb

@@ -0,0 +1,3 @@
+module FlagDash
+  VERSION = "0.1.0"
+end

data/lib/flagdash.rb

@@ -0,0 +1,189 @@
+require "json"
+require "net/http"
+require "securerandom"
+require "time"
+require "uri"
+require_relative "flagdash/version"
+
+module FlagDash
+  Detail = Struct.new(:key, :value, :reason, :variation_key, keyword_init: true)
+
+  class Client
+    REGION_ENV = %w[FLAGDASH_REGION FLY_REGION AWS_REGION AWS_DEFAULT_REGION VERCEL_REGION GOOGLE_CLOUD_REGION RAILWAY_REPLICA_REGION RENDER_REGION].freeze
+
+    def initialize(sdk_key:, base_url: "https://flagdash.io", timeout: 5, cache_ttl: 60, region: nil, transport: nil)
+      raise ArgumentError, "sdk_key is required" if sdk_key.to_s.empty?
+
+      @sdk_key = sdk_key
+      @base_url = base_url.delete_suffix("/")
+      @timeout = timeout
+      @cache_ttl = cache_ttl
+      @region = region || REGION_ENV.filter_map { |name| ENV[name] }.first
+      @transport = transport || method(:http_request)
+      @cache = {}
+      @mutex = Mutex.new
+      @events = []
+    end
+
+    def flag(key, default: false, context: nil)
+      return flag_detail(key, default: default, context: context).value if context && !context.empty?
+
+      cached("flag:#{key}") { all_flags.fetch(key, default) }
+    end
+
+    def flag_detail(key, default: nil, context: nil)
+      data = request(:get, "/server/flags/#{segment(key)}", params: context_params(context))
+      flag = data.fetch("flag")
+      Detail.new(key: flag.fetch("key", key), value: flag.fetch("evaluated_value", default),
+                 reason: flag.fetch("evaluation_path", "default"), variation_key: flag["variation_key"])
+    rescue StandardError
+      Detail.new(key: key, value: default, reason: "default", variation_key: nil)
+    end
+
+    def all_flags(context: nil)
+      return fetch_flags(context) if context && !context.empty?
+
+      cached("all_flags") { fetch_flags(nil) }
+    end
+
+    def list_flags
+      request(:get, "/server/flags", params: context_params(nil)).fetch("flags", [])
+    end
+
+    def config(key, default: nil)
+      cached("config:#{key}") do
+        request(:get, "/server/configs/#{segment(key)}").fetch("config", {}).fetch("value", default)
+      end
+    rescue StandardError
+      default
+    end
+
+    def get_config(key)
+      request(:get, "/server/configs/#{segment(key)}")["config"]
+    end
+
+    def list_configs
+      request(:get, "/server/configs").fetch("configs", [])
+    end
+
+    def ai_config(file_name)
+      cached("ai:#{file_name}") { request(:get, "/server/ai-configs/#{segment(file_name)}")["ai_config"] }
+    rescue StandardError
+      nil
+    end
+
+    def list_ai_configs(file_type: nil, folder: :any)
+      request(:get, "/server/ai-configs").fetch("ai_configs", []).select do |item|
+        (!file_type || item["file_type"] == file_type.to_s) && (folder == :any || item["folder"] == folder)
+      end
+    end
+
+    def translation(key, locale:, default: nil, variables: {})
+      namespace, message = key.split(".", 2)
+      return default || key unless message
+
+      catalog = cached("translation:#{locale}:#{namespace}") do
+        request(:get, "/server/translations/#{segment(locale)}/#{segment(namespace)}").fetch("catalog", {})
+      end
+      pattern = catalog.fetch("messages", {})[message]
+      return default || key unless pattern
+
+      pattern.gsub(/\{([\w.]+)\}/) { |match| variables.fetch(Regexp.last_match(1), variables.fetch(Regexp.last_match(1).to_sym, match)).to_s }
+    rescue StandardError
+      default || key
+    end
+
+    def experiment(key, context:)
+      return nil unless identity(context)
+
+      request(:get, "/server/experiments/#{segment(key)}", params: context_params(context))["experiment"]
+    rescue StandardError
+      nil
+    end
+
+    def track_experiment_metric(experiment_key:, event_name:, user_id:, value: nil, properties: {}, event_id: nil, occurred_at: nil)
+      event = {event_id: event_id || "evt_#{SecureRandom.uuid}", experiment_key: experiment_key,
+               event_name: event_name, user_id: user_id, value: value, properties: properties,
+               occurred_at: occurred_at || Time.now.utc.iso8601}
+      @mutex.synchronize { @events << event if @events.length < 1_000 }
+      nil
+    end
+
+    def flush
+      loop do
+        batch = @mutex.synchronize { @events.first(100) }
+        break if batch.empty?
+
+        request(:post, "/server/experiment-events/batch", json: {events: batch})
+        @mutex.synchronize { @events.shift(batch.length) }
+      end
+      true
+    rescue StandardError
+      false
+    end
+
+    def clear_cache
+      @mutex.synchronize { @cache.clear }
+    end
+
+    def close
+      flush
+    end
+
+    private
+
+    def fetch_flags(context)
+      values = request(:get, "/server/flags", params: context_params(context)).fetch("evaluated", {})
+      @mutex.synchronize { values.each { |key, value| put_cache("flag:#{key}", value) } } unless context
+      values
+    end
+
+    def cached(key)
+      return yield if @cache_ttl.zero?
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      hit = @mutex.synchronize { @cache[key] }
+      return hit[0] if hit && hit[1] > now
+
+      value = yield
+      @mutex.synchronize { put_cache(key, value) }
+      value
+    end
+
+    def put_cache(key, value)
+      @cache[key] = [value, Process.clock_gettime(Process::CLOCK_MONOTONIC) + @cache_ttl]
+    end
+
+    def request(method, path, params: {}, json: nil)
+      @transport.call(method, "#{@base_url}/api/v1#{path}", params, json, @sdk_key, @timeout)
+    end
+
+    def http_request(method, url, params, json, key, timeout)
+      uri = URI(url)
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      request = method == :post ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{key}"
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(json) if json
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout, read_timeout: timeout) { |http| http.request(request) }
+      raise "FlagDash HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    end
+
+    def context_params(context)
+      result = (context || {}).transform_keys(&:to_s)
+      user = result.delete("user")
+      user&.each { |key, value| result[key.to_s == "id" ? "user_id" : "user_#{key}"] = value }
+      result["region"] ||= @region if @region
+      result
+    end
+
+    def identity(context)
+      context[:user_id] || context["user_id"] || context[:unit_id] || context["unit_id"] || context.dig(:user, :id) || context.dig("user", "id")
+    end
+
+    def segment(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: flagdash
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- FlagDash
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-25 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- support@flagdash.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/flagdash.rb
+- lib/flagdash/version.rb
+homepage: https://flagdash.com/docs#sdk-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/flagdash/flagdash-ruby
+  changelog_uri: https://github.com/flagdash/flagdash-ruby/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official server-side FlagDash SDK for Ruby
+test_files: []