transistor

package module
v0.0.0-...-6871d04 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2022 License: MIT Imports: 15 Imported by: 0

README

Go Report Card GoDoc

Transistor.fm Go SDK

Done:

Needs tests:

Documentation

Overview

Package transistor provides a Go SDK to the transistor.fm JSON:API interface described at https://developers.transistor.fm/

Index

Constants

View Source
const DefaultURL = "https://api.transistor.fm/v1"

DefaultURL is the default URL. It may be overridden with Client#SetURL.

Variables

This section is empty.

Functions

This section is empty.

Types

type AnalyticsQuery

type AnalyticsQuery struct {
	StartDate time.Time           `url:"start_date,omitempty,format=02-01-2006"`
	EndDate   time.Time           `url:"end_date,omitempty,format=02-01-2006"`
	Fields    map[string][]string `url:"fields,omitempty"`
	Include   []string            `url:"include,omitempty"`
}

AnalyticsQuery is a query for ShowAnalytics, EpisodeAnalytics, or AllEpisodesAnalytics.

See https://developers.transistor.fm/#analytics

type AudioUpload

type AudioUpload struct {
	ID string `json:"id"`
	// UploadURL is the endpoint URL to upload your audio file using HTTP PUT.
	UploadURL string `json:"upload_url"`
	// ContentType ist he content type of the file to upload. audio/mpeg,
	// audio/wav, etc.
	ContentType string `json:"content_type"`
	// Expiration time of this link in seconds.
	ExpiresIn int `json:"expires_in"`
	// AudioURL is the URL of your audio file after uploading is complete,
	// to be used when creating or updating an episode.
	AudioURL string `json:"audio_url"`
}

AudioUpload represents an authorized audio upload resource.

See https://developers.transistor.fm/#AudioUpload

func (*AudioUpload) UnmarshalJSON

func (a *AudioUpload) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a client connection to the Transistor.fm API.

func New

func New(baseURL, apiKey string) (*Client, error)

New returns a new Transistor.fm API client instance. If baseURL is omitted, DefaultURL is used.

func (*Client) AllEpisodesAnalytics

func (c *Client) AllEpisodesAnalytics(ctx context.Context, showID string, query ...*AnalyticsQuery) (*EpisodesAnalytics, error)

AllEpisodesAnalytics retrieves analytics of downloads for all episodes of a podcast. Defaults to the last 7 days.

Only the first query value is honored.

See https://developers.transistor.fm/#analytics

func (*Client) AuthorizeUpload

func (c *Client) AuthorizeUpload(ctx context.Context, filename string) (*AudioUpload, error)

AuthorizeUpload authorizes a URL for uploading an audio file to be used when creating or updating an episode, if you don't already have a URL for an audio file.

See https://developers.transistor.fm/#episodes

func (*Client) CreateEpisode

func (c *Client) CreateEpisode(ctx context.Context, episode *Episode) (*Episode, error)

CreateEpisode create a new draft episode for the specified show. Note that publishing an episode involves a separate endpoint.

See https://developers.transistor.fm/#episodes

func (*Client) CreateSubscriber

func (c *Client) CreateSubscriber(ctx context.Context, subscriber *Subscriber) (*Subscriber, error)

CreateSubscriber adds a single subscriber to a private podcast, and send an optional instructional email.

See https://developers.transistor.fm/#subscribers

func (*Client) CreateSubscribers

func (c *Client) CreateSubscribers(ctx context.Context, showID string, skipEmail bool, email ...string) ([]*Subscriber, error)

CreateSubscribers adds a batch of multiple subscribers to a private podcast, and sends them optional instructional emails.

See https://developers.transistor.fm/#subscribers

func (*Client) DeleteSubscriber

func (c *Client) DeleteSubscriber(ctx context.Context, subscriberID string) (*Subscriber, error)

DeleteSubscriber removes a single private podcast subscriber and revokes their access to the podcast.

See https://developers.transistor.fm/#subscribers

func (*Client) DeleteSubscriberEmail

func (c *Client) DeleteSubscriberEmail(ctx context.Context, showID, email string) (*Subscriber, error)

