helix Go Client for Twitch Helix API

Twitch enforces rate limits. Helix provides helper methods on response objects to retrieve rate limit headers as integers:

• Response.GetRateLimit()
• Response.GetRateLimitRemaining()
• Response.GetRateLimitReset()
• Response.GetClipsCreationRateLimit() (specific to CreateClip)
• Response.GetClipsCreationRateLimitRemaining() (specific to CreateClip)

You can provide a custom RateLimitFunc in helix.Options. If provided, the client will re-attempt a request if it receives a 429 (Too Many Requests) response, applying the function before retrying.

Helix includes a DefaultRateLimitFunc that automatically waits until the rate limit reset time before retrying.

client, err := helix.NewClient(&helix.Options{
    ClientID:      "your-client-id",
    RateLimitFunc: helix.DefaultRateLimitFunc,
})

Every API request returns a response object that includes a ResponseCommon struct. This struct contains the HTTP status code and any error information returned by Twitch. This is useful for detecting 500 errors or invalid requests.

Common fields in ResponseCommon:

• StatusCode (int): The HTTP status code.
• Header (http.Header): The response headers.
• Error (string): The error string returned by the API.
• ErrorStatus (int): The error status code.
• ErrorMessage (string): The error message returned by the API.

type ResponseCommon struct {
    StatusCode   int
    Header       http.Header
    Error        string `json:"error"`
    ErrorStatus  int    `json:"status"`
    ErrorMessage string `json:"message"`
}

To cancel an ongoing raid, use the CancelRaid method on a helix.Client instance. You must provide a CancelRaidParams object containing the BroadcasterID of the broadcaster whose raid is being cancelled.

client, err := helix.NewClient(&helix.Options{
    ClientID: "your-client-id",
})
if err != nil {
    // handle error
}

resp, err := client.CancelRaid(&helix.CancelRaidParams{
    BroadcasterID: "22484632", 
})
if err != nil {
    // handle error
}

fmt.Printf("%+v\n", resp)

When retrieving drops entitlements, use the After and First fields in GetDropEntitlementsParams to handle pagination. To fetch the next page of results, pass the Cursor value from the current response's pagination object into the After field of the next request.

Example of fetching the first page and then the subsequent page:

// First page 
resp, err := client.GetDropsEntitlements(&helix.GetDropEntitlementsParams{
	GameID: "your-game-id",
    After: "",
    First: 50,
})

// Next page
resp, err = client.GetDropsEntitlements(&helix.GetDropEntitlementsParams{
	GameID: "your-game-id",
    After: resp.Data.Pagination.Cursor,
    First: 50,
})

Use RevokeUserAccessToken to invalidate an existing user access token. You can retrieve the current token from the client using GetUserAccessToken() before passing it to the revocation method.

client, err := helix.NewClient(&helix.Options{
    ClientID: "your-client-id",
})
if err != nil {
    // handle error
}

userAccessToken := client.GetUserAccessToken()

resp, err := client.RevokeUserAccessToken(userAccessToken)
if err != nil {
    // handle error
}

fmt.Printf("%+v\n", resp)

You can customize the User-Agent header sent with every request using two methods:

1. During Client Initialization: Pass the UserAgent string within the helix.Options struct when calling helix.NewClient().
2. After Client Initialization: Call the SetUserAgent(string) method on an existing client instance.

This is useful for identifying your application to the Helix API.

// Method 1: Via Options
client, err := helix.NewClient(&helix.Options{
    ClientID:  "your-client-id",
    UserAgent: "your-user-agent-value",
})

// Method 2: Via SetUserAgent method
client.SetUserAgent("your-user-agent-value")

Use GetAuthorizationURL to generate a URL that allows users to authenticate with their Twitch accounts. After authorization, the user is redirected to your RedirectURI with an authorization code.

To use this, initialize a client with ClientID and RedirectURI, then call GetAuthorizationURL with an AuthorizationURLParams object.

client, err := helix.NewClient(&helix.Options{
    ClientID:    "your-client-id",
    RedirectURI: "https://example.com/auth/callback",
})
if err != nil {
    // handle error
}

url := client.GetAuthorizationURL(&helix.AuthorizationURLParams{
    ResponseType: "code", // or "token"
    Scopes:       []string{"user:read:email"},
    State:        "some-state",
    ForceVerify:  false,
})

fmt.Printf("%s\n", url)

Use RefreshToken to refresh a device access token. You can retrieve the current refresh token from the client using GetRefreshToken().

client, err := helix.NewClient(&helix.Options{
    ClientID:     "your-client-id",
})
if err != nil {
    // handle error
}

// Get the refresh token from the client
refreshToken := client.GetRefreshToken() 

if refreshToken != "" {
  resp, err := client.RefreshToken(refreshToken)
  if err != nil {
      // handle error
  }

  fmt.Printf("%+v\n", resp)
}

Use RefreshUserAccessToken to obtain a new user access token using a provided refreshToken.

client, err := helix.NewClient(&helix.Options{
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
})
if err != nil {
    // handle error
}

refreshToken := "your-refresh-token"

resp, err := client.RefreshUserAccessToken(refreshToken)
if err != nil {
    // handle error
}

fmt.Printf("%+v\n", resp)