From 86eb900d6e5d79714f384dfe6de33b8f34f6c15e Mon Sep 17 00:00:00 2001
From: Gabriel Kaszewski <gabrielkaszewski@gmail.com>
Date: Fri, 29 May 2026 02:14:23 +0000
Subject: [PATCH] wiki: add Actor Lookup and Remote Outbox page

---
 Actor-Lookup-and-Remote-Outbox.md | 48 +++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 Actor-Lookup-and-Remote-Outbox.md

diff --git a/Actor-Lookup-and-Remote-Outbox.md b/Actor-Lookup-and-Remote-Outbox.md
new file mode 100644
index 0000000..16834fb
--- /dev/null
+++ b/Actor-Lookup-and-Remote-Outbox.md
@@ -0,0 +1,48 @@
+# Actor Lookup and Remote Outbox
+
+---
+
+## Resolve a remote handle
+
+```rust
+use k_ap::LookedUpActor;
+
+let actor: LookedUpActor = service.lookup_actor_by_handle("@user@remote.example").await?;
+```
+
+This sends a **signed** WebFinger request — required by strict instances such as Threads that reject unsigned WebFinger. The returned `LookedUpActor` includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `handle` | `String` | `user@domain` format |
+| `display_name` | `Option<String>` | Display name from actor JSON |
+| `bio` | `Option<String>` | Summary from actor JSON |
+| `avatar_url` | `Option<Url>` | Icon URL |
+| `banner_url` | `Option<Url>` | Image URL |
+| `ap_url` | `Url` | Stable actor URL (the AP ID) |
+| `outbox_url` | `Option<Url>` | Outbox collection URL |
+| `followers_url` | `Option<Url>` | Followers collection URL |
+| `following_url` | `Option<Url>` | Following collection URL |
+| `also_known_as` | `Vec<String>` | All known aliases |
+| `profile_url` | `Option<Url>` | Profile page URL |
+| `attachment` | `Vec<ApProfileField>` | PropertyValue metadata |
+
+Use `lookup_actor_by_handle` before calling `follow`, or to resolve a mentioned actor's inbox URL for `broadcast_create_note`.
+
+---
+
+## Import a remote actor's post history
+
+```rust
+// Fetches pages from the remote actor's outbox and calls on_create for each object.
+service.import_remote_outbox(outbox_url_str, actor_url_str).await?;
+```
+
+Use this to surface a remote account's past posts after a local user follows them.
+
+**This is distinct from `run_backfill_for_follower`**, which sends *your* local content *to* a new follower. `import_remote_outbox` fetches content *from* a remote server *into* your instance.
+
+| Method | Direction | Use case |
+|--------|-----------|----------|
+| `import_remote_outbox` | Remote → local | Show a remote user's history after follow |
+| `run_backfill_for_follower` | Local → remote | Send your history to a new follower |
\ No newline at end of file