(new): v1.2 release

tgapi/methods.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"math"
 	"net/http"
 
 	"git.scuroneko.dev/scuroneko/laniakea/utils"
@@ -12,9 +13,24 @@ import (
 // UpdateParams holds parameters for the getUpdates method.
 // See https://core.telegram.org/bots/api#getupdates
 type UpdateParams struct {
-	Offset         *int         `json:"offset,omitempty"`
-	Limit          *int         `json:"limit,omitempty"`
-	Timeout        *int         `json:"timeout,omitempty"`
+	// Offset Optional. Identifier of the first update to be returned. Must be greater by one than the highest
+	// among the identifiers of previously received updates. By default, updates starting with the earliest
+	// unconfirmed update are returned. An update is considered confirmed as soon as getUpdates is called with
+	// an offset higher than its update_id. The negative offset can be specified to retrieve updates starting
+	// from -offset update from the end of the updates queue. All previous updates will be forgotten.
+	Offset *int `json:"offset,omitempty"`
+	// Limit Optional. Limits the number of updates to be retrieved. Values between 1-100 are accepted. Defaults
+	// to 100.
+	Limit *int `json:"limit,omitempty"`
+	// Timeout Optional. Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling. Should be
+	// positive, short polling should be used for testing purposes only.
+	Timeout *int `json:"timeout,omitempty"`
+	// AllowedUpdates Optional. A JSON-serialized list of the update types you want your bot to receive. For
+	// example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these
+	// types. See Update for a complete list of available update types. Specify an empty list to receive all
+	// update types except chat_member, message_reaction, and message_reaction_count (default). If not
+	// specified, the previous setting will be used. Please note that this parameter doesn't affect updates
+	// created before the call to getUpdates, so unwanted updates may be received for a short period of time.
 	AllowedUpdates []UpdateType `json:"allowed_updates,omitempty"`
 }
 
@@ -36,6 +52,7 @@ func (api *API) GetMeWithContext(ctx context.Context) (User, error) {
 // GetManagedBotToken holds parameters for the getManagedBotToken method.
 // See https://core.telegram.org/bots/api#getmanagedbottoken
 type GetManagedBotToken struct {
+	// UserID Required. User identifier of the managed bot whose token will be returned
 	UserID int64 `json:"user_id"`
 }
 
@@ -57,6 +74,7 @@ func (api *API) GetManagedBotTokenWithContext(ctx context.Context, params GetMan
 // ReplaceManagedBotToken holds parameters for the replaceManagedBotToken method.
 // See https://core.telegram.org/bots/api#replacemanagedbottoken
 type ReplaceManagedBotToken struct {
+	// UserID Required. User identifier of the managed bot whose token will be replaced
 	UserID int64 `json:"user_id"`
 }
 
@@ -126,12 +144,29 @@ func (api *API) GetUpdatesWithContext(ctx context.Context, params UpdateParams)
 // To upload a self-signed certificate, use Uploader.SetWebhook.
 // See https://core.telegram.org/bots/api#setwebhook
 type SetWebhook struct {
-	URL                string       `json:"url"`
-	IPAddress          string       `json:"ip_address,omitempty"`
-	MaxConnections     int8         `json:"max_connections,omitempty"`
-	AllowedUpdates     []UpdateType `json:"allowed_updates,omitempty"`
-	DropPendingUpdates bool         `json:"drop_pending_updates,omitempty"`
-	SecretToken        string       `json:"secret_token,omitempty"`
+	// URL Required. HTTPS URL to send updates to. Use an empty string to remove webhook integration.
+	URL string `json:"url"`
+	// IPAddress Optional. The fixed IP address which will be used to send webhook requests instead of the IP
+	// address resolved through DNS
+	IPAddress string `json:"ip_address,omitempty"`
+	// MaxConnections Optional. The maximum allowed number of simultaneous HTTPS connections to the webhook for
+	// update delivery, 1-100. Defaults to 40. Use lower values to limit the load on your bot's server, and
+	// higher values to increase your bot's throughput.
+	MaxConnections int8 `json:"max_connections,omitempty"`
+	// AllowedUpdates Optional. A JSON-serialized list of the update types you want your bot to receive. For
+	// example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these
+	// types. See Update for a complete list of available update types. Specify an empty list to receive all
+	// update types except chat_member, message_reaction, and message_reaction_count (default). If not
+	// specified, the previous setting will be used. Please note that this parameter doesn't affect updates
+	// created before the call to the setWebhook, so unwanted updates may be received for a short period of
+	// time.
+	AllowedUpdates []UpdateType `json:"allowed_updates,omitempty"`
+	// DropPendingUpdates Optional. Pass True to drop all pending updates
+	DropPendingUpdates bool `json:"drop_pending_updates,omitempty"`
+	// SecretToken Optional. A secret token to be sent in a header “X-Telegram-Bot-Api-Secret-Token” in
+	// every webhook request, 1-256 characters. Only characters A-Z, a-z, 0-9, _ and - are allowed. The header
+	// is useful to ensure that the request comes from a webhook set by you.
+	SecretToken string `json:"secret_token,omitempty"`
 }
 
 // SetWebhook sets a webhook URL for incoming updates.
@@ -155,6 +190,7 @@ func (api *API) SetWebhookWithContext(ctx context.Context, params SetWebhook) (b
 // DeleteWebhook holds parameters for the deleteWebhook method.
 // See https://core.telegram.org/bots/api#deletewebhook
 type DeleteWebhook struct {
+	// DropPendingUpdates Optional. Pass True to drop all pending updates
 	DropPendingUpdates bool `json:"drop_pending_updates,omitempty"`
 }
 
@@ -192,6 +228,7 @@ func (api *API) GetWebhookInfoWithContext(ctx context.Context) (WebhookInfo, err
 // GetFile holds parameters for the getFile method.
 // See https://core.telegram.org/bots/api#getfile
 type GetFile struct {
+	// FileID Required. File identifier to get information about
 	FileID string `json:"file_id"`
 }
 
@@ -213,6 +250,8 @@ func (api *API) GetFileWithContext(ctx context.Context, params GetFile) (File, e
 // GetFileByLink downloads a file from Telegram's file server using the provided file link.
 // The link is usually obtained from File.FilePath.
 // For large files, prefer OpenFileByLink or OpenFileByLinkWithContext to stream the response body.
+// This unbounded helper is retained for v1 compatibility and is subject to change in v2;
+// prefer GetFileByLinkLimit for untrusted or potentially large files.
 // See https://core.telegram.org/bots/api#file
 func (api *API) GetFileByLink(link string) ([]byte, error) {
 	return api.getFileByLink(context.Background(), link)
@@ -226,6 +265,37 @@ func (api *API) GetFileByLinkWithContext(ctx context.Context, link string) ([]by
 	return api.getFileByLink(ctx, link)
 }
 
+// GetFileByLinkLimit downloads at most maxBytes from Telegram's file server.
+// It returns ErrFileTooLarge when the response exceeds the limit.
+func (api *API) GetFileByLinkLimit(link string, maxBytes int64) ([]byte, error) {
+	return api.GetFileByLinkLimitWithContext(context.Background(), link, maxBytes)
+}
+
+// GetFileByLinkLimitWithContext is the context-aware variant of GetFileByLinkLimit.
+func (api *API) GetFileByLinkLimitWithContext(ctx context.Context, link string, maxBytes int64) ([]byte, error) {
+	if maxBytes < 0 {
+		return nil, fmt.Errorf("maximum file size must not be negative: %d", maxBytes)
+	}
+	body, err := api.openFileByLink(ctx, link)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = body.Close() }()
+
+	readLimit := maxBytes
+	if readLimit < math.MaxInt64 {
+		readLimit++
+	}
+	data, err := io.ReadAll(io.LimitReader(body, readLimit))
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(data)) > maxBytes {
+		return nil, ErrFileTooLarge
+	}
+	return data, nil
+}
+
 // OpenFileByLink opens a streaming response body for a file hosted on Telegram's file server.
 // The caller must close the returned ReadCloser.
 // See https://core.telegram.org/bots/api#file