altertable 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7472be3a607d8398965c62ed90f5531fe33b21d77fa4827bd73259d7a714eba5
-  data.tar.gz: 536319ad37e423c82ab298d5804aaf22de1563ece73226abaa42b5fd6bd93c39
+  metadata.gz: e63f277260656f5e0ed3c5696ae4fc974f99ddbbc75a6e983917d60d1b7af644
+  data.tar.gz: d52d275511b219aa0df3e8d9ee42e30830f3fb9fa399fe91a8198e35c15bbbc3
 SHA512:
-  metadata.gz: 231d0b578dd8fe4ed8856d07fe233b4e256ce3650ce9a11260a21c01d352fcb9bc291477ab526c2d8984078caa4b879f92da667483af5e475d6ea08089999283
-  data.tar.gz: 7ba2dd340e96f6d906c44456032b6a959e0cfa3f106bf5bf42d2982ac710da4856e4fb1e6d028a030afab62a3ed702e5a27e9fbd920725ff3b4926da40e64e35
+  metadata.gz: '0295a9615766d0fa8487568349a705705211cfb511087c0e79de3a6ac1804b3d33280e24167a7511dee768edb9f27f9c3fc83107af303af44ac62f5b519f8802'
+  data.tar.gz: de4d98a9ef278872d585e56941754d0a7b7515eb91065a2545f6e5e403b2d3eb5412c65cce24617426458aee040e03b4cd54f1775d4b28ac33f285cc311a236b

