nextcloud-client 0.211.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1 @@
1
+ """Data models returned by the Nextcloud app clients."""
@@ -0,0 +1,302 @@
1
+ from datetime import datetime
2
+ from typing import Any, Dict, List, Optional, Union
3
+
4
+ from pydantic import BaseModel, Field, field_validator
5
+
6
+
7
+ class DeckUser(BaseModel):
8
+ primaryKey: str
9
+ uid: str
10
+ displayname: str
11
+
12
+
13
+ class DeckPermissions(BaseModel):
14
+ PERMISSION_READ: bool
15
+ PERMISSION_EDIT: bool
16
+ PERMISSION_MANAGE: bool
17
+ PERMISSION_SHARE: bool
18
+
19
+
20
+ #: Shared wording for the deep links, so every Deck response describes them the
21
+ #: same way. Populated by ``links.with_links``; see ADR-035. Deck has no route
22
+ #: that opens a single stack, so a stack links to its board.
23
+ BOARD_URL_DESCRIPTION = (
24
+ "Link that opens this board in the Nextcloud Deck app. None when the server "
25
+ "has no browser-reachable Nextcloud base URL configured."
26
+ )
27
+ CARD_URL_DESCRIPTION = (
28
+ "Link that opens this card in the Nextcloud Deck app. Offer it to the user "
29
+ "when referring to the card so they can open it in place. None when the "
30
+ "server has no browser-reachable Nextcloud base URL configured, or when the "
31
+ "card's board is not known from the response or the tool's arguments."
32
+ )
33
+
34
+
35
+ ATTACHMENT_URL_DESCRIPTION = (
36
+ "Link that opens this attachment. For type='file' attachments that is the "
37
+ "shared file in Nextcloud's Files UI; for type='deck_file' it is Deck's own "
38
+ "download route. None when the server has no browser-reachable Nextcloud "
39
+ "base URL configured."
40
+ )
41
+
42
+
43
+ class DeckLabel(BaseModel):
44
+ id: int
45
+ title: str
46
+ color: str
47
+ boardId: Optional[int] = None
48
+ cardId: Optional[int] = None
49
+
50
+
51
+ class DeckACL(BaseModel):
52
+ id: int
53
+ participant: DeckUser
54
+ type: int
55
+ boardId: int
56
+ permissionEdit: bool
57
+ permissionShare: bool
58
+ permissionManage: bool
59
+ owner: bool
60
+
61
+
62
+ class DeckBoardSettings(BaseModel):
63
+ calendar: bool
64
+ cardDetailsInModal: Optional[bool] = Field(default=None, alias="cardDetailsInModal")
65
+ cardIdBadge: Optional[bool] = Field(default=None, alias="cardIdBadge")
66
+ groupLimit: Optional[List[Dict[str, str]]] = Field(default=None, alias="groupLimit")
67
+ notify_due: Optional[str] = Field(default=None, alias="notify-due")
68
+
69
+
70
+ class DeckBoard(BaseModel):
71
+ id: int
72
+ title: str
73
+ owner: DeckUser
74
+ color: str
75
+ archived: bool
76
+ labels: List[DeckLabel]
77
+ acl: List[DeckACL]
78
+ permissions: DeckPermissions
79
+ users: List[DeckUser]
80
+ deletedAt: int
81
+ lastModified: Optional[int] = None
82
+ url: str | None = Field(default=None, description=BOARD_URL_DESCRIPTION)
83
+ settings: Optional[DeckBoardSettings] = None
84
+ etag: Optional[str] = Field(default=None, alias="ETag")
85
+
86
+ @field_validator("settings", mode="before")
87
+ @classmethod
88
+ def validate_settings(cls, v):
89
+ # Handle case where API returns empty array instead of dict/null
90
+ if isinstance(v, list) and len(v) == 0:
91
+ return None
92
+ return v
93
+
94
+
95
+ class DeckAssignedUser(BaseModel):
96
+ id: int
97
+ participant: DeckUser
98
+ cardId: int
99
+ type: int
100
+
101
+
102
+ class DeckCard(BaseModel):
103
+ id: int
104
+ title: str
105
+ stackId: int
106
+ type: str
107
+ order: int
108
+ archived: bool
109
+ owner: Union[str, DeckUser] # Can be either string or user object
110
+ description: Optional[str] = None
111
+ duedate: Optional[datetime] = None
112
+ startdate: Optional[datetime] = None # Deck >= 1.18
113
+ done: Optional[datetime] = None
114
+ color: Optional[str] = None # Deck >= 1.18; bare hex, e.g. "FF0000"
115
+ lastModified: Optional[int] = None
116
+ createdAt: Optional[int] = None
117
+ labels: Optional[List[DeckLabel]] = None
118
+ assignedUsers: Optional[List[Union[DeckUser, DeckAssignedUser]]] = None
119
+ dependentCards: Optional[List[int]] = None # IDs of cards this card depends on
120
+ attachments: Optional[List["DeckAttachment"]] = None
121
+ attachmentCount: Optional[int] = None
122
+ deletedAt: Optional[int] = None
123
+ commentsUnread: Optional[int] = None
124
+ commentsCount: Optional[int] = None
125
+ lastEditor: Optional[str] = None
126
+ overdue: Optional[int] = None
127
+ etag: Optional[str] = Field(default=None, alias="ETag")
128
+ url: str | None = Field(default=None, description=CARD_URL_DESCRIPTION)
129
+
130
+ @field_validator("owner", mode="before")
131
+ @classmethod
132
+ def validate_owner(cls, v):
133
+ # Handle case where API returns user object instead of string
134
+ if isinstance(v, dict):
135
+ return v.get("uid", v.get("primaryKey", str(v)))
136
+ return v
137
+
138
+ @field_validator("assignedUsers", mode="before")
139
+ @classmethod
140
+ def validate_assigned_users(cls, v):
141
+ # Handle different formats of assigned users from the API
142
+ if not v:
143
+ return v
144
+
145
+ validated_users = []
146
+ for user in v:
147
+ if isinstance(user, dict):
148
+ # Check if it's an assignment object with participant
149
+ if "participant" in user:
150
+ validated_users.append(user)
151
+ # Check if it's a direct user object
152
+ elif "uid" in user or "primaryKey" in user:
153
+ validated_users.append(user)
154
+ else:
155
+ validated_users.append(user)
156
+
157
+ return validated_users
158
+
159
+
160
+ class DeckCardSummary(BaseModel):
161
+ """Compact projection of a :class:`DeckCard` for list/overview views.
162
+
163
+ Drops the heavy fields that dominate token cost when many cards are
164
+ returned at once — the full ``description`` (kept only as a short
165
+ ``descriptionPreview``), the nested ``labels``/``assignedUsers``/
166
+ ``attachments`` objects (kept as flat title/uid lists + counts), and the
167
+ ``etag``/``order``/``*Modified``/``createdAt``/``deletedAt``/``overdue``/
168
+ ``type``/``owner`` bookkeeping fields. Fetch a single card with
169
+ ``deck_get_card`` (or ``detail="full"``) when the full body is needed.
170
+ """
171
+
172
+ id: int
173
+ title: str
174
+ stackId: int
175
+ archived: bool = False
176
+ duedate: datetime | None = None
177
+ startdate: datetime | None = None
178
+ done: datetime | None = None
179
+ color: str | None = Field(default=None, description="Card color (bare hex)")
180
+ labels: list[str] = Field(
181
+ default_factory=list, description="Label titles assigned to the card"
182
+ )
183
+ assignedUsers: list[str] = Field(
184
+ default_factory=list, description="UIDs of users assigned to the card"
185
+ )
186
+ attachmentCount: int | None = Field(
187
+ default=None, description="Number of attachments on the card"
188
+ )
189
+ commentsUnread: int | None = Field(
190
+ default=None, description="Number of unread comments"
191
+ )
192
+ commentsCount: int | None = Field(
193
+ default=None, description="Total number of comments"
194
+ )
195
+ hasDescription: bool = Field(
196
+ default=False, description="Whether the card has a non-empty description"
197
+ )
198
+ descriptionPreview: str | None = Field(
199
+ default=None, description="Truncated preview of the card description"
200
+ )
201
+ url: str | None = Field(default=None, description=CARD_URL_DESCRIPTION)
202
+
203
+
204
+ class DeckStack(BaseModel):
205
+ id: int
206
+ title: str
207
+ boardId: int
208
+ order: int
209
+ deletedAt: int
210
+ lastModified: Optional[int] = None
211
+ # Cards may be projected to DeckCardSummary when a tool is called with
212
+ # detail="summary" (the default for list tools).
213
+ cards: list[DeckCard | DeckCardSummary] | None = None
214
+ etag: Optional[str] = Field(default=None, alias="ETag")
215
+ url: str | None = Field(
216
+ default=None,
217
+ description=(
218
+ "Link that opens this stack's board in the Nextcloud Deck app; Deck "
219
+ "has no route that opens a single stack. None when the server has no "
220
+ "browser-reachable Nextcloud base URL configured."
221
+ ),
222
+ )
223
+
224
+
225
+ class DeckAttachmentExtendedData(BaseModel):
226
+ # Every field is optional: Deck leaves extendedData empty when the
227
+ # underlying file is gone or unreadable (FileService/FilesAppService
228
+ # extendData bail out), which happens routinely for deleted attachments.
229
+ filesize: int | None = None
230
+ mimetype: str | None = None
231
+ info: Dict[str, str] = Field(default_factory=dict)
232
+ # Populated for type="file" (Files share) attachments via FilesAppService.
233
+ path: str | None = None
234
+ fileid: int | None = None
235
+ hasPreview: bool | None = None
236
+ permissions: int | None = None
237
+
238
+ @field_validator("info", mode="before")
239
+ @classmethod
240
+ def validate_info(cls, v):
241
+ # PHP serialises an empty pathinfo() as [], not {}.
242
+ return v or {}
243
+
244
+
245
+ class DeckAttachment(BaseModel):
246
+ id: int
247
+ cardId: int
248
+ type: str
249
+ data: str
250
+ lastModified: int
251
+ createdAt: int
252
+ createdBy: str
253
+ deletedAt: int
254
+ extendedData: DeckAttachmentExtendedData = Field(
255
+ default_factory=DeckAttachmentExtendedData
256
+ )
257
+ url: str | None = Field(default=None, description=ATTACHMENT_URL_DESCRIPTION)
258
+
259
+ @field_validator("extendedData", mode="before")
260
+ @classmethod
261
+ def validate_extended_data(cls, v):
262
+ return v or {}
263
+
264
+
265
+ class DeckComment(BaseModel):
266
+ id: int
267
+ objectId: int
268
+ message: str
269
+ actorId: str
270
+ actorType: str
271
+ actorDisplayName: str
272
+ creationDateTime: datetime
273
+ mentions: List[Dict[str, str]]
274
+ replyTo: Optional[Any] = None # Self-referencing, handle later if needed
275
+
276
+
277
+ class DeckCommentSummary(BaseModel):
278
+ """Compact projection of a :class:`DeckComment` for list views.
279
+
280
+ Drops ``mentions``, ``actorType``, ``actorDisplayName`` and ``replyTo``,
281
+ keeping only the fields needed to read the conversation. Long messages are
282
+ truncated by the tool layer via ``message_max_length``.
283
+ """
284
+
285
+ id: int
286
+ actorId: str
287
+ message: str
288
+ creationDateTime: datetime
289
+
290
+
291
+ class DeckSession(BaseModel):
292
+ token: str
293
+
294
+
295
+ class DeckConfig(BaseModel):
296
+ calendar: bool
297
+ cardDetailsInModal: bool
298
+ cardIdBadge: bool
299
+ groupLimit: Optional[List[Dict[str, str]]] = None
300
+
301
+
302
+ # Response Models for MCP Tools
@@ -0,0 +1,24 @@
1
+ """Pydantic models for Nextcloud sharing responses."""
2
+
3
+ from enum import IntEnum
4
+
5
+
6
+ class ShareType(IntEnum):
7
+ """OCS ``shareType`` values.
8
+
9
+ An ``IntEnum`` so it stays interchangeable with the bare ints the OCS API
10
+ and our tool signatures use.
11
+
12
+ Every type addresses a named recipient except :attr:`PUBLIC_LINK`, which
13
+ addresses nobody — see ``validate_share_with`` in the sharing client for
14
+ why that distinction has to be enforced before the request is sent.
15
+ """
16
+
17
+ USER = 0
18
+ GROUP = 1
19
+ PUBLIC_LINK = 3
20
+ EMAIL = 4
21
+ FEDERATED = 6
22
+ CIRCLE = 7
23
+ TALK_CONVERSATION = 10
24
+ DECK_CARD = 12
@@ -0,0 +1,136 @@
1
+ """Pydantic models for the Nextcloud Talk (spreed) integration."""
2
+
3
+ from typing import Any, Literal
4
+
5
+ from pydantic import BaseModel, ConfigDict, Field, field_validator
6
+
7
+ #: The actor sources spreed accepts when adding a participant. A ``Literal``
8
+ #: rather than a bare ``str`` so an unsupported source is rejected by the schema
9
+ #: -- and appears as an enum in the MCP tool definition -- instead of reaching
10
+ #: the server as a bare 400 that names no field.
11
+ TalkParticipantSource = Literal[
12
+ "users", "groups", "emails", "circles", "federated_users"
13
+ ]
14
+
15
+ #: The room types spreed accepts: 1=one-to-one, 2=group, 3=public. A ``Literal``
16
+ #: for the same reason as the source above.
17
+ TalkRoomType = Literal[1, 2, 3]
18
+
19
+ # Domain models
20
+
21
+
22
+ class TalkMessage(BaseModel):
23
+ """A single chat message in a Talk conversation.
24
+
25
+ See spreed docs/chat.md for the field definitions. We map only the
26
+ fields that are useful to MCP consumers; spreed returns more.
27
+ """
28
+
29
+ id: int
30
+ token: str
31
+ actorType: str
32
+ actorId: str
33
+ actorDisplayName: str
34
+ timestamp: int
35
+ systemMessage: str = ""
36
+ messageType: str
37
+ message: str
38
+ messageParameters: dict[str, Any] = Field(default_factory=dict)
39
+ expirationTimestamp: int | None = None
40
+ referenceId: str | None = None
41
+ markdown: bool | None = None
42
+ # Present when the room's spreed "threads" feature is enabled (OCS
43
+ # capability spreed.features includes "threads"); undocumented in
44
+ # docs/chat.md at the time of writing. threadId is the id of the
45
+ # thread's root message; isThread is True on that root message itself.
46
+ threadId: int | None = None
47
+ isThread: bool | None = None
48
+
49
+ @field_validator("messageParameters", mode="before")
50
+ @classmethod
51
+ def _coerce_empty_list_params(cls, v: Any) -> Any:
52
+ # spreed serializes an empty parameter map as `[]` (PHP array) rather
53
+ # than `{}`; normalize so pydantic accepts it as a dict.
54
+ if isinstance(v, list) and not v:
55
+ return {}
56
+ return v
57
+
58
+
59
+ class TalkConversation(BaseModel):
60
+ """A Talk conversation (room).
61
+
62
+ See spreed docs/conversation.md for the full field reference. Many
63
+ optional fields are omitted; we keep the ones useful for chat-centric
64
+ flows.
65
+ """
66
+
67
+ # ``populate_by_name=True`` lets us deserialize spreed's ``type`` key
68
+ # into the ``room_type`` field while still allowing internal callers
69
+ # to construct the model with ``room_type=...`` directly.
70
+ model_config = ConfigDict(populate_by_name=True)
71
+
72
+ id: int
73
+ token: str
74
+ # The spreed JSON wire format uses ``type`` for the room kind, but
75
+ # ``type`` shadows Python's builtin within the class scope, which
76
+ # would silently call this int field if anyone wrote ``type(...)``
77
+ # in a validator or method on this model. Map to ``room_type`` and
78
+ # alias the wire field instead.
79
+ room_type: int = Field(
80
+ alias="type",
81
+ description=(
82
+ "Conversation kind: 1=one-to-one, 2=group, 3=public, "
83
+ "4=changelog, 5=former one-to-one, 6=note-to-self."
84
+ ),
85
+ )
86
+ name: str
87
+ displayName: str
88
+ description: str = ""
89
+ participantType: int | None = None
90
+ unreadMessages: int = 0
91
+ unreadMention: bool = False
92
+ lastActivity: int | None = None
93
+ # spreed returns `0` (not `null`) when the user has not read any
94
+ # message in the room yet — compare to ``None`` explicitly rather
95
+ # than relying on truthiness, since `0` is falsy but valid.
96
+ lastReadMessage: int | None = None
97
+ lastMessage: TalkMessage | None = None
98
+ readOnly: int | None = None
99
+ isFavorite: bool | None = None
100
+ notificationLevel: int | None = None
101
+ objectType: str | None = None
102
+ objectId: str | None = None
103
+
104
+ @field_validator("lastMessage", mode="before")
105
+ @classmethod
106
+ def _coerce_empty_last_message(cls, v: Any) -> Any:
107
+ # spreed returns `lastMessage: []` (PHP empty array) when there has
108
+ # never been a message in the room; normalize to None.
109
+ if isinstance(v, list) and not v:
110
+ return None
111
+ return v
112
+
113
+
114
+ class TalkParticipant(BaseModel):
115
+ """A participant (attendee) in a Talk conversation."""
116
+
117
+ attendeeId: int
118
+ actorType: str
119
+ actorId: str
120
+ displayName: str
121
+ participantType: int
122
+ inCall: int = 0
123
+ lastPing: int = 0
124
+ sessionIds: list[str] = Field(default_factory=list)
125
+ status: str | None = None
126
+ statusIcon: str | None = None
127
+ statusMessage: str | None = None
128
+
129
+
130
+ class TalkReactionActor(BaseModel):
131
+ """One actor's reaction to a chat message."""
132
+
133
+ actorType: str
134
+ actorId: str
135
+ actorDisplayName: str = ""
136
+ timestamp: int = 0
@@ -0,0 +1,41 @@
1
+ from typing import Any, Dict, List, Optional, Union
2
+
3
+ from pydantic import BaseModel, ConfigDict, Field
4
+
5
+
6
+ class User(BaseModel):
7
+ """Model for creating a new user."""
8
+
9
+ userid: str
10
+ password: Optional[str] = None
11
+ displayName: Optional[str] = None
12
+ email: Optional[str] = None
13
+ groups: Optional[List[str]] = Field(default_factory=list)
14
+ subadmin: Optional[List[str]] = Field(default_factory=list)
15
+ quota: Optional[str] = None
16
+ language: Optional[str] = None
17
+
18
+
19
+ class UserDetails(BaseModel):
20
+ """Model for retrieving detailed user information."""
21
+
22
+ model_config = ConfigDict(populate_by_name=True)
23
+
24
+ enabled: bool
25
+ id: str
26
+ quota: Union[str, Dict[str, Any]] # Can be string or quota object
27
+ email: Optional[str] = None # Can be null
28
+ displayname: str = Field(
29
+ alias="display-name"
30
+ ) # Handle both displayname and display-name
31
+ phone: Optional[str] = None
32
+ address: Optional[str] = None
33
+ website: Optional[str] = None
34
+ twitter: Optional[str] = None
35
+ groups: Optional[List[str]] = Field(default_factory=list)
36
+
37
+
38
+ class Group(BaseModel):
39
+ """Model for a user group."""
40
+
41
+ id: str