telegraph

package module
v2.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2024 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

The telegraph package contains the base bindings for working with the Telegraph API.

Telegra.ph is a minimalist publishing tool that allows you to create richly formatted posts and push them to the Web in just a click. Telegraph posts also get beautiful Instant View pages on Telegram.

To maintain the purity of the basic interface, we launched the @Telegraph bot for those who require advanced features. This bot can help you manage your articles across any number of devices and get page view statistics for any Telegraph page.

Anyone can enjoy the simplicity of Telegraph publishing, not just Telegram users. For this reason, all developers are welcome to use this Telegraph API to create bots like @Telegraph for any other platform, or even standalone interfaces.

Example 
client := http.DefaultClient

account, err := telegraph.CreateAccount{
	AuthorURL:  nil,
	AuthorName: util.Must(telegraph.NewAuthorName("Anonymous")),
	ShortName:  *util.Must(telegraph.NewShortName("Sandbox")),
}.Do(context.Background(), client)
if err != nil {
	log.Fatalln("cannot create account:", err)
}

page, err := telegraph.CreatePage{
	AuthorURL:   nil,
	AccessToken: account.AccessToken,
	Title:       *util.Must(telegraph.NewTitle("Sample Page")),
	AuthorName:  &account.AuthorName,
	Content: []telegraph.Node{{
		Element: &telegraph.NodeElement{
			Tag:      telegraph.P,
			Children: []telegraph.Node{{Text: "Hello, World!"}},
		},
	}},
	ReturnContent: true,
}.Do(context.Background(), client)
if err != nil {
	log.Fatalln("cannot create page:", err)
}

fmt.Printf("'%s' by %s\n%s", page.Title, page.AuthorName, page.Content[0])

Output:

'Sample Page' by Anonymous
<p>Hello, World!</p>

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DefaultEndpoint *url.URL = &url.URL{
	Scheme: "https",
	Host:   "api.telegra.ph",
	Path:   "/",
}
View Source 
var ErrAuthorNameLength error = errors.New("unsupported length")
View Source 
var ErrShortNameLength error = errors.New("unsupported length")
View Source 
var ErrTag error = errors.New("unsupported Tag")

Functions

This section is empty.

Types

type Account 

type Account struct {
	// Profile link, opened when users click on the author's name below the
	// title. Can be any link, not necessarily to a Telegram profile or
	// channel.
	AuthorURL URL `json:"author_url"`

	// Optional. URL to authorize a browser on [telegra.ph] and connect it to
	// a Telegraph account. This URL is valid for only one use and for 5
	// minutes only.
	//
	// [telegra.ph]: https://telegra.ph/
	AuthURL *URL `json:"auth_url,omitempty"`

	ShortName ShortName `json:"short_name"`

	// Default author name used when creating new articles.
	AuthorName AuthorName `json:"author_name"`

	// Optional. Only returned by the [createAccount] and
	// [revokeAccessToken] method. Access token of the Telegraph account.
	AccessToken string `json:"access_token,omitempty"`

	// Optional. Number of pages belonging to the Telegraph account.
	PageCount uint `json:"page_count,omitempty"`
}

Account represents a Telegraph account.

type AccountField 

type AccountField struct {
	// contains filtered or unexported fields
}
var (
	FieldAuthorName AccountField = AccountField{"author_name"}
	FieldAuthorURL  AccountField = AccountField{"author_url"}
	FieldAuthURL    AccountField = AccountField{"auth_url"}
	FieldPageCount  AccountField = AccountField{"page_count"}
	FieldShortName  AccountField = AccountField{"short_name"}
)

func (AccountField) GoString added in v2.1.0 

func (af AccountField) GoString() string

func (AccountField) MarshalJSON added in v2.1.0 

func (af AccountField) MarshalJSON() ([]byte, error)

func (AccountField) String added in v2.1.0 

func (af AccountField) String() string

func (*AccountField) UnmarshalJSON added in v2.1.0 

func (af *AccountField) UnmarshalJSON(v []byte) error

type Attributes 

type Attributes struct {
	Href string `json:"href,omitempty"`
	Src  string `json:"src,omitempty"`
}

type AuthorName 

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

AuthorName represent author name used when creating new articles.

func NewAuthorName 

func NewAuthorName(raw string) (*AuthorName, error)

NewAuthorName parse raw string as AuthorName and validate it's length.

func TestAuthorName 

func TestAuthorName(tb testing.TB) *AuthorName

func (AuthorName) GoString 

func (an AuthorName) GoString() string

func (AuthorName) IsEmpty 

func (an AuthorName) IsEmpty() bool

