twitter

package module
v0.0.0-...-d727afa Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2023 License: MIT Imports: 7 Imported by: 2

README

twitter

Note: It is no longer practical or worthwhile for me to continue work on this library, as Twitter now charges $100 per month for minimal API access. I have therefore archived the repository.

This repository provides Go package that implements an experimental client for the Twitter API v2. It is no longer under active development.

This was an experiment, and is not ready for production use. In particular, test coverage is not nearly as good as it should be. There are replay tests using responses captured from the production service, but a lot of invariants remain unverified.

The documentation could also use more work. All the packages and exported types have doc comments, but working examples are lacking. Normal test-based examples are tricky because there is not (as far as I know) a good test double for the API.

API Index

Here is the current status of v2 API endpoint implementations.

Edits
  • DELETE 2/tweets/:id
  • PUT 2/tweets/:id/hidden
  • POST 2/users/:id/blocking
  • DELETE 2/users/:id/blocking/:other
  • POST 2/users/:id/bookmarks
  • DELETE 2/users/:id/bookmarks/:tid
  • POST 2/users/:id/following
  • DELETE 2/users/:id/following/:other
  • POST 2/users/:id/likes
  • DELETE 2/users/:id/likes/:tid
  • POST 2/users/:id/muting
  • DELETE 2/users/:id/muting/:other
  • POST 2/users/:id/pinned_lists
  • DELETE 2/users/:id/pinned_lists/:lid
  • POST 2/users/:id/retweets
  • DELETE 2/users/:id/retweets/:tid
Lists
  • GET 2/lists
  • POST 2/lists
  • DELETE 2/lists/:id
  • PUT 2/lists/:id
  • GET 2/lists/:id/followers
  • GET 2/lists/:id/members
  • POST 2/lists/:id/members
  • DELETE 2/lists/:id/members/:userid
  • GET 2/lists/:id/tweets
  • GET 2/lists/:id/pinned_lists
Rules
  • GET 2/tweets/search/stream/rules
  • POST 2/tweets/search/stream/rules
  • POST 2/tweets/search/stream/rules, dry_run=true
Tweets
  • GET 2/tweets
  • POST 2/tweets
  • GET 2/tweets/:id/liking_users
  • GET 2/tweets/:id/quote_tweets
  • GET 2/tweets/count/all (requires academic access)
  • GET 2/tweets/count/recent
  • GET 2/tweets/sample/stream
  • GET 2/tweets/search/all (requires academic access)
  • GET 2/tweets/search/recent
  • GET 2/tweets/search/stream
Users
  • GET 2/users
  • GET 2/users/:id/blocking
  • GET 2/users/:id/bookmarks
  • GET 2/users/:id/followed_lists
  • GET 2/users/:id/followers
  • GET 2/users/:id/following
  • GET 2/users/:id/liked_tweets
  • GET 2/users/:id/list_memberships
  • GET 2/users/:id/mentions
  • GET 2/users/:id/muting
  • GET 2/users/:id/owned_lists
  • GET 2/users/:id/retweeted_by
  • GET 2/users/:id/tweets
  • GET 2/users/by
  • GET 2/users/me

Documentation

Overview

Package twitter implements a client for the Twitter API v2. This package is in development and is not yet ready for production use.

Usage outline

The general structure of an API call is to first construct a query, then invoke that query with a context on a client: 

cli := twitter.NewClient(&jape.Client{
   Authorize: jape.BearerTokenAuthorizer(token),
})

ctx := context.Background()
rsp, err := users.LookupByName("jack", nil).Invoke(ctx, cli)
if err != nil {
   log.Fatalf("Request failed: %v", err)
} else if len(rsp.Users) == 0 {
   log.Fatal("No matches")
}
process(rsp.Users)

Packages

Package "types" contains the type and constant definitions for the API.

Queries to look up tweets by ID or username, to search recent tweets, and to search or sample streams of tweets are defined in package "tweets".

Queries to look up users by ID or user name are defined in package "users".

Queries to read or update search rules are defined in package "rules".

Queries to create, edit, delete, and show the contents of lists are defined in package "lists".

Index

Constants

View Source 
const (
	// BaseURL is the default base URL for the production Twitter API.
	// This is the default base URL if one is not given in the client.
	BaseURL = "https://api.twitter.com"

	// NextTokenParam is the name of the query parameter used to send a page
	// token to the service.
	NextTokenParam = "pagination_token"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Callback 

type Callback func(*Reply) error

A Callback function is invoked for each reply received in a stream. If the callback reports a non-nil error, the stream is terminated. If the error is anything other than ErrStopStreaming, it is reported to the caller.

type Client 

type Client jape.Client

A Client serves as a client for the Twitter API v2.

func NewClient 

func NewClient(cli *jape.Client) *Client

NewClient returns a new client for the Twitter API. If cli == nil, default client options are used targeting the production API at BaseURL.

func (*Client) Call 

func (c *Client) Call(ctx context.Context, req *jape.Request) (*Reply, error)

Call issues the specified API request and returns the decoded reply. Errors from Call have concrete type *jape.Error.

func (*Client) CallRaw 

func (c *Client) CallRaw(ctx context.Context, req *jape.Request) ([]byte, error)

CallRaw issues the specified API request and returns the raw response body without decoding. Errors from CallRaw have concrete type *jape.Error

func (*Client) Stream 

func (c *Client) Stream(ctx context.Context, req *jape.Request, f Callback) error

Stream issues the specified API request and streams results to the given callback. Errors from Stream have concrete type *jape.Error.

type Pagination 

type Pagination struct {
	ResultCount int    `json:"result_count"`
	NextToken   string `json:"next_token"`
}

Pagination records metadata about pagination of results.

type RateLimit 

type RateLimit struct {
	Ceiling   int       // rate limit ceiling for this endpoint
	Remaining int       // requests remaining in the current window
	Reset     time.Time // time of next window reset
}

RateLimit records metadata about API rate limits reported by the server.

type Reply 

type Reply struct {
	// The root reply object from a successful query.
	Data json.RawMessage `json:"data,omitempty"`

	// For expansions that generate attachments, a map of attachment type to
	// JSON arrays of attachment objects.
	Includes map[string]json.RawMessage `json:"includes,omitempty"`

	// Server metadata reported with search replies.
	Meta json.RawMessage `json:"meta,omitempty"`

	// Error details reported with lookup or search replies.
	Errors []*types.ErrorDetail `json:"errors,omitempty"`

	// Rate limit metadata reported by the server. If the server did not return
	// these data, this field will be nil.
	RateLimit *RateLimit `json:"-"`
}

A Reply is a wrapper for the reply object returned by successful calls to the Twitter API v2.

func (*Reply) IncludedMedia 

func (r *Reply) IncludedMedia() (types.Medias, error)

IncludedMedia decodes any media objects in the includes of r. It returns nil without error if there are no media inclusions.

func (*Reply) IncludedPlaces 

func (r *Reply) IncludedPlaces() (types.Places, error)

IncludedPlaces decodes any place objects in the includes of r. It returns nil without error if there are no place inclusions.

func (*Reply) IncludedPolls 

func (r *Reply) IncludedPolls() (types.Polls, error)

IncludedPolls decodes any poll objects in the includes of r. It returns nil without error if there are no poll inclusions.

func (*Reply) IncludedTweets 

func (r *Reply) IncludedTweets() (types.Tweets, error)

IncludedTweets decodes any tweet objects in the includes of r. It returns nil without error if there are no tweet inclusions.

func (*Reply) IncludedUsers 

func (r *Reply) IncludedUsers() (types.Users, error)

IncludedUsers decodes any user objects in the includes of r. It returns nil without error if there are no user inclusions.

Source Files

View all Source files

Directories

Path Synopsis
Package edit implements editing operations on tweets and tweet metadata.
 Package edit implements editing operations on tweets and tweet metadata.
internal
ocall
Package ocall carries some shared utility code for calling the Twitter API v1.1.
 Package ocall carries some shared utility code for calling the Twitter API v1.1.
otest
Package otest carries some shared setup code for unit tests.
 Package otest carries some shared setup code for unit tests.
otypes
Package jape implements a client for a JSON-based HTTP API.
 Package jape implements a client for a JSON-based HTTP API.
auth
Package auth supports OAuth 1.0a request signing.
 Package auth supports OAuth 1.0a request signing.
Package lists supports queries for lists.
 Package lists supports queries for lists.
Package olists implements queries that operate on lists using the Twitter API v1.1.
 Package olists implements queries that operate on lists using the Twitter API v1.1.
Package ostatus implements queries that operate on statuses (tweets) using the Twitter API v1.1.
 Package ostatus implements queries that operate on statuses (tweets) using the Twitter API v1.1.
Package query defines a structured builder for search query strings.
 Package query defines a structured builder for search query strings.
Package rules implements queries for reading and modifying the rules used by streaming search queries.
 Package rules implements queries for reading and modifying the rules used by streaming search queries.
Package tokens defines queries to obtain and authorize access tokens for the Twitter API.
 Package tokens defines queries to obtain and authorize access tokens for the Twitter API.
Package tweets supports queries for tweet lookup and search.
 Package tweets supports queries for tweet lookup and search.
Package types defines types for the Twitter API v2 object model.
 Package types defines types for the Twitter API v2 object model.
mkenum
Program mkenum constructs type enumerations for the optional fields that may be requested in Twitter API v2.
 Program mkenum constructs type enumerations for the optional fields that may be requested in Twitter API v2.
Package users supports queries for user lookup.
 Package users supports queries for user lookup.

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.