From 94c291c472ecbc2849ab59515f94f973423ec9d8 Mon Sep 17 00:00:00 2001
From: Jannis Braun <151788261+TheZwiss@users.noreply.github.com>
Date: Sun, 26 Apr 2026 21:14:51 +0200
Subject: [PATCH] =?UTF-8?q?refactor(shared):=20rename=20TriggerReason=20?=
 =?UTF-8?q?=E2=86=92=20PeeringTriggerReason,=20pin=20subscribers=20semanti?=
 =?UTF-8?q?cs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Symmetric with PeeringNotificationKind at module scope; avoids
  future collision with unrelated trigger systems.
- subscribers field doc now explicit: undefined for inbound, present
  (possibly []) for outbound. Pins the response contract before Task 7
  implements the GET endpoint response shape.
---
 packages/shared/src/types.ts | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/packages/shared/src/types.ts b/packages/shared/src/types.ts
index 9cf6af5a..bf7325e1 100644
--- a/packages/shared/src/types.ts
+++ b/packages/shared/src/types.ts
@@ -1037,7 +1037,7 @@ export interface FederationPeer {
  * the human-readable cause and the user can recover their original action
  * after approval. Persisted as a string column with this exact set of values.
  */
-export type TriggerReason = 'friend_add' | 'space_join' | 'direct_message';
+export type PeeringTriggerReason = 'friend_add' | 'space_join' | 'direct_message';
 
 /**
  * Caller intent passed into `ensurePeered()`. The gate (when
@@ -1053,7 +1053,7 @@ export type TriggerReason = 'friend_add' | 'space_join' | 'direct_message';
  * for space_join, the federated DM channel id for direct_message).
  */
 export type EnsurePeeredCallerIntent =
-  | { kind: 'user_action'; userId: string; reason: TriggerReason; target: string }
+  | { kind: 'user_action'; userId: string; reason: PeeringTriggerReason; target: string }
   | { kind: 'system' };
 
 /**
@@ -1074,7 +1074,7 @@ export interface PeeringSubscription {
   requestId: string;
   peerOrigin: string;
   peerInstanceName: string | null;
-  triggerReason: TriggerReason;
+  triggerReason: PeeringTriggerReason;
   triggerTarget: string;
   createdAt: number;
 }
@@ -1089,7 +1089,7 @@ export interface PeeringNotification {
   id: string;
   kind: PeeringNotificationKind;
   peerOrigin: string;
-  triggerReason: TriggerReason;
+  triggerReason: PeeringTriggerReason;
   triggerTarget: string;
   createdAt: number;
   readAt: number | null;
@@ -1103,7 +1103,7 @@ export interface PeeringNotification {
 export interface ApprovalRequestSubscriberSummary {
   userId: string;
   username: string;
-  triggerReason: TriggerReason;
+  triggerReason: PeeringTriggerReason;
   triggerTarget: string;
 }
 
@@ -1121,5 +1121,11 @@ export interface ApprovalRequest {
   instanceName: string | null;
   requestedAt: number;
   expiresAt: number;
+  /**
+   * Subscriber summaries — present (and possibly empty array) only when
+   * `direction === 'outbound'`. ABSENT (`undefined`) when `direction === 'inbound'`.
+   * Inbound rows have no per-action context; the field is omitted from the server
+   * response, not set to `[]`.
+   */
   subscribers?: ApprovalRequestSubscriberSummary[];
 }