telegra_ph/methods.rs
1use crate::entity::*;
2
3/// Use this method to create a new Telegraph account. Most users only need one account, but this
4/// can be useful for channel administrators who would like to keep individual author names and
5/// profile links for each of their channels. On success, returns an Account object with the
6/// regular fields and an additional access_token field.
7///
8/// - short_name (String, 1-32 characters)
9/// Required. Account name, helps users with several accounts remember which they are
10/// currently using. Displayed to the user above the "Edit/Publish" button on Telegra.ph,
11/// other users don't see this name.
12/// - author_name (String, 0-128 characters)
13/// Default author name used when creating new articles.
14/// - author_url (String, 0-512 characters)
15/// Default profile link, opened when users click on the author's name
16/// below the title. Can be any link, not necessarily to a Telegram profile
17/// or channel.
18/// - Sample request
19/// <https://api.telegra.ph/createAccount?short_name=Sandbox&author_name=Anonymous>
20pub struct CreateAccount {
21 pub short_name: ShortName,
22 pub author_name: Option<AuthorName>,
23 pub author_url: Option<AuthorUrl>,
24}
25
26impl CreateAccount {
27 pub fn new(short_name: String) -> Self {
28 assert!(!short_name.is_empty(), "short name is required");
29 Self {
30 short_name: ShortName::new(short_name),
31 author_name: None,
32 author_url: None,
33 }
34 }
35
36 pub fn with_raw(
37 short_name: String,
38 author_name: Option<String>,
39 author_url: Option<String>,
40 ) -> Self {
41 let author_name = match author_name {
42 Some(name) => Some(AuthorName::new(name)),
43 None => None
44 };
45 let author_url = match author_url {
46 Some(url) => Some(AuthorUrl::new(url)),
47 None => None
48 };
49 Self {
50 short_name: ShortName::new(short_name),
51 author_name,
52 author_url,
53 }
54 }
55
56 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut CreateAccount) -> Pin<Box<dyn Future<Output = Ret<Account>> + 'a>>> ) -> Ret<Account> {
57 f(self).await
58 }
59}
60
61/// Use this method to update information about a Telegraph account. Pass only the parameters that
62/// you want to edit. On success, returns an Account object with the default fields.
63///
64/// - access_token (String)
65/// Required. Access token of the Telegraph account.
66/// - short_name (String, 1-32 characters)
67/// New account name.
68/// - author_name (String, 0-128 characters)
69/// New default author name used when creating new articles.
70/// - author_url (String, 0-512 characters)
71/// 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.
72///
73/// - Sample request
74/// <https://api.telegra.ph/editAccountInfo?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&short_name=Sandbox&author_name=Anonymous>
75pub struct EditAccountInfo {
76 pub access_token: String,
77 pub short_name: ShortName,
78 pub author_name: Option<AuthorName>,
79 pub author_url: Option<AuthorUrl>,
80}
81use std::pin::Pin;
82use std::future::Future;
83pub type Ret<T> = Result<T, Box<dyn std::error::Error>> ;
84
85impl EditAccountInfo {
86 pub fn new(access_token: String, short_name: String) -> Self {
87 Self {
88 access_token,
89 short_name: ShortName::new(short_name),
90 author_name: None,
91 author_url: None,
92 }
93 }
94
95 pub fn with_raw(
96 access_token: String,
97 short_name: String,
98 author_name: Option<String>,
99 author_url: Option<String>,
100 ) -> Self {
101 let author_name = match author_name {
102 Some(name) => Some(AuthorName(name)),
103 None => None
104 };
105 let author_url = match author_url {
106 Some(url) => Some(AuthorUrl(url)),
107 None => None
108 };
109 Self {
110 access_token,
111 short_name: ShortName::new(short_name),
112 author_name,
113 author_url,
114 }
115 }
116
117 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut EditAccountInfo) -> Pin<Box<dyn Future<Output = Ret<Account>> + 'a>>> ) -> Ret<Account> {
118 f(self).await
119 }
120}
121
122/// Use this method to get information about a Telegraph account. Returns an Account object on
123/// success.
124/// - access_token (String)
125/// Required. Access token of the Telegraph account.
126/// - fields (Array of String, default = [“short_name”,“author_name”,“author_url”])
127/// List of account fields to return. Available fields: short_name, author_name, author_url, auth_url, page_count.
128///
129/// - Sample request
130/// <https://api.telegra.ph/getAccountInfo?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&fields=["short_name","page_count"]>
131pub struct GetAccountInfo {
132 pub access_token: String,
133 pub fields: Fields,
134}
135
136impl GetAccountInfo {
137 pub fn new(access_token: String) -> Self {
138 Self {
139 access_token,
140 fields: Fields::new(vec![]),
141 }
142 }
143
144 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut GetAccountInfo) -> Pin<Box<dyn Future<Output = Ret<Account>> + 'a>>> ) -> Ret<Account> {
145 f(self).await
146 }
147}
148
149/// Use this method to revoke access_token and generate a new one, for example, if the user would
150/// like to reset all connected sessions, or you have reasons to believe the token was compromised.
151/// On success, returns an Account object with new access_token and auth_url fields.
152///
153/// - access_token (String)
154/// Required. Access token of the Telegraph account.
155///
156/// - Sample request
157/// <https://api.telegra.ph/revokeAccessToken?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb>
158pub struct RevokeAccessToken {
159 pub access_token: String,
160}
161
162impl RevokeAccessToken {
163 pub fn new(access_token: String) -> Self {
164 Self {
165 access_token,
166 }
167 }
168
169 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut RevokeAccessToken) -> Pin<Box<dyn Future<Output = Ret<Account>> + 'a>>> ) -> Ret<Account> {
170 f(self).await
171 }
172}
173
174
175/// Use this method to create a new Telegraph page. On success, returns a Page object.
176///
177/// - access_token (String)
178/// Required. Access token of the Telegraph account.
179/// - title (String, 1-256 characters)
180/// Required. Page title.
181/// - author_name (String, 0-128 characters)
182/// Author name, displayed below the article's title.
183/// - author_url (String, 0-512 characters)
184/// 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.
185/// - content (Array of Node, up to 64 KB)
186/// Required. Content of the page.
187/// - return_content (Boolean, default = false)
188/// If true, a content field will be returned in the Page object (see: Content format).
189///
190/// - Sample request
191/// <https://api.telegra.ph/createPage?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&title=Sample+Page&author_name=Anonymous&content=[{"tag":"p","children":["Hello,+world!"]}]&return_content=true>
192pub struct CreatePage {
193 pub access_token: String,
194 pub title: Title,
195 pub author_name: AuthorName,
196 pub author_url: AuthorUrl,
197 pub content: Content,
198 pub return_content: bool,
199}
200
201impl CreatePage {
202 pub fn new(access_token: String, title: String, content: Content, return_content: bool) -> Self {
203 Self {
204 access_token,
205 title: Title::new(title),
206 author_name: AuthorName::new("".into()),
207 author_url: AuthorUrl::new("".into()),
208 content,
209 return_content,
210 }
211 }
212
213 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut CreatePage) -> Pin<Box<dyn Future<Output = Ret<Page>> + 'a>>> ) -> Ret<Page> {
214 f(self).await
215 }
216}
217
218/// Use this method to edit an existing Telegraph page. On success, returns a Page object.
219///
220/// - access_token (String)
221/// Required. Access token of the Telegraph account.
222/// - path (String)
223/// Required. Path to the page.
224/// - title (String, 1-256 characters)
225/// Required. Page title.
226/// - content (Array of Node, up to 64 KB)
227/// Required. Content of the page.
228/// - author_name (String, 0-128 characters)
229/// Author name, displayed below the article's title.
230/// - author_url (String, 0-512 characters)
231/// 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.
232/// - return_content (Boolean, default = false)
233/// If true, a content field will be returned in the Page object.
234///
235/// - Sample request
236/// <https://api.telegra.ph/editPage/Sample-Page-12-15?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&title=Sample+Page&author_name=Anonymous&content=[{"tag":"p","children":["Hello,+world!"]}]&return_content=true>
237pub struct EditPage {
238 pub access_token: String,
239 pub path: String,
240 pub title: Title,
241 pub content: Content,
242 pub author_name: AuthorName,
243 pub author_url: AuthorUrl,
244 pub return_content: bool,
245}
246
247impl EditPage {
248 pub fn new(access_token: String, path: String, title: String, content: Content, return_content: bool) -> Self {
249 Self {
250 access_token,
251 title: Title::new(title),
252 path,
253 author_name: AuthorName::new("".into()),
254 author_url: AuthorUrl::new("".into()),
255 content,
256 return_content,
257 }
258 }
259
260 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut EditPage) -> Pin<Box<dyn Future<Output = Ret<Page>> + 'a>>> ) -> Ret<Page> {
261 f(self).await
262 }
263}
264
265/// Use this method to get a Telegraph page. Returns a Page object on success.
266///
267/// - path (String)
268/// Required. Path to the Telegraph page (in the format Title-12-31, i.e. everything that comes after <http://telegra.ph/>).
269/// - return_content (Boolean, default = false)
270/// If true, content field will be returned in Page object.
271///
272/// - Sample request
273/// <https://api.telegra.ph/getPage/Sample-Page-12-15?return_content=true>
274pub struct GetPage {
275 pub path: String,
276 pub return_content: bool,
277}
278
279impl GetPage {
280 pub fn new( path: String, return_content: bool) -> Self {
281 Self {
282 path,
283 return_content,
284 }
285 }
286
287 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut GetPage) -> Pin<Box<dyn Future<Output = Ret<Page>> + 'a>>> ) -> Ret<Page> {
288 f(self).await
289 }
290}
291
292/// Use this method to get a list of pages belonging to a Telegraph account. Returns a PageList object, sorted by most recently created pages first.
293///
294/// - access_token (String)
295/// Required. Access token of the Telegraph account.
296/// - offset (Integer, default = 0)
297/// Sequential number of the first page to be returned.
298/// - limit (Integer, 0-200, default = 50)
299/// Limits the number of pages to be retrieved.
300///
301/// - Sample request
302/// <https://api.telegra.ph/getPageList?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&limit=3>
303pub struct GetPageList {
304 pub access_token: String,
305 pub offset: u32,
306 pub limit: Limit,
307}
308
309impl GetPageList {
310 pub fn new(access_token: String, offset: u32, ) -> Self {
311 Self {
312 access_token,
313 offset,
314 limit: Limit::new(),
315 }
316 }
317
318 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut GetPageList) -> Pin<Box<dyn Future<Output = Ret<PageList>> + 'a>>> ) -> Ret<PageList> {
319 f(self).await
320 }
321}
322
323/// Use this method to 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.
324///
325/// - path (String)
326/// 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).
327/// - year (Integer, 2000-2100)
328/// Required if month is passed. If passed, the number of page views for the requested year will be returned.
329/// - month (Integer, 1-12)
330/// Required if day is passed. If passed, the number of page views for the requested month will be returned.
331/// - day (Integer, 1-31)
332/// Required if hour is passed. If passed, the number of page views for the requested day will be returned.
333/// - hour (Integer, 0-24)
334/// If passed, the number of page views for the requested hour will be returned.
335///
336/// - Sample request
337/// <https://api.telegra.ph/getViews/Sample-Page-12-15?year=2016&month=12>
338pub struct GetViews {
339 pub path: String,
340 pub year: Option<Year>,
341 pub month: Option<Month>,
342 pub day: Option<Day>,
343 pub hour: Option<Hour>,
344}
345
346impl GetViews {
347 pub fn new(path: String, year: u16, ) -> Self {
348 Self {
349 path,
350 year: Some(Year::new(year)),
351 month: None,
352 day: None,
353 hour: None,
354 }
355 }
356
357 pub async fn run(&mut self, f: Box<dyn for<'a> Fn(&'a mut GetViews) -> Pin<Box<dyn Future<Output = Ret<PageViews>> + 'a>>> ) -> Ret<PageViews> {
358 f(self).await
359 }
360}
361