IsEmpty returns true if current AuthorName is empty.

func (AuthorName) MarshalJSON 

func (an AuthorName) MarshalJSON() ([]byte, error)

func (AuthorName) String 

func (an AuthorName) String() string

func (*AuthorName) UnmarshalJSON 

func (an *AuthorName) UnmarshalJSON(v []byte) error

type CreateAccount 

type CreateAccount struct {
	// Default profile link, opened when users click on the author's name
	// below the title. Can be any link, not necessarily to a Telegram
	// profile or channel.
	AuthorURL *URL `json:"author_url,omitempty"` // 0-512 characters

	// Default author name used when creating new articles.
	AuthorName *AuthorName `json:"author_name,omitempty"` // 0-128 characters

	// Required.
	ShortName ShortName `json:"short_name"` // 1-32 characters
}

CreateAccount create a new Telegraph account. Most users only need one account, but this can be useful for channel administrators who would like to keep individual author names and profile links for each of their channels. On success, returns an Account object with the regular fields and an additional access_token field.

func (CreateAccount) Do 

func (params CreateAccount) Do(ctx context.Context, client *http.Client) (*Account, error)

type CreatePage 

type CreatePage struct {
	// Profile link, opened when users click on the author's name below the
	// title. Can be any link, not necessarily to a Telegram profile or
	// channel.
	AuthorURL *URL `json:"author_url,omitempty"` // 0-512 characters

	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`

	// Required. Page title.
	Title Title `json:"title"` // 1-256 characters

	// Author name, displayed below the article's title.
	AuthorName *AuthorName `json:"author_name,omitempty"` // 0-128 characters

	// Required. Content of the page.
	Content []Node `json:"content"` // up to 64 KB

	// If true, a content field will be returned in the Page object.
	ReturnContent bool `json:"return_content,omitempty"` // false
}

CreatePage create a new Telegraph page. On success, returns a Page object.

func (CreatePage) Do 

func (params CreatePage) Do(ctx context.Context, client *http.Client) (*Page, error)

type EditAccountInfo 

type EditAccountInfo struct {
	// New default profile link, opened when users click on the author's
	// name below the title. Can be any link, not necessarily to a Telegram
	// profile or channel.
	AuthorURL *URL `json:"author_url,omitempty"` // 0-512 characters

	// New account name.
	ShortName *ShortName `json:"short_name,omitempty"` // 1-32 characters

	// New default author name used when creating new articles.
	AuthorName *AuthorName `json:"author_name,omitempty"` // 0-128 characters

	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`
}

EditAccountInfo update information about a Telegraph account. Pass only the parameters that you want to edit. On success, returns an Account object with the default fields.

func (EditAccountInfo) Do 

func (params EditAccountInfo) Do(ctx context.Context, client *http.Client) (*Account, error)

type EditPage 

type EditPage struct {
	// Profile link, opened when users click on the author's name below the
	// title. Can be any link, not necessarily to a Telegram profile or
	// channel.
	AuthorURL *URL `json:"author_url,omitempty"` // 0-512 characters

	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`

	// Required. Path to the page.
	Path string `json:"path"`

	// Required. Page title.
	Title Title `json:"title"` // 1-256 characters

	// Author name, displayed below the article's title.
	AuthorName *AuthorName `json:"author_name,omitempty"` // 0-128 characters

	// Required. [Content] of the page.
	Content []Node `json:"content"` // up to 64 KB

	// If true, a content field will be returned in the [Page] object.
	ReturnContent bool `json:"return_content,omitempty"` // false
}

EditPage edit an existing Telegraph page. On success, returns a Page object.

func (EditPage) Do added in v2.1.0 

func (params EditPage) Do(ctx context.Context, client *http.Client) (*Page, error)

type GetAccountInfo 

type GetAccountInfo struct {
	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`

	// List of account fields to return.
	Fields []AccountField `json:"fields,omitempty"` // ["short_name","author_name","author_url"]
}

GetAccountInfo get information about a Telegraph account. Returns an Account object on success.

func (GetAccountInfo) Do 

func (params GetAccountInfo) Do(ctx context.Context, client *http.Client) (*Account, error)

type GetPage 

type GetPage struct {
	// Required. Path to the Telegraph page (in the format Title-12-31, i.e.
	// everything that comes after http://telegra.ph/).
	Path string `json:"path"`

	// If true, content field will be returned in [Page] object.
	ReturnContent bool `json:"return_content,omitempty"`
}

GetPage get a Telegraph page. Returns a Page object on success.

func (GetPage) Do 

func (params GetPage) Do(ctx context.Context, client *http.Client) (*Page, error)

type GetPageList 

