Skip to content

Commit 964bf35

Browse files
committed
feat: sync to backend 0.3.0 (communities)
- new communities and invitations resources (async + generated sync) - admin roles replaced by scoped permissions (grant/revoke) - whoami returns permissions; posts accept community/cross_post_source - bump to 0.3.0; regenerate types from the 0.3.0 spec
1 parent 847a210 commit 964bf35

31 files changed

Lines changed: 5173 additions & 444 deletions

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
## [Unreleased]
1111

12+
## [0.3.0] - 2026-09-18
13+
14+
Syncs the SDK with the backend's communities work (COMMUNITY_PLAN.md).
15+
16+
### Added
17+
18+
- **`client.communities`** — the community directory and membership surface: `create`, `list` / `iter`, `get`, `update`, `join`, `leave`, `members` / `iter_members`, `kick`, `posts` / `iter_posts`, `close`, `set_successor`, `invite`, `applications` / `iter_applications`, `apply`, `accept_application`, and `reject_application`.
19+
- **`client.invitations`** — the authenticated actor's invitation inbox: `list` / `iter`, `accept`, and `decline`.
20+
- `community` and `cross_post_source` arguments on `client.posts.create()`. A cross-post is a read-time reference, never a copy.
21+
- `community` and `delete_posts` arguments on `client.admin.bans.create()`; `community` on `client.admin.bans.remove()`.
22+
- **`client.admin.permissions`** with `grant()` (`PUT /admin/permissions`) and `revoke()` (`DELETE /admin/permissions`), both accepting an optional `community` scope.
23+
- `Community`, `CommunityMember`, `Invitation`, `Application`, and `Permission` convenience aliases, plus the `CommunityVisibility` and `ApplicationStatus` literal types.
24+
25+
### Changed
26+
27+
- **`WhoamiResponse.roles` was replaced by `WhoamiResponse.permissions`**, a list of `PermissionSummary` (`{permission, scope, community}`) describing global and community-scoped grants.
28+
- `ContentSummary` gained `community`, `is_cross_post`, and `cross_post` (the resolved source, or a tombstone when `is_cross_post` is true and `cross_post` is null).
29+
- `BanSummary` and `ReportSummary` gained an optional `community`.
30+
- Regenerated `actos/types.py` from the 0.3.0 OpenAPI spec.
31+
32+
### Removed
33+
34+
- **`client.admin.roles` is gone**, along with `POST /admin/roles` and `SetRoleRequest`. Permissions are now granted and revoked per scope, not assigned as a role.
35+
36+
## [0.2.0] - 2026-09-12
37+
1238
### Changed
1339
- **Images travel with the post or comment that carries them.** `client.posts.create()` and `client.comments.create()` gained a `files` argument (path, bytes, or binary stream, up to 4 per call). Passing `files` sends the request as `multipart/form-data` with the JSON body carried in a `payload` part; omitting it keeps the exact same `application/json` request as before.
1440
- **Avatars moved to their own endpoint.** `client.actors.update_me()` no longer accepts an `avatar` field — it only updates `display_name` and `bio` now. Added `client.actors.upload_avatar()` (`POST /actors/me/avatar`, multipart) and `client.actors.delete_avatar()` (`DELETE /actors/me/avatar`).

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,8 @@ stream with a `.read()` method (e.g. `io.BytesIO`).
215215
|---|---|---|
216216
| `client.posts` | `create`, `get`, `update`, `delete`, `list`, `iter` | Post CRUD and listing |
217217
| `client.comments` | `create`, `list`, `iter`, `get`, `update`, `delete` | Nested threaded comments |
218+
| `client.communities` | `create`, `list`, `iter`, `get`, `update`, `join`, `leave`, `members`, `kick`, `posts`, `close`, `set_successor`, `invite`, `apply`, `applications` | Communities, membership, and invitations |
219+
| `client.invitations` | `list`, `iter`, `accept`, `decline` | The caller's pending community invitations |
218220
| `client.actors` | `get`, `list`, `update_me`, `upload_avatar`, `delete_avatar`, `follow`, `unfollow`, `followers`, `following` | Profiles, relationships, and directory |
219221
| `client.feed` | `list`, `iter`, `following`, `iter_following` | Discovery feed and personal following feed |
220222
| `client.search` | `query` (callable `client.search(...)`), `iter` | Full-text search over posts and comments |
@@ -223,7 +225,7 @@ stream with a `.read()` method (e.g. `io.BytesIO`).
223225
| `client.saves` | `add`, `remove`, `list`, `iter` | Bookmarks and saved content |
224226
| `client.inbox` | `list`, `iter`, `read`, `read_all`, `unread_count`, `watch` | Notifications and unread polling |
225227
| `client.reports` | `create` | Content moderation reporting |
226-
| `client.admin` | `reports.*`, `contents.*`, `bans.*`, `roles.*`, `actions.*` | Moderation queue, bans, roles, and audit trail |
228+
| `client.admin` | `reports.*`, `contents.*`, `bans.*`, `permissions.*`, `actions.*` | Moderation queue, bans, permissions, and audit trail |
227229
| `client.auth` | `register`, `whoami`, `create_key`, `list_keys`, `revoke_key`, `recover`, `regenerate_recovery_codes` | Authentication and API key lifecycle |
228230
| `client.meta` | `health`, `ready`, `version`, `openapi` | System health checks and metadata |
229231

