From d2a898c5f757e79d9b7757ee3a8065bb2c7e8ec6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Chalifour?= Date: Fri, 6 Nov 2026 16:19:35 +0100 Subject: [PATCH 1/3] Deprecate analytics environment routing --- CHANGELOG.md | 4 ++++ README.md | 24 ++++++++++++++++++++---- lib/altertable/client.rb | 25 ++++++++++++++++++++----- rbi/altertable.rbi | 1 + sig/altertable/client.rbs | 2 +- spec/altertable/client_audience_spec.rb | 6 ++++-- spec/altertable/client_batch_spec.rb | 23 +++++++++++++++++++---- 7 files changed, 69 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 20c5aee..1492a31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ * Add `mode: :audience` to collect events without identity fields. Product mode remains the default. +### Changed + +* Deprecated `environment` constructor arguments are accepted and ignored; the Product Analytics API key selects the environment, and unbound keys must be replaced before upgrading. + ## [1.3.0](https://github.com/altertable-ai/altertable-ruby/compare/altertable/v1.2.0...altertable/v1.3.0) (2026-09-04) diff --git a/README.md b/README.md index 1505793..c1473cc 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Initialize the client and track your first event. Call `track()` to record an ac require 'altertable' # Initialize the Altertable client -Altertable.init('pk_live_abc123', environment: 'production') +Altertable.init('pk_live_abc123') # Track an event Altertable.track('button_clicked', 'user_123', properties: { @@ -40,7 +40,7 @@ Initialize the global Altertable client instance. `Altertable.init(api_key, options = {})` ```ruby -Altertable.init('pk_live_abc123', environment: 'production', debug: true) +Altertable.init('pk_live_abc123', debug: true) ``` ### Tracking Events @@ -79,7 +79,7 @@ Altertable.track('Docs Opened', properties: { section: 'installation' }) ``` Audience events send only `event`, `timestamp`, and `properties`; distinct, anonymous, -device, session, and environment fields are dropped. `identify` and `alias` are ignored. +device, and session fields are dropped. `identify` and `alias` are ignored. Requests come from your server, so they cannot distinguish browser visitors. ### Identifying Users @@ -128,7 +128,7 @@ You can configure the client by passing options during initialization. | Option | Type | Default | Description | |---|---|---|---| | `mode` | Symbol, String | `:product` | Collection mode: `:product` or `:audience`. Fixed for the client lifetime. | -| `environment` | String | `"production"` | Product environment name (e.g., `production`, `development`). Omitted in audience mode; the API key selects its environment. | +| `environment` | String | — | Deprecated and ignored. It is accepted for compatibility but never sent; use an environment-bound Product Analytics API key. | | `base_url` | String | `"https://api.altertable.ai"` | Base URL for API requests. | | `request_timeout` | Integer | `5` | Request timeout in seconds. | | `release` | String | `nil` | Application release version (e.g., commit hash). | @@ -137,6 +137,22 @@ You can configure the client by passing options during initialization. | `adapter` | Symbol | auto-detect | HTTP adapter to use (`:faraday`, `:httpx`, `:net_http`). | | `proxy` | String, Boolean | adapter default | Proxy to use for requests. Pass a URI string to force a specific proxy, or `false` to disable proxying (including any `HTTP_PROXY`/`HTTPS_PROXY` environment variables) for a fixed, trusted `base_url`. Unset by default: the `:faraday` and `:net_http` adapters auto-detect a proxy from the environment as they normally would; `:httpx` never does. | +### Migrating from `environment` + +Create or select a Product Analytics API key bound to the target environment, then +remove `environment:` from initialization. The SDK still accepts the option during +the transition, including hash and batch event inputs, but ignores it and omits the +top-level field from every request. A legacy unbound key cannot deliver after this +migration because the backend has no environment to select. + +```ruby +# Before +Altertable.init('legacy-key', environment: 'staging') + +# After +Altertable.init('staging-environment-bound-key') +``` + ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). diff --git a/lib/altertable/client.rb b/lib/altertable/client.rb index 8e822e7..634629c 100644 --- a/lib/altertable/client.rb +++ b/lib/altertable/client.rb @@ -9,6 +9,8 @@ module Altertable class Client DEFAULT_BASE_URL = "https://api.altertable.ai" DEFAULT_TIMEOUT = 5 + # @deprecated Environments are selected by the Product Analytics API key. + # Retained so applications that reference the public constant continue to load. DEFAULT_ENVIRONMENT = "production" def initialize(api_key, options = {}) @@ -22,7 +24,7 @@ def initialize(api_key, options = {}) end @api_key = api_key @base_url = options[:base_url] || DEFAULT_BASE_URL - @environment = options[:environment] || DEFAULT_ENVIRONMENT + warn "[Altertable] The environment is determined by your API key. Remove the :environment option." if options.key?(:environment) && options[:debug] @timeout = options[:request_timeout] || DEFAULT_TIMEOUT @release = options[:release] @debug = options[:debug] || false @@ -178,7 +180,6 @@ def track_payload(event, distinct_id, options) payload = { timestamp: options[:timestamp] || default_timestamp, event: event, - environment: @environment, distinct_id: distinct_id, properties: { '$lib': "altertable-ruby", @@ -201,7 +202,6 @@ def audience_payload(payload) def identify_payload(user_id, options) payload = { timestamp: options[:timestamp] || default_timestamp, - environment: @environment, distinct_id: user_id, traits: options[:traits] || {} } @@ -213,19 +213,34 @@ def identify_payload(user_id, options) def alias_payload(distinct_id, new_user_id, options) { timestamp: options[:timestamp] || default_timestamp, - environment: @environment, distinct_id: distinct_id, new_user_id: new_user_id } end def post(path, payload) - res = @adapter.post(path, body: payload.to_json) + res = @adapter.post(path, body: remove_deprecated_environment(payload).to_json) handle_response(res) rescue StandardError => e handle_error(e) end + # Keep accepting legacy payload hashes, but never let their top-level routing + # field reach the API. Properties named "environment" remain event data. + def remove_deprecated_environment(payload) + case payload + when Array + payload.map { |item| remove_deprecated_environment(item) } + when Hash + payload.dup.tap do |item| + item.delete(:environment) + item.delete("environment") + end + else + payload + end + end + def handle_response(res) case res.status when 200..299 diff --git a/rbi/altertable.rbi b/rbi/altertable.rbi index c4b2415..0807d17 100644 --- a/rbi/altertable.rbi +++ b/rbi/altertable.rbi @@ -29,6 +29,7 @@ module Altertable class Client DEFAULT_BASE_URL = T.let(T.unsafe(nil), String) DEFAULT_TIMEOUT = T.let(T.unsafe(nil), Integer) + # @deprecated Environments are selected by the Product Analytics API key. DEFAULT_ENVIRONMENT = T.let(T.unsafe(nil), String) sig { params(api_key: String, options: T::Hash[Symbol, T.untyped]).void } diff --git a/sig/altertable/client.rbs b/sig/altertable/client.rbs index 5b96428..72aaa72 100644 --- a/sig/altertable/client.rbs +++ b/sig/altertable/client.rbs @@ -3,7 +3,6 @@ module Altertable @mode: :product | :audience @api_key: String @base_url: String - @environment: String @timeout: Integer | Float @release: String? @debug: bool @@ -12,6 +11,7 @@ module Altertable DEFAULT_BASE_URL: String DEFAULT_TIMEOUT: Integer + # @deprecated Environments are selected by the Product Analytics API key. DEFAULT_ENVIRONMENT: String def initialize: (String api_key, ?::Hash[Symbol, untyped] options) -> void diff --git a/spec/altertable/client_audience_spec.rb b/spec/altertable/client_audience_spec.rb index 8bcd2ad..e337f53 100644 --- a/spec/altertable/client_audience_spec.rb +++ b/spec/altertable/client_audience_spec.rb @@ -88,7 +88,8 @@ def expect_audience(payload) product = build_client(mode: mode, environment: "staging") product.track("Opened", "user", anonymous_id: "anon", device_id: "device", mode: :audience, properties: { "$url" => "https://site.example/?private=yes", "$viewport" => "100x100" }) - expect(calls.last[:body]).to include("distinct_id" => "user", "anonymous_id" => "anon", "device_id" => "device", "environment" => "staging") + expect(calls.last[:body]).to include("distinct_id" => "user", "anonymous_id" => "anon", "device_id" => "device") + expect(calls.last[:body]).not_to have_key("environment") expect(calls.last[:body]).not_to have_key("mode") expect(calls.last[:body]["properties"]).to include("$url" => "https://site.example/?private=yes", "$viewport" => "100x100") expect { product.track({ event: "No ID" }) }.to raise_error(ArgumentError, /distinct_id/) @@ -102,7 +103,8 @@ def expect_audience(payload) it "defaults to product mode" do build_client.track("Opened", "user") - expect(calls.last[:body]).to include("distinct_id" => "user", "environment" => "production") + expect(calls.last[:body]).to include("distinct_id" => "user") + expect(calls.last[:body]).not_to have_key("environment") expect(calls.last[:body]).not_to have_key("mode") end diff --git a/spec/altertable/client_batch_spec.rb b/spec/altertable/client_batch_spec.rb index 44311b8..3d5a590 100644 --- a/spec/altertable/client_batch_spec.rb +++ b/spec/altertable/client_batch_spec.rb @@ -41,7 +41,6 @@ def post(path, body: nil, params: {}) expect(payload).to include( "event" => "signup", "distinct_id" => "u1", - "environment" => "production", "timestamp" => "2025-06-15T14:30:00.000Z" ) expect(payload["properties"]).to include("plan" => "pro", "$lib" => "altertable-ruby") @@ -75,7 +74,6 @@ def post(path, body: nil, params: {}) expect(payloads[0]).to include( "event" => "signup", "distinct_id" => "u1", - "environment" => "production", "timestamp" => "2025-06-15T14:30:00.000Z" ) expect(payloads[0]["properties"]).to include("plan" => "pro", "$lib" => "altertable-ruby", "$lib_version" => Altertable::VERSION, "$release" => "1.2.3") @@ -161,7 +159,6 @@ def post(path, body: nil, params: {}) payloads = adapter.calls.first[:body] expect(payloads[0]).to include( "distinct_id" => "u1", - "environment" => "production", "timestamp" => "2025-06-15T14:30:00.000Z" ) expect(payloads[0]["traits"]).to include("email" => "a@example.com") @@ -210,7 +207,6 @@ def post(path, body: nil, params: {}) expect(payloads[0]).to include( "distinct_id" => "anon-1", "new_user_id" => "u1", - "environment" => "production", "timestamp" => "2025-06-15T14:30:00.000Z" ) expect(payloads[1]).to include("distinct_id" => "anon-2", "new_user_id" => "u2") @@ -232,4 +228,23 @@ def post(path, body: nil, params: {}) expect(adapter.calls.first[:body].first).to include("distinct_id" => "anon-1", "new_user_id" => "u1") end end + + it "accepts deprecated environments without sending them for scalar, hash, and batch calls" do + deprecated = nil + expect { deprecated = described_class.new(api_key, environment: "staging", debug: true) } + .to output(/environment is determined by your API key/).to_stderr + deprecated.instance_variable_set(:@adapter, adapter) + + deprecated.track("Scalar", "u1", environment: "event") + deprecated.track({ event: "Hash", distinct_id: "u2", environment: "hash", properties: { environment: "business" } }) + deprecated.track([{ event: "Batch", distinct_id: "u3", "environment" => "batch" }]) + deprecated.identify([{ user_id: "u1", environment: "identify" }]) + deprecated.alias([{ distinct_id: "old", new_user_id: "new", environment: "alias" }]) + + adapter.calls.each do |call| + payloads = call[:body].is_a?(Array) ? call[:body] : [call[:body]] + payloads.each { |payload| expect(payload).not_to have_key("environment") } + end + expect(adapter.calls[1][:body]["properties"]).to include("environment" => "business") + end end From 7a452ea6e5080992176d6e2188e8f3a9df1b3d81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Chalifour?= Date: Mon, 9 Nov 2026 14:31:16 +0100 Subject: [PATCH 2/3] refactor: drop unreachable environment stripping and migration guide Payload builders select fields explicitly, so environment cannot reach the wire once the client stops adding it. Migration guidance belongs on the docs site. --- CHANGELOG.md | 2 +- README.md | 16 ---------------- lib/altertable/client.rb | 18 +----------------- 3 files changed, 2 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1492a31..d2f68a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ ### Changed -* Deprecated `environment` constructor arguments are accepted and ignored; the Product Analytics API key selects the environment, and unbound keys must be replaced before upgrading. +* Deprecate the `environment` option: it is ignored and no longer sent. Use an environment-bound Product Analytics API key. ## [1.3.0](https://github.com/altertable-ai/altertable-ruby/compare/altertable/v1.2.0...altertable/v1.3.0) (2026-09-04) diff --git a/README.md b/README.md index c1473cc..c647d1b 100644 --- a/README.md +++ b/README.md @@ -137,22 +137,6 @@ You can configure the client by passing options during initialization. | `adapter` | Symbol | auto-detect | HTTP adapter to use (`:faraday`, `:httpx`, `:net_http`). | | `proxy` | String, Boolean | adapter default | Proxy to use for requests. Pass a URI string to force a specific proxy, or `false` to disable proxying (including any `HTTP_PROXY`/`HTTPS_PROXY` environment variables) for a fixed, trusted `base_url`. Unset by default: the `:faraday` and `:net_http` adapters auto-detect a proxy from the environment as they normally would; `:httpx` never does. | -### Migrating from `environment` - -Create or select a Product Analytics API key bound to the target environment, then -remove `environment:` from initialization. The SDK still accepts the option during -the transition, including hash and batch event inputs, but ignores it and omits the -top-level field from every request. A legacy unbound key cannot deliver after this -migration because the backend has no environment to select. - -```ruby -# Before -Altertable.init('legacy-key', environment: 'staging') - -# After -Altertable.init('staging-environment-bound-key') -``` - ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). diff --git a/lib/altertable/client.rb b/lib/altertable/client.rb index 634629c..2742564 100644 --- a/lib/altertable/client.rb +++ b/lib/altertable/client.rb @@ -219,28 +219,12 @@ def alias_payload(distinct_id, new_user_id, options) end def post(path, payload) - res = @adapter.post(path, body: remove_deprecated_environment(payload).to_json) + res = @adapter.post(path, body: payload.to_json) handle_response(res) rescue StandardError => e handle_error(e) end - # Keep accepting legacy payload hashes, but never let their top-level routing - # field reach the API. Properties named "environment" remain event data. - def remove_deprecated_environment(payload) - case payload - when Array - payload.map { |item| remove_deprecated_environment(item) } - when Hash - payload.dup.tap do |item| - item.delete(:environment) - item.delete("environment") - end - else - payload - end - end - def handle_response(res) case res.status when 200..299 From 2c16d9bbeb504582e916cfbd739e119392869fba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Chalifour?= Date: Mon, 9 Nov 2026 15:04:45 +0100 Subject: [PATCH 3/3] refactor: drop environment deprecation warning --- lib/altertable/client.rb | 1 - spec/altertable/client_batch_spec.rb | 3 +-- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/lib/altertable/client.rb b/lib/altertable/client.rb index 2742564..bbda2d1 100644 --- a/lib/altertable/client.rb +++ b/lib/altertable/client.rb @@ -24,7 +24,6 @@ def initialize(api_key, options = {}) end @api_key = api_key @base_url = options[:base_url] || DEFAULT_BASE_URL - warn "[Altertable] The environment is determined by your API key. Remove the :environment option." if options.key?(:environment) && options[:debug] @timeout = options[:request_timeout] || DEFAULT_TIMEOUT @release = options[:release] @debug = options[:debug] || false diff --git a/spec/altertable/client_batch_spec.rb b/spec/altertable/client_batch_spec.rb index 3d5a590..66c7620 100644 --- a/spec/altertable/client_batch_spec.rb +++ b/spec/altertable/client_batch_spec.rb @@ -231,8 +231,7 @@ def post(path, body: nil, params: {}) it "accepts deprecated environments without sending them for scalar, hash, and batch calls" do deprecated = nil - expect { deprecated = described_class.new(api_key, environment: "staging", debug: true) } - .to output(/environment is determined by your API key/).to_stderr + expect { deprecated = described_class.new(api_key, environment: "staging", debug: true) }.not_to output.to_stderr deprecated.instance_variable_set(:@adapter, adapter) deprecated.track("Scalar", "u1", environment: "event")