gotwi

package module
v0.15.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2024 License: MIT Imports: 20 Imported by: 0

README

gotwi

Go Reference Twitter API v2 codecov

This is a library for using the Twitter API v2 in the Go language. (It is still under development).

Supported APIs

Twitter API Documentation | Docs | Twitter Developer Platform

Progress of supporting APIs:

Category Sub Category Endpoint
Tweets Tweet lookup GET /2/tweets
GET /2/tweets/:id
Manage Tweet POST /2/tweets
DELETE /2/tweets/:id
Timelines GET /2/users/:id/tweets
GET /2/users/:id/mentions
GET /2/users/:id/timelines/reverse_chronological
Search Tweets GET /2/tweets/search/recent
GET /2/tweets/search/all
Tweet counts GET /2/tweets/counts/recent
GET /2/tweets/counts/all
Filtered stream POST /2/tweets/search/stream/rules
GET /2/tweets/search/stream/rules
GET /2/tweets/search/stream
Volume streams GET /2/tweets/sample/stream
Retweets GET /2/users/:id/retweeted_by
POST /2/users/:id/retweets
DELETE /2/users/:id/retweets/:source_tweet_id
Likes GET /2/tweets/:id/liking_users
GET /2/tweets/:id/liked_tweets
POST /2/users/:id/likes
DELETE /2/users/:id/likes/:tweet_id
Hide replies PUT /2/tweets/:id/hidden
Quote Tweets GET /2/tweets/:id/quote_tweets
Bookmarks GET /2/users/:id/bookmarks
POST /2/users/:id/bookmarks
DELETE /2/users/:id/bookmarks/:tweet_id
Users User lookup GET /2/users
GET /2/users/:id
GET /2/users/by
GET /2/users/by/username
GET /2/users/by/me
Follows GET /2/users/:id/following
GET /2/users/:id/followers
POST /2/users/:id/following
DELETE /2/users/:source_user_id/following/:target_user_id
Blocks GET /2/users/:id/blocking
POST /2/users/:id/blocking
DELETE /2/users/:source_user_id/blocking/:target_user_id
Mutes GET /2/users/:id/muting
POST /2/users/:id/muting
DELETE /2/users/:source_user_id/muting/:target_user_id
Lists List lookup GET /2/lists/:id
GET /2/users/:id/owned_lists
Manage Lists POST /2/lists
DELETE /2/lists/:id
PUT /2/lists/:id
List Tweets lookup GET /2/lists/:id/tweets
List members GET /2/users/:id/list_memberships
GET /2/lists/:id/members
POST /2/lists/:id/members
DELETE /2/lists/:id/members/:user_id
List follows GET /2/lists/:id/followers
GET /2/users/:id/followed_lists
POST /2/users/:id/followed_lists
DELETE /2/users/:id/followed_lists/:list_id
Pinned Lists GET /2/users/:id/pinned_lists
POST /2/users/:id/pinned_lists
DELETE /2/users/:id/pinned_lists/:list_id
Spaces Spaces Lookup GET /2/spaces/:id
GET /2/spaces
GET /2/spaces/by/creator_ids
GET /2/spaces/:id/buyers
GET /2/spaces/:id/tweets
Search Spaces GET /2/spaces/search
Compliance Batch compliance GET /2/compliance/jobs/:id
GET /2/compliance/jobs
POST /2/compliance/jobs

How to use

Prepare

Set the API key and API key secret to environment variables.

export GOTWI_API_KEY='your-api-key'
export GOTWI_API_KEY_SECRET='your-api-key-secret'

Request with OAuth 1.0a User Context

With this authentication method, each operation will be performed as the authenticated Twitter account. For example, you can tweet as that account, or retrieve accounts that are blocked by that account.

Example: Get your own information.
package main

import (
	"context"
	"fmt"

	"github.com/NHypocrite/gotwi"
	"github.com/NHypocrite/gotwi/fields"
	"github.com/NHypocrite/gotwi/user/userlookup"
	"github.com/NHypocrite/gotwi/user/userlookup/types"
)

func main() {
	in := &gotwi.NewClientInput{
		AuthenticationMethod: gotwi.AuthenMethodOAuth1UserContext,
		OAuthToken:           "your-access-token",
		OAuthTokenSecret:     "your-access-token-secret",
	}

	c, err := gotwi.NewClient(in)
	if err != nil {
		fmt.Println(err)
		return
	}

	p := &types.GetMeInput{
		Expansions: fields.ExpansionList{
			fields.ExpansionPinnedTweetID,
		},
		UserFields: fields.UserFieldList{
			fields.UserFieldCreatedAt,
		},
		TweetFields: fields.TweetFieldList{
			fields.TweetFieldCreatedAt,
		},
	}

	u, err := userlookup.GetMe(context.Background(), c, p)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println("ID:          ", gotwi.StringValue(u.Data.ID))
	fmt.Println("Name:        ", gotwi.StringValue(u.Data.Name))
	fmt.Println("Username:    ", gotwi.StringValue(u.Data.Username))
	fmt.Println("CreatedAt:   ", u.Data.CreatedAt)
	if u.Includes.Tweets != nil {
		for _, t := range u.Includes.Tweets {
			fmt.Println("PinnedTweet: ", gotwi.StringValue(t.Text))
		}
	}
}

