From 07ee79187956f66dbae7d97caaee19b917cc4c67 Mon Sep 17 00:00:00 2001
From: Gabriel Kaszewski <gabrielkaszewski@gmail.com>
Date: Fri, 29 May 2026 02:13:06 +0000
Subject: [PATCH] wiki: add Broadcasts page

---
 Broadcasts.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 Broadcasts.md

diff --git a/Broadcasts.md b/Broadcasts.md
new file mode 100644
index 0000000..bee8855
--- /dev/null
+++ b/Broadcasts.md
@@ -0,0 +1,115 @@
+# Broadcasts
+
+k-ap provides methods to send activities to remote servers. All outbound requests are HTTP-signature-signed using the local user's private key from `ActorRepository`.
+
+---
+
+## Visibility
+
+`ApVisibility` controls the `to`/`cc` addressing of `Create` and `Update` activities and determines who receives delivery:
+
+| Variant | `to` | `cc` | Delivery |
+|---------|------|------|----------|
+| `Public` | `[AS_PUBLIC]` | `[followers_url]` | Followers + mentioned non-followers |
+| `FollowersOnly` | `[followers_url]` | `[]` | Followers + mentioned non-followers |
+| `Private` | — | — | No delivery (returns immediately) |
+
+---
+
+## Create / Update
+
+```rust
+use k_ap::ApVisibility;
+
+// Resolve mentioned non-followers' inbox URLs before calling — pass vec![] if none.
+let mentioned: Vec<Url> = vec![bob_inbox_url, carol_inbox_url];
+
+// Wraps note_json in a Create activity and delivers to followers + mentioned, deduplicated.
+service.broadcast_create_note(local_user_id, note_json, ApVisibility::Public, mentioned).await?;
+
+// Wraps note_json in an Update activity.
+service.broadcast_update_note(local_user_id, note_json, ApVisibility::FollowersOnly, vec![]).await?;
+```
+
+`note_json` is your AP object JSON (`serde_json::Value`). k-ap wraps it in the activity. Pass `vec![]` for `mentioned` if there are no non-follower mentions.
+
+---
+
+## Delete
+
+```rust
+// Delivers Delete(Tombstone) to all accepted followers.
+service.broadcast_delete_to_followers(local_user_id, ap_object_id).await?;
+```
+
+`ap_object_id` is the `Url` of the object being deleted.
+
+---
+
+## Announce (boost)
+
+```rust
+service.broadcast_announce_to_followers(local_user_id, object_ap_id).await?;
+service.broadcast_undo_announce_to_followers(local_user_id, object_ap_id).await?;
+```
+
+Delivers `Announce` or `Undo(Announce)` to all accepted followers.
+
+---
+
+## Add / Undo Add
+
+```rust
+// Delivers Add to all accepted followers. ap_id is the activity URL; object is the AP object JSON.
+service.broadcast_add_to_followers(local_user_id, ap_id, object).await?;
+service.broadcast_undo_add_to_followers(local_user_id, watchlist_entry_ap_id).await?;
+```
+
+Used for collection membership changes (e.g. adding to a watchlist).
+
+---
+
+## Like
+
+```rust
+// Delivers to a single inbox — not followers.
+service.broadcast_like_to_inbox(liker_user_id, object_ap_id, author_inbox_url).await?;
+service.broadcast_undo_like_to_inbox(liker_user_id, object_ap_id, author_inbox_url).await?;
+```
+
+Resolve the author's inbox URL before calling (via `lookup_actor_by_handle` or from your `RemoteActor` cache).
+
+---
+
+## Actor update
+
+```rust
+// Delivers Update(Person) to all accepted followers.
+service.broadcast_actor_update(user_id).await?;
+```
+
+Call this whenever a local user's profile changes — display name, bio, avatar, etc.
+
+---
+
+## Account migration (Move)
+
+```rust
+// Delivers Move to all accepted followers.
+// Set alsoKnownAs in ApUser to include new_actor_url BEFORE calling this.
+service.broadcast_move(user_id, new_actor_url).await?;
+```
+
+The receiving server verifies that the new actor's `alsoKnownAs` contains the old actor's URL. Set this up on the new account before broadcasting.
+
+---
+
+## Block
+
+```rust
+// Adds actor to blocklist, removes from followers/following, sends Block activity.
+service.block_actor(local_user_id, actor_url).await?;
+
+// Removes actor from blocklist.
+service.unblock_actor(local_user_id, actor_url).await?;
+```
\ No newline at end of file