DeleteSubscriberEmail removes a single private podcast subscriber by email and revokes their access to the podcast.

showID may be the show ID or slug.

See https://developers.transistor.fm/#subscribers

func (*Client) Episode

func (c *Client) Episode(ctx context.Context, id string) (*Episode, error)

Episode retrieves a single podcast episode.

See https://developers.transistor.fm/#episodes

func (*Client) EpisodeAnalytics

func (c *Client) EpisodeAnalytics(ctx context.Context, episodeID string, query ...*AnalyticsQuery) (*EpisodeAnalytics, error)

EpisodeAnalytics retrieves analytics of downloads for a single episode. Defaults to the last 14 days.

Only the first query value is honored.

See https://developers.transistor.fm/#analytics

func (*Client) Episodes

func (c *Client) Episodes(ctx context.Context, query *EpisodesQuery) ([]*Episode, *Meta, error)

Episodes retrieves a paginated list of episodes in descending order by published date.

See https://developers.transistor.fm/#episodes

func (*Client) PublishEpisode

func (c *Client) PublishEpisode(ctx context.Context, id, status string, publishAt time.Time) (*Episode, error)

PublishEpisode pulibshes a single episode now or in the past, schedule for the future, or revert to a draft.

publishAt defaults to now.

See https://developers.transistor.fm/#episodes

func (*Client) SetClient

func (c *Client) SetClient(client *http.Client)

SetClient sets a custom HTTP client.

func (*Client) Show

func (c *Client) Show(ctx context.Context, id string) (*Show, error)

Show retrieves a single show (podcast).

See https://developers.transistor.fm/#shows

func (*Client) ShowAnalytics

func (c *Client) ShowAnalytics(ctx context.Context, showID string, query ...*AnalyticsQuery) (*ShowAnalytics, error)

ShowAnalytics retrieves analytics of downloads per day for an entire podcast. Defaults to the4 last 14 days.

Only the first query, if provided, is honored.

See https://developers.transistor.fm/#analytics

func (*Client) Shows

func (c *Client) Shows(ctx context.Context, query *ShowsQuery) ([]*Show, *Meta, error)

Shows retrieves a paginated list of shows in descending order by updated date.

See https://developers.transistor.fm/#shows

func (*Client) SubscribeWebhook

func (c *Client) SubscribeWebhook(ctx context.Context, showID, event, url string) (*Webhook, error)

SubscribeWebhook subscribes to a webhook with the given event name and show.

See https://developers.transistor.fm/#webhooks

func (*Client) Subscriber

func (c *Client) Subscriber(ctx context.Context, subscriberID string) (*Subscriber, error)

Subscriber retrieves a single private podcast subscriber.

See https://developers.transistor.fm/#subscribers

func (*Client) Subscribers

func (c *Client) Subscribers(ctx context.Context, query *SubscribersQuery) ([]*Subscriber, *Meta, error)

Subscribers retrieves a list of all subscribers for a single private podcast.

See https://developers.transistor.fm/#subscribers

func (*Client) UnsubscribeWebhook

func (c *Client) UnsubscribeWebhook(ctx context.Context, webhookID string) (*Webhook, error)

UnsubscribeWebhook unsubscribes from the specified webhook.

See https://developers.transistor.fm/#webhooks

func (*Client) UpdateEpisode

func (c *Client) UpdateEpisode(ctx context.Context, episode *Episode) (*Episode, error)

UpdateEpisode Update a single podcast episode. Note that publishing or unpublishing an episode involves a separate endpoint.

See https://developers.transistor.fm/#episodes

func (*Client) UpdateShow

func (c *Client) UpdateShow(ctx context.Context, show *Show) (*Show, error)

UpdateShow updates a show with any of the set attributes. show.ID or show.Slug must be set.

See https://developers.transistor.fm/#shows

func (*Client) UpdateSubscriber

func (c *Client) UpdateSubscriber(ctx context.Context, subscriber *Subscriber) (*Subscriber, error)

UpdateSubscriber updates a single private podcast subscriber.

See https://developers.transistor.fm/#subscribers

func (*Client) User

