Merge pull request #13 from invokable/copilot/fix-d08b2e20-2077-49f0-a85e-9c2b9bce22ac

Update .github/copilot-instructions.md with comprehensive accuracy improvements and missing features

Author: kawax

.github/copilot-instructions.md

@@ -5,15 +5,29 @@
 The `revolution/laravel-threads` package is a Laravel library that provides comprehensive integration with Meta's Threads platform. It serves Laravel developers who need to:
 
 - **Authenticate users via Threads OAuth** using Laravel Socialite
-- **Publish content to Threads** (text posts, images, videos, carousels)
-- **Manage Threads content** (delete, repost, search)
+- **Publish content to Threads** (text posts, images, videos, carousels, polls)
+- **Manage Threads content** (delete, repost, search, status checking)
 - **Send notifications through Threads** via Laravel's notification system
 - **Retrieve user profiles and posts** from the Threads API
+- **Monitor publishing quotas** and API limits
 
-The package abstracts the complexity of the Threads API behind familiar Laravel patterns (facades, service providers, notifications), enabling developers to integrate Threads functionality without dealing with raw HTTP requests or OAuth flows. It supports both direct API usage and Laravel's notification system for automated posting.
+The package abstracts the complexity of the Threads API behind familiar Laravel patterns (facades, service providers, notifications), enabling developers to integrate Threads functionality without dealing with raw HTTP requests or OAuth flows. It supports both direct API usage and Laravel's notification system for automated posting, with extensibility through Laravel's macro system.
 
 **Target Users**: Laravel application developers building social media integrations, content management systems, or marketing automation tools that need to interact with Threads.
 
+## Token Management
+
+The package handles two types of Threads API tokens:
+
+- **Short-lived tokens**: Obtained through Socialite OAuth flow, valid for limited time
+- **Long-lived tokens**: Valid for 60-90 days, required for API operations
+
+Key token management features:
+- Automatic conversion from short-lived to long-lived tokens via `exchangeToken()`
+- Token refresh capability via `refreshToken()` for continuous access
+- Support for Threads tester tokens (pre-generated as long-lived)
+- Database storage recommended (tokens cannot be stored in `.env` permanently)
+
 ## Project Organization
 
 ### Core Systems
@@ -23,7 +37,8 @@ The package is organized into four main subsystems:
 1. **Core API Client System** (`src/ThreadsClient.php`, `src/Contracts/Factory.php`)
     - Handles direct HTTP communication with Threads API
     - Implements two-phase content creation (create → publish)
-    - Manages token authentication and refresh
+    - Manages token authentication, refresh, and quota monitoring
+    - Supports extensibility through Laravel's macro system
 
 2. **Laravel Integration Layer** (`src/ThreadsServiceProvider.php`, `src/Facades/Threads.php`, `src/Traits/WithThreads.php`)
     - Registers services with Laravel's container
@@ -37,7 +52,7 @@ The package is organized into four main subsystems:
 
 4. **Notification System** (`src/Notifications/ThreadsChannel.php`, `src/Notifications/ThreadsMessage.php`)
     - Custom Laravel notification channel for Threads
-    - Supports text, image, and video content
+    - Supports text, image, video, and poll content
     - Integrates with Laravel's notification infrastructure
 
 ### Main Files and Directories
@@ -76,30 +91,32 @@ docs/
 ### Main Classes and Functions
 
 **Core API Client:**
-- `ThreadsClient`: Main HTTP client with methods like `createText()`, `createImage()`, `publish()`, `delete()`
+- `ThreadsClient`: Main HTTP client with methods like `createText()`, `createImage()`, `createVideo()`, `createCarousel()`, `publish()`, `delete()`, `repost()`, `search()`, `profiles()`, `posts()`, `single()`, `replies()`, `status()`, `quota()`
 - `Factory`: Interface defining the client contract for dependency injection
 
 **Laravel Integration:**
-- `ThreadsServiceProvider::register()`: Binds Factory to ThreadsClient in service container
-- `ThreadsServiceProvider::boot()`: Extends Socialite with Threads driver
-- `Threads` (Facade): Provides static access like `Threads::createText()`
+- `ThreadsServiceProvider::register()`: Binds Factory to ThreadsClient as scoped service in container
+- `ThreadsServiceProvider::boot()`: Extends Socialite with Threads driver using service configuration
+- `Threads` (Facade): Provides static access like `Threads::createText()` with macro and conditional support
 - `WithThreads::threads()`: Trait method returning configured client instance
 
 **OAuth System:**
