feat: add upload convenience methods, new permissions, and godoc examples (v0.4.0)

Add UploadPhotoFromFile, UploadPhotoFromURL, UploadMediaFromFile,
UploadMediaFromURL with security hardening: URL scheme validation
(http/https only), 50 MB download limit, Content-Disposition filename
sanitization, and proper timeout propagation via ensureTimeout.

Introduce ErrFetch error kind for external URL and local file failures,
separating them from ErrAPI (Max Bot API errors) and ErrNetwork.

Add 5 new ChatAdminPermission constants documented on dev.max.ru and
8 example tests for godoc documentation.

Author: Saveliy Yudin

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [v0.4.0] - 2026-03-11
+
+### Added
+- 5 new `ChatAdminPermission` constants: `PermCanCall`, `PermEditLink`, `PermPostEditDeleteMessage`, `PermEditMessage`, `PermDeleteMessage`
+- Upload convenience methods: `UploadPhotoFromFile`, `UploadPhotoFromURL`, `UploadMediaFromFile`, `UploadMediaFromURL`
+- `ErrFetch` error kind for external URL and local file failures in upload helpers
+- Example tests for godoc documentation
+
+### Security
+- `FromURL` upload methods validate URL scheme (only http/https allowed, prevents SSRF via file:// etc.)
+- `FromURL` upload methods limit download size to 50 MB (`maxFetchSize`)
+- `extractFilename` sanitizes Content-Disposition filenames with `filepath.Base` (prevents path traversal)
+
 ## [v0.3.0] - 2026-02-23
 
 ### Added

client.go

@@ -201,6 +201,14 @@ func (c *Client) parseAPIError(op string, statusCode int, body []byte) *Error {
 	return apiError(op, statusCode, msg)
 }
 
+// ensureTimeout applies the default timeout if the context has no deadline.
+func (c *Client) ensureTimeout(ctx context.Context) (context.Context, context.CancelFunc) {
+	if _, ok := ctx.Deadline(); !ok && c.timeout > 0 {
+		return context.WithTimeout(ctx, c.timeout)
+	}
+	return ctx, func() {}
+}
+
 func isTimeout(err error) bool {
 	var t interface{ Timeout() bool }
 	if errors.As(err, &t) {

errors.go

@@ -24,6 +24,9 @@ const (
 	ErrTimeout
 	// ErrDecode indicates a JSON marshal or unmarshal failure.
 	ErrDecode
+	// ErrFetch indicates a failure when downloading from an external URL
+	// (used by UploadPhotoFromURL and UploadMediaFromURL).
+	ErrFetch
 )
 
 // String returns a human-readable name for the error kind.
@@ -37,6 +40,8 @@ func (k ErrorKind) String() string {
 		return "timeout"
 	case ErrDecode:
 		return "decode"
+	case ErrFetch:
+		return "fetch"
 	default:
 		return "unknown"
 	}
@@ -70,7 +75,7 @@ type Error struct {
 
 // Error returns a formatted error string including the operation, kind, and details.
 func (e *Error) Error() string {
-	if e.Kind == ErrAPI {
+	if e.Kind == ErrAPI || e.Kind == ErrFetch {
 		return fmt.Sprintf("%s: %s error %d: %s", e.Op, e.Kind, e.StatusCode, e.Message)
 	}
 	if e.Message != "" {
@@ -125,3 +130,12 @@ func decodeError(op string, err error) *Error {
 		Err:     err,
 	}
 }
+
+func fetchError(op string, statusCode int, message string) *Error {
+	return &Error{
+		Kind:       ErrFetch,
+		StatusCode: statusCode,
+		Message:    message,
+		Op:         op,
+	}
+}

example_test.go

@@ -0,0 +1,143 @@
+package maxigo_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/maxigo-bot/maxigo-client"
+)
+
+func ExampleNew() {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(maxigo.BotInfo{
+			UserWithPhoto: maxigo.UserWithPhoto{
+				User: maxigo.User{UserID: 1, FirstName: "TestBot", IsBot: true},
+			},
+		})
+	}))
+	defer srv.Close()
+
+	client, err := maxigo.New("test-token", maxigo.WithBaseURL(srv.URL))
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+
+	bot, err := client.GetBot(context.Background())
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+	fmt.Println(bot.FirstName)
+	// Output: TestBot
+}
+
+func ExampleClient_SendMessage() {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		resp := struct {
+			Message maxigo.Message `json:"message"`
+		}{
+			Message: maxigo.Message{
+				Body: maxigo.MessageBody{MID: "mid-1", Text: strPtr("Hello!")},
+			},
+		}
+		_ = json.NewEncoder(w).Encode(resp)
+	}))
+	defer srv.Close()
+
+	client, _ := maxigo.New("test-token", maxigo.WithBaseURL(srv.URL))
+	msg, err := client.SendMessage(context.Background(), 12345, &maxigo.NewMessageBody{
+		Text: maxigo.Some("Hello!"),
+	})
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+	fmt.Println(*msg.Body.Text)
+	// Output: Hello!
+}
+
+func ExampleClient_AnswerCallback() {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(maxigo.SimpleQueryResult{Success: true})
+	}))
+	defer srv.Close()
+
+	client, _ := maxigo.New("test-token", maxigo.WithBaseURL(srv.URL))
+	result, err := client.AnswerCallback(context.Background(), "cb-123", &maxigo.CallbackAnswer{
+		Notification: maxigo.Some("Done!"),
+	})
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+	fmt.Println(result.Success)
+	// Output: true
+}
+
+func ExampleClient_UploadPhoto() {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/uploads":
+			// GetUploadURL — return the same server
+			_ = json.NewEncoder(w).Encode(maxigo.UploadEndpoint{
+				URL: "http://" + r.Host + "/do-upload",
+			})
+		default:
+			// Actual upload
+			_ = json.NewEncoder(w).Encode(maxigo.PhotoTokens{
+				Photos: map[string]maxigo.PhotoToken{"default": {Token: "photo-tok"}},
+			})
+		}
+	}))
+	defer srv.Close()
+
+	client, _ := maxigo.New("test-token", maxigo.WithBaseURL(srv.URL))
+	tokens, err := client.UploadPhoto(context.Background(), "photo.jpg", strings.NewReader("image data"))
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+	fmt.Println(tokens.Photos["default"].Token)
+	// Output: photo-tok
+}
+
+func ExampleNewCallbackButton() {
+	btn := maxigo.NewCallbackButton("OK", "confirm")
+	fmt.Printf("type=%s text=%s payload=%s\n", btn.Type, btn.Text, btn.Payload)
+	// Output: type=callback text=OK payload=confirm
+}
+
+func ExampleNewLinkButton() {
+	btn := maxigo.NewLinkButton("Open", "https://example.com")
+	fmt.Printf("type=%s url=%s\n", btn.Type, btn.URL)
+	// Output: type=link url=https://example.com
+}
+
+func ExampleSome() {
+	opt := maxigo.Some("hello")
+	fmt.Printf("set=%t value=%s\n", opt.Set, opt.Value)
+
+	var empty maxigo.OptString
+	fmt.Printf("set=%t value=%q\n", empty.Set, empty.Value)
+	// Output:
+	// set=true value=hello
+	// set=false value=""
+}
+
+func ExampleNewInlineKeyboardAttachment() {
+	kb := maxigo.NewInlineKeyboardAttachment([][]maxigo.Button{
+		{
+			maxigo.NewCallbackButton("Yes", "yes"),
+			maxigo.NewCallbackButton("No", "no"),
+		},
+	})
+	fmt.Println(kb.Type)
+	// Output: inline_keyboard
+}
+
+func strPtr(s string) *string { return &s }

