go-twitch/api/raids/start_a_raid.go

package raids

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/google/go-querystring/query"
	"go.fifitido.net/twitch/api/endpoint"
)

type StartARaidParams struct {
	// The ID of the broadcaster that’s sending the raiding party. This ID must match the user ID in the user access token.
	FromBroadcasterID string `url:"from_broadcaster_id"`

	// The ID of the broadcaster to raid.
	ToBroadcasterID string `url:"to_broadcaster_id"`
}

type StartARaidResponse struct {
	// A list that contains a single object with information about the pending raid.
	Data []struct {
		// The UTC date and time, in RFC3339 format, of when the raid was requested.
		CreatedAt string `json:"created_at"`
		// A Boolean value that indicates whether the channel being raided contains mature content.
		IsMature bool `json:"is_mature"`
	} `json:"data"`
}

// Raid another channel by sending the broadcaster’s viewers to the targeted channel.
//
// When you call the API from a chat bot or extension,
// the Twitch UX pops up a window at the top of the chat room that identifies the number of viewers in the raid.
// The raid occurs when the broadcaster clicks Raid Now or after the 90-second countdown expires.
//
// To determine whether the raid successfully occurred, you must subscribe to the Channel Raid event.
// For more information, see Get notified when a raid begins: https://dev.twitch.tv/docs/api/raids#get-notified-when-a-raid-begins
//
// To cancel a pending raid, use the Cancel a raid endpoint.
//
// Rate Limit: The limit is 10 requests within a 10-minute window.
//
// Requires a user access token that includes the channel:manage:raids scope.
func (r *Raids) StartARaid(ctx context.Context, params *StartARaidParams) (*StartARaidResponse, error) {
	v, _ := query.Values(params)

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint.Make(r.baseUrl, "raids", v), nil)
	if err != nil {
		return nil, err
	}

	res, err := r.client.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	statusOK := res.StatusCode >= 200 && res.StatusCode < 300
	if !statusOK {
		return nil, fmt.Errorf("failed to start a raid (%d)", res.StatusCode)
	}

	var data StartARaidResponse
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		return nil, err
	}

	return &data, nil
}