feat(payments): shipping/pre-checkout queries and answers

Add payment query types (ShippingQuery, PreCheckoutQuery, OrderInfo,
ShippingAddress, ShippingOption, LabeledPrice), wire the incoming
UpdateBotShippingQuery/UpdateBotPrecheckoutQuery into the router with
Update.ShippingQuery/PreCheckoutQuery and On{Shipping,PreCheckout}Query
handlers, and implement AnswerShippingQuery/AnswerPreCheckoutQuery over
messages.setBot{Shipping,Precheckout}Results.

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

Author: ernado

conformance_test.go

@@ -21,10 +21,8 @@ var coveredByOtherMeans = map[string]string{
 // implemented. Each is an acknowledged gap tracked in docs/roadmap.md; the
 // conformance test allows them so it can still catch *unacknowledged* drift.
 var deferredMethods = map[string]string{
-	"answerPreCheckoutQuery": "payments — deferred until payment updates land",
-	"answerShippingQuery":    "payments — deferred until payment updates land",
-	"sendInvoice":            "payments — deferred",
-	"setPassportDataErrors":  "Telegram Passport — deferred",
+	"sendInvoice":           "payments — deferred",
+	"setPassportDataErrors": "Telegram Passport — deferred",
 }
 
 // notApplicableMethods lists published methods that do not apply to the

on.go

@@ -35,6 +35,14 @@ func (b *Bot) installHandlers() {
 		b.route(ctx, &Update{InlineQuery: inlineQueryFromTg(e, u)})
 		return nil
 	})
+	b.disp.OnBotShippingQuery(func(ctx context.Context, e tg.Entities, u *tg.UpdateBotShippingQuery) error {
+		b.route(ctx, &Update{ShippingQuery: shippingQueryFromTg(e, u)})
+		return nil
+	})
+	b.disp.OnBotPrecheckoutQuery(func(ctx context.Context, e tg.Entities, u *tg.UpdateBotPrecheckoutQuery) error {
+		b.route(ctx, &Update{PreCheckoutQuery: preCheckoutQueryFromTg(e, u)})
+		return nil
+	})
 }
 
 // dispatchMessage converts a message and routes it as the appropriate update