go run main.go

You will get the output like following.

ID:           581780917
Name:         michimani Lv.873
Username:     michimani210
CreatedAt:    2012-05-16 12:07:04 +0000 UTC
PinnedTweet:  OpenAI API の Function Calling を使って自然言語で AWS リソースを作成してみる
Example: Tweet with poll.
package main

import (
	"context"
	"fmt"

	"github.com/NHypocrite/gotwi"
	"github.com/NHypocrite/gotwi/tweet/managetweet"
	"github.com/NHypocrite/gotwi/tweet/managetweet/types"
)

func main() {
	in := &gotwi.NewClientInput{
		AuthenticationMethod: gotwi.AuthenMethodOAuth1UserContext,
		OAuthToken:           "your-access-token",
		OAuthTokenSecret:     "your-access-token-secret",
	}

	c, err := gotwi.NewClient(in)
	if err != nil {
		fmt.Println(err)
		return
	}

	p := &types.CreateInput{
		Text: gotwi.String("This is a test tweet with poll."),
		Poll: &types.CreateInputPoll{
			DurationMinutes: gotwi.Int(5),
			Options: []string{
				"Cyan",
				"Magenta",
				"Yellow",
				"Key plate",
			},
		},
	}

	res, err := managetweet.Create(context.Background(), c, p)
	if err != nil {
		fmt.Println(err.Error())
		return
	}

	fmt.Printf("[%s] %s\n", gotwi.StringValue(res.Data.ID), gotwi.StringValue(res.Data.Text))
}

go run main.go

You will get the output like following.

[1462813519607263236] This is a test tweet with poll.

Request with OAuth 2.0 Bearer Token

This authentication method allows only read-only access to public information.

Example: Get a user by user name.

⚠ This example only works with Twitter API v2 Basic or Pro plan. see details: Developers Portal

package main

import (
	"context"
	"fmt"

	"github.com/NHypocrite/gotwi"
	"github.com/NHypocrite/gotwi/fields"
	"github.com/NHypocrite/gotwi/user/userlookup"
	"github.com/NHypocrite/gotwi/user/userlookup/types"
)

func main() {
	c, err := gotwi.NewClient(&gotwi.NewClientInput{
		AuthenticationMethod: gotwi.AuthenMethodOAuth2BearerToken,
	})
	if err != nil {
		fmt.Println(err)
		return
	}

	p := &types.GetByUsernameInput{
		Username: "michimani210",
		Expansions: fields.ExpansionList{
			fields.ExpansionPinnedTweetID,
		},
		UserFields: fields.UserFieldList{
			fields.UserFieldCreatedAt,
		},
		TweetFields: fields.TweetFieldList{
			fields.TweetFieldCreatedAt,
		},
	}

	u, err := userlookup.GetByUsername(context.Background(), c, p)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println("ID:          ", gotwi.StringValue(u.Data.ID))
	fmt.Println("Name:        ", gotwi.StringValue(u.Data.Name))
	fmt.Println("Username:    ", gotwi.StringValue(u.Data.Username))
	fmt.Println("CreatedAt:   ", u.Data.CreatedAt)
	if u.Includes.Tweets != nil {
		for _, t := range u.Includes.Tweets {
			fmt.Println("PinnedTweet: ", gotwi.StringValue(t.Text))
		}
	}
}

go run main.go

You will get the output like following.

ID:           581780917
Name:         michimani Lv.861
Username:     michimani210
CreatedAt:    2012-05-16 12:07:04 +0000 UTC
PinnedTweet:  真偽をハッキリしたい西城秀樹「ブーリアン、ブーリアン」

Request with OAuth 2.0 Authorization Code with PKCE

If you already have a pre-generated access token (e.g. OAuth 2.0 Authorization Code with PKCE), you can use NewClientWithAccessToken() function to generate a Gotwi client.

in := &gotwi.NewClientWithAccessTokenInput{
	AccessToken: "your-access-token",
}

c, err := gotwi.NewClientWithAccessToken(in)
if err != nil {
	// error handling
}

See below for information on which authentication methods are available for which endpoints.

