Update AGENTS.md and add Kakao BMS documentation

- Updated AGENTS.md to reflect the latest SDK generation date and commit hash.
- Enhanced the overview of the SOLAPI PHP SDK to include PSR-18 HTTP client abstraction.
- Revised the structure section to detail the new BMS components and their organization.
- Added a new AGENTS.md file for Kakao BMS, outlining its structure, chat bubble types, validation rules, and usage patterns.

Author: Palbahngmiyine

AGENTS.md

@@ -1,29 +1,33 @@
 # SOLAPI PHP SDK
 
-**Generated:** 2026-01-21  
-**Commit:** b68825d  
+**Generated:** 2026-01-27  
+**Commit:** a27d32f  
 **Branch:** master
 
 ## OVERVIEW
 
-PHP SDK for SOLAPI messaging API (SMS, LMS, MMS, Kakao Alimtalk, Voice, Fax) targeting Korean telecom. Zero external dependencies, PHP 7.1+.
+PHP SDK for SOLAPI messaging API (SMS, LMS, MMS, Kakao Alimtalk/BMS, Voice, Fax) targeting Korean telecom. PSR-18 HTTP client abstraction, PHP 7.1+.
 
 ## STRUCTURE
 
 ```
 solapi-php/
 ├── src/
 │   ├── Services/           # Entry point (SolapiMessageService)
-│   ├── Libraries/          # HTTP client, auth, utilities
+│   ├── Libraries/          # HTTP client, auth, utilities (4 files)
 │   ├── Models/
 │   │   ├── Request/        # API request DTOs (7 files)
 │   │   ├── Response/       # API response DTOs (17 files)
-│   │   ├── Kakao/          # Kakao message options
-│   │   ├── Voice/          # Voice message options
-│   │   └── Fax/            # Fax message options
-│   └── Exceptions/         # Custom exceptions (4 files)
+│   │   ├── Kakao/          # Kakao options (4 files)
+│   │   │   └── Bms/        # Brand Message Service (14 files) ← See Bms/AGENTS.md
+│   │   ├── Voice/          # Voice options (3 files)
+│   │   └── Fax/            # Fax options (1 file)
+│   └── Exceptions/         # Custom exceptions (5 files)
+├── tests/
+│   ├── Models/             # Unit tests
+│   └── E2E/                # Integration tests
 ├── composer.json           # PSR-4: Nurigo\Solapi\ → src/
-└── README.md
+└── phpunit.xml             # Test configuration
 ```
 
 ## WHERE TO LOOK
@@ -32,13 +36,17 @@ solapi-php/
 |------|----------|-------|
 | Send messages | `Services/SolapiMessageService.php` | Main entry point, all public methods |
 | Build message | `Models/Message.php` | Fluent builder, extends BaseMessage |
-| HTTP requests | `Libraries/Fetcher.php` | Singleton, CURL-based |
+| HTTP requests | `Libraries/Fetcher.php` | Singleton, PSR-18 client |
 | Auth header | `Libraries/Authenticator.php` | HMAC-SHA256, static method |
-| Kakao options | `Models/Kakao/KakaoOption.php` | pfId, templateId, buttons, bms |
+| HTTP transport | `Libraries/HttpClient.php` | stream_context-based, PSR-18 compliant |
+| Kakao Alimtalk | `Models/Kakao/KakaoOption.php` | pfId, templateId, buttons, variables |
+| Kakao BMS | `Models/Kakao/KakaoBms.php` | Brand messages, 8 chatBubbleTypes |
+| BMS validation | `Models/Kakao/Bms/BmsValidator.php` | Field requirements by type |
 | Voice options | `Models/Voice/VoiceOption.php` | voiceType, headerMessage, tailMessage |
-| Error handling | `Exceptions/` | BaseException, CurlException, MessageNotReceivedException |
-| Request params | `Models/Request/` | SendRequest, GetMessagesRequest, etc. |
-| Response parsing | `Models/Response/` | SendResponse, GroupMessageResponse, etc. |
+| Fax options | `Models/Fax/FaxOption.php` | fileIds array |
+| Error handling | `Exceptions/` | BaseException, HttpException, BmsValidationException |
+| Request DTOs | `Models/Request/` | SendRequest, GetMessagesRequest, etc. |
+| Response DTOs | `Models/Response/` | SendResponse, GroupMessageResponse, etc. |
 
 ## CODE MAP
 