@@ -73,11 +81,13 @@ func (b *Bot) dispatchMessage(ctx context.Context, msg tg.MessageClass, edited b
 
 // Kind predicates select an update by which field it carries. They are shared
 // by Bot.On* and Group.On*.
-func hasMessage(u *Update) bool       { return u.Message != nil }
-func hasEditedMessage(u *Update) bool { return u.EditedMessage != nil }
-func hasChannelPost(u *Update) bool   { return u.ChannelPost != nil }
-func hasCallbackQuery(u *Update) bool { return u.CallbackQuery != nil }
-func hasInlineQuery(u *Update) bool   { return u.InlineQuery != nil }
+func hasMessage(u *Update) bool          { return u.Message != nil }
+func hasEditedMessage(u *Update) bool    { return u.EditedMessage != nil }
+func hasChannelPost(u *Update) bool      { return u.ChannelPost != nil }
+func hasCallbackQuery(u *Update) bool    { return u.CallbackQuery != nil }
+func hasInlineQuery(u *Update) bool      { return u.InlineQuery != nil }
+func hasShippingQuery(u *Update) bool    { return u.ShippingQuery != nil }
+func hasPreCheckoutQuery(u *Update) bool { return u.PreCheckoutQuery != nil }
 
 // OnMessage registers a handler for new messages matching the predicates.
 func (b *Bot) OnMessage(h Handler, predicates ...Predicate) {
@@ -104,6 +114,16 @@ func (b *Bot) OnInlineQuery(h Handler, predicates ...Predicate) {
 	b.on(h, prepend(hasInlineQuery, predicates)...)
 }
 
+// OnShippingQuery registers a handler for shipping queries (flexible invoices).
+func (b *Bot) OnShippingQuery(h Handler, predicates ...Predicate) {
+	b.on(h, prepend(hasShippingQuery, predicates)...)
+}
+
+// OnPreCheckoutQuery registers a handler for pre-checkout queries.
+func (b *Bot) OnPreCheckoutQuery(h Handler, predicates ...Predicate) {
+	b.on(h, prepend(hasPreCheckoutQuery, predicates)...)
+}
+
 // prepend returns p followed by rest, without mutating rest.
 func prepend(p Predicate, rest []Predicate) []Predicate {
 	out := make([]Predicate, 0, len(rest)+1)

payments.go

@@ -0,0 +1,107 @@
+package botapi
+
+import (
+	"context"
+	"strconv"
+
+	"github.com/gotd/td/tg"
+)
+
+// AnswerShippingQuery replies to a shipping query. When ok is true, provide the
+// available shipping options; otherwise pass an error message via
+// WithShippingError describing why the order can't be shipped.
+func (b *Bot) AnswerShippingQuery(ctx context.Context, shippingQueryID string, ok bool, opts ...ShippingAnswerOption) error {
+	var cfg shippingAnswerConfig
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	queryID, err := strconv.ParseInt(shippingQueryID, 10, 64)
+	if err != nil {
+		return &Error{Code: 400, Description: "Bad Request: invalid shipping query id"}
+	}
+
+	req := &tg.MessagesSetBotShippingResultsRequest{QueryID: queryID}
+	if ok {
+		req.ShippingOptions = shippingOptionsToTg(cfg.options)
+	} else {
+		req.Error = cfg.errorMessage
+	}
+
+	if _, err := b.raw.MessagesSetBotShippingResults(ctx, req); err != nil {
+		return asAPIError(err)
+	}
+	return nil
+}
+
+// ShippingAnswerOption configures an AnswerShippingQuery call.
+type ShippingAnswerOption func(*shippingAnswerConfig)
+
+type shippingAnswerConfig struct {
+	options      []ShippingOption
+	errorMessage string
+}
+
+// WithShippingOptions sets the available shipping options (required when ok).
+func WithShippingOptions(options ...ShippingOption) ShippingAnswerOption {
+	return func(c *shippingAnswerConfig) { c.options = options }
+}
+
+// WithShippingError sets the human-readable reason shipping is impossible (used
+// when ok is false).
+func WithShippingError(message string) ShippingAnswerOption {
+	return func(c *shippingAnswerConfig) { c.errorMessage = message }
+}
+
+// AnswerPreCheckoutQuery replies to a pre-checkout query. When ok is false,
+// provide a human-readable reason via WithPreCheckoutError.
+func (b *Bot) AnswerPreCheckoutQuery(ctx context.Context, preCheckoutQueryID string, ok bool, opts ...PreCheckoutAnswerOption) error {
+	var cfg preCheckoutAnswerConfig
+	for _, o := range opts {
+		o(&cfg)
+	}
+
+	queryID, err := strconv.ParseInt(preCheckoutQueryID, 10, 64)
+	if err != nil {
+		return &Error{Code: 400, Description: "Bad Request: invalid pre-checkout query id"}
+	}
+
+	req := &tg.MessagesSetBotPrecheckoutResultsRequest{
+		Success: ok,
+		QueryID: queryID,
+	}
+	if !ok {
+		req.Error = cfg.errorMessage
+	}
+
+	if _, err := b.raw.MessagesSetBotPrecheckoutResults(ctx, req); err != nil {
+		return asAPIError(err)
+	}
+	return nil
+}
+
+// PreCheckoutAnswerOption configures an AnswerPreCheckoutQuery call.
+type PreCheckoutAnswerOption func(*preCheckoutAnswerConfig)
+
+type preCheckoutAnswerConfig struct {
+	errorMessage string
+}
+
+// WithPreCheckoutError sets the reason the checkout can't proceed (used when ok
+// is false).
+func WithPreCheckoutError(message string) PreCheckoutAnswerOption {
+	return func(c *preCheckoutAnswerConfig) { c.errorMessage = message }
+}
+
+// shippingOptionsToTg converts Bot API shipping options to MTProto.
+func shippingOptionsToTg(options []ShippingOption) []tg.ShippingOption {
+	out := make([]tg.ShippingOption, 0, len(options))
+	for _, o := range options {
+		prices := make([]tg.LabeledPrice, 0, len(o.Prices))
+		for _, p := range o.Prices {
+			prices = append(prices, tg.LabeledPrice{Label: p.Label, Amount: int64(p.Amount)})
+		}
+		out = append(out, tg.ShippingOption{ID: o.ID, Title: o.Title, Prices: prices})
+	}
+	return out
+}

payments_test.go

@@ -0,0 +1,62 @@
+package botapi
+
+import (
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestShippingQueryFromTg(t *testing.T) {
+	e := tg.Entities{Users: map[int64]*tg.User{7: {ID: 7, FirstName: "Ann"}}}
+	u := &tg.UpdateBotShippingQuery{
+		QueryID: 100,
+		UserID:  7,
+		Payload: []byte("order-1"),
+		ShippingAddress: tg.PostAddress{
+			StreetLine1: "1 Main St",
+			City:        "Town",
+			CountryISO2: "US",
+			PostCode:    "12345",
+		},
+	}
+	q := shippingQueryFromTg(e, u)
+	if q.ID != "100" || q.From.FirstName != "Ann" || q.InvoicePayload != "order-1" {
+		t.Fatalf("query: %#v", q)
+	}
+	if q.ShippingAddress.CountryCode != "US" || q.ShippingAddress.City != "Town" {
+		t.Fatalf("address: %#v", q.ShippingAddress)
+	}
+}
+
+func TestPreCheckoutQueryFromTg(t *testing.T) {
+	u := &tg.UpdateBotPrecheckoutQuery{
+		QueryID:          200,
+		UserID:           9,
+		Payload:          []byte("p"),
+		Currency:         "USD",
+		TotalAmount:      1500,
+		ShippingOptionID: "express",
+	}
+	u.SetInfo(tg.PaymentRequestedInfo{Name: "Bob", Email: "b@x.io"})
+
+	q := preCheckoutQueryFromTg(tg.Entities{}, u)
+	if q.ID != "200" || q.From.ID != 9 || q.Currency != "USD" || q.TotalAmount != 1500 {
+		t.Fatalf("query: %#v", q)
+	}
+	if q.ShippingOptionID != "express" {
+		t.Fatalf("shipping option: %q", q.ShippingOptionID)
+	}
+	if q.OrderInfo == nil || q.OrderInfo.Name != "Bob" || q.OrderInfo.Email != "b@x.io" {
+		t.Fatalf("order info: %#v", q.OrderInfo)
+	}
+}
+
+func TestShippingOptionsToTg(t *testing.T) {
+	opts := []ShippingOption{
+		{ID: "std", Title: "Standard", Prices: []LabeledPrice{{Label: "Base", Amount: 500}}},
+	}
+	got := shippingOptionsToTg(opts)
+	if len(got) != 1 || got[0].ID != "std" || len(got[0].Prices) != 1 || got[0].Prices[0].Amount != 500 {
+		t.Fatalf("converted: %#v", got)
+	}
+}

types_payment.go

@@ -0,0 +1,53 @@
+package botapi
+
+// LabeledPrice represents a portion of the price for goods or services.
+type LabeledPrice struct {
+	Label string `json:"label"`
+	// Amount is the price in the smallest units of the currency (integer), e.g.
+	// for $1.45 pass amount = 145.
+	Amount int `json:"amount"`
+}
+
+// ShippingOption represents one shipping option.
+type ShippingOption struct {
+	ID     string         `json:"id"`
+	Title  string         `json:"title"`
+	Prices []LabeledPrice `json:"prices"`
+}
+
+// ShippingAddress represents a shipping address.
+type ShippingAddress struct {
+	CountryCode string `json:"country_code"`
+	State       string `json:"state"`
+	City        string `json:"city"`
+	StreetLine1 string `json:"street_line1"`
+	StreetLine2 string `json:"street_line2"`
+	PostCode    string `json:"post_code"`
+}
+
+// OrderInfo represents information about an order.
+type OrderInfo struct {
+	Name            string           `json:"name,omitempty"`
+	PhoneNumber     string           `json:"phone_number,omitempty"`
+	Email           string           `json:"email,omitempty"`
+	ShippingAddress *ShippingAddress `json:"shipping_address,omitempty"`
+}
+
+// ShippingQuery contains information about an incoming shipping query.
+type ShippingQuery struct {
+	ID              string          `json:"id"`
+	From            User            `json:"from"`
+	InvoicePayload  string          `json:"invoice_payload"`
+	ShippingAddress ShippingAddress `json:"shipping_address"`
+}
+
+// PreCheckoutQuery contains information about an incoming pre-checkout query.
+type PreCheckoutQuery struct {
+	ID               string     `json:"id"`
+	From             User       `json:"from"`
+	Currency         string     `json:"currency"`
+	TotalAmount      int        `json:"total_amount"`
+	InvoicePayload   string     `json:"invoice_payload"`
+	ShippingOptionID string     `json:"shipping_option_id,omitempty"`
+	OrderInfo        *OrderInfo `json:"order_info,omitempty"`
+}

update.go

@@ -11,6 +11,8 @@ type Update struct {
 	InlineQuery        *InlineQuery        `json:"inline_query,omitempty"`
 	ChosenInlineResult *ChosenInlineResult `json:"chosen_inline_result,omitempty"`
 	CallbackQuery      *CallbackQuery      `json:"callback_query,omitempty"`
+	ShippingQuery      *ShippingQuery      `json:"shipping_query,omitempty"`
+	PreCheckoutQuery   *PreCheckoutQuery   `json:"pre_checkout_query,omitempty"`
 	Poll               *Poll               `json:"poll,omitempty"`
 	PollAnswer         *PollAnswer         `json:"poll_answer,omitempty"`
 	MyChatMember       *ChatMemberUpdated  `json:"my_chat_member,omitempty"`

updates_map.go

@@ -49,3 +49,65 @@ func inlineQueryFromTg(e tg.Entities, u *tg.UpdateBotInlineQuery) *InlineQuery {
 	}
 	return iq
 }
+
+// shippingQueryFromTg builds a ShippingQuery from a bot shipping-query update.
+func shippingQueryFromTg(e tg.Entities, u *tg.UpdateBotShippingQuery) *ShippingQuery {
+	q := &ShippingQuery{
+		ID:              strconv.FormatInt(u.QueryID, 10),
+		InvoicePayload:  string(u.Payload),
+		ShippingAddress: shippingAddressFromTg(u.ShippingAddress),
+	}
+	if user, ok := e.Users[u.UserID]; ok {
+		q.From = userFromTgUser(user)
+	} else {
+		q.From = User{ID: u.UserID}
+	}
+	return q
+}
+
+// preCheckoutQueryFromTg builds a PreCheckoutQuery from a bot pre-checkout
+// update.
+func preCheckoutQueryFromTg(e tg.Entities, u *tg.UpdateBotPrecheckoutQuery) *PreCheckoutQuery {
+	q := &PreCheckoutQuery{
+		ID:               strconv.FormatInt(u.QueryID, 10),
+		Currency:         u.Currency,
+		TotalAmount:      int(u.TotalAmount),
+		InvoicePayload:   string(u.Payload),
+		ShippingOptionID: u.ShippingOptionID,
+	}
+	if user, ok := e.Users[u.UserID]; ok {
+		q.From = userFromTgUser(user)
+	} else {
+		q.From = User{ID: u.UserID}
+	}
+	if info, ok := u.GetInfo(); ok {
+		q.OrderInfo = orderInfoFromTg(info)
+	}
+	return q
+}
+
+// shippingAddressFromTg converts an MTProto post address.
+func shippingAddressFromTg(a tg.PostAddress) ShippingAddress {
+	return ShippingAddress{
+		CountryCode: a.CountryISO2,
+		State:       a.State,
+		City:        a.City,
+		StreetLine1: a.StreetLine1,
+		StreetLine2: a.StreetLine2,
+		PostCode:    a.PostCode,
+	}
+}
+
+// orderInfoFromTg converts MTProto requested payment info.
+func orderInfoFromTg(info tg.PaymentRequestedInfo) *OrderInfo {
+	out := &OrderInfo{
+		Name:        info.Name,
+		PhoneNumber: info.Phone,
+		Email:       info.Email,
+	}
+	if addr, ok := info.GetShippingAddress(); ok {
+		a := shippingAddressFromTg(addr)
+		out.ShippingAddress = &a
+	}
+	return out
+}