data/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [altertable-ai]

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What
+
+<!-- What does this PR do? One sentence is fine. -->
+
+## Why
+
+<!-- Link an issue or explain the motivation. -->
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] `CHANGELOG.md` updated (skip for docs/CI-only changes)
+- [ ] Breaking change noted in commit footer (`BREAKING CHANGE: …`) and changelog

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.3.0](https://github.com/altertable-ai/altertable-ruby/compare/altertable/v1.2.0...altertable/v1.3.0) (2026-09-04)
+
+
+### Features
+
+* **client:** add batch track, identify, and alias ([#53](https://github.com/altertable-ai/altertable-ruby/issues/53)) ([2aff25b](https://github.com/altertable-ai/altertable-ruby/commit/2aff25b8b6f8767da113fce38901160dffbd9733))
+
 ## [1.2.0](https://github.com/altertable-ai/altertable-ruby/compare/altertable/v1.1.2...altertable/v1.2.0) (2026-08-27)
 
 

data/CODE_OF_CONDUCT.md

@@ -70,14 +70,14 @@ Community leaders will follow these Community Impact Guidelines in determining t
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct/][v2.1].
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
 
-For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq/][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations/][translations].
 
 [homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+[Mozilla CoC]: https://github.com/mozilla/inclusion
+[FAQ]: https://www.contributor-covenant.org/faq/
+[translations]: https://www.contributor-covenant.org/translations/

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    altertable (1.2.0)
+    altertable (1.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -47,38 +47,67 @@ Altertable.init('pk_live_abc123', environment: 'production', debug: true)
 
 Record an action performed by a user.
 
-`Altertable.track(event, distinct_id, **options)`
+`Altertable.track(event, distinct_id, **options)`  
+`Altertable.track(event_payload, **options)`  
+`Altertable.track(event_payloads, **options)`
 
 ```ruby
 Altertable.track('item_purchased', 'user_123', properties: {
   item_id: 'item_999',
   price: 19.99
 })
+
+Altertable.track({
+  event: 'item_purchased',
+  distinct_id: 'user_123',
+  properties: { item_id: 'item_999', price: 19.99 }
+})
+
+Altertable.track([
+  { event: 'signup', distinct_id: 'user_1', properties: { plan: 'pro' } },
+  { event: 'login', distinct_id: 'user_2', timestamp: '2025-06-15T14:30:00.000Z' }
+])
 ```
 
 ### Identifying Users
 
 Link a user ID to their traits (like email or name).
 
-`Altertable.identify(user_id, **options)`
+`Altertable.identify(user_id, **options)`  
+`Altertable.identify(identify_payload, **options)`  
+`Altertable.identify(identify_payloads, **options)`
 
 ```ruby
 Altertable.identify('user_123', traits: {
   email: 'user@example.com',
   name: 'John Doe'
 })
+
+Altertable.identify([
+  { user_id: 'user_1', traits: { email: 'one@example.com' } },
+  { user_id: 'user_2', traits: { email: 'two@example.com' } }
+])
 ```
 
 ### Alias
 
 Merge a previous anonymous ID with a newly identified user ID.
 
-`Altertable.alias(distinct_id, new_user_id, **options)`
+`Altertable.alias(distinct_id, new_user_id, **options)`  
+`Altertable.alias(alias_payload, **options)`  
+`Altertable.alias(alias_payloads, **options)`
 
 ```ruby
 Altertable.alias('anon_session_456', 'user_123')
+
+Altertable.alias([
+  { distinct_id: 'anon_1', new_user_id: 'user_1' },
+  { distinct_id: 'anon_2', new_user_id: 'user_2' }
+])
 ```
 
+A Hash payload posts one object; an Array posts a JSON array on the same endpoint. Omitted `timestamp` values default to the current time as ISO 8601.
+
 ## Configuration
 
 You can configure the client by passing options during initialization.

data/SECURITY.md

@@ -8,7 +8,7 @@ Only the latest minor release receives security patches.
 
 **Do not open a public issue.**
 
-Email security@altertable.ai with:
+Email <security@altertable.ai> with:
 
 1. Description of the vulnerability
 2. Steps to reproduce

data/lib/altertable/client.rb

@@ -31,51 +31,40 @@ module Altertable
       @adapter = select_adapter(adapter_name, { base_url: @base_url, timeout: @timeout, headers: headers, proxy: options[:proxy] })
     end
 
-    def track(event, distinct_id, **options)
-      properties = options[:properties] || {}
-      timestamp = options[:timestamp] || Time.now.utc.iso8601(3)
-      payload = {
-        timestamp: timestamp,
-        event: event,
-        environment: @environment,
-        distinct_id: distinct_id,
-        properties: {
-          '$lib': "altertable-ruby",
-          '$lib_version': Altertable::VERSION
-        }.merge(properties)
-      }
-      payload[:properties]["$release"] = @release if @release
-      payload[:anonymous_id] = options[:anonymous_id] if options.key?(:anonymous_id)
-      payload[:device_id] = options[:device_id] if options.key?(:device_id)
-
-      post("/track", payload)
+    def track(event, distinct_id = nil, **options)
+      case event
+      when Array
+        payloads = map_batch(event, "events") { |item| track_payload_from_item(merge_payload(item, options)) }
+        post("/track", payloads)
+      when Hash
+        post("/track", track_payload_from_item(merge_payload(event, options)))
+      else
+        post("/track", track_payload(event, distinct_id, options))
+      end
     end
 
     def identify(user_id, **options)
-      traits = options[:traits] || {}
-      timestamp = options[:timestamp] || Time.now.utc.iso8601(3)
-      payload = {
-        timestamp: timestamp,
-        environment: @environment,
-        distinct_id: user_id,
-        traits: traits
-      }
-      payload[:anonymous_id] = options[:anonymous_id] if options.key?(:anonymous_id)
-      payload[:device_id] = options[:device_id] if options.key?(:device_id)
-
-      post("/identify", payload)
+      case user_id
+      when Array
+        payloads = map_batch(user_id, "identifies") { |item| identify_payload_from_item(merge_payload(item, options)) }
+        post("/identify", payloads)
+      when Hash
+        post("/identify", identify_payload_from_item(merge_payload(user_id, options)))
+      else
+        post("/identify", identify_payload(user_id, options))
+      end
     end
 
-    def alias(distinct_id, new_user_id, **options)
-      timestamp = options[:timestamp] || Time.now.utc.iso8601(3)
-      payload = {
-        timestamp: timestamp,
-        environment: @environment,
-        distinct_id: distinct_id,
-        new_user_id: new_user_id
-      }
-
-      post("/alias", payload)
+    def alias(distinct_id, new_user_id = nil, **options)
+      case distinct_id
+      when Array
+        payloads = map_batch(distinct_id, "aliases") { |item| alias_payload_from_item(merge_payload(item, options)) }
+        post("/alias", payloads)
+      when Hash
+        post("/alias", alias_payload_from_item(merge_payload(distinct_id, options)))
+      else
+        post("/alias", alias_payload(distinct_id, new_user_id, options))
+      end
     end
 
     private
@@ -107,6 +96,108 @@ module Altertable
       false
     end
 
+    def map_batch(items, name, &block)
+      raise ArgumentError, "#{name} must be a non-empty Array" unless items.is_a?(Array) && !items.empty?
+
+      items.each_with_index do |item, index|
+        raise ArgumentError, "#{name}[#{index}] must be a Hash" unless item.is_a?(Hash)
+      end
+
+      items.map(&block)
+    end
+
+    def merge_payload(item, options)
+      return item if options.empty?
+
+      item.merge(options)
+    end
+
+    def item_value(item, key)
+      if item.key?(key)
+        item[key]
+      elsif item.key?(key.to_s)
+        item[key.to_s]
+      end
+    end
+
+    def item_options(item, *keys)
+      keys.each_with_object({}) do |key, opts|
+        opts[key] = item_value(item, key) if item.key?(key) || item.key?(key.to_s)
+      end
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def default_timestamp
+      Time.now.utc.iso8601(3)
+    end
+
+    def track_payload_from_item(item)
+      event = item_value(item, :event)
+      distinct_id = item_value(item, :distinct_id)
+      raise ArgumentError, "event is required" if blank?(event)
+      raise ArgumentError, "distinct_id is required" if blank?(distinct_id)
+
+      track_payload(event, distinct_id, item_options(item, :properties, :anonymous_id, :device_id, :timestamp))
+    end
+
+    def identify_payload_from_item(item)
+      user_id = item_value(item, :user_id)
+      raise ArgumentError, "user_id is required" if blank?(user_id)
+
+      identify_payload(user_id, item_options(item, :traits, :anonymous_id, :device_id, :timestamp))
+    end
+
+    def alias_payload_from_item(item)
+      distinct_id = item_value(item, :distinct_id)
+      new_user_id = item_value(item, :new_user_id)
+      raise ArgumentError, "distinct_id is required" if blank?(distinct_id)
+      raise ArgumentError, "new_user_id is required" if blank?(new_user_id)
+
+      alias_payload(distinct_id, new_user_id, item_options(item, :timestamp))
+    end
+
+    def track_payload(event, distinct_id, options)
+      properties = options[:properties] || {}
+      payload = {
+        timestamp: options[:timestamp] || default_timestamp,
+        event: event,
+        environment: @environment,
+        distinct_id: distinct_id,
+        properties: {
+          '$lib': "altertable-ruby",
+          '$lib_version': Altertable::VERSION
+        }.merge(properties)
+      }
+      payload[:properties]["$release"] = @release if @release
+      payload[:anonymous_id] = options[:anonymous_id] if options.key?(:anonymous_id)
+      payload[:device_id] = options[:device_id] if options.key?(:device_id)
+      payload
+    end
+
+    def identify_payload(user_id, options)
+      payload = {
+        timestamp: options[:timestamp] || default_timestamp,
+        environment: @environment,
+        distinct_id: user_id,
+        traits: options[:traits] || {}
+      }
+      payload[:anonymous_id] = options[:anonymous_id] if options.key?(:anonymous_id)
+      payload[:device_id] = options[:device_id] if options.key?(:device_id)
+      payload
+    end
+
+    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)
       handle_response(res)

data/lib/altertable/version.rb

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

data/lib/altertable.rb

@@ -10,7 +10,7 @@ module Altertable
       @client = Client.new(api_key, options)
     end
 
-    def track(event, distinct_id, **options)
+    def track(event, distinct_id = nil, **options)
       client.track(event, distinct_id, **options)
     end
 
@@ -18,7 +18,7 @@ module Altertable
       client.identify(user_id, **options)
     end
 
-    def alias(distinct_id, new_user_id, **options)
+    def alias(distinct_id, new_user_id = nil, **options)
       client.alias(distinct_id, new_user_id, **options)
     end
 

data/rbi/altertable.rbi

@@ -34,14 +34,14 @@ module Altertable
     sig { params(api_key: String, options: T::Hash[Symbol, T.untyped]).void }
     def initialize(api_key, options = {}); end
 
-    sig { params(event: String, distinct_id: String, options: T.untyped).returns(T.untyped) }
-    def track(event, distinct_id, **options); end
+    sig { params(event: T.any(String, T::Hash[T.any(Symbol, String), T.untyped], T::Array[T::Hash[T.any(Symbol, String), T.untyped]]), distinct_id: T.nilable(String), options: T.untyped).returns(T.untyped) }
+    def track(event, distinct_id = nil, **options); end
 
-    sig { params(user_id: String, options: T.untyped).returns(T.untyped) }
+    sig { params(user_id: T.any(String, T::Hash[T.any(Symbol, String), T.untyped], T::Array[T::Hash[T.any(Symbol, String), T.untyped]]), options: T.untyped).returns(T.untyped) }
     def identify(user_id, **options); end
 
-    sig { params(distinct_id: String, new_user_id: String, options: T.untyped).returns(T.untyped) }
-    def alias(distinct_id, new_user_id, **options); end
+    sig { params(distinct_id: T.any(String, T::Hash[T.any(Symbol, String), T.untyped], T::Array[T::Hash[T.any(Symbol, String), T.untyped]]), new_user_id: T.nilable(String), options: T.untyped).returns(T.untyped) }
+    def alias(distinct_id, new_user_id = nil, **options); end
 
     private
 
@@ -51,7 +51,7 @@ module Altertable
     sig { params(gem_name: String).returns(T::Boolean) }
     def try_require(gem_name); end
 
-    sig { params(path: String, payload: T::Hash[T.any(Symbol, String), T.untyped]).returns(T.untyped) }
+    sig { params(path: String, payload: T.any(T::Hash[T.any(Symbol, String), T.untyped], T::Array[T::Hash[T.any(Symbol, String), T.untyped]])).returns(T.untyped) }
     def post(path, payload); end
 
     sig { params(res: T.untyped).returns(T.untyped) }
@@ -124,14 +124,14 @@ module Altertable
   sig { params(api_key: String, options: T::Hash[Symbol, T.untyped]).returns(Client) }
   def self.init(api_key, options = {}); end
 
-  sig { params(event: String, distinct_id: String, options: T.untyped).returns(T.untyped) }
-  def self.track(event, distinct_id, **options); end
+  sig { params(event: T.any(String, T::Hash[T.any(Symbol, String), T.untyped], T::Array[T::Hash[T.any(Symbol, String), T.untyped]]), distinct_id: T.nilable(String), options: T.untyped).returns(T.untyped) }
+  def self.track(event, distinct_id = nil, **options); end
 
-  sig { params(user_id: String, options: T.untyped).returns(T.untyped) }
+  sig { params(user_id: T.any(String, T::Hash[T.any(Symbol, String), T.untyped], T::Array[T::Hash[T.any(Symbol, String), T.untyped]]), options: T.untyped).returns(T.untyped) }
   def self.identify(user_id, **options); end
 
-  sig { params(distinct_id: String, new_user_id: String, options: T.untyped).returns(T.untyped) }
-  def self.alias(distinct_id, new_user_id, **options); end
+  sig { params(distinct_id: T.any(String, T::Hash[T.any(Symbol, String), T.untyped], T::Array[T::Hash[T.any(Symbol, String), T.untyped]]), new_user_id: T.nilable(String), options: T.untyped).returns(T.untyped) }
+  def self.alias(distinct_id, new_user_id = nil, **options); end
 
   sig { returns(Client) }
   def self.client; end

data/sig/altertable/client.rbs

@@ -16,16 +16,22 @@ module Altertable
     def initialize: (String api_key, ?::Hash[Symbol, untyped] options) -> void
 
     def track: (String event, String distinct_id, **untyped options) -> untyped
+             | (::Hash[Symbol | String, untyped] event_payload, **untyped options) -> untyped
+             | (::Array[::Hash[Symbol | String, untyped]] event_payloads, **untyped options) -> untyped
 
     def identify: (String user_id, **untyped options) -> untyped
+                | (::Hash[Symbol | String, untyped] identify_payload, **untyped options) -> untyped
+                | (::Array[::Hash[Symbol | String, untyped]] identify_payloads, **untyped options) -> untyped
 
     def alias: (String distinct_id, String new_user_id, **untyped options) -> untyped
+             | (::Hash[Symbol | String, untyped] alias_payload, **untyped options) -> untyped
+             | (::Array[::Hash[Symbol | String, untyped]] alias_payloads, **untyped options) -> untyped
 
     private
 
     def select_adapter: (Symbol? name, ::Hash[Symbol, untyped] options) -> untyped
     def try_require: (String gem_name) -> bool
-    def post: (String path, ::Hash[Symbol | String, untyped] payload) -> untyped
+    def post: (String path, ::Hash[Symbol | String, untyped] | ::Array[::Hash[Symbol | String, untyped]] payload) -> untyped
     def handle_response: (untyped res) -> untyped
     def handle_error: (Exception error) -> untyped
   end

data/sig/altertable.rbs

@@ -4,10 +4,16 @@ module Altertable
   def self.init: (String api_key, ?::Hash[Symbol, untyped] options) -> Client
 
   def self.track: (String event, String distinct_id, **untyped options) -> untyped
+                | (::Hash[Symbol | String, untyped] event_payload, **untyped options) -> untyped
+                | (::Array[::Hash[Symbol | String, untyped]] event_payloads, **untyped options) -> untyped
 
   def self.identify: (String user_id, **untyped options) -> untyped
+                   | (::Hash[Symbol | String, untyped] identify_payload, **untyped options) -> untyped
+                   | (::Array[::Hash[Symbol | String, untyped]] identify_payloads, **untyped options) -> untyped
 
   def self.alias: (String distinct_id, String new_user_id, **untyped options) -> untyped
+                | (::Hash[Symbol | String, untyped] alias_payload, **untyped options) -> untyped
+                | (::Array[::Hash[Symbol | String, untyped]] alias_payloads, **untyped options) -> untyped
 
   def self.client: () -> Client
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: altertable
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Altertable
@@ -170,8 +170,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/FUNDING.yml"
 - ".github/ISSUE_TEMPLATE/bug_report.yml"
 - ".github/ISSUE_TEMPLATE/feature_request.yml"
+- ".github/PULL_REQUEST_TEMPLATE.md"
 - ".github/workflows/ci.yml"
 - ".github/workflows/release-please.yml"
 - ".github/workflows/semantic-pull-request.yml"