GET /xrpc/app.bsky.actor.searchActorsTypeahead
typeahead.waow.tech
add readme with usage, architecture, and known limitations
documents the response shape gap (missing labels, associated, createdAt)
and lack of moderation filtering as explicit known limitations.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+55
+55
README.md
+55
README.md
···
1
+
# typeahead
2
+
3
+
community actor search for [atproto](https://atproto.com).
4
+
5
+
**live:** https://typeahead.waow.tech
6
+
7
+
## what it does
8
+
9
+
drop-in replacement for Bluesky's `app.bsky.actor.searchActorsTypeahead` endpoint. any atproto app can point at this instead of `public.api.bsky.app` and get actor search without depending on Bluesky's infrastructure.
10
+
11
+
```bash
12
+
curl "https://typeahead.waow.tech/xrpc/app.bsky.actor.searchActorsTypeahead?q=nate&limit=10"
13
+
```
14
+
15
+
## how it works
16
+
17
+
1. **ingester** (zig) subscribes to [Jetstream](https://docs.bsky.app/blog/jetstream), filters identity and profile events, batches them to the worker
18
+
2. **worker** (cloudflare) serves search via FTS5 full-text search over D1, with edge caching (60s) and rate limiting
19
+
3. **backfill** fills index gaps by querying Bluesky's typeahead in the background — temporary bridge while the index catches up
20
+
21
+
## stack
22
+
23
+
- **ingester**: zig on fly.io — streams jetstream, posts batches to worker
24
+
- **worker**: cloudflare worker + D1 (sqlite/FTS5) + KV + cache API
25
+
- **search**: FTS5 prefix matching, edge-cached per query
26
+
27
+
## run locally
28
+
29
+
```bash
30
+
# worker
31
+
npm install
32
+
npx wrangler dev
33
+
34
+
# ingester
35
+
cd ingester && zig build run
36
+
```
37
+
38
+
requires `TYPEAHEAD_URL` and `TYPEAHEAD_SECRET` env vars for the ingester.
39
+
40
+
## deploy
41
+
42
+
```bash
43
+
npx wrangler deploy # worker to cloudflare
44
+
cd ingester && fly deploy # ingester to fly.io
45
+
```
46
+
47
+
## known limitations
48
+
49
+
- **response shape**: returns `did`, `handle`, `displayName`, `avatar`. does not yet include `associated`, `labels`, `createdAt`, or other fields from [`profileViewBasic`](https://docs.bsky.app/docs/api/app-bsky-actor-search-actors-typeahead). apps that only destructure the core fields work fine; apps that depend on labels or associated metadata should be aware of this gap.
50
+
- **no moderation filtering**: results are not filtered by moderation labels. unsafe accounts may appear in results.
51
+
- **index coverage**: the index grows from jetstream events + backfill. it does not yet have full coverage of all atproto actors.
52
+
53
+
## license
54
+
55
+
MIT