feat(telegram): add SendDocument + wire document media type in sendMedia

Adds Bot.SendDocument(chatID, path, caption, opts) for sending
documents via the Telegram API, matching the SendPhoto/SendVoice
pattern. Wires 'document' media type into handler.sendMedia so
MEDIA:document:path responses are delivered correctly. Updates
testServer to handle /sendDocument and adds dedicated tests.

Author: molty3000

internal/telegram/bot.go

@@ -276,6 +276,26 @@ func (b *Bot) SendVoice(chatID int64, path string, caption string, opts *SendOpt
 	return &msg, nil
 }
 
+// SendDocument sends a document from a file path to the specified chat.
+// opts may contain ReplyToMessageID to reply to a specific message.
+func (b *Bot) SendDocument(chatID int64, path string, caption string, opts *SendOpts) (*Message, error) {
+	params := map[string]any{
+		"chat_id": chatID,
+	}
+	if caption != "" {
+		params["caption"] = caption
+	}
+	if opts != nil && opts.ReplyToMessageID != 0 {
+		params["reply_to_message_id"] = opts.ReplyToMessageID
+	}
+
+	var msg Message
+	if err := b.doUpload("sendDocument", "document", path, params, &msg); err != nil {
+		return nil, err
+	}
+	return &msg, nil
+}
+
 // GetUpdates retrieves incoming updates using long polling.
 func (b *Bot) GetUpdates(offset int, timeout int) ([]Update, error) {
 	params := map[string]any{

internal/telegram/bot_test.go

@@ -626,6 +626,91 @@ func TestSendPhoto_FileNotFound(t *testing.T) {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// SendDocument — multipart upload
+// ---------------------------------------------------------------------------
+
+func TestSendDocument_Success(t *testing.T) {
+	tmpDir := t.TempDir()
+	docPath := filepath.Join(tmpDir, "test_doc.pdf")
+	if err := os.WriteFile(docPath, []byte("fake-pdf-data"), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		path := strings.TrimSuffix(r.URL.Path, "/")
+		if path != "/sendDocument" {
+			t.Errorf("unexpected path: %s", path)
+		}
+		requireMultipartBody(t, r, "document", "test_doc.pdf", map[string]any{
+			"chat_id": float64(123),
+			"caption": "here is the doc",
+		})
+		okResponse(w, map[string]any{
+			"message_id": 20,
+			"text":       "",
+			"chat":       map[string]any{"id": 123, "type": "private"},
+			"date":       2000,
+		})
+	}))
+	defer ts.Close()
+
+	bot := NewBot("x")
+	bot.BaseURL = ts.URL
+
+	msg, err := bot.SendDocument(123, docPath, "here is the doc", nil)
+	if err != nil {
+		t.Fatalf("SendDocument: %v", err)
+	}
+	if msg == nil {
+		t.Fatal("SendDocument returned nil message")
+	}
+	if msg.ID != 20 {
+		t.Errorf("msg.ID = %d, want 20", msg.ID)
+	}
+}
+
+func TestSendDocument_NoCaption(t *testing.T) {
+	tmpDir := t.TempDir()
+	docPath := filepath.Join(tmpDir, "report.csv")
+	if err := os.WriteFile(docPath, []byte("a,b,c\n1,2,3"), 0o644); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requireMultipartBody(t, r, "document", "report.csv", map[string]any{
+			"chat_id": float64(456),
+		})
+		okResponse(w, map[string]any{
+			"message_id": 21,
+			"chat":       map[string]any{"id": 456},
+		})
+	}))
+	defer ts.Close()
+
+	bot := NewBot("x")
+	bot.BaseURL = ts.URL
+
+	msg, err := bot.SendDocument(456, docPath, "", nil)
+	if err != nil {
+		t.Fatalf("SendDocument(no caption): %v", err)
+	}
+	if msg.ID != 21 {
+		t.Errorf("msg.ID = %d, want 21", msg.ID)
+	}
+}
+
+func TestSendDocument_FileNotFound(t *testing.T) {
+	bot := NewBot("x")
+	_, err := bot.SendDocument(1, "/nonexistent/path.pdf", "", nil)
+	if err == nil {
+		t.Fatal("expected error for missing file, got nil")
+	}
+	if !strings.Contains(err.Error(), "open") {
+		t.Errorf("error = %q, want substring %q", err, "open")
+	}
+}
+
 // ---------------------------------------------------------------------------
 // AnswerCallbackQuery
 // ---------------------------------------------------------------------------

internal/telegram/handler.go

@@ -438,6 +438,12 @@ func (h *Handler) sendMedia(chatID int64, text string, replyToMessageID int) {
 			opts = &SendOpts{ReplyToMessageID: replyToMessageID}
 		}
 		_, err = h.Bot.SendVoice(chatID, filePath, "", opts)
+	case "document":
+		var opts *SendOpts
+		if replyToMessageID != 0 {
+			opts = &SendOpts{ReplyToMessageID: replyToMessageID}
+		}
+		_, err = h.Bot.SendDocument(chatID, filePath, "", opts)
 	default:
 		h.log.Error("unknown media type", "chat_id", chatID, "media_type", mediaType)
 		if h.OnError != nil {

internal/telegram/handler_test.go

@@ -63,6 +63,11 @@ func testServer(t *testing.T, recorder *requestRecorder) *httptest.Server {
 				"ok":     true,
 				"result": map[string]any{"message_id": 3},
 			}
+		case strings.HasSuffix(r.URL.Path, "/sendDocument"):
+			resp = map[string]any{
+				"ok":     true,
+				"result": map[string]any{"message_id": 4},
+			}
 		default:
 			resp = map[string]any{"ok": true}
 		}
@@ -1084,19 +1089,49 @@ func TestSendResponse_MediaUnknownType(t *testing.T) {
 		errCalled = true
 	}
 
-	h.SendResponse(123, "MEDIA:document:"+tmpPath, 0)
+	h.SendResponse(123, "MEDIA:video:"+tmpPath, 0)
 
 	reqs := rec.all()
 	for _, req := range reqs {
-		if strings.HasSuffix(req.Path, "/sendPhoto") || strings.HasSuffix(req.Path, "/sendVoice") {
-			t.Errorf("unexpected send request for unknown media type")
+		if strings.HasSuffix(req.Path, "/sendPhoto") || strings.HasSuffix(req.Path, "/sendVoice") || strings.HasSuffix(req.Path, "/sendDocument") {
+			t.Errorf("unexpected send request for unknown media type: %s", req.Path)
 		}
 	}
 	if !errCalled {
 		t.Error("OnError was not called for unknown media type")
 	}
 }
 
+func TestSendResponse_MediaDocument(t *testing.T) {
+	tmpFile, err := os.CreateTemp("", "test-doc-*.pdf")
+	if err != nil {
+		t.Fatalf("failed to create temp file: %v", err)
+	}
+	tmpPath := tmpFile.Name()
+	tmpFile.Close()
+	defer os.Remove(tmpPath)
+
+	rec := new(requestRecorder)
+	ts := testServer(t, rec)
+	defer ts.Close()
+	bot := testBot(t, ts)
+	h := NewHandler(bot)
+
+	h.SendResponse(456, "MEDIA:document:"+tmpPath, 0)
+
+	reqs := rec.all()
+	found := false
+	for _, req := range reqs {
+		if strings.HasSuffix(req.Path, "/sendDocument") {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Error("no sendDocument request was made for MEDIA:document")
+	}
+}
+
 func TestSendResponse_MediaMalformed(t *testing.T) {
 	rec := new(requestRecorder)
 	ts := testServer(t, rec)