feat: anonymous adoption telemetry on first client.New

Sends one fire-and-forget POST per process the first time a consumer
constructs a Bot via client.New. Helps track real-world adoption and
version spread of the library. No identifiers, no API contents.

Implementation:
- new client/version.go: exported Version var (currently 0.7.11)
- new client/telemetry.go: sync.Once gate + telemetry.Send call
- client.go New(): single fireTelemetryOnce() line at function entry
- client/telemetry_test.go: TestMain disables outgoing pings during the
  library's own test suite

README §Telemetry documents the payload, the opt-out env vars, and links
to the upstream oss-telemetry source so consumers can audit what is sent.

Opt out via any of:
  DO_NOT_TRACK=1
  OSS_TELEMETRY_DISABLED=1
  GO_TELEGRAM_DISABLE_TELEMETRY=1
  osstelemetry.Disable() before the first client.New
This commit is contained in:
2026-05-21 03:59:07 +01:00
parent d39be13822
commit 609c4ce649
7 changed files with 137 additions and 1 deletions
+31
View File
@@ -371,6 +371,37 @@ bot := client.New("token", client.WithHTTPClient(fakeDoer{
The library's own generated test suite (`api/methods_gen_test.go`) covers 176 methods × 8 scenarios each: Success, APIError, NetworkError, ParseError, ContextCanceled, MissingRequiredFields, Forbidden, ServerError.
## Telemetry
On the **first call to `client.New`** in a process, this library sends a single
anonymous HTTP POST to `https://oss.raczylo.com/v1/ping` containing exactly
this body:
```json
{ "project": "go-telegram", "version": "0.7.11", "ts": 1747782200 }
```
This helps us see approximate adoption and version spread. No identifiers,
no telemetry of API calls, no message contents, no tokens, no IPs stored
beyond a short server-side dedupe window. The ping is fire-and-forget —
it never blocks `New`, never panics, never returns errors, and a 2-second
timeout caps any network impact.
Telemetry source: [`client/telemetry.go`](client/telemetry.go) and the
upstream library [`github.com/lukaszraczylo/oss-telemetry`](https://github.com/lukaszraczylo/oss-telemetry).
### Opting out
Any one of these turns it off (case-insensitive truthy values
`1`, `true`, `yes`, `on`):
| Mechanism | How |
| ------------------------ | -------------------------------------------- |
| Universal opt-out | `DO_NOT_TRACK=1` |
| Library-wide opt-out | `OSS_TELEMETRY_DISABLED=1` |
| Per-library opt-out | `GO_TELEGRAM_DISABLE_TELEMETRY=1` |
| Programmatic | `osstelemetry.Disable()` before `client.New` |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).