telegraph

package module
v0.0.0-...-318c661 Latest Latest
Warning

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

Go to latest
Published: Apr 12, 2023 License: GPL-3.0 Imports: 13 Imported by: 0

README

Golang Bindings for Telegraph API

⭐️ A star from you, means a lot!

This library represents a convenient wrapper around the Telegra.ph API. This is my first project in golang, so I would love to know my mistakes.

Features

Here are the most important aspects, shown as pros and cons:

Pros
  • Auto-generated from API, leaving less space for mistakes.
  • Very easy to use.
  • Upload media to Telegraph, the method which isn't included in the official API.
  • Helpful methods like Prettify() to pretty-print any object or convert object to JSON.
  • In-built HTML to NodeElement conversion so you can directly use strings with embedded HTML
  • Highly documented (doc strings) for IDEs like VSCode.
Cons
  • No custom error handling. Not much panicking. Though official errors will be returned as error object. But I guess that's conventional, and maybe convenient?
  • The bugs you are going to find.

Installing

Just install it using the standard go get command.

go get github.com/StarkBotsIndustries/telegraph/v2

Documentation

Docs can be found here : Go Reference

Example

A project based on this library can be found here : Telegraph Go Bot

Usage

This is pretty straightforward. First, import the library

import "github.com/StarkBotsIndustries/telegraph/v2"

Now you can call any methods. Let's say, CreateAccount?

acc, err := telegraph.CreateAccount(
    telegraph.CreateAccountOpts{ShortName: "Go is Love"},
)

acc.AccessToken
>>> "abcdefghijklmnopqrstuvwxyz"

acc.ShortName
>>> "Go is Love"

Or CreatePage

	page, err := telegraph.CreatePage(telegraph.CreatePageOpts{
		Title: "My First Page",
		Content: []telegraph.Node{
			"Hi ",
			telegraph.NodeElement{
				Tag:      "b",
				Children: []telegraph.Node{"Brothers"},
			},
			" and ",
			telegraph.NodeElement{
				Tag:      "code",
				Children: []telegraph.Node{"Sisters"},
			},
		},
		AccessToken: "abcdefghijklmnopqrstuvwxyz",
	})

page.URL
>>> "https://telegra.ph/My-First-Page-02-20"

page.Path
>>> "My-First-Page-02-20"

You can also directly use HTML using HTMLContent field

page, err := telegraph.CreatePage(telegraph.CreatePageOpts{
    Title: "My First Page",
    HTMLContent: "Hi <b>Brothers</b> and <code>Sisters</code>",
    AccessToken: "abcdefghijklmnopqrstuvwxyz",
})

Pretty Print an Object / Convert to JSON

acc, err := telegraph.CreateAccount(telegraph.CreateAccountOpts{ShortName: "Go is Love"})
prettifiedObject := telegraph.Prettify(acc)

prettifiedObject
>>> {
>>>     "short_name": "Go is Love",
>>>     "author_name": "",
>>>     "author_url": "",
>>>     "access_token": "abcdefghijklmnopqrstuvwxyz",
>>>     "auth_url": "https://edit.telegra.ph/auth/lmnopqrstuvwxyzabcdefghijk",
>>>     "page_count": 0
>>> }

Upload Media to Telegraph

file, _ := os.Open("file.jpg")
// os.File is io.Reader so just pass it.
link, _ := telegraph.Upload(file, "photo")

link
>>> "https://telegra.ph/file/abcdefghijklmnopqrstuvwxyz.jpg"

Raw Get Request

opts := telegraph.CreateAccountOpts{ShortName: "Durov Uncle"}
acc, err := telegraph.Get("createAccount", opts)

acc.AccessToken
>>> "abcdefghijklmnopqrstuvwxyz"

Raw Post Request

opts := telegraph.CreateAccountOpts{ShortName: "Durov Uncle"}
acc, err := telegraph.Post("createAccount", opts)

acc.AccessToken
>>> "abcdefghijklmnopqrstuvwxyz"

Community and Support

Telegram Channel - StarkBots

Telegram Chat - StarkBotsChat

