megalodon/
megalodon.rs

1//! Megalodon modules
2
3use core::fmt;
4use std::str::FromStr;
5
6use crate::error::{Error, Kind};
7use crate::oauth::{AppData, TokenData};
8use crate::response::Response;
9use crate::{entities, Streaming};
10use async_trait::async_trait;
11use chrono::{DateTime, Utc};
12use serde::Serialize;
13use tokio::{fs::File, io::AsyncRead};
14
15/// Megalodon API interface
16#[async_trait]
17pub trait Megalodon {
18    /// Register the application to get client_id and client_secret.
19    async fn register_app(
20        &self,
21        client_name: String,
22        options: &AppInputOptions,
23    ) -> Result<AppData, Error>;
24
25    /// Create an application.
26    async fn create_app(
27        &self,
28        client_name: String,
29        options: &AppInputOptions,
30    ) -> Result<AppData, Error>;
31
32    // ======================================
33    // apps/oauth
34    // ======================================
35    /// Fetch OAuth access token.
36    /// Get an access token based client_id, client_secret and authorization_code.
37    async fn fetch_access_token(
38        &self,
39        client_id: String,
40        client_secret: String,
41        code: String,
42        redirect_uri: String,
43    ) -> Result<TokenData, Error>;
44
45    /// Refresh OAuth access token.
46    /// Send refresh token and get new access token.
47    async fn refresh_access_token(
48        &self,
49        client_id: String,
50        client_secret: String,
51        refresh_token: String,
52    ) -> Result<TokenData, Error>;
53
54    /// Revoke an access token.
55    async fn revoke_access_token(
56        &self,
57        client_id: String,
58        client_secret: String,
59        access_token: String,
60    ) -> Result<Response<()>, Error>;
61
62    // ======================================
63    // apps
64    // ======================================
65    /// Test to make sure that the application token works.
66    async fn verify_app_credentials(&self) -> Result<Response<entities::Application>, Error>;
67
68    // ======================================
69    // accounts
70    // ======================================
71    /// Register an user account.
72    async fn register_account(
73        &self,
74        username: String,
75        email: String,
76        password: String,
77        agreement: String,
78        locale: String,
79        reason: Option<String>,
80    ) -> Result<Response<entities::Token>, Error>;
81
82    /// Test to make sure that the user token works.
83    async fn verify_account_credentials(&self) -> Result<Response<entities::Account>, Error>;
84
85    /// Update the user's display and preferences.
86    async fn update_credentials(
87        &self,
88        options: Option<&UpdateCredentialsInputOptions>,
89    ) -> Result<Response<entities::Account>, Error>;
90
91    /// Get an account information.
92    async fn get_account(&self, id: String) -> Result<Response<entities::Account>, Error>;
93
94    /// Get statuses of the account.
95    async fn get_account_statuses(
96        &self,
97        id: String,
98        options: Option<&GetAccountStatusesInputOptions>,
99    ) -> Result<Response<Vec<entities::Status>>, Error>;
100
101    /// Get favourited statuses of the account.
102    async fn get_account_favourites(
103        &self,
104        id: String,
105        options: Option<&GetAccountFavouritesInputOptions>,
106    ) -> Result<Response<Vec<entities::Status>>, Error>;
107
108    /// Receive notifications when this account posts a status.
109    async fn subscribe_account(
110        &self,
111        id: String,
112    ) -> Result<Response<entities::Relationship>, Error>;
113
114    /// Stop receiving notifications when this account posts a status.
115    async fn unsubscribe_account(
116        &self,
117        id: String,
118    ) -> Result<Response<entities::Relationship>, Error>;
119
120    /// Get accounts which follow the give account.
121    async fn get_account_followers(
122        &self,
123        id: String,
124        options: Option<&AccountFollowersInputOptions>,
125    ) -> Result<Response<Vec<entities::Account>>, Error>;
126
127    /// Get accounts which the given acount is following.
128    async fn get_account_following(
129        &self,
130        id: String,
131        options: Option<&AccountFollowersInputOptions>,
132    ) -> Result<Response<Vec<entities::Account>>, Error>;
133
134    /// Get lists of the given account.
135    async fn get_account_lists(&self, id: String) -> Result<Response<Vec<entities::List>>, Error>;
136
137    /// Get proofs of the given account.
138    async fn get_identity_proofs(
139        &self,
140        id: String,
141    ) -> Result<Response<Vec<entities::IdentityProof>>, Error>;
142
143    /// Follow the given account. Can also be used to update whether to show reblogs or enable notifications.
144    async fn follow_account(
145        &self,
146        id: String,
147        options: Option<&FollowAccountInputOptions>,
148    ) -> Result<Response<entities::Relationship>, Error>;
149
150    /// Unfollow the given account.
151    async fn unfollow_account(&self, id: String)
152        -> Result<Response<entities::Relationship>, Error>;
153
154    /// Block the given account.
155    async fn block_account(&self, id: String) -> Result<Response<entities::Relationship>, Error>;
156
157    /// Unblock the given account.
158    async fn unblock_account(&self, id: String) -> Result<Response<entities::Relationship>, Error>;
159
160    /// Mute the given account.
161    async fn mute_account(
162        &self,
163        id: String,
164        notifications: bool,
165    ) -> Result<Response<entities::Relationship>, Error>;
166
167    /// Unmute the given account.
168    async fn unmute_account(&self, id: String) -> Result<Response<entities::Relationship>, Error>;
169
170    /// Add the given account to the user's featured profiles.
171    async fn pin_account(&self, id: String) -> Result<Response<entities::Relationship>, Error>;
172
173    /// Remove the given account from the user's featured profiles.
174    async fn unpin_account(&self, id: String) -> Result<Response<entities::Relationship>, Error>;
175
176    /// Set a private note on the given account.
177    async fn set_account_note(
178        &self,
179        id: String,
180        note: Option<String>,
181    ) -> Result<Response<entities::Relationship>, Error>;
182
183    /// Find out whether a given account is followed, blocked, muted, etc.
184    async fn get_relationships(
185        &self,
186        ids: Vec<String>,
187    ) -> Result<Response<Vec<entities::Relationship>>, Error>;
188
189    /// Search for matching accounts by username or display name.
190    async fn search_account(
191        &self,
192        q: String,
193        options: Option<&SearchAccountInputOptions>,
194    ) -> Result<Response<Vec<entities::Account>>, Error>;
195
196    /// Lookup account ID from Webfinger address.
197    async fn lookup_account(&self, acct: String) -> Result<Response<entities::Account>, Error>;
198
199    // ======================================
200    // accounts/bookmarks
201    // ======================================
202    /// Get statuses the user has bookmarked.
203    async fn get_bookmarks(
204        &self,
205        options: Option<&GetBookmarksInputOptions>,
206    ) -> Result<Response<Vec<entities::Status>>, Error>;
207
208    // ======================================
209    // accounts/favourites
210    // ======================================
211    /// Get statuses the user has favourited.
212    async fn get_favourites(
213        &self,
214        options: Option<&GetFavouritesInputOptions>,
215    ) -> Result<Response<Vec<entities::Status>>, Error>;
216
217    // ======================================
218    // accounts/mutes
219    // ======================================
220    /// Get accounts the user has muted.
221    async fn get_mutes(
222        &self,
223        options: Option<&GetMutesInputOptions>,
224    ) -> Result<Response<Vec<entities::Account>>, Error>;
225
226    // ======================================
227    // accounts/blocks
228    // ======================================
229    /// Get accounts the user has blocked.
230    async fn get_blocks(
231        &self,
232        options: Option<&GetBlocksInputOptions>,
233    ) -> Result<Response<Vec<entities::Account>>, Error>;
234
235    // ======================================
236    // accounts/domain_blocks
237    // ======================================
238    /// Get domains the user has blocked.
239    async fn get_domain_blocks(
240        &self,
241        options: Option<&GetDomainBlocksInputOptions>,
242    ) -> Result<Response<Vec<String>>, Error>;
243
244    /// Block a domain.
245    async fn block_domain(&self, domain: String) -> Result<Response<()>, Error>;
246
247    /// Remove a domain block.
248    async fn unblock_domain(&self, domain: String) -> Result<Response<()>, Error>;
249
250    // ======================================
251    // accounts/filters
252    // ======================================
253    /// Get all filters.
254    async fn get_filters(&self) -> Result<Response<Vec<entities::Filter>>, Error>;
255
256    /// Get a specified filter.
257    async fn get_filter(&self, id: String) -> Result<Response<entities::Filter>, Error>;
258
259    /// Create a filter.
260    async fn create_filter(
261        &self,
262        phrase: String,
263        context: Vec<entities::filter::FilterContext>,
264        options: Option<&FilterInputOptions>,
265    ) -> Result<Response<entities::Filter>, Error>;
266
267    /// Update a filter.
268    async fn update_filter(
269        &self,
270        id: String,
271        phrase: String,
272        context: Vec<entities::filter::FilterContext>,
273        options: Option<&FilterInputOptions>,
274    ) -> Result<Response<entities::Filter>, Error>;
275
276    /// Delete a filter.
277    async fn delete_filter(&self, id: String) -> Result<Response<()>, Error>;
278
279    // ======================================
280    // accounts/reports
281    // ======================================
282    /// Report an user.
283    async fn report(
284        &self,
285        account_id: String,
286        options: Option<&ReportInputOptions>,
287    ) -> Result<Response<entities::Report>, Error>;
288
289    // ======================================
290    // accounts/follow_requests
291    // ======================================
292    /// Get accounts who send follow request to the user.
293    async fn get_follow_requests(
294        &self,
295        limit: Option<u32>,
296    ) -> Result<Response<Vec<FollowRequestOutput>>, Error>;
297
298    /// Accept the follow request.
299    async fn accept_follow_request(
300        &self,
301        id: String,
302    ) -> Result<Response<entities::Relationship>, Error>;
303
304    /// Reject the follow request.
305    async fn reject_follow_request(
306        &self,
307        id: String,
308    ) -> Result<Response<entities::Relationship>, Error>;
309
310    // ======================================
311    // accounts/endorsements
312    // ======================================
313    /// Get accounts that the user is currently featuring on their profile.
314    async fn get_endorsements(
315        &self,
316        options: Option<&GetEndorsementsInputOptions>,
317    ) -> Result<Response<Vec<entities::Account>>, Error>;
318
319    // ======================================
320    // accounts/featured_tags
321    // ======================================
322    /// Get featured tags.
323    async fn get_featured_tags(&self) -> Result<Response<Vec<entities::FeaturedTag>>, Error>;
324
325    /// Create a featured tag.
326    async fn create_featured_tag(
327        &self,
328        name: String,
329    ) -> Result<Response<entities::FeaturedTag>, Error>;
330
331    /// Delete a featured tag.
332    async fn delete_featured_tag(&self, id: String) -> Result<Response<()>, Error>;
333
334    /// Shows your 10 most-used tags, with usage history for the past week.
335    async fn get_suggested_tags(&self) -> Result<Response<Vec<entities::Tag>>, Error>;
336
337    // ======================================
338    // accounts/preferences
339    // ======================================
340    /// Get preferences defined by the user in their account settings.
341    async fn get_preferences(&self) -> Result<Response<entities::Preferences>, Error>;
342
343    // ======================================
344    // accounts/followed_tags
345    // ======================================
346    /// Get all followed tags.
347    async fn get_followed_tags(&self) -> Result<Response<Vec<entities::Tag>>, Error>;
348
349    // ======================================
350    // accounts/suggestions
351    // ======================================
352    /// Get accounts the user has had past positive interactions with, but is not yet following.
353    async fn get_suggestions(
354        &self,
355        limit: Option<u32>,
356    ) -> Result<Response<Vec<entities::Account>>, Error>;
357
358    // ======================================
359    // accounts/tags
360    // ======================================
361    /// Get a hashtag and its associated information.
362    async fn get_tag(&self, id: String) -> Result<Response<entities::Tag>, Error>;
363
364    /// Follow a hashtag. Posts containing a followed hashtag will be inserted into your home timeline.
365    async fn follow_tag(&self, id: String) -> Result<Response<entities::Tag>, Error>;
366
367    /// Unfollow a hashtag. Posts containing this hashtag will no longer be inserted into your home timeline.
368    async fn unfollow_tag(&self, id: String) -> Result<Response<entities::Tag>, Error>;
369
370    // ======================================
371    // statuses
372    // ======================================
373    /// Post a new status.
374    async fn post_status(
375        &self,
376        status: String,
377        options: Option<&PostStatusInputOptions>,
378    ) -> Result<Response<PostStatusOutput>, Error>;
379
380    /// Get information about a status.
381    async fn get_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
382
383    /// Obtain the source properties for a status so that it can be edited.
384    async fn get_status_source(
385        &self,
386        id: String,
387    ) -> Result<Response<entities::StatusSource>, Error>;
388
389    /// Edit a status.
390    async fn edit_status(
391        &self,
392        id: String,
393        options: &EditStatusInputOptions,
394    ) -> Result<Response<entities::Status>, Error>;
395
396    /// Delete a status of your own statuses.
397    async fn delete_status(&self, id: String) -> Result<Response<()>, Error>;
398
399    /// Get statuses above and below this status in the thread.
400    async fn get_status_context(
401        &self,
402        id: String,
403        options: Option<&GetStatusContextInputOptions>,
404    ) -> Result<Response<entities::Context>, Error>;
405
406    /// Get accounts who boosted a given status.
407    async fn get_status_reblogged_by(
408        &self,
409        id: String,
410    ) -> Result<Response<Vec<entities::Account>>, Error>;
411
412    /// Get accounts who favourited a given status.
413    async fn get_status_favourited_by(
414        &self,
415        id: String,
416    ) -> Result<Response<Vec<entities::Account>>, Error>;
417
418    /// Add a status to your favourites list.
419    async fn favourite_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
420
421    /// Remove a status from your favourites list.
422    async fn unfavourite_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
423
424    /// Reblog a status.
425    async fn reblog_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
426
427    /// Undo a reblog of a status.
428    async fn unreblog_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
429
430    /// Add a status to your bookmark list.
431    async fn bookmark_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
432
433    /// Remove a status from your bookmark lits.
434    async fn unbookmark_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
435
436    /// Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.
437    async fn mute_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
438
439    /// Start receiving notifications again for the thread that this status is part of.
440    async fn unmute_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
441
442    /// Feature one of your own public statuses at the top of your profile.
443    async fn pin_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
444
445    /// Unfeature a status from the top of your profile.
446    async fn unpin_status(&self, id: String) -> Result<Response<entities::Status>, Error>;
447
448    // ======================================
449    // statuses/media
450    // ======================================
451    /// Creates an attachment to be used with a new status.
452    async fn upload_media(
453        &self,
454        file_path: String,
455        options: Option<&UploadMediaInputOptions>,
456    ) -> Result<Response<entities::UploadMedia>, Error> {
457        let file = File::open(file_path.clone()).await?;
458        self.upload_media_reader(Box::new(file), options, Some(file_path)).await
459    }
460
461    async fn upload_media_reader(
462        &self,
463        reader: Box<dyn AsyncRead + Sync + Send + Unpin>,
464        options: Option<&UploadMediaInputOptions>,
465        file_name: Option<String>,
466    ) -> Result<Response<entities::UploadMedia>, Error>;
467
468    /// Get an Attachment.
469    async fn get_media(&self, id: String) -> Result<Response<entities::Attachment>, Error>;
470
471    /// Update an Attachment, before it is attached to a status and posted.
472    async fn update_media(
473        &self,
474        id: String,
475        options: Option<&UpdateMediaInputOptions>,
476    ) -> Result<Response<entities::Attachment>, Error>;
477
478    // ======================================
479    // statuses/polls
480    // ======================================
481    /// Get a poll information.
482    async fn get_poll(&self, id: String) -> Result<Response<entities::Poll>, Error>;
483
484    /// Vote a poll.
485    async fn vote_poll(
486        &self,
487        id: String,
488        choices: Vec<u32>,
489        status_id: Option<String>,
490    ) -> Result<Response<entities::Poll>, Error>;
491
492    // ======================================
493    // statuses/scheduled_statuses
494    // ======================================
495    /// Get statuses which scheduled to publish later.
496    async fn get_scheduled_statuses(
497        &self,
498        options: Option<&GetScheduledStatusesInputOptions>,
499    ) -> Result<Response<Vec<entities::ScheduledStatus>>, Error>;
500
501    /// Get a scheduled status.
502    async fn get_scheduled_status(
503        &self,
504        id: String,
505    ) -> Result<Response<entities::ScheduledStatus>, Error>;
506
507    /// Schedule a status to publish later.
508    async fn schedule_status(
509        &self,
510        id: String,
511        scheduled_at: Option<DateTime<Utc>>,
512    ) -> Result<Response<entities::ScheduledStatus>, Error>;
513
514    /// Remove the schdule to publish.
515    async fn cancel_scheduled_status(&self, id: String) -> Result<Response<()>, Error>;
516
517    // ======================================
518    // timeilnes
519    // ======================================
520    /// Get statuses of public timeline.
521    async fn get_public_timeline(
522        &self,
523        options: Option<&GetPublicTimelineInputOptions>,
524    ) -> Result<Response<Vec<entities::Status>>, Error>;
525
526    /// Get statuses of local timeline.
527    async fn get_local_timeline(
528        &self,
529        options: Option<&GetLocalTimelineInputOptions>,
530    ) -> Result<Response<Vec<entities::Status>>, Error>;
531
532    /// Get statuses of tag timeline.
533    async fn get_tag_timeline(
534        &self,
535        hashtag: String,
536        options: Option<&GetTagTimelineInputOptions>,
537    ) -> Result<Response<Vec<entities::Status>>, Error>;
538
539    /// Get statuses of home timeline.
540    async fn get_home_timeline(
541        &self,
542        options: Option<&GetHomeTimelineInputOptions>,
543    ) -> Result<Response<Vec<entities::Status>>, Error>;
544
545    /// Get status of list timeline.
546    async fn get_list_timeline(
547        &self,
548        list_id: String,
549        options: Option<&GetListTimelineInputOptions>,
550    ) -> Result<Response<Vec<entities::Status>>, Error>;
551
552    // ======================================
553    // timeilnes/conversations
554    // ======================================
555    /// Get statuses of conversation timeline.
556    async fn get_conversation_timeline(
557        &self,
558        options: Option<&GetConversationTimelineInputOptions>,
559    ) -> Result<Response<Vec<entities::Conversation>>, Error>;
560
561    /// Delete a conversation.
562    async fn delete_conversation(&self, id: String) -> Result<Response<()>, Error>;
563
564    /// Mark to read the conversation.
565    async fn read_conversation(
566        &self,
567        id: String,
568    ) -> Result<Response<entities::Conversation>, Error>;
569
570    // ======================================
571    // timeilnes/lists
572    // ======================================
573    /// Get list timelines which you created.
574    async fn get_lists(&self) -> Result<Response<Vec<entities::List>>, Error>;
575
576    /// Get a list timeline.
577    async fn get_list(&self, id: String) -> Result<Response<entities::List>, Error>;
578
579    /// Create a new list timeline.
580    async fn create_list(&self, title: String) -> Result<Response<entities::List>, Error>;
581
582    /// Update the list timeline.
583    async fn update_list(
584        &self,
585        id: String,
586        title: String,
587    ) -> Result<Response<entities::List>, Error>;
588
589    /// Delete the list timeline.
590    async fn delete_list(&self, id: String) -> Result<Response<()>, Error>;
591
592    /// Get accounts which registered to the list.
593    async fn get_accounts_in_list(
594        &self,
595        id: String,
596        options: Option<&GetAccountsInListInputOptions>,
597    ) -> Result<Response<Vec<entities::Account>>, Error>;
598
599    /// Register an account to the list.
600    async fn add_accounts_to_list(
601        &self,
602        id: String,
603        account_ids: Vec<String>,
604    ) -> Result<Response<entities::List>, Error>;
605
606    /// Remove the account from the list.
607    async fn delete_accounts_from_list(
608        &self,
609        id: String,
610        account_ids: Vec<String>,
611    ) -> Result<Response<()>, Error>;
612
613    // ======================================
614    // timeilnes/markers
615    // ======================================
616    /// Get your position in timelines.
617    async fn get_markers(&self, timeline: Vec<String>)
618        -> Result<Response<entities::Marker>, Error>;
619
620    /// Save your position in timelines.
621    async fn save_markers(
622        &self,
623        options: Option<&SaveMarkersInputOptions>,
624    ) -> Result<Response<entities::Marker>, Error>;
625
626    // ======================================
627    // notifications
628    // ======================================
629    /// Notifications concerning the user.
630    async fn get_notifications(
631        &self,
632        options: Option<&GetNotificationsInputOptions>,
633    ) -> Result<Response<Vec<entities::Notification>>, Error>;
634
635    /// Get a notification information.
636    async fn get_notification(&self, id: String)
637        -> Result<Response<entities::Notification>, Error>;
638
639    /// Clear all notifications from the server.
640    async fn dismiss_notifications(&self) -> Result<Response<()>, Error>;
641
642    /// Clear a notification from the server.
643    async fn dismiss_notification(&self, id: String) -> Result<Response<()>, Error>;
644
645    /// Mark as read all unread notifications.
646    async fn read_notifications(
647        &self,
648        options: &ReadNotificationsInputOptions,
649    ) -> Result<Response<()>, Error>;
650
651    // ======================================
652    // notifications/push
653    // ======================================
654    /// Add a Web Push API subscription to receive notifications.
655    async fn subscribe_push_notification(
656        &self,
657        subscription: &SubscribePushNotificationInputSubscription,
658        data: Option<&SubscribePushNotificationInputData>,
659    ) -> Result<Response<entities::PushSubscription>, Error>;
660
661    /// Get the PushSubscription currently associated with this access token.
662    async fn get_push_subscription(&self) -> Result<Response<entities::PushSubscription>, Error>;
663
664    /// Updates the current push subscription.
665    async fn update_push_subscription(
666        &self,
667        data: Option<&SubscribePushNotificationInputData>,
668    ) -> Result<Response<entities::PushSubscription>, Error>;
669
670    /// Removes the current Web Push API subscription.
671    async fn delete_push_subscription(&self) -> Result<Response<()>, Error>;
672
673    // ======================================
674    // search
675    // ======================================
676    /// Search for content in accounts, statuses and hashtags.
677    async fn search(
678        &self,
679        q: String,
680        options: Option<&SearchInputOptions>,
681    ) -> Result<Response<entities::Results>, Error>;
682
683    // ======================================
684    // instance
685    // ======================================
686    /// Get information about the server.
687    async fn get_instance(&self) -> Result<Response<entities::Instance>, Error>;
688
689    /// Get domains that this instance is aware of.
690    async fn get_instance_peers(&self) -> Result<Response<Vec<String>>, Error>;
691
692    /// Get instance activity over the last 3 months, binned weekly.
693    async fn get_instance_activity(&self) -> Result<Response<Vec<entities::Activity>>, Error>;
694
695    // ======================================
696    // instance/trends
697    // ======================================
698    /// Tags that are being used more frequently within the past week.
699    async fn get_instance_trends(
700        &self,
701        limit: Option<u32>,
702    ) -> Result<Response<Vec<entities::Tag>>, Error>;
703
704    // ======================================
705    // instance/directory
706    // ======================================
707    /// List accounts visible in the directory.
708    async fn get_instance_directory(
709        &self,
710        options: Option<&GetInstanceDirectoryInputOptions>,
711    ) -> Result<Response<Vec<entities::Account>>, Error>;
712
713    // ======================================
714    // instance/custom_emojis
715    // ======================================
716    /// Returns custom emojis that are available on the server.
717    async fn get_instance_custom_emojis(&self) -> Result<Response<Vec<entities::Emoji>>, Error>;
718
719    // ======================================
720    // instance/announcements
721    // ======================================
722    /// Get all currently active announcements set by admins.
723    async fn get_instance_announcements(
724        &self,
725    ) -> Result<Response<Vec<entities::Announcement>>, Error>;
726
727    /// Dismiss an announcement
728    async fn dismiss_instance_announcement(&self, id: String) -> Result<Response<()>, Error>;
729
730    /// Add a reaction to an announcement.
731    async fn add_reaction_to_announcement(
732        &self,
733        id: String,
734        name: String,
735    ) -> Result<Response<()>, Error>;
736
737    /// Remove a reaction from an announcement.
738    async fn remove_reaction_from_announcement(
739        &self,
740        id: String,
741        name: String,
742    ) -> Result<Response<()>, Error>;
743
744    // ======================================
745    // Emoji reactions
746    // ======================================
747    /// Add an emoji reaction to the status.
748    async fn create_emoji_reaction(
749        &self,
750        id: String,
751        emoji: String,
752    ) -> Result<Response<entities::Status>, Error>;
753
754    /// Remove the emoji reaction from the status.
755    async fn delete_emoji_reaction(
756        &self,
757        id: String,
758        emoji: String,
759    ) -> Result<Response<entities::Status>, Error>;
760
761    /// Get emoji reactions of the status.
762    async fn get_emoji_reactions(
763        &self,
764        id: String,
765    ) -> Result<Response<Vec<entities::Reaction>>, Error>;
766
767    /// Get emoji reaction of the status.
768    async fn get_emoji_reaction(
769        &self,
770        id: String,
771        emoji: String,
772    ) -> Result<Response<entities::Reaction>, Error>;
773
774    // ======================================
775    // Streaming
776    // ======================================
777    /// Get the base URL for streaming endpoints
778    async fn streaming_url(&self) -> String;
779
780    /// Get user streaming object.
781    async fn user_streaming(&self) -> Box<dyn Streaming + Send + Sync>;
782
783    /// Get public streaming object.
784    async fn public_streaming(&self) -> Box<dyn Streaming + Send + Sync>;
785
786    /// Get local streaming object.
787    async fn local_streaming(&self) -> Box<dyn Streaming + Send + Sync>;
788
789    /// Get direct streaming object.
790    async fn direct_streaming(&self) -> Box<dyn Streaming + Send + Sync>;
791
792    /// Get tag streaming object.
793    async fn tag_streaming(&self, tag: String) -> Box<dyn Streaming + Send + Sync>;
794
795    /// Get list streaming object.
796    async fn list_streaming(&self, list_id: String) -> Box<dyn Streaming + Send + Sync>;
797}
798
799/// Input options for [`Megalodon::register_app`] and [`Megalodon::create_app`].
800#[derive(Debug, Clone, Default)]
801pub struct AppInputOptions {
802    /// List of requested OAuth scopes.
803    pub scopes: Option<Vec<String>>,
804    /// Set a URI to redirect the user to.
805    pub redirect_uris: Option<String>,
806    /// URL of the application.
807    pub website: Option<String>,
808}
809
810/// Input options for [`Megalodon::update_credentials`].
811#[derive(Debug, Clone, Default)]
812pub struct UpdateCredentialsInputOptions {
813    /// Whether the account should be shown in the profile directory.
814    pub discoverable: Option<bool>,
815    /// Whether the account has a bot flag.
816    pub bot: Option<bool>,
817    /// The display name to use for the profile.
818    pub display_name: Option<String>,
819    /// The account bio.
820    pub note: Option<String>,
821    /// Avatar image encoded using multipart/form-data.
822    pub avatar: Option<String>,
823    /// Header image encoded using multipart/form-data.
824    pub header: Option<String>,
825    /// Whether manual approval of follow requests is required.
826    pub locked: Option<bool>,
827    /// Credential source options.
828    pub source: Option<CredentialsSource>,
829    /// Profile metadata array.
830    pub fields_attributes: Option<Vec<CredentialsFieldAttribute>>,
831}
832
833/// Credential source options.
834#[derive(Debug, Serialize, Clone, Default)]
835pub struct CredentialsSource {
836    /// Default post privacy for authored statuses.
837    pub privacy: Option<String>,
838    /// Whether to mark authored statuses as sensitive by default.
839    pub sensitive: Option<bool>,
840    /// Default language to use for authored statuses. (ISO 6391)
841    pub language: Option<String>,
842}
843
844/// Profile metadata array.
845#[derive(Debug, Serialize, Clone)]
846pub struct CredentialsFieldAttribute {
847    /// Name of the metadata.
848    pub name: String,
849    /// Value of the metadata.
850    pub value: String,
851}
852
853/// Input options for [`Megalodon::get_account_statuses`].
854#[derive(Debug, Clone, Default)]
855pub struct GetAccountStatusesInputOptions {
856    /// Maximum number of results to return.
857    pub limit: Option<u32>,
858    /// Return results older than this ID.
859    pub max_id: Option<String>,
860    /// Return results newer than this ID.
861    pub since_id: Option<String>,
862    /// Include pinned statuses.
863    pub pinned: Option<bool>,
864    /// Exclude statuses of replies.
865    pub exclude_replies: Option<bool>,
866    /// Exclude statuses of reblogged.
867    pub exclude_reblogs: Option<bool>,
868    /// Show only statuses with metia attached.
869    pub only_media: Option<bool>,
870    /// Show only public statuses.
871    pub only_public: Option<bool>,
872}
873
874/// Input options for [`Megalodon::get_account_favourites`].
875#[derive(Debug, Clone, Default)]
876pub struct GetAccountFavouritesInputOptions {
877    /// Maximum number of results to return.
878    pub limit: Option<u32>,
879    /// Return results older than this ID.
880    pub max_id: Option<String>,
881    /// Return results newer than this ID.
882    pub since_id: Option<String>,
883}
884
885/// Input options for [`Megalodon::get_account_followers`] and [`Megalodon::get_account_following`].
886#[derive(Debug, Clone, Default)]
887pub struct AccountFollowersInputOptions {
888    /// Maximum number of results to return.
889    pub limit: Option<u32>,
890    /// Return results older than this ID.
891    pub max_id: Option<String>,
892    /// Return results newer than this ID.
893    pub since_id: Option<String>,
894}
895
896/// Input options for [`Megalodon::follow_account`].
897#[derive(Debug, Clone, Default)]
898pub struct FollowAccountInputOptions {
899    /// Receive this account's reblogs in home timeline.
900    pub reblog: Option<bool>,
901    /// Receive notifications when this account posts a status.
902    pub notify: Option<bool>,
903}
904
905/// Input options for [`Megalodon::search_account`].
906#[derive(Debug, Clone, Default)]
907pub struct SearchAccountInputOptions {
908    /// Only who the user is following.
909    pub following: Option<bool>,
910    /// Attempt WebFinger lookup.
911    pub resolve: Option<bool>,
912    /// Maximum number of results to return.
913    pub limit: Option<u32>,
914    /// Return results older than this ID.
915    pub max_id: Option<String>,
916    /// Return results newer than this ID.
917    pub since_id: Option<String>,
918}
919
920/// Input options for [`Megalodon::get_bookmarks`].
921pub type GetBookmarksInputOptions = GetArrayWithSinceOptions;
922
923/// Input options for [`Megalodon::get_favourites`].
924pub type GetFavouritesInputOptions = GetArrayOptions;
925
926/// Input options for [`Megalodon::get_mutes`].
927pub type GetMutesInputOptions = GetArrayOptions;
928
929/// Input options for [`Megalodon::get_blocks`].
930pub type GetBlocksInputOptions = GetArrayOptions;
931
932/// Input options for [`Megalodon::get_domain_blocks`].
933pub type GetDomainBlocksInputOptions = GetArrayOptions;
934
935/// Get array options.
936#[derive(Debug, Clone, Default)]
937pub struct GetArrayOptions {
938    /// Maximum number of results to return.
939    pub limit: Option<u32>,
940    /// Return results older than this ID.
941    pub max_id: Option<String>,
942    /// Return results immediately newer than this ID.
943    pub min_id: Option<String>,
944}
945
946/// Get array options with since.
947#[derive(Debug, Clone, Default)]
948pub struct GetArrayWithSinceOptions {
949    /// Maximum number of results to return.
950    pub limit: Option<u32>,
951    /// Return results older than this ID.
952    pub max_id: Option<String>,
953    /// Return results newer than this ID.
954    pub since_id: Option<String>,
955    /// Return results immediately newer than this ID.
956    pub min_id: Option<String>,
957}
958
959/// Input options for [`Megalodon::create_filter`] and [`Megalodon::update_filter`].
960#[derive(Debug, Clone, Default)]
961pub struct FilterInputOptions {
962    /// Should the server irreversibly drop matching entities from home and notifications.
963    pub irreversible: Option<bool>,
964    /// Consider word boundaries.
965    pub whole_word: Option<bool>,
966    /// Number of seconds from now the filter should expire.
967    pub expires_in: Option<u64>,
968}
969
970/// Input options for [`Megalodon::report`].
971#[derive(Debug, Clone, Default)]
972pub struct ReportInputOptions {
973    /// Array of Statuses to attach to the report.
974    pub status_ids: Option<Vec<String>>,
975    /// The reason for the report. Default maximum of 1000 characters.
976    pub comment: Option<String>,
977    /// If the account is remote, should the report be forwarded to the remote admin.
978    pub forward: Option<bool>,
979    /// Specify if the report is due to spam, violation of enumerated instance rules, or some other reason. Defaults to other. Will be set to violation if rule_ids[] is provided (regardless of any category value you provide).
980    pub category: Option<entities::report::Category>,
981    /// For violation category reports, specify the ID of the exact rules broken. Rules and their IDs are available via GET /api/v1/instance/rules and GET /api/v1/instance.
982    pub rule_ids: Option<Vec<u64>>,
983}
984
985/// Input options for [`Megalodon::get_endorsements`].
986#[derive(Debug, Clone, Default)]
987pub struct GetEndorsementsInputOptions {
988    /// Maximum number of results to return.
989    pub limit: Option<u32>,
990    /// Return results older than this ID.
991    pub max_id: Option<String>,
992    /// Return results newer than this ID.
993    pub since_id: Option<String>,
994}
995
996/// Input options for [`Megalodon::post_status`].
997#[derive(Debug, Clone, Default)]
998pub struct PostStatusInputOptions {
999    /// Array of Attachment ids to be attached as media.
1000    pub media_ids: Option<Vec<String>>,
1001    /// Poll options.
1002    pub poll: Option<PollOptions>,
1003    /// ID of the status being replied to, if status is a reply.
1004    pub in_reply_to_id: Option<String>,
1005    /// Mark status and attached media as sensitive.
1006    pub sensitive: Option<bool>,
1007    /// Text to be shown as a warning or subject before the actual content.
1008    pub spoiler_text: Option<String>,
1009    /// Visibility of the posted status.
1010    pub visibility: Option<entities::status::StatusVisibility>,
1011    /// ISO 8601 Datetime at which to schedule a status.
1012    pub scheduled_at: Option<DateTime<Utc>>,
1013    /// ISO 639 language code for this status.
1014    pub language: Option<String>,
1015    /// ID of the status being quoted to.
1016    pub quote_id: Option<String>,
1017}
1018
1019/// Input options for [`Megalodon::edit_status`].
1020#[derive(Debug, Clone, Default)]
1021pub struct EditStatusInputOptions {
1022    /// The plain text content of the status.
1023    pub status: Option<String>,
1024    /// Text to be shown as a warning or subject before the actual content.
1025    pub spoiler_text: Option<String>,
1026    /// Mark status and attached media as sensitive.
1027    pub sensitive: Option<bool>,
1028    /// ISO 639 language code for this status.
1029    pub language: Option<String>,
1030    /// Array of Attachment ids to be attached as media.
1031    pub media_ids: Option<Vec<String>>,
1032    /// Poll options.
1033    pub poll: Option<PollOptions>,
1034}
1035
1036/// Poll options.
1037#[derive(Debug, Serialize, Clone, Default)]
1038pub struct PollOptions {
1039    /// Array of possible answers.
1040    pub options: Vec<String>,
1041    /// Duration the poll should be open, in seconds.
1042    pub expires_in: Option<u64>,
1043    /// Allow multiple choices.
1044    pub multiple: Option<bool>,
1045    /// Hide vote counts until the poll ends.
1046    pub hide_totals: Option<bool>,
1047}
1048
1049/// Input options for [`Megalodon::get_status_context`].
1050#[derive(Debug, Clone, Default)]
1051pub struct GetStatusContextInputOptions {
1052    /// Maximum number of results to return.
1053    pub limit: Option<u32>,
1054    /// REturn results older than this ID.
1055    pub max_id: Option<String>,
1056    /// Return results newer than this ID.
1057    pub since_id: Option<String>,
1058}
1059
1060/// Input options for [`Megalodon::upload_media`].
1061#[derive(Debug, Clone, Default)]
1062pub struct UploadMediaInputOptions {
1063    /// A plain-text description of the file.
1064    pub description: Option<String>,
1065    /// Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0.
1066    pub focus: Option<String>,
1067}
1068
1069/// Input options for [`Megalodon::update_media`].
1070#[derive(Debug, Clone, Default)]
1071pub struct UpdateMediaInputOptions {
1072    /// The file path to be attached.
1073    pub file_path: Option<String>,
1074    /// A plain-text description of the file.
1075    pub description: Option<String>,
1076    /// Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0.
1077    pub focus: Option<String>,
1078}
1079
1080/// Input options for [`Megalodon::get_scheduled_statuses`].
1081pub type GetScheduledStatusesInputOptions = GetArrayWithSinceOptions;
1082
1083/// Input options for [`Megalodon::get_public_timeline`].
1084pub type GetPublicTimelineInputOptions = GetTimelineOptions;
1085/// Input options for [`Megalodon::get_local_timeline`].
1086pub type GetLocalTimelineInputOptions = GetTimelineOptions;
1087/// Input options for [`Megalodon::get_tag_timeline`].
1088pub type GetTagTimelineInputOptions = GetTimelineOptionsWithLocal;
1089/// Input options for [`Megalodon::get_home_timeline`].
1090pub type GetHomeTimelineInputOptions = GetTimelineOptionsWithLocal;
1091/// Input options for [`Megalodon::get_list_timeline`].
1092pub type GetListTimelineInputOptions = GetArrayWithSinceOptions;
1093/// Input options for [`Megalodon::get_conversation_timeline`].
1094pub type GetConversationTimelineInputOptions = GetArrayWithSinceOptions;
1095
1096/// Input ptions for [`Megalodon::get_accounts_in_list`].
1097pub type GetAccountsInListInputOptions = GetArrayOptions;
1098
1099/// Timeline options.
1100#[derive(Debug, Clone, Default)]
1101pub struct GetTimelineOptions {
1102    /// Show only statuses with media attached.
1103    pub only_media: Option<bool>,
1104    /// Maximum number of results to return.
1105    pub limit: Option<u32>,
1106    /// Return results older than this ID.
1107    pub max_id: Option<String>,
1108    /// Return results newer than this ID.
1109    pub since_id: Option<String>,
1110    /// Return results immediately newer than this ID.
1111    pub min_id: Option<String>,
1112}
1113
1114/// Timeline options with local flag.
1115#[derive(Debug, Clone, Default)]
1116pub struct GetTimelineOptionsWithLocal {
1117    /// Show only statuses with media attached.
1118    pub only_media: Option<bool>,
1119    /// Maximum number of results to return.
1120    pub limit: Option<u32>,
1121    /// Return results older than this ID.
1122    pub max_id: Option<String>,
1123    /// Return results newer than this ID.
1124    pub since_id: Option<String>,
1125    /// Return results immediately newer than this ID.
1126    pub min_id: Option<String>,
1127    /// Show only local statuses.
1128    pub local: Option<bool>,
1129}
1130
1131/// Input options for [`Megalodon::save_markers`].
1132#[derive(Debug, Clone, Default)]
1133pub struct SaveMarkersInputOptions {
1134    /// ID of the last status read in the home timeline.
1135    pub home: Option<Marker>,
1136    /// ID of the last notification read.
1137    pub notifications: Option<Marker>,
1138}
1139
1140/// Marker of timelines.
1141#[derive(Debug, Serialize, Clone)]
1142pub struct Marker {
1143    /// ID of the last status read
1144    pub last_reading_id: String,
1145}
1146
1147/// Input options for [`Megalodon::get_notifications`].
1148#[derive(Debug, Clone, Default)]
1149pub struct GetNotificationsInputOptions {
1150    /// Maximum number of results to return. Default 20.
1151    pub limit: Option<u32>,
1152    /// Return results older than this ID.
1153    pub max_id: Option<String>,
1154    /// Return results newer than this ID.
1155    pub since_id: Option<String>,
1156    /// Return results immediately newer than this ID.
1157    pub min_id: Option<String>,
1158    /// Array of types to exclude.
1159    pub exclude_types: Option<Vec<entities::notification::NotificationType>>,
1160    /// Return only notifications received from this account.
1161    pub account_id: Option<String>,
1162}
1163
1164/// Input options for [`Megalodon::read_notifications`].
1165#[derive(Debug, Clone, Default)]
1166pub struct ReadNotificationsInputOptions {
1167    /// A single notification ID to read.
1168    pub id: Option<String>,
1169    /// Read all notifications up to this ID.
1170    pub max_id: Option<String>,
1171}
1172
1173/// Subscription input options for [`Megalodon::subscribe_push_notification`].
1174#[derive(Debug, Serialize, Clone)]
1175pub struct SubscribePushNotificationInputSubscription {
1176    /// Endpoint URL that is called when a notification event occurs.
1177    pub endpoint: String,
1178    /// Keys for subscription.
1179    pub keys: SubscriptionKeys,
1180}
1181
1182/// Keys for subscription.
1183#[derive(Debug, Serialize, Clone)]
1184pub struct SubscriptionKeys {
1185    /// User agent public key. Base64 encoded string of public key of ECDH key using prime256v1 curve.1
1186    pub p256h: String,
1187    /// Auth secret. Base64 encoded string of 16 bytes of random data.
1188    pub auth: String,
1189}
1190
1191/// Input data of [`Megalodon::subscribe_push_notification`].
1192#[derive(Debug, Serialize, Clone, Default)]
1193pub struct SubscribePushNotificationInputData {
1194    /// Alert options.
1195    pub alerts: Option<DataAlerts>,
1196}
1197
1198/// Alert options.
1199#[derive(Debug, Serialize, Clone, Default)]
1200pub struct DataAlerts {
1201    /// Receive follow notification.
1202    pub follow: Option<bool>,
1203    /// Receive favourite notification.
1204    pub favourite: Option<bool>,
1205    /// Receive reblog notification.
1206    pub reblog: Option<bool>,
1207    /// Receive mention notification.
1208    pub mention: Option<bool>,
1209    /// Receive poll notification.
1210    pub poll: Option<bool>,
1211}
1212
1213/// Type of search results.
1214#[derive(Debug, Clone)]
1215pub enum SearchType {
1216    /// Search accounts.
1217    Accounts,
1218    /// Search hash tags.
1219    Hashtags,
1220    /// Search statuses.
1221    Statuses,
1222}
1223
1224impl fmt::Display for SearchType {
1225    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1226        match self {
1227            SearchType::Accounts => write!(f, "accounts"),
1228            SearchType::Hashtags => write!(f, "hashtags"),
1229            SearchType::Statuses => write!(f, "statuses"),
1230        }
1231    }
1232}
1233
1234impl FromStr for SearchType {
1235    type Err = Error;
1236
1237    fn from_str(s: &str) -> Result<Self, Self::Err> {
1238        match s {
1239            "accounts" => Ok(SearchType::Accounts),
1240            "hashtags" => Ok(SearchType::Hashtags),
1241            "statuses" => Ok(SearchType::Statuses),
1242            _ => Err(Error::new_own(
1243                s.to_owned(),
1244                Kind::ParseError,
1245                None,
1246                None,
1247                None,
1248            )),
1249        }
1250    }
1251}
1252
1253/// Input options for [`Megalodon::search`].
1254#[derive(Debug, Clone, Default)]
1255pub struct SearchInputOptions {
1256    /// Specify whether to search for only accounts, hashtags, statuses.
1257    pub r#type: Option<SearchType>,
1258    /// Maximum number of results. Default 20, max 40.
1259    pub limit: Option<u32>,
1260    /// Return results oder than this id.
1261    pub max_id: Option<String>,
1262    /// Return results newer than this id.
1263    pub min_id: Option<String>,
1264    /// Attempt WebFinger lookup. Defaults to false.
1265    pub resolve: Option<bool>,
1266    /// Offset in search results. Used for pagination. Defaults to 0.
1267    pub offset: Option<u64>,
1268    /// Only include accounts that the user is following. Defaults to false.
1269    pub following: Option<bool>,
1270    /// If provided, statuses returned will be authored only by this account
1271    pub account_id: Option<String>,
1272    /// Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags.
1273    pub exclude_unreviewed: Option<bool>,
1274}
1275
1276/// Input options for [`Megalodon::get_instance_directory`].
1277#[derive(Debug, Clone, Default)]
1278pub struct GetInstanceDirectoryInputOptions {
1279    /// How many accounts to load. Default 40.
1280    pub limit: Option<u32>,
1281    /// How many accounts to skip before returning results. Default 0.
1282    pub offset: Option<u64>,
1283    /// Sort options of accounts.
1284    pub order: Option<Order>,
1285    /// Only returns local accounts.
1286    pub local: Option<bool>,
1287}
1288
1289/// Sort option of accounts.
1290#[derive(Debug, Clone)]
1291pub enum Order {
1292    /// Active to sort by most recently posted statuses.
1293    Active,
1294    /// New to sort by most recently created profiles.
1295    New,
1296}
1297
1298impl fmt::Display for Order {
1299    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1300        match self {
1301            Order::Active => write!(f, "active"),
1302            Order::New => write!(f, "new"),
1303        }
1304    }
1305}
1306
1307impl FromStr for Order {
1308    type Err = Error;
1309
1310    fn from_str(s: &str) -> Result<Self, Self::Err> {
1311        match s {
1312            "active" => Ok(Order::Active),
1313            "new" => Ok(Order::New),
1314            _ => Err(Error::new_own(
1315                s.to_owned(),
1316                Kind::ParseError,
1317                None,
1318                None,
1319                None,
1320            )),
1321        }
1322    }
1323}
1324
1325/// FollowRequest output object. It is FollowRequest object only if Friendica, otherwise it is Account object.
1326#[derive(Debug, Clone)]
1327pub enum FollowRequestOutput {
1328    /// Account object for Mastodon and Pleroma.
1329    Account(entities::Account),
1330    /// FollowRequest object for Friendica.
1331    FollowRequest(entities::FollowRequest),
1332}
1333
1334/// PostStatus output object. When the scheduled_at is specified, it returns ScheduledStatus object. Otherwise, it returns Status object.
1335#[derive(Debug, Clone)]
1336pub enum PostStatusOutput {
1337    /// Status object for normal post results.
1338    Status(entities::Status),
1339    /// ScheduleStatus object for scheduled_at is specified.
1340    ScheduledStatus(entities::ScheduledStatus),
1341}
megalodon/megalodon.rs

megalodon/
megalodon.rs