Twitter API v2 authentication mapping | Docs | Twitter Developer Platform

Error handling

Each function that calls the Twitter API (e.g. retweet.ListUsers()) may return an error for some reason. If the error is caused by the Twitter API returning a status other than 2XX, you can check the details by doing the following.

res, err := retweet.ListUsers(context.Background(), c, p)
if err != nil {
	fmt.Println(err)

	// more error information
	ge := err.(*gotwi.GotwiError)
	if ge.OnAPI {
		fmt.Println(ge.Title)
		fmt.Println(ge.Detail)
		fmt.Println(ge.Type)
		fmt.Println(ge.Status)
		fmt.Println(ge.StatusCode)

		for _, ae := range ge.APIErrors {
			fmt.Println(ae.Message)
			fmt.Println(ae.Label)
			fmt.Println(ae.Parameters)
			fmt.Println(ae.Code)
			fmt.Println(ae.Code.Detail())
		}

		if ge.RateLimitInfo != nil {
			fmt.Println(ge.RateLimitInfo.Limit)
			fmt.Println(ge.RateLimitInfo.Remaining)
			fmt.Println(ge.RateLimitInfo.ResetAt)
		}
	}
}

More examples

See _examples directory.

Licence

MIT

Author

michimani210

Documentation

Index

Constants

View Source 
const (
	APIKeyEnvName       = "GOTWI_API_KEY"
	APIKeySecretEnvName = "GOTWI_API_KEY_SECRET"
)
View Source 
const (
	AuthenMethodOAuth1UserContext = "OAuth 1.0a User context"
	AuthenMethodOAuth2BearerToken = "OAuth 2.0 Bearer token"
)
View Source 
const (
	OAuthVersion10               = "1.0"
	OAuthSignatureMethodHMACSHA1 = "HMAC-SHA1"
)
View Source 
const OAuth2TokenEndpoint = "https://api.twitter.com/oauth2/token"

Variables

This section is empty.

Functions

func Bool 

func Bool(b bool) *bool

func BoolValue 

func BoolValue(b *bool) bool

func Float64 

func Float64(f float64) *float64

func Float64Value 

func Float64Value(f *float64) float64

func GenerateBearerToken 

func GenerateBearerToken(c IClient, apiKey, apiKeySecret string) (string, error)

func Int 

func Int(i int) *int

func IntValue 

func IntValue(i *int) int

func String 

func String(s string) *string

func StringValue 

func StringValue(s *string) string

func Time 

func Time(t time.Time) *time.Time

func TimeValue 

func TimeValue(t *time.Time) time.Time

Types

type AuthenticationMethod 

type AuthenticationMethod string

func (AuthenticationMethod) Valid 

func (a AuthenticationMethod) Valid() bool

type Client 

type Client struct {
	Client *http.Client
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(in *NewClientInput) (*Client, error)

func NewClientWithAccessToken 

func NewClientWithAccessToken(in *NewClientWithAccessTokenInput) (*Client, error)

func (*Client) AccessToken 

func (c *Client) AccessToken() string

func (*Client) AuthenticationMethod 

func (c *Client) AuthenticationMethod() AuthenticationMethod

func (*Client) CallAPI 

func (c *Client) CallAPI(ctx context.Context, endpoint, method string, p util.Parameters, i util.Response) error

func (*Client) Exec 

func (c *Client) Exec(req *http.Request, i util.Response) (*resources.Non2XXError, error)

func (*Client) IsReady 

func (c *Client) IsReady() bool

func (*Client) OAuthConsumerKey 

func (c *Client) OAuthConsumerKey() string

func (*Client) OAuthToken 

func (c *Client) OAuthToken() string

func (*Client) SetAccessToken 

func (c *Client) SetAccessToken(v string)

func (*Client) SetAuthenticationMethod 

func (c *Client) SetAuthenticationMethod(v AuthenticationMethod)

func (*Client) SetOAuthConsumerKey 

func (c *Client) SetOAuthConsumerKey(v string)

func (*Client) SetOAuthToken 

func (c *Client) SetOAuthToken(v string)

func (*Client) SetSigningKey 

func (c *Client) SetSigningKey(v string)

func (*Client) SigningKey 

func (c *Client) SigningKey() string

type ClientResponse 

type ClientResponse struct {
	StatusCode int
	Status     string
	Error      *resources.Non2XXError
	Body       []byte
	Response   util.Response
}

type CreateOAuthSignatureInput 

type CreateOAuthSignatureInput struct {
	HTTPMethod       string
	RawEndpoint      string
	OAuthConsumerKey string
	OAuthToken       string
	SigningKey       string
	ParameterMap     map[string]string
}

type CreateOAuthSignatureOutput 

type CreateOAuthSignatureOutput struct {
	OAuthNonce           string
	OAuthSignatureMethod string
	OAuthTimestamp       string
	OAuthVersion         string
	OAuthSignature       string
}

func CreateOAuthSignature 

func CreateOAuthSignature(in *CreateOAuthSignatureInput) (*CreateOAuthSignatureOutput, error)

type Endpoint 

type Endpoint string

func (Endpoint) Detail 

func (e Endpoint) Detail() (*EndpointInfo, error)

func (Endpoint) String 

func (e Endpoint) String() string

type EndpointInfo 

type EndpointInfo struct {
	Raw                      string
	Base                     string
	EncodedQueryParameterMap map[string]string
}

type GotwiError 

type GotwiError struct {
	OnAPI bool
	resources.Non2XXError
	// contains filtered or unexported fields
}

func (*GotwiError) Error 

func (e *GotwiError) Error() string

func (*GotwiError) Unwrap 

func (e *GotwiError) Unwrap() error

type IClient 

type IClient interface {
	Exec(req *http.Request, i util.Response) (*resources.Non2XXError, error)
	IsReady() bool
	AccessToken() string
	AuthenticationMethod() AuthenticationMethod
	OAuthToken() string
	OAuthConsumerKey() string
	SigningKey() string
}

type NewClientInput 

type NewClientInput struct {
	HTTPClient           *http.Client
	AuthenticationMethod AuthenticationMethod
	OAuthToken           string
	OAuthTokenSecret     string
	Debug                bool
}

type NewClientWithAccessTokenInput 

type NewClientWithAccessTokenInput struct {
	HTTPClient  *http.Client
	AccessToken string
}

type OAuth2TokenResponse 

type OAuth2TokenResponse struct {
	TokenType   string `json:"token_type"`
	AccessToken string `json:"access_token"`
}

func (OAuth2TokenResponse) HasPartialError 

func (o OAuth2TokenResponse) HasPartialError() bool

type StreamClient 

type StreamClient[T util.Response] struct {
	// contains filtered or unexported fields
}

func (*StreamClient[T]) Read 

func (s *StreamClient[T]) Read() (T, error)

func (*StreamClient[T]) Receive 

func (s *StreamClient[T]) Receive() bool

func (*StreamClient[T]) Stop 

func (s *StreamClient[T]) Stop()

type TypedClient 

type TypedClient[T util.Response] struct {
	Client *http.Client
	// contains filtered or unexported fields
}

func NewTypedClient 

func NewTypedClient[T util.Response](c *Client) *TypedClient[T]

func (*TypedClient[T]) AccessToken 

func (c *TypedClient[T]) AccessToken() string

func (*TypedClient[T]) AuthenticationMethod 

func (c *TypedClient[T]) AuthenticationMethod() AuthenticationMethod

func (*TypedClient[T]) CallStreamAPI 

func (c *TypedClient[T]) CallStreamAPI(ctx context.Context, endpoint, method string, p util.Parameters) (*StreamClient[T], error)

func (*TypedClient[T]) Exec 

func (c *TypedClient[T]) Exec(req *http.Request, i util.Response) (*resources.Non2XXError, error)

func (*TypedClient[T]) ExecStream 

func (c *TypedClient[T]) ExecStream(req *http.Request) (*http.Response, *resources.Non2XXError, error)

func (*TypedClient[T]) IsReady 

func (c *TypedClient[T]) IsReady() bool

func (*TypedClient[T]) OAuthConsumerKey 

func (c *TypedClient[T]) OAuthConsumerKey() string

func (*TypedClient[T]) OAuthToken 

func (c *TypedClient[T]) OAuthToken() string

func (*TypedClient[T]) SigningKey 

func (c *TypedClient[T]) SigningKey() string

Source Files

View all Source files

Directories

Path Synopsis
compliance
batchcompliance
batchcompliance/types
internal
gotwierrors
util
list
listfollow
listfollow/types
listlookup
listlookup/types
listmember
listmember/types
listtweetlookup
listtweetlookup/types
managelist
managelist/types
pinnedlist
pinnedlist/types
space
searchspace
searchspace/types
spacelookup
spacelookup/types
tweet
bookmark
bookmark/types
filteredstream
filteredstream/types
hidereply
hidereply/types
like
like/types
managetweet
managetweet/types
quotetweet
quotetweet/types
retweet
retweet/types
searchtweet
searchtweet/types
timeline
timeline/types
tweetcount
tweetcount/types
tweetlookup
tweetlookup/types
volumestream
volumestream/types
user
block
block/types
follow
follow/types
mute
mute/types
userlookup
userlookup/types

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.