shipeasy-sdk (Ruby)

Server SDK for Shipeasy — feature flags, dynamic configs, kill switches, A/B experiments, and metric tracking, with Rails i18n view helpers. Server-key only; never embed in a browser.

📚 Full documentation: https://shipeasy-ai.github.io/sdk-ruby/ — also browsable under docs/. This README is generated from those docs.

Source-available under the Shipeasy-SAL 1.0.

🤖 Using an AI agent?

This SDK ships an installable agent skill — a copy-paste-ready guide to Shipeasy.configure + Client.new(user), testing, experiments, error reporting, and more, with links the agent can pull for deeper docs:

• Skill: docs/skill/SKILL.md · raw: https://shipeasy-ai.github.io/sdk-ruby/skill/SKILL.md
• Install it (ships with the gem — no network): shipeasy-skill install → .claude/skills/shipeasy-ruby/SKILL.md (or via the Shipeasy CLI: shipeasy docs skill --sdk ruby --install)

Humans: you can copy that skill straight into your own project's agent skills directory (e.g. .claude/skills/shipeasy-ruby/SKILL.md) so your coding agent always uses the correct Shipeasy patterns. Every doc page and snippet is also fetchable by URL — start from the manifest at https://shipeasy-ai.github.io/sdk-ruby/manifest.json.

Install

# Gemfile
gem "shipeasy-sdk"

Requires Ruby 3.0+. Per-framework setup (Rails / Sinatra / serverless) and the anon-id middleware are on the Installation page.

Quickstart — configure once, then Client.new(user) per request

# boot (config/initializers/shipeasy.rb)
Shipeasy.configure do |c|
  c.api_key    = ENV.fetch("SHIPEASY_SERVER_KEY")
  c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
end

# per request — construct once per callsite (cheap; binds the user)
flags = Shipeasy::Client.new(current_user)

flags.get_flag("new_checkout")                       # NO user arg — bound at construction
flags.get_config("button_color")
assignment = flags.universe("checkout").assign       # <=1 experiment; auto-logs exposure
assignment.get("label", "Buy")                       # variant ?? universe default ?? fallback
flags.track("purchase", { revenue: 49 })             # on conversion
flags.get_killswitch("payments")

Constructing Shipeasy::Client.new(user) before Shipeasy.configure raises Shipeasy::Error.

Documentation

Page	What
Overview	The Shipeasy.configure + Client.new(user) model.
Installation	Install, frameworks (Rails / Sinatra / serverless), configure wiring.
Configuration	Keys, attributes, one-shot vs poll, every option.
Feature flags	get_flag, get_flag_detail, defaults.
Dynamic configs	get_config, typed decode, defaults.
Kill switches	get_killswitch, named switches.
Experiments	universe(name).assign, Assignment#get, track.
Internationalization	Rails view helpers + the SSR loader tag.
Error reporting	see() structured error reporting.
Testing

Copy-paste snippets live under docs/snippets/ (release · metrics · i18n · ops); an installable agent skill is at docs/skill/SKILL.md.

Testing

Use Shipeasy.configure_for_testing — the test-mode sibling of Shipeasy.configure. It does zero network, needs no api key, and seeds the values your code under test should see via override arguments. Then read through the ordinary Shipeasy::Client.new(user) — the same call your production code uses.

require "shipeasy-sdk"

Shipeasy.configure_for_testing(
  flags:       { "new_checkout" => true },
  configs:     { "billing_copy" => { "title" => "Welcome" } },
  experiments: { "checkout_button" => ["treatment", { "color" => "green" }] },
)

# construct once per callsite (cheap; binds the user)
client = Shipeasy::Client.new({ "user_id" => "u_123" })

client.get_flag("new_checkout")              # => true
client.get_config("billing_copy")            # => { "title" => "Welcome" }

# An experiment override surfaces through universe(name).assign once the loaded
# blob maps that experiment to its universe (an offline snapshot does this; a
# bare configure_for_testing has no blob). Read via the universe:
assignment = client.universe("checkout").assign
assignment.enrolled?                         # => true
assignment.group                             # => "treatment"
assignment.get("color")                      # => "green"

# track / assign exposures are no-ops in test mode — safe to call, send nothing
client.track("purchase", { amount: 49 })

More — the on-the-spot override helpers and a working example shipeasy-snapshot.json — on the Testing page.

License

Shipeasy-SAL 1.0 — source-available, non-commercial-use, permitted as a Shipeasy client. Evaluation is tested against the cross-language MurmurHash3 vectors in Rollouts & bucketing.