refactor: drop free-text note from ping (violated no-free-text convention)

Every message type in this app forbids free text (MoodType "No free
text", StatusType "not a notes field", etc.), so PingType's optional
prose `note` field was inconsistent. Removed the field, the --note
option, and the note-in-payload — the ping payload is now just
{user_ids}. That eliminated the only user-controlled value that could
make the envelope invalid, so the now-unreachable InvalidEnvelopeException
try/catch and renderEnvelopeError helper were removed too (the envelope
is valid by construction). Dropped the two note-max-length tests
accordingly.

Author: ikidnapmyself

app/Console/Commands/PingThreadUsers.php

@@ -2,13 +2,11 @@
 
 namespace App\Console\Commands;
 
-use App\Exceptions\InvalidEnvelopeException;
 use App\Interfaces\MessageServiceInterface;
 use App\Models\Thread;
 use App\Models\User;
 use Illuminate\Console\Command;
 use Illuminate\Database\Eloquent\Collection;
-use Illuminate\Http\JsonResponse;
 
 class PingThreadUsers extends Command
 {
@@ -19,8 +17,7 @@ class PingThreadUsers extends Command
         {--thread= : Existing thread UUID to ping into (omit to create a new thread)}
         {--from= : Sender / thread-creator user UUID}
         {--user=* : User UUID(s) to ping}
-        {--subject= : Subject for a NEW thread (required when --thread is omitted)}
-        {--note= : Optional short note included in the ping payload}';
+        {--subject= : Subject for a NEW thread (required when --thread is omitted)}';
 
     /**
      * @var string
@@ -34,7 +31,6 @@ public function handle(MessageServiceInterface $service): int
         $fromId = $this->option('from');
         /** @var array<int, string> $userIds */
         $userIds = array_values(array_unique($this->option('user')));
-        $note = $this->option('note');
 
         $threadId = is_string($threadId) && $threadId !== '' ? $threadId : null;
         $subject = is_string($subject) && $subject !== '' ? $subject : null;
@@ -83,21 +79,11 @@ public function handle(MessageServiceInterface $service): int
         $envelope = [
             'type' => 'ping',
             'version' => '1.0',
-            'payload' => array_filter(
-                ['user_ids' => $userIds, 'note' => $note],
-                fn ($value) => $value !== null && $value !== '',
-            ),
+            'payload' => ['user_ids' => $userIds],
         ];
 
         if ($threadId === null) {
-            try {
-                $thread = $service->newThread((string) $subject, $sender, $envelope, $userIds);
-            } catch (InvalidEnvelopeException $e) {
-                $this->error('Could not send ping: '.$this->renderEnvelopeError($e));
-
-                return self::FAILURE;
-            }
-
+            $thread = $service->newThread((string) $subject, $sender, $envelope, $userIds);
             $this->info("Created thread {$thread->id} and pinged {$users->count()} user(s).");
 
             return self::SUCCESS;
@@ -128,25 +114,9 @@ public function handle(MessageServiceInterface $service): int
             return self::FAILURE;
         }
 
-        try {
-            $message = $service->newMessage($thread, $sender, $envelope);
-        } catch (InvalidEnvelopeException $e) {
-            $this->error('Could not send ping: '.$this->renderEnvelopeError($e));
-
-            return self::FAILURE;
-        }
-
+        $message = $service->newMessage($thread, $sender, $envelope);
         $this->info("Pinged {$users->count()} user(s) in thread {$thread->id} (message {$message->id}).");
 
         return self::SUCCESS;
     }
-
-    private function renderEnvelopeError(InvalidEnvelopeException $e): string
-    {
-        $response = $e->getResponse();
-
-        return $response instanceof JsonResponse
-            ? (string) $response->getContent()
-            : $e->getMessage();
-    }
 }

app/MessageTypes/PingType.php

