feat(storage): add storage.Open/Close and persist session in all examples

Add a one-call storage.Open(path) that opens (creating if needed) a
bbolt-backed Storage and owns the database, with a matching Close. This makes
enabling persistence a two-liner instead of opening bbolt by hand.

Every example (echo, buttons, inline, media, rich, background, advanced) now
opens a per-example <name>-session.bbolt and passes it as Options.Storage, so
bots resume across restarts without re-authorizing. Update the guide, README
and CHANGELOG, and gitignore *.bbolt.

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

Author: ernado

.gitignore

@@ -20,6 +20,9 @@ gen
 # Bot db files
 state/*.bbolt
 
+# Session/peers/state stores written by the examples.
+*.bbolt
+
 # Stray binaries from `go build ./examples/<name>` run at the repo root.
 /echo
 /buttons

CHANGELOG.md

@@ -17,6 +17,10 @@ messages follow [Conventional Commits](https://www.conventionalcommits.org/).
 
 ### Added
 
+- **`storage.Open`/`Close`** — a one-call opener that creates (or reuses) a
+  bbolt-backed `Storage` and owns the database, so persisting a session is
+  `storage.Open("bot.bbolt")` plus a deferred `Close`. Every example now
+  persists its session by default.
 - **Rich messages** (Bot API 10.1) — `SendRichMessage`/`SendRichHTML`/
   `SendRichMarkdown` send structured page-block content built with
   `github.com/gotd/td/telegram/message/rich`. The `examples/rich` bot showcases

README.md

@@ -79,8 +79,10 @@ errors, pooling) and [`examples/`](./examples) for runnable bots
 (`echo`, `buttons`, `inline`, `media`, `rich`, `background`, `advanced`).
 
 `Options.Storage` is optional — leave it nil to keep session, peers and update
-state in memory (nothing survives a restart). `storage.BBoltStorage` persists
-all of it to a single bbolt file.
+state in memory (nothing survives a restart). `storage.Open("bot.bbolt")`
+persists all of it to a single bbolt file; close it on shutdown. Every example
+under [`examples/`](./examples) persists its session this way by default, so
+they reconnect without re-authorizing.
 
 ## Package layout
 

docs/guide.md

@@ -410,13 +410,23 @@ botapi.Options{
 ## Persistence
 
 By default everything is in memory (nothing survives a restart). Provide a
-`Storage` to persist the session, peer access hashes and update state:
+`Storage` to persist the session, peer access hashes and update state.
+`storage.Open` is the one-call form — it opens (creating it if needed) a
+bbolt file and owns it, so close it on shutdown:
 
 ```go
-db, _ := bbolt.Open("bot.bbolt", 0o666, nil)
-opts := botapi.Options{AppID: appID, AppHash: appHash, Storage: storage.NewBBoltStorage(db)}
+store, err := storage.Open("bot.bbolt")
+if err != nil {
+	return err
+}
+defer store.Close()
+opts := botapi.Options{AppID: appID, AppHash: appHash, Storage: store}
 ```
 
+To share a `*bbolt.DB` you already manage, wrap it with
+`storage.NewBBoltStorage(db)` instead and close the db yourself. Every bot under
+`examples/` persists its session this way by default.
+
 ## Running many bots
 
 `pool.Pool` lazily starts and multiplexes bots by token over one process — the

examples/advanced/main.go

@@ -26,6 +26,7 @@ import (
 	"github.com/gotd/td/telegram/message/rich"
 
 	"github.com/gotd/botapi"
+	"github.com/gotd/botapi/storage"
 )
 
 const samplePhotoURL = "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
@@ -39,10 +40,18 @@ func main() {
 		log.Fatal("APP_ID must be a number (see https://my.telegram.org)", zap.Error(err))
 	}
 
+	// Persist session, peers and update state so the bot resumes across restarts.
+	store, err := storage.Open("advanced-session.bbolt")
+	if err != nil {
+		log.Fatal("Open storage", zap.Error(err))
+	}
+	defer func() { _ = store.Close() }()
+
 	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
 		AppID:     appID,
 		AppHash:   os.Getenv("APP_HASH"),
 		Logger:    logzap.New(log),
+		Storage:   store,
 		FloodWait: true, // transparently wait out flood limits
 	})
 	if err != nil {

examples/background/main.go

@@ -35,6 +35,7 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/gotd/botapi"
+	"github.com/gotd/botapi/storage"
 )
 
 func main() {
@@ -46,10 +47,18 @@ func main() {
 		log.Fatal("APP_ID must be a number (see https://my.telegram.org)", zap.Error(err))
 	}
 
+	// Persist session, peers and update state so the bot resumes across restarts.
+	sess, err := storage.Open("background-session.bbolt")
+	if err != nil {
+		log.Fatal("Open storage", zap.Error(err))
+	}
+	defer func() { _ = sess.Close() }()
+
 	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
 		AppID:   appID,
 		AppHash: os.Getenv("APP_HASH"),
 		Logger:  logzap.New(log),
+		Storage: sess,
 	})
 	if err != nil {
 		log.Fatal("Create bot", zap.Error(err))

examples/buttons/main.go

@@ -19,6 +19,7 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/gotd/botapi"
+	"github.com/gotd/botapi/storage"
 )
 
 func menu() *botapi.InlineKeyboardMarkup {
@@ -44,10 +45,18 @@ func main() {
 		log.Fatal("APP_ID must be a number (see https://my.telegram.org)", zap.Error(err))
 	}
 
+	// Persist session, peers and update state so the bot resumes across restarts.
+	store, err := storage.Open("buttons-session.bbolt")
+	if err != nil {
+		log.Fatal("Open storage", zap.Error(err))
+	}
+	defer func() { _ = store.Close() }()
+
 	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
 		AppID:   appID,
 		AppHash: os.Getenv("APP_HASH"),
 		Logger:  logzap.New(log),
+		Storage: store,
 	})
 	if err != nil {
 		log.Fatal("Create bot", zap.Error(err))

examples/echo/main.go

@@ -18,6 +18,7 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/gotd/botapi"
+	"github.com/gotd/botapi/storage"
 )
 
 func main() {
@@ -29,10 +30,18 @@ func main() {
 		log.Fatal("APP_ID must be a number (see https://my.telegram.org)", zap.Error(err))
 	}
 
+	// Persist session, peers and update state so the bot resumes across restarts.
+	store, err := storage.Open("echo-session.bbolt")
+	if err != nil {
+		log.Fatal("Open storage", zap.Error(err))
+	}
+	defer func() { _ = store.Close() }()
+
 	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
 		AppID:   appID,
 		AppHash: os.Getenv("APP_HASH"),
 		Logger:  logzap.New(log),
+		Storage: store,
 	})
 	if err != nil {
 		log.Fatal("Create bot", zap.Error(err))

examples/inline/main.go

@@ -19,6 +19,7 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/gotd/botapi"
+	"github.com/gotd/botapi/storage"
 )
 
 func main() {
@@ -30,10 +31,18 @@ func main() {
 		log.Fatal("APP_ID must be a number (see https://my.telegram.org)", zap.Error(err))
 	}
 
+	// Persist session, peers and update state so the bot resumes across restarts.
+	store, err := storage.Open("inline-session.bbolt")
+	if err != nil {
+		log.Fatal("Open storage", zap.Error(err))
+	}
+	defer func() { _ = store.Close() }()
+
 	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
 		AppID:   appID,
 		AppHash: os.Getenv("APP_HASH"),
 		Logger:  logzap.New(log),
+		Storage: store,
 	})
 	if err != nil {
 		log.Fatal("Create bot", zap.Error(err))

examples/media/main.go

@@ -24,6 +24,7 @@ import (
 	"go.uber.org/zap"
 
 	"github.com/gotd/botapi"
+	"github.com/gotd/botapi/storage"
 )
 
 // A small public domain image to send for /photo.
@@ -38,10 +39,18 @@ func main() {
 		log.Fatal("APP_ID must be a number (see https://my.telegram.org)", zap.Error(err))
 	}
 
+	// Persist session, peers and update state so the bot resumes across restarts.
+	store, err := storage.Open("media-session.bbolt")
+	if err != nil {
+		log.Fatal("Open storage", zap.Error(err))
+	}
+	defer func() { _ = store.Close() }()
+
 	bot, err := botapi.New(os.Getenv("BOT_TOKEN"), botapi.Options{
 		AppID:   appID,
 		AppHash: os.Getenv("APP_HASH"),
 		Logger:  logzap.New(log),
+		Storage: store,
 	})
 	if err != nil {
 		log.Fatal("Create bot", zap.Error(err))