A comprehensive Go SDK for the Telegraph API that provides a complete, type-safe interface to all Telegraph endpoints with proper error handling, rate limiting, and retry mechanisms.
- Complete API Coverage: All Telegraph API endpoints implemented
- Type Safety: Full type-safe request/response structs
- Error Handling: Comprehensive error types and handling
- Rate Limiting: Built-in rate limiting with configurable limits
- Retry Logic: Automatic retry with exponential backoff
- Context Support: Full context support for cancellation and timeouts
- Thread Safe: Concurrent usage safe
- Configurable: Customizable HTTP client, timeouts, and retry behavior
- Content Builder: Fluent interface for building Telegraph content
- HTML to Page Conversion: Convert HTML strings to Telegraph Page objects
- Comprehensive Testing: >95% test coverage with unit and integration tests
go get github.com/telegraph-go/telegraphpackage main
import (
"context"
"fmt"
"log"
"github.com/telegraph-go/telegraph"
)
func main() {
// Create a new Telegraph client
client := telegraph.NewClient()
// Create a new account
account, err := client.CreateAccount(context.Background(), &telegraph.CreateAccountRequest{
ShortName: "MyBlog",
AuthorName: "John Doe",
AuthorURL: "https://example.com",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Account created: %s\n", account.ShortName)
fmt.Printf("Access Token: %s\n", account.AccessToken)
// Create a page using the content builder
content := telegraph.NewContentBuilder().
AddParagraph("Welcome to my first Telegraph article!").
AddHeading("Introduction", 3).
AddParagraph("This is a sample article.").
AddLink("Visit our website", "https://example.com").
Build()
page, err := client.CreatePage(context.Background(), &telegraph.CreatePageRequest{
AccessToken: account.AccessToken,
Title: "My First Article",
Content: content,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Page created: %s\n", page.URL)
// Convert HTML to Telegraph Page
htmlContent := `<html><head><title>My HTML Article</title><meta name="author" content="HTML Author"></head><body><h1>Hello</h1><p>This is from HTML.</p></body></html>`
htmlPage, err := client.ConvertHTMLToPage(htmlContent, &telegraph.HTMLToPageOptions{AuthorURL: "https://html-author.com"})
if err != nil {
log.Fatal(err)
}
fmt.Printf("HTML Page Title: %s, Author: %s, URL: %s\n", htmlPage.Title, htmlPage.AuthorName, htmlPage.AuthorURL)
}The SDK provides several configuration options:
import (
"net/http"
"time"
"golang.org/x/time/rate"
)
// Create a custom HTTP client
httpClient := &http.Client{
Timeout: 30 * time.Second,
}
// Custom retry configuration
retryConfig := telegraph.RetryConfig{
MaxRetries: 5,
InitialDelay: 100 * time.Millisecond,
MaxDelay: 10 * time.Second,
Multiplier: 2.0,
}
// Create client with custom options
client := telegraph.NewClient(
telegraph.WithHTTPClient(httpClient),
telegraph.WithBaseURL("https://api.telegra.ph"),
telegraph.WithRateLimit(rate.Limit(10)), // 10 requests per second
telegraph.WithRetryConfig(retryConfig),
)account, err := client.CreateAccount(ctx, &telegraph.CreateAccountRequest{
ShortName: "MyBlog", // Required: 1-32 characters
AuthorName: "John Doe", // Optional: 0-128 characters
AuthorURL: "https://example.com", // Optional: 0-512 characters
})account, err := client.EditAccountInfo(ctx, &telegraph.EditAccountInfoRequest{
AccessToken: "your-access-token",
ShortName: "UpdatedBlog",
AuthorName: "Jane Doe",
})account, err := client.GetAccountInfo(ctx, &telegraph.GetAccountInfoRequest{
AccessToken: "your-access-token",
Fields: []string{"short_name", "author_name", "page_count"},
})page, err := client.CreatePage(ctx, &telegraph.CreatePageRequest{
AccessToken: "your-access-token",
Title: "My Article",
AuthorName: "John Doe",
Content: content, // []telegraph.Node
ReturnContent: true,
})page, err := client.EditPage(ctx, &telegraph.EditPageRequest{
AccessToken: "your-access-token",
Path: "My-Article-12-15",
Title: "Updated Title",
Content: updatedContent,
})page, err := client.GetPage(ctx, &telegraph.GetPageRequest{
Path: "My-Article-12-15",
ReturnContent: true,
})pageList, err := client.GetPageList(ctx, &telegraph.GetPageListRequest{
AccessToken: "your-access-token",
Offset: 0,
Limit: 50,
})views, err := client.GetViews(ctx, &telegraph.GetViewsRequest{
Path: "My-Article-12-15",
Year: 2023,
Month: 12,
Day: 15,
Hour: 10,
})The SDK provides a fluent interface for building Telegraph content:
content := telegraph.NewContentBuilder().
AddParagraph("Introduction paragraph").
AddHeading("Section Title", 3).
AddParagraph("Section content").
AddLink("Example Link", "https://example.com").
AddImage("https://example.com/image.jpg").
AddBlockquote("Important quote").
AddCodeBlock("fmt.Println(\"Hello, World!\")").
AddLineBreak().
Build()- Paragraphs:
AddParagraph(text) - Headings:
AddHeading(text, level)(levels 3-4) - Links:
AddLink(text, url) - Images:
AddImage(src) - Blockquotes:
AddBlockquote(text) - Code Blocks:
AddCodeBlock(code) - Line Breaks:
AddLineBreak()
The SDK provides comprehensive error handling:
page, err := client.GetPage(ctx, &telegraph.GetPageRequest{
Path: "non-existent-page",
})
if err != nil {
var apiErr *telegraph.APIError
if errors.As(err, &apiErr) {
fmt.Printf("API Error (code %d): %s\n", apiErr.Code, apiErr.Description)
} else {
fmt.Printf("Generic Error: %v\n", err)
}
}The SDK includes built-in rate limiting to respect API limits:
// Set custom rate limit (requests per second)
client := telegraph.NewClient(
telegraph.WithRateLimit(rate.Limit(5)), // 5 requests per second
)Automatic retry with exponential backoff for failed requests:
retryConfig := telegraph.RetryConfig{
MaxRetries: 3, // Maximum retry attempts
InitialDelay: 100 * time.Millisecond, // Initial delay
MaxDelay: 5 * time.Second, // Maximum delay
Multiplier: 2.0, // Backoff multiplier
}
client := telegraph.NewClient(
telegraph.WithRetryConfig(retryConfig),
)Run the unit tests:
go test ./...Run integration tests (requires internet connection):
TELEGRAPH_INTEGRATION_TEST=1 go test ./...Run benchmarks:
go test -bench=. ./...Check out the examples directory for more comprehensive usage examples:
- Basic Usage - Simple account and page creation
- Advanced Usage - Advanced features and configuration
- Integration Tests - Real API integration tests
The Telegraph client is thread-safe and can be used concurrently from multiple goroutines:
client := telegraph.NewClient()
// Safe to use from multiple goroutines
for i := 0; i < 10; i++ {
go func(i int) {
page, err := client.GetPage(ctx, &telegraph.GetPageRequest{
Path: fmt.Sprintf("page-%d", i),
})
// Handle page and err
}(i)
}Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Initial release
- Complete Telegraph API coverage
- Type-safe request/response structs
- Comprehensive error handling
- Rate limiting and retry logic
- Content builder utility
- HTML to Page Conversion
- Full test coverage
- Documentation and examples
If you have questions or need help, please:
- Check the documentation
- Look at the examples
- Open an issue on GitHub
- Telegraph API for providing the excellent API
- The Go community for inspiration and best practices