From 6ef7c7a427f50e81bb512161cb64ba00641b4d34 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Wed, 10 Apr 2024 19:25:04 +0900
Subject: [PATCH] Add PUBLIC_COLLECTION constant for public addressing

---
 CHANGES.md          |  4 ++++
 docs/manual/send.md | 13 ++++++++-----
 vocab/constants.ts  | 11 +++++++++++
 vocab/mod.ts        |  1 +
 4 files changed, 24 insertions(+), 5 deletions(-)
 create mode 100644 vocab/constants.ts

diff --git a/CHANGES.md b/CHANGES.md
index acb41ce3..603d3ee3 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -8,6 +8,10 @@ Version 0.7.0
 
 To be released.
 
+ -  Added `PUBLIC_COLLECTION` constant for [public addressing].
+
+[public addressing]: https://www.w3.org/TR/activitypub/#public-addressing
+
 
 Version 0.6.0
 -------------
diff --git a/docs/manual/send.md b/docs/manual/send.md
index 0f576198..f4d10929 100644
--- a/docs/manual/send.md
+++ b/docs/manual/send.md
@@ -132,7 +132,7 @@ recipient's personal inbox.  To deliver an activity to the shared inbox,
 you can pass the `preferSharedInbox` option:
 
 ~~~~ typescript
-import { Actor, Context, Create, Note } from "@fedify/fedify";
+import { Actor, Context, Create, Note, PUBLIC_COLLECTION } from "@fedify/fedify";
 
 async function sendNote(
   ctx: Context<void>,
@@ -144,10 +144,10 @@ async function sendNote(
     recipient,
     new Create({
       actor: ctx.getActorUri(senderHandle),
-      to: new URL("https://www.w3.org/ns/activitystreams#Public"),
+      to: PUBLIC_COLLECTION,
       object: new Note({
         attribution: ctx.getActorUri(senderHandle),
-        to: new URL("https://www.w3.org/ns/activitystreams#Public"),
+        to: PUBLIC_COLLECTION,
       }),
     }),
     { preferSharedInbox: true },  // [!code highlight]
@@ -156,9 +156,12 @@ async function sendNote(
 ~~~~
 
 > [!TIP]
-> <https://www.w3.org/ns/activitystreams#Public> is a special IRI that
+> `PUBLIC_COLLECTION` constant contains a `URL` object of
+> <https://www.w3.org/ns/activitystreams#Public>, a special IRI that
 > represents the public audience.  By setting the `to` property to this IRI,
-> the activity is visible to everyone.
+> the activity is visible to everyone.  See also the [*Public Addressing*
+> section](https://www.w3.org/TR/activitypub/#public-addressing) in the
+> ActivityPub specification.
 
 > [!NOTE]
 > To deliver an activity to the shared inbox, the recipient server must support
diff --git a/vocab/constants.ts b/vocab/constants.ts
new file mode 100644
index 00000000..304c34d6
--- /dev/null
+++ b/vocab/constants.ts
@@ -0,0 +1,11 @@
+/**
+ * The special public collection for [public addressing].  *Do not mutate this
+ * object.*
+ *
+ * [public addressing]: https://www.w3.org/TR/activitypub/#public-addressing
+ *
+ * @since 0.7.0
+ */
+export const PUBLIC_COLLECTION: URL = new URL(
+  "https://www.w3.org/ns/activitystreams#Public",
+);
diff --git a/vocab/mod.ts b/vocab/mod.ts
index 7b7f6541..59ef94e3 100644
--- a/vocab/mod.ts
+++ b/vocab/mod.ts
@@ -50,5 +50,6 @@
  * @module
  */
 export * from "./actor.ts";
+export * from "./constants.ts";
 export * from "./lookup.ts";
 export * from "./vocab.ts";