type GetPageList struct {
	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`

	// Sequential number of the first page to be returned.
	Offset uint `json:"offset,omitempty"` // 0

	// Limits the number of pages to be retrieved.
	Limit uint16 `json:"limit,omitempty"` // 50 (0-200)
}

GetPageList get a list of pages belonging to a Telegraph account. Returns a PageList object, sorted by most recently created pages first.

func (GetPageList) Do 

func (params GetPageList) Do(ctx context.Context, client *http.Client) (*PageList, error)

type GetViews 

type GetViews struct {
	// Required. Path to the Telegraph page (in the format Title-12-31,
	// where 12 is the month and 31 the day the article was first
	// published).
	Path string `json:"-"`

	// Required if month is passed. If passed, the number of page views for
	// the requested year will be returned.
	Year uint16 `json:"year,omitempty"` // 2000-2100

	// Required if day is passed. If passed, the number of page views for
	// the requested month will be returned.
	Month uint8 `json:"month,omitempty"` // 1-12

	// Required if hour is passed. If passed, the number of page views for
	// the requested day will be returned.
	Day uint8 `json:"day,omitempty"` // 1-31

	// If passed, the number of page views for the requested hour will be
	// returned.
	Hour uint8 `json:"hour,omitempty"` // 0-24
}

GetViews get the number of views for a Telegraph article. Returns a PageViews object on success. By default, the total number of page views will be returned.

func (GetViews) Do 

func (params GetViews) Do(ctx context.Context, client *http.Client) (*PageViews, error)

type Node 

type Node struct {
	Element *NodeElement `json:"-"`
	Text    string       `json:"-"`
}

Node represent abstract object represents a DOM Node. It can be a String which represents a DOM text node or a NodeElement object.

func (Node) GoString 

func (n Node) GoString() string

func (Node) MarshalJSON 

func (n Node) MarshalJSON() ([]byte, error)

func (Node) String 

func (n Node) String() string

func (*Node) UnmarshalJSON 

func (n *Node) UnmarshalJSON(v []byte) error

type NodeElement 

type NodeElement struct {
	// Optional. Attributes of the DOM element. Key of object represents
	// name of attribute, value represents value of attribute. Available
	// attributes: href, src.
	Attrs *Attributes `json:"attrs,omitempty"`

	// Optional. List of child nodes for the DOM element.
	Children []Node `json:"children,omitempty"`

	// Name of the DOM element. Available tags: a, aside, b, blockquote, br,
	// code, em, figcaption, figure, h3, h4, hr, i, iframe, img, li, ol, p,
	// pre, s, strong, u, ul, video.
	Tag Tag `json:"tag"`
}

NodeElement object represents a DOM element node.

func NewNodeElement 

func NewNodeElement(tag Tag) *NodeElement

func (NodeElement) GoString 

func (ne NodeElement) GoString() string

func (NodeElement) String 

func (ne NodeElement) String() string

type Page 

type Page struct {
	// URL of the page.
	URL *URL `json:"url,omitempty"`

	// Optional. Profile link, opened when users click on the author's name
	// below the title. Can be any link, not necessarily to a Telegram
	// profile or channel.
	AuthorURL *URL `json:"author_url,omitempty"`

	// Optional. Image URL of the page.
	ImageURL *URL `json:"image_url,omitempty"`

	// Path to the page.
	Path string `json:"path,omitempty"`

	// Title of the page.
	Title *Title `json:"title,omitempty"`

	// Description of the page.
	Description string `json:"description,omitempty"`

	// Optional. Name of the author, displayed below the title.
	AuthorName *AuthorName `json:"author_name,omitempty"`

	// Optional. [Content] of the page.
	Content []Node `json:"content,omitempty"`

	// Number of page views for the page.
	Views uint `json:"views,omitempty"`

	// Optional. Only returned if access_token passed. True, if the target
	// Telegraph account can edit the page.
	CanEdit bool `json:"can_edit,omitempty"`
}

Page represents a page on Telegraph.

type PageList 

type PageList struct {
	// Requested pages of the target Telegraph account.
	Pages []Page `json:"pages"`

	// Total number of pages belonging to the target Telegraph account.
	TotalCount uint `json:"total_count"`
}

PageList represents a list of Telegraph articles belonging to an account. Most recently created articles first.

type PageViews 

type PageViews struct {
	// Number of page views for the target page.
	Views uint `json:"views"`
}

PageViews represents the number of page views for a Telegraph article.

type RevokeAccessToken 

type RevokeAccessToken struct {
	// Access token of the Telegraph account.
	AccessToken string `json:"access_token"`
}

RevokeAccessToken revoke access_token and generate a new one, for example, if the user would like to reset all connected sessions, or you have reasons to believe the token was compromised. On success, returns an Account object with new access_token and auth_url fields.

func (RevokeAccessToken) Do 

func (params RevokeAccessToken) Do(ctx context.Context, client *http.Client) (*Account, error)

type ShortName 

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

ShortName represent account name, helps users with several accounts remember which they are currently using. Displayed to the user above the "Edit/Publish" button on Telegra.ph, other users don't see this name.

func NewShortName 

func NewShortName(raw string) (*ShortName, error)

NewShortName parse raw string as ShortName and validate it's length.

func TestShortName 

func TestShortName(tb testing.TB) *ShortName

func (ShortName) GoString 

func (sn ShortName) GoString() string

func (ShortName) MarshalJSON 

func (sn ShortName) MarshalJSON() ([]byte, error)

func (ShortName) String 

func (sn ShortName) String() string

func (*ShortName) UnmarshalJSON 

func (sn *ShortName) UnmarshalJSON(v []byte) error

type Tag 

type Tag struct {
	// contains filtered or unexported fields
}
var (
	A          Tag = Tag{atom.A}          // "a"
	Aside      Tag = Tag{atom.Aside}      // "aside"
	B          Tag = Tag{atom.B}          // "b"
	Blockquote Tag = Tag{atom.Blockquote} // "blockquote"
	Br         Tag = Tag{atom.Br}         // "br"
	Code       Tag = Tag{atom.Code}       // "code"
	Em         Tag = Tag{atom.Em}         // "em"
	Figcaption Tag = Tag{atom.Figcaption} // "figcaption"
	Figure     Tag = Tag{atom.Figure}     // "figure"
	H3         Tag = Tag{atom.H3}         // "h3"
	H4         Tag = Tag{atom.H4}         // "h4"
	Hr         Tag = Tag{atom.Hr}         // "hr"
	I          Tag = Tag{atom.I}          // "i"
	Iframe     Tag = Tag{atom.Iframe}     // "iframe"
	Img        Tag = Tag{atom.Img}        // "img"
	Li         Tag = Tag{atom.Li}         // "li"
	Ol         Tag = Tag{atom.Ol}         // "ol"
	P          Tag = Tag{atom.P}          // "p"
	Pre        Tag = Tag{atom.Pre}        // "pre"
	S          Tag = Tag{atom.S}          // "s"
	Strong     Tag = Tag{atom.Strong}     // "strong"
	U          Tag = Tag{atom.U}          // "u"
	Ul         Tag = Tag{atom.Ul}         // "ul"
	Video      Tag = Tag{atom.Video}      // "video"
)

func NewTag 

func NewTag(t atom.Atom) (Tag, error)

func (Tag) Atom 

func (t Tag) Atom() atom.Atom

func (Tag) GoString 

func (t Tag) GoString() string

func (Tag) MarshalJSON 

func (t Tag) MarshalJSON() ([]byte, error)

func (Tag) String 

func (t Tag) String() string

func (*Tag) UnmarshalJSON 

func (t *Tag) UnmarshalJSON(v []byte) error

type Title 

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

Title represent page title.

func NewTitle 

func NewTitle(raw string) (*Title, error)

NewTitle returns a new Title from string if validation successull, or [ErrTitleLength] error if Title is too short or long.

func TestTitle 

func TestTitle(tb testing.TB) *Title

TestTitle returns valid Title for tests.

func (Title) GoString 

func (t Title) GoString() string

func (Title) MarshalJSON 

func (t Title) MarshalJSON() ([]byte, error)

func (Title) String 

func (t Title) String() string

func (*Title) UnmarshalJSON 

func (t *Title) UnmarshalJSON(v []byte) error

func (*Title) Update 

func (t *Title) Update(newTitle string) error

type URL 

type URL struct {
	*url.URL `json:"-"`
}

URL represent (un)marshling domain for Telegraph JSON objects.

func NewURL 

func NewURL(u *url.URL) *URL

func (URL) GoString 

func (u URL) GoString() string

func (URL) MarshalJSON 

func (u URL) MarshalJSON() ([]byte, error)

func (*URL) UnmarshalJSON 

func (u *URL) UnmarshalJSON(v []byte) error

Source Files

View all Source files

Directories

Path Synopsis
The content package contains utilities for converting page content from HTML DOM format to Telegraph API supported JSON objects and vice versa.
 The content package contains utilities for converting page content from HTML DOM format to Telegraph API supported JSON objects and vice versa.
internal
util
The util package contains utilities for working with URL paths.
 The util package contains utilities for working with URL paths.

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.