:)

ForTheBadge made-with-go

ForTheBadge built-with-love

ForTheBadge makes-people-smile

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NodeToQueryString

func NodeToQueryString(nodes []Node) string

func Prettify

func Prettify(t interface{}) string

func Upload

func Upload(f io.Reader, mediaType string) (string, error)

Upload photo/video to Telegra.ph on the '/upload' endpoint. Media type should either be "video" or "photo". "Animation" is considered "video" here.

Types

type Account

type Account struct {
	ShortName   string `json:"short_name"`
	AuthorName  string `json:"author_name"`
	AuthorURL   string `json:"author_url"`
	AccessToken string `json:"access_token"`
	AuthURL     string `json:"auth_url"`
	PageCount   int64  `json:"page_count"`
}

Account implements the Account type of Telegraph API

func CreateAccount

func CreateAccount(opts CreateAccountOpts) (acc *Account, err error)

CreateAccount using Telegraph API. Returns Account object

func EditAccountInfo

func EditAccountInfo(opts EditAccountInfoOpts) (acc *Account, err error)

EditAccountInfo using Telegraph API. Returns Account object

func GetAccountInfo

func GetAccountInfo(opts GetAccountInfoOpts) (acc *Account, err error)

GetAccountInfo using Telegraph API. Returns Account object

func RevokeAccessToken

func RevokeAccessToken(opts RevokeAccessTokenOpts) (acc *Account, err error)

RevokeAccessToken using Telegraph API. Returns Account object

type AllValueTypes

type AllValueTypes struct {
	ShortName   string            `json:"short_name"`
	AuthorName  string            `json:"author_name"`
	AuthorURL   string            `json:"author_url"`
	AccessToken string            `json:"access_token"`
	AuthURL     string            `json:"auth_url"`
	PageCount   int64             `json:"page_count"`
	TotalCount  int64             `json:"total_count"`
	Pages       []Page            `json:"pages"`
	Path        string            `json:"path"`
	URL         string            `json:"url"`
	Title       string            `json:"title"`
	Description string            `json:"description"`
	ImageURL    string            `json:"image_url"`
	Content     []Node            `json:"content"`
	Views       int64             `json:"views"`
	CanEdit     bool              `json:"can_edit"`
	Tag         string            `json:"tag"`
	Attrs       map[string]string `json:"attrs"`
	Children    []Node            `json:"children"`
}

A way to set defaults to their zero types instead of nil Know a better way to do this?

func Get

func Get(route string, opts interface{}) (*AllValueTypes, error)

func Post

func Post(route string, opts interface{}) (*AllValueTypes, error)

type CreateAccountOpts

type CreateAccountOpts struct {
	// Required. 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.
	ShortName string `json:"short_name"`
	// Optional. Default author name used when creating new articles.
	AuthorName string `json:"author_name"`
	// Optional. 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 string `json:"author_url"`
}

CreateAccountOpts is the set of fields for 'Telegraph.CreateAccount'

type CreatePageOpts

type CreatePageOpts struct {
	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`
	// Required. Page title.
	Title string `json:"title"`
	// Optional. Author name, displayed below the article's title.
	AuthorName string `json:"author_name"`
	// 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 string `json:"author_url"`
	// Required if Content is empty. Content of the page as HTML string.
	HTMLContent string `json:"html_content"`
	// Required. Content of the page.
	Content []Node `json:"content"`
	// Optional. If true, a content field will be returned in the Page object
	ReturnContent bool `json:"return_content"`
}

CreatePageOpts is the set of fields for 'Telegraph.CreatePage'

type EditAccountInfoOpts

type EditAccountInfoOpts struct {
	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`
	// Optional. New account name.
	ShortName string `json:"short_name"`
	// Optional. New default author name used when creating new articles.
	AuthorName string `json:"author_name"`
	// Optional. 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 string `json:"author_url"`
}

EditAccountInfoOpts is the set of fields for 'Telegraph.EditAccountInfo'

type EditPageOpts

