Teac

Twitch Elixir API Client For Twitch's REST and Websocket api.

Hex docs

Installation

This is currently a work in progress. While in development its highly recomended to use the github mix package as there are rapid changes coming in.

def deps do
  [
    {:teac, "~> 0.8.0"}
  ]
end

.env

export TWITCH_CLIENT_ID=""
export TWITCH_CLIENT_SECRET=""
export TWITCH_API_URI="https://api.twitch.tv/helix/"
export TWITCH_AUTH_URI="https://id.twitch.tv/oauth2/"
export TWITCH_OAUTH_CALLBACK_URI="http://example.com:4000/oauth/callbacks/twitch/"

config.ex

config :teac,
  client_id: System.get_env("TWITCH_CLIENT_ID"),
  client_secret: System.get_env("TWITCH_CLIENT_SECRET"),
  api_uri: System.get_env("TWITCH_API_URI"),
  auth_uri: System.get_env("TWITCH_AUTH_URI"),
  oauth_callback_uri: System.get_env("TWITCH_OAUTH_CALLBACK_URI")

Basic Usage

Create a client with your credentials, then pass it to any endpoint:

client = Teac.new(token: "some_auth_token", client_id: "your_client_id")

Teac.Api.Bits.Leaderboard.get(client)
Teac.Api.Chat.Color.get(client, user_id: "some_users_id")
Teac.Api.Polls.post(client, broadcaster_id: "123", title: "Best game?", choices: [...], duration: 300)

The client_id defaults to the value in your config if omitted:

client = Teac.new(token: "some_auth_token")

Check the endpoint documentation to determine whether it requires a user or app access token — some accept either, some are exclusive. https://dev.twitch.tv/docs/api/reference/

Example Application using this lib.

https://codeberg.org/FullStacking/teac_example

Using App Flow Auth token.

A genserver that fetches and mantains a valid auth token for Client Credential is provided. IE: Server To Server or noted as on any endpoint as Requires an app access token

def start(_type, _args) do
  children = [
    ...
    Teac.Oauth.ClientCredentialManager,
    ...
  ]
  opts = [strategy: :one_for_one, name: TeacExample.Supervisor]
  Supervisor.start_link(children, opts)
end

Assuming you provided your .env vars and have a running server, retrieve a token and build a client:

token = Teac.Oauth.ClientCredentialManager.get_token()
client = Teac.new(token: token)

get_token/0 always returns a valid app token. Pass the resulting client to any endpoint that accepts an app access token.

Developing

You will need the twitch cli tool. https://dev.twitch.tv/docs/cli/

Generate some mock data twitch mock-api generate -c 6
Set Env Variables from mock output export TWITCH_CLIENT_ID=your_client_idexport TWITCH_CLIENT_SECRET=your_client_secretexport TWITCH_API_URI="http://localhost:8080"
Start a mock twitch server. twitch mock-api serve

Assuming you have a Twitch mock server running to get the auth:

{:ok, [%{"ID" => client_id, "Secret" => client_secret}]} = Teac.MockApi.clients()

{:ok, %{"access_token" => access_token}} =
  Teac.MockAuth.fetch_app_access_token(client_id: client_id, client_secret: client_secret)

client = Teac.new(token: access_token, client_id: client_id)
{:ok, data} = Teac.Api.Bits.Cheermotes.get(client)

All endpoints take a %Teac.Client{} as the first argument, followed by an optional keyword list of endpoint-specific parameters.