dregs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4f2ed05bc7ad6b7f11275cd1433eb3289d2eb9e0591067bbf238bf65c614e1d
+  data.tar.gz: cdd0d2097662216dee63c3453ea925295f62710adbc546d3c3e8ee1e8ae96b9e
+SHA512:
+  metadata.gz: 5f41a1a52cdc61c9cdd50f8b8fcba9ebd635070946eeaea1330da0494f167138bc9f0c4ebd6b766181f779bf328a5ad221779cc4d72731a32687e1a1efc05271
+  data.tar.gz: 86d8d64737dabd2c619b94a45795b774cf5035bfed7dc7494be30f1255ff0c41b2269967e2f52f9941bfdd408baeb33cac6dabccd6b83224ce8ffbb2f84f3b89

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-22
+
+The first release. A server-side client for tracking events and reading scores.
+
+### Added
+
+- `Dregs::Client`, authenticating with a credential's `sk_` secret key against a configurable base
+  URL, with no runtime dependencies beyond the standard library.
+- `track` for recording backend events against an identity, always sending an idempotency `id` so a
+  retry cannot double-count.
+- `identities.get`, `identities.scores`, `identities.analysis`, and `identities.analyze`.
+- Typed errors for 400, 401, 402, 403, 404, 429, and 5xx, plus connection and timeout failures, all
+  deriving from `Dregs::Error`.
+- Automatic retries with exponential backoff and jitter, honouring `Retry-After`.
+- `Dregs::Webhooks.verify` for checking a webhook's signature and rejecting replays.
+- Lenient models with a `raw` escape hatch, and RBS signatures in `sig/`.
+
+[Unreleased]: https://github.com/dregs-sdk/dregs-sdk-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dregs-sdk/dregs-sdk-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dregs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,247 @@
+# Dregs Ruby SDK
+
+[![Gem](https://img.shields.io/gem/v/dregs.svg)](https://rubygems.org/gems/dregs)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/github/license/dregs-sdk/dregs-sdk-ruby.svg)](LICENSE)
+
+The official Ruby client for [Dregs](https://dregs.com), which scores the users of your application
+for fraud and abuse across four categories: humanity, authenticity, uniqueness, and behavior.
+
+Send events from your backend, read back the scores and the observations behind them.
+
+```bash
+bundle add dregs
+```
+
+The gem has no runtime dependencies: it uses `net/http`, `json`, and `openssl` from the standard
+library, so adding it cannot conflict with the HTTP client your application already has.
+
+## Getting started
+
+You need the **secret key** from an API credential, which you will find under **Settings → Credentials**
+in the Dregs dashboard. It starts with `sk_`. The `pk_` public key is for the browser tracker and cannot
+read identities or scores.
+
+```ruby
+require "dregs"
+
+client = Dregs::Client.new(secret_key: ENV.fetch("DREGS_SECRET_KEY"))
+```
+
+The key is read from `DREGS_SECRET_KEY` when you do not pass one, so `Dregs::Client.new` on its own is
+usually enough. Build one at startup and keep it; the client holds no per-request state, so it is safe
+to share across threads.
+
+## Tracking events
+
+```ruby
+client.track(
+  "user.signup",
+  identity: "user_12345",
+  data: { plan: "pro", referrer: "partner-x" },
+  identity_data: { email: "ada@example.com", name: "Ada Lovelace" }
+)
+```
+
+`identity:` is your own id for the user — the same one you pass to `dregs.identify()` in the browser
+tracker, and the one you look scores up by. It is required: a server-side event carries no device
+signature, so the identity is the only thing tying the event to a user.
+
+`identity_data:` carries attributes of the *user* rather than the event. The analyzers lean on these
+heavily, so send them whenever you have them. Name the keys the way your application already does and
+map them to Dregs's canonical fields under **Settings → Mappings**; the same goes for event names.
+
+### Idempotency
+
+Every event is sent with an `id`, which makes ingestion idempotent: reposting the same id returns the
+original event instead of recording a second one. Pass the id your application already has, and a retry
+after a timeout can never double-count.
+
+```ruby
+client.track("purchase", identity: "user_12345", event_id: "order-#{order.id}")
+```
+
+When you omit it the SDK generates one, which is what makes its own retries safe.
+
+### What comes back
+
+```ruby
+result = client.track("user.signup", identity: "user_12345")
+
+result.accepted?  # true when Dregs recorded the event
+result.id         # the event's id
+```
+
+`accepted?` is `false` in the uncommon case where Dregs accepts the request without recording
+an event. Failures that are yours to act on raise instead — see [Errors](#errors).
+
+## Reading scores
+
+```ruby
+scores = client.identities.scores("user_12345")
+
+scores.humanity      # 85
+scores.authenticity  # 72
+scores.uniqueness    # 91
+scores.behavior      # 68
+```
+
+This is the cheap read and the one most integrations want. A category Dregs has not scored yet reads as
+`nil`, and a brand-new identity comes back empty. `Scores` is `Enumerable`, so you can map and sort it.
+
+Scoring is **asynchronous**. Scores appear moments after the events that move them, not in the same
+breath, so read them at a decision point rather than immediately after a `track` call.
+
+```ruby
+hold_for_review("user_12345") if scores.authenticity && scores.authenticity < 40
+```
+
+### Seeing exactly why
+
+The scores are the summary; the observations are the evidence. When you need to show or log *why* an
+identity scored the way it did, ask for the analysis.
+
+```ruby
+analysis = client.identities.analysis("user_12345")
+
+analysis.observations.each do |observation|
+  puts "#{observation.label}: #{observation.explanation} (value #{observation.value})"
+end
+```
+
+Each observation carries the analyzer that produced it, a `value` from 0.0 (suspicious) to 1.0
+(legitimate), a `confidence`, a `weight`, and the counts behind the finding in `metadata`. `analysis`
+raises `Dregs::NotFoundError` until the identity has been analyzed at least once.
+
+### The whole identity
+
+```ruby
+identity = client.identities.get("user_12345")
+
+identity.display_email   # "ada@example.com"
+identity.humanity_score  # 85
+identity.badges          # [#<Dregs::Badge name="Account Takeover Suspected" ...>]
+identity.data            # every attribute you have sent
+```
+
+### Forcing a rescore
+
+```ruby
+client.identities.analyze("user_12345")
+```
+
+This queues the work and returns; it does not wait for the cycle to finish. Dregs rescores on its own
+as events arrive, so you rarely need this outside of a support or backfill flow.
+
+## Errors
+
+```ruby
+begin
+  client.track("user.signup", identity: "user_12345")
+rescue Dregs::QuotaExceededError
+  # over the monthly event limit; the event was not queued
+rescue Dregs::RateLimitError => e
+  # ingesting too fast; e.retry_after when the server said how long
+rescue Dregs::Error => e
+  # anything else this library raises
+end
+```
+
+| Exception | When |
+| --- | --- |
+| `Dregs::BadRequestError` | 400, the event was malformed |
+| `Dregs::AuthenticationError` | 401, the secret key was not recognized |
+| `Dregs::QuotaExceededError` | 402, the account is over its monthly event limit |
+| `Dregs::PermissionDeniedError` | 403, the credential may not do this |
+| `Dregs::NotFoundError` | 404, no such identity, or it has not been analyzed |
+| `Dregs::RateLimitError` | 429, too many requests |
+| `Dregs::ServerError` | 5xx |
+| `Dregs::TimeoutError` | the request timed out |
+| `Dregs::ConnectionError` | the request never reached Dregs |
+
+All of them derive from `Dregs::Error`. Those that reached the API also derive from `Dregs::APIError`
+and carry `status_code`, `body`, and `request_id`. A mistake in how you called the SDK — a missing
+secret key, an event id the API would refuse — raises `ArgumentError` before anything leaves the
+process.
+
+### Retries
+
+Connection failures, timeouts, 429s, and 5xx are retried automatically with exponential backoff and
+jitter, honouring `Retry-After` when the server sends one. Two retries by default:
+
+```ruby
+client = Dregs::Client.new(max_retries: 5)  # or 0 to handle it yourself
+```
+
+## Concurrency
+
+The client is synchronous: every call blocks until Dregs answers or the retries run out. Ruby has no
+idiomatic async twin to offer, so there is one client rather than two.
+
+It holds no connection state between calls, which makes it safe to share across threads and to call
+from a background job. If you do not want a signup to wait on an HTTP round trip, put the `track` call
+in Sidekiq, Active Job, or a thread pool rather than reaching for a different client.
+
+## Webhooks
+
+Dregs signs every webhook with the channel's signing secret. Verify it against the **raw request body**
+before acting on the payload — a re-serialized hash will not match, because key order and whitespace
+change.
+
+```ruby
+post "/webhooks/dregs" do
+  event = Dregs::Webhooks.verify(
+    payload: request.body.read,
+    signature: request.env["HTTP_X_DREGS_SIGNATURE"],
+    secret: ENV.fetch("DREGS_WEBHOOK_SECRET")
+  )
+
+  handle(event)
+rescue Dregs::WebhookVerificationError
+  halt 400
+end
+```
+
+In Rails the raw body is `request.raw_post`; in Rack it is `request.body.read`, and you may need to
+`rewind` the body if something downstream reads it again. Do not use `params` — by the time Rails has
+parsed and merged them, the bytes that were signed are gone.
+
+`verify` also rejects payloads older than five minutes as replays; pass `tolerance: nil` to skip that if
+you are deduplicating on the event id yourself. The signing secret is shown once, when you create the
+webhook channel, and is not your API secret key.
+
+## Configuration
+
+```ruby
+client = Dregs::Client.new(
+  secret_key: nil,  # defaults to $DREGS_SECRET_KEY
+  base_url: nil,    # defaults to $DREGS_BASE_URL, then https://dregs.com/api
+  timeout: 10,      # seconds, for connecting and for reading
+  max_retries: 2
+)
+```
+
+## Type signatures
+
+The gem ships RBS signatures in `sig/`, so Steep, RBS, and editors that read them see the full surface
+without stubs. Responses are plain objects with readers; each one also keeps the body it was built from
+in `raw`, so a field Dregs adds after this release is reachable without waiting for an SDK upgrade.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version:
+
+```bash
+bundle install
+bundle exec rake        # rubocop, rbs validate, and rspec
+```
+
+## Links
+
+- [Dregs manual](https://dregs.com/manual/) and [REST API reference](https://dregs.com/manual/api/)
+- [Dregs MCP server](https://github.com/dregs-sdk/dregs-mcp), for connecting AI agents to your data
+- [Security policy](SECURITY.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/SECURITY.md

@@ -0,0 +1,36 @@
+# Security
+
+## Reporting a vulnerability
+
+Report security issues in this SDK, or anywhere else in the Dregs service, to
+[security@dregs.com](mailto:security@dregs.com). Dregs's
+[security page](https://dregs.com/legal/security/) describes how reports are handled. Please
+don't open a public GitHub issue for security reports.
+
+## Handling keys
+
+- The **secret key** (`sk_…`) this SDK authenticates with acts as an administrator of the team
+  that owns it. Treat it like a password: keep it in your server's environment or secret manager,
+  never in source control, and never anywhere a browser can reach it.
+- The **public key** (`pk_…`) is the one that belongs in a browser. It is a different credential
+  and cannot read identities or scores. This SDK refuses one with an explanation rather than
+  letting you discover the difference through confusing 401s.
+- A credential's **webhook signing secret** is a third value again. It proves a payload came from
+  Dregs; it does not authenticate you to Dregs. Rotate it separately.
+- Revoke a leaked credential under **Settings → Credentials** in the dashboard. Revocation takes
+  effect immediately.
+
+## Verifying webhooks
+
+Verify every webhook before acting on it, against the **raw request body**. `Dregs::Webhooks.verify`
+does the HMAC comparison in constant time, with `OpenSSL.secure_compare`, and rejects stale payloads
+as replays. Verifying a re-serialized hash instead of the received bytes will not match, and working
+around that by skipping verification would leave the endpoint open to anyone who learns its URL. In
+Rails, read `request.raw_post` rather than `params`.
+
+## Treating scored data as untrusted
+
+The identity attributes, display names, and event data this SDK returns were written by the users
+being scored. Treat them as untrusted input: escape them before rendering, and do not feed them to
+an LLM or an agent as instructions. This matters more than usual here, because the people writing
+that data are, by construction, the ones trying to get something past you.