types.go

@@ -105,6 +105,12 @@ const (
 	PermChangeChatInfo   ChatAdminPermission = "change_chat_info"
 	PermPinMessage       ChatAdminPermission = "pin_message"
 	PermWrite            ChatAdminPermission = "write"
+
+	PermCanCall               ChatAdminPermission = "can_call"
+	PermEditLink              ChatAdminPermission = "edit_link"
+	PermPostEditDeleteMessage ChatAdminPermission = "post_edit_delete_message"
+	PermEditMessage           ChatAdminPermission = "edit_message"
+	PermDeleteMessage         ChatAdminPermission = "delete_message"
 )
 
 // User represents a Max user or bot.

types_test.go

@@ -548,6 +548,49 @@ func TestParseAttachments(t *testing.T) {
 	})
 }
 
+func TestChatAdminPermissionJSON(t *testing.T) {
+	allPerms := []ChatAdminPermission{
+		PermReadAllMessages,
+		PermAddRemoveMembers,
+		PermAddAdmins,
+		PermChangeChatInfo,
+		PermPinMessage,
+		PermWrite,
+		PermCanCall,
+		PermEditLink,
+		PermPostEditDeleteMessage,
+		PermEditMessage,
+		PermDeleteMessage,
+	}
+
+	admin := ChatAdmin{
+		UserID:      12345,
+		Permissions: allPerms,
+	}
+
+	data, err := json.Marshal(admin)
+	if err != nil {
+		t.Fatalf("Marshal error: %v", err)
+	}
+
+	var got ChatAdmin
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("Unmarshal error: %v", err)
+	}
+
+	if got.UserID != admin.UserID {
+		t.Errorf("UserID = %d, want %d", got.UserID, admin.UserID)
+	}
+	if len(got.Permissions) != len(allPerms) {
+		t.Fatalf("Permissions count = %d, want %d", len(got.Permissions), len(allPerms))
+	}
+	for i, p := range got.Permissions {
+		if p != allPerms[i] {
+			t.Errorf("Permissions[%d] = %q, want %q", i, p, allPerms[i])
+		}
+	}
+}
+
 func TestContactAttachmentPayload_Phone(t *testing.T) {
 	tests := []struct {
 		name    string