ci(regen): merge the weekly regeneration PR automatically

The weekly job already gates the update. `make regen` fails on any audit
fallback and the test step runs the full race suite, so a PR only opens when
both pass. Merge it from the same job.

A PR opened with GITHUB_TOKEN does not trigger ci.yml, so GitHub auto-merge
would wait for checks that never start. The push to main triggers ci.yml,
which cuts the release.

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
         with:
           go-version: '1.25.x'
           check-latest: true
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/go/pkg/mod
@@ -46,7 +46,7 @@ jobs:
         with:
           go-version: '1.25.x'
           check-latest: true
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/go/pkg/mod
@@ -63,7 +63,7 @@ jobs:
         with:
           go-version: '1.25.x'
           check-latest: true
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/go/pkg/mod
@@ -80,7 +80,7 @@ jobs:
         with:
           go-version: '1.25.x'
           check-latest: true
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/go/pkg/mod
@@ -103,7 +103,7 @@ jobs:
         with:
           go-version: '1.25.x'
           check-latest: true
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/go/pkg/mod
@@ -112,7 +112,7 @@ jobs:
       - run: go test -race -coverprofile=coverage.out ./...
       - name: Build all examples
         run: go build ./examples/...
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: coverage
           path: coverage.out
@@ -125,7 +125,7 @@ jobs:
         with:
           go-version: '1.25.x'
           check-latest: true
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/go/pkg/mod
@@ -146,7 +146,7 @@ jobs:
         with:
           go-version: '1.25.x'
           check-latest: true
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: |
             ~/go/pkg/mod
@@ -258,7 +258,7 @@ jobs:
 
       - name: Run GoReleaser
         if: github.event_name != 'workflow_dispatch' || inputs.dry-run-release == false
-        uses: goreleaser/goreleaser-action@v6
+        uses: goreleaser/goreleaser-action@v7
         with:
           distribution: goreleaser
           version: '~> v2'

.github/workflows/regen.yml

@@ -88,6 +88,7 @@ jobs:
           echo "version=$VERSION" >> $GITHUB_OUTPUT
 
       - name: Open PR
+        id: pr
         if: steps.diff.outputs.no_changes != 'true'
         uses: peter-evans/create-pull-request@v8
         with:
@@ -115,4 +116,17 @@ jobs:
 
             Inspect the IR diff (`internal/spec/api.json`) for added/changed/removed methods.
 
-            CI must pass before merge. Auto-merge: enable when satisfied with the diff.
+            This PR merges itself once every step above passes. The gates are
+            `make regen` (which fails on any audit fallback) and `go test -race ./...`,
+            both run in this job before the PR opens.
+
+      # A PR opened with GITHUB_TOKEN does not trigger `ci.yml`, so waiting for
+      # PR checks would wait forever. The gates already ran in this job: `make
+      # regen` fails on any audit fallback, and the test step runs the full race
+      # suite. Merging here therefore means "merged because the checks passed".
+      # `ci.yml` then runs on the push to main and cuts the release.
+      - name: Merge regen PR
+        if: steps.diff.outputs.no_changes != 'true' && steps.pr.outputs.pull-request-number != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh pr merge "${{ steps.pr.outputs.pull-request-number }}" --squash --delete-branch

Makefile

@@ -35,7 +35,10 @@ lint: vet
 integration:
 	$(GO) test -tags=integration -v ./test/integration/...
 
-SCRAPE_INPUT ?= testdata/html/snapshot_2026-05-08.html
+# Resolve via testdata/html/latest.html symlink so the pinned-fixture target
+# auto-tracks whatever snapshot regen.yml last committed. Override with
+# SCRAPE_INPUT=path/to/snapshot.html for ad-hoc replays.
+SCRAPE_INPUT ?= testdata/html/$(shell readlink testdata/html/latest.html)
 SCRAPE_OUTPUT ?= internal/spec/api.json
 
 snapshot:

README.md

@@ -371,6 +371,20 @@ 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 adoption ping — project name, version, timestamp; no
+identifiers, no message contents, no API call metadata. Fire-and-forget
+with a 2-second timeout; cannot block `New` or panic.
+
+Local source: [`client/telemetry.go`](client/telemetry.go). Upstream
+implementation, exact wire format, and full opt-out documentation:
+**[oss-telemetry — Disabling telemetry](https://github.com/lukaszraczylo/oss-telemetry#disabling-telemetry)**.
+
+Quick opt-out: set any of `DO_NOT_TRACK=1`, `OSS_TELEMETRY_DISABLED=1`,
+or `GO_TELEGRAM_DISABLE_TELEMETRY=1`.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

api/enums.gen.go

@@ -33,6 +33,14 @@ const (
 	BotCommandScopeTypeChatMember            BotCommandScopeType = "chat_member"
 )
 
+type BotSubscriptionUpdatedState string
+
+const (
+	BotSubscriptionUpdatedStateCanceled BotSubscriptionUpdatedState = "canceled"
+	BotSubscriptionUpdatedStateActive   BotSubscriptionUpdatedState = "active"
+	BotSubscriptionUpdatedStateFailed   BotSubscriptionUpdatedState = "failed"
+)
+
 type ChatBoostSourceKind string
 
 const (
@@ -133,6 +141,12 @@ const (
 	InputMediaTypeVideo     InputMediaType = "video"
 )
 
+type InputMediaVoiceNoteType string
+
+const (
+	InputMediaVoiceNoteTypeVoiceNote InputMediaVoiceNoteType = "voice_note"
+)
+
 type InputPaidMediaType string
 
 const (
@@ -158,6 +172,7 @@ type InputPollOptionMediaType string
 
 const (
 	InputPollOptionMediaTypeAnimation InputPollOptionMediaType = "animation"
+	InputPollOptionMediaTypeLink      InputPollOptionMediaType = "link"
 	InputPollOptionMediaTypeLivePhoto InputPollOptionMediaType = "live_photo"
 	InputPollOptionMediaTypeLocation  InputPollOptionMediaType = "location"
 	InputPollOptionMediaTypePhoto     InputPollOptionMediaType = "photo"
@@ -173,6 +188,32 @@ const (
 	InputProfilePhotoTypeAnimated InputProfilePhotoType = "animated"
 )
 
+type InputRichBlockType string
+
+const (
+	InputRichBlockTypeParagraph              InputRichBlockType = "paragraph"
+	InputRichBlockTypeHeading                InputRichBlockType = "heading"
+	InputRichBlockTypePre                    InputRichBlockType = "pre"
+	InputRichBlockTypeFooter                 InputRichBlockType = "footer"
+	InputRichBlockTypeDivider                InputRichBlockType = "divider"
+	InputRichBlockTypeMathematicalExpression InputRichBlockType = "mathematical_expression"
+	InputRichBlockTypeAnchor                 InputRichBlockType = "anchor"
+	InputRichBlockTypeList                   InputRichBlockType = "list"
+	InputRichBlockTypeBlockquote             InputRichBlockType = "blockquote"
+	InputRichBlockTypePullquote              InputRichBlockType = "pullquote"
+	InputRichBlockTypeCollage                InputRichBlockType = "collage"
+	InputRichBlockTypeSlideshow              InputRichBlockType = "slideshow"
+	InputRichBlockTypeTable                  InputRichBlockType = "table"
+	InputRichBlockTypeDetails                InputRichBlockType = "details"
+	InputRichBlockTypeMap                    InputRichBlockType = "map"
+	InputRichBlockTypeAnimation              InputRichBlockType = "animation"
+	InputRichBlockTypeAudio                  InputRichBlockType = "audio"
+	InputRichBlockTypePhoto                  InputRichBlockType = "photo"
+	InputRichBlockTypeVideo                  InputRichBlockType = "video"
+	InputRichBlockTypeVoiceNote              InputRichBlockType = "voice_note"
+	InputRichBlockTypeThinking               InputRichBlockType = "thinking"
+)
+
 type InputStickerFormat string
 
 const (
@@ -357,6 +398,14 @@ const (
 	RefundedPaymentCurrencyXTR RefundedPaymentCurrency = "XTR"
 )
 
+type Result string
+
+const (
+	ResultApprove Result = "approve"
+	ResultDecline Result = "decline"
+	ResultQueue   Result = "queue"
+)
+
 type RevenueWithdrawalStateKind string
 
 const (
@@ -365,6 +414,88 @@ const (
 	RevenueWithdrawalStateKindFailed    RevenueWithdrawalStateKind = "failed"
 )
 
+type RichBlockListItemType string
+
+const (
+	RichBlockListItemTypeLowerA RichBlockListItemType = "a"
+	RichBlockListItemTypeUpperA RichBlockListItemType = "A"
+	RichBlockListItemTypeLowerI RichBlockListItemType = "i"
+	RichBlockListItemTypeUpperI RichBlockListItemType = "I"
+	RichBlockListItemType1      RichBlockListItemType = "1"
+)
+
+type RichBlockTableCellAlign string
+
+const (
+	RichBlockTableCellAlignLeft   RichBlockTableCellAlign = "left"
+	RichBlockTableCellAlignCenter RichBlockTableCellAlign = "center"
+	RichBlockTableCellAlignRight  RichBlockTableCellAlign = "right"
+)
+
+type RichBlockTableCellValign string
+
+const (
+	RichBlockTableCellValignTop    RichBlockTableCellValign = "top"
+	RichBlockTableCellValignMiddle RichBlockTableCellValign = "middle"
+	RichBlockTableCellValignBottom RichBlockTableCellValign = "bottom"
+)
+
+type RichBlockType string
+
+const (
+	RichBlockTypeParagraph              RichBlockType = "paragraph"
+	RichBlockTypeHeading                RichBlockType = "heading"
+	RichBlockTypePre                    RichBlockType = "pre"
+	RichBlockTypeFooter                 RichBlockType = "footer"
+	RichBlockTypeDivider                RichBlockType = "divider"
+	RichBlockTypeMathematicalExpression RichBlockType = "mathematical_expression"
+	RichBlockTypeAnchor                 RichBlockType = "anchor"
+	RichBlockTypeList                   RichBlockType = "list"
+	RichBlockTypeBlockquote             RichBlockType = "blockquote"
+	RichBlockTypePullquote              RichBlockType = "pullquote"
+	RichBlockTypeCollage                RichBlockType = "collage"
+	RichBlockTypeSlideshow              RichBlockType = "slideshow"
+	RichBlockTypeTable                  RichBlockType = "table"
+	RichBlockTypeDetails                RichBlockType = "details"
+	RichBlockTypeMap                    RichBlockType = "map"
+	RichBlockTypeAnimation              RichBlockType = "animation"
+	RichBlockTypeAudio                  RichBlockType = "audio"
+	RichBlockTypePhoto                  RichBlockType = "photo"
+	RichBlockTypeVideo                  RichBlockType = "video"
+	RichBlockTypeVoiceNote              RichBlockType = "voice_note"
+	RichBlockTypeThinking               RichBlockType = "thinking"
+)
+
+type RichTextType string
+
+const (
+	RichTextTypeBold                   RichTextType = "bold"
+	RichTextTypeItalic                 RichTextType = "italic"
+	RichTextTypeUnderline              RichTextType = "underline"
+	RichTextTypeStrikethrough          RichTextType = "strikethrough"
+	RichTextTypeSpoiler                RichTextType = "spoiler"
+	RichTextTypeDateTime               RichTextType = "date_time"
+	RichTextTypeTextMention            RichTextType = "text_mention"
+	RichTextTypeSubscript              RichTextType = "subscript"
+	RichTextTypeSuperscript            RichTextType = "superscript"
+	RichTextTypeMarked                 RichTextType = "marked"
+	RichTextTypeCode                   RichTextType = "code"
+	RichTextTypeCustomEmoji            RichTextType = "custom_emoji"
+	RichTextTypeMathematicalExpression RichTextType = "mathematical_expression"
+	RichTextTypeURL                    RichTextType = "url"
+	RichTextTypeEmailAddress           RichTextType = "email_address"
+	RichTextTypePhoneNumber            RichTextType = "phone_number"
+	RichTextTypeBankCardNumber         RichTextType = "bank_card_number"
+	RichTextTypeMention                RichTextType = "mention"
+	RichTextTypeHashtag                RichTextType = "hashtag"
+	RichTextTypeCashtag                RichTextType = "cashtag"
+	RichTextTypeBotCommand             RichTextType = "bot_command"
+	RichTextTypeAnchor                 RichTextType = "anchor"
+	RichTextTypeAnchorLink             RichTextType = "anchor_link"
+	RichTextTypeReference              RichTextType = "reference"
+	RichTextTypeReferenceLink          RichTextType = "reference_link"
+)
+
 type StickerType string
 
 const (

client/client.go

@@ -45,6 +45,7 @@ func (b *Bot) Logger() Logger { return b.logger }
 // NewDefaultHTTPDoer); the default codec wraps encoding/json; the default
 // logger discards records.
 func New(token string, opts ...Option) *Bot {
+	fireTelemetryOnce()
 	b := &Bot{
 		token:  token,
 		base:   defaultBaseURL,

client/telemetry.go

@@ -0,0 +1,33 @@
+package client
+
+import (
+	"sync"
+
+	telemetry "github.com/lukaszraczylo/oss-telemetry"
+)
+
+// telemetryOnce guards the single anonymous "library used" ping that is sent
+// on the first call to New. Long-running bots typically construct one Bot;
+// short-lived programs or test suites may construct many, but the Once gate
+// keeps the fire-and-forget call from amplifying into per-construction pings.
+var telemetryOnce sync.Once
+
+// fireTelemetryOnce dispatches a fire-and-forget anonymous adoption ping.
+//
+// The call is failproof by contract of oss-telemetry: it never blocks New,
+// never panics, never returns errors, and silently no-ops if disabled or
+// if the network is unavailable.
+//
+// Opt-out is honored via any of these environment variables (case-insensitive
+// truthy values "1", "true", "yes", "on"):
+//
+//   - DO_NOT_TRACK
+//   - OSS_TELEMETRY_DISABLED
+//   - GO_TELEGRAM_DISABLE_TELEMETRY
+//
+// See README §Telemetry for the full disclosure.
+func fireTelemetryOnce() {
+	telemetryOnce.Do(func() {
+		telemetry.SendForModule("go-telegram", "github.com/lukaszraczylo/go-telegram", Version)
+	})
+}

client/telemetry_test.go

@@ -0,0 +1,54 @@
+package client
+
+import (
+	"os"
+	"sync"
+	"testing"
+
+	telemetry "github.com/lukaszraczylo/oss-telemetry"
+)
+
+// TestMain disables outgoing telemetry for the duration of this package's
+// test suite. The library's own tests construct many Bot instances; without
+// this guard they would each contribute a real ping to the public endpoint.
+// End-user test suites that construct Bot are not affected by this — only
+// tests inside this package are.
+func TestMain(m *testing.M) {
+	telemetry.Disable()
+	os.Exit(m.Run())
+}
+
+// TestFireTelemetryOnce_OnlyFiresOnce verifies the sync.Once gate. Even if
+// New is called repeatedly, the underlying telemetry.Send is invoked at most
+// once per process. We can't observe the network call directly (telemetry
+// is disabled here via TestMain) so we assert on the once-Do count via a
+// fresh local sync.Once paralleling the production one.
+func TestFireTelemetryOnce_OnlyFiresOnce(t *testing.T) {
+	// Reset the package-level Once so this test starts from a clean state.
+	telemetryOnce = sync.Once{}
+	t.Cleanup(func() { telemetryOnce = sync.Once{} })
+
+	calls := 0
+	probe := func() { telemetryOnce.Do(func() { calls++ }) }
+
+	for i := 0; i < 50; i++ {
+		probe()
+	}
+	if calls != 1 {
+		t.Fatalf("expected exactly 1 Once execution, got %d", calls)
+	}
+}
+
+// TestNew_DoesNotPanicUnderRepeatedConstruction is a smoke test that
+// telemetry wiring does not affect New's existing contract. New must never
+// panic, regardless of telemetry state.
+func TestNew_DoesNotPanicUnderRepeatedConstruction(t *testing.T) {
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("New panicked: %v", r)
+		}
+	}()
+	for i := 0; i < 20; i++ {
+		_ = New("test-token-" + string(rune('A'+i)))
+	}
+}

client/version.go

@@ -0,0 +1,11 @@
+package client
+
+// Version is a fallback version string used only when Go's build info is
+// unavailable (replace directives, detached `go run`) or has been overridden
+// via linker flags. The authoritative version forwarded to telemetry is
+// resolved at runtime by [telemetry.SendForModule] from the build info of
+// whatever binary linked this library, so this constant does NOT need to be
+// bumped on every release. Exposed as a var (not const) for ldflag override:
+//
+//	go build -ldflags="-X github.com/lukaszraczylo/go-telegram/client.Version=1.2.3"
+var Version = "0.0.0-fallback"

cmd/audit/extra_test.go

@@ -125,12 +125,18 @@ func TestAuditDrift_InvalidRefReturnsError(t *testing.T) {
 }
 
 func TestAuditDrift_SameRefNoDrift(t *testing.T) {
+	// Compare HEAD's IR against itself, not against the working tree: during a
+	// regen run the working tree legitimately carries new methods, and drift
+	// against HEAD is the expected outcome rather than a failure.
 	irPath := "../../internal/spec/api.json"
-	cur, err := loadIR(irPath)
+	out, err := exec.Command("git", "show", "HEAD:"+irPath).Output()
 	if err != nil {
-		t.Skip("api.json not available, skipping drift test")
+		t.Skip("api.json not available at HEAD, skipping drift test")
 	}
-	changes, err := auditDrift(irPath, "HEAD", cur)
+	var head spec.API
+	require.NoError(t, json.Unmarshal(out, &head))
+
+	changes, err := auditDrift(irPath, "HEAD", &head)
 	require.NoError(t, err)
 	require.Empty(t, changes)
 }
@@ -166,7 +172,7 @@ func TestAuditAny_FlagsUnknownMethodReturn(t *testing.T) {
 			},
 		},
 	}
-	out := auditAny(api)
+	out := auditAny(api, &spec.Overrides{})
 	require.Len(t, out, 1)
 	require.Contains(t, out[0], "any return: weirdMethod")
 }
@@ -182,7 +188,7 @@ func TestAuditAny_FlagsUnknownMethodParam(t *testing.T) {
 			},
 		},
 	}
-	out := auditAny(api)
+	out := auditAny(api, &spec.Overrides{})
 	require.Len(t, out, 1)
 	require.Contains(t, out[0], "any param: weirdMethod.Thing")
 }

cmd/audit/main.go

@@ -54,7 +54,7 @@ func main() {
 	var problems []string
 
 	problems = append(problems, auditBool(api, overrides)...)
-	problems = append(problems, auditAny(api)...)
+	problems = append(problems, auditAny(api, overrides)...)
 
 	driftFound := false
 	if *checkDrift {
@@ -140,8 +140,9 @@ func looksGenuinelyBool(doc string) bool {
 
 // auditAny scans the IR for any KindOneOf TypeRef that would render as
 // `any` in generated code (not matched by ChatID/InputFile-or-string/known
-// union heuristics). Reports each occurrence with location.
-func auditAny(api *spec.API) []string {
+// union heuristics). Reports each occurrence with location, except the
+// locations approved in overrides.
+func auditAny(api *spec.API, ov *spec.Overrides) []string {
 	var out []string
 	isKnownUnion := func(variants []string) bool {
 		if hasVariants(variants, "int64", "string") {
@@ -166,17 +167,17 @@ func auditAny(api *spec.API) []string {
 	}
 	for _, t := range api.Types {
 		for _, f := range t.Fields {
-			if isAny(f.Type) {
+			if isAny(f.Type) && !ov.IsAnyApproved(t.Name+"."+f.Name) {
 				out = append(out, fmt.Sprintf("any field: %s.%s (variants=%v)", t.Name, f.Name, f.Type.Variants))
 			}
 		}
 	}
 	for _, m := range api.Methods {
-		if isAny(m.Returns) {
+		if isAny(m.Returns) && !ov.IsAnyApproved(m.Name) {
 			out = append(out, fmt.Sprintf("any return: %s (variants=%v)", m.Name, m.Returns.Variants))
 		}
 		for _, p := range m.Params {
-			if isAny(p.Type) {
+			if isAny(p.Type) && !ov.IsAnyApproved(m.Name+"."+p.Name) {
 				out = append(out, fmt.Sprintf("any param: %s.%s (variants=%v)", m.Name, p.Name, p.Type.Variants))
 			}
 		}

cmd/audit/main_test.go

@@ -66,11 +66,37 @@ func TestAuditAny_FlagsUnrecognisedOneOf(t *testing.T) {
 			},
 		},
 	}
-	out := auditAny(api)
+	out := auditAny(api, &spec.Overrides{})
 	require.Len(t, out, 1)
 	require.Contains(t, out[0], "any field: Foo.Bar")
 }
 
+func TestAuditAny_SkipsApprovedLocations(t *testing.T) {
+	api := &spec.API{
+		Types: []spec.TypeDecl{
+			{
+				Name: "Foo",
+				Fields: []spec.Field{
+					{Name: "Bar", JSONName: "bar", Type: spec.TypeRef{Kind: spec.KindOneOf, Variants: []string{"A", "B"}}},
+				},
+			},
+		},
+		Methods: []spec.MethodDecl{
+			{
+				Name:    "doThing",
+				Returns: spec.TypeRef{Kind: spec.KindOneOf, Variants: []string{"A", "B"}},
+				Params: []spec.Field{
+					{Name: "Baz", JSONName: "baz", Type: spec.TypeRef{Kind: spec.KindOneOf, Variants: []string{"A", "B"}}},
+				},
+			},
+		},
+	}
+	require.Len(t, auditAny(api, &spec.Overrides{}), 3)
+
+	ov := &spec.Overrides{ApprovedAnyLocations: []string{"Foo.Bar", "doThing", "doThing.Baz"}}
+	require.Empty(t, auditAny(api, ov))
+}
+
 func TestAuditAny_SkipsChatIDShape(t *testing.T) {
 	api := &spec.API{
 		Types: []spec.TypeDecl{
@@ -82,7 +108,7 @@ func TestAuditAny_SkipsChatIDShape(t *testing.T) {
 			},
 		},
 	}
-	require.Empty(t, auditAny(api))
+	require.Empty(t, auditAny(api, &spec.Overrides{}))
 }
 
 func TestAuditAny_SkipsKnownUnion(t *testing.T) {
@@ -97,7 +123,7 @@ func TestAuditAny_SkipsKnownUnion(t *testing.T) {
 			},
 		},
 	}
-	require.Empty(t, auditAny(api))
+	require.Empty(t, auditAny(api, &spec.Overrides{}))
 }
 
 func TestAuditAny_SkipsReplyMarkupShape(t *testing.T) {
@@ -111,7 +137,7 @@ func TestAuditAny_SkipsReplyMarkupShape(t *testing.T) {
 			},
 		},
 	}
-	require.Empty(t, auditAny(api))
+	require.Empty(t, auditAny(api, &spec.Overrides{}))
 }
 
 func TestAuditAny_SkipsInputFileShape(t *testing.T) {
@@ -125,7 +151,7 @@ func TestAuditAny_SkipsInputFileShape(t *testing.T) {
 			},
 		},
 	}
-	require.Empty(t, auditAny(api))
+	require.Empty(t, auditAny(api, &spec.Overrides{}))
 }
 
 // ---- diffSignatures ------------------------------------------------------

cmd/genapi/emitter.go

@@ -420,7 +420,7 @@ func funcs(plan *enumPlan) template.FuncMap {
 			return goField(plan, parent, f)
 		},
 		"goFieldP": func(methodName string, f spec.Field) string {
-			return goFieldX(plan, "", title(methodName)+"Params", f)
+			return goFieldX(plan, methodEnumParent(methodName), title(methodName)+"Params", f)
 		},
 		"docComment":  docComment,
 		"isOptional":  func(f spec.Field) bool { return !f.Required },
@@ -432,7 +432,7 @@ func funcs(plan *enumPlan) template.FuncMap {
 			return multipartFieldEntry(plan, parent, f)
 		},
 		"multipartFieldEntryP": func(methodName string, f spec.Field) string {
-			return multipartFieldEntryX(plan, "", title(methodName)+"Params", f)
+			return multipartFieldEntryX(plan, methodEnumParent(methodName), title(methodName)+"Params", f)
 		},
 		"multipartFileEntry": multipartFileEntry,
 		"returnGoType":       returnGoType,
@@ -915,15 +915,15 @@ func buildUnionTypeSet(api *spec.API) map[string]bool {
 // used in generated test param literals. plan supplies typed-enum names
 // so a method-param sentinel for a ParseMode field becomes a typed
 // constant rather than a magic string.
-func makeSentinelValue(unionTypes map[string]bool, plan *enumPlan) func(spec.Field) string {
-	return func(f spec.Field) string {
-		return sentinelForField(f, unionTypes, plan)
+func makeSentinelValue(unionTypes map[string]bool, plan *enumPlan) func(string, spec.Field) string {
+	return func(methodName string, f spec.Field) string {
+		return sentinelForField(methodName, f, unionTypes, plan)
 	}
 }
 
-func sentinelForField(f spec.Field, unionTypes map[string]bool, plan *enumPlan) string {
-	if name := plan.FieldEnum("", f.Name); name != "" && len(f.EnumValues) > 0 {
-		return constName(name, f.EnumValues[0])
+func sentinelForField(methodName string, f spec.Field, unionTypes map[string]bool, plan *enumPlan) string {
+	if name := plan.FieldEnum(methodEnumParent(methodName), f.Name); name != "" && len(f.EnumValues) > 0 {
+		return plan.ConstFor(name, f.EnumValues[0])
 	}
 	tr := f.Type
 	switch tr.Kind {

cmd/genapi/enums.go

@@ -26,15 +26,21 @@ type enumPlan struct {
 }
 
 // enumKey identifies a single Field occurrence so the emitter can look
-// up the enum name later. Parent is "" for method params (the method
-// doesn't share a Go type with the field).
+// up the enum name later. Parent is the type name for struct fields and
+// methodEnumParent(name) for method params, so two methods sharing a
+// param name never alias each other's enum (or non-enum) fields.
 func enumKey(parent, fieldName string) string { return parent + "::" + fieldName }
 
+// methodEnumParent is the enum-plan key parent for a method's params.
+// The "method:" prefix keeps it disjoint from type names.
+func methodEnumParent(methodName string) string { return "method:" + methodName }
+
 // planEnums walks the IR, decides on enum names, deduplicates, and
 // returns an enumPlan. All scraper-marked enum fields are covered.
 func planEnums(api *spec.API) *enumPlan {
 	type ref struct {
-		parent    string
+		parent    string // naming parent ("" for method params)
+		keyParent string // byField key parent (methodEnumParent(...) for method params)
 		fieldName string
 		jsonName  string
 		values    []string
@@ -52,7 +58,7 @@ func planEnums(api *spec.API) *enumPlan {
 	}
 
 	var refs []ref
-	collect := func(parent string, fields []spec.Field) {
+	collect := func(parent, keyParent string, fields []spec.Field) {
 		for _, f := range fields {
 			if len(f.EnumValues) == 0 {
 				continue
@@ -62,6 +68,7 @@ func planEnums(api *spec.API) *enumPlan {
 			}
 			refs = append(refs, ref{
 				parent:    parent,
+				keyParent: keyParent,
 				fieldName: f.Name,
 				jsonName:  f.JSONName,
 				values:    f.EnumValues,
@@ -70,13 +77,15 @@ func planEnums(api *spec.API) *enumPlan {
 		}
 	}
 	for _, t := range api.Types {
-		collect(t.Name, t.Fields)
+		collect(t.Name, t.Name, t.Fields)
 	}
 	for _, m := range api.Methods {
-		// Method params have no shared Go parent type, so we pass "" as
-		// the parent. The default-name heuristic still produces the
-		// right answer for ParseMode-style enums.
-		collect("", m.Params)
+		// Method params have no shared Go parent type, so the naming
+		// parent is "" (the default-name heuristic still produces the
+		// right answer for ParseMode-style enums), but the byField key
+		// is method-scoped so a same-named non-enum param on another
+		// method can never pick up this enum.
+		collect("", methodEnumParent(m.Name), m.Params)
 	}
 
 	// candidate name per ref (before collision resolution)
@@ -196,7 +205,7 @@ func planEnums(api *spec.API) *enumPlan {
 	}
 	for i, r := range refs {
 		name := groups[r.valueKey].name
-		plan.byField[enumKey(r.parent, r.fieldName)] = name
+		plan.byField[enumKey(r.keyParent, r.fieldName)] = name
 		_ = i
 	}
 	for vk, g := range groups {
@@ -389,6 +398,18 @@ func (p *enumPlan) FieldEnum(parent, fieldName string) string {
 	return p.byField[enumKey(parent, fieldName)]
 }
 
+// ConstFor returns the collision-resolved constant identifier for value
+// within the named enum declaration. Falls back to the plain constName
+// when the declaration is unknown (unit tests with partial plans).
+func (p *enumPlan) ConstFor(enumName, value string) string {
+	if p != nil {
+		if d, ok := p.decls[enumName]; ok {
+			return d.ConstName(value)
+		}
+	}
+	return constName(enumName, value)
+}
+
 // defaultEnumName picks an initial Go enum name for a field. parse_mode
 // fields collapse to the canonical "ParseMode"; otherwise the name is
 // parent + PascalCase(jsonName).
@@ -406,6 +427,48 @@ func constName(enumName, value string) string {
 	return enumName + valuePascal(value)
 }
 
+// ConstName returns the constant identifier for value within this enum,
+// resolving case-collisions between values that Pascal-case to the same
+// identifier (e.g. RichBlockListItem.type values "a" and "A"). Colliding
+// values get a Lower/Upper prefix on the value part based on the case of
+// the value's first letter; any residual collision gets a numeric suffix.
+func (e enumDecl) ConstName(value string) string {
+	counts := map[string]int{}
+	for _, v := range e.Values {
+		counts[constName(e.Name, v)]++
+	}
+	plain := constName(e.Name, value)
+	if counts[plain] <= 1 {
+		return plain
+	}
+	cased := e.Name + casePrefix(value) + valuePascal(value)
+	// Residual collision (same value text repeated, or Lower/Upper still
+	// ambiguous): append the value's 1-based position for determinism.
+	casedCounts := map[string]int{}
+	pos := 0
+	for i, v := range e.Values {
+		if counts[constName(e.Name, v)] > 1 {
+			casedCounts[e.Name+casePrefix(v)+valuePascal(v)]++
+		}
+		if v == value {
+			pos = i + 1
+		}
+	}
+	if casedCounts[cased] > 1 {
+		return cased + itoa(pos)
+	}
+	return cased
+}
+
+// casePrefix distinguishes case-colliding enum values: "Lower" when the
+// value starts with a lowercase letter, "Upper" otherwise.
+func casePrefix(v string) string {
+	if v != "" && v[0] >= 'a' && v[0] <= 'z' {
+		return "Lower"
+	}
+	return "Upper"
+}
+
 func valuePascal(v string) string {
 	// "image/jpeg" → "ImageOfJpeg"
 	parts := strings.Split(v, "/")

cmd/genapi/enums.tmpl

@@ -8,6 +8,6 @@ package api
 type {{$e.Name}} string
 
 const (
-{{range $v := $e.Values}}	{{enumConstName $e.Name $v}} {{$e.Name}} = {{printf "%q" $v}}
+{{range $v := $e.Values}}	{{$e.ConstName $v}} {{$e.Name}} = {{printf "%q" $v}}
 {{end}})
 {{end}}

cmd/genapi/enums_collision_test.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/lukaszraczylo/go-telegram/internal/spec"
+	"github.com/stretchr/testify/require"
+)
+
+// Regression: Bot API 9.x RichBlockListItem.type enumerates "a"/"A"/"i"/"I"/"1",
+// which Pascal-case to the same identifier. ConstName must disambiguate.
+func TestEnumDecl_ConstName_CaseCollision(t *testing.T) {
+	d := enumDecl{Name: "RichBlockListItemType", Values: []string{"a", "A", "i", "I", "1"}}
+	got := map[string]bool{}
+	for _, v := range d.Values {
+		n := d.ConstName(v)
+		require.False(t, got[n], "duplicate const ident %q for value %q", n, v)
+		got[n] = true
+	}
+	require.Equal(t, "RichBlockListItemTypeLowerA", d.ConstName("a"))
+	require.Equal(t, "RichBlockListItemTypeUpperA", d.ConstName("A"))
+	// Non-colliding values keep the plain name.
+	require.Equal(t, "RichBlockListItemType1", d.ConstName("1"))
+}
+
+// Regression: answerChatJoinRequestQuery has an enum param named "result";
+// answerGuestQuery has a NON-enum param also named "result". The enum plan
+// must scope method params per method so the enum never leaks onto the
+// other method's field.
+func TestPlanEnums_MethodParamsScopedPerMethod(t *testing.T) {
+	api := &spec.API{
+		Methods: []spec.MethodDecl{
+			{
+				Name: "answerChatJoinRequestQuery",
+				Params: []spec.Field{{
+					Name: "Result", JSONName: "result", Required: true,
+					Type:       spec.TypeRef{Kind: spec.KindPrimitive, Name: "string"},
+					EnumValues: []string{"approve", "decline", "queue"},
+				}},
+			},
+			{
+				Name: "answerGuestQuery",
+				Params: []spec.Field{{
+					Name: "Result", JSONName: "result", Required: true,
+					Type: spec.TypeRef{Kind: spec.KindNamed, Name: "InlineQueryResult"},
+				}},
+			},
+		},
+	}
+	plan := planEnums(api)
+	require.Equal(t, "Result",
+		plan.FieldEnum(methodEnumParent("answerChatJoinRequestQuery"), "Result"))
+	require.Empty(t,
+		plan.FieldEnum(methodEnumParent("answerGuestQuery"), "Result"),
+		"non-enum param must not inherit another method's enum")
+}

cmd/genapi/extra_test.go

@@ -574,7 +574,7 @@ func TestSentinelForField(t *testing.T) {
 	}
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
-			got := sentinelForField(c.field, unionTypes, nil)
+			got := sentinelForField("testMethod", c.field, unionTypes, nil)
 			require.Contains(t, got, c.contains, "sentinelForField for %q", c.name)
 		})
 	}

cmd/genapi/tests.tmpl

@@ -48,7 +48,7 @@ func Test_{{$mName}}_Success(t *testing.T) {
 	{{- if .Params}}
 	params := &{{$mName}}Params{
 		{{- range .Params}}{{if .Required}}
-		{{.Name}}: {{sentinelValue .}},{{end}}
+		{{.Name}}: {{sentinelValue $m.Name .}},{{end}}
 		{{- end}}
 	}
 	_, err := {{$mName}}(context.Background(), bot, params)
@@ -67,7 +67,7 @@ func Test_{{$mName}}_APIError(t *testing.T) {
 	{{- if .Params}}
 	params := &{{$mName}}Params{
 		{{- range .Params}}{{if .Required}}
-		{{.Name}}: {{sentinelValue .}},{{end}}
+		{{.Name}}: {{sentinelValue $m.Name .}},{{end}}
 		{{- end}}
 	}
 	_, err := {{$mName}}(context.Background(), bot, params)
@@ -89,7 +89,7 @@ func Test_{{$mName}}_NetworkError(t *testing.T) {
 	{{- if .Params}}
 	params := &{{$mName}}Params{
 		{{- range .Params}}{{if .Required}}
-		{{.Name}}: {{sentinelValue .}},{{end}}
+		{{.Name}}: {{sentinelValue $m.Name .}},{{end}}
 		{{- end}}
 	}
 	_, err := {{$mName}}(context.Background(), bot, params)
@@ -109,7 +109,7 @@ func Test_{{$mName}}_ParseError(t *testing.T) {
 	{{- if .Params}}
 	params := &{{$mName}}Params{
 		{{- range .Params}}{{if .Required}}
-		{{.Name}}: {{sentinelValue .}},{{end}}
+		{{.Name}}: {{sentinelValue $m.Name .}},{{end}}
 		{{- end}}
 	}
 	_, err := {{$mName}}(context.Background(), bot, params)
@@ -132,7 +132,7 @@ func Test_{{$mName}}_ContextCanceled(t *testing.T) {
 	{{- if .Params}}
 	params := &{{$mName}}Params{
 		{{- range .Params}}{{if .Required}}
-		{{.Name}}: {{sentinelValue .}},{{end}}
+		{{.Name}}: {{sentinelValue $m.Name .}},{{end}}
 		{{- end}}
 	}
 	_, err := {{$mName}}(ctx, bot, params)
@@ -177,7 +177,7 @@ func Test_{{$mName}}_Forbidden(t *testing.T) {
 	{{- if .Params}}
 	params := &{{$mName}}Params{
 		{{- range .Params}}{{if .Required}}
-		{{.Name}}: {{sentinelValue .}},{{end}}
+		{{.Name}}: {{sentinelValue $m.Name .}},{{end}}
 		{{- end}}
 	}
 	_, err := {{$mName}}(context.Background(), bot, params)
@@ -203,7 +203,7 @@ func Test_{{$mName}}_ServerError(t *testing.T) {
 	{{- if .Params}}
 	params := &{{$mName}}Params{
 		{{- range .Params}}{{if .Required}}
-		{{.Name}}: {{sentinelValue .}},{{end}}
+		{{.Name}}: {{sentinelValue $m.Name .}},{{end}}
 		{{- end}}
 	}
 	_, err := {{$mName}}(context.Background(), bot, params)

cmd/scrape/method.go

@@ -42,7 +42,7 @@ func extractReturn(desc string) spec.TypeRef {
 			return spec.TypeRef{Kind: spec.KindArray, ElemType: &elem}
 		}},
 		// "an array of X of the sent messages is returned" (ForwardMessages/CopyMessages shape).
-		{regexp.MustCompile(`(?:[Oo]n success[,.]?\s+)?an? array of ([A-Z][A-Za-z0-9]+)(?:\s+of [^.]+?)?\s+(?:objects\s+)?(?:is|are) returned`), func(m []string) spec.TypeRef {
+		{regexp.MustCompile(`(?:[Oo]n success[,.]?\s+)?an? [Aa]rray of ([A-Z][A-Za-z0-9]+)(?:\s+of [^.]+?)?\s+(?:objects\s+)?(?:is|are) returned`), func(m []string) spec.TypeRef {
 			elem := primitiveOrNamed(m[1])
 			return spec.TypeRef{Kind: spec.KindArray, ElemType: &elem}
 		}},

cmd/scrape/method_test.go

@@ -29,6 +29,8 @@ func TestExtractReturn(t *testing.T) {
 		{"On success, an array of Message objects that were sent is returned.", spec.TypeRef{Kind: spec.KindArray, ElemType: &spec.TypeRef{Kind: spec.KindNamed, Name: "Message"}}},
 		// ForwardMessages/CopyMessages shape: "an array of X of the sent messages is returned".
 		{"On success, an array of MessageId of the sent messages is returned.", spec.TypeRef{Kind: spec.KindArray, ElemType: &spec.TypeRef{Kind: spec.KindNamed, Name: "MessageId"}}},
+		// Bot API 10.1 recapitalised the same sentence to "an Array of X".
+		{"On success, an Array of MessageId of the sent messages is returned.", spec.TypeRef{Kind: spec.KindArray, ElemType: &spec.TypeRef{Kind: spec.KindNamed, Name: "MessageId"}}},
 		// "Returns X on success" (no article) — OwnedGifts, StarAmount, Story, MenuButton, etc.
 		{"Returns the gifts received and owned by a managed business account. Returns OwnedGifts on success.", spec.TypeRef{Kind: spec.KindNamed, Name: "OwnedGifts"}},
 		{"Returns StarAmount on success.", spec.TypeRef{Kind: spec.KindNamed, Name: "StarAmount"}},

docs/reference/client.md

@@ -87,6 +87,16 @@ var (
 )
 ```
 
+<a name="Version"></a>Version is a fallback version string used only when Go's build info is unavailable \(replace directives, detached \`go run\`\) or has been overridden via linker flags. The authoritative version forwarded to telemetry is resolved at runtime by \[telemetry.SendForModule\] from the build info of whatever binary linked this library, so this constant does NOT need to be bumped on every release. Exposed as a var \(not const\) for ldflag override:
+
+```
+go build -ldflags="-X github.com/lukaszraczylo/go-telegram/client.Version=1.2.3"
+```
+
+```go
+var Version = "0.0.0-fallback"
+```
+
 <a name="Call"></a>
 ## func [Call](<https://github.com/lukaszraczylo/go-telegram/blob/main/client/call.go#L68>)
 

examples/echo/handlers.go

@@ -26,7 +26,7 @@ func handleEcho(c *dispatch.Context, m *api.Message) error {
 	_, err := api.SendMessage(c.Ctx, c.Bot, &api.SendMessageParams{
 		ChatID:          api.ChatIDFromInt(m.Chat.ID),
 		Text:            m.Text,
-		ReplyParameters: &api.ReplyParameters{MessageID: m.MessageID},
+		ReplyParameters: &api.ReplyParameters{MessageID: &m.MessageID},
 	})
 	return err
 }

go.mod

@@ -4,8 +4,10 @@ go 1.25.0
 
 require (
 	github.com/goccy/go-json v0.10.6
+	github.com/lukaszraczylo/oss-telemetry v0.2.3
 	github.com/stretchr/testify v1.9.0
-	golang.org/x/net v0.54.0
+	github.com/valyala/fasthttp v1.71.0
+	golang.org/x/net v0.56.0
 )
 
 require (
@@ -15,6 +17,5 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
-	github.com/valyala/fasthttp v1.71.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -6,6 +6,10 @@ github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
 github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao=
 github.com/klauspost/compress v1.18.6/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/lukaszraczylo/oss-telemetry v0.2.1 h1:6ULyfzXplpdmIY/i01OPM1jeod9+L1RAhI0jtbVnJI0=
+github.com/lukaszraczylo/oss-telemetry v0.2.1/go.mod h1:+Cn78qZo8rc3T9eZt0v3oICYRdd75wORtSidc8lNjDQ=
+github.com/lukaszraczylo/oss-telemetry v0.2.3 h1:xoDtBqeZGmXj7IteiE1M5WMuzeoqag58qEleI0Cf2Ms=
+github.com/lukaszraczylo/oss-telemetry v0.2.3/go.mod h1:+Cn78qZo8rc3T9eZt0v3oICYRdd75wORtSidc8lNjDQ=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
@@ -16,8 +20,12 @@ github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6Kllzaw
 github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
 github.com/valyala/fasthttp v1.71.0 h1:tepR7H+Guh9VUqxxcPggYi8R3lGUu2Rsdh+z7/FCY3k=
 github.com/valyala/fasthttp v1.71.0/go.mod h1:z1sDUvOShhXq/C9mwH/fSm1Vb71tUJwmQdgkBrBNwnA=
-golang.org/x/net v0.54.0 h1:2zJIZAxAHV/OHCDTCOHAYehQzLfSXuf/5SoL/Dv6w/w=
-golang.org/x/net v0.54.0/go.mod h1:Sj4oj8jK6XmHpBZU/zWHw3BV3abl4Kvi+Ut7cQcY+cQ=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

internal/spec/overrides.go

@@ -22,6 +22,12 @@ type Overrides struct {
 	// ApprovedBoolMethods lists methods whose returns are genuinely bool.
 	// The audit tool ignores these.
 	ApprovedBoolMethods []string `json:"approved_bool_methods,omitempty"`
+
+	// ApprovedAnyLocations lists IR locations whose union renders as `any` by
+	// design, keyed "<TypeName>.<FieldName>" for struct fields,
+	// "<methodName>.<ParamName>" for params and "<methodName>" for returns.
+	// The audit tool ignores these.
+	ApprovedAnyLocations []string `json:"approved_any_locations,omitempty"`
 }
 
 // LoadOverrides reads and parses overrides.json. Returns an empty Overrides
@@ -73,3 +79,17 @@ func (o *Overrides) IsBoolApproved(methodName string) bool {
 	}
 	return false
 }
+
+// IsAnyApproved reports whether location is on the approved `any` list.
+// See ApprovedAnyLocations for the key format.
+func (o *Overrides) IsAnyApproved(location string) bool {
+	if o == nil {
+		return false
+	}
+	for _, n := range o.ApprovedAnyLocations {
+		if n == location {
+			return true
+		}
+	}
+	return false
+}

internal/spec/overrides.json

@@ -1,6 +1,9 @@
 {
   "method_returns": {},
   "field_types": {},
+  "approved_any_locations": [
+    "InputRichMessageMedia.Media"
+  ],
   "approved_bool_methods": [
     "setWebhook",
     "deleteWebhook",

testdata/html/latest.html

@@ -1 +1 @@
-snapshot_2026-05-08.html
+snapshot_2026-07-21.html