feat: add service account support

[lajohn4747]

Summary

• Service Account Credentials: New Mixpanel::ServiceAccountCredentials class for storing username, secret, and project_id
• Import Support: Events#import now accepts service account credentials instead of API keys
• Feature Flags Support: Both local and remote feature flags authenticate using service accounts
• Readme.rdoc - Added usage examples
• Comprehensive test coverage

[linear-code]

MULTI-567

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.17%. Comparing base (3f9a8d4) to head (5e8836b).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #152      +/-   ##
==========================================
+ Coverage   96.73%   97.17%   +0.44%     
==========================================
  Files          14       15       +1     
  Lines         673      709      +36     
==========================================
+ Hits          651      689      +38     
+ Misses         22       20       -2     

Flag	Coverage Δ
openfeature	100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds first-class “service account” support across import and feature flags by introducing a credentials object, wiring it through the tracker/providers, and updating docs + tests to demonstrate and validate the new flow.

Changes:

• Introduce Mixpanel::ServiceAccountCredentials and serialize it into import messages.
• Update import pipeline (Events#import → Consumer#send!) to send either legacy api_key or service account fields.
• Thread optional credentials into local/remote flags providers and use them for HTTP Basic Auth, plus README usage examples and new/updated specs.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
spec/mixpanel-ruby/tracker_spec.rb	Adds spec asserting credentials are passed into flags providers.
spec/mixpanel-ruby/flags/remote_flags_spec.rb	Updates constructor usage and adds auth test for remote flags with credentials.
spec/mixpanel-ruby/flags/local_flags_spec.rb	Updates constructor usage and adds auth test for local flags with credentials.
spec/mixpanel-ruby/events_spec.rb	Adds import message-shape test for service account credentials (currently missing a require).
spec/mixpanel-ruby/credentials_spec.rb	New unit tests for credentials validation + JSON serialization.
spec/mixpanel-ruby/consumer_spec.rb	Adds test ensuring import requests include service account fields.
Readme.rdoc	Documents service account usage for import and feature flags.
lib/mixpanel-ruby/tracker.rb	Adds credentials: keyword and passes it to flags providers; updates import docs/signature.
lib/mixpanel-ruby/flags/remote_flags_provider.rb	Extends initializer to accept credentials and forward into provider config.
lib/mixpanel-ruby/flags/local_flags_provider.rb	Extends initializer to accept credentials and forward into provider config.
lib/mixpanel-ruby/flags/flags_provider.rb	Uses credentials for Basic Auth when present; retains token auth fallback.
lib/mixpanel-ruby/events.rb	Allows import to accept either API key or service account credentials.
lib/mixpanel-ruby/credentials.rb	Implements ServiceAccountCredentials and JSON serialization helpers.
lib/mixpanel-ruby/consumer.rb	Sends either service account fields or legacy API key when posting import payloads.
lib/mixpanel-ruby.rb	Requires the new credentials file.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Confidence Score: 4/5

The core auth flows are correct, but the import path serializes the service account secret into the message JSON payload, which any custom consumer block, queue writer, or BufferedConsumer sink will receive verbatim — an architectural tradeoff that needs care in custom deployments.

All three code paths (import, local flags, remote flags) are wired consistently and the previously identified argument-count and serialization issues are resolved. The backward-compat conditional in consumer.rb correctly preserves 2-arg subclass overrides. The one structural concern is that the import path must route the service account secret through a JSON message string to reach the consumer, meaning any custom sink receives the secret in plaintext — the code documents this, but it is a real exposure risk for anyone using queue-based or logging consumers.

lib/mixpanel-ruby/consumer.rb — the interplay between the conditional request() dispatch and the deserialized credentials hash is the most intricate part of the change and worth a careful read.

Important Files Changed

Filename	Overview
lib/mixpanel-ruby/credentials.rb	New ServiceAccountCredentials class with proper validation, Integer project_id coercion, and JSON serialization including secret for the consumer auth path.
lib/mixpanel-ruby/consumer.rb	Conditionally calls 2-arg or 4-arg request() to preserve backward compat with custom Consumer subclasses; adds Basic Auth and project_id query param for service account import path.
lib/mixpanel-ruby/events.rb	Routes import to credentials path or legacy api_key path; deprecation warning on legacy key usage.
lib/mixpanel-ruby/flags/flags_provider.rb	Extracts credentials from provider_config; uses service account Basic Auth and adds project_id query param when credentials present, otherwise falls back to token auth.
lib/mixpanel-ruby/flags/local_flags_provider.rb	Adds credentials as optional 5th parameter (correctly placed after error_handler) and threads it through provider_config to the base class.
lib/mixpanel-ruby/tracker.rb	Adds credentials keyword arg to initialize; passes it to both flag providers. Import credentials remain caller-supplied per-call, not stored on the tracker.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User
    participant Tracker
    participant Events
    participant Consumer
    participant MixpanelAPI

    User->>Tracker: import(credentials, distinct_id, event)
    Tracker->>Events: import(credentials, distinct_id, event)
    Events->>Events: "Build message {data, credentials}"
    Events->>Events: message.to_json (credentials.as_json includes secret)
    Events->>Consumer: sink.call(:import, json_message)
    Consumer->>Consumer: JSON.load(message) → extract credentials hash
    Consumer->>Consumer: "Build form_data {data, verbose}"
    Consumer->>Consumer: URI.encode_www_form with project_id
    Consumer->>Consumer: request.basic_auth(username, secret)
    Consumer->>MixpanelAPI: "POST /import?project_id=... (Basic Auth)"
    MixpanelAPI-->>Consumer: "{status: 1}"
    Consumer-->>Tracker: success

    Note over User,Tracker: Flags path (no serialization)
    User->>Tracker: new(token, credentials: creds, remote_flags_config: cfg)
    Tracker->>RemoteFlagsProvider: new(token, cfg, track_cb, err_handler, creds)
    RemoteFlagsProvider->>FlagsProvider: super(provider_config with :credentials)
    FlagsProvider->>FlagsProvider: "@credentials = creds (object, not serialized)"
    User->>Tracker: remote_flags.get_variant_value(flag_key, fallback, ctx)
    FlagsProvider->>MixpanelAPI: "GET /flags?token=...&project_id=... (Basic Auth)"
    MixpanelAPI-->>FlagsProvider: flag definitions

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User
    participant Tracker
    participant Events
    participant Consumer
    participant MixpanelAPI

    User->>Tracker: import(credentials, distinct_id, event)
    Tracker->>Events: import(credentials, distinct_id, event)
    Events->>Events: "Build message {data, credentials}"
    Events->>Events: message.to_json (credentials.as_json includes secret)
    Events->>Consumer: sink.call(:import, json_message)
    Consumer->>Consumer: JSON.load(message) → extract credentials hash
    Consumer->>Consumer: "Build form_data {data, verbose}"
    Consumer->>Consumer: URI.encode_www_form with project_id
    Consumer->>Consumer: request.basic_auth(username, secret)
    Consumer->>MixpanelAPI: "POST /import?project_id=... (Basic Auth)"
    MixpanelAPI-->>Consumer: "{status: 1}"
    Consumer-->>Tracker: success

    Note over User,Tracker: Flags path (no serialization)
    User->>Tracker: new(token, credentials: creds, remote_flags_config: cfg)
    Tracker->>RemoteFlagsProvider: new(token, cfg, track_cb, err_handler, creds)
    RemoteFlagsProvider->>FlagsProvider: super(provider_config with :credentials)
    FlagsProvider->>FlagsProvider: "@credentials = creds (object, not serialized)"
    User->>Tracker: remote_flags.get_variant_value(flag_key, fallback, ctx)
    FlagsProvider->>MixpanelAPI: "GET /flags?token=...&project_id=... (Basic Auth)"
    MixpanelAPI-->>FlagsProvider: flag definitions

Loading

_{Reviews (10): Last reviewed commit: "move notice earlier" | Re-trigger Greptile}

[tylerjroach]

Review: public API / backward-compatibility concerns

Most of the surface here is additive and compatible (Tracker#initialize gaining a credentials: kwarg, the import first-param rename, the new ServiceAccountCredentials class). Findings below, one real backward-compat break plus a consistency issue and a security decision to confirm.

1. 🔴 Consumer#request is now called with extra args on every send — breaks custom-consumer overrides

send! now calls request(endpoint, form_data, credentials, type) unconditionally, for all event types (track, profile updates, imports — everything).

Consumer#request is a public, changelog-documented extension point — it was added in 1.3.0 specifically so users could swap the HTTP layer:

== 1.3.0
* Added Consumer#request method, demo with Faraday integration

Anyone who followed that guidance has a 2-arg override:

class MyConsumer < Mixpanel::Consumer
  def request(endpoint, form_data)   # per the 1.3.0 Faraday pattern
    # ...
  end
end

After this change, that override raises ArgumentError: wrong number of arguments (given 4, expected 2) on the first send of any type — not just imports.

Suggested fix — only widen the call on the new service-account path, and branch at the call site so all existing traffic still calls request(endpoint, form_data) with exactly two args:

# send!
credentials = decoded_message["credentials"]
form_data = {"data" => data, "verbose" => 1}
form_data.merge!("api_key" => api_key) if api_key && !credentials

response_code, response_body =
  if credentials
    request(endpoint, form_data, credentials: credentials, type: type)  # new path only
  else
    request(endpoint, form_data)                                        # unchanged
  end

def request(endpoint, form_data, credentials: nil, type: nil)
  uri = URI(endpoint)
  if credentials && type == :import
    query = URI.decode_www_form(uri.query || '').to_h
    query['project_id'] = credentials['project_id']
    uri.query = URI.encode_www_form(query)
  end
  request = Net::HTTP::Post.new(uri.request_uri)
  request.set_form_data(form_data)
  request.basic_auth(credentials['username'], credentials['secret']) if credentials && type == :import
  # ...unchanged Net::HTTP setup...
end

This way the only remaining break is a new combination (custom request override + service-account import), which no existing code can depend on because service accounts don't exist yet — and it fails loudly on the opt-in feature rather than silently across 100% of traffic. Note it must branch at the call site: always passing credentials:/type: (even as nil) re-breaks 2-arg overrides.

2. 🟡 RemoteFlagsProvider#initialize puts credentials in the middle — inconsistent with LocalFlagsProvider

(Correcting my earlier take: this is not a customer-facing break.) Both providers are only ever instantiated internally by Tracker (the sole .new call sites), and there's no README/changelog pattern presenting them as direct-use or override points. The remote call site matches the middle-position signature, so it functions correctly.

The remaining issue is consistency: the two sibling classes ended up with different constructor shapes, and the tracker calls them differently (credentials last for local, third for remote):

# local  — credentials trailing + default
def initialize(token, config, tracker_callback, error_handler, credentials = nil)
# remote — credentials 3rd, required
def initialize(token, config, credentials, tracker_callback, error_handler)

Not blocking, but worth aligning remote to match local (credentials = nil trailing) and updating the remote call site — cheaper to fix now than to leave two divergent signatures. Looks like the patch-16 rebase aligned only the local provider.

3. 🟡 Service account secret is serialized into the message payload

ServiceAccountCredentials#as_json includes secret, so it rides inside the message JSON handed to the sink/consumer. The default Consumer needs it for Basic Auth and strips it from the POST body — fine there. But the secret is now present in the serialized message that any custom sink/block, BufferedConsumer, or async executor receives, and could log or persist in plaintext.

This flip-flopped during the branch (removed for security in one commit, re-added in another), so I want to make sure it's a deliberate, documented decision rather than an accident. If the secret should never touch the message channel, credentials would need to live on the consumer/tracker instance instead of in the payload — larger change, worth a separate discussion. At minimum, please document that messages carry the secret so operators don't log them.

[tylerjroach]

Hey @lajohn4747 I posted a a Claude review guided by a few concerns I had noticed. Theres a few places where params were added that should probably be added to the end to ensure they aren't breaking. A few other concerns were posted as well. LMK what you think.