func (c *Client) User(ctx context.Context) (*User, error)

User retrieves details of the user account that is authenticating to the API.

See https://developers.transistor.fm/#root

func (*Client) Webhooks

func (c *Client) Webhooks(ctx context.Context, showID string) ([]*Webhook, error)

Webhooks retrieve a list of webhooks for a show.

See https://developers.transistor.fm/#webhooks

type Downloads

type Downloads struct {
	Date      time.Time `json:"date"`
	Downloads int64     `json:"downloads"`
}

Downloads reports the number of downloads on a given day.

func (*Downloads) UnmarshalJSON

func (d *Downloads) UnmarshalJSON(p []byte) error

UnmarshalJSON handles custom unmarshaling for

type Episode

type Episode struct {
	ID           string `json:"id" url:"-"`
	AlternateURL string `json:"alternate_url" url:"alternate_url,omitempty"`
	// TranscriptURL is the URL To the transcript text, used for reading a
	// transcript.
	TranscriptURL string `json:"transcript_url" url:"-"`
	// TranscriptText is the full text of the transcript, only used for setting
	// the transcript. Use TranscriptURL to read the existing transcript.
	TranscriptText  string    `json:"-" url:"transcript_text"`
	AudioProcessing bool      `json:"audio_processing" url:"-"`
	Author          string    `json:"author" url:"author,omitempty"`
	CreatedAt       time.Time `json:"created_at" url:"-"`
	Description     string    `json:"description" url:"description,omitempty"`
	// Duration of the episode in seconds.
	Duration int `json:"duration" url:"-"`
	// FormattedDuration is the duration of episode in minutes and seconds.
	// e.g. 34:12
	FormattedDuration  string `json:"duration_in_mmss" url:"-"`
	EmailNotifications string `json:"email_notifications" url:"email_notifications,omitempty"`
	EmbedHTML          string `json:"embed_html" url:"-"`
	EmbedHTMLDark      string `json:"embed_html_dark" url:"-"`
	Explicit           bool   `json:"explicit" url:"explicit,omitempty"`
	// Formatted version of the PublishedAt field.
	FormattedPublishedAt string `json:"formatted_published_at" url:"-"`
	// FormattedSummary is the formatted episode summary short description.
	FormattedSummary string `json:"formatted_summary" url:"-"`
	ImageURL         string `json:"image_url" url:"image_url,omitempty"`
	Keywords         string `json:"keywords" url:"keywords,omitempty"`
	// MediaURL is the URL to the trackable audio MP3 file.
	MediaURL string `json:"media_url" url:"-"`
	// Number is the episode number.
	Number int `json:"number" url:"number,omitempty"`
	// PublishedAt is the time the episode was published, in the podcast's
	// time zone.
	PublishedAt time.Time `json:"published_at" url:"-"`
	// Season number.
	Season    int       `json:"season" url:"season,omitempty"`
	ShareURL  string    `json:"share_url" url:"-"`
	Status    string    `json:"status" url:"-"`
	Summary   string    `json:"summary" url:"summary,omitempty"`
	Title     string    `json:"title" url:"title,omitempty"`
	Type      string    `json:"type" url:"type,omitempty"`
	UpdatedAt time.Time `json:"updated_at" url:"-"`
	// ShowID is the id of the show this episode belongs to.
	ShowID string `json:"-" url:"show_id,omitempty"`
}

Episode represents a single podcast episode.

See https://developers.transistor.fm/#Episode

func (*Episode) UnmarshalJSON

func (e *Episode) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type EpisodeAnalytics

type EpisodeAnalytics struct {
	ID        string      `json:"id"`
	Downloads []Downloads `json:"downloads"`
	StartDate time.Time   `json:"start_date"`
	EndDate   time.Time   `json:"end_date"`
}

EpisodeAnalytics reports download analytics per day for a single episode.

See https://developers.transistor.fm/#EpisodeAnalytics

func (*EpisodeAnalytics) UnmarshalJSON

func (a *EpisodeAnalytics) UnmarshalJSON(p []byte) error

UnmarshalJSON handles the backwards parsing of dates in the Downloads slice.

