BilldogEng (BilldogEng v1.0.0-beta.1)

Copy Markdown View Source

The BilldogEng server SDK client for Elixir.

Engagement suite for server-side use: Analytics, Feature Flags (remote + local evaluation), Surveys (data API), Messaging dispatch, and LLM tracing.

Quickstart

{:ok, bd} = BilldogEng.new("bd_test_xxx", local_evaluation: true)

BilldogEng.capture(bd, "user-123", "order_completed", %{"revenue" => 49.99})
on? = BilldogEng.is_feature_enabled(bd, "new_checkout", "user-123")

BilldogEng.shutdown(bd)

The client holds two supervising-free GenServers — one for the analytics batch queue, one for the feature-flag definition cache. Call shutdown/1 to flush remaining events and stop the background flush timer.

Summary

Types

t()

Functions

abandon_survey(client, survey_id, respondent_id)

See BilldogEng.Surveys.abandon/3.

alias(c, distinct_id, alias)

Alias one distinct id to another. Emits $create_alias.

capture(c, distinct_id, event, properties \\ %{}, groups \\ %{})

Capture an event for a user. Batched; flushed per the configured policy.

capture_trace(c, params)

Capture an LLM trace span. See BilldogEng.Llm.capture_trace/2.

dispatch_message(c, params)

Dispatch a message. See BilldogEng.Messaging.dispatch/2.

fetch_survey(client, survey_id, opts \\ [])

See BilldogEng.Surveys.fetch/3.

flush(c)

Flush queued analytics events now.

get_all_flags(c, distinct_id, opts \\ [])

Evaluate all known flags for a user.

get_feature_flag(c, key, distinct_id, opts \\ [])

Get a flag value: boolean, variant key string, or nil if unknown.

get_feature_flag_payload(c, key, distinct_id, opts \\ [])

Get a flag's payload (variant config), local mode.

group_identify(c, group_type, group_key, properties \\ %{})

Set group properties. Emits $groupidentify.

identify(c, distinct_id, properties \\ %{})

Set person properties. Emits $identify.

is_feature_enabled(c, key, distinct_id, opts \\ [])

Whether a flag is enabled for the user.

list_surveys(client, opts \\ [])

See BilldogEng.Surveys.list/2.

new(api_key, opts \\ [])

Construct a client.

new!(api_key, opts \\ [])

Like new/2 but raises on error.

queue_length(c)

Number of events currently queued (test/observability aid).

record_partial(client, survey_id, respondent_id, answers, context \\ [])

See BilldogEng.Surveys.record_partial/5.

reload_feature_flag_definitions(c)

Reload local flag definitions (local mode).

set_definitions(c, defs)

Inject flag definitions directly, bypassing the network (advanced/tests).

shutdown(c)

Flush remaining events and stop the background flush timer.

start_survey(client, survey_id, context \\ [])

See BilldogEng.Surveys.start/3.

submit_survey(client, survey_id, answers, context \\ [])

See BilldogEng.Surveys.submit/4.

Types

t()

@type t() :: %BilldogEng{
  analytics: pid(),
  api_key: String.t(),
  flags: pid(),
  transport: BilldogEng.Transport.config()
}

Functions

abandon_survey(client, survey_id, respondent_id)

See BilldogEng.Surveys.abandon/3.

alias(c, distinct_id, alias)

@spec alias(t(), String.t(), String.t()) :: :ok

Alias one distinct id to another. Emits $create_alias.

capture(c, distinct_id, event, properties \\ %{}, groups \\ %{})

@spec capture(t(), String.t(), String.t(), map(), map()) :: :ok

Capture an event for a user. Batched; flushed per the configured policy.

capture_trace(c, params)

@spec capture_trace(
  t(),
  keyword()
) :: {:ok, term()} | {:error, BilldogEng.Error.t()}

Capture an LLM trace span. See BilldogEng.Llm.capture_trace/2.

dispatch_message(c, params)

@spec dispatch_message(
  t(),
  keyword()
) :: {:ok, term()} | {:error, BilldogEng.Error.t()}

Dispatch a message. See BilldogEng.Messaging.dispatch/2.

fetch_survey(client, survey_id, opts \\ [])

See BilldogEng.Surveys.fetch/3.

flush(c)

@spec flush(t()) :: :ok | {:error, BilldogEng.Error.t()}

Flush queued analytics events now.

get_all_flags(c, distinct_id, opts \\ [])

@spec get_all_flags(t(), String.t(), keyword()) :: map()

Evaluate all known flags for a user.

get_feature_flag(c, key, distinct_id, opts \\ [])

@spec get_feature_flag(t(), String.t(), String.t(), keyword()) ::
  boolean() | String.t() | nil

Get a flag value: boolean, variant key string, or nil if unknown.

get_feature_flag_payload(c, key, distinct_id, opts \\ [])

@spec get_feature_flag_payload(t(), String.t(), String.t(), keyword()) :: term()

Get a flag's payload (variant config), local mode.

group_identify(c, group_type, group_key, properties \\ %{})

@spec group_identify(t(), String.t(), String.t(), map()) :: :ok

Set group properties. Emits $groupidentify.

identify(c, distinct_id, properties \\ %{})

@spec identify(t(), String.t(), map()) :: :ok

Set person properties. Emits $identify.

is_feature_enabled(c, key, distinct_id, opts \\ [])

@spec is_feature_enabled(t(), String.t(), String.t(), keyword()) :: boolean()

Whether a flag is enabled for the user.

list_surveys(client, opts \\ [])

See BilldogEng.Surveys.list/2.

new(api_key, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Construct a client.

Options

  • :host — base URL (default "https://api.billdog.io/v1")
  • :flush_at — batch size that triggers a flush (default 20)
  • :flush_interval — background flush cadence in ms (default 10_000)
  • :max_queue_size — max queued events before oldest are dropped (default 1000)
  • :gzip — gzip large request bodies (default true)
  • :local_evaluation — enable local feature-flag evaluation (default false)
  • :request_timeout — per-request timeout in ms (default 10_000)
  • :max_retries — retry attempts for 5xx/network errors (default 3)
  • :group_type_index — map of group-type → positional index 0..4
  • :enable_logging — emit verbose diagnostics (default false)
  • :sleep_fn — injectable sleep (tests)

new!(api_key, opts \\ [])

@spec new!(
  String.t(),
  keyword()
) :: t()

Like new/2 but raises on error.

queue_length(c)

@spec queue_length(t()) :: non_neg_integer()

Number of events currently queued (test/observability aid).

record_partial(client, survey_id, respondent_id, answers, context \\ [])

See BilldogEng.Surveys.record_partial/5.

reload_feature_flag_definitions(c)

@spec reload_feature_flag_definitions(t()) :: :ok

Reload local flag definitions (local mode).

set_definitions(c, defs)

@spec set_definitions(t(), [map()]) :: :ok

Inject flag definitions directly, bypassing the network (advanced/tests).

shutdown(c)

@spec shutdown(t()) :: :ok | {:error, BilldogEng.Error.t()}

Flush remaining events and stop the background flush timer.

start_survey(client, survey_id, context \\ [])

See BilldogEng.Surveys.start/3.

submit_survey(client, survey_id, answers, context \\ [])

See BilldogEng.Surveys.submit/4.