sparrowtek.com
this repo has no description
radmakr.com
1# EffemKit
2
3Swift client for the Effem AT Protocol AppView. Provides social podcasting features — subscriptions, comments, recommendations, bookmarks, curated lists, and profiles — built on the AT Protocol.
4
5## Requirements
6
7- Swift 6.2+
8- iOS 26+ / macOS 26+ / watchOS 26+ / tvOS 26+
9
10## Dependencies
11
12- [CoreATProtocol](https://tangled.org/@sparrowtek.com/CoreATProtocol) — AT Protocol primitives, OAuth, networking
13
14## Installation
15
16Add EffemKit as a dependency in your `Package.swift`:
17
18```swift
19dependencies: [
20 .package(url: "https://tangled.org/@sparrowtek.com/EffemKit", branch: "main"),
21]
22```
23
24Or add it as a local package in Xcode.
25
26## Quick Start
27
28### 1. Configure the AppView
29
30```swift
31import EffemKit
32import CoreATProtocol
33
34// At app launch
35Task { @APActor in
36 setup(appViewHost: "https://appview.effem.xyz")
37}
38```
39
40### 2. Read Data
41
42```swift
43@APActor
44func loadTrending() async throws -> [PodcastResult] {
45 let service = EffemService()
46 let response = try await service.getTrending(max: 20)
47 return response.feeds
48}
49```
50
51### 3. Write Data (requires authentication)
52
53```swift
54@APActor
55func subscribe(feedId: Int, userDID: String) async throws {
56 let repoService = EffemRepoService()
57 let podcast = PodcastRef(feedId: feedId)
58 _ = try await repoService.subscribe(to: podcast, repo: userDID)
59}
60```
61
62## Architecture
63
64EffemKit uses a two-router architecture:
65
66| Path | Service | Target | Auth Required |
67|------|---------|--------|--------------|
68| Read | `EffemService` | Effem AppView | No |
69| Write | `EffemRepoService` | User's PDS | Yes |
70
71**Reads** go to the Effem AppView, which indexes social records from the AT Protocol firehose and proxies Podcast Index metadata enriched with social overlay data.
72
73**Writes** go to the authenticated user's PDS using standard `com.atproto.repo.createRecord` / `deleteRecord` calls. The AppView picks up new records asynchronously via the firehose.
74
75All public API is isolated to `@APActor` for thread safety.
76
77## API Overview
78
79### EffemService (Read)
80
81| Category | Methods |
82|----------|---------|
83| Subscriptions | `getSubscriptions`, `getSubscribers` |
84| Comments | `getComments`, `getCommentThread` |
85| Recommendations | `getRecommendations`, `getPopular` |
86| Lists | `getList`, `getLists` |
87| Bookmarks | `getBookmarks` |
88| Inbox | `getInbox` |
89| Profiles | `getProfile` |
90| Podcast Search | `searchPodcasts`, `searchEpisodes` |
91| Podcast Metadata | `getPodcast`, `getEpisodes`, `getEpisode`, `getTrending`, `getCategories` |
92
93### EffemRepoService (Write)
94
95| Category | Methods |
96|----------|---------|
97| Subscriptions | `subscribe`, `unsubscribe` |
98| Comments | `postComment`, `deleteComment` |
99| Recommendations | `recommend`, `unrecommend` |
100| Bookmarks | `bookmark`, `removeBookmark` |
101| Lists | `createList`, `deleteList` |
102| Profile | `updateProfile` |
103
104## Lexicon Namespace
105
106All Effem records use the `xyz.effem.*` namespace:
107
108- `xyz.effem.feed.subscription`
109- `xyz.effem.feed.comment`
110- `xyz.effem.feed.recommendation`
111- `xyz.effem.feed.bookmark`
112- `xyz.effem.feed.list`
113- `xyz.effem.actor.profile`
114
115## Documentation
116
117Build the DocC documentation:
118
119```bash
120swift package generate-documentation
121```
122
123Or in Xcode: Product > Build Documentation.
124
125## Testing
126
127```bash
128swift test
129```
130
13115 tests across 8 suites covering model decoding, round-tripping, serialization, and AT URI generation.