@@ -50,19 +58,33 @@ $response = $service->send($message);
 
 **Call Flow:**
 ```
-SolapiMessageService → Fetcher (singleton) → Authenticator (static)
-                                          → CURL → api.solapi.com
-                                          → Response DTOs
+SolapiMessageService
+    → Fetcher::getInstance() [singleton]
+        → Authenticator::getAuthorizationHeaderInfo() [static]
+        → NullEliminator::array_null_eliminate() [static]
+        → HttpClient::sendRequest() [PSR-18]
+            → stream_context + file_get_contents
+        → Response DTOs
 ```
 
 **Key Classes:**
 | Class | Type | Role |
 |-------|------|------|
 | `SolapiMessageService` | Service | Primary API (send, uploadFile, getMessages, getGroups, getBalance) |
-| `Message` | Model | Message builder with fluent setters |
-| `Fetcher` | Library | HTTP client singleton, handles all API requests |
-| `Authenticator` | Library | Generates HMAC-SHA256 auth headers |
-| `NullEliminator` | Library | Removes null values before JSON serialization |
+| `Message` | Model | Fluent builder with 12 setters |
+| `Fetcher` | Library | Singleton HTTP client, credential storage |
+| `HttpClient` | Library | PSR-18 stream-based implementation |
+| `Authenticator` | Library | HMAC-SHA256 auth header generation |
+| `NullEliminator` | Library | Recursive null removal for JSON |
+| `BmsValidator` | Validator | BMS field validation by chatBubbleType |
+
+**Model Hierarchy:**
+```
+BaseMessage → Message (fluent builder)
+BaseKakaoOption → KakaoOption (fluent builder)
+                   └── KakaoBms (fluent builder, 8 types)
+                        └── Bms/* components (14 files)
+```
 
 ## CONVENTIONS
 
@@ -71,43 +93,61 @@ SolapiMessageService → Fetcher (singleton) → Authenticator (static)
 **Patterns:**
 - Fluent builder: `$msg->setTo("...")->setFrom("...")->setText("...")`
 - Singleton: `Fetcher::getInstance($key, $secret)`
-- Public properties with getters/setters on models
-- Korean PHPDoc comments (domain-specific)
+- Public properties with getter/setter pairs on models
+- Korean PHPDoc comments (수신번호, 발신번호, 메시지 내용)
 
 **Type Safety:**
 - Full type hints on method params/returns
 - PHPDoc `@var`, `@param`, `@return`, `@throws` annotations
+- PHP 7.1 compatible (no union types, no enums)
+
+**Enum-Like Constants:**
+- `VoiceType::FEMALE`, `VoiceType::MALE`
+- `BmsChatBubbleType::TEXT`, `IMAGE`, `WIDE`, etc.
+- All have `values()` static method
 
 **Tidy First (Kent Beck):**
 - Separate structural and behavioral changes into distinct commits
 - Tidy related code before making feature changes
-- Guard clauses, helper variables/functions, code proximity, symmetry normalization, delete unused code
+- Guard clauses, helper variables/functions, code proximity
 
 ## ANTI-PATTERNS
 
-- **Avoid catch-all nulls:** Many get* methods return `null` on any exception — check response validity
-- **Singleton state:** Fetcher singleton retains credentials — don't mix different API keys in same process
+- **Silent null returns:** get* methods return `null` on any exception — always check response validity
+- **Singleton state:** Fetcher retains credentials — don't mix API keys in same process
 - **No interfaces:** Service/Fetcher have no contracts — mocking requires concrete class extension
-- **SSL verification disabled:** `CURLOPT_SSL_VERIFYPEER = false` in Fetcher
+- **Hardcoded timezone:** `Asia/Seoul` set in Authenticator — affects global timezone
+- **Hardcoded country:** `"82"` default in BaseMessage — Korean-only by default
 
 ## UNIQUE STYLES
 
-- **Korean comments:** PHPDoc descriptions in Korean (수신번호, 발신번호, 메시지 내용)
-- **Default country:** `"82"` (Korea) hardcoded in BaseMessage
-- **Timezone:** `Asia/Seoul` set in Authenticator
+- **Korean comments:** PHPDoc descriptions in Korean
+- **PSR-18 via stream:** Uses `file_get_contents` + `stream_context_create`, not cURL
+- **Null elimination:** Removes nulls before JSON serialization
 
 ## COMMANDS
 
 ```bash
 # Install
 composer require solapi/sdk
 
-# No local tests — see solapi-php-examples repo
+# Run all tests
+composer test
+
+# Run unit tests only
+composer test:unit
+
+# Run E2E tests only
+composer test:e2e
+
+# Run with coverage
+composer test:coverage
 ```
 
 ## NOTES
 
 - **Examples:** External repo at `github.com/solapi/solapi-php-examples`
 - **API docs:** `developers.solapi.com`
-- **PHP requirement:** 7.1+ (ext-curl, ext-json required)
-- **TODO in README:** Missing documentation link (line 19)
+- **PHP requirement:** 7.1+ (ext-json, allow_url_fopen or custom PSR-18 client)
+- **Dependencies:** psr/http-client, psr/http-message, nyholm/psr7
+- **BMS details:** See `src/Models/Kakao/Bms/AGENTS.md` for Brand Message Service specifics

src/Models/Kakao/Bms/AGENTS.md

@@ -0,0 +1,94 @@
+# Kakao BMS (Brand Message Service)
+
+**Parent:** See root `AGENTS.md` for SDK overview.
+
+## OVERVIEW
+
+14-file subsystem for Kakao Brand Message Service. Supports 8 chatBubbleTypes with type-specific required fields and validation.
+
+## STRUCTURE
+
+```
+Bms/
+├── BmsChatBubbleType.php   # 8 type constants + values()
+├── BmsValidator.php        # Validates fields by chatBubbleType
+├── BmsButton.php           # Button with 8 linkTypes
+├── BmsCarousel.php         # head + list[] + tail
+├── BmsCarouselHead.php     # Carousel header
+├── BmsCarouselTail.php     # Carousel footer
+├── BmsCarouselFeedItem.php # Feed carousel item
+├── BmsCarouselCommerceItem.php # Commerce carousel item
+├── BmsCommerce.php         # Product info with pricing
+├── BmsCoupon.php           # Coupon with 5 title formats
+├── BmsVideo.php            # Video (Kakao TV only)
+├── BmsMainWideItem.php     # WIDE_ITEM_LIST main item
+├── BmsSubWideItem.php      # WIDE_ITEM_LIST sub items (min 3)
+└── BmsButtonLinkType.php   # 8 link type constants
+```
+
+## CHAT BUBBLE TYPES
+
+| Type | Required Fields | Notes |
+|------|-----------------|-------|
+| `TEXT` | (none) | Uses Message.text |
+| `IMAGE` | imageId | |
+| `WIDE` | imageId | |
+| `WIDE_ITEM_LIST` | header, mainWideItem, subWideItemList | subWideItemList min 3 items |
+| `COMMERCE` | imageId, commerce, buttons | |
+| `CAROUSEL_FEED` | carousel | Uses BmsCarouselFeedItem[] |
+| `CAROUSEL_COMMERCE` | carousel | Uses BmsCarouselCommerceItem[] |
+| `PREMIUM_VIDEO` | video | videoUrl must start with `https://tv.kakao.com/` |
+
+## VALIDATION RULES
+
+**BmsValidator.php** enforces:
+
+1. **Required fields** by chatBubbleType (see table above)
+2. **WIDE_ITEM_LIST**: `subWideItemList` minimum 3 items
+3. **Commerce pricing** (mutually exclusive):
+   - Cannot use both `discountRate` AND `discountFixed`
+   - If `discountPrice` set, must have `discountRate` OR `discountFixed`
+   - If `discountRate`/`discountFixed` set, must have `discountPrice`
+4. **PREMIUM_VIDEO**: `videoUrl` must start with `https://tv.kakao.com/`
+
+## BUTTON LINK TYPES
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `WL` | Web Link | linkMobile |
+| `AL` | App Link | linkMobile |
+| `AC` | App Channel | (none) |
+| `BK` | Bot Keyword | (none) |
+| `MD` | Message Delivery | (none) |
+| `BC` | Bot Channel | (none) |
+| `BT` | Bot Talk | (none) |
+| `BF` | Business Form | (none) |
+
+## TARGETING TYPES
+
+- `M`: Marketing consent + Kakao channel friend
+- `N`: Marketing consent only
+- `I`: Kakao channel friend only
+
+## USAGE PATTERN
+
+```php
+use Nurigo\Solapi\Models\Kakao\KakaoBms;
+use Nurigo\Solapi\Models\Kakao\Bms\BmsChatBubbleType;
+use Nurigo\Solapi\Models\Kakao\Bms\BmsValidator;
+
+$bms = new KakaoBms();
+$bms->setTargeting('I')
+    ->setChatBubbleType(BmsChatBubbleType::IMAGE)
+    ->setImageId('uploaded-image-id');
+
+// Validate before sending
+BmsValidator::validate($bms);  // Throws BmsValidationException on failure
+```
+
+## ANTI-PATTERNS
+
+- **Missing validation:** Always call `BmsValidator::validate()` before sending
+- **Wrong type combinations:** Each chatBubbleType has specific required fields
+- **Invalid video URL:** PREMIUM_VIDEO only accepts Kakao TV URLs
+- **Insufficient sub items:** WIDE_ITEM_LIST requires exactly 3+ subWideItemList items