gtvapi - Gronkh.TV API Client for Go

A robust, production-ready Go client library for the Gronkh.TV API. This library provides easy access to video information, comments, playlists, discovery features, and Twitch live status.

Features

• 🚀 Simple and intuitive API - Easy-to-use client with clear method names
• 🔄 Automatic retry logic - Built-in retry with exponential backoff for resilient API calls
• ⏱️ Context support - Full context support for cancellation and timeouts
• 📝 Comprehensive documentation - Complete GoDoc comments for all public APIs
• ✅ Well-tested - High test coverage with unit and integration tests
• 🛡️ Type-safe - Strongly typed responses with proper error handling
• 🔍 Request logging - Optional debug logging for troubleshooting

Installation

go get github.com/wehmoen-dev/gtvapi

Requirements

• Go 1.20 or higher

Quick Start

package main
import (
"context""fmt""log""time""github.com/wehmoen-dev/gtvapi"
)
funcmain() {
// Create a new clientclient:=gtvapi.NewClient(nil)
// Set a timeout contextctx, cancel:=context.WithTimeout(context.Background(), 10*time.Second)
defercancel()
// Get video informationvideoInfo, err:=client.VideoInfo(ctx, 1000)
iferr!=nil {
log.Fatal(err)
}
fmt.Printf("Video: %s (Episode %d)\n", videoInfo.Title, videoInfo.Episode)
fmt.Printf("Views: %d\n", videoInfo.Views)
}

Usage Examples

Creating a Client

Basic Client

client:=gtvapi.NewClient(nil)

Client with Custom Options

config:=&gtvapi.ClientConfig{
Debug: true, // Enable debug loggingTimeout: 30*time.Second, // Request timeoutMaxRetries: 3, // Maximum retry attemptsRetryWaitMin: 1*time.Second, // Minimum wait between retriesRetryWaitMax: 30*time.Second, // Maximum wait between retries
}
client:=gtvapi.NewClient(config)

Getting Video Information

ctx:=context.Background()
videoInfo, err:=client.VideoInfo(ctx, 1000)
iferr!=nil {
log.Fatal(err)
}
fmt.Printf("Title: %s\n", videoInfo.Title)
fmt.Printf("Season: %d, Episode: %d\n", videoInfo.Season, videoInfo.Episode)
fmt.Printf("Duration: %d seconds\n", videoInfo.SourceLength)

Fetching Video Comments

ctx:=context.Background()
comments, err:=client.VideoComments(ctx, 1000)
iferr!=nil {
log.Fatal(err)
}
for_, comment:=rangecomments {
fmt.Printf("%s: %s\n", comment.User.Username, comment.Comment)
}

Getting Video Playlist URL

ctx:=context.Background()
playlistURL, err:=client.VideoPlaylist(ctx, 1000)
iferr!=nil {
log.Fatal(err)
}
fmt.Printf("Playlist URL: %s\n", playlistURL)

Discovering Videos

ctx:=context.Background()
// Get most recent videosrecent, err:=client.Discover(ctx, gtvapi.DiscoveryTypeRecent)
iferr!=nil {
log.Fatal(err)
}
// Get most viewed videospopular, err:=client.Discover(ctx, gtvapi.DiscoveryTypeViews)
iferr!=nil {
log.Fatal(err)
}
// Get similar videossimilar, err:=client.Discover(ctx, gtvapi.DiscoveryTypeSimilar)
iferr!=nil {
log.Fatal(err)
}

Fetching All Tags

ctx:=context.Background()
tags, err:=client.AllTags(ctx)
iferr!=nil {
log.Fatal(err)
}
for_, tag:=rangetags {
fmt.Printf("Tag #%d: %s\n", tag.ID, tag.Title)
}

Checking Twitch Live Status

ctx:=context.Background()
channels, err:=client.LiveCheck(ctx)
iferr!=nil {
log.Fatal(err)
}
forname, info:=rangechannels {
ifinfo.IsLive {
fmt.Printf("%s is live! Viewers: %d\n", name, info.ViewerCount)
fmt.Printf("Playing: %s\n", info.GameName)
}
}

API Reference

Client Methods

NewClient(config *ClientConfig) *Client

Creates a new Gronkh.TV API client with optional configuration.

VideoInfo(ctx context.Context, episode int) (*VideoInfo, error)

Retrieves detailed information about a specific video episode.

VideoComments(ctx context.Context, episode int) ([]Comment, error)

Fetches all comments for a specific video episode.

VideoPlaylist(ctx context.Context, episode int) (string, error)

Gets the playlist URL for streaming a specific video episode.

Discover(ctx context.Context, discoveryType DiscoveryType) ([]VideoSearchResult, error)

Discovers videos based on the specified discovery type (recent, views, or similar).

AllTags(ctx context.Context) ([]Tag, error)

Retrieves all available video tags.

LiveCheck(ctx context.Context) (map[ChannelName]ChannelInfo, error)

Checks the live status of Twitch channels associated with Gronkh.TV.

Types

See the GoDoc for detailed type definitions and field descriptions.

Error Handling

The library provides structured error handling:

videoInfo, err:=client.VideoInfo(ctx, 1000)
iferr!=nil {
// Check for specific error typesiferrors.Is(err, context.DeadlineExceeded) {
log.Println("Request timed out")
} elseiferrors.Is(err, context.Canceled) {
log.Println("Request was canceled")
} else {
log.Printf("API error: %v", err)
}
return
}

Best Practices

1. Always use context - Pass context to all API methods for proper timeout and cancellation handling
2. Set reasonable timeouts - Configure appropriate timeouts based on your use case
3. Handle errors properly - Check and handle all errors returned by the API
4. Reuse clients - Create one client and reuse it for multiple requests
5. Enable retry logic - Use the built-in retry mechanism for production environments

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Testing

Run the test suite:

# Run all tests
go test -v ./...
# Run tests with coverage
go test -v -cover ./...
# Run tests with race detection
go test -v -race ./...
# Run benchmarks
go test -bench=. ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Gronkh.TV for providing the API
• Resty for the excellent HTTP client library

Support

For questions, issues, or feature requests, please open an issue on GitHub.