# `Teac.WssClient`
[🔗](https://codeberg.org/FullStacking/teac)

# `assign_shard`

Assigns this WebSocket session to a conduit shard.

For conduit-based setups, call this instead of `subscribe/2` within 10 seconds
of `session_welcome`. Subscriptions are then created separately via
`Teac.Api.EventSub.Subscriptions.post/2` using the conduit ID as transport.

## Options

  * `:conduit_id` - required. The conduit to assign this session to.
  * `:shard_id` - required. The shard ID (zero-based string) to assign.

## Example

    Teac.WssClient.assign_shard(pid, conduit_id: "abc123", shard_id: "0")

# `child_spec`

Returns a child spec for use in a supervision tree.

The argument must be a two-element tuple of `{client, opts}`, where `opts`
is the same keyword list accepted by `start_link/2`. A `:name` opt is
recommended so the process can be looked up by name.

## Example

    children = [
      {Teac.WssClient, {client, handler: MyApp.TwitchHandler, name: MyApp.TwitchSocket}}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)

# `start_link`

Starts a WebSocket connection to the Twitch EventSub endpoint.

## Options

  * `:handler` - required. A module implementing `Teac.WssClient.Handler`.
  * `:handler_state` - optional initial state passed to handler callbacks. Defaults to `nil`.
  * `:keepalive_timeout_seconds` - optional integer (10–600). Tells Twitch how often to
    send keepalive frames. Defaults to Twitch's server-side default (10s).

## Example

    Teac.WssClient.start_link(client,
      handler: MyApp.TwitchHandler,
      keepalive_timeout_seconds: 30
    )

# `stop`

Gracefully closes the WebSocket connection with a normal close frame.

# `subscribe`

Creates an EventSub subscription tied to this WebSocket session.

Must be called after the connection is established (i.e. after `session_welcome`
has been received). Twitch requires at least one subscription within 10 seconds
of the welcome message or it closes the connection with code 4003.

## Options

  * `:type` - required. The subscription type, e.g. `"channel.follow"`.
  * `:version` - required. The subscription version, e.g. `"2"`.
  * `:condition` - required. A map of condition parameters for the subscription type.

## Example

    Teac.WssClient.subscribe(pid,
      type: "channel.follow",
      version: "2",
      condition: %{"broadcaster_user_id" => "123", "moderator_user_id" => "123"}
    )

# `unsubscribe`

Deletes an EventSub subscription by ID.

## Example

    Teac.WssClient.unsubscribe(pid, "2d9e9f1b-9b7a-4e6a-8f3c-1a2b3c4d5e6f")

---

*Consult [api-reference.md](api-reference.md) for complete listing*