type EditPageOpts struct {
	// 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 string `json:"title"`
	// Required if Content is empty. Content of the page as HTML string.
	HTMLContent string `json:"html_content"`
	// Required if HTMLContent is empty. Content of the page.
	Content []Node `json:"content"`
	// Optional. Author name, displayed below the article's title.
	AuthorName string `json:"author_name"`
	// 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 string `json:"author_url"`
	// Optional. If true, a content field will be returned in the Page object.
	ReturnContent bool `json:"return_content"`
}

EditPageOpts is the set of fields for 'Telegraph.EditPage'

type GetAccountInfoOpts

type GetAccountInfoOpts struct {
	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`
	// Optional. List of account fields to return. Available fields: short_name, author_name, author_url, auth_url, page_count.
	Fields []string `json:"fields"`
}

GetAccountInfoOpts is the set of fields for 'Telegraph.GetAccountInfo'

type GetPageListOpts

type GetPageListOpts struct {
	// Required. Access token of the Telegraph account.
	AccessToken string `json:"access_token"`
	// Optional. Sequential number of the first page to be returned.
	Offset int64 `json:"offset"`
	// Optional. Limits the number of pages to be retrieved.
	Limit int64 `json:"limit"`
}

GetPageListOpts is the set of fields for 'Telegraph.GetPageList'

type GetPageOpts

type GetPageOpts 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"`
	// Optional. If true, content field will be returned in Page object.
	ReturnContent bool `json:"return_content"`
}

GetPageOpts is the set of fields for 'Telegraph.GetPage'

type GetViewsOpts

type GetViewsOpts 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:"path"`
	// Required if month is passed. If passed, the number of page views for the requested year will be returned.
	Year int64 `json:"year"`
	// Required if day is passed. If passed, the number of page views for the requested month will be returned.
	Month int64 `json:"month"`
	// Required if hour is passed. If passed, the number of page views for the requested day will be returned.
	Day int64 `json:"day"`
	// Optional. If passed, the number of page views for the requested hour will be returned.
	Hour int64 `json:"hour"`
}

GetViewsOpts is the set of fields for 'Telegraph.GetViews'

type Node

type Node interface{}

Node implements the Node type of Telegraph API It can be a String or NodeElement object

func HTMLToNode

func HTMLToNode(html string) []Node

type NodeElement

type NodeElement struct {
	Tag      string            `json:"tag"`
	Attrs    map[string]string `json:"attrs"`
	Children []Node            `json:"children"`
}

NodeElement implements the NodeElement type of Telegraph API

type Page

type Page struct {
	Path        string `json:"path"`
	URL         string `json:"url"`
	Title       string `json:"title"`
	Description string `json:"description"`
	AuthorName  string `json:"author_name"`
	AuthorURL   string `json:"author_url"`
	ImageURL    string `json:"image_url"`
	Content     []Node `json:"content"`
	Views       int64  `json:"views"`
	CanEdit     bool   `json:"can_edit"`
}

Page implements the Page type of Telegraph API

func CreatePage

func CreatePage(opts CreatePageOpts) (page *Page, err error)

CreatePage using Telegraph API. Returns Page object

func EditPage

func EditPage(opts EditPageOpts) (page *Page, err error)

EditPage using Telegraph API. Returns Page object

func GetPage

func GetPage(opts GetPageOpts) (page *Page, err error)

GetPage using Telegraph API. Returns Page object

type PageList

type PageList struct {
	TotalCount int64  `json:"total_count"`
	Pages      []Page `json:"pages"`
}

PageList implements the PageList type of Telegraph API

func GetPageList

func GetPageList(opts GetPageListOpts) (pl *PageList, err error)

GetPageList using Telegraph API. Returns PageList object

type PageViews

type PageViews struct {
	Views int64 `json:"views"`
}

PageViews implements the PageViews type of Telegraph API

func GetViews

func GetViews(opts GetViewsOpts) (views *PageViews, err error)

GetViews using Telegraph API. Returns PageViews object

type RevokeAccessTokenOpts

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

RevokeAccessTokenOpts is the set of fields for 'Telegraph.RevokeAccessToken'

Jump to

Keyboard shortcuts

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