Implement core functionality

LICENSE

···
+MIT License
+
+Copyright (c) 2025 Social Dept.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

···
+# Signal
+
+**Laravel package for building Signals that respond to AT Protocol Jetstream events**
+
+Signal provides a clean, Laravel-style interface for consuming real-time events from the AT Protocol firehose (Jetstream). Build reactive applications that respond to posts, likes, follows, and other social interactions on the AT Protocol network.
+
+---
+
+## Features
+
+- 🔌 **WebSocket Connection** - Connect to AT Protocol Jetstream with automatic reconnection
+- 🎯 **Signal-based Architecture** - Clean, testable event handlers (avoiding Laravel's "listener" naming collision)
+- ⭐ **Wildcard Collection Filtering** - Match multiple collections with patterns like `app.bsky.feed.*`
+- 💾 **Cursor Management** - Resume from last position after disconnections (Database, Redis, or File storage)
+- ⚡ **Queue Integration** - Process events asynchronously with Laravel queues
+- 🔍 **Auto-Discovery** - Automatically find and register Signals in `app/Signals`
+- 🧪 **Testing Tools** - Test your Signals with sample data
+- 🛠️ **Artisan Commands** - Full CLI support for managing and testing Signals
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Creating Signals](#creating-signals)
+- [Filtering Events](#filtering-events)
+- [Queue Integration](#queue-integration)
+- [Configuration](#configuration)
+- [Available Commands](#available-commands)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [License](#license)
+
+---
+
+## Installation
+
+Install the package via Composer:
+
+```bash
+composer require social-dept/signal
+```
+
+Run the installation command:
+
+```bash
+php artisan signal:install
+```
+
+This will:
+- Publish the configuration file to `config/signal.php`
+- Publish the database migration
+- Run migrations (with confirmation)
+- Display next steps
+
+### Manual Installation
+
+If you prefer manual installation:
+
+```bash
+php artisan vendor:publish --tag=signal-config
+php artisan vendor:publish --tag=signal-migrations
+php artisan migrate
+```
+
+---
+
+## Quick Start
+
+### 1. Create Your First Signal
+
+```bash
+php artisan make:signal NewPostSignal
+```
+
+This creates `app/Signals/NewPostSignal.php`:
+
+```php
+<?php
+
+namespace App\Signals;
+
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class NewPostSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function handle(JetstreamEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        logger()->info('New post created', [
+            'did' => $event->did,
+            'text' => $record->text ?? null,
+        ]);
+    }
+}
+```
+
+### 2. Start Consuming Events
+
+```bash
+php artisan signal:consume
+```
+
+Your Signal will now respond to new posts on the AT Protocol network in real-time!
+
+---
+
+## Creating Signals
+
+### Basic Signal Structure
+
+Every Signal extends the base `Signal` class and must implement:
+
+```php
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class MySignal extends Signal
+{
+    // Required: Define which event types to listen for
+    public function eventTypes(): array
+    {
+        return ['commit']; // 'commit', 'identity', or 'account'
+    }
+
+    // Required: Handle the event
+    public function handle(JetstreamEvent $event): void
+    {
+        // Your logic here
+    }
+}
+```
+
+### Event Types
+
+Three event types are available:
+
+| Type | Description | Use Cases |
+|------|-------------|-----------|
+| `commit` | Repository commits (posts, likes, follows, etc.) | Content creation, social interactions |
+| `identity` | Identity changes (handle updates) | User profile tracking |
+| `account` | Account status changes | Account monitoring |
+
+### Accessing Event Data
+
+```php
+public function handle(JetstreamEvent $event): void
+{
+    // Common properties
+    $did = $event->did;           // User's DID
+    $kind = $event->kind;         // Event type
+    $timestamp = $event->timeUs;  // Microsecond timestamp
+
+    // Commit events
+    if ($event->isCommit()) {
+        $collection = $event->getCollection();  // e.g., 'app.bsky.feed.post'
+        $operation = $event->getOperation();    // 'create', 'update', or 'delete'
+        $record = $event->getRecord();          // The actual record data
+        $rkey = $event->commit->rkey;           // Record key
+    }
+
+    // Identity events
+    if ($event->isIdentity()) {
+        $handle = $event->identity->handle;
+    }
+
+    // Account events
+    if ($event->isAccount()) {
+        $active = $event->account->active;
+        $status = $event->account->status;
+    }
+}
+```
+
+---
+
+## Filtering Events
+
+### Collection Filtering (with Wildcards!)
+
+Filter events by AT Protocol collection:
+
+```php
+// Exact match - only posts
+public function collections(): ?array
+{
+    return ['app.bsky.feed.post'];
+}
+
+// Wildcard - all feed events
+public function collections(): ?array
+{
+    return ['app.bsky.feed.*'];
+}
+
+// Multiple patterns
+public function collections(): ?array
+{
+    return [
+        'app.bsky.feed.post',
+        'app.bsky.feed.repost',
+        'app.bsky.graph.*',  // All graph collections
+    ];
+}
+
+// No filter - all collections
+public function collections(): ?array
+{
+    return null;
+}
+```
+
+### Common Collection Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `app.bsky.feed.*` | Posts, likes, reposts, etc. |
+| `app.bsky.graph.*` | Follows, blocks, mutes |
+| `app.bsky.actor.*` | Profile updates |
+| `app.bsky.*` | All Bluesky collections |
+
+### DID Filtering
+
+Filter events by specific users:
+
+```php
+public function dids(): ?array
+{
+    return [
+        'did:plc:z72i7hdynmk6r22z27h6tvur',  // Specific user
+        'did:plc:ragtjsm2j2vknwkz3zp4oxrd',  // Another user
+    ];
+}
+```
+
+### Custom Filtering
+
+Add complex filtering logic:
+
+```php
+public function shouldHandle(JetstreamEvent $event): bool
+{
+    // Only handle posts with images
+    if ($event->isCommit() && $event->commit->collection === 'app.bsky.feed.post') {
+        $record = $event->getRecord();
+        return isset($record->embed);
+    }
+
+    return true;
+}
+```
+
+---
+
+## Queue Integration
+
+Process events asynchronously using Laravel queues:
+
+```php
+class HeavyProcessingSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    // Enable queueing
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    // Optional: Customize queue
+    public function queue(): string
+    {
+        return 'high-priority';
+    }
+
+    // Optional: Customize connection
+    public function queueConnection(): string
+    {
+        return 'redis';
+    }
+
+    public function handle(JetstreamEvent $event): void
+    {
+        // This runs in a queue job
+        $this->performExpensiveOperation($event);
+    }
+
+    // Handle failures
+    public function failed(JetstreamEvent $event, \Throwable $exception): void
+    {
+        Log::error('Signal failed', [
+            'event' => $event->toArray(),
+            'error' => $exception->getMessage(),
+        ]);
+    }
+}
+```
+
+---
+
+## Configuration
+
+Configuration is stored in `config/signal.php`:
+
+### Jetstream URL
+
+```php
+'websocket_url' => env('SIGNAL_JETSTREAM_URL', 'wss://jetstream2.us-east.bsky.network'),
+```
+
+Available endpoints:
+- **US East**: `wss://jetstream2.us-east.bsky.network`
+- **US West**: `wss://jetstream1.us-west.bsky.network`
+
+### Cursor Storage
+
+Choose how to store cursor positions:
+
+```php
+'cursor_storage' => env('SIGNAL_CURSOR_STORAGE', 'database'),
+```
+
+| Driver | Best For | Configuration |
+|--------|----------|---------------|
+| `database` | Production, multi-server | Default connection |
+| `redis` | High performance, distributed | Redis connection |
+| `file` | Development, single server | Storage path |
+
+### Environment Variables
+
+Add to your `.env`:
+
+```env
+# Required
+SIGNAL_JETSTREAM_URL=wss://jetstream2.us-east.bsky.network
+
+# Optional
+SIGNAL_CURSOR_STORAGE=database
+SIGNAL_QUEUE_CONNECTION=redis
+SIGNAL_QUEUE=signal
+SIGNAL_BATCH_SIZE=100
+SIGNAL_RATE_LIMIT=1000
+```
+
+### Auto-Discovery
+
+Signals are automatically discovered from `app/Signals`. Disable if needed:
+
+```php
+'auto_discovery' => [
+    'enabled' => true,
+    'path' => app_path('Signals'),
+    'namespace' => 'App\\Signals',
+],
+```
+
+Or manually register Signals:
+
+```php
+'signals' => [
+    \App\Signals\NewPostSignal::class,
+    \App\Signals\NewFollowSignal::class,
+],
+```
+
+---
+
+## Available Commands
+
+### `signal:install`
+Install the package (publish config, migrations, run migrations)
+
+```bash
+php artisan signal:install
+```
+
+### `signal:consume`
+Start consuming events from Jetstream
+
+```bash
+php artisan signal:consume
+
+# Start from specific cursor
+php artisan signal:consume --cursor=123456789
+
+# Start fresh (ignore stored cursor)
+php artisan signal:consume --fresh
+```
+
+### `signal:list`
+List all registered Signals
+
+```bash
+php artisan signal:list
+```
+
+### `signal:make`
+Create a new Signal class
+
+```bash
+php artisan make:signal NewPostSignal
+
+# With options
+php artisan make:signal FollowSignal --type=commit --collection=app.bsky.graph.follow
+```
+
+### `signal:test`
+Test a Signal with sample data
+
+```bash
+php artisan signal:test NewPostSignal
+```
+
+---
+
+## Testing
+
+Signal includes a comprehensive test suite. Test your Signals:
+
+### Unit Testing
+
+```php
+use SocialDept\Signal\Events\CommitEvent;
+use SocialDept\Signal\Events\JetstreamEvent;
+
+class NewPostSignalTest extends TestCase
+{
+    /** @test */
+    public function it_handles_new_posts()
+    {
+        $signal = new NewPostSignal();
+
+        $event = new JetstreamEvent(
+            did: 'did:plc:test',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'test',
+                operation: 'create',
+                collection: 'app.bsky.feed.post',
+                rkey: 'test',
+                record: (object) [
+                    'text' => 'Hello World!',
+                    'createdAt' => now()->toIso8601String(),
+                ],
+            ),
+        );
+
+        $signal->handle($event);
+
+        // Assert your expected behavior
+    }
+}
+```
+
+### Testing with Artisan
+
+```bash
+php artisan signal:test NewPostSignal
+```
+
+---
+
+## Documentation
+
+For detailed documentation, see:
+
+- **[INSTALLATION.md](./INSTALLATION.md)** - Complete installation guide with troubleshooting
+- **[PACKAGE_SUMMARY.md](./PACKAGE_SUMMARY.md)** - Quick reference for package components
+- **[WILDCARD_EXAMPLES.md](./WILDCARD_EXAMPLES.md)** - Comprehensive wildcard pattern guide
+- **[IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)** - Full architecture and implementation details
+
+### External Resources
+
+- [AT Protocol Documentation](https://atproto.com/)
+- [Jetstream Documentation](https://docs.bsky.app/docs/advanced-guides/jetstream)
+- [Bluesky Lexicon](https://atproto.com/lexicons)
+
+---
+
+## Examples
+
+### Monitor All Feed Activity
+
+```php
+class FeedMonitorSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.*'];
+    }
+
+    public function handle(JetstreamEvent $event): void
+    {
+        // Handles posts, likes, reposts, etc.
+        Log::info('Feed activity', [
+            'collection' => $event->getCollection(),
+            'operation' => $event->getOperation(),
+            'did' => $event->did,
+        ]);
+    }
+}
+```
+
+### Track New Follows
+
+```php
+class NewFollowSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.graph.follow'];
+    }
+
+    public function handle(JetstreamEvent $event): void
+    {
+        if ($event->commit->isCreate()) {
+            $record = $event->getRecord();
+
+            // Store follow relationship
+            Follow::create([
+                'follower_did' => $event->did,
+                'following_did' => $record->subject,
+            ]);
+        }
+    }
+}
+```
+
+### Content Moderation
+
+```php
+class ModerationSignal extends Signal
+{
+    public function eventTypes(): array
+    {
+        return ['commit'];
+    }
+
+    public function collections(): ?array
+    {
+        return ['app.bsky.feed.post'];
+    }
+
+    public function shouldQueue(): bool
+    {
+        return true;
+    }
+
+    public function handle(JetstreamEvent $event): void
+    {
+        $record = $event->getRecord();
+
+        if ($this->containsProhibitedContent($record->text)) {
+            $this->flagForModeration($event->did, $record);
+        }
+    }
+}
+```
+
+---
+
+## Requirements
+
+- PHP 8.2 or higher
+- Laravel 11.0 or higher
+- WebSocket support (enabled by default in most environments)
+
+---
+
+## License
+
+The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](contributing.md) for details.
+
+---
+
+## Support
+
+For issues, questions, or feature requests:
+- Open an issue on GitHub
+- Check the [documentation files](#documentation)
+- Review the [implementation plan](./IMPLEMENTATION_PLAN.md)
+
+---
+
+**Built for the AT Protocol ecosystem** • Made with ❤️ by Social Dept

changelog.md

···
-# Changelog
-
-All notable changes to `Signal` will be documented in this file.
-
-## Version 1.0
-
-### Added
-- Everything

composer.json

···
 {
     "name": "social-dept/signal",
-    "description": ":package_description",
+    "description": "Laravel package for building Signals that respond to AT Protocol Jetstream events",
+    "type": "library",
     "license": "MIT",
-    "authors": [
-        {
-            "name": "Author Name",
-            "email": "[e-mail]",
-            "homepage": "http://author.com"
-        }
-    ],
-    "homepage": "https://github.com/social-dept/signal",
-    "keywords": ["Laravel", "Signal"],
     "require": {
-        "illuminate/support": "~9"
+        "php": "^8.2",
+        "illuminate/support": "^11.0",
+        "illuminate/console": "^11.0",
+        "illuminate/database": "^11.0",
+        "ratchet/pawl": "^0.4",
+        "react/event-loop": "^1.5"
     },
     "require-dev": {
-        "phpunit/phpunit": "~9.0",
-        "orchestra/testbench": "~7"
+        "orchestra/testbench": "^9.0",
+        "phpunit/phpunit": "^11.0"
     },
     "autoload": {
         "psr-4": {
···
     },
     "autoload-dev": {
         "psr-4": {
-            "SocialDept\\Signal\\Tests\\": "tests"
+            "SocialDept\\Signal\\Tests\\": "tests/"
         }
     },
     "extra": {

config/signal.php

···
 <?php
 
 return [
-    //
-];
+    /*
+    |--------------------------------------------------------------------------
+    | Jetstream WebSocket URL
+    |--------------------------------------------------------------------------
+    |
+    | The WebSocket URL for the AT Protocol Jetstream service.
+    | US East: wss://jetstream2.us-east.bsky.network
+    | US West: wss://jetstream1.us-west.bsky.network
+    |
+    */
+    'websocket_url' => env('SIGNAL_JETSTREAM_URL', 'wss://jetstream2.us-east.bsky.network'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Cursor Storage Driver
+    |--------------------------------------------------------------------------
+    |
+    | Determines how Signal stores the cursor position for resuming after
+    | disconnections. Options: 'database', 'redis', 'file'
+    |
+    */
+    'cursor_storage' => env('SIGNAL_CURSOR_STORAGE', 'database'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Cursor Storage Configuration
+    |--------------------------------------------------------------------------
+    */
+    'cursor_config' => [
+        'database' => [
+            'table' => 'signal_cursors',
+            'connection' => null, // null = default connection
+        ],
+        'redis' => [
+            'connection' => 'default',
+            'key' => 'signal:cursor',
+        ],
+        'file' => [
+            'path' => storage_path('signal/cursor.json'),
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Signals
+    |--------------------------------------------------------------------------
+    |
+    | Register your Signals here, or use auto-discovery by placing them
+    | in app/Signals directory.
+    |
+    */
+    'signals' => [
+        // App\Signals\NewPostSignal::class,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Auto-Discovery
+    |--------------------------------------------------------------------------
+    |
+    | Automatically discover Signals in the specified directory.
+    |
+    */
+    'auto_discovery' => [
+        'enabled' => true,
+        'path' => app_path('Signals'),
+        'namespace' => 'App\\Signals',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Queue Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Default queue settings for Signals that should be queued.
+    |
+    */
+    'queue' => [
+        'connection' => env('SIGNAL_QUEUE_CONNECTION', 'default'),
+        'queue' => env('SIGNAL_QUEUE', 'signal'),
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Connection Settings
+    |--------------------------------------------------------------------------
+    */
+    'connection' => [
+        'reconnect_attempts' => 5,
+        'reconnect_delay' => 5, // seconds
+        'ping_interval' => 30, // seconds
+        'timeout' => 60, // seconds
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Performance & Rate Limiting
+    |--------------------------------------------------------------------------
+    */
+    'performance' => [
+        'batch_size' => env('SIGNAL_BATCH_SIZE', 100),
+        'rate_limit' => env('SIGNAL_RATE_LIMIT', 1000), // events per minute
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Logging
+    |--------------------------------------------------------------------------
+    */
+    'logging' => [
+        'channel' => env('SIGNAL_LOG_CHANNEL', 'stack'),
+        'level' => env('SIGNAL_LOG_LEVEL', 'info'),
+    ],
+];

contributing.md

···
-# Contributing
-
-Contributions are welcome and will be fully credited.
-
-Contributions are accepted via Pull Requests on [Github](https://github.com/social-dept/signal).
-
-# Things you could do
-If you want to contribute but do not know where to start, this list provides some starting points.
-- Add license text
-- Remove rewriteRules.php
-- Set up TravisCI, StyleCI, ScrutinizerCI
-- Write a comprehensive ReadMe
-
-## Pull Requests
-
-- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
-
-- **Document any change in behaviour** - Make sure the `readme.md` and any other relevant documentation are kept up-to-date.
-
-- **Consider our release cycle** - We try to follow [SemVer v2.0.0](http://semver.org/). Randomly breaking public APIs is not an option.
-
-- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
-
-- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](http://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
-
-
-**Happy coding**!

database/migrations/2024_01_01_000000_create_signal_cursors_table.php

···
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('signal_cursors', function (Blueprint $table) {
+            $table->id();
+            $table->string('key')->unique();
+            $table->bigInteger('cursor');
+            $table->timestamps();
+
+            $table->index('key');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('signal_cursors');
+    }
+};

license.md

···
-# The license
-
-Copyright (c) Author Name <[e-mail]>
-
-...Add your license text here...

phpunit.xml

···
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit bootstrap="vendor/autoload.php"
-         backupGlobals="false"
-         backupStaticAttributes="false"
-         colors="true"
-         verbose="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true">
     <testsuites>
-        <testsuite name="Package">
-            <directory suffix=".php">./tests/</directory>
+        <testsuite name="Signal Test Suite">
+            <directory>tests</directory>
         </testsuite>
     </testsuites>
-    <filter>
-        <whitelist>
-            <directory>src/</directory>
-        </whitelist>
-    </filter>
+    <php>
+        <env name="APP_ENV" value="testing"/>
+        <env name="CACHE_DRIVER" value="array"/>
+        <env name="SESSION_DRIVER" value="array"/>
+        <env name="QUEUE_CONNECTION" value="sync"/>
+    </php>
 </phpunit>

readme.md

···
-# Signal
-
-[![Latest Version on Packagist][ico-version]][link-packagist]
-[![Total Downloads][ico-downloads]][link-downloads]
-[![Build Status][ico-travis]][link-travis]
-[![StyleCI][ico-styleci]][link-styleci]
-
-This is where your description should go. Take a look at [contributing.md](contributing.md) to see a to do list.
-
-## Installation
-
-Via Composer
-
-```bash
-composer require social-dept/signal
-```
-
-## Usage
-
-## Change log
-
-Please see the [changelog](changelog.md) for more information on what has changed recently.
-
-## Testing
-
-```bash
-composer test
-```
-
-## Contributing
-
-Please see [contributing.md](contributing.md) for details and a todolist.
-
-## Security
-
-If you discover any security related issues, please email [e-mail] instead of using the issue tracker.
-
-## Credits
-
-- [Author Name][link-author]
-- [All Contributors][link-contributors]
-
-## License
-
-MIT. Please see the [license file](license.md) for more information.
-
-[ico-version]: https://img.shields.io/packagist/v/social-dept/signal.svg?style=flat-square
-[ico-downloads]: https://img.shields.io/packagist/dt/social-dept/signal.svg?style=flat-square
-[ico-travis]: https://img.shields.io/travis/social-dept/signal/master.svg?style=flat-square
-[ico-styleci]: https://styleci.io/repos/12345678/shield
-
-[link-packagist]: https://packagist.org/packages/social-dept/signal
-[link-downloads]: https://packagist.org/packages/social-dept/signal
-[link-travis]: https://travis-ci.org/social-dept/signal
-[link-styleci]: https://styleci.io/repos/12345678
-[link-author]: https://github.com/social-dept
-[link-contributors]: ../../contributors

src/Commands/ConsumeCommand.php

···
+<?php
+
+namespace SocialDept\Signal\Commands;
+
+use Illuminate\Console\Command;
+use SocialDept\Signal\Services\JetstreamConsumer;
+use SocialDept\Signal\Services\SignalRegistry;
+
+class ConsumeCommand extends Command
+{
+    protected $signature = 'signal:consume
+                            {--cursor= : Start from a specific cursor position}
+                            {--fresh : Start from the beginning, ignoring stored cursor}';
+
+    protected $description = 'Start consuming events from the AT Protocol Jetstream';
+
+    public function handle(JetstreamConsumer $consumer, SignalRegistry $registry): int
+    {
+        $this->info('Signal: Initializing Jetstream consumer...');
+
+        // Discover signals
+        $registry->discover();
+
+        $signalCount = $registry->all()->count();
+        $this->info("Registered {$signalCount} signal(s)");
+
+        if ($signalCount === 0) {
+            $this->warn('No signals registered. Create signals in app/Signals or register them in config/signal.php');
+            return self::FAILURE;
+        }
+
+        // List registered signals
+        $this->table(
+            ['Signal', 'Event Types', 'Collections'],
+            $registry->all()->map(function ($signal) {
+                return [
+                    get_class($signal),
+                    implode(', ', $signal->eventTypes()),
+                    $signal->collections() ? implode(', ', $signal->collections()) : 'All',
+                ];
+            })
+        );
+
+        // Determine cursor
+        $cursor = null;
+        if ($this->option('fresh')) {
+            $this->info('Starting fresh from the beginning');
+        } elseif ($this->option('cursor')) {
+            $cursor = (int) $this->option('cursor');
+            $this->info("Starting from cursor: {$cursor}");
+        } else {
+            $this->info('Resuming from stored cursor position');
+        }
+
+        // Start consuming
+        $this->info('Starting Jetstream consumer... Press Ctrl+C to stop.');
+
+        try {
+            $consumer->start($cursor);
+        } catch (\Exception $e) {
+            $this->error('Error: ' . $e->getMessage());
+            return self::FAILURE;
+        }
+
+        return self::SUCCESS;
+    }
+}

src/Commands/InstallCommand.php

···
+<?php
+
+namespace SocialDept\Signal\Commands;
+
+use Illuminate\Console\Command;
+
+class InstallCommand extends Command
+{
+    protected $signature = 'signal:install';
+
+    protected $description = 'Install the Signal package (publish config, migrations, and run migrations)';
+
+    public function handle(): int
+    {
+        $this->info('Installing Signal package...');
+        $this->newLine();
+
+        // Publish config
+        $this->comment('Publishing configuration...');
+        $this->callSilently('vendor:publish', [
+            '--tag' => 'signal-config',
+            '--force' => $this->option('force', false),
+        ]);
+        $this->info('✓ Configuration published');
+
+        // Publish migrations
+        $this->comment('Publishing migrations...');
+        $this->callSilently('vendor:publish', [
+            '--tag' => 'signal-migrations',
+            '--force' => $this->option('force', false),
+        ]);
+        $this->info('✓ Migrations published');
+
+        // Run migrations
+        $this->newLine();
+        $this->comment('Running migrations...');
+
+        if ($this->confirm('Do you want to run the migrations now?', true)) {
+            $this->call('migrate');
+            $this->info('✓ Migrations completed');
+        } else {
+            $this->warn('⚠ Skipped migrations. Run "php artisan migrate" manually when ready.');
+        }
+
+        $this->newLine();
+        $this->info('Signal package installed successfully!');
+        $this->newLine();
+
+        // Show next steps
+        $this->line('Next steps:');
+        $this->line('1. Review the config file: config/signal.php');
+        $this->line('2. Create your first signal: php artisan make:signal NewPostSignal');
+        $this->line('3. Start consuming events: php artisan signal:consume');
+
+        return self::SUCCESS;
+    }
+}

src/Commands/ListSignalsCommand.php

···
+<?php
+
+namespace SocialDept\Signal\Commands;
+
+use Illuminate\Console\Command;
+use SocialDept\Signal\Services\SignalRegistry;
+
+class ListSignalsCommand extends Command
+{
+    protected $signature = 'signal:list';
+
+    protected $description = 'List all registered Signals';
+
+    public function handle(SignalRegistry $registry): int
+    {
+        $registry->discover();
+
+        $signals = $registry->all();
+
+        if ($signals->isEmpty()) {
+            $this->warn('No signals registered.');
+            $this->info('Create signals in app/Signals or register them in config/signal.php');
+            return self::SUCCESS;
+        }
+
+        $this->info("Found {$signals->count()} signal(s):");
+        $this->newLine();
+
+        $this->table(
+            ['Signal', 'Event Types', 'Collections', 'DIDs', 'Queued'],
+            $signals->map(function ($signal) {
+                return [
+                    get_class($signal),
+                    implode(', ', $signal->eventTypes()),
+                    $signal->collections() ? implode(', ', $signal->collections()) : 'All',
+                    $signal->dids() ? implode(', ', $signal->dids()) : 'All',
+                    $signal->shouldQueue() ? 'Yes' : 'No',
+                ];
+            })
+        );
+
+        return self::SUCCESS;
+    }
+}

src/Commands/MakeSignalCommand.php

···
+<?php
+
+namespace SocialDept\Signal\Commands;
+
+use Illuminate\Console\GeneratorCommand;
+use Symfony\Component\Console\Input\InputOption;
+
+class MakeSignalCommand extends GeneratorCommand
+{
+    protected $name = 'make:signal';
+
+    protected $description = 'Create a new Signal class';
+
+    protected $type = 'Signal';
+
+    protected function getStub(): string
+    {
+        return __DIR__ . '/../../stubs/signal.stub';
+    }
+
+    protected function getDefaultNamespace($rootNamespace): string
+    {
+        return $rootNamespace . '\\Signals';
+    }
+
+    protected function buildClass($name): string
+    {
+        $stub = parent::buildClass($name);
+
+        $eventType = $this->option('type') ?? 'commit';
+        $collection = $this->option('collection') ?? 'app.bsky.feed.post';
+
+        $stub = str_replace('{{ eventType }}', $eventType, $stub);
+        $stub = str_replace('{{ collection }}', $collection, $stub);
+
+        return $stub;
+    }
+
+    protected function getOptions(): array
+    {
+        return [
+            ['type', 't', InputOption::VALUE_OPTIONAL, 'The event type (commit, identity, account)'],
+            ['collection', 'c', InputOption::VALUE_OPTIONAL, 'The collection to watch'],
+        ];
+    }
+}

src/Commands/TestSignalCommand.php

···
+<?php
+
+namespace SocialDept\Signal\Commands;
+
+use Illuminate\Console\Command;
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Events\CommitEvent;
+
+class TestSignalCommand extends Command
+{
+    protected $signature = 'signal:test
+                            {signal : The Signal class name}
+                            {--sample=commit : The type of sample event to use}';
+
+    protected $description = 'Test a Signal with sample data';
+
+    public function handle(): int
+    {
+        $signalClass = $this->argument('signal');
+
+        // Try to resolve the class
+        if (!class_exists($signalClass)) {
+            $signalClass = 'App\\Signals\\' . $signalClass;
+        }
+
+        if (!class_exists($signalClass)) {
+            $this->error("Signal class not found: {$signalClass}");
+            return self::FAILURE;
+        }
+
+        $signal = app($signalClass);
+
+        $this->info("Testing signal: {$signalClass}");
+        $this->newLine();
+
+        // Create sample event
+        $event = $this->createSampleEvent($this->option('sample'));
+
+        $this->info('Sample event created:');
+        $this->line(json_encode($event->toArray(), JSON_PRETTY_PRINT));
+        $this->newLine();
+
+        try {
+            if ($signal->shouldHandle($event)) {
+                $this->info('Calling signal->handle()...');
+                $signal->handle($event);
+                $this->info('✓ Signal executed successfully');
+            } else {
+                $this->warn('Signal->shouldHandle() returned false');
+            }
+        } catch (\Exception $e) {
+            $this->error('Error executing signal: ' . $e->getMessage());
+            return self::FAILURE;
+        }
+
+        return self::SUCCESS;
+    }
+
+    protected function createSampleEvent(string $type): JetstreamEvent
+    {
+        switch ($type) {
+            case 'commit':
+                return new JetstreamEvent(
+                    did: 'did:plc:sample123456789',
+                    timeUs: time() * 1000000,
+                    kind: 'commit',
+                    commit: new CommitEvent(
+                        rev: 'sample-rev',
+                        operation: 'create',
+                        collection: 'app.bsky.feed.post',
+                        rkey: 'sample-rkey',
+                        record: (object) [
+                            'text' => 'This is a sample post for testing',
+                            'createdAt' => now()->toIso8601String(),
+                        ],
+                        cid: 'sample-cid',
+                    ),
+                );
+
+            default:
+                throw new \InvalidArgumentException("Unknown sample type: {$type}");
+        }
+    }
+}

src/Contracts/CursorStore.php

···
+<?php
+
+namespace SocialDept\Signal\Contracts;
+
+interface CursorStore
+{
+    /**
+     * Get the current cursor position.
+     */
+    public function get(): ?int;
+
+    /**
+     * Set the cursor position.
+     */
+    public function set(int $cursor): void;
+
+    /**
+     * Clear the cursor position.
+     */
+    public function clear(): void;
+}

src/Events/AccountEvent.php

···
+<?php
+
+namespace SocialDept\Signal\Events;
+
+class AccountEvent
+{
+    public function __construct(
+        public string $did,
+        public bool $active,
+        public ?string $status = null,
+        public int $seq = 0,
+        public ?string $time = null,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            did: $data['did'],
+            active: $data['active'],
+            status: $data['status'] ?? null,
+            seq: $data['seq'] ?? 0,
+            time: $data['time'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'did' => $this->did,
+            'active' => $this->active,
+            'status' => $this->status,
+            'seq' => $this->seq,
+            'time' => $this->time,
+        ];
+    }
+}

src/Events/CommitEvent.php

···
+<?php
+
+namespace SocialDept\Signal\Events;
+
+class CommitEvent
+{
+    public function __construct(
+        public string $rev,
+        public string $operation, // 'create', 'update', 'delete'
+        public string $collection,
+        public string $rkey,
+        public ?object $record = null,
+        public ?string $cid = null,
+    ) {}
+
+    public function isCreate(): bool
+    {
+        return $this->operation === 'create';
+    }
+
+    public function isUpdate(): bool
+    {
+        return $this->operation === 'update';
+    }
+
+    public function isDelete(): bool
+    {
+        return $this->operation === 'delete';
+    }
+
+    public function uri(): string
+    {
+        return "at://{$this->collection}/{$this->rkey}";
+    }
+
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            rev: $data['rev'],
+            operation: $data['operation'],
+            collection: $data['collection'],
+            rkey: $data['rkey'],
+            record: isset($data['record']) ? (object) $data['record'] : null,
+            cid: $data['cid'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'rev' => $this->rev,
+            'operation' => $this->operation,
+            'collection' => $this->collection,
+            'rkey' => $this->rkey,
+            'record' => $this->record,
+            'cid' => $this->cid,
+        ];
+    }
+}

src/Events/IdentityEvent.php

···
+<?php
+
+namespace SocialDept\Signal\Events;
+
+class IdentityEvent
+{
+    public function __construct(
+        public string $did,
+        public ?string $handle = null,
+        public int $seq = 0,
+        public ?string $time = null,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            did: $data['did'],
+            handle: $data['handle'] ?? null,
+            seq: $data['seq'] ?? 0,
+            time: $data['time'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'did' => $this->did,
+            'handle' => $this->handle,
+            'seq' => $this->seq,
+            'time' => $this->time,
+        ];
+    }
+}

src/Events/JetstreamEvent.php

···
+<?php
+
+namespace SocialDept\Signal\Events;
+
+class JetstreamEvent
+{
+    public function __construct(
+        public string $did,
+        public int $timeUs,
+        public string $kind, // 'commit', 'identity', 'account'
+        public ?CommitEvent $commit = null,
+        public ?IdentityEvent $identity = null,
+        public ?AccountEvent $account = null,
+    ) {}
+
+    public function isCommit(): bool
+    {
+        return $this->kind === 'commit';
+    }
+
+    public function isIdentity(): bool
+    {
+        return $this->kind === 'identity';
+    }
+
+    public function isAccount(): bool
+    {
+        return $this->kind === 'account';
+    }
+
+    public function getCollection(): ?string
+    {
+        return $this->commit?->collection;
+    }
+
+    public function getRecord(): ?object
+    {
+        return $this->commit?->record;
+    }
+
+    public function getOperation(): ?string
+    {
+        return $this->commit?->operation;
+    }
+
+    public static function fromArray(array $data): self
+    {
+        $commit = isset($data['commit'])
+            ? CommitEvent::fromArray($data['commit'])
+            : null;
+
+        $identity = isset($data['identity'])
+            ? IdentityEvent::fromArray($data['identity'])
+            : null;
+
+        $account = isset($data['account'])
+            ? AccountEvent::fromArray($data['account'])
+            : null;
+
+        return new self(
+            did: $data['did'],
+            timeUs: $data['time_us'],
+            kind: $data['kind'],
+            commit: $commit,
+            identity: $identity,
+            account: $account,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'did' => $this->did,
+            'time_us' => $this->timeUs,
+            'kind' => $this->kind,
+            'commit' => $this->commit?->toArray(),
+            'identity' => $this->identity?->toArray(),
+            'account' => $this->account?->toArray(),
+        ];
+    }
+}

src/Exceptions/ConnectionException.php

···
+<?php
+
+namespace SocialDept\Signal\Exceptions;
+
+class ConnectionException extends \Exception
+{
+    //
+}

src/Exceptions/SignalException.php

···
+<?php
+
+namespace SocialDept\Signal\Exceptions;
+
+class SignalException extends \Exception
+{
+    //
+}

src/Facades/Signal.php

···
 namespace SocialDept\Signal\Facades;
 
 use Illuminate\Support\Facades\Facade;
+use SocialDept\Signal\Services\JetstreamConsumer;
 
+/**
+ * @method static void start(?int $cursor = null)
+ * @method static void stop()
+ *
+ * @see \SocialDept\Signal\Services\JetstreamConsumer
+ */
 class Signal extends Facade
 {
-    /**
-     * Get the registered name of the component.
-     *
-     * @return string
-     */
     protected static function getFacadeAccessor(): string
     {
-        return 'signal';
+        return JetstreamConsumer::class;
     }
 }

src/Jobs/ProcessSignalJob.php

···
+<?php
+
+namespace SocialDept\Signal\Jobs;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class ProcessSignalJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function __construct(
+        protected Signal $signal,
+        protected JetstreamEvent $event,
+    ) {}
+
+    public function handle(): void
+    {
+        $this->signal->handle($this->event);
+    }
+
+    public function failed(\Throwable $exception): void
+    {
+        $this->signal->failed($this->event, $exception);
+    }
+}

src/Services/EventDispatcher.php

···
+<?php
+
+namespace SocialDept\Signal\Services;
+
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Queue;
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Jobs\ProcessSignalJob;
+
+class EventDispatcher
+{
+    protected SignalRegistry $signalRegistry;
+
+    public function __construct(SignalRegistry $signalRegistry)
+    {
+        $this->signalRegistry = $signalRegistry;
+    }
+
+    /**
+     * Dispatch event to matching signals.
+     */
+    public function dispatch(JetstreamEvent $event): void
+    {
+        $signals = $this->signalRegistry->getMatchingSignals($event);
+
+        foreach ($signals as $signal) {
+            try {
+                if ($signal->shouldQueue()) {
+                    $this->dispatchToQueue($signal, $event);
+                } else {
+                    $this->dispatchSync($signal, $event);
+                }
+            } catch (\Exception $e) {
+                Log::error('Signal: Error dispatching to signal', [
+                    'signal' => get_class($signal),
+                    'error' => $e->getMessage(),
+                ]);
+
+                $signal->failed($event, $e);
+            }
+        }
+    }
+
+    /**
+     * Dispatch signal synchronously.
+     */
+    protected function dispatchSync($signal, JetstreamEvent $event): void
+    {
+        $signal->handle($event);
+    }
+
+    /**
+     * Dispatch signal to queue.
+     */
+    protected function dispatchToQueue($signal, JetstreamEvent $event): void
+    {
+        ProcessSignalJob::dispatch($signal, $event)
+            ->onConnection($signal->queueConnection())
+            ->onQueue($signal->queue());
+    }
+}

src/Services/JetstreamConsumer.php

···
+<?php
+
+namespace SocialDept\Signal\Services;
+
+use Illuminate\Support\Facades\Log;
+use Ratchet\Client\Connector;
+use Ratchet\Client\WebSocket;
+use React\EventLoop\Loop;
+use SocialDept\Signal\Contracts\CursorStore;
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Exceptions\ConnectionException;
+
+class JetstreamConsumer
+{
+    protected CursorStore $cursorStore;
+    protected SignalRegistry $signalRegistry;
+    protected EventDispatcher $eventDispatcher;
+    protected ?WebSocket $connection = null;
+    protected int $reconnectAttempts = 0;
+    protected bool $shouldStop = false;
+
+    public function __construct(
+        CursorStore $cursorStore,
+        SignalRegistry $signalRegistry,
+        EventDispatcher $eventDispatcher
+    ) {
+        $this->cursorStore = $cursorStore;
+        $this->signalRegistry = $signalRegistry;
+        $this->eventDispatcher = $eventDispatcher;
+    }
+
+    /**
+     * Start consuming the Jetstream.
+     */
+    public function start(?int $cursor = null): void
+    {
+        $this->shouldStop = false;
+
+        // Get cursor from storage if not provided
+        if ($cursor === null) {
+            $cursor = $this->cursorStore->get();
+        }
+
+        $url = $this->buildWebSocketUrl($cursor);
+
+        Log::info('Signal: Starting Jetstream consumer', [
+            'url' => $url,
+            'cursor' => $cursor,
+        ]);
+
+        $this->connect($url);
+    }
+
+    /**
+     * Stop consuming the Jetstream.
+     */
+    public function stop(): void
+    {
+        $this->shouldStop = true;
+
+        if ($this->connection) {
+            $this->connection->close();
+        }
+
+        Log::info('Signal: Jetstream consumer stopped');
+    }
+
+    /**
+     * Connect to the Jetstream WebSocket.
+     */
+    protected function connect(string $url): void
+    {
+        $loop = Loop::get();
+        $connector = new Connector($loop);
+
+        $connector($url)->then(
+            function (WebSocket $conn) {
+                $this->connection = $conn;
+                $this->reconnectAttempts = 0;
+
+                Log::info('Signal: Connected to Jetstream');
+
+                $conn->on('message', function ($msg) {
+                    $this->handleMessage($msg);
+                });
+
+                $conn->on('close', function ($code, $reason) {
+                    Log::warning('Signal: Connection closed', [
+                        'code' => $code,
+                        'reason' => $reason,
+                    ]);
+
+                    if (!$this->shouldStop) {
+                        $this->attemptReconnect();
+                    }
+                });
+
+                $conn->on('error', function (\Exception $e) {
+                    Log::error('Signal: Connection error', [
+                        'error' => $e->getMessage(),
+                    ]);
+                });
+
+                // Setup ping interval to keep connection alive
+                $this->setupPingInterval($conn, $loop);
+            },
+            function (\Exception $e) {
+                Log::error('Signal: Could not connect to Jetstream', [
+                    'error' => $e->getMessage(),
+                ]);
+
+                if (!$this->shouldStop) {
+                    $this->attemptReconnect();
+                }
+            }
+        );
+
+        $loop->run();
+    }
+
+    /**
+     * Handle incoming WebSocket message.
+     */
+    protected function handleMessage($message): void
+    {
+        try {
+            $data = json_decode($message, true);
+
+            if (!$data) {
+                Log::warning('Signal: Failed to decode message');
+                return;
+            }
+
+            $event = JetstreamEvent::fromArray($data);
+
+            // Update cursor
+            $this->cursorStore->set($event->timeUs);
+
+            // Dispatch to matching signals
+            $this->eventDispatcher->dispatch($event);
+
+        } catch (\Exception $e) {
+            Log::error('Signal: Error handling message', [
+                'error' => $e->getMessage(),
+                'trace' => $e->getTraceAsString(),
+            ]);
+        }
+    }
+
+    /**
+     * Attempt to reconnect to the Jetstream.
+     */
+    protected function attemptReconnect(): void
+    {
+        $maxAttempts = config('signal.connection.reconnect_attempts', 5);
+        $delay = config('signal.connection.reconnect_delay', 5);
+
+        if ($this->reconnectAttempts >= $maxAttempts) {
+            Log::error('Signal: Max reconnection attempts reached');
+            throw new ConnectionException('Failed to reconnect to Jetstream after ' . $maxAttempts . ' attempts');
+        }
+
+        $this->reconnectAttempts++;
+
+        Log::info('Signal: Attempting to reconnect', [
+            'attempt' => $this->reconnectAttempts,
+            'max_attempts' => $maxAttempts,
+        ]);
+
+        sleep($delay);
+
+        $cursor = $this->cursorStore->get();
+        $url = $this->buildWebSocketUrl($cursor);
+
+        $this->connect($url);
+    }
+
+    /**
+     * Setup ping interval to keep connection alive.
+     */
+    protected function setupPingInterval(WebSocket $conn, $loop): void
+    {
+        $interval = config('signal.connection.ping_interval', 30);
+
+        $loop->addPeriodicTimer($interval, function () use ($conn) {
+            if ($conn->getReadyState() === WebSocket::STATE_OPEN) {
+                $conn->send(json_encode(['type' => 'ping']));
+            }
+        });
+    }
+
+    /**
+     * Build the WebSocket URL with optional cursor.
+     */
+    protected function buildWebSocketUrl(?int $cursor = null): string
+    {
+        $baseUrl = config('signal.websocket_url', 'wss://jetstream2.us-east.bsky.network');
+        $url = rtrim($baseUrl, '/') . '/subscribe';
+
+        if ($cursor !== null) {
+            $url .= '?cursor=' . $cursor;
+        }
+
+        return $url;
+    }
+}

src/Services/SignalRegistry.php

···
+<?php
+
+namespace SocialDept\Signal\Services;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\File;
+use ReflectionClass;
+use SocialDept\Signal\Signals\Signal;
+
+class SignalRegistry
+{
+    protected Collection $signals;
+
+    public function __construct()
+    {
+        $this->signals = collect();
+    }
+
+    /**
+     * Register a signal.
+     */
+    public function register(string $signalClass): void
+    {
+        if (!is_subclass_of($signalClass, Signal::class)) {
+            throw new \InvalidArgumentException(
+                "Signal class must extend " . Signal::class
+            );
+        }
+
+        $this->signals->push($signalClass);
+    }
+
+    /**
+     * Get all registered signals.
+     */
+    public function all(): Collection
+    {
+        return $this->signals->map(fn($class) => app($class));
+    }
+
+    /**
+     * Auto-discover signals in the configured directory.
+     */
+    public function discover(): void
+    {
+        if (!config('signal.auto_discovery.enabled', true)) {
+            return;
+        }
+
+        $path = config('signal.auto_discovery.path', app_path('Signals'));
+        $namespace = config('signal.auto_discovery.namespace', 'App\\Signals');
+
+        if (!File::exists($path)) {
+            return;
+        }
+
+        $files = File::allFiles($path);
+
+        foreach ($files as $file) {
+            $class = $namespace . '\\' . $file->getFilenameWithoutExtension();
+
+            if (class_exists($class) && is_subclass_of($class, Signal::class)) {
+                $this->register($class);
+            }
+        }
+    }
+
+    /**
+     * Get signals that match the given event.
+     */
+    public function getMatchingSignals($event): Collection
+    {
+        return $this->all()->filter(function (Signal $signal) use ($event) {
+            // Check event type
+            if (!in_array($event->kind, $signal->eventTypes())) {
+                return false;
+            }
+
+            // Check collections filter (with wildcard support)
+            if ($signal->collections() !== null && $event->isCommit()) {
+                if (!$this->matchesCollection($event->getCollection(), $signal->collections())) {
+                    return false;
+                }
+            }
+
+            // Check DIDs filter
+            if ($signal->dids() !== null) {
+                if (!in_array($event->did, $signal->dids())) {
+                    return false;
+                }
+            }
+
+            // Check custom shouldHandle logic
+            if (!$signal->shouldHandle($event)) {
+                return false;
+            }
+
+            return true;
+        });
+    }
+
+    /**
+     * Check if a collection matches any of the patterns (supports wildcards).
+     *
+     * @param string|null $collection The actual collection from the event
+     * @param array $patterns Array of collection patterns (may include wildcards like 'app.bsky.feed.*')
+     * @return bool
+     */
+    protected function matchesCollection(?string $collection, array $patterns): bool
+    {
+        if ($collection === null) {
+            return false;
+        }
+
+        foreach ($patterns as $pattern) {
+            // Exact match
+            if ($pattern === $collection) {
+                return true;
+            }
+
+            // Wildcard match
+            if (str_contains($pattern, '*')) {
+                // Convert wildcard pattern to regex
+                // Escape special regex characters except *
+                $regex = preg_quote($pattern, '/');
+                // Replace escaped \* with .* for regex wildcard
+                $regex = str_replace('\*', '.*', $regex);
+
+                if (preg_match('/^' . $regex . '$/', $collection)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+}

src/Signal.php

···
-<?php
-
-namespace SocialDept\Signal;
-
-class Signal
-{
-    // Build wonderful things
-}

src/SignalServiceProvider.php

···
 namespace SocialDept\Signal;
 
 use Illuminate\Support\ServiceProvider;
+use SocialDept\Signal\Commands\ConsumeCommand;
+use SocialDept\Signal\Commands\InstallCommand;
+use SocialDept\Signal\Commands\ListSignalsCommand;
+use SocialDept\Signal\Commands\MakeSignalCommand;
+use SocialDept\Signal\Commands\TestSignalCommand;
+use SocialDept\Signal\Contracts\CursorStore;
+use SocialDept\Signal\Services\EventDispatcher;
+use SocialDept\Signal\Services\JetstreamConsumer;
+use SocialDept\Signal\Services\SignalRegistry;
+use SocialDept\Signal\Storage\DatabaseCursorStore;
+use SocialDept\Signal\Storage\FileCursorStore;
+use SocialDept\Signal\Storage\RedisCursorStore;
 
 class SignalServiceProvider extends ServiceProvider
 {
-    /**
-     * Perform post-registration booting of services.
-     *
-     * @return void
-     */
-    public function boot(): void
+    public function register(): void
     {
-        // $this->loadTranslationsFrom(__DIR__.'/../resources/lang', 'social-dept');
-        // $this->loadViewsFrom(__DIR__.'/../resources/views', 'social-dept');
-        // $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
-        // $this->loadRoutesFrom(__DIR__.'/routes.php');
+        $this->mergeConfigFrom(__DIR__ . '/../config/signal.php', 'signal');
+
+        // Register cursor store
+        $this->app->singleton(CursorStore::class, function ($app) {
+            return match (config('signal.cursor_storage')) {
+                'redis' => new RedisCursorStore(),
+                'file' => new FileCursorStore(),
+                default => new DatabaseCursorStore(),
+            };
+        });
+
+        // Register signal registry
+        $this->app->singleton(SignalRegistry::class, function ($app) {
+            $registry = new SignalRegistry();
 
-        // Publishing is only necessary when using the CLI.
-        if ($this->app->runningInConsole()) {
-            $this->bootForConsole();
-        }
-    }
+            // Register configured signals
+            foreach (config('signal.signals', []) as $signal) {
+                $registry->register($signal);
+            }
 
-    /**
-     * Register any package services.
-     *
-     * @return void
-     */
-    public function register(): void
-    {
-        $this->mergeConfigFrom(__DIR__.'/../config/signal.php', 'signal');
+            return $registry;
+        });
 
-        // Register the service the package provides.
-        $this->app->singleton('signal', function ($app) {
-            return new Signal;
+        // Register event dispatcher
+        $this->app->singleton(EventDispatcher::class, function ($app) {
+            return new EventDispatcher($app->make(SignalRegistry::class));
         });
-    }
 
-    /**
-     * Get the services provided by the provider.
-     *
-     * @return array
-     */
-    public function provides()
-    {
-        return ['signal'];
+        // Register Jetstream consumer
+        $this->app->singleton(JetstreamConsumer::class, function ($app) {
+            return new JetstreamConsumer(
+                $app->make(CursorStore::class),
+                $app->make(SignalRegistry::class),
+                $app->make(EventDispatcher::class),
+            );
+        });
     }
 
-    /**
-     * Console-specific booting.
-     *
-     * @return void
-     */
-    protected function bootForConsole(): void
+    public function boot(): void
     {
-        // Publishing the configuration file.
-        $this->publishes([
-            __DIR__.'/../config/signal.php' => config_path('signal.php'),
-        ], 'signal.config');
-
-        // Publishing the views.
-        /*$this->publishes([
-            __DIR__.'/../resources/views' => base_path('resources/views/vendor/social-dept'),
-        ], 'signal.views');*/
+        if ($this->app->runningInConsole()) {
+            // Publish config
+            $this->publishes([
+                __DIR__ . '/../config/signal.php' => config_path('signal.php'),
+            ], 'signal-config');
 
-        // Publishing assets.
-        /*$this->publishes([
-            __DIR__.'/../resources/assets' => public_path('vendor/social-dept'),
-        ], 'signal.assets');*/
+            // Publish migrations
+            $this->publishes([
+                __DIR__ . '/../database/migrations' => database_path('migrations'),
+            ], 'signal-migrations');
 
-        // Publishing the translation files.
-        /*$this->publishes([
-            __DIR__.'/../resources/lang' => resource_path('lang/vendor/social-dept'),
-        ], 'signal.lang');*/
+            // Register commands
+            $this->commands([
+                InstallCommand::class,
+                ConsumeCommand::class,
+                ListSignalsCommand::class,
+                MakeSignalCommand::class,
+                TestSignalCommand::class,
+            ]);
+        }
 
-        // Registering package commands.
-        // $this->commands([]);
+        // Load migrations
+        $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
     }
 }

src/Signals/Signal.php

···
+<?php
+
+namespace SocialDept\Signal\Signals;
+
+use SocialDept\Signal\Events\JetstreamEvent;
+
+abstract class Signal
+{
+    /**
+     * Define which event types to listen for.
+     *
+     * @return array<string> ['commit', 'identity', 'account']
+     */
+    abstract public function eventTypes(): array;
+
+    /**
+     * Define collections to watch (optional, null = all).
+     * Supports wildcards using asterisk (*).
+     *
+     * Examples:
+     * - ['app.bsky.feed.post'] - Only posts
+     * - ['app.bsky.feed.*'] - All feed collections (post, like, repost, etc.)
+     * - ['app.bsky.graph.*'] - All graph collections (follow, block, etc.)
+     * - ['app.bsky.*'] - All app.bsky collections
+     *
+     * @return array<string>|null
+     */
+    public function collections(): ?array
+    {
+        return null;
+    }
+
+    /**
+     * Define DIDs to watch (optional, null = all).
+     *
+     * @return array<string>|null
+     */
+    public function dids(): ?array
+    {
+        return null;
+    }
+
+    /**
+     * Handle the Jetstream event.
+     */
+    abstract public function handle(JetstreamEvent $event): void;
+
+    /**
+     * Determine if this signal should handle the event.
+     */
+    public function shouldHandle(JetstreamEvent $event): bool
+    {
+        return true;
+    }
+
+    /**
+     * Should this signal be queued?
+     */
+    public function shouldQueue(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Get the queue connection name.
+     */
+    public function queueConnection(): ?string
+    {
+        return config('signal.queue.connection');
+    }
+
+    /**
+     * Get the queue name.
+     */
+    public function queue(): ?string
+    {
+        return config('signal.queue.queue');
+    }
+
+    /**
+     * Middleware to run before handling the event.
+     *
+     * @return array
+     */
+    public function middleware(): array
+    {
+        return [];
+    }
+
+    /**
+     * Handle a failed signal execution.
+     */
+    public function failed(JetstreamEvent $event, \Throwable $exception): void
+    {
+        //
+    }
+}

src/Storage/DatabaseCursorStore.php

···
+<?php
+
+namespace SocialDept\Signal\Storage;
+
+use Illuminate\Support\Facades\DB;
+use SocialDept\Signal\Contracts\CursorStore;
+
+class DatabaseCursorStore implements CursorStore
+{
+    protected string $table;
+    protected ?string $connection;
+
+    public function __construct()
+    {
+        $this->table = config('signal.cursor_config.database.table', 'signal_cursors');
+        $this->connection = config('signal.cursor_config.database.connection');
+    }
+
+    public function get(): ?int
+    {
+        $cursor = $this->query()
+            ->where('key', 'jetstream')
+            ->value('cursor');
+
+        return $cursor ? (int) $cursor : null;
+    }
+
+    public function set(int $cursor): void
+    {
+        $this->query()
+            ->updateOrInsert(
+                ['key' => 'jetstream'],
+                [
+                    'cursor' => $cursor,
+                    'updated_at' => now(),
+                ]
+            );
+    }
+
+    public function clear(): void
+    {
+        $this->query()
+            ->where('key', 'jetstream')
+            ->delete();
+    }
+
+    protected function query()
+    {
+        return DB::connection($this->connection)
+            ->table($this->table);
+    }
+}

src/Storage/FileCursorStore.php

···
+<?php
+
+namespace SocialDept\Signal\Storage;
+
+use Illuminate\Support\Facades\File;
+use SocialDept\Signal\Contracts\CursorStore;
+
+class FileCursorStore implements CursorStore
+{
+    protected string $path;
+
+    public function __construct()
+    {
+        $this->path = config('signal.cursor_config.file.path', storage_path('signal/cursor.json'));
+
+        // Ensure directory exists
+        $directory = dirname($this->path);
+        if (!File::exists($directory)) {
+            File::makeDirectory($directory, 0755, true);
+        }
+    }
+
+    public function get(): ?int
+    {
+        if (!File::exists($this->path)) {
+            return null;
+        }
+
+        $data = json_decode(File::get($this->path), true);
+
+        return $data['cursor'] ?? null;
+    }
+
+    public function set(int $cursor): void
+    {
+        File::put($this->path, json_encode([
+            'cursor' => $cursor,
+            'updated_at' => now()->toIso8601String(),
+        ], JSON_PRETTY_PRINT));
+    }
+
+    public function clear(): void
+    {
+        if (File::exists($this->path)) {
+            File::delete($this->path);
+        }
+    }
+}

src/Storage/RedisCursorStore.php

···
+<?php
+
+namespace SocialDept\Signal\Storage;
+
+use Illuminate\Support\Facades\Redis;
+use SocialDept\Signal\Contracts\CursorStore;
+
+class RedisCursorStore implements CursorStore
+{
+    protected string $connection;
+    protected string $key;
+
+    public function __construct()
+    {
+        $this->connection = config('signal.cursor_config.redis.connection', 'default');
+        $this->key = config('signal.cursor_config.redis.key', 'signal:cursor');
+    }
+
+    public function get(): ?int
+    {
+        $cursor = Redis::connection($this->connection)->get($this->key);
+
+        return $cursor ? (int) $cursor : null;
+    }
+
+    public function set(int $cursor): void
+    {
+        Redis::connection($this->connection)->set($this->key, $cursor);
+    }
+
+    public function clear(): void
+    {
+        Redis::connection($this->connection)->del($this->key);
+    }
+}

stubs/signal.stub

···
+<?php
+
+namespace {{ namespace }};
+
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class {{ class }} extends Signal
+{
+    /**
+     * Define which event types to listen for.
+     */
+    public function eventTypes(): array
+    {
+        return ['{{ eventType }}'];
+    }
+
+    /**
+     * Define collections to watch (optional, null = all).
+     *
+     * Supports wildcards:
+     * - ['app.bsky.feed.post'] - Only posts
+     * - ['app.bsky.feed.*'] - All feed collections
+     * - ['app.bsky.graph.*'] - All graph collections
+     */
+    public function collections(): ?array
+    {
+        return ['{{ collection }}'];
+    }
+
+    /**
+     * Handle the Jetstream event.
+     */
+    public function handle(JetstreamEvent $event): void
+    {
+        // Handle the event here
+
+        // Example: Access commit data
+        if ($event->isCommit()) {
+            $record = $event->getRecord();
+            $operation = $event->getOperation();
+            $collection = $event->getCollection();
+
+            // Your logic here
+        }
+    }
+
+    /**
+     * Determine if this signal should handle the event.
+     */
+    public function shouldHandle(JetstreamEvent $event): bool
+    {
+        return true;
+    }
+
+    /**
+     * Should this signal be queued?
+     */
+    public function shouldQueue(): bool
+    {
+        return false;
+    }
+}

tests/Unit/SignalRegistryTest.php

···
+<?php
+
+namespace SocialDept\Signal\Tests\Unit;
+
+use Orchestra\Testbench\TestCase;
+use SocialDept\Signal\Events\CommitEvent;
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Services\SignalRegistry;
+use SocialDept\Signal\Signals\Signal;
+
+class SignalRegistryTest extends TestCase
+{
+    /** @test */
+    public function it_matches_exact_collections()
+    {
+        $registry = new SignalRegistry();
+
+        $event = new JetstreamEvent(
+            did: 'did:plc:test',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'test',
+                operation: 'create',
+                collection: 'app.bsky.feed.post',
+                rkey: 'test',
+            ),
+        );
+
+        $result = $this->invokeMethod(
+            $registry,
+            'matchesCollection',
+            ['app.bsky.feed.post', ['app.bsky.feed.post']]
+        );
+
+        $this->assertTrue($result);
+    }
+
+    /** @test */
+    public function it_matches_wildcard_collections()
+    {
+        $registry = new SignalRegistry();
+
+        // Test app.bsky.feed.*
+        $this->assertTrue(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.feed.post', ['app.bsky.feed.*']]
+            )
+        );
+
+        $this->assertTrue(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.feed.like', ['app.bsky.feed.*']]
+            )
+        );
+
+        $this->assertFalse(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.graph.follow', ['app.bsky.feed.*']]
+            )
+        );
+
+        // Test app.bsky.*
+        $this->assertTrue(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.feed.post', ['app.bsky.*']]
+            )
+        );
+
+        $this->assertTrue(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.graph.follow', ['app.bsky.*']]
+            )
+        );
+    }
+
+    /** @test */
+    public function it_matches_multiple_patterns()
+    {
+        $registry = new SignalRegistry();
+
+        $patterns = [
+            'app.bsky.feed.post',
+            'app.bsky.graph.*',
+        ];
+
+        // Exact match
+        $this->assertTrue(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.feed.post', $patterns]
+            )
+        );
+
+        // Wildcard match
+        $this->assertTrue(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.graph.follow', $patterns]
+            )
+        );
+
+        // No match
+        $this->assertFalse(
+            $this->invokeMethod(
+                $registry,
+                'matchesCollection',
+                ['app.bsky.feed.like', $patterns]
+            )
+        );
+    }
+
+    /**
+     * Call protected/private method of a class.
+     */
+    protected function invokeMethod(&$object, $methodName, array $parameters = [])
+    {
+        $reflection = new \ReflectionClass(get_class($object));
+        $method = $reflection->getMethod($methodName);
+        $method->setAccessible(true);
+
+        return $method->invokeArgs($object, $parameters);
+    }
+}

tests/Unit/SignalTest.php

···
+<?php
+
+namespace SocialDept\Signal\Tests\Unit;
+
+use Orchestra\Testbench\TestCase;
+use SocialDept\Signal\Events\CommitEvent;
+use SocialDept\Signal\Events\JetstreamEvent;
+use SocialDept\Signal\Signals\Signal;
+
+class SignalTest extends TestCase
+{
+    /** @test */
+    public function it_can_create_a_signal()
+    {
+        $signal = new class extends Signal {
+            public function eventTypes(): array
+            {
+                return ['commit'];
+            }
+
+            public function handle(JetstreamEvent $event): void
+            {
+                //
+            }
+        };
+
+        $this->assertInstanceOf(Signal::class, $signal);
+        $this->assertEquals(['commit'], $signal->eventTypes());
+    }
+
+    /** @test */
+    public function it_can_filter_by_exact_collection()
+    {
+        $signal = new class extends Signal {
+            public function eventTypes(): array
+            {
+                return ['commit'];
+            }
+
+            public function collections(): ?array
+            {
+                return ['app.bsky.feed.post'];
+            }
+
+            public function handle(JetstreamEvent $event): void
+            {
+                //
+            }
+        };
+
+        $event = new JetstreamEvent(
+            did: 'did:plc:test',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'test',
+                operation: 'create',
+                collection: 'app.bsky.feed.post',
+                rkey: 'test',
+            ),
+        );
+
+        $this->assertTrue($signal->shouldHandle($event));
+    }
+
+    /** @test */
+    public function it_can_filter_by_wildcard_collection()
+    {
+        $signal = new class extends Signal {
+            public function eventTypes(): array
+            {
+                return ['commit'];
+            }
+
+            public function collections(): ?array
+            {
+                return ['app.bsky.feed.*'];
+            }
+
+            public function handle(JetstreamEvent $event): void
+            {
+                //
+            }
+        };
+
+        // Test that it matches app.bsky.feed.post
+        $postEvent = new JetstreamEvent(
+            did: 'did:plc:test',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'test',
+                operation: 'create',
+                collection: 'app.bsky.feed.post',
+                rkey: 'test',
+            ),
+        );
+
+        $this->assertTrue($signal->shouldHandle($postEvent));
+
+        // Test that it matches app.bsky.feed.like
+        $likeEvent = new JetstreamEvent(
+            did: 'did:plc:test',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'test',
+                operation: 'create',
+                collection: 'app.bsky.feed.like',
+                rkey: 'test',
+            ),
+        );
+
+        $this->assertTrue($signal->shouldHandle($likeEvent));
+
+        // Test that it does NOT match app.bsky.graph.follow
+        $followEvent = new JetstreamEvent(
+            did: 'did:plc:test',
+            timeUs: time() * 1000000,
+            kind: 'commit',
+            commit: new CommitEvent(
+                rev: 'test',
+                operation: 'create',
+                collection: 'app.bsky.graph.follow',
+                rkey: 'test',
+            ),
+        );
+
+        $this->assertFalse($signal->shouldHandle($followEvent));
+    }
+}