-- `ThreadsProvider::redirect()`: Initiates OAuth authorization flow
+- `ThreadsProvider::redirect()`: Initiates OAuth authorization flow with default scopes
 - `ThreadsProvider::user()`: Handles callback and retrieves user data
 - `ThreadsProvider::exchangeToken()`: Converts short-lived to long-lived tokens
+- Default scopes: `['threads_basic', 'threads_content_publish', 'threads_delete', 'threads_keyword_search']`
 
 **Notification System:**
 - `ThreadsChannel::send()`: Processes notifications and dispatches to Threads
 - `ThreadsMessage::create()`: Factory method for message construction
-- `ThreadsMessage::withImage()`, `ThreadsMessage::withVideo()`: Fluent media attachment
+- `ThreadsMessage::withImage()`, `ThreadsMessage::withVideo()`: Fluent media attachment methods
 
 ### CI/CD Pipeline
 
-- **`.github/workflows/test.yml`**: Runs PHPUnit tests across PHP 8.2-8.4, generates coverage
-- **`.github/workflows/lint.yml`**: Enforces code style using Laravel Pint
-- **`phpunit.xml`**: Configures test discovery and coverage reporting
+- **`.github/workflows/test.yml`**: Runs PHPUnit tests across PHP 8.2-8.4, generates coverage with Qlty integration
+- **`.github/workflows/lint.yml`**: Enforces code style using Laravel Pint (PHP 8.4)
+- **`.github/workflows/copilot-setup-steps.yml`**: Automated setup workflow for GitHub Copilot integration
+- **`phpunit.xml`**: Configures test discovery and coverage reporting to `build/logs/clover.xml`
 - **`pint.json`**: Laravel coding standards with disabled unused imports rule
 
 ## Glossary of Codebase-Specific Terms
@@ -124,7 +141,7 @@ docs/
 
 **MediaType** - Enum defining content types: TEXT, IMAGE, VIDEO, CAROUSEL. Located: `src/Enums/MediaType.php`
 
-**ReplyControl** - Enum for reply permissions: EVERYONE, FOLLOW, MENTIONED. Located: `src/Enums/ReplyControl.php`
+**ReplyControl** - Enum for reply permissions: EVERYONE, FOLLOW (accounts_you_follow), MENTIONED (mentioned_only). Located: `src/Enums/ReplyControl.php`
 
 **SearchType** - Enum for search ordering: TOP, RECENT. Located: `src/Enums/SearchType.php`
 
@@ -138,13 +155,29 @@ docs/
 
 **createCarousel** - Method creating multi-media carousel posts. Found in: `ThreadsClient::createCarousel()`
 
+**profiles** - Method retrieving user profile information. Found in: `ThreadsClient::profiles()`
+
+**posts** - Method retrieving user's posts with pagination. Found in: `ThreadsClient::posts()`
+
+**single** - Method retrieving a single post by ID. Found in: `ThreadsClient::single()`
+
+**replies** - Method retrieving replies to posts. Found in: `ThreadsClient::replies()`
+
+**repost** - Method for reposting existing content. Found in: `ThreadsClient::repost()`
+
+**status** - Method checking publishing status of containers. Found in: `ThreadsClient::status()`
+
+**quota** - Method checking API usage limits and quotas. Found in: `ThreadsClient::quota()`
+
+**search** - Method for keyword search across public Threads content. Found in: `ThreadsClient::search()`
+
 **toThreads** - Notification method returning ThreadsMessage instance. Found in: custom notification classes
 
 **routeNotificationForThreads** - Model method providing Threads token for notifications. Found in: Notifiable models
 
 **threads** - Trait method returning configured ThreadsClient instance. Found in: `WithThreads::threads()`
 
-**tokenForThreads** - Abstract method models must implement for token retrieval. Found in: `WithThreads` trait
+**tokenForThreads** - Abstract method models must implement for token retrieval. Found in: `WithThreads` trait (must be implemented by classes using the trait)
 
 **POST_DEFAULT_FIELDS** - Constant array of default API response fields. Found in: `ThreadsClient::POST_DEFAULT_FIELDS`
 
@@ -157,3 +190,7 @@ docs/
 **is_carousel** - Boolean flag marking media for carousel inclusion. Found in: media creation methods
 
 **sleep** - Parameter controlling publish timing/delays. Found in: `publish()` and `ThreadsMessage`
+
+**poll_attachment** - Option for adding polls to text posts. Found in: `createText()` options
+
+**Macroable** - Trait enabling custom method addition to ThreadsClient and ThreadsMessage. Found in: `ThreadsClient` and `ThreadsMessage` classes

.gitignore

@@ -1,3 +1,4 @@
 /vendor
 .phpunit.result.cache
 composer.lock
+build