@@ -18,7 +18,7 @@ public function version(): string
 
     public function purpose(): string
     {
-        return 'Nudge specific participants of a thread. The payload lists the pinged user IDs (a targeted mention) so clients may highlight the message for those users. An optional short note may accompany the ping.';
+        return 'Nudge specific participants of a thread. The payload lists the pinged user IDs (a targeted mention) so clients may highlight the message for those users.';
     }
 
     /**
@@ -37,7 +37,6 @@ public function schema(): array
                     'uniqueItems' => true,
                     'items' => ['type' => 'string'],
                 ],
-                'note' => ['type' => 'string', 'maxLength' => 280],
             ],
         ];
     }

docs/plans/2026-07-14-thread-ping-command-design.md

@@ -3,6 +3,8 @@
 **Status:** Approved 2026-07-14
 **Source:** ops/admin need to nudge specific participants of a thread from the CLI — either inside an existing thread or by spinning up a new thread whose opening message is the ping.
 
+> **Amendment 2026-07-15:** The optional free-text `note` field (and the `--note` option) described below were **removed** before merge. Every message type in this app deliberately forbids free text (e.g. `MoodType` "No free text", `StatusType` "not a notes field"), so a prose `note` violated that convention. The ping payload is now just `{ user_ids: [...] }`. Because that removed the only user-controlled value that could produce an invalid envelope, the `InvalidEnvelopeException` try/catch in the command was also dropped (the envelope is now valid by construction).
+
 ## 1. Goal
 
 Add an artisan command, `thread:ping`, that an operator/admin runs to "ping" a set of users. It works in two modes:

tests/Feature/PingThreadUsersCommandTest.php

@@ -90,7 +90,6 @@ public function test_creates_a_new_thread_and_pings_recipients(): void
             '--from' => $sender->id,
             '--subject' => 'Heads up',
             '--user' => [$a->id, $b->id],
-            '--note' => 'please respond',
         ])->assertSuccessful();
 
         $thread = Thread::where('subject', 'Heads up')->firstOrFail();
@@ -103,29 +102,10 @@ public function test_creates_a_new_thread_and_pings_recipients(): void
         $ping = $this->pingMessage($thread);
         $this->assertNotNull($ping);
         $this->assertSame([$a->id, $b->id], Arr::get($ping->body, 'payload.user_ids'));
-        $this->assertSame('please respond', Arr::get($ping->body, 'payload.note'));
 
         Notification::assertSentTo($a, ThreadCreated::class);
     }
 
-    public function test_fails_gracefully_when_note_exceeds_max_length(): void
-    {
-        Notification::fake();
-
-        $sender = User::factory()->create(['notify_via' => ['broadcast']]);
-        $recipient = User::factory()->create(['notify_via' => ['broadcast']]);
-        $thread = $this->service->newThread('Subject', $sender, $this->envelope(), [$recipient->id]);
-
-        $this->runPing([
-            '--thread' => $thread->id,
-            '--from' => $sender->id,
-            '--user' => [$recipient->id],
-            '--note' => str_repeat('a', 281),
-        ])->assertFailed();
-
-        $this->assertNull($this->pingMessage($thread));
-    }
-
     public function test_fails_when_neither_thread_nor_subject_is_given(): void
     {
         $sender = User::factory()->create();
@@ -248,22 +228,6 @@ public function test_fails_when_a_pinged_user_does_not_exist(): void
         $this->assertNoPingMessagesExist();
     }
 
-    public function test_create_mode_fails_gracefully_when_note_exceeds_max_length(): void
-    {
-        $sender = User::factory()->create();
-        $recipient = User::factory()->create();
-
-        $this->runPing([
-            '--from' => $sender->id,
-            '--subject' => 'Heads up',
-            '--user' => [$recipient->id],
-            '--note' => str_repeat('a', 281),
-        ])->assertFailed();
-
-        $this->assertNoPingMessagesExist();
-        $this->assertDatabaseMissing('threads', ['subject' => 'Heads up']);
-    }
-
     private function assertNoPingMessagesExist(): void
     {
         $this->assertFalse(

tests/Unit/MessageTypeTest.php

@@ -131,10 +131,10 @@ public function test_ping(): void
         $this->assertNotEmpty($type->purpose());
 
         $this->assertTrue($this->accepts($type->schema(), ['user_ids' => ['u1']]));
-        $this->assertTrue($this->accepts($type->schema(), ['user_ids' => ['u1', 'u2'], 'note' => 'please respond']));
+        $this->assertTrue($this->accepts($type->schema(), ['user_ids' => ['u1', 'u2']]));
         $this->assertFalse($this->accepts($type->schema(), ['user_ids' => []]));               // minItems
         $this->assertFalse($this->accepts($type->schema(), ['user_ids' => ['u1', 'u1']]));      // uniqueItems
-        $this->assertFalse($this->accepts($type->schema(), ['note' => 'x']));                   // missing user_ids
-        $this->assertFalse($this->accepts($type->schema(), ['user_ids' => ['u1'], 'x' => 1]));  // additionalProperties
+        $this->assertFalse($this->accepts($type->schema(), []));                               // missing user_ids
+        $this->assertFalse($this->accepts($type->schema(), ['user_ids' => ['u1'], 'note' => 'x']));  // additionalProperties (note no longer allowed)
     }
 }