hypothesis_rs/
groups.rs

1//! Objects related to the "groups" endpoint
2
3use serde::{Deserialize, Serialize};
4#[cfg(feature = "cli")]
5use structopt::StructOpt;
6
7use crate::is_default;
8
9/// Which field to expand
10#[derive(Serialize, Debug, Clone, PartialEq)]
11#[serde(rename_all = "lowercase")]
12pub enum Expand {
13    /// Expand `organization` field to `Org`
14    Organization,
15    /// Expand `scopes` field to `Scope`
16    Scopes,
17}
18
19/// Filter groups by authority and target document
20#[cfg_attr(feature = "cli", derive(StructOpt))]
21#[derive(Serialize, Debug, Default, Clone, PartialEq)]
22pub struct GroupFilters {
23    /// Filter returned groups to this authority.
24    /// For authenticated requests, the user's associated authority will supersede any provided value.
25    ///
26    /// Default: "hypothes.is"
27    #[serde(skip_serializing_if = "is_default")]
28    #[cfg_attr(feature = "cli", structopt(default_value = "hypothes.is", long))]
29    pub authority: String,
30    /// Only retrieve public (i.e. non-private) groups that apply to a given document URI (i.e. the target document being annotated).
31    #[serde(skip_serializing_if = "is_default")]
32    #[cfg_attr(feature = "cli", structopt(default_value, long))]
33    pub document_uri: String,
34    /// One or more relations to expand for a group resource.
35    /// Possible values: organization, scopes
36    #[serde(skip_serializing_if = "is_default")]
37    #[cfg_attr(feature = "cli", structopt(long, possible_values = & Expand::variants()))]
38    pub expand: Vec<Expand>,
39}
40
41/// URL to the group's main (activity) page
42#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
43pub struct Links {
44    /// URL to the group's main (activity) page
45    #[serde(default)]
46    pub html: Option<String>,
47}
48
49/// See [the Hypothesis API docs](https://h.readthedocs.io/en/latest/api-reference/v1/#tag/groups/paths/~1groups/get) for more information.
50#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
51pub struct Scope {
52    pub enforced: bool,
53    pub uri_patterns: Vec<String>,
54}
55
56/// Group type
57#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
58#[serde(rename_all = "lowercase")]
59pub enum Type {
60    /// Only creator can view and edit
61    Private,
62    /// Anyone can view and edit
63    Open,
64    /// More than one user can view and edit
65    Restricted,
66}
67
68/// Information about an organization
69/// Can be just the organization ID,
70/// an `Org` struct,
71/// or None if user is not authorized to access this organization
72#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
73#[serde(untagged)]
74pub enum Organization {
75    /// Unexpanded = Unique organization ID
76    String(String),
77    /// Expanded (None if not authorized)
78    Organization(Option<Org>),
79}
80
81/// Information about an organization
82#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
83pub struct Org {
84    /// Organization ID
85    pub id: String,
86    /// true if this organization is the default organization for the current authority
87    pub default: bool,
88    /// URI to logo image; may be null if no logo exists
89    pub logo: Option<String>,
90    /// Organization name
91    pub name: String,
92}
93
94/// Information returned about a Group resource
95#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
96pub struct Group {
97    /// Group ID
98    pub id: String,
99    /// Authority-unique identifier that may be set for groups that are owned by a third-party authority.
100    /// This field is currently present but unused for first-party-authority groups.
101    pub groupid: Option<String>,
102    /// Group name
103    pub name: String,
104    /// URL to the group's main (activity) page
105    pub links: Links,
106    /// The organization to which this group belongs.
107    pub organization: Organization,
108    #[serde(default)]
109    /// Information about the URL restrictions for annotations within this group.
110    pub scopes: Option<Scope>,
111    /// Whether or not this group has URL restrictions for documents that may be annotated within it.
112    /// Non-scoped groups allow annotation to documents at any URL
113    pub scoped: bool,
114    /// Is the groyp private, open, or restricted
115    #[serde(rename = "type")]
116    pub group_type: Type,
117}
118
119/// Information about another user
120#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
121pub struct Member {
122    /// "hypothes.is"
123    pub authority: String,
124    /// string [ 3 .. 30 ] characters ^[A-Za-z0-9._]+$
125    pub username: String,
126    /// string^acct:.+$
127    pub userid: String,
128    /// string <= 30 characters
129    #[serde(default)]
130    pub display_name: Option<String>,
131}
hypothesis_rs/groups.rs

hypothesis_rs/
groups.rs