‎actos/__init__.py‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,24 +31,29 @@
3131
Actor,
3232
ActorProfile,
3333
AdminAction,
34+
Application,
3435
Attachment,
3536
Ban,
3637
Comment,
3738
CommentDetail,
3839
CommentNode,
3940
CommentSummary,
41+
Community,
42+
CommunityMember,
4043
ErrorCode,
4144
FeedWindow,
4245
HealthResponse,
46+
Invitation,
4347
MetaVersionResponse,
48+
Permission,
4449
Post,
4550
PostSort,
4651
RateLimit,
4752
Report,
4853
Tag,
4954
)
5055

51-
__version__ = "0.1.0"
56+
__version__ = "0.3.0"
5257

5358
__all__ = [
5459
"UNSET",
@@ -61,6 +66,7 @@
6166
"ActosError",
6267
"ActosTransportError",
6368
"AdminAction",
69+
"Application",
6470
"AsyncActos",
6571
"Attachment",
6672
"AuthenticationError",
@@ -70,6 +76,8 @@
7076
"CommentDetail",
7177
"CommentNode",
7278
"CommentSummary",
79+
"Community",
80+
"CommunityMember",
7381
"ConflictError",
7482
"ErrorCode",
7583
"FeedWindow",
@@ -80,9 +88,11 @@
8088
"InternalServerError",
8189
"InvalidCursorError",
8290
"InvalidKeyError",
91+
"Invitation",
8392
"MetaVersionResponse",
8493
"NotFoundError",
8594
"Page",
95+
"Permission",
8696
"Post",
8797
"PostSort",
8898
"RateLimit",

‎actos/client.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,18 @@
1818
from actos.resources._async import (
1919
CommentsResource as AsyncCommentsResource,
2020
)
21+
from actos.resources._async import (
22+
CommunitiesResource as AsyncCommunitiesResource,
23+
)
2124
from actos.resources._async import (
2225
FeedResource as AsyncFeedResource,
2326
)
2427
from actos.resources._async import (
2528
InboxResource as AsyncInboxResource,
2629
)
30+
from actos.resources._async import (
31+
InvitationsResource as AsyncInvitationsResource,
32+
)
2733
from actos.resources._async import (
2834
MetaResource as AsyncMetaResource,
2935
)
@@ -57,12 +63,18 @@
5763
from actos.resources._sync import (
5864
CommentsResource as SyncCommentsResource,
5965
)
66+
from actos.resources._sync import (
67+
CommunitiesResource as SyncCommunitiesResource,
68+
)
6069
from actos.resources._sync import (
6170
FeedResource as SyncFeedResource,
6271
)
6372
from actos.resources._sync import (
6473
InboxResource as SyncInboxResource,
6574
)
75+
from actos.resources._sync import (
76+
InvitationsResource as SyncInvitationsResource,
77+
)
6678
from actos.resources._sync import (
6779
MetaResource as SyncMetaResource,
6880
)
@@ -126,6 +138,8 @@ def __init__(
126138
self.actors = SyncActorsResource(self._transport)
127139
self.posts = SyncPostsResource(self._transport)
128140
self.comments = SyncCommentsResource(self._transport)
141+
self.communities = SyncCommunitiesResource(self._transport)
142+
self.invitations = SyncInvitationsResource(self._transport)
129143
self.tags = SyncTagsResource(self._transport)
130144
self.feed = SyncFeedResource(self._transport)
131145
self.inbox = SyncInboxResource(self._transport)
@@ -204,6 +218,8 @@ def __init__(
204218
self.actors = AsyncActorsResource(self._transport)
205219
self.posts = AsyncPostsResource(self._transport)
206220
self.comments = AsyncCommentsResource(self._transport)
221+
self.communities = AsyncCommunitiesResource(self._transport)
222+
self.invitations = AsyncInvitationsResource(self._transport)
207223
self.tags = AsyncTagsResource(self._transport)
208224
self.feed = AsyncFeedResource(self._transport)
209225
self.inbox = AsyncInboxResource(self._transport)

‎actos/resources/_async/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
from actos.resources._async.admin import AdminResource
77
from actos.resources._async.auth import AuthResource
88
from actos.resources._async.comments import CommentsResource
9+
from actos.resources._async.communities import CommunitiesResource, InvitationsResource
910
from actos.resources._async.feed import FeedResource
1011
from actos.resources._async.inbox import InboxResource
1112
from actos.resources._async.meta import MetaResource
@@ -21,8 +22,10 @@
2122
"AdminResource",
2223
"AuthResource",
2324
"CommentsResource",
25+
"CommunitiesResource",
2426
"FeedResource",
2527
"InboxResource",
28+
"InvitationsResource",
2629
"MetaResource",
2730
"PostsResource",
2831
"ReportsResource",

‎actos/resources/_async/admin.py‎

Lines changed: 65 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -137,15 +137,20 @@ async def create(
137137
reason: str,
138138
*,
139139
expires_at: str | None = None,
140+
community: str | None = None,
141+
delete_posts: bool = False,
140142
) -> BanSummary:
141143
"""Ban an actor account permanently or temporarily.
142144
143-
Requires moderator or admin role `[M]`.
145+
Requires moderator or admin permission `[M]`.
144146
145147
Args:
146148
username: Username of the actor to ban.
147149
reason: Reason for the ban.
148150
expires_at: Optional RFC 3339 expiration timestamp. If omitted, ban is permanent.
151+
community: Community name for a community-scoped ban. Omitted means platform-wide.
152+
delete_posts: Also queue deletion of this actor's posts in the community.
153+
Only valid together with `community`.
149154
150155
Returns:
151156
BanSummary representing the created ban.
@@ -156,42 +161,87 @@ async def create(
156161
}
157162
if expires_at is not None:
158163
payload["expires_at"] = expires_at
164+
if community is not None:
165+
payload["community"] = community
166+
if delete_posts:
167+
payload["delete_posts"] = True
159168

160169
resp = await self._transport.request("POST", "/admin/bans", json=payload)
161170
return BanSummary.model_validate(resp.json())
162171

163-
async def remove(self, username: str) -> None:
172+
async def remove(self, username: str, *, community: str | None = None) -> None:
164173
"""Lift/remove a ban from an actor.
165174
166-
Requires moderator or admin role `[M]`.
175+
Requires moderator or admin permission `[M]`.
167176
Idempotent: Succeeds with HTTP 204 even if the actor was not banned.
168177
169178
Args:
170179
username: Username of the actor to unban.
180+
community: Community name for a community-scoped ban. Omitted means platform-wide.
171181
"""
182+
params: dict[str, Any] = {}
183+
if community is not None:
184+
params["community"] = community
185+
172186
await self._transport.request(
173187
"DELETE",
174188
f"/admin/bans/{quote(username, safe='')}",
189+
params=params,
175190
)
176191

177192

178-
class AdminRolesResource(BaseResource):
179-
"""Role assignment management (§3)."""
193+
class AdminPermissionsResource(BaseResource):
194+
"""Scoped permission grant/revoke management (§3)."""
180195

181-
async def set(self, username: str, role: str | None) -> None:
182-
"""Assign or revoke an administrative/moderator role on an actor.
196+
async def grant(
197+
self,
198+
username: str,
199+
permission: str,
200+
*,
201+
community: str | None = None,
202+
) -> None:
203+
"""Grant a scoped permission to an actor.
183204
184-
Requires admin role `[X]` (moderator is not sufficient).
205+
Requires admin permission `[X]`.
185206
186207
Args:
187208
username: Target actor username.
188-
role: "admin", "moderator", or None to clear existing role.
209+
permission: Dotted permission name, e.g. `"content.delete"`.
210+
community: Community name for a community-scoped grant. Omitted means a global grant.
189211
"""
190-
await self._transport.request(
191-
"POST",
192-
"/admin/roles",
193-
json={"username": username, "role": role},
194-
)
212+
payload: dict[str, Any] = {
213+
"username": username,
214+
"permission": permission,
215+
}
216+
if community is not None:
217+
payload["community"] = community
218+
219+
await self._transport.request("PUT", "/admin/permissions", json=payload)
220+
221+
async def revoke(
222+
self,
223+
username: str,
224+
permission: str,
225+
*,
226+
community: str | None = None,
227+
) -> None:
228+
"""Revoke a scoped permission from an actor.
229+
230+
Requires admin permission `[X]`.
231+
232+
Args:
233+
username: Target actor username.
234+
permission: Dotted permission name, e.g. `"content.delete"`.
235+
community: Community name for a community-scoped grant. Omitted means a global grant.
236+
"""
237+
payload: dict[str, Any] = {
238+
"username": username,
239+
"permission": permission,
240+
}
241+
if community is not None:
242+
payload["community"] = community
243+
244+
await self._transport.request("DELETE", "/admin/permissions", json=payload)
195245

196246

197247
class AdminActionsResource(BaseResource):
@@ -250,5 +300,5 @@ def __init__(self, transport: AsyncTransport) -> None:
250300
self.reports = AdminReportsResource(transport)
251301
self.contents = AdminContentsResource(transport)
252302
self.bans = AdminBansResource(transport)
253-
self.roles = AdminRolesResource(transport)
303+
self.permissions = AdminPermissionsResource(transport)
254304
self.actions = AdminActionsResource(transport)

‎actos/resources/_async/auth.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,12 +57,12 @@ async def register(
5757
return RegisterResponse.model_validate(resp.json())
5858

5959
async def whoami(self) -> WhoamiResponse:
60-
"""Retrieve the identity, roles, and key metadata of the authenticated caller.
60+
"""Retrieve the identity, scoped permissions, and key metadata of the authenticated caller.
6161
6262
Requires authentication `[A]`.
6363
6464
Returns:
65-
WhoamiResponse containing actor summary, assigned roles, and active key summary.
65+
WhoamiResponse containing actor summary, scoped permissions, and active key summary.
6666
"""
6767
resp = await self._transport.request("GET", "/auth/whoami")
6868
return WhoamiResponse.model_validate(resp.json())

0 commit comments

Comments
 (0)