billdogeng 1.0.2.pre.beta.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfff3e8914b52fef194e6ba43a996ca3a9fbf9aa3c35bcb0a842e9df8013f997
+  data.tar.gz: fe59c1944e99b1fb80344d75780f5d73024c209d15e051eb10c264576ac9133b
+SHA512:
+  metadata.gz: 28df3557077d20a6638ca9bc51d5a8984e33ff413b987fed508f7d5a1f8fdaa8466e5d3f5dc4c2589d7930a4a23af6eb69fb1a92f9995a679631d6ca2d2d08bf
+  data.tar.gz: 4b7c2897e20fa020d6c40f58fc651c80e5378c8707d503aa6cf1f1d6eefd4cf88fe0bd16a0ff72a17e6e80e797d3556491013a7c66d1774212f42b052ded2681

data/README.md

@@ -0,0 +1,173 @@
+# billdogeng (Ruby)
+
+Official **BilldogEng** server SDK for Ruby — the engagement suite for
+server-side use: **Analytics**, **Feature Flags** (remote + local evaluation),
+**Surveys** (data API), **Messaging** dispatch, and **LLM** observability.
+
+Pure Ruby standard library (`net/http`, `json`, `zlib`) — no runtime
+dependencies. Wire-compatible with every other `billdogeng-*` server SDK so the
+cross-language parity corpus passes.
+
+## Install
+
+```ruby
+# Gemfile
+gem "billdogeng"
+```
+
+```sh
+bundle install
+# or
+gem install billdogeng
+```
+
+## Quickstart
+
+```ruby
+require "billdogeng"
+
+bd = BilldogEng.new("bd_test_xxx", local_evaluation: true)
+
+# Analytics (batched + background flush + gzip + backoff retry)
+bd.capture("user-123", "order_completed", { "revenue" => 49.99 })
+bd.identify("user-123", { "email" => "a@b.com", "plan" => "pro" })
+bd.group_identify("company", "acme", { "seats" => 50 })
+bd.alias("user-123", "anon-abc")
+
+# Feature flags (local, deterministic murmurhash3 bucketing)
+on      = bd.feature_enabled?("new_checkout", "user-123")
+value   = bd.get_feature_flag("new_checkout", "user-123",
+                              person_properties: { "plan" => "pro" })
+payload = bd.get_feature_flag_payload("new_checkout", "user-123")
+all     = bd.get_all_flags("user-123")
+
+# Surveys (data API)
+list   = bd.surveys.list("user-123")
+config = bd.surveys.fetch(survey_id, "user-123")
+start  = bd.surveys.start(survey_id, customer_id: "user-123", idempotency_key: "idem-1")
+bd.surveys.record_partial(survey_id, start["respondent_id"], answers)
+bd.surveys.submit(survey_id, answers, respondent_id: start["respondent_id"])
+bd.surveys.abandon(survey_id, start["respondent_id"])
+
+# Messaging dispatch (Bearer JWT, not X-BillDog-API-Key)
+bd.messaging.dispatch(
+  project_id:   "…",
+  channel:      "push",
+  content:      { "title" => "Hi", "body" => "There" },
+  targeting:    { "type" => "all" },
+  scheduling:   { "deliveryType" => "immediate" },
+  access_token: "<supabase-session-jwt>",
+)
+
+# LLM observability
+bd.llm.capture_trace(
+  trace_id: "t-1", span_id: "s-1", model: "claude-opus-4-8",
+  input_text: "hello", output_text: "hi",
+  prompt_tokens: 10, completion_tokens: 5, duration_ms: 123, cost_usd: 0.002,
+)
+
+# Flush remaining events and stop the background timer.
+bd.shutdown
+```
+
+## Configuration
+
+| Option              | Default                        | Description                                  |
+| ------------------- | ------------------------------ | -------------------------------------------- |
+| `host`              | `https://api.billdog.io/v1`    | Base URL for all requests                    |
+| `flush_at`          | `20`                           | Queue size that triggers an automatic flush  |
+| `flush_interval`    | `10_000`                       | Background flush cadence (ms)                |
+| `max_queue_size`    | `1000`                         | Drop oldest events beyond this               |
+| `gzip`              | `true`                         | Gzip large request bodies                    |
+| `local_evaluation`  | `false`                        | Evaluate feature flags locally (server only) |
+| `request_timeout`   | `10_000`                       | Per-request timeout (ms)                     |
+| `max_retries`       | `3`                            | Retry attempts for 5xx / 429 / network       |
+| `enable_logging`    | `false`                        | Verbose diagnostics to stderr                |
+
+Auth: every request sends `X-BillDog-API-Key: <apiKey>` (`bd_test_*` sandbox /
+`bd_live_*` live). Messaging dispatch instead authenticates with a per-call
+Bearer JWT (`access_token`).
+
+## Exhausted allowance (`quota_limited`)
+
+Ingestion answers a drained meter with **HTTP 200** and a top-level
+`quota_limited` array — never an error status — so your app is never broken by
+your BillDog meter filling up. The data in that batch was **not** stored.
+
+The SDK reads those 200s and suspends: it stops flushing, `capture` /
+`identify` / `group_identify` / `alias` become no-ops (buffering data the server
+has already refused would just grow your process's memory), and the reason is
+written to stderr **once**, regardless of `enable_logging` — it is the only
+signal your pipeline has gone dark:
+
+```
+[BilldogEng:analytics] Your free plan's monthly events allowance (1,000,000) is exhausted — this data was not stored.
+```
+
+It also heals itself: every 15 minutes one probe batch is allowed through, and
+the first one accepted resumes normal flushing (logging `allowance restored`
+once). So a monthly reset or a plan upgrade brings the pipeline back with no
+redeploy. `flush` / `shutdown` never raise or block on a quota refusal.
+
+## Feature-flag evaluation
+
+Local evaluation fetches flag **definitions** from `/feature-flag-definitions`
+once, caches them (5-minute TTL / `reload_feature_flag_definitions`), and
+evaluates deterministically:
+
+1. missing / inactive → `false`
+2. the flag's `targeting_rule` — the ONE canonical audience DSL, evaluated by
+   `BilldogEng::Targeting` — must match, else `false`. AND/OR combinators, date
+   windows, rule status, group membership, experiment-variant dependencies and
+   the full operator set all resolve locally, with no server round-trip:
+
+   ```ruby
+   bd.get_feature_flag("beta", "user-123",
+                       country: "US", platform: "ios",
+                       app_version: "2.5", sdk_version: "1.4",
+                       groups: { "organisation" => "acme" },
+                       person_properties: { "plan" => "pro" },
+                       experiment_variants: { "exp-1" => "treatment" })
+   ```
+
+   `country` / `platform` / `app_version` / `sdk_version` each fall back to a
+   same-named person property when not passed explicitly.
+3. `bucket = murmurhash3("flag:{key}:{distinct_id}") % 100`; ON iff `bucket < rollout_percentage`
+4. multivariate: walk `variants` by cumulative rollout against an INDEPENDENT
+   hash, `murmurhash3("flag-variant:{key}:{distinct_id}") % 100`
+
+Conditions that only the database can answer (`segment`, `cohort`,
+`survey_answer`, `event_fired_in_window`, `group_property`) are never guessed at:
+they go **cold** and the flag is resolved against the server instead. Such flags
+are normally already marked `requires_server_evaluation`.
+
+The `murmurhash3` (32-bit, seed 0, UTF-8 bytes) is identical across web / iOS /
+Android / every server SDK, so a user buckets the same everywhere. Both the
+bucketing and the audience evaluator are pinned to fixtures generated from the
+backend (`tests/fixtures/flag-bucketing.json`, `tests/fixtures/flag-targeting.json`).
+
+## Tests
+
+```sh
+bundle install && bundle exec rspec
+```
+
+Covers: batching (10 captures → 1 POST), identify/group shapes, the 12 canonical
+murmurhash3 vectors + rollout/targeting/multivariate eval, 503-then-200 retry
+with backoff, the `quota_limited` 200 suspend / self-heal path, and a survey
+round-trip + messaging dispatch shape (all against a local WEBrick stub).
+
+## BillDog Auth
+
+Session-token verification is **not available in this SDK yet**.
+[`billdogeng-node`](https://www.npmjs.com/package/billdogeng-node) is the only
+server SDK that can verify a BillDog Auth token offline today.
+
+Until it lands here, either verify in a Node service, or call the
+`auth-introspect` endpoint over HTTP — that costs a network round-trip per
+check, and in exchange tells you whether the session is live *right now* rather
+than only that the token was valid when it was issued.
+
+## License
+
+MIT