altertable 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c5cf2ceb0732f00a0017795d33e2c28fe1b3c131bd443d3c00247eeddc88c25
-  data.tar.gz: 8941f4802ae2ee21517353ce0628420a70ffa3a823855d32d3d4daab62315b32
+  metadata.gz: 7472be3a607d8398965c62ed90f5531fe33b21d77fa4827bd73259d7a714eba5
+  data.tar.gz: 536319ad37e423c82ab298d5804aaf22de1563ece73226abaa42b5fd6bd93c39
 SHA512:
-  metadata.gz: ff9de77df94949d60e633985af119074276e334352ccce1fb510f2bb68f2acface25aaaaf256a3585118cccc3e79898386d226e3df036937f03bf0e5986ace7c
-  data.tar.gz: 0f7eafb061c8d266952cb6549c124e53fcc1b9c53e2c961fc8298eeefd91bd2b716b9cb681afcc93bf5632d20cac5e6ffbf32c93faad8849e618afd02b69512d
+  metadata.gz: 231d0b578dd8fe4ed8856d07fe233b4e256ce3650ce9a11260a21c01d352fcb9bc291477ab526c2d8984078caa4b879f92da667483af5e475d6ea08089999283
+  data.tar.gz: 7ba2dd340e96f6d906c44456032b6a959e0cfa3f106bf5bf42d2982ac710da4856e4fb1e6d028a030afab62a3ed702e5a27e9fbd920725ff3b4926da40e64e35

data/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -37,7 +37,7 @@ body:
   - type: input
     id: runtime
     attributes:
-      label: "{language} Version"
+      label: "Ruby Version"
     validations:
       required: true
   - type: dropdown

data/.github/workflows/ci.yml

@@ -3,16 +3,14 @@ name: CI
 on:
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
-
+  pull_request: {}
 jobs:
   lint:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
       - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1
         with:
           ruby-version: "3.4"
           bundler-cache: true
@@ -20,7 +18,7 @@ jobs:
         run: bundle exec rubocop
 
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         ruby-version: ["3.2", "3.3", "3.4", "4.0"]
@@ -40,12 +38,12 @@ jobs:
           --health-start-period 10s
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
           submodules: recursive
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1
         with:
           ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
@@ -55,11 +53,11 @@ jobs:
 
   typing:
     name: "Typing"
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
       - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1
         with:
           ruby-version: "3.4"
           bundler-cache: true

data/.github/workflows/release-please.yml

@@ -7,14 +7,14 @@ on:
 
 jobs:
   check:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     permissions:
       contents: write
       pull-requests: write
 
     steps:
-      - uses: googleapis/release-please-action@v4
+      - uses: googleapis/release-please-action@8b8fd2cc23b2e18957157a9d923d75aa0c6f6ad5 # v4
         id: release
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -29,7 +29,7 @@ jobs:
 
     if: ${{ needs.check.outputs.release_created }}
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     permissions:
       contents: write
@@ -37,11 +37,11 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
           persist-credentials: false
-      - uses: ruby/setup-ruby@v1
+      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1
         with:
           ruby-version: 3.4
           bundler-cache: true
-      - uses: rubygems/release-gem@v1
+      - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1

data/.github/workflows/semantic-pull-request.yml

@@ -1,4 +1,5 @@
 name: Semantic Pull Request
+
 on:
   pull_request_target:
     types:
@@ -6,11 +7,33 @@ on:
       - edited
       - synchronize
 
+permissions:
+  pull-requests: read
+
+concurrency:
+  group: semantic-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   main:
     name: Validate PR title
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
     steps:
-      - uses: amannn/action-semantic-pull-request@v5
+      - name: Validate pull request title
+        uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            perf
+            revert
+            docs
+            style
+            chore
+            refactor
+            test
+            build
+            ci

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.1.1"
+    ".": "1.2.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.2.0](https://github.com/altertable-ai/altertable-ruby/compare/altertable/v1.1.2...altertable/v1.2.0) (2026-08-27)
+
+
+### Features
+
+* **adapters:** support explicit proxy configuration ([#51](https://github.com/altertable-ai/altertable-ruby/issues/51)) ([309aa8f](https://github.com/altertable-ai/altertable-ruby/commit/309aa8f43c43f57cf87cf23a6d1034298612b0be))
+
+## [1.1.2](https://github.com/altertable-ai/altertable-ruby/compare/altertable/v1.1.1...altertable/v1.1.2) (2026-03-19)
+
+
+### Bug Fixes
+
+* **readme:** correct package name ([#33](https://github.com/altertable-ai/altertable-ruby/issues/33)) ([5838578](https://github.com/altertable-ai/altertable-ruby/commit/58385785e8849cda3627bdd04e563eadab933ba3))
+* **transport:** remove the hard dep on `faraday-retry` ([#42](https://github.com/altertable-ai/altertable-ruby/issues/42)) ([f758d02](https://github.com/altertable-ai/altertable-ruby/commit/f758d0254d86de2ea3d6105a429d885c6a8aadbf))
+
 ## [1.1.1](https://github.com/altertable-ai/altertable-ruby/compare/altertable/v1.1.0...altertable/v1.1.1) (2026-03-09)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    altertable (1.1.1)
+    altertable (1.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -25,8 +25,6 @@ GEM
       logger
     faraday-net_http (3.4.2)
       net-http (~> 0.5)
-    faraday-retry (2.4.0)
-      faraday (~> 2.0)
     http-2 (1.1.3)
     httpx (1.7.3)
       http-2 (>= 1.1.3)
@@ -144,8 +142,6 @@ DEPENDENCIES
   altertable!
   base64
   faraday (~> 2.0)
-  faraday-net_http
-  faraday-retry
   httpx
   rake (~> 13.0)
   rbs

data/README.md

@@ -1,55 +1,99 @@
 # Altertable Ruby SDK
 
+[![Build Status](https://github.com/altertable-ai/altertable-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/altertable-ai/altertable-ruby/actions)
+[![Gem Version](https://badge.fury.io/rb/altertable.svg)](https://rubygems.org/gems/altertable)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 Official Ruby SDK for Altertable Product Analytics.
 
-## Installation
+## Install
 
-Add this line to your application's Gemfile:
+Install the gem with a single command:
 
-```ruby
-gem 'altertable-ruby'
+```bash
+gem install altertable
 ```
 
-And then execute:
-
-    $ bundle install
-
-## Usage
+## Quick Start
 
-### Initialization
+Initialize the client and track your first event. Call `track()` to record an action a user performed.
 
 ```ruby
 require 'altertable'
 
-Altertable.init('your_api_key', {
-  environment: 'production'
+# Initialize the Altertable client
+Altertable.init('pk_live_abc123', environment: 'production')
+
+# Track an event
+Altertable.track('button_clicked', 'user_123', properties: {
+  button_id: 'signup_btn',
+  page: 'home'
 })
 ```
 
+## API Reference
+
+### Initialization
+
+Initialize the global Altertable client instance.
+
+`Altertable.init(api_key, options = {})`
+
+```ruby
+Altertable.init('pk_live_abc123', environment: 'production', debug: true)
+```
+
 ### Tracking Events
 
+Record an action performed by a user.
+
+`Altertable.track(event, distinct_id, **options)`
+
 ```ruby
-Altertable.track('button_clicked', 'user_123', properties: {
-  button_id: 'signup_btn',
-  page: 'home'
-}, timestamp: Time.now.utc.iso8601)
+Altertable.track('item_purchased', 'user_123', properties: {
+  item_id: 'item_999',
+  price: 19.99
+})
 ```
 
 ### Identifying Users
 
+Link a user ID to their traits (like email or name).
+
+`Altertable.identify(user_id, **options)`
+
 ```ruby
 Altertable.identify('user_123', traits: {
   email: 'user@example.com',
   name: 'John Doe'
-}, anonymous_id: 'previous_anon_id')
+})
 ```
 
 ### Alias
 
+Merge a previous anonymous ID with a newly identified user ID.
+
+`Altertable.alias(distinct_id, new_user_id, **options)`
+
 ```ruby
-Altertable.alias('previous_anonymous_id', 'new_user_id')
+Altertable.alias('anon_session_456', 'user_123')
 ```
 
+## Configuration
+
+You can configure the client by passing options during initialization.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `environment` | String | `"production"` | Environment name (e.g., `production`, `development`). |
+| `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). |
+| `debug` | Boolean | `false` | Enable debug logging. |
+| `on_error` | Proc | `nil` | Callback for handling errors. |
+| `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. |
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/altertable.gemspec

@@ -37,7 +37,5 @@ Gem::Specification.new do |spec|
 
   # Optional adapter support (development only)
   spec.add_development_dependency "faraday", "~> 2.0"
-  spec.add_development_dependency "faraday-retry"
-  spec.add_development_dependency "faraday-net_http"
   spec.add_development_dependency "httpx"
 end

data/lib/altertable/adapters.rb

@@ -15,16 +15,17 @@ module Altertable
     end
 
     class FaradayAdapter < Base
-      def initialize(base_url:, timeout:, headers: {})
-        super
+      # proxy left unset (default) follows Faraday's own env-based auto-detection
+      # (HTTP_PROXY/HTTPS_PROXY/NO_PROXY). Pass `false` to disable proxying entirely for
+      # fixed, trusted destinations, or a URI string to force a specific proxy.
+      def initialize(base_url:, timeout:, headers: {}, proxy: nil)
+        super(base_url: base_url, timeout: timeout, headers: headers)
         require "faraday"
-        require "faraday/retry"
-        require "faraday/net_http"
-        
+
         @conn = Faraday.new(url: @base_url) do |f|
           @headers.each { |k, v| f.headers[k] = v }
           f.options.timeout = @timeout
-          f.request :retry, max: 3, interval: 0.05, backoff_factor: 2
+          f.proxy = proxy unless proxy.nil?
           f.adapter Faraday.default_adapter
         end
       end
@@ -49,10 +50,14 @@ module Altertable
     end
 
     class HttpxAdapter < Base
-      def initialize(base_url:, timeout:, headers: {})
-        super
+      # This adapter never auto-detects HTTP_PROXY/HTTPS_PROXY (httpx requires the :proxy
+      # plugin to be loaded explicitly). `proxy: false` and the default (unset) are
+      # therefore equivalent; pass a URI string to force a specific proxy.
+      def initialize(base_url:, timeout:, headers: {}, proxy: nil)
+        super(base_url: base_url, timeout: timeout, headers: headers)
         require "httpx"
-        @client = HTTPX.plugin(:retries).with(
+        client = proxy ? HTTPX.plugin(:proxy).plugin(:retries).with(proxy: { uri: proxy }) : HTTPX.plugin(:retries)
+        @client = client.with(
           timeout: { operation_timeout: @timeout },
           headers: @headers,
           base_url: @base_url
@@ -77,11 +82,15 @@ module Altertable
     end
 
     class NetHttpAdapter < Base
-      def initialize(base_url:, timeout:, headers: {})
-        super
+      # proxy left unset (default) follows Net::HTTP's own env-based auto-detection
+      # (HTTP_PROXY/HTTPS_PROXY/NO_PROXY). Pass `false` to disable proxying entirely for
+      # fixed, trusted destinations, or a URI string to force a specific proxy.
+      def initialize(base_url:, timeout:, headers: {}, proxy: nil)
+        super(base_url: base_url, timeout: timeout, headers: headers)
         require "net/http"
         require "uri"
         @uri = URI.parse(@base_url)
+        @proxy = proxy
       end
 
       def post(path, body: nil, params: {})
@@ -92,7 +101,7 @@ module Altertable
         @headers.each { |k, v| req[k] = v }
         req.body = body if body
 
-        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) do |http|
+        Net::HTTP.start(uri.host, uri.port, *proxy_start_args, use_ssl: uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) do |http|
           resp = http.request(req)
           Response.new(resp.code.to_i, resp.body, resp.to_hash)
         end
@@ -101,6 +110,18 @@ module Altertable
       rescue StandardError => e
         raise Altertable::NetworkError.new(e.message, e)
       end
+
+      private
+
+      # Net::HTTP.start's p_addr defaults to :ENV; returning [] here preserves that.
+      # Passing an explicit nil p_addr (i.e. [nil]) is how Net::HTTP disables proxying.
+      def proxy_start_args
+        return [] if @proxy.nil?
+        return [nil] if @proxy == false
+
+        proxy_uri = URI.parse(@proxy)
+        [proxy_uri.host, proxy_uri.port, proxy_uri.user, proxy_uri.password]
+      end
     end
   end
 end

data/lib/altertable/client.rb

@@ -28,7 +28,7 @@ module Altertable
         "X-API-Key" => @api_key,
         "Content-Type" => "application/json"
       }
-      @adapter = select_adapter(adapter_name, { base_url: @base_url, timeout: @timeout, headers: headers })
+      @adapter = select_adapter(adapter_name, { base_url: @base_url, timeout: @timeout, headers: headers, proxy: options[:proxy] })
     end
 
     def track(event, distinct_id, **options)

data/lib/altertable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Altertable
-  VERSION = "1.1.1"
+  VERSION = "1.2.0"
 end

data/rbi/altertable.rbi

@@ -82,8 +82,8 @@ module Altertable
     end
 
     class FaradayAdapter < Base
-      sig { params(base_url: String, timeout: T.any(Integer, Float), headers: T.nilable(T::Hash[String, String])).void }
-      def initialize(base_url:, timeout:, headers: nil); end
+      sig { params(base_url: String, timeout: T.any(Integer, Float), headers: T.nilable(T::Hash[String, String]), proxy: T.nilable(T.any(String, T::Boolean))).void }
+      def initialize(base_url:, timeout:, headers: nil, proxy: nil); end
 
       sig { params(path: String, body: T.nilable(String), params: T.nilable(T::Hash[T.any(Symbol, String), T.untyped]), block: T.nilable(T.proc.params(arg0: T.untyped).void)).returns(Altertable::Adapters::Response) }
       def post(path, body: nil, params: nil, &block); end
@@ -95,8 +95,8 @@ module Altertable
     end
 
     class HttpxAdapter < Base
-      sig { params(base_url: String, timeout: T.any(Integer, Float), headers: T.nilable(T::Hash[String, String])).void }
-      def initialize(base_url:, timeout:, headers: nil); end
+      sig { params(base_url: String, timeout: T.any(Integer, Float), headers: T.nilable(T::Hash[String, String]), proxy: T.nilable(T.any(String, T::Boolean))).void }
+      def initialize(base_url:, timeout:, headers: nil, proxy: nil); end
 
       sig { params(path: String, body: T.nilable(String), params: T.nilable(T::Hash[T.any(Symbol, String), T.untyped]), block: T.nilable(T.proc.params(arg0: T.untyped).void)).returns(Altertable::Adapters::Response) }
       def post(path, body: nil, params: nil, &block); end
@@ -108,11 +108,16 @@ module Altertable
     end
 
     class NetHttpAdapter < Base
-      sig { params(base_url: String, timeout: T.any(Integer, Float), headers: T.nilable(T::Hash[String, String])).void }
-      def initialize(base_url:, timeout:, headers: nil); end
+      sig { params(base_url: String, timeout: T.any(Integer, Float), headers: T.nilable(T::Hash[String, String]), proxy: T.nilable(T.any(String, T::Boolean))).void }
+      def initialize(base_url:, timeout:, headers: nil, proxy: nil); end
 
       sig { params(path: String, body: T.nilable(String), params: T.nilable(T::Hash[T.any(Symbol, String), T.untyped]), block: T.nilable(T.proc.params(arg0: T.untyped).void)).returns(Altertable::Adapters::Response) }
       def post(path, body: nil, params: nil, &block); end
+
+      private
+
+      sig { returns(T::Array[T.untyped]) }
+      def proxy_start_args; end
     end
   end
 

data/sig/altertable/adapters.rbs

@@ -19,7 +19,7 @@ module Altertable
     class FaradayAdapter < Base
       @conn: untyped
 
-      def initialize: (base_url: String, timeout: Integer | Float, ?headers: ::Hash[String, String]) -> void
+      def initialize: (base_url: String, timeout: Integer | Float, ?headers: ::Hash[String, String], ?proxy: (String | bool)?) -> void
       def post: (String path, ?body: String?, ?params: ::Hash[Symbol | String, untyped]) -> Response
 
       private
@@ -30,7 +30,7 @@ module Altertable
     class HttpxAdapter < Base
       @client: untyped
 
-      def initialize: (base_url: String, timeout: Integer | Float, ?headers: ::Hash[String, String]) -> void
+      def initialize: (base_url: String, timeout: Integer | Float, ?headers: ::Hash[String, String], ?proxy: (String | bool)?) -> void
       def post: (String path, ?body: String?, ?params: ::Hash[Symbol | String, untyped]) -> Response
 
       private
@@ -40,9 +40,14 @@ module Altertable
 
     class NetHttpAdapter < Base
       @uri: URI::HTTP | URI::HTTPS
+      @proxy: (String | bool)?
 
-      def initialize: (base_url: String, timeout: Integer | Float, ?headers: ::Hash[String, String]) -> void
+      def initialize: (base_url: String, timeout: Integer | Float, ?headers: ::Hash[String, String], ?proxy: (String | bool)?) -> void
       def post: (String path, ?body: String?, ?params: ::Hash[Symbol | String, untyped]) -> Response
+
+      private
+
+      def proxy_start_args: () -> ::Array[untyped]
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: altertable
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Altertable
@@ -149,34 +149,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: faraday-retry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: faraday-net_http
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: httpx
   requirement: !ruby/object:Gem::Requirement