type EpisodesAnalytics

type EpisodesAnalytics struct {
	ID        string             `json:"id"`
	Episodes  []EpisodeAnalytics `json:"episodes"`
	StartDate time.Time          `json:"start_date"`
	EndDate   time.Time          `json:"end_date"`
	ShowID    string             `json:"-"`
}

EpisodesAnalytics is a report of download analytics per day for all episodes of a single podcast.

See https://developers.transistor.fm/#EpisodesAnalytics

func (*EpisodesAnalytics) UnmarshalJSON

func (a *EpisodesAnalytics) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type EpisodesQuery

type EpisodesQuery struct {
	ShowID     string `url:"show_id"`
	Query      string `url:"query,omitempty"`
	Status     string `url:"status"`
	Pagination `url:"pagination"`
	Fields     map[string][]string `url:"fields"`
}

EpisodesQuery is a query for episodes.

type Error

type Error struct {

	// ID is a unique identifier for this particular occurrence of a problem.
	ID string `json:"id,omitempty"`
	// Title is a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
	Title string `json:"title,omitempty"`
	// Detail is a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
	Detail string `json:"detail,omitempty"`
	// Status is the HTTP status code applicable to this problem.
	Status string `json:"status,omitempty"`
	// Code is an application-specific error code, expressed as a string value.
	Code string `json:"code,omitempty"`
	// Meta is an object containing non-standard meta-information about the error.
	Meta *map[string]interface{} `json:"meta,omitempty"`
	// contains filtered or unexported fields
}

Error represents an API error.

This is a copy of jsonapi.ErrorObject, with minor customizations.

func (*Error) Error

func (e *Error) Error() string

func (*Error) HTTPStatus

func (e *Error) HTTPStatus() int

HTTPStatus returns the HTTP status of the response that returned this error.

type Meta

type Meta struct {
	CurrentPage int `json:"currentPage"`
	TotalPages  int `json:"totalPages"`
	TotalCount  int `json:"totalCount"`
}

Meta represents metadata about a response.

type Pagination

type Pagination struct {
	// Page is the page number.
	Page int `url:"page,omitempty"`
	// Per is the number of resources per page.
	Per int `url:"per,omitempty"`
}

Pagination represents the pagination arguments understood by the Transistor.fm API.

type Show

type Show struct {
	ID                 string    `json:"id" url:"-"`
	AmazonMusicURL     string    `json:"amazon_music" url:"-"`
	ApplePodcastsURL   string    `json:"apple_podcasts" url:"-"`
	Author             string    `json:"author" url:"author,omitempty"`
	CastboxURL         string    `json:"castbox" url:"-"`
	CastroURL          string    `json:"castro" url:"-"`
	Category           string    `json:"category" url:"category,omitempty"`
	Copyright          string    `json:"copyright" url:"copyright,omitempty"`
	CreatedAt          time.Time `json:"created_at" url:"-"`
	DeezerURL          string    `json:"deezer" url:"-"`
	Description        string    `json:"description" url:"description,omitempty"`
	EmailNotifications bool      `json:"email_notifications" url:"-"`
	Explicit           bool      `json:"explicit" url:"explicit,omitempty"`
	FeedURL            string    `json:"feed_url" url:"-"`
	GooglePodcastsURL  string    `json:"google_podcasts" url:"-"`
	IHeartRadioURL     string    `json:"iHeartRadio" url:"-"`
	ImageURL           string    `json:"image_url" url:"-"`
	// Comma-separated list of keywords.
	Keywords string `json:"keywords"  url:"keywords,omitempty"`
	// Podcast's spoken language
	Language              string `json:"language" url:"language,omitempty"`
	MultipleSeasons       bool   `json:"multiple_seasons" url:"-"`
	OvercastURL           string `json:"overcast" url:"-"`
	OwnerEmail            string `json:"owner_email" url:"owner_email,omitempty"`
	PandoraURL            string `json:"pandora" url:"-"`
	PasswordProtectedFeed bool   `json:"password_protected_feed" url:"-"`
	PlayerFMURL           string `json:"player_FM" url:"-"`
	// Playlist embed player episode limit.
	PlaylistLimit     int       `json:"playlist_limit" url:"-"`
	PocketCastsURL    string    `json:"pocket_casts" url:"-"`
	Private           bool      `json:"private" url:"-"`
	RadioPublicURL    string    `json:"radioPublic" url:"-"`
	SecondaryCategory string    `json:"secondary_category" url:"secondary_category,omitempty"`
	ShowType          string    `json:"show_type" url:"show_type,omitempty"`
	Slug              string    `json:"slug" url:"-"`
	SoundcloudURL     string    `json:"soundcloud" url:"-"`
	SpotifyURL        string    `json:"spotify" url:"-"`
	StitcherURL       string    `json:"stitcher" url:"-"`
	TimeZone          string    `json:"time_zone" url:"time_zone,omitempty"`
	Title             string    `json:"title" url:"title,omitempty"`
	TuneInURL         string    `json:"tuneIn" url:"-"`
	UpdatedAt         time.Time `json:"updated_at" url:"-"`
	WebsiteURL        string    `json:"website" url:"website,omitempty"`
	Episodes          []string  `json:"-"`
}

