1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Objects related to the "groups" endpoint

use serde::{Deserialize, Serialize};
#[cfg(feature = "cli")]
use structopt::StructOpt;

use crate::is_default;

/// Which field to expand
#[derive(Serialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum Expand {
    /// Expand `organization` field to `Org`
    Organization,
    /// Expand `scopes` field to `Scope`
    Scopes,
}

/// Filter groups by authority and target document
#[cfg_attr(feature = "cli", derive(StructOpt))]
#[derive(Serialize, Debug, Default, Clone, PartialEq)]
pub struct GroupFilters {
    /// Filter returned groups to this authority.
    /// For authenticated requests, the user's associated authority will supersede any provided value.
    ///
    /// Default: "hypothes.is"
    #[serde(skip_serializing_if = "is_default")]
    #[cfg_attr(feature = "cli", structopt(default_value = "hypothes.is", long))]
    pub authority: String,
    /// Only retrieve public (i.e. non-private) groups that apply to a given document URI (i.e. the target document being annotated).
    #[serde(skip_serializing_if = "is_default")]
    #[cfg_attr(feature = "cli", structopt(default_value, long))]
    pub document_uri: String,
    /// One or more relations to expand for a group resource.
    /// Possible values: organization, scopes
    #[serde(skip_serializing_if = "is_default")]
    #[cfg_attr(feature = "cli", structopt(long, possible_values = & Expand::variants()))]
    pub expand: Vec<Expand>,
}

/// URL to the group's main (activity) page
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Links {
    /// URL to the group's main (activity) page
    #[serde(default)]
    pub html: Option<String>,
}

/// See [the Hypothesis API docs](https://h.readthedocs.io/en/latest/api-reference/v1/#tag/groups/paths/~1groups/get) for more information.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Scope {
    pub enforced: bool,
    pub uri_patterns: Vec<String>,
}

/// Group type
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Type {
    /// Only creator can view and edit
    Private,
    /// Anyone can view and edit
    Open,
    /// More than one user can view and edit
    Restricted,
}

/// Information about an organization
/// Can be just the organization ID,
/// an `Org` struct,
/// or None if user is not authorized to access this organization
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(untagged)]
pub enum Organization {
    /// Unexpanded = Unique organization ID
    String(String),
    /// Expanded (None if not authorized)
    Organization(Option<Org>),
}

/// Information about an organization
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Org {
    /// Organization ID
    pub id: String,
    /// true if this organization is the default organization for the current authority
    pub default: bool,
    /// URI to logo image; may be null if no logo exists
    pub logo: Option<String>,
    /// Organization name
    pub name: String,
}

/// Information returned about a Group resource
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Group {
    /// Group ID
    pub id: String,
    /// Authority-unique identifier that may be set for groups that are owned by a third-party authority.
    /// This field is currently present but unused for first-party-authority groups.
    pub groupid: Option<String>,
    /// Group name
    pub name: String,
    /// URL to the group's main (activity) page
    pub links: Links,
    /// The organization to which this group belongs.
    pub organization: Organization,
    #[serde(default)]
    /// Information about the URL restrictions for annotations within this group.
    pub scopes: Option<Scope>,
    /// Whether or not this group has URL restrictions for documents that may be annotated within it.
    /// Non-scoped groups allow annotation to documents at any URL
    pub scoped: bool,
    /// Is the groyp private, open, or restricted
    #[serde(rename = "type")]
    pub group_type: Type,
}

/// Information about another user
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Member {
    /// "hypothes.is"
    pub authority: String,
    /// string [ 3 .. 30 ] characters ^[A-Za-z0-9._]+$
    pub username: String,
    /// string^acct:.+$
    pub userid: String,
    /// string <= 30 characters
    #[serde(default)]
    pub display_name: Option<String>,
}