SOLAPI Kotlin SDK 1.1.0

.claude/scripts/sync-version.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# 버전 동기화 스크립트
+# build.gradle.kts의 버전이 변경되면 README.md와 LLM_GUIDE.md에 반영
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+GRADLE_FILE="$PROJECT_ROOT/build.gradle.kts"
+README_FILE="$PROJECT_ROOT/README.md"
+LLM_GUIDE_FILE="$PROJECT_ROOT/LLM_GUIDE.md"
+
+# build.gradle.kts가 수정된 경우에만 실행
+if [[ -n "$CLAUDE_FILE_PATHS" ]]; then
+    if ! echo "$CLAUDE_FILE_PATHS" | grep -q "build.gradle.kts"; then
+        exit 0
+    fi
+fi
+
+# build.gradle.kts에서 버전 추출 (예: version = "1.1.0" -> 1.1.0)
+VERSION=$(grep -E '^version\s*=' "$GRADLE_FILE" | head -1 | sed -E 's/.*"([0-9]+\.[0-9]+\.[0-9]+)".*/\1/')
+
+if [[ -z "$VERSION" ]] || [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "유효한 버전을 찾을 수 없습니다: $VERSION"
+    exit 1
+fi
+
+# README.md 버전 업데이트
+if [[ -f "$README_FILE" ]]; then
+    # com.solapi:sdk:X.X.X 패턴 업데이트
+    sed -i '' -E "s/(com\.solapi:sdk:)[0-9]+\.[0-9]+\.[0-9]+/\1$VERSION/g" "$README_FILE"
+    # <version>X.X.X</version> 패턴
+    sed -i '' -E "s|(<version>)[0-9]+\.[0-9]+\.[0-9]+(</version>)|\1$VERSION\2|g" "$README_FILE"
+fi
+
+# LLM_GUIDE.md 버전 업데이트
+if [[ -f "$LLM_GUIDE_FILE" ]]; then
+    sed -i '' -E "s/(com\.solapi:sdk:)[0-9]+\.[0-9]+\.[0-9]+/\1$VERSION/g" "$LLM_GUIDE_FILE"
+    sed -i '' -E "s|(<version>)[0-9]+\.[0-9]+\.[0-9]+(</version>)|\1$VERSION\2|g" "$LLM_GUIDE_FILE"
+fi
+
+echo "버전 $VERSION 동기화 완료"

.env.example

@@ -0,0 +1,10 @@
+# SOLAPI API Credentials
+SOLAPI_API_KEY=
+SOLAPI_API_SECRET=
+
+# Kakao Business Channel
+KAKAO_PF_ID=
+
+# Phone Numbers (Optional)
+SENDER_NUMBER=
+TEST_PHONE_NUMBER=

.gitignore

@@ -34,7 +34,13 @@ signing.gpg
 *.gpg
 *.asc
 secret.key
+.env
+.env.local
 
 # Generated files
 /docs/
-manual/
+manual/
+
+# OMO, OMC
+.sisyphus/
+.omc/

AGENTS.md

@@ -0,0 +1,187 @@
+# SOLAPI Kotlin SDK - Knowledge Base
+
+**Generated:** 2026-01-27 | **Commit:** 618f129 | **Branch:** main
+
+## CRITICAL: Development Principles
+
+**MUST follow `CLAUDE.md` development principles:**
+
+| Principle | Rule |
+|-----------|------|
+| **Tidy First** | NEVER mix structural and behavioral changes in a single commit |
+| **Commit Separation** | `refactor:` (structural) vs `feat:`/`fix:` (behavioral) in separate commits |
+| **TDD** | Write tests first (Red → Green → Refactor) |
+| **Single Responsibility** | Classes/methods have single responsibility only |
+| **Tidy Code First** | Clean up target area code before adding features |
+
+```bash
+# Correct commit order
+git commit -m "refactor: extract validation logic to separate method"
+git commit -m "feat: add phone number format validation"
+
+# Forbidden (mixed commit)
+git commit -m "feat: add validation and refactor code"  # ❌ FORBIDDEN
+```
+
+---
+
+## OVERVIEW
+
+Kotlin/Java SDK for SOLAPI messaging platform. Supports SMS, LMS, MMS, Kakao Alimtalk/Brand Message, Naver Smart Notification, RCS, Fax, and Voice messaging.
+
+## STRUCTURE
+
+```
+src/main/java/com/solapi/sdk/
+├── SolapiClient.kt          # Entry point (use this)
+├── NurigoApp.kt             # DEPRECATED - do not use
+└── message/
+    ├── service/             # API operations (send, query, templates)
+    ├── model/               # Domain models (Message, options)
+    │   └── kakao/           # 19 files - Kakao templates, buttons, options
+    ├── dto/                 # Request/Response DTOs
+    ├── exception/           # Exception hierarchy (8 types)
+    └── lib/                 # Internal utilities (auth, helpers)
+```
+
+## WHERE TO LOOK
+
+| Task | Location | Notes |
+|------|----------|-------|
+| **Initialize SDK** | `SolapiClient.kt` | `createInstance(apiKey, secretKey)` |
+| **Send messages** | `service/DefaultMessageService.kt` | `send(message)` or `send(messages)` |
+| **Query messages** | `service/DefaultMessageService.kt` | `getMessageList(params)` |
+| **Upload files** | `service/DefaultMessageService.kt` | `uploadFile(file, type)` for MMS/Fax |
+| **Kakao Alimtalk** | `service/DefaultMessageService.kt` | 11 template methods |
+| **Create Message** | `model/Message.kt` | Data class with all message options |
+| **Kakao options** | `model/kakao/KakaoOption.kt` | Alimtalk/FriendTalk config |
+| **Handle errors** | `exception/` | Catch specific `Solapi*Exception` types |
+| **HTTP layer** | `service/MessageHttpService.kt` | Retrofit interface (internal) |
+| **Auth** | `lib/Authenticator.kt` | HMAC-SHA256 (internal, auto-injected) |
+
+## CODE PATTERNS
+
+### Serialization
+```kotlin
+@Serializable
+data class Message(
+    var to: String? = null,
+    var from: String? = null,
+    // All fields nullable with defaults for flexibility
+)
+```
+- **ALWAYS** use `@Serializable` annotation
+- **ALWAYS** use `kotlinx.serialization` (not Jackson/Gson)
+- **ALWAYS** provide nullable fields with defaults
+
+### Service Methods
+```kotlin
+@JvmOverloads  // Java interop
+@Throws(SolapiMessageNotReceivedException::class, ...)
+fun send(messages: List<Message>, config: SendRequestConfig? = null): MultipleDetailMessageSentResponse
+```
+- **ALWAYS** annotate with `@JvmOverloads` for optional params
+- **ALWAYS** declare `@Throws` for checked exceptions
+
+### Exception Handling
+```kotlin
+// Internal: Map error codes to exceptions
+when (errorResponse.errorCode) {
+    "ValidationError" -> throw SolapiBadRequestException(msg)
+    "InvalidApiKey" -> throw SolapiInvalidApiKeyException(msg)
+    else -> throw SolapiUnknownException(msg)
+}
+```
+- Exceptions are `sealed interface` based (SolapiException)
+- 8 specific exception types
+
+### Phone Number Normalization
+```kotlin
+init {
+    from = from?.replace("-", "")
+    to = to?.replace("-", "")
+}
+```
+- Dashes auto-stripped from phone numbers in `Message.init`
+
+### Test Conventions
+```kotlin
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+import kotlin.test.assertFailsWith
+
+class AuthenticatorTest {
+    @Test
+    fun `generateAuthInfo returns HMAC-SHA256 format`() {
+        // Given
+        val authenticator = Authenticator("api-key", "secret")
+        // When
+        val result = authenticator.generateAuthInfo()
+        // Then
+        assertTrue(result.startsWith("HMAC-SHA256 "))
+    }
+}
+```
+- **ALWAYS** use `kotlin.test` (NOT JUnit directly)
+- **ALWAYS** use Given-When-Then comment structure
+- **ALWAYS** use backtick method names for readability
+
+## ANTI-PATTERNS
+
+| Forbidden | Required |
+|-----------|----------|
+| `NurigoApp.initialize()` | `SolapiClient.createInstance()` |
+| Direct `DefaultMessageService()` | Use factory via `SolapiClient` |
+| Catch generic `Exception` | Catch specific `Solapi*Exception` |
+| `net.nurigo.sdk` imports | `com.solapi.sdk` package only |
+| Jackson/Gson serialization | `kotlinx.serialization` only |
+| Mixed structural+behavioral commits | Separate commits per Tidy First |
+
+## INTERNAL CLASSES (Do Not Use Directly)
+
+- `Authenticator` - HMAC auth (auto-injected via interceptor)
+- `ErrorResponse` - Internal error DTO
+- `MessageHttpService` - Retrofit interface
+- `JsonSupport` - Serialization config
+- `MapHelper`, `Criterion` - Internal utilities
+
+## EXCEPTION TYPES
+
+| Exception | When Thrown |
+|-----------|-------------|
+| `SolapiApiKeyException` | Empty/missing API key |
+| `SolapiInvalidApiKeyException` | Invalid credentials |
+| `SolapiBadRequestException` | Validation error, bad input |
+| `SolapiEmptyResponseException` | Server returned empty body |
+| `SolapiFileUploadException` | File upload failed |
+| `SolapiMessageNotReceivedException` | All messages failed (has `failedMessageList`) |
+| `SolapiUnknownException` | Unclassified server error |
+
+## KAKAO INTEGRATION
+
+19 model files in `model/kakao/`:
+- `KakaoOption` - Main config (pfId, templateId, variables)
+- `KakaoAlimtalkTemplate*` - Template CRUD models
+- `KakaoBrandMessageTemplate` - Brand message with carousels
+- `KakaoButton`, `KakaoButtonType` - Button configurations
+
+Template workflow: `getKakaoAlimtalkTemplateCategories()` → `createKakaoAlimtalkTemplate()` → `requestKakaoAlimtalkTemplateInspection()`
+
+## BUILD & TEST
+
+```bash
+./gradlew clean build test    # Full build
+./gradlew test                # Tests only
+./gradlew shadowJar           # Fat JAR with relocated deps
+```
+
+**Shadow JAR**: Dependencies relocated to `com.solapi.shadow.*` to prevent conflicts.
+
+## NOTES
+
+- **Java 8 target**: Code must work on JVM 1.8
+- **Source location**: Kotlin in `src/main/java/` (unconventional but intentional)
+- **Tests**: `src/test/kotlin/`, `kotlin.test` (Kotlin native), Given-When-Then style
+- **Version**: Auto-generated at `build/generated/source/kotlin/com/solapi/sdk/Version.kt`
+- **Docs**: Dokka output to `./docs/`, run `./gradlew dokkaGeneratePublicationHtml`