Show represents a show.

See https://developers.transistor.fm/#Show

func (*Show) UnmarshalJSON

func (s *Show) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type ShowAnalytics

type ShowAnalytics struct {
	ID        string      `json:"id"`
	Downloads []Downloads `json:"downloads"`
	ShowID    string      `json:"-"`
	StartDate time.Time   `json:"start_date"`
	EndDate   time.Time   `json:"end_date"`
}

ShowAnalytics reports download analytics per day for a single podcast.

See https://developers.transistor.fm/#ShowAnalytics

func (*ShowAnalytics) UnmarshalJSON

func (s *ShowAnalytics) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type ShowsQuery

type ShowsQuery struct {
	// Private filters for private shows.
	Private    bool   `url:"private,omitempty"`
	Query      string `url:"query,omitempty"`
	Pagination `url:"pagination,omitempty"`
	Fields     map[string][]string `url:"fields,omitempty"`
}

ShowsQuery is a query for shows.

type Subscriber

type Subscriber struct {
	ID               string    `json:"id" url:"-"`
	CreatedAt        time.Time `json:"created_at" url:"-"`
	Email            string    `json:"email" url:"email"`
	FeedURL          string    `json:"feed_url" url:"-"`
	HasDownloads     bool      `json:"has_downloads" url:"-"`
	LastNotifiedAt   time.Time `json:"last_notified_at" url:"-"`
	Status           string    `json:"status" url:"-"`
	SubscribeURL     string    `json:"subscribe_url" url:"-"`
	UpdatedAt        time.Time `json:"updated_at" url:"-"`
	ShowID           string    `json:"-" url:"show_id,omitempty"`
	SkipWelcomeEmail string    `json:"-" url:"skip_welcome_email,omitempty"`
}

Subscriber is an individual subscriber record for a private podcast.

See https://developers.transistor.fm/#Subscriber

func (*Subscriber) UnmarshalJSON

func (s *Subscriber) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type SubscribersQuery

type SubscribersQuery struct {
	ShowID     string `url:"show_id"`
	Pagination `url:"pagination"`
	Fields     map[string][]string `url:"fields"`
}

SubscribersQuery is a query for subscribers.

type User

type User struct {
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
	ImageURL  *string   `json:"image_url"`
	Name      string    `json:"name"`
	TimeZone  string    `json:"time_zone"`
	UpdatedAt time.Time `json:"updated_at"`
}

User represents a Transistor.fm user.

func (*User) UnmarshalJSON

func (u *User) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

type Webhook

type Webhook struct {
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
	EventName string    `json:"event_name"`
	UpdatedAt time.Time `json:"updated_at"`
	URL       string    `json:"url"`
	UserID    string    `json:"-"`
	ShowID    string    `json:"-"`
}

Webhook is an individual subscription to a Transistor webhook.

See https://developers.transistor.fm/#Webhook

func (*Webhook) UnmarshalJSON

func (w *Webhook) UnmarshalJSON(p []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL