feat(peer): serializable PeerRef for restart-safe sends

Addressing a chat needs its access hash. Add PeerRef — a JSON-
serializable {kind,id,access_hash} captured with Bot.PeerRef — and
Peer(ref), a ChatID that builds the input peer directly from the
reference (no stored peer data, no re-resolution). This is what makes a
serialized background/scheduled send to a chat work across restarts. The
ref is send-only; chat management still takes a resolved ID/Username.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

CHANGELOG.md

@@ -15,6 +15,10 @@ messages follow [Conventional Commits](https://www.conventionalcommits.org/).
 - **Background sends** — `Bot.Background()` / `Context.Background()` expose a
   run-lifetime context for proactive sends to any chat from timers, queues or
   goroutines, instead of the per-update handler context. Plus `Bot.Logger()`.
+- **Serializable peer references** — `Bot.PeerRef` captures a chat's id and
+  access hash into a JSON-serializable `PeerRef`; `Peer(ref)` addresses it
+  directly (no stored peer data, no re-resolution), so background/scheduled
+  sends survive a restart.
 
 ## [0.1.0] - 2026-06-14
 

docs/guide.md

@@ -224,6 +224,28 @@ botapi.ID(chatID), text)` from wherever you like once the bot is running.
 `Background` returns an already-canceled context before `Run` connects (and
 after it stops), so background sends fail fast instead of blocking.
 
+#### Across restarts
+
+Addressing a chat needs its MTProto **access hash**. The bot persists access
+hashes for peers it has seen (with a `Storage`), but to address a chat after a
+restart without relying on that, capture a **`PeerRef`** — a self-contained,
+JSON-serializable reference (id + access hash) — and reuse it with `Peer`:
+
+```go
+ref, _ := bot.PeerRef(ctx, botapi.ID(chatID)) // resolve once, capture the hash
+data, _ := json.Marshal(ref)                  // persist it (DB, file, …)
+
+// … bot restarts …
+var ref botapi.PeerRef
+_ = json.Unmarshal(data, &ref)
+bot.SendMessage(bot.Background(), botapi.Peer(ref), "still works") // no re-resolution
+```
+
+`Peer(ref)` is addressed straight from the reference, so a serialized
+`{chat, text}` is all you need to deliver a message after a restart — no task
+queue. (`PeerRef` is for sending; chat-management methods still take a resolved
+`ID`/`Username`.)
+
 ## Predicates
 
 Every `On*` method accepts trailing `Predicate`s (`func(*Update) bool`); the

peerref.go

@@ -0,0 +1,103 @@
+package botapi
+
+import (
+	"context"
+	"strconv"
+
+	"github.com/gotd/td/constant"
+	"github.com/gotd/td/tg"
+)
+
+// Peer kinds for a PeerRef.
+const (
+	peerKindUser    = "user"
+	peerKindChat    = "chat"
+	peerKindChannel = "channel"
+)
+
+// PeerRef is a serializable reference to a chat that carries its access hash.
+//
+// Sending to a chat requires its MTProto access hash. The bot harvests and
+// persists access hashes for peers it has seen, but addressing a chat after a
+// restart otherwise depends on that stored peer data. A PeerRef captures the
+// id and access hash in a self-contained, JSON-serializable form: persist it
+// yourself (in a DB, a file, …) and, after a restart, send to it with Peer —
+// directly from the reference, no re-resolution.
+//
+//	ref, _ := bot.PeerRef(ctx, botapi.ID(chatID)) // resolve once, capture the hash
+//	data, _ := json.Marshal(ref)                  // persist it
+//	// … restart …
+//	var ref botapi.PeerRef
+//	_ = json.Unmarshal(data, &ref)
+//	bot.SendMessage(ctx, botapi.Peer(ref), "still works")
+type PeerRef struct {
+	Kind       string `json:"kind"` // "user", "chat" or "channel"
+	ID         int64  `json:"id"`
+	AccessHash int64  `json:"access_hash,omitempty"`
+}
+
+// PeerRef resolves a chat to a serializable reference including its access hash.
+func (b *Bot) PeerRef(ctx context.Context, chat ChatID) (PeerRef, error) {
+	peer, err := b.resolveInputPeer(ctx, chat)
+	if err != nil {
+		return PeerRef{}, err
+	}
+	return peerRefFromInputPeer(peer)
+}
+
+// peerRefFromInputPeer extracts a PeerRef from a resolved input peer.
+func peerRefFromInputPeer(p tg.InputPeerClass) (PeerRef, error) {
+	switch v := p.(type) {
+	case *tg.InputPeerUser:
+		return PeerRef{Kind: peerKindUser, ID: v.UserID, AccessHash: v.AccessHash}, nil
+	case *tg.InputPeerChannel:
+		return PeerRef{Kind: peerKindChannel, ID: v.ChannelID, AccessHash: v.AccessHash}, nil
+	case *tg.InputPeerChat:
+		return PeerRef{Kind: peerKindChat, ID: v.ChatID}, nil
+	default:
+		return PeerRef{}, &Error{Code: 400, Description: "Bad Request: chat can't be referenced"}
+	}
+}
+
+// inputPeer reconstructs the MTProto input peer from the reference.
+func (r PeerRef) inputPeer() (tg.InputPeerClass, error) {
+	switch r.Kind {
+	case peerKindUser:
+		return &tg.InputPeerUser{UserID: r.ID, AccessHash: r.AccessHash}, nil
+	case peerKindChannel:
+		return &tg.InputPeerChannel{ChannelID: r.ID, AccessHash: r.AccessHash}, nil
+	case peerKindChat:
+		return &tg.InputPeerChat{ChatID: r.ID}, nil
+	default:
+		return nil, &Error{Code: 400, Description: "Bad Request: invalid peer reference"}
+	}
+}
+
+// tdlibID returns the TDLib (Bot API) chat id for the reference.
+func (r PeerRef) tdlibID() int64 {
+	var id constant.TDLibPeerID
+	switch r.Kind {
+	case peerKindUser:
+		id.User(r.ID)
+	case peerKindChat:
+		id.Chat(r.ID)
+	case peerKindChannel:
+		id.Channel(r.ID)
+	}
+	return int64(id)
+}
+
+// chatIDRef adapts a PeerRef to the ChatID union.
+type chatIDRef struct{ ref PeerRef }
+
+func (chatIDRef) isChatID() {}
+
+// MarshalJSON encodes the reference as its bare Bot API chat id.
+func (c chatIDRef) MarshalJSON() ([]byte, error) {
+	return []byte(strconv.FormatInt(c.ref.tdlibID(), 10)), nil
+}
+
+// Peer targets a chat by a serializable reference captured with Bot.PeerRef.
+// The send is addressed directly from the reference's access hash — no stored
+// peer data and no re-resolution — so it works across restarts.
+func Peer(ref PeerRef) ChatID { return chatIDRef{ref} }

peerref_test.go

@@ -0,0 +1,80 @@
+package botapi
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestPeerRefInputPeerRoundTrip(t *testing.T) {
+	cases := []struct {
+		ref  PeerRef
+		want tg.InputPeerClass
+	}{
+		{PeerRef{Kind: peerKindUser, ID: 7, AccessHash: 11}, &tg.InputPeerUser{UserID: 7, AccessHash: 11}},
+		{PeerRef{Kind: peerKindChannel, ID: 9, AccessHash: 13}, &tg.InputPeerChannel{ChannelID: 9, AccessHash: 13}},
+		{PeerRef{Kind: peerKindChat, ID: 5}, &tg.InputPeerChat{ChatID: 5}},
+	}
+	for _, c := range cases {
+		got, err := c.ref.inputPeer()
+		if err != nil {
+			t.Fatal(err)
+		}
+		if got.String() != c.want.String() {
+			t.Fatalf("inputPeer: got %#v, want %#v", got, c.want)
+		}
+		// Extracting a ref back from the input peer yields the original.
+		back, err := peerRefFromInputPeer(got)
+		if err != nil || back != c.ref {
+			t.Fatalf("round-trip: got %#v (%v), want %#v", back, err, c.ref)
+		}
+	}
+}
+
+func TestPeerSendsDirectlyFromRef(t *testing.T) {
+	// resolveInputPeer must build the input peer straight from the ref, with no
+	// peer manager or network — this is what survives a restart.
+	b := &Bot{}
+	ref := PeerRef{Kind: peerKindChannel, ID: 100, AccessHash: 200}
+	got, err := b.resolveInputPeer(context.Background(), Peer(ref))
+	if err != nil {
+		t.Fatal(err)
+	}
+	ch, ok := got.(*tg.InputPeerChannel)
+	if !ok || ch.ChannelID != 100 || ch.AccessHash != 200 {
+		t.Fatalf("input peer: %#v", got)
+	}
+}
+
+func TestPeerRefJSONRoundTrip(t *testing.T) {
+	ref := PeerRef{Kind: peerKindUser, ID: 42, AccessHash: 99}
+	data, err := json.Marshal(ref)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var back PeerRef
+	if err := json.Unmarshal(data, &back); err != nil {
+		t.Fatal(err)
+	}
+	if back != ref {
+		t.Fatalf("json round-trip: got %#v, want %#v", back, ref)
+	}
+}
+
+func TestPeerChatIDMarshalsToTDLibID(t *testing.T) {
+	// Peer(ref) is a ChatID; its JSON form is the bare Bot API chat id.
+	data, err := json.Marshal(Peer(PeerRef{Kind: peerKindUser, ID: 42}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(data) != "42" {
+		t.Fatalf("user chat id: %s", data)
+	}
+	// Channels use the -100… supergroup id space.
+	data, _ = json.Marshal(Peer(PeerRef{Kind: peerKindChannel, ID: 123}))
+	if string(data) != "-1000000000123" {
+		t.Fatalf("channel chat id: %s", data)
+	}
+}

resolve.go

@@ -32,13 +32,22 @@ func (b *Bot) resolvePeer(ctx context.Context, chat ChatID) (peers.Peer, error)
 			return nil, asAPIError(err)
 		}
 		return p, nil
+	case chatIDRef:
+		// A PeerRef is addressed directly for sending (resolveInputPeer); it
+		// cannot back the peers.Peer that chat-management needs.
+		return nil, &Error{Code: 400, Description: "Bad Request: peer reference is only usable for sending"}
 	default:
 		return nil, &Error{Code: 400, Description: "Bad Request: invalid chat_id"}
 	}
 }
 
 // resolveInputPeer resolves a ChatID to the tg.InputPeerClass the sender needs.
 func (b *Bot) resolveInputPeer(ctx context.Context, chat ChatID) (tg.InputPeerClass, error) {
+	// A PeerRef carries its own access hash, so it is addressed directly without
+	// consulting stored peer data — this is what makes it survive a restart.
+	if ref, ok := chat.(chatIDRef); ok {
+		return ref.ref.inputPeer()
+	}
 	p, err := b.resolvePeer(ctx, chat)
 	if